Claude Platform Docs
Managed Agents高级编排

多智能体编排

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

"Multiagent orchestration"(多智能体编排)让一个智能体能够与其他智能体协作完成复杂的工作。各智能体可以在各自隔离的上下文中并行运行,这有助于提升输出质量,也可以缩短完成时间。

不确定多智能体方案是否适合您的问题?请参阅何时使用多智能体系统(以及何时不使用)。

将工作交给其他智能体

会话运行的智能体可以通过两种方式将工作交给其他智能体。使用 subagents(子智能体)时,它自己委派任务并读取每个子智能体的报告。使用 dynamic workflows(动态工作流)时,它会编写一个工作流:一个在后台运行多个智能体并合并其结果的程序。它还可以在自己完成工作的同时,向 advisor(顾问)模型寻求指导。

您决定智能体可以使用其中哪些方式,而智能体决定何时使用它们。为了引导这一选择,请在智能体的系统提示中告诉它何时使用工作流运行。请参阅告诉智能体何时使用运行。您还可以将智能体限制为只能使用您列出的智能体。

使用子智能体时,由智能体自己决定接下来发生什么。子智能体的线程在您将其归档之前一直可用,因此智能体可以向其发送后续消息。使用动态工作流时,Claude 会编写一个程序来编排智能体,而无需 Claude 直接参与。上下文和结果以编程方式从一个智能体传递到另一个智能体,从而让主会话线程腾出手来与用户沟通,并查看一个或多个正在运行的工作流以报告进度。智能体无法向运行的线程发送后续消息,服务器最迟会在运行结束时将其中每个线程归档。

方式会发生什么适用场景注意事项
子智能体智能体将任务委派给其子智能体。每个子智能体在自己的会话线程中工作,您可以列出这些线程并对其进行流式传输。智能体需要在子智能体报告后对其进行跟进,或者需要您列出的、拥有各自系统提示和工具的专业智能体。委派只有一层深度,一个会话同时最多可以有 25 个子线程,包括空闲线程。顾问线程和工作流运行的线程不计入其中。
动态工作流智能体编写一个工作流:一个分阶段运行多个智能体并合并其结果的程序。服务器在后台将其作为一个工作流运行来执行,您可以跟踪它。工作流会定义智能体,或从您提供的列表中选择智能体。大多数需要多个智能体的工作:包含许多部分的工作、并行工作,或应更快完成的长任务。例如审计、迁移、深度研究和交叉核对。运行中的每个智能体都会消耗令牌,因此请设置会话预算来限制会话的支出(包括运行)。在智能体的系统提示中告诉它何时使用运行。您可以按阶段跟踪运行,并可以读取其每个线程。
为会话配置顾问会话的主线程在轮次中途向顾问模型寻求指导,例如规划方法或审查工作,并继续自己完成工作。应由一个智能体完成工作,并在规划或最终审查等关键时刻借助顾问模型的判断。只有主线程可以咨询顾问,咨询按顾问模型的费率计费。

您可以在智能体定义的 multiagent 块中设置这些内容,该块有一个 type。使用 multiagent_20261001 类型时,智能体可以同时使用这三种方式,并且您可以分别开启或关闭每一种。默认情况下,subagents 和 workflows 都已启用。subagents 和 workflows 各自都启用了 inline_agents,这是用于由智能体或工作流自行定义的智能体的设置:

{
  "multiagent": { "type": "multiagent_20261001" }
}

要设置智能体可以调用哪些智能体,请参阅预定义智能体和内联智能体。要关闭某项设置,请参阅开启动态工作流。

预定义智能体和内联智能体

每个子智能体,以及工作流运行中的每个智能体,都属于以下两种类型之一:

  • 预定义智能体(predefined agent): 您已经创建并在 multiagent 块中列出的智能体。它使用自己的配置:模型、系统提示、工具、MCP 服务器和技能。
  • 内联智能体(inline agent): 未保存的智能体。会话运行的智能体或工作流在分派工作时定义它。它使用该智能体的模型、工具、MCP 服务器和技能。

这两种类型在 subagents 和 workflows 下都可以使用:

智能体类型在 subagents 下在 workflows 下
预定义智能体可以委派给您在 subagents.predefined_agents 中列出的智能体。工作流可以使用您在 workflows.predefined_agents 中列出的智能体。
内联智能体在委派时可以定义内联智能体。subagents.inline_agents 用于开启或关闭此功能。工作流可以定义内联智能体,并为每个智能体编写系统提示。workflows.inline_agents 用于开启或关闭此功能。

subagents.predefined_agents 和 workflows.predefined_agents 是两个独立的列表。一个列表中的智能体不会被添加到另一个列表中。两个列表默认都为空。任一列表的条目采用以下形式之一:

  • {"type": "agent", "id": agent.id} 通过 ID 引用先前创建的 agent。如果未指定 version,则在创建列出它的智能体时,或在更新发送该列表时,该引用会固定到该智能体的最新版本。
  • {"type": "agent", "id": agent.id, "version": agent.version} 固定特定的智能体版本。
  • 单独的 agent.id 字符串是 {"type": "agent", "id": agent.id} 的简写。
  • {"type": "self"} 列出智能体本身,以便由它的副本来完成工作。如果会话是使用智能体配置覆盖创建的,这些覆盖也会应用于这些副本。通过 ID 引用的条目不受影响。

这些条目及其所指智能体的规则适用于两个列表。请参阅列出子智能体。

在这两项设置下,内联智能体默认都是开启的。要只允许您列出的智能体,请在 subagents 下、workflows 下或两者下将 inline_agents 设置为 {"type": "disabled"}。关闭内联智能体的设置需要在其 predefined_agents 列表中至少有一个智能体。如果列表为空,请求会失败并返回 400 错误。在更新时,服务器会检查更新后的设置。

以下智能体只允许其列出的智能体。它可以委派给一个智能体以及它自己的副本,并且工作流可以使用另一个智能体的版本 2:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }]
    },
    "workflows": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": [
        { "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h", "version": 2 }
      ]
    }
  }
}

委派给子智能体

委派什么

多智能体协调最适合复杂任务:这些任务要么需要跨多种界面开展工作,要么由多个范围明确的任务共同服务于一个总体目标。

效果良好的模式:

  • 并行化: 同时分发独立的子任务(搜索多个来源、分析不同的文件),并让智能体综合结果。
  • 专业化: 路由到具有领域专注系统提示和工具的智能体,例如安全智能体或文档智能体,而不是让单个智能体承载所有能力。
  • 升级: 针对一部分复杂子任务咨询能力更强的智能体或模型。要咨询模型,请为会话配置顾问。

工作原理

所有智能体共享同一个沙箱、文件系统和保管库凭据,但每个智能体都在自己的 session thread(会话线程)中运行,这是一个具有独立对话历史、上下文隔离的事件流。会话运行的智能体在主线程中报告活动,主线程即会话级别的事件流。当它委派工作时,会在运行时生成额外的线程。工作流运行也会创建线程。

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

子智能体使用哪种配置取决于它是预定义智能体还是内联智能体。会话级别的智能体配置覆盖适用于会话运行的智能体及其 self 副本。每个智能体都保留自己的对话历史。

列出子智能体

在定义您的智能体时,在 multiagent 块中设置 subagents 的 predefined_agents 列表,以列出它可以委派的智能体:

ant apply engineering-lead.md reviewer.md test-writer.md
engineering-lead.md
---
name: Engineering Lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents: # ant apply replaces each path with {type: agent, id, version}
      - ./reviewer.md
      - ./test-writer.md
---

You coordinate engineering work. Delegate code review to the reviewer agent
and test writing to the test agent.
reviewer.md
---
name: reviewer
model: claude-haiku-5-5
---

You are a code reviewer.
test-writer.md
---
name: test-writer
model: claude-haiku-5-5
---

You write unit tests.

除非您将其关闭,否则智能体还可以委派给内联智能体。关于该设置,以及 subagents 的 predefined_agents 列表条目可采用的形式,请参阅预定义智能体和内联智能体。

"advisor": {"type": "enabled", "model": "<model id>"} 为会话的主线程提供一个可在轮次中途咨询的顾问。顾问是 multiagent 块中的一项设置,而不是此列表中的条目。请参阅为会话配置顾问。

使用此类型时,动态工作流也默认启用,因此该智能体可以规划在后台运行多个智能体的大型工作。要关闭它们,或列出工作流可以使用的智能体,请参阅开启动态工作流。

以下规则适用于您在 subagents 的 predefined_agents 列表中列出的智能体,也适用于您在 workflows 的 predefined_agents 列表中列出的智能体:

  • 固定版本: 智能体的配置(包括 subagents 的 predefined_agents 列表)会在智能体创建或更新时生成快照。被引用的智能体会固定在当时解析出的版本上,不会获取其定义的后续更新。未发送该列表的更新会保留已固定的版本。要委派给被引用智能体的较新版本,请更新智能体,使 subagents 的 predefined_agents 列表引用该版本。
  • 一层: 智能体只能委派给一层智能体。引用另一个设置了 multiagent 的智能体,会导致创建或更新请求失败并返回 400 验证错误。
  • 最多 20 个智能体: subagents 的 predefined_agents 列表最多可以列出 20 个不同的智能体。该限制按列表计算:workflows 的 predefined_agents 列表也最多可以列出 20 个。在会话的线程限制范围内,智能体可以调用每个子智能体的多个副本。
  • 推理地理区域: 智能体以及您在 subagents 或 workflows 的 predefined_agents 列表中列出的每个智能体,必须固定相同的推理地理区域(智能体定义的 model 中的 inference_geo),或者它们都不固定。任一列表中出现不匹配都会被拒绝并返回 400 验证错误。该检查在保存智能体时运行,也会在会话创建覆盖更改任何固定设置时运行。

创建会话

创建一个引用该智能体的会话。智能体会根据需要委派给您在 subagents 的 predefined_agents 列表中列出的智能体。除非您将其关闭,否则它还可以委派给内联智能体。

session = client.beta.sessions.create(
    agent=lead_agent.id,
    environment_id=environment.id,
)

将智能体连接到 MCP 服务器

MCP 服务器的作用域是智能体:每个智能体定义声明自己的服务器和工具。内联智能体没有智能体定义,因此它使用会话运行的智能体的 MCP 服务器和工具。保管库凭据的作用域是会话:在创建会话时传入的 vault_ids 适用于每个线程。这对您的集成有两点影响:

  • 要对 MCP 服务器进行身份验证,请为所有智能体中使用的每个 MCP 服务器提供保管库凭据。
  • 要限制智能体的访问权限,请在其智能体定义中只声明它需要的服务器。您无法以这种方式限制内联智能体。要只允许您列出的智能体,请在 subagents 和 workflows 中都禁用 inline_agents,并在每个列表中至少列出一个智能体。请参阅预定义智能体和内联智能体。

创建会话时的智能体配置覆盖可以替换会话运行的智能体及其 self 副本的 MCP 服务器。

使用 limited 环境时,如果智能体或您在 subagents 或 workflows 的 predefined_agents 列表中列出的智能体声明了主机不在 allowed_hosts 中的 MCP 服务器,会话创建会失败并返回 400 错误。在环境的网络设置中将 allow_mcp_servers 设置为 true 可关闭此检查。

创建声明了 GitHub MCP 服务器的研究员智能体,以及委派给该研究员的智能体:

ant apply lead.md researcher.md
lead.md
---
name: lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents: # ant apply replaces each path with {type: agent, id, version}
      - ./researcher.md
---
researcher.md
---
name: researcher
model: claude-haiku-5-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: mcp_toolset
    mcp_server_name: github
---

然后使用保存 GitHub 凭据的保管库创建会话:

session = client.beta.sessions.create(
    agent=lead_agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
print(session.id)

在此示例中,只有研究员声明了 GitHub MCP 服务器,因此会话运行的智能体没有访问权限。会话的 vault_ids 将 GitHub 凭据提供给研究员的线程。

线程

每个智能体的会话线程都有自己的事件流。要列出、中断或归档线程,读取其事件,以及跨线程处理工具权限,请参阅会话线程。

动态工作流

借助动态工作流,智能体可以承担包含许多部分的工作,例如审查数百份文档或交叉核查多个来源。智能体编写一个 workflow(工作流):一个分阶段运行多个智能体并合并其返回结果的程序。服务器在后台将其作为 workflow run(工作流运行)来执行,同时智能体继续工作或结束其轮次。您可以通过智能体 multiagent 块中的 workflows 设置开启或关闭动态工作流。运行中的智能体可以同时工作,因此与由一个智能体依次完成每个部分相比,长任务可以更快完成。

  • 运行如何启动: 您在 user.message 中描述工作。智能体据此决定是否以及何时启动运行,因此无需额外的 API 调用。相反,您可以通过在 user.message 或智能体的系统提示中描述何时使用运行,来影响智能体的决定。(权限策略适用于运行中的智能体所调用的工具,而不适用于启动运行。)
  • 使用哪些智能体: 工作流定义的内联智能体、您在 workflows 的 predefined_agents 列表中列出的预定义智能体,或两者兼有。如果您未列出任何智能体,则由工作流定义所有智能体。内联智能体使用会话运行的智能体的模型。要让运行中的部分智能体使用其他模型,请将它们创建为智能体,并在 workflows 的 predefined_agents 列表中列出它们。
  • 如何跟踪: 运行事件会到达会话的事件流,运行中的每个智能体都在一个会话线程中工作,您可以列出、读取这些线程并对其进行流式传输。有关事件、中断、限制以及运行的线程显示的内容,请参阅工作流运行。

开启动态工作流

在定义您的智能体时,将 multiagent.type 设置为 "multiagent_20261001" 并启用 workflows。使用此类型时,动态工作流和委派(subagents)默认均处于启用状态。如果只需要动态工作流,请添加 "subagents": {"type": "disabled"}。

在更改现有智能体的 multiagent.type 之前,请参阅如何将智能体迁移到此类型。

ant apply contract-reviewer.md
contract-reviewer.md
---
name: Contract Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  workflows:
    type: enabled
---

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

要让工作流使用您已创建的智能体,请在 workflows.predefined_agents 中列出它们。subagents 和 advisor 设置位于同一个 multiagent 块中。要列出子智能体,请参阅委派给子智能体。要设置顾问,请参阅为会话配置顾问。以下智能体允许工作流使用您创建的一个智能体,列出了两个子智能体,并配置了一个顾问:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "workflows": {
      "type": "enabled",
      "predefined_agents": [{ "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h" }]
    },
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

每项设置都可以单独启用或禁用:

设置启用的功能智能体所在位置默认值
workflows动态工作流workflows.predefined_agents,最多 20 个启用
subagents委派给子智能体:您列出的智能体,以及智能体自行定义的智能体subagents.predefined_agents,最多 20 个启用
advisor顾问模型无。设置 model。禁用

关于每个列表中应包含的内容,以及如何仅允许您列出的智能体,请参阅预定义智能体和内联智能体。

请注意以下几点:

  • 更新: 保持 multiagent_20261001 类型的更新只会更改其发送的内容:
    • 您省略的设置或字段会保留其已存储的值。
    • 您以 null 发送的设置或字段会采用其默认值,其内部的所有内容也是如此,无论您之前存储了什么。
    • 您发送的 predefined_agents 列表会替换已存储的列表。
    • 您以不同 type 发送的设置会替换已存储的设置,您在其中省略的字段会采用其默认值。
    • 您发送的每个对象都需要包含其 type,已启用的 advisor 需要包含其 model。
  • 关闭: 将 workflows 设置为 {"type": "disabled"}。它会保持关闭状态,直到某次更新再次将其启用。发送 null 会将其启用,因为其默认值为启用。subagents 同理。
  • 现有会话: 会话在创建时会复制该设置,因此之后更改智能体不会影响已存在的会话。
  • 可列出的智能体: 设置了 multiagent 的智能体不能被列为另一个智能体的子智能体,也不能列在另一个智能体的 workflows 的 predefined_agents 列表中。智能体可以使用 {"type": "self"} 在任一列表中列出自身,读取时会显示为其自身的 id 和 version。
  • 工具名称: ant__ 前缀为保留前缀。如果您的智能体已有名称以 ant__ 开头的自定义工具,更新将失败并返回 400 错误,直到您发送不含该名称的 tools。如果新会话的智能体或任一列表中的智能体拥有此类工具,该会话也会被拒绝并返回 400 错误。请在开启动态工作流的同一次更新中重命名或移除该工具。请参阅自定义工具。
  • 预算: 在创建会话时设置会话预算,以限制会话的支出(包括运行);您无法为现有会话添加预算。当会话达到预算时,运行会暂停;当您提高或移除预算时,因预算而暂停的运行会恢复,除非它们同时也因中断而暂停。请参阅成本和预算。

告诉智能体何时使用运行

开启动态工作流后,智能体便能够启动工作流运行。由智能体决定何时启动运行。为了引导这一选择,请在智能体的系统提示中添加类似以下的指令。开启动态工作流中的合同审查智能体使用的就是此系统提示:

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

要对其进行调整,请列出您的智能体所在领域中需要运行的任务,以及智能体应自行完成的小任务。您还可以引导运行如何完成工作,如以下示例所示:

  • 如何拆分工作: "在运行中,每份合同使用一个智能体。然后让第二个智能体审查每一份合同,而不仅仅是第一个智能体发现问题的合同,并查找第一个智能体遗漏的内容。任何未通过审查的内容都要重做并再次审查。"
  • 智能体失败时怎么办: "一个智能体失败不得导致整个运行失败。如果某个智能体未能读取某份合同,请将该合同列为未覆盖。运行结束时,告诉我哪些合同未被覆盖。"
  • 时间限制: "为运行设置一小时的时间限制。"
  • 先做计划: "在启动运行之前,描述其各个阶段以及每个阶段运行多少个智能体。然后等待我的批准。"运行启动前没有审批步骤,因此没有任何机制强制执行这一点。

请仅在需要时使用运行,因为运行中的每个智能体都会消耗令牌。

然后像使用任何智能体一样,使用该智能体创建会话,并在 user.message 中描述工作。您也可以在该消息中请求启动运行。

关于运行的事件、在有运行处于打开状态时中断会话、运行打开期间会发生哪些变化,以及预算和限制,请参阅工作流运行。

为会话配置顾问

智能体的 multiagent 块中已启用的 advisor 设置会为会话的主线程提供一个 advisor(顾问):主线程可以在轮次中途咨询该模型以获取战略性指导,例如规划方法、摆脱困境或在完成前审查工作。该设置默认处于禁用状态。要启用它,请将 advisor 设置为 {"type": "enabled", "model": "..."},它恰好有两个字段:type 和 model:

ant apply backend-engineer.md
backend-engineer.md
---
name: Backend engineer
model: claude-sonnet-5
multiagent:
  type: multiagent_20261001
  advisor:
    type: enabled
    model: claude-opus-5-5
---

You implement backend features end to end. Consult the advisor before major backend design decisions.

此示例仅设置了 advisor。另外两项设置 subagents 和 workflows 保持默认值,因此两者均已启用,智能体还可以委派给内联智能体并启动工作流运行。如果希望智能体咨询顾问并自行完成所有工作,请将两者都设置为 {"type": "disabled"}。

您不能在 subagents 或 workflows 的 predefined_agents 列表中列出顾问。已启用的 advisor 会保留名称 anthropic.advisor。在其启用期间,两个列表都不能包含名称恰好为 anthropic.advisor 的智能体:此类请求会被拒绝并返回 400 验证错误。

顾问模型必须达到最低能力标准,且智能体自身的模型能力不得高于其顾问;能力相当的模型可以配对。无效的配对会在保存智能体时被拒绝并返回 400 验证错误,在创建会话时也会再次被拒绝。每次咨询开始时也会检查配对:如果配对已不再有效,该次咨询会失败,而会话会继续进行。有效的配对遵循顾问工具的模型兼容性表。

顾问也可作为 Messages API 上的服务器工具使用。Managed Agents 中的顾问在配置和交付方式上有所不同:advisor 设置没有 max_uses、max_tokens 或 caching 字段,且建议通过线程事件而非 advisor_tool_result 块送达。

咨询的工作原理

每次咨询都作为一个由平台生成、名为 anthropic.advisor 的线程运行,该线程在咨询完成时自行终止,建议会以 agent.thread_message_received 事件的形式送达主线程。咨询会发出标准的线程事件,并以保留名称 anthropic.advisor 标识(线程生命周期事件将其作为 agent_name 携带,建议送达事件将其作为 from_agent_name 携带),通常按以下顺序:

  1. session.thread_created
  2. session.thread_status_running
  3. agent.thread_message_received(建议)
  4. session.thread_status_idle(stop_reason: end_turn)
  5. session.thread_status_terminated

咨询不会发出 agent.tool_use 事件,会话的事件流中也不会出现 agent.thread_message_sent 事件,因为咨询输入是由平台组合的,而不是由智能体发送的。如果您列出顾问线程自身的事件,建议也会以 agent.thread_message_sent 事件的形式出现在其中。建议传递(事件 3)不保证在顾问线程的空闲和终止事件之前到达,因此不要将这些事件视为建议已送达的信号。

您的客户端能否读取建议取决于顾问模型的策略。这与 Messages API 顾问工具上的结果变体划分一致。在那里返回明文结果的顾问模型,在这里会交付可读文本。返回已编辑结果的顾问模型会在每个客户端界面上交付 [{"type": "redacted"}] 占位符,而智能体仍会在服务器端读取完整建议。前面的示例使用您可用的最新 Opus 模型作为顾问。Claude Opus 5.5 返回已编辑结果,因此您的客户端只能看到占位符。要在事件流中读取建议,请使用返回明文的顾问,例如 Claude Opus 4.8。模型的策略可能会在 API 不变的情况下发生变化,因此请同时处理 text 和 redacted 块。某些智能体模型只能与返回已编辑结果的顾问配对;请参阅顾问工具的兼容性表。顾问的思考过程永远不会公开。客户端不能自行发送 redacted 块;包含此类块的事件会被拒绝并返回 400 验证错误。

失败或被中断的咨询永远不会导致智能体的轮次失败:智能体会在收到咨询失败的通用通知后继续。在咨询期间发送会话级别的 user.interrupt 会终止顾问线程,且不会交付任何建议;带有顾问线程 session_thread_id 的 user.interrupt 只会放弃该次咨询。

顾问线程

顾问不是子智能体。智能体的 list_agents 工具不会显示它,用于向子智能体发送后续消息的 send_to_agent 也无法触达它。只有会话的主线程可以咨询它;子智能体不能。

顾问线程不受 25 个子线程的限制。它们会出现在会话的线程列表中。它们的 agent 为顾问形式 {"type": "advisor", "model": ...},其中包含您配置的模型,它们的 parent_thread_id 为主线程。

顾问端的提示缓存是自动的,无需任何配置。咨询按顾问模型的费率计费,其令牌会显示在顾问线程的用量和会话的用量总计中。它们还会按顾问模型的标价计入会话预算。每次咨询都会将主线程截至当时的对话发送给顾问,因此在长会话后期进行的咨询会使用更多输入令牌。

移除顾问

要移除顾问,请更新智能体,将 advisor 设置为 {"type": "disabled"}。对于已具有 multiagent_20261001 类型的智能体,更新中省略的设置会保留其已存储的值,因此您无需再次发送 subagents 或 workflows。出于同样的原因,省略 advisor 的更新会保留顾问。在更改现有智能体的 multiagent.type 之前,请参阅如何将智能体迁移到此类型。

从 coordinator 类型迁移

与 multiagent_20261001 一样,coordinator 类型允许智能体委派给您列出的子智能体并咨询顾问模型。使用 coordinator 类型时,智能体无法启动工作流运行,也无法自行定义子智能体。API 接受这两种类型。

要将智能体迁移到 multiagent_20261001,请使用该类型的 multiagent 块更新智能体:

  1. 将 type 设置为 "multiagent_20261001"。
  2. 在 subagents.predefined_agents 中列出智能体可以调用的智能体。这些条目保持其现有形式。
  3. 如果智能体有顾问,请将 advisor 设置为 {"type": "enabled", "model": "..."},并填入顾问的模型。
  4. 在一次更新中发送整个块。

例如,以下块为智能体提供了两个子智能体和一个顾问:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

该块省略了 workflows 和 subagents.inline_agents,因此两者都采用其默认值并处于启用状态。迁移后的智能体还可以启动工作流运行并自行定义子智能体。要保持其中任一项关闭,请在同一次更新中将其设置为 {"type": "disabled"}。请参阅开启动态工作流和预定义智能体和内联智能体。

如果智能体有顾问但没有子智能体,请将 subagents 设置为 {"type": "disabled"} 以保持委派关闭。禁用 subagents.inline_agents 且未列出任何智能体的请求会失败并返回 400 错误。

该更新会替换整个 multiagent 块,因此请像示例中那样再次发送智能体列表和顾问。您省略的内容会采用其默认值:

  • subagents.predefined_agents: 列表为空,因此智能体会失去您列出的子智能体。
  • advisor: 顾问被禁用。

一旦智能体具有 multiagent_20261001 类型,后续更新中省略的设置会保留其已存储的值。

该更新不会更改已存在的会话。要使用新块,请在更新后创建会话。

Was this page helpful?