多代理会话

构建高级编排

多智能体会话

在单个会话中协调多个智能体。

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

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

所有托管智能体 API 请求都需要 managed-agents-2026-04-01 测试版标头。研究预览功能需要额外的测试版标头。SDK 会自动设置这些测试版标头。

工作原理

所有智能体共享同一个容器和文件系统，但每个智能体在自己的会话线程中运行，这是一个上下文隔离的事件流，具有自己的对话历史。协调器在主线程中报告活动（与会话级事件流相同）；当协调器决定委派时，在运行时生成额外的线程。

线程是持久的：协调器可以向之前调用过的智能体发送后续消息，该智能体会保留其之前所有轮次的内容。

每个智能体使用其自己的配置（模型、系统提示、工具、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?

构建高级编排

多智能体会话

在单个会话中协调多个智能体。

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

所有托管智能体 API 请求都需要 managed-agents-2026-04-01 测试版标头。研究预览功能需要额外的测试版标头。SDK 会自动设置这些测试版标头。

工作原理

线程是持久的：协调器可以向之前调用过的智能体发送后续消息，该智能体会保留其之前所有轮次的内容。

每个智能体使用其自己的配置（模型、系统提示、工具、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?