多代理工作階段

建構進階協調

多代理會話

在單一會話中協調多個代理。

多代理是研究預覽功能。請求存取以試用。

多代理編排讓一個代理與其他代理協調以完成複雜的工作。代理可以並行運作，各自擁有隔離的上下文，這有助於改善輸出品質並縮短完成時間。

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。研究預覽功能需要額外的 beta 標頭。SDK 會自動設定這些 beta 標頭。

運作方式

所有代理共享相同的容器和檔案系統，但每個代理在自己的會話執行緒中運作，這是一個上下文隔離的事件流，具有自己的對話歷史。協調器在主執行緒中報告活動（與會話級事件流相同）；當協調器決定委派時，會在執行時生成額外的執行緒。

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

每個代理使用自己的配置（模型、系統提示、工具、MCP 伺服器和技能），如建立該代理時定義的那樣。工具和上下文不共享。

委派的內容

多代理會話在有多個範圍明確、專門化的任務來完成整體目標時效果最佳：

程式碼審查： 具有專注系統提示和唯讀工具的審查代理。
測試生成： 編寫和執行測試而不觸及生產程式碼的測試代理。
研究： 具有網路工具的搜尋代理，將發現結果總結回協調器。

宣告可呼叫的代理

當定義您的代理時，列出它被允許呼叫的其他代理的 ID：

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

callable_agents 中的每個項目必須是現有代理的 ID。僅支援一級委派：協調器可以呼叫其他代理，但這些代理不能呼叫自己的代理。

然後建立參考協調器的會話：

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

可呼叫的代理從協調器的配置中解析。您不需要在會話建立時參考它們。

會話執行緒

會話級事件流（/v1/sessions/:id/stream）被視為主執行緒，包含所有執行緒中所有活動的濃縮檢視。您不會看到被呼叫代理的個別追蹤，但您會看到它們工作的開始和結束。會話執行緒是您深入了解特定代理推理和工具呼叫的地方。

會話狀態也是所有代理活動的聚合；如果至少一個執行緒是 running，則整體會話狀態也將是 running。

列出會話中的所有執行緒如下：

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

從特定執行緒串流事件：

with client.beta.sessions.threads.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_idle":
                break

列出執行緒的過去事件：

for event in client.beta.sessions.threads.events.list(
    thread.id,
    session_id=session.id,
):
    print(f"[{event.type}] {event.processed_at}")

多代理事件類型

這些事件在頂級會話流上呈現多代理活動。

類型	描述
`session.thread_created`	協調器生成了新執行緒。包括 `session_thread_id` 和 `model`。
`session.thread_idle`	代理執行緒完成了其目前的工作。
`agent.thread_message_sent`	代理向另一個執行緒發送了訊息。包括 `to_thread_id` 和 `content`。
`agent.thread_message_received`	代理從另一個執行緒接收了訊息。包括 `from_thread_id` 和 `content`。

執行緒中的工具權限和自訂工具

當 callable_agent 執行緒需要來自您的用戶端的某些內容（權限以執行 always_ask 工具，或自訂工具的結果）時，請求會在會話流上呈現，並帶有 session_thread_id 欄位。在發佈回應時包括相同的 session_thread_id，以便平台將其路由回等待的執行緒。

session_thread_id 存在： 事件源自子代理執行緒。在您的回覆中回應它。
session_thread_id 不存在： 事件來自主執行緒。回覆時不包括該欄位。
在 tool_use_id 上匹配以配對請求和回應。

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

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    # Echo session_thread_id when the request came from a subagent thread
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])

Was this page helpful?

建構進階協調

多代理會話

在單一會話中協調多個代理。

多代理是研究預覽功能。請求存取以試用。

多代理編排讓一個代理與其他代理協調以完成複雜的工作。代理可以並行運作，各自擁有隔離的上下文，這有助於改善輸出品質並縮短完成時間。

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。研究預覽功能需要額外的 beta 標頭。SDK 會自動設定這些 beta 標頭。

運作方式

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

每個代理使用自己的配置（模型、系統提示、工具、MCP 伺服器和技能），如建立該代理時定義的那樣。工具和上下文不共享。

委派的內容

多代理會話在有多個範圍明確、專門化的任務來完成整體目標時效果最佳：

程式碼審查： 具有專注系統提示和唯讀工具的審查代理。
測試生成： 編寫和執行測試而不觸及生產程式碼的測試代理。
研究： 具有網路工具的搜尋代理，將發現結果總結回協調器。

宣告可呼叫的代理

當定義您的代理時，列出它被允許呼叫的其他代理的 ID：

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

callable_agents 中的每個項目必須是現有代理的 ID。僅支援一級委派：協調器可以呼叫其他代理，但這些代理不能呼叫自己的代理。

然後建立參考協調器的會話：

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

可呼叫的代理從協調器的配置中解析。您不需要在會話建立時參考它們。

會話執行緒

會話狀態也是所有代理活動的聚合；如果至少一個執行緒是 running，則整體會話狀態也將是 running。

列出會話中的所有執行緒如下：

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

從特定執行緒串流事件：

with client.beta.sessions.threads.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_idle":
                break

列出執行緒的過去事件：

for event in client.beta.sessions.threads.events.list(
    thread.id,
    session_id=session.id,
):
    print(f"[{event.type}] {event.processed_at}")

多代理事件類型

這些事件在頂級會話流上呈現多代理活動。

類型	描述
`session.thread_created`	協調器生成了新執行緒。包括 `session_thread_id` 和 `model`。
`session.thread_idle`	代理執行緒完成了其目前的工作。
`agent.thread_message_sent`	代理向另一個執行緒發送了訊息。包括 `to_thread_id` 和 `content`。
`agent.thread_message_received`	代理從另一個執行緒接收了訊息。包括 `from_thread_id` 和 `content`。

執行緒中的工具權限和自訂工具

session_thread_id 存在： 事件源自子代理執行緒。在您的回覆中回應它。
session_thread_id 不存在： 事件來自主執行緒。回覆時不包括該欄位。
在 tool_use_id 上匹配以配對請求和回應。

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

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    # Echo session_thread_id when the request came from a subagent thread
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])

Was this page helpful?