多代理工作階段

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



運作方式

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

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

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



適合委派的工作

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

運作良好的模式：

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



設定協調者

在定義您的代理時，設定 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 名單）會在協調者建立或更新時建立快照。被參照的代理會固定在當時解析的版本，不會自動取得其定義的後續更新。若要委派給被參照代理的較新版本，請更新協調者，使其名單參照該版本。

協調者只能委派至一層代理；深度 > 1 會被忽略。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)

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



執行緒

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

Session threads（工作階段執行緒）是您深入查看特定代理活動的地方。

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



主執行緒事件

這些事件會在 /v1/sessions/:id/events/stream 的主執行緒上呈現多代理活動。



工作階段執行緒事件

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



工具權限和自訂工具

如果子代理需要您的用戶端提供某些內容，例如執行 always_ask 工具的權限，或自訂工具的結果，該事件會被交叉發布至 primary thread（主執行緒），並附帶 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",
            }
        ],
    )