多智能体会话

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



工作原理

所有智能体共享同一个沙箱、文件系统和保险库凭据，但每个智能体都在自己的 "session 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_ids 适用于每个线程）。这对您的集成有两个影响：

• 要对 MCP 服务器进行身份验证，请为所有智能体使用的每个 MCP 服务器包含一个保险库凭据。
• 要限制某个智能体的访问权限，请在其智能体定义中仅声明它所需的服务器。

会话创建时的智能体配置覆盖可以替换协调器及其 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）被视为主线程，包含所有线程中所有活动的精简视图。您不会看到子智能体的完整活动，但可以看到它们工作的开始和结束，以及工具权限请求等阻塞事件。

会话线程是您深入查看特定智能体活动的地方。

会话的 status 是所有智能体活动的聚合；如果至少有一个线程处于 running 状态，则整个会话状态也为 running。



主线程事件

这些事件在 /v1/sessions/:id/events/stream 的主线程上呈现多智能体活动。



会话线程事件

关键事件会被代理到主线程。但是，您可能仍然希望调查特定智能体的推理过程和工具调用。为此，请从关联的会话线程流式传输或列出事件。



工具权限和自定义工具

如果子智能体需要从您的客户端获取某些内容，例如运行 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",
            }
        ],
    )