多智能体会话

多智能体是一项研究预览功能。请求访问权限以试用。

多智能体编排允许一个智能体与其他智能体协调以完成复杂工作。智能体可以并行运行，每个都有自己隔离的上下文，这有助于提高输出质量并缩短完成时间。

所有托管智能体 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")