系統(tǒng)“設(shè)計)
目錄1. 如何優(yōu)雅地駕馭長期運行的 AI Agent2. 上下文壓縮讓長期 Agent 永不“失憶“3. 工作區(qū)Workspace文件即真理目錄即架構(gòu)4. 雙層記憶系統(tǒng) 讓 Agent 擁有真正的“長期大腦“5. 文件系統(tǒng)一套代碼三種部署零改動切換6. 沙箱Sandbox讓 Agent 在安全籠子里自由奔跑7. 子 Agent 編排 文件驅(qū)動的多智能體協(xié)作架構(gòu)8. Skill技能讓 Agent 從“會說話“進化為“會做事“9. Plan Mode 讓 Agent 先想清楚再動手10. Channel Agent 通信的“神經(jīng)系統(tǒng)“設(shè)計單 Agent 是孤島多 Agent 才是生態(tài)。但多 Agent 協(xié)作的真正瓶頸從來不是能力不夠而是溝通不暢。Channel 就是 AgentScope Harness 為多智能體系統(tǒng)設(shè)計的標準化通信基礎(chǔ)設(shè)施——它不是消息隊列的簡單封裝而是一套面向 Agent 認知模型的交互協(xié)議。一、引言為什么多 Agent 通信這么難當你從單 Agent 邁向多 Agent 系統(tǒng)時會迅速撞上一堵墻Agent 之間的通信和人類/服務(wù)之間的通信有本質(zhì)區(qū)別。維度傳統(tǒng)服務(wù)通信Agent 間通信消息格式結(jié)構(gòu)化 APIJSON/gRPC自然語言 結(jié)構(gòu)化混合語義理解無需理解內(nèi)容接收方必須讀懂消息意圖路由邏輯確定性URL/RPC推理性LLM 判斷發(fā)給誰狀態(tài)依賴無狀態(tài)或顯式狀態(tài)隱式共享上下文錯誤處理重試/熔斷澄清/重述/換一種說法拓撲結(jié)構(gòu)固定動態(tài)運行時決定誰參與用 HTTP/gRPC 的思維做 Agent 通信就像用電話交換機的方式組織一場頭腦風暴——技術(shù)上可行認知上錯位。AgentScope Java 2.0 的 Harness Channel正是為解決這個錯位而生它提供了一套面向 Agent 認知模型的標準化通信抽象讓多 Agent 協(xié)作從硬編碼消息傳遞進化為聲明式交互編排。二、核心概念Channel 是什么2.1 定義Channel 是 Agent 之間結(jié)構(gòu)化消息交換的抽象通道。它封裝了誰可以發(fā)消息參與者管理消息長什么樣消息協(xié)議消息怎么送達路由策略消息如何被理解語義綁定歷史如何追溯消息持久化2.2 Channel ≠ Message Queue這是最常見的誤解。Channel 不是 Kafka/RabbitMQ 的 Agent 版包裝維度Message QueueHarness Channel核心關(guān)注可靠投遞、吞吐量語義理解、認知對齊消費者模型訂閱/競爭消費LLM 推理決定是否響應(yīng)消息生命周期投遞即完成投遞 → 理解 → 響應(yīng) → 確認拓撲感知無感知 Agent 角色和能力上下文傳遞手動自動攜帶會話/任務(wù)上下文**關(guān)鍵洞察**Channel 的設(shè)計目標是讓 Agent “像人一樣溝通”而不是像服務(wù)一樣調(diào)用。三、架構(gòu)定位Channel 在 Harness 中的位置┌─────────────────────────────────────────────────────────────┐ │ Harness 多 Agent 架構(gòu) │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Agent A │ │ Agent B │ │ Agent C │ │ │ │(Harness) │ │(Harness) │ │(Harness) │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Channel Layer │ │ │ │ │ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │ │ │ │ │ Direct │ │ Broadcast │ │ Routed │ │ │ │ │ │ Channel │ │ Channel │ │ Channel │ │ │ │ │ │ (點對點) │ │ (廣播) │ │ (語義路由) │ │ │ │ │ └────────────┘ └────────────┘ └────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ │ │ Message Protocol Serialization │ │ │ │ │ └──────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ StateStore / Session Persistence │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘Channel 位于 Agent 實例與底層存儲之間是多 Agent 交互的唯一入口。所有 Agent 間的消息交換都通過 Channel 進行禁止繞過 Channel 直接調(diào)用其他 Agent。四、三種 Channel 類型4.1 Direct Channel點對點通道**語義**Agent A 明確知道要發(fā)給 Agent B一對一通信。DirectChannelchannelDirectChannel.builder().name(analyst-to-writer).participants(List.of(data-analyst,report-writer)).build();適用場景串行流水線中的上下游傳遞明確的請求-響應(yīng)模式兩個 Agent 之間的私有協(xié)商消息流data-analyst ──分析結(jié)果──? report-writer ?──澄清請求── ──補充數(shù)據(jù)──?4.2 Broadcast Channel廣播通道**語義**一條消息發(fā)送給所有參與者每個 Agent 自行決定是否響應(yīng)。BroadcastChannelchannelBroadcastChannel.builder().name(team-updates).participants(List.of(pm,developer,tester,designer)).build();適用場景狀態(tài)通知“部署完成”、“需求變更”征求意見“大家對方案有什么看法”事件驅(qū)動的多 Agent 協(xié)同**關(guān)鍵特性**廣播不是所有人都必須回復。每個 Agent 通過 LLM 推理判斷消息是否與自身職責相關(guān)無關(guān)則靜默忽略。4.3 Routed Channel語義路由通道**語義**發(fā)送方不知道接收方是誰由 Channel 根據(jù)消息內(nèi)容和 Agent 能力描述自動路由。RoutedChannelchannelRoutedChannel.builder().name(task-dispatch).participants(List.of(code-reviewer,data-analyst,doc-writer)).routingStrategy(RoutingStrategy.SEMANTIC).build();路由策略策略機制適用場景SEMANTICLLM 根據(jù)消息內(nèi)容 Agent description 匹配通用任務(wù)分發(fā)KEYWORD關(guān)鍵詞匹配 Agent tags簡單分類ROUND_ROBIN輪詢負載均衡同類 AgentCUSTOM自定義路由函數(shù)特殊業(yè)務(wù)邏輯適用場景主 Agent 不確定該委派給誰動態(tài)加入/退出的 Agent 池基于內(nèi)容的智能分發(fā)4.4 選型決策樹你知道消息應(yīng)該發(fā)給誰嗎 ├── YES → 只有一個接收方 │ ├── YES → Direct Channel │ └── NO → 所有人都需要看到 │ ├── YES → Broadcast Channel │ └── NO → 部分人需要看到 → 多個 Direct / 分組 Broadcast │ └── NO → Routed Channel ├── 消息內(nèi)容有明確語義 → SEMANTIC ├── 消息有標簽/關(guān)鍵詞 → KEYWORD └── 同類 Agent 負載均衡 → ROUND_ROBIN五、消息協(xié)議AgentMessage5.1 消息結(jié)構(gòu)Channel 中傳輸?shù)牟皇窃甲址墙Y(jié)構(gòu)化的 AgentMessage{id:msg-a1b2c3d4,channel:task-dispatch,sender:coordinator,timestamp:2026-08-11T17:30:0008:00,type:TASK_ASSIGNMENT,content:{text:請分析這份Q3銷售數(shù)據(jù)找出環(huán)比下降超過10%的品類,attachments:[{type:file_ref,path:/workspace/data/q3-sales.csv}]},metadata:{priority:high,deadline:2026-08-12T12:00:0008:00,parent_task_id:task-x9y8z7,session_id:sess-001},reply_to:null}5.2 消息類型枚舉類型語義典型使用場景TEXT純文本消息日常溝通、澄清TASK_ASSIGNMENT任務(wù)分配主 Agent → 子 AgentTASK_RESULT任務(wù)結(jié)果返回子 Agent → 主 AgentSTATUS_UPDATE狀態(tài)更新進度匯報CLARIFICATION_REQUEST澄清請求信息不足時追問EVENT事件通知外部觸發(fā)、系統(tǒng)事件SYSTEM系統(tǒng)消息加入/離開/超時等5.3 為什么需要結(jié)構(gòu)化消息自由文本AgentMessage接收方需從頭解析意圖type 字段直接表明意圖元數(shù)據(jù)混在正文中metadata 獨立承載無法程序化處理框架可攔截、過濾、路由無法持久化和檢索可序列化到 StateStore附件無法引用attachments 支持文件引用六、Channel 與工作區(qū)的深度集成6.1 消息持久化所有 Channel 消息自動持久化到工作區(qū)workspace/agents/agentId/channels/ ├── task-dispatch/ │ ├── messages.jsonl ← 消息流追加寫入 │ └── state.json ← 通道狀態(tài)未讀計數(shù)等 └── team-updates/ ├── messages.jsonl └── state.json6.2 上下文自動注入當 Agent 收到消息時WorkspaceContextHook 自動將相關(guān) Channel 歷史注入 system reminder## Recent Messages in [task-dispatch] [17:30] coordinator → TASK_ASSIGNMENT: 請分析Q3銷售數(shù)據(jù)... [17:32]>6.3 文件引用解析當消息包含 file_ref 附件時框架自動解析為沙箱內(nèi)可訪問的路徑// 發(fā)送方AgentMessagemsgAgentMessage.builder().type(AgentMessageType.TASK_ASSIGNMENT).content(Content.builder().text(請分析這份數(shù)據(jù)).attachment(FileRef.of(/workspace/data/q3-sales.csv)).build()).build();// 接收方在沙箱內(nèi)可直接讀取 /workspace/data/q3-sales.csv// 框架自動處理宿主→沙箱的文件同步七、高級特性7.1 消息攔截器InterceptorChannel 支持注冊消息攔截器在消息發(fā)送/接收前后執(zhí)行自定義邏輯channel.addInterceptor(newMessageInterceptor(){OverridepublicAgentMessagebeforeSend(AgentMessagemsg){// 敏感信息脫敏if(msg.getContent().getText().contains(password)){returnmsg.redact(password,***);}returnmsg;}OverridepublicvoidafterReceive(AgentMessagemsg,StringagentId){// 審計日志auditLog.record(agentId,msg);}});內(nèi)置攔截器攔截器功能RateLimitInterceptor消息頻率限制ContentFilterInterceptor內(nèi)容安全過濾AuditLogInterceptor審計日志記錄MetricsInterceptor消息指標采集7.2 消息確認機制對于關(guān)鍵消息Channel 支持應(yīng)用層確認// 發(fā)送方要求確認AgentMessagemsgAgentMessage.builder().type(AgentMessageType.TASK_ASSIGNMENT).metadata(Map.of(require_ack,true)).build();// 接收方處理后發(fā)送確認channel.send(AgentMessage.ack(originalMsg));注意這不是 MQ 的 ACK而是語義級確認——表示我已理解并接受了這個任務(wù)而非我收到了字節(jié)。7.3 動態(tài)參與者管理Channel 的參與者列表可以在運行時動態(tài)調(diào)整// 新 Agent 加入團隊channel.addParticipant(new-analyst);// Agent 臨時離線channel.suspendParticipant(data-analyst);// Agent 恢復channel.resumeParticipant(data-analyst);RoutedChannel會自動將新參與者納入路由候選池。7.4 跨會話消息延續(xù)Channel 消息與會話Session解耦。Agent 在新會話中可以查看歷史 Channel 消息// 新會話啟動時框架自動加載未讀的 Channel 消息// Agent 可以回憶上次會話中的溝通內(nèi)容八、完整實戰(zhàn)多 Agent 研究團隊8.1 場景設(shè)定構(gòu)建一個由 4 個 Agent 組成的研究團隊Coordinator任務(wù)分解與分發(fā)Web Researcher網(wǎng)絡(luò)信息搜集Data Analyst數(shù)據(jù)分析Report Writer報告撰寫8.2 Channel 拓撲┌─────────────────┐ │ task-dispatch │ (Routed, SEMANTIC) │ Coordinator ? * │ └────────┬────────┘ │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌────────────┐ │Web Researcher│ │Data Analyst│ │Report Writer│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │ │ │ └───────────────┼───────────────┘ ▼ ┌─────────────────┐ │ team-updates │ (Broadcast) │ 所有人可見 │ └─────────────────┘8.3 代碼配置// 1. 創(chuàng)建 ChannelRoutedChanneltaskDispatchRoutedChannel.builder().name(task-dispatch).participants(List.of(web-researcher,data-analyst,report-writer)).routingStrategy(RoutingStrategy.SEMANTIC).build();BroadcastChannelteamUpdatesBroadcastChannel.builder().name(team-updates).participants(List.of(coordinator,web-researcher,data-analyst,report-writer)).build();// 2. 創(chuàng)建 Agent 并綁定 ChannelHarnessAgentcoordinatorHarnessAgent.builder().name(coordinator).model(strongModel).workspace(Path.of(./workspace/coordinator)).channels(List.of(taskDispatch,teamUpdates)).planMode(PlanModeConfig.enabled(true)).build();HarnessAgentwebResearcherHarnessAgent.builder().name(web-researcher).model(fastModel).workspace(Path.of(./workspace/web-researcher)).channels(List.of(taskDispatch,teamUpdates)).build();// ... 其他 Agent 類似8.4 交互流程用戶 → Coordinator: 調(diào)研國內(nèi)Agent框架的市場格局 Coordinator (Plan Mode): Step 1: 分解任務(wù) Step 2: 通過 task-dispatch 分發(fā) → [task-dispatch] TASK_ASSIGNMENT → web-researcher 搜集國內(nèi)主流Agent框架的產(chǎn)品定位、融資情況、用戶規(guī)模 → [task-dispatch] TASK_ASSIGNMENT →>九、與其他子系統(tǒng)的協(xié)作┌─────────────────────────────────────────────────────────────┐ │ Channel 生態(tài)協(xié)作 │ │ │ │ ┌──────────────┐ │ │ │ Channel │ ← 消息交換抽象 │ │ └──────┬───────┘ │ │ │ │ │ ┌────┴────┬──────────┬──────────┬──────────┐ │ │ ▼ ▼ ▼ ▼ ▼ │ │ ┌──────┐ ┌──────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │Sub- │ │Plan │ │Memory │ │Sandbox │ │Session │ │ │ │Agents│ │Mode │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │委派 │ │Step │ │溝通 │ │文件 │ │消息 │ │ │ │通過 │ │結(jié)果 │ │摘要 │ │引用 │ │持久化 │ │ │ │Chann.│ │通過 │ │寫入 │ │自動 │ │到 │ │ │ │ │ │Chann.│ │MEMORY │ │同步 │ │StateSt.│ │ │ └──────┘ └──────┘ └────────┘ └────────┘ └────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ WorkspaceContextHook │ │ │ │ 每輪推理前注入 Channel 歷史到 system reminder │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘子系統(tǒng)與 Channel 的關(guān)系Sub-Agents子 Agent 委派通過 Channel 進行而非直接方法調(diào)用Plan ModePlan step 的執(zhí)行結(jié)果可通過 Channel 傳遞給其他 AgentMemory重要溝通摘要寫入 MEMORY.md供后續(xù)會話參考Sandbox消息中的文件引用自動同步到接收方沙箱SessionChannel 消息持久化到 StateStore跨會話可追溯Skills技能 Workflow 中可包含 Channel 通信步驟CompressionChannel 歷史作為壓縮時的保留錨點十、最佳實踐10.1 Channel 設(shè)計原則原則說明最小權(quán)限Agent 只加入必要的 Channel不加入無關(guān)通道語義明確每個 Channel 有清晰的用途定義避免萬能通道消息類型規(guī)范使用標準 AgentMessageType不自造類型元數(shù)據(jù)豐富充分利用 metadata 傳遞上下文減少正文冗余歷史可追溯所有 Channel 消息持久化支持事后審計優(yōu)雅降級Channel 不可用時 Agent 應(yīng)能降級為單機模式10.2 常見反模式// ? 一個 Broadcast Channel 承載所有通信// 消息噪音大Agent 注意力分散// ? 用 TEXT 類型傳遞任務(wù).type(AgentMessageType.TEXT).content(幫我分析一下數(shù)據(jù))// 應(yīng)使用 TASK_ASSIGNMENT便于框架處理和追蹤// ? 在消息正文中嵌入大段數(shù)據(jù).content(以下是1000行CSV數(shù)據(jù)...)// 應(yīng)使用 file_ref 附件// ? 繞過 Channel 直接調(diào)用其他 AgentotherAgent.call(message);// 禁止// 所有交互必須通過 Channel// ? 不設(shè)消息攔截器// 生產(chǎn)環(huán)境至少應(yīng)有審計日志和內(nèi)容過濾10.3 調(diào)試與觀測工具用途Channel 消息日志查看完整消息流MetricsInterceptor消息延遲、吞吐量監(jiān)控StateStore 查詢檢查消息持久化狀態(tài)System Reminder 注入預(yù)覽驗證 Agent 看到的 Channel 上下文十一、設(shè)計哲學總結(jié)1. 通信是認知行為不是傳輸行為Channel 的設(shè)計前提是Agent 收發(fā)消息是認知過程理解、判斷、決策不是傳輸過程投遞、確認、重試。這決定了 Channel 的每一個設(shè)計選擇都圍繞語義而非可靠性展開。2. 結(jié)構(gòu)化是語義理解的基礎(chǔ)自由文本的消息只有 LLM 能讀結(jié)構(gòu)化的 AgentMessage 框架也能讀。這使得路由、過濾、持久化、注入等基礎(chǔ)設(shè)施操作成為可能而不必每次都經(jīng)過 LLM。3. Channel 是契約不是管道Channel 定義了參與者之間的交互契約誰能發(fā)、什么類型、什么格式而不僅僅是消息的傳輸管道。這種契約意識是多 Agent 系統(tǒng)可治理的前提。4. 歷史是上下文不是日志Channel 消息歷史不是用完即棄的日志而是 Agent 的共享工作記憶。它通過 WorkspaceContextHook 注入每輪推理成為 Agent 認知的一部分。5. 通信拓撲應(yīng)該反映認知拓撲Direct/Broadcast/Routed 三種 Channel 類型對應(yīng)三種人類協(xié)作模式一對一協(xié)商、全員同步、按需分發(fā)。技術(shù)拓撲與認知拓撲的對齊是多 Agent 系統(tǒng)自然感的來源。十二、結(jié)語AgentScope Harness 的 Channel 系統(tǒng)回答了一個根本性的架構(gòu)問題如何讓多個 Agent 像團隊一樣溝通而不是像微服務(wù)一樣調(diào)用答案是設(shè)計一套面向 Agent 認知模型的通信抽象讓消息的結(jié)構(gòu)、路由、歷史和語義都服務(wù)于理解而非傳輸。當你把 Agent 通信從消息傳遞重新定義為認知協(xié)調(diào)時很多設(shè)計決策就變得自然而然了消息需要結(jié)構(gòu)化 → 因為框架要參與理解路由可以是語義的 → 因為誰該收到本身就是一個推理問題歷史要注入上下文 → 因為溝通是連續(xù)的認知過程確認是語義級的 → 因為收到不等于理解并接受如果你正在構(gòu)建多 Agent 系統(tǒng)這套認知導向的通信設(shè)計思路值得深入研究和借鑒。它讓多 Agent 協(xié)作從技術(shù)拼接走向了認知融合——這不僅是架構(gòu)的升級更是讓 AI 系統(tǒng)真正具備團隊協(xié)作智能的關(guān)鍵一步。 AgentScope Java Harness：10. Channel Agent 通信的“神經(jīng)系統(tǒng)“設(shè)計
目錄1. 如何優(yōu)雅地駕馭長期運行的 AI Agent2. 上下文壓縮讓長期 Agent 永不“失憶“3. 工作區(qū)Workspace文件即真理目錄即架構(gòu)4. 雙層記憶系統(tǒng) 讓 Agent 擁有真正的“長期大腦“5. 文件系統(tǒng)一套代碼三種部署零改動切換6. 沙箱Sandbox讓 Agent 在安全籠子里自由奔跑7. 子 Agent 編排 文件驅(qū)動的多智能體協(xié)作架構(gòu)8. Skill技能讓 Agent 從“會說話“進化為“會做事“9. Plan Mode 讓 Agent 先想清楚再動手10. Channel Agent 通信的“神經(jīng)系統(tǒng)“設(shè)計單 Agent 是孤島多 Agent 才是生態(tài)。但多 Agent 協(xié)作的真正瓶頸從來不是能力不夠而是溝通不暢。Channel 就是 AgentScope Harness 為多智能體系統(tǒng)設(shè)計的標準化通信基礎(chǔ)設(shè)施——它不是消息隊列的簡單封裝而是一套面向 Agent 認知模型的交互協(xié)議。一、引言為什么多 Agent 通信這么難當你從單 Agent 邁向多 Agent 系統(tǒng)時會迅速撞上一堵墻Agent 之間的通信和人類/服務(wù)之間的通信有本質(zhì)區(qū)別。維度傳統(tǒng)服務(wù)通信Agent 間通信消息格式結(jié)構(gòu)化 APIJSON/gRPC自然語言 結(jié)構(gòu)化混合語義理解無需理解內(nèi)容接收方必須讀懂消息意圖路由邏輯確定性URL/RPC推理性LLM 判斷發(fā)給誰狀態(tài)依賴無狀態(tài)或顯式狀態(tài)隱式共享上下文錯誤處理重試/熔斷澄清/重述/換一種說法拓撲結(jié)構(gòu)固定動態(tài)運行時決定誰參與用 HTTP/gRPC 的思維做 Agent 通信就像用電話交換機的方式組織一場頭腦風暴——技術(shù)上可行認知上錯位。AgentScope Java 2.0 的 Harness Channel正是為解決這個錯位而生它提供了一套面向 Agent 認知模型的標準化通信抽象讓多 Agent 協(xié)作從硬編碼消息傳遞進化為聲明式交互編排。二、核心概念Channel 是什么2.1 定義Channel 是 Agent 之間結(jié)構(gòu)化消息交換的抽象通道。它封裝了誰可以發(fā)消息參與者管理消息長什么樣消息協(xié)議消息怎么送達路由策略消息如何被理解語義綁定歷史如何追溯消息持久化2.2 Channel ≠ Message Queue這是最常見的誤解。Channel 不是 Kafka/RabbitMQ 的 Agent 版包裝維度Message QueueHarness Channel核心關(guān)注可靠投遞、吞吐量語義理解、認知對齊消費者模型訂閱/競爭消費LLM 推理決定是否響應(yīng)消息生命周期投遞即完成投遞 → 理解 → 響應(yīng) → 確認拓撲感知無感知 Agent 角色和能力上下文傳遞手動自動攜帶會話/任務(wù)上下文**關(guān)鍵洞察**Channel 的設(shè)計目標是讓 Agent “像人一樣溝通”而不是像服務(wù)一樣調(diào)用。三、架構(gòu)定位Channel 在 Harness 中的位置┌─────────────────────────────────────────────────────────────┐ │ Harness 多 Agent 架構(gòu) │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Agent A │ │ Agent B │ │ Agent C │ │ │ │(Harness) │ │(Harness) │ │(Harness) │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Channel Layer │ │ │ │ │ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │ │ │ │ │ Direct │ │ Broadcast │ │ Routed │ │ │ │ │ │ Channel │ │ Channel │ │ Channel │ │ │ │ │ │ (點對點) │ │ (廣播) │ │ (語義路由) │ │ │ │ │ └────────────┘ └────────────┘ └────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ │ │ Message Protocol Serialization │ │ │ │ │ └──────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ StateStore / Session Persistence │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘Channel 位于 Agent 實例與底層存儲之間是多 Agent 交互的唯一入口。所有 Agent 間的消息交換都通過 Channel 進行禁止繞過 Channel 直接調(diào)用其他 Agent。四、三種 Channel 類型4.1 Direct Channel點對點通道**語義**Agent A 明確知道要發(fā)給 Agent B一對一通信。DirectChannelchannelDirectChannel.builder().name(analyst-to-writer).participants(List.of(data-analyst,report-writer)).build();適用場景串行流水線中的上下游傳遞明確的請求-響應(yīng)模式兩個 Agent 之間的私有協(xié)商消息流data-analyst ──分析結(jié)果──? report-writer ?──澄清請求── ──補充數(shù)據(jù)──?4.2 Broadcast Channel廣播通道**語義**一條消息發(fā)送給所有參與者每個 Agent 自行決定是否響應(yīng)。BroadcastChannelchannelBroadcastChannel.builder().name(team-updates).participants(List.of(pm,developer,tester,designer)).build();適用場景狀態(tài)通知“部署完成”、“需求變更”征求意見“大家對方案有什么看法”事件驅(qū)動的多 Agent 協(xié)同**關(guān)鍵特性**廣播不是所有人都必須回復。每個 Agent 通過 LLM 推理判斷消息是否與自身職責相關(guān)無關(guān)則靜默忽略。4.3 Routed Channel語義路由通道**語義**發(fā)送方不知道接收方是誰由 Channel 根據(jù)消息內(nèi)容和 Agent 能力描述自動路由。RoutedChannelchannelRoutedChannel.builder().name(task-dispatch).participants(List.of(code-reviewer,data-analyst,doc-writer)).routingStrategy(RoutingStrategy.SEMANTIC).build();路由策略策略機制適用場景SEMANTICLLM 根據(jù)消息內(nèi)容 Agent description 匹配通用任務(wù)分發(fā)KEYWORD關(guān)鍵詞匹配 Agent tags簡單分類ROUND_ROBIN輪詢負載均衡同類 AgentCUSTOM自定義路由函數(shù)特殊業(yè)務(wù)邏輯適用場景主 Agent 不確定該委派給誰動態(tài)加入/退出的 Agent 池基于內(nèi)容的智能分發(fā)4.4 選型決策樹你知道消息應(yīng)該發(fā)給誰嗎 ├── YES → 只有一個接收方 │ ├── YES → Direct Channel │ └── NO → 所有人都需要看到 │ ├── YES → Broadcast Channel │ └── NO → 部分人需要看到 → 多個 Direct / 分組 Broadcast │ └── NO → Routed Channel ├── 消息內(nèi)容有明確語義 → SEMANTIC ├── 消息有標簽/關(guān)鍵詞 → KEYWORD └── 同類 Agent 負載均衡 → ROUND_ROBIN五、消息協(xié)議AgentMessage5.1 消息結(jié)構(gòu)Channel 中傳輸?shù)牟皇窃甲址墙Y(jié)構(gòu)化的 AgentMessage{id:msg-a1b2c3d4,channel:task-dispatch,sender:coordinator,timestamp:2026-08-11T17:30:0008:00,type:TASK_ASSIGNMENT,content:{text:請分析這份Q3銷售數(shù)據(jù)找出環(huán)比下降超過10%的品類,attachments:[{type:file_ref,path:/workspace/data/q3-sales.csv}]},metadata:{priority:high,deadline:2026-08-12T12:00:0008:00,parent_task_id:task-x9y8z7,session_id:sess-001},reply_to:null}5.2 消息類型枚舉類型語義典型使用場景TEXT純文本消息日常溝通、澄清TASK_ASSIGNMENT任務(wù)分配主 Agent → 子 AgentTASK_RESULT任務(wù)結(jié)果返回子 Agent → 主 AgentSTATUS_UPDATE狀態(tài)更新進度匯報CLARIFICATION_REQUEST澄清請求信息不足時追問EVENT事件通知外部觸發(fā)、系統(tǒng)事件SYSTEM系統(tǒng)消息加入/離開/超時等5.3 為什么需要結(jié)構(gòu)化消息自由文本AgentMessage接收方需從頭解析意圖type 字段直接表明意圖元數(shù)據(jù)混在正文中metadata 獨立承載無法程序化處理框架可攔截、過濾、路由無法持久化和檢索可序列化到 StateStore附件無法引用attachments 支持文件引用六、Channel 與工作區(qū)的深度集成6.1 消息持久化所有 Channel 消息自動持久化到工作區(qū)workspace/agents/agentId/channels/ ├── task-dispatch/ │ ├── messages.jsonl ← 消息流追加寫入 │ └── state.json ← 通道狀態(tài)未讀計數(shù)等 └── team-updates/ ├── messages.jsonl └── state.json6.2 上下文自動注入當 Agent 收到消息時WorkspaceContextHook 自動將相關(guān) Channel 歷史注入 system reminder## Recent Messages in [task-dispatch] [17:30] coordinator → TASK_ASSIGNMENT: 請分析Q3銷售數(shù)據(jù)... [17:32]>6.3 文件引用解析當消息包含 file_ref 附件時框架自動解析為沙箱內(nèi)可訪問的路徑// 發(fā)送方AgentMessagemsgAgentMessage.builder().type(AgentMessageType.TASK_ASSIGNMENT).content(Content.builder().text(請分析這份數(shù)據(jù)).attachment(FileRef.of(/workspace/data/q3-sales.csv)).build()).build();// 接收方在沙箱內(nèi)可直接讀取 /workspace/data/q3-sales.csv// 框架自動處理宿主→沙箱的文件同步七、高級特性7.1 消息攔截器InterceptorChannel 支持注冊消息攔截器在消息發(fā)送/接收前后執(zhí)行自定義邏輯channel.addInterceptor(newMessageInterceptor(){OverridepublicAgentMessagebeforeSend(AgentMessagemsg){// 敏感信息脫敏if(msg.getContent().getText().contains(password)){returnmsg.redact(password,***);}returnmsg;}OverridepublicvoidafterReceive(AgentMessagemsg,StringagentId){// 審計日志auditLog.record(agentId,msg);}});內(nèi)置攔截器攔截器功能RateLimitInterceptor消息頻率限制ContentFilterInterceptor內(nèi)容安全過濾AuditLogInterceptor審計日志記錄MetricsInterceptor消息指標采集7.2 消息確認機制對于關(guān)鍵消息Channel 支持應(yīng)用層確認// 發(fā)送方要求確認AgentMessagemsgAgentMessage.builder().type(AgentMessageType.TASK_ASSIGNMENT).metadata(Map.of(require_ack,true)).build();// 接收方處理后發(fā)送確認channel.send(AgentMessage.ack(originalMsg));注意這不是 MQ 的 ACK而是語義級確認——表示我已理解并接受了這個任務(wù)而非我收到了字節(jié)。7.3 動態(tài)參與者管理Channel 的參與者列表可以在運行時動態(tài)調(diào)整// 新 Agent 加入團隊channel.addParticipant(new-analyst);// Agent 臨時離線channel.suspendParticipant(data-analyst);// Agent 恢復channel.resumeParticipant(data-analyst);RoutedChannel會自動將新參與者納入路由候選池。7.4 跨會話消息延續(xù)Channel 消息與會話Session解耦。Agent 在新會話中可以查看歷史 Channel 消息// 新會話啟動時框架自動加載未讀的 Channel 消息// Agent 可以回憶上次會話中的溝通內(nèi)容八、完整實戰(zhàn)多 Agent 研究團隊8.1 場景設(shè)定構(gòu)建一個由 4 個 Agent 組成的研究團隊Coordinator任務(wù)分解與分發(fā)Web Researcher網(wǎng)絡(luò)信息搜集Data Analyst數(shù)據(jù)分析Report Writer報告撰寫8.2 Channel 拓撲┌─────────────────┐ │ task-dispatch │ (Routed, SEMANTIC) │ Coordinator ? * │ └────────┬────────┘ │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌────────────┐ │Web Researcher│ │Data Analyst│ │Report Writer│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │ │ │ └───────────────┼───────────────┘ ▼ ┌─────────────────┐ │ team-updates │ (Broadcast) │ 所有人可見 │ └─────────────────┘8.3 代碼配置// 1. 創(chuàng)建 ChannelRoutedChanneltaskDispatchRoutedChannel.builder().name(task-dispatch).participants(List.of(web-researcher,data-analyst,report-writer)).routingStrategy(RoutingStrategy.SEMANTIC).build();BroadcastChannelteamUpdatesBroadcastChannel.builder().name(team-updates).participants(List.of(coordinator,web-researcher,data-analyst,report-writer)).build();// 2. 創(chuàng)建 Agent 并綁定 ChannelHarnessAgentcoordinatorHarnessAgent.builder().name(coordinator).model(strongModel).workspace(Path.of(./workspace/coordinator)).channels(List.of(taskDispatch,teamUpdates)).planMode(PlanModeConfig.enabled(true)).build();HarnessAgentwebResearcherHarnessAgent.builder().name(web-researcher).model(fastModel).workspace(Path.of(./workspace/web-researcher)).channels(List.of(taskDispatch,teamUpdates)).build();// ... 其他 Agent 類似8.4 交互流程用戶 → Coordinator: 調(diào)研國內(nèi)Agent框架的市場格局 Coordinator (Plan Mode): Step 1: 分解任務(wù) Step 2: 通過 task-dispatch 分發(fā) → [task-dispatch] TASK_ASSIGNMENT → web-researcher 搜集國內(nèi)主流Agent框架的產(chǎn)品定位、融資情況、用戶規(guī)模 → [task-dispatch] TASK_ASSIGNMENT →>九、與其他子系統(tǒng)的協(xié)作┌─────────────────────────────────────────────────────────────┐ │ Channel 生態(tài)協(xié)作 │ │ │ │ ┌──────────────┐ │ │ │ Channel │ ← 消息交換抽象 │ │ └──────┬───────┘ │ │ │ │ │ ┌────┴────┬──────────┬──────────┬──────────┐ │ │ ▼ ▼ ▼ ▼ ▼ │ │ ┌──────┐ ┌──────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │Sub- │ │Plan │ │Memory │ │Sandbox │ │Session │ │ │ │Agents│ │Mode │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │委派 │ │Step │ │溝通 │ │文件 │ │消息 │ │ │ │通過 │ │結(jié)果 │ │摘要 │ │引用 │ │持久化 │ │ │ │Chann.│ │通過 │ │寫入 │ │自動 │ │到 │ │ │ │ │ │Chann.│ │MEMORY │ │同步 │ │StateSt.│ │ │ └──────┘ └──────┘ └────────┘ └────────┘ └────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ WorkspaceContextHook │ │ │ │ 每輪推理前注入 Channel 歷史到 system reminder │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘子系統(tǒng)與 Channel 的關(guān)系Sub-Agents子 Agent 委派通過 Channel 進行而非直接方法調(diào)用Plan ModePlan step 的執(zhí)行結(jié)果可通過 Channel 傳遞給其他 AgentMemory重要溝通摘要寫入 MEMORY.md供后續(xù)會話參考Sandbox消息中的文件引用自動同步到接收方沙箱SessionChannel 消息持久化到 StateStore跨會話可追溯Skills技能 Workflow 中可包含 Channel 通信步驟CompressionChannel 歷史作為壓縮時的保留錨點十、最佳實踐10.1 Channel 設(shè)計原則原則說明最小權(quán)限Agent 只加入必要的 Channel不加入無關(guān)通道語義明確每個 Channel 有清晰的用途定義避免萬能通道消息類型規(guī)范使用標準 AgentMessageType不自造類型元數(shù)據(jù)豐富充分利用 metadata 傳遞上下文減少正文冗余歷史可追溯所有 Channel 消息持久化支持事后審計優(yōu)雅降級Channel 不可用時 Agent 應(yīng)能降級為單機模式10.2 常見反模式// ? 一個 Broadcast Channel 承載所有通信// 消息噪音大Agent 注意力分散// ? 用 TEXT 類型傳遞任務(wù).type(AgentMessageType.TEXT).content(幫我分析一下數(shù)據(jù))// 應(yīng)使用 TASK_ASSIGNMENT便于框架處理和追蹤// ? 在消息正文中嵌入大段數(shù)據(jù).content(以下是1000行CSV數(shù)據(jù)...)// 應(yīng)使用 file_ref 附件// ? 繞過 Channel 直接調(diào)用其他 AgentotherAgent.call(message);// 禁止// 所有交互必須通過 Channel// ? 不設(shè)消息攔截器// 生產(chǎn)環(huán)境至少應(yīng)有審計日志和內(nèi)容過濾10.3 調(diào)試與觀測工具用途Channel 消息日志查看完整消息流MetricsInterceptor消息延遲、吞吐量監(jiān)控StateStore 查詢檢查消息持久化狀態(tài)System Reminder 注入預(yù)覽驗證 Agent 看到的 Channel 上下文十一、設(shè)計哲學總結(jié)1. 通信是認知行為不是傳輸行為Channel 的設(shè)計前提是Agent 收發(fā)消息是認知過程理解、判斷、決策不是傳輸過程投遞、確認、重試。這決定了 Channel 的每一個設(shè)計選擇都圍繞語義而非可靠性展開。2. 結(jié)構(gòu)化是語義理解的基礎(chǔ)自由文本的消息只有 LLM 能讀結(jié)構(gòu)化的 AgentMessage 框架也能讀。這使得路由、過濾、持久化、注入等基礎(chǔ)設(shè)施操作成為可能而不必每次都經(jīng)過 LLM。3. Channel 是契約不是管道Channel 定義了參與者之間的交互契約誰能發(fā)、什么類型、什么格式而不僅僅是消息的傳輸管道。這種契約意識是多 Agent 系統(tǒng)可治理的前提。4. 歷史是上下文不是日志Channel 消息歷史不是用完即棄的日志而是 Agent 的共享工作記憶。它通過 WorkspaceContextHook 注入每輪推理成為 Agent 認知的一部分。5. 通信拓撲應(yīng)該反映認知拓撲Direct/Broadcast/Routed 三種 Channel 類型對應(yīng)三種人類協(xié)作模式一對一協(xié)商、全員同步、按需分發(fā)。技術(shù)拓撲與認知拓撲的對齊是多 Agent 系統(tǒng)自然感的來源。十二、結(jié)語AgentScope Harness 的 Channel 系統(tǒng)回答了一個根本性的架構(gòu)問題如何讓多個 Agent 像團隊一樣溝通而不是像微服務(wù)一樣調(diào)用答案是設(shè)計一套面向 Agent 認知模型的通信抽象讓消息的結(jié)構(gòu)、路由、歷史和語義都服務(wù)于理解而非傳輸。當你把 Agent 通信從消息傳遞重新定義為認知協(xié)調(diào)時很多設(shè)計決策就變得自然而然了消息需要結(jié)構(gòu)化 → 因為框架要參與理解路由可以是語義的 → 因為誰該收到本身就是一個推理問題歷史要注入上下文 → 因為溝通是連續(xù)的認知過程確認是語義級的 → 因為收到不等于理解并接受如果你正在構(gòu)建多 Agent 系統(tǒng)這套認知導向的通信設(shè)計思路值得深入研究和借鑒。它讓多 Agent 協(xié)作從技術(shù)拼接走向了認知融合——這不僅是架構(gòu)的升級更是讓 AI 系統(tǒng)真正具備團隊協(xié)作智能的關(guān)鍵一步。