多代理協調

「Multiagent orchestration」（多代理協調）讓一個代理能與其他代理協調以完成複雜的工作。代理可以在各自獨立的上下文中平行運作，這有助於提升輸出品質，也能縮短完成時間。

不確定多代理設置是否適合您的問題？請參閱何時使用多代理系統（以及何時不該使用）。



運作方式

所有代理共享相同的沙箱、檔案系統和 vault 憑證，但每個代理都在自己的**工作階段執行緒（session thread）中運行，這是一個具有自己對話歷史的上下文隔離事件串流。協調者（coordinator）在主要執行緒（primary thread）**中回報活動（與工作階段層級的事件串流相同）；當協調者委派工作時，會在執行期間產生額外的執行緒。

執行緒是持久性的：協調者可以向先前呼叫過的代理發送後續訊息，而該代理會保留其先前回合的所有內容。

每個代理使用自己的配置：模型、系統提示、工具、MCP 伺服器和技能。工作階段層級的代理配置覆寫是例外；它們適用於協調者及其 self 副本。工具、MCP 伺服器和上下文不會共享。



應委派什麼

多代理協調最適合用於需要跨多種介面工作的複雜任務，或是由多個範圍明確的任務共同達成整體目標的情況。

效果良好的模式：

• 平行化（Parallelization）： 同時分散執行獨立的子任務（搜尋多個來源、分析不同的檔案），並讓協調者綜合結果。
• 專業化（Specialization）： 路由到具有特定領域系統提示和工具的代理，例如安全代理或文件代理，而不是讓單一代理承載所有功能。
• 升級（Escalation）： 針對一部分複雜的子任務諮詢能力更強的代理或模型。



配置協調者

在定義您的代理時，設定 multiagent 以宣告協調者可以委派的代理名單：

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-8
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID
    - type: agent
      id: $TEST_WRITER_AGENT_ID
YAML

multiagent.agents 可以接受以下任何一種：

• {"type": "agent", "id": agent.id} 透過 ID 參照先前建立的 agent。如果未指定 version，則該參照會固定在協調者建立時該代理的最新版本。
• {"type": "agent", "id": agent.id, "version": agent.version} 固定特定的代理版本。
• {"type": "self"} 允許協調者產生自己的副本。如果工作階段是使用代理配置覆寫建立的，這些覆寫也會套用到這些副本；透過 ID 參照的名單項目則不受影響。

協調者的配置（包括其 multiagent.agents 名單）會在協調者建立或更新時建立快照。被參照的代理會固定在當時解析的版本，不會自動採用其定義的後續更新。若要委派給被參照代理的較新版本，請更新協調者，使其名單參照該版本。

協調者只能委派給一層代理；參照一個本身擁有 multiagent.agents 名單的代理，會使建立或更新請求因驗證錯誤而失敗。multiagent.agents 中最多可列出 20 個不重複的代理，但協調者可以呼叫每個代理的多個副本。



建立工作階段

建立一個參照協調者的工作階段。協調者會視需要委派給其名單中的代理。

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
)



將代理連接到 MCP 伺服器

MCP 伺服器是代理範圍的（每個代理定義宣告自己的伺服器和工具），而 vault 憑證是工作階段範圍的（在建立工作階段時傳入的 vault_ids 適用於每個執行緒）。這對您的整合有兩個影響：

• 若要驗證 MCP 伺服器，請為所有代理使用的每個 MCP 伺服器包含一個 vault 憑證。
• 若要限制代理的存取權限，只在其代理定義中宣告它需要的伺服器。

在建立工作階段時的代理配置覆寫可以取代協調者及其 self 副本的 MCP 伺服器。

research_agent = client.beta.agents.create(
    name="researcher",
    model="claude-haiku-4-5",
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)

coordinator = client.beta.agents.create(
    name="coordinator",
    model="claude-opus-4-8",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [{"type": "agent", "id": research_agent.id}],
    },
)

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
print(session.id)

在此範例中，只有研究員（researcher）宣告了 GitHub MCP 伺服器，因此協調者沒有存取權限。工作階段的 vault_ids 將 GitHub 憑證提供給研究員的執行緒。



執行緒

工作階段層級的事件串流（/v1/sessions/{session_id}/events/stream）被視為主要執行緒，包含所有執行緒中所有活動的精簡檢視。您不會看到子代理的完整活動，但會看到它們工作的開始和結束，以及阻塞事件（例如工具權限請求）。

工作階段執行緒是您深入檢視特定代理活動的地方。

工作階段的 status 是所有代理活動的彙總；如果至少有一個執行緒是 running，則整體工作階段狀態也會是 running。

for thread in client.beta.sessions.threads.list(session.id):
    print(f"[{thread.agent.name}] {thread.status}")



主要執行緒事件

這些事件在 /v1/sessions/{session_id}/events/stream 的主要執行緒上呈現多代理活動。訊息方向事件的命名是相對於其串流所在的執行緒：agent.thread_message_received 表示有訊息從另一個執行緒抵達此執行緒，而 agent.thread_message_sent 表示此執行緒發送了一則訊息。例如，協調者委派的任務會以 agent.thread_message_received 事件的形式抵達子執行緒自己的串流。



工作階段執行緒事件

關鍵事件會被代理轉發到主要執行緒。不過，您可能仍想調查特定代理的推理和工具呼叫。若要這麼做，請串流或列出相關工作階段執行緒的事件。

每個工作階段執行緒在 /v1/sessions/{session_id}/threads/{thread_id}/stream 都有自己的事件串流，並且接受與工作階段層級串流相同的 event_deltas[] 參數，因此您可以在模型生成時預覽子代理的文字。一個連線只會預覽它正在讀取的執行緒：子執行緒的預覽永遠不會出現在工作階段層級的串流上，因此若要即時觀看子代理，請開啟其自己的執行緒串流。請參閱預覽工作階段執行緒事件以了解如何選擇加入、累積和核對預覽。

with client.beta.sessions.threads.events.stream(
    thread.id,
    session_id=session.id,
) as stream:
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.thread_status_idle":
                break



工具權限和自訂工具

如果子代理需要從您的用戶端取得某些東西，例如執行 always_ask 工具的權限，或是自訂工具的結果，該事件會被交叉發佈到主要執行緒，並以 session_thread_id 識別來源的工作階段執行緒。

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["toolu_01XYZ..."]
  }
}

發佈 user.tool_confirmation（帶有 tool_use_id）或 user.custom_tool_result（帶有 custom_tool_use_id）；伺服器會自動將回應路由到正確的執行緒。

以下範例擴展了工具確認處理器以路由回覆。相同的模式也適用於 user.custom_tool_result。

for event_id in stop.event_ids:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.tool_confirmation",
                "tool_use_id": event_id,
                "result": "allow",
            }
        ],
    )