多代理會話

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

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

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

運作方式

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

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

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

委派的內容

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

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

宣告可呼叫的代理

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

orchestrator=$(curl -fsS https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "name": "Engineering Lead",
  "model": "claude-sonnet-4-6",
  "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}
  ]
}
EOF
)

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

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

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

會話執行緒

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

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

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

從特定執行緒串流事件：

列出執行緒的過去事件：

多代理事件類型

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

類型	描述
`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。

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"agent": "'$ORCHESTRATOR_ID'", "environment_id": "'$ENVIRONMENT_ID'"}')

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.agent_name)] \(.status)"'

curl -fsSN "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" |
  while IFS= read -r line; do
    [[ $line == data:* ]] || continue
    json=${line#data: }
    case $(jq -r '.type' <<<"$json") in
      agent.message)
        printf '%s' "$(jq -j '.content[] | select(.type == "text") | .text' <<<"$json")"
        ;;
      session.thread_idle)
        break
        ;;
    esac
  done

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.type)] \(.processed_at)"'

while IFS= read -r event_id; do
  pending=$(jq -r --arg id "$event_id" '.[$id]' <<<"$events_by_id")
  thread_id=$(jq -r '.session_thread_id // empty' <<<"$pending")
  jq -n --arg id "$event_id" --arg thread "$thread_id" '
    {events: [
      {type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}
      + (if $thread != "" then {session_thread_id: $thread} else {} end)
    ]}' |
    curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: managed-agents-2026-04-01" \
      -H "content-type: application/json" \
      -d @-
done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")