如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

多智能体

让智能体将任务委派给独立的子智能体。

启用多智能体功能后,智能体可以将任务委派给子智能体。每个子智能体都有自己的上下文,可以与其他子智能体并行工作。主智能体负责协调工作并汇总结果。

何时使用子智能体

将彼此独立的任务交给子智能体,例如分别审阅不同的文档,或排查同一故障的不同可能原因。为每项任务明确要回答的问题和预期结果。

让主智能体处理耗时短的任务和有依赖关系的步骤。如果多个智能体编辑同一文件,就必须协调各自的修改。

启用多智能体编排

创建会话时,将 agent.multi_agent.enabled 设为 true。执行框架提供的工具可用于创建子智能体、向子智能体发送消息、等待子智能体以及中断子智能体。您无需自行声明这些工具。

在此示例中,用户输入明确要求使用两个子智能体。每个子智能体审阅一组发布说明,再由主智能体汇总审阅结果。此示例无需使用环境,也无需配置工具。

比较发布说明
from openai import OpenAI

client = OpenAI()

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Delegate each release to a separate subagent. Ask each to extract customer-visible changes and required migration steps using only its release notes. Wait for both results, then combine them into one release summary with release labels. Do not invent missing details.",
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 2},
    },
    environment={"type": "none"},
    input="Use two subagents, one for each release, and combine their findings into a labeled summary. Release A: Search now supports filtering by date. Existing queries continue to work. Release B: The export endpoint now returns a download URL instead of file bytes. Update clients to fetch that URL.",
    stream=True,
).with_result_collection() as stream:
    for event in stream:
        print(event.model_dump_json())
    result = stream.get_final_result()
print(result.output_text)

使用 environment.type: "none" 时,请在创建会话的请求中包含初始 input。设置 stream: true 后,首轮交互也会以流式方式返回。有关如何处理和恢复事件流,请参阅会话事件和条目。

并发设置

max_concurrent_subagents 限制可同时运行的子智能体数量。默认上限为 6,负责协调的主智能体不计入其中。启用委派时,请将上限设为正整数。

要禁用委派,请省略 multi_agent,或将 enabled 设为 false 并省略并发上限。这些设置在创建会话时生效。对已保存智能体的更改仅对新会话生效。

使用环境

当智能体需要访问文件或执行命令时,请添加环境。主智能体和子智能体共享该环境的文件系统。创建子智能体时不会创建新环境。

此示例创建一个会话,让智能体在您自己的环境中工作。

在您自己的环境中启用委派
const result = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "Prepare release notes from the repository. Have one subagent identify customer-visible changes and another check migration guides and examples, then combine their findings.",
    multi_agent: {
      enabled: true,
      max_concurrent_subagents: 3,
    },
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

请在您的应用中保存返回的会话 ID 和环境 ID。连接环境,然后发送输入以开始工作。

子智能体可用的工具

子智能体会继承已配置的 MCP 工具及其凭据和允许使用的工具列表,也会继承网页搜索设置。子智能体还可以使用环境中的文件和命令行工具。子智能体不支持函数工具。

查看委派过程

会话事件流会报告子智能体的活动:

  • agent.session.subagent.created 提供新建子智能体的 ID。
  • agent.session.turn.item.added 和 agent.session.turn.item.done 报告协调操作。对应的条目类型包括 create_subagent_call、send_subagent_input_call、wait_for_subagents_call 和 interrupt_subagent_call。

执行框架负责执行这些操作。创建或等待操作完成,并不代表子智能体已完成任务。在创建操作的条目中,agent_id 标识请求创建子智能体的智能体。

协调操作的条目可能不包含消息内容。如果有智能体之间传递的文本,agent_message 条目会包含这些文本,但事件流不会提供完整的对话记录。

查看主智能体的回复即可获取汇总结果。您可以通过已保存的条目和轮次查看先前的工作,包括每个子智能体的历史记录。

确定命令由哪个智能体执行

使用命令条目及其会话 ID 检索该命令所属的轮次,即可确定执行命令的智能体。如果命令由主智能体执行,该轮次的 subagent_id 为 null。

确定执行命令的智能体
// Use the saved session ID and command execution item from your application.
const turn = await client.beta.agents.sessions.turns.retrieve(
  command.turn_id,
  { session_id: sessionId }
);
console.log(turn.subagent_id);