文档中心

火山方舟

高级能力

编排 Multi Agent

当一次任务需要代码审查、测试设计等不同角色共同完成时，可以使用 Multi Agent。主 Agent（Main Agent）负责拆分任务、选择子 Agent（Subagent），并把各角色的结果汇总成最终答复。

本文以评审一个 Python 登录接口为例。你将为主 Agent 配置代码审查员和测试工程师两个固定成员，再创建 Session、提交评审任务，并通过 Thread 查看各成员的执行过程。开始前，准备 API Key、模型 ID、一个可用的 Environment，以及两个成员 Agent 的 ID 和版本号。

选择协作模式

方舟支持 multiagent_20261001 和 coordinator 两种 Multi Agent 配置。先根据任务是否需要持续协作、跨层派发和运行时角色选择配置，再准备子 Agent。

对比项	multiagent_20261001	coordinator
成员字段	subagents	agents
成员来源	预定义 Agent、Self 和 Inline Agent	预定义 Agent 和 Self
将使用 multiagent_20261001 的 Agent 作为预定义成员	支持	不支持
委派方式	目标 Thread 接受任务后，派发方继续执行	委派方等待子 Agent 执行结束
结果返回	结果异步回投给创建目标 Thread 的父 Thread	结果作为本次委派的工具结果返回
Thread 生命周期	Thread 保留在当前 Session 中，可以继续接收任务	每次委派创建一次性 Thread，委派结束后不再复用
子 Agent 层级	最多 3 层	最多 1 层

multiagent_20261001 模式

multiagent_20261001 适合多个角色在独立 Thread 中持续协作，或需要子 Agent 继续派生和派发任务的场景。它遵循以下规则：

子 Agent Thread 创建后会保留在当前 Session 中，可以继续接收任务，也可以单独中断或归档。

目标 Thread 接受任务后，派发方可以继续处理自己的工作，不需要等待。

一个 Agent 可以向同一 Session 中已有的其他子 Agent Thread 派发任务，包括同层或不同层的 Thread。派发方不会直接收到目标 Thread 的执行结果。

子 Agent 的结果始终异步回投给创建它的父 Thread，而不是最近一次派发任务的 Thread。父 Thread 处于 idle 时，结果会唤醒它；父 Thread 仍在运行时，结果会排队等待处理。

只要还有 Thread 正在运行，Session 就会保持 running。所有 Thread 都不再运行后，Session 才会进入 idle；此时仍需根据 stop_reason 判断任务已经结束，还是正在等待外部操作。

主 Agent、子 Agent A、孙 Agent A1 和子 Agent B 之间异步派发任务，结果沿父子关系向上回投

coordinator 模式

coordinator 适合由主 Agent 依次调用固定成员、并在每次调用中直接等待结果的任务。它遵循以下规则：

每次委派创建一个一次性子 Thread。

主 Agent 会等待子 Agent 完成任务，收到结果后再继续处理。

子 Agent 的最终输出作为本次委派的工具结果返回给委派方。

委派完成后，一次性子 Thread 变为 idle，仍可通过线程接口查询。

coordinator 模式下，主 Agent 依次等待子 Agent A 和 B 完成任务，结果作为当前委派结果返回，一次性子 Thread 随后变为 idle

本文后续以 multiagent_20261001 为例，介绍子 Agent 来源、配置和 Session 管理。若现有 Agent 使用 coordinator，迁移限制参见从 coordinator 迁移。

使用场景

multiagent_20261001 支持三种子 Agent 来源。你可以根据角色是否固定、是否需要复用，以及是否要在任务运行时创建临时角色进行选择：

来源	说明	适用场景	配置方式
预定义 Agent	提前创建并可以锁定版本的 Agent	角色和能力已经稳定，需要在多次任务中复用	在 predefined_agents 中引用已有 Agent
Self	复用当前 Agent 的模型和能力，但单独保存对话上下文	需要并行处理多个同类子任务	在 predefined_agents 中加入 {"type":"self"}
Inline Agent	由主 Agent 在任务运行时定义的临时角色，不创建 Agent 资源	事先无法确定角色或分工	将 inline_agents.type 设为 enabled

三种来源可以同时使用。API 请求中，multiagent.type 设为 multiagent_20261001，并在 multiagent.subagents 中配置这些来源。

Self 只复用当前 Agent 的模型、系统提示词和能力，不会复制其预定义成员列表。Inline Agent 也不会获得创建它的 Agent 的成员列表。

配置主 Agent

准备成员和委派规则

使用已有 Agent 作为固定成员时，先创建成员并记录 Agent ID 和版本号。详情请参见 Agent。

以下示例使用两个固定成员：

角色	职责
代码审查员	检查代码质量、架构和安全风险，输出问题与修改建议
测试工程师	设计测试用例，说明覆盖范围和未覆盖风险

配置本地环境变量：

Self 和 Inline Agent 都不需要提前创建 Agent 资源。主 Agent 选择 Self 后，系统会创建一个新的子 Agent Thread。它使用主 Agent 在本次 Session 中的模型、系统提示词、工具、MCP 和技能，但会单独保存对话上下文。Inline Agent 则由主 Agent 在任务运行时定义角色和系统提示词，并使用独立 Thread。

主 Agent 的系统提示词需要回答三个问题：

每个固定成员负责什么。

什么情况下创建 Self 或 Inline Agent。

收到成员结果后如何汇总并回复。

固定成员的名称和职责需要与配置一致。名称相似或职责重叠时，主 Agent 更容易选错成员。

如果允许主 Agent 创建 Inline Agent，还需要明确以下边界：

Inline Agent 使用创建它的 Agent 的模型、工具、MCP 和技能。创建时不能单独增加或减少这些能力。

委派内容需要包含职责、必要背景、预期产物和文件责任。

大段中间产物写入共享文件系统，消息只传递文件路径和结论摘要。

用户只与主 Agent 交互，子 Agent 的结果由主 Agent 统一汇总。

以下提示词片段可以作为起点：

创建主 Agent

以下 cURL 使用两个预定义 Agent、一个 Self 和已启用的 Inline Agent 创建主 Agent，并锁定预定义 Agent 的版本：

cURL

脚本将主 Agent ID 和版本号写入 COORDINATOR_AGENT_ID 和 COORDINATOR_AGENT_VERSION。确认这两个变量均不为空后，再创建 Session。字段说明参见创建智能体。

脚本提交的核心配置如下：

subagents 决定主 Agent 能否创建子 Agent，以及可以使用哪些子 Agent 来源：

subagents.type 设为 disabled 时，主 Agent 不派生子 Agent。

inline_agents.type 设为 disabled 时，主 Agent 只能从 predefined_agents 中选择成员。

没有预定义成员时，传入 predefined_agents: []。

注意

当 subagents.type 为 enabled 时，省略 inline_agents 表示允许创建 Inline Agent。若要禁止任务运行时创建临时角色，必须显式传入 "inline_agents": {"type": "disabled"}。

子 Agent 使用哪些配置

创建 Session 后，三类子 Agent 按以下规则确定模型和能力配置：

来源	使用的配置	后续更新的影响
预定义 Agent	使用创建 Session 时记录的成员 Agent 配置，包括模型、系统提示词、工具、MCP 和技能	之后更新成员 Agent，不会改变当前 Session
Self	使用主 Agent 在本次 Session 中的模型、系统提示词、工具、MCP 和技能	如果创建 Session 时临时修改了主 Agent 配置，Self 也使用修改后的值
Inline Agent	运行时定义名称和系统提示词，模型、工具、MCP 和技能与创建它的 Agent 相同	不创建独立 Agent 资源，能力也不能在创建时单独调整

同一 Session 中的子 Agent 共享 Environment、Sandbox、文件系统和已绑定的 Vault 凭据，但不会自动共享对话历史。因此，创建 Session 时就需要确定 Environment 和需要挂载的 Vault 凭据。

注意

共享文件系统不等于共享上下文。一个 Thread 写入文件后，其他 Thread 可以读取该文件，但主 Agent 不会自动获得写入过程和结论。子 Agent 需要显式回传文件路径和摘要。

配置限制

固定成员列表最多包含 20 项。

同一 Session 默认最多包含 20 个 Thread，包括 Main Thread；账号和项目可以配置其他上限。

使用 multiagent_20261001 时，一个 Session 最多派生 3 层子 Agent，包括预定义 Agent、Self 和 Inline Agent。

更新主 Agent 不会修改已有 Session 正在使用的配置。

主 Agent 和子 Agent 分别产生模型与运行资源用量，详情参见模型价格。

更新并检查配置

需要新增、移除预定义成员或切换成员版本时，先调用查询智能体详情查询主 Agent。更新请求必须携带返回的 version，以免覆盖其他更新。以下示例整体提交 predefined_agents 和匹配的系统提示词。

创建脚本已导出 COORDINATOR_SYSTEM。更新前，确认该变量保存的是主 Agent 当前使用的完整系统提示词。

cURL

脚本将新版本号写入 COORDINATOR_AGENT_VERSION。接口返回 version: conflict 时，重新查询最新版本，合并配置后再提交。

更新语义

请求写法	更新结果
省略顶层 multiagent	保留完整的 Multi Agent 配置
传入 multiagent: null	删除 Multi Agent 配置，改为单 Agent
省略 multiagent.subagents.predefined_agents	保留当前预定义成员列表
传入 multiagent.subagents.predefined_agents: []	清空预定义成员列表
将 subagents.type 或 inline_agents.type 设为 disabled	分别禁止创建子 Agent 或 Inline Agent

从 coordinator 迁移

coordinator 使用 agents 配置成员，multiagent_20261001 使用 subagents。迁移时需要提交完整的 subagents 配置，原有 agents 不会自动转换。

切换配置时遵循以下规则：

单 Agent 或使用 coordinator 的 Agent 可以切换为 multiagent_20261001。请求中需要提交完整的 subagents 配置。

使用 multiagent_20261001 后不能切换回 coordinator。如需改为单 Agent，传入 multiagent: null 清空配置。

更新 Agent 只生成新版本，不会改变已有 Session。需要让已有 Session 使用新配置时，参见升级 Session 配置。

创建或更新完成后，调用查询智能体详情检查以下内容：

version 是本次保存产生的新版本。

multiagent.type 为 multiagent_20261001。

multiagent.subagents.type 为 enabled。

multiagent.subagents.predefined_agents 包含预期的预定义 Agent 和 Self。

multiagent.subagents.inline_agents.type 与是否允许动态角色一致。

固定成员的 id 和 version 与计划一致。

系统提示词中的角色名称与成员职责一致。

按最小权限原则，只为主 Agent 和成员 Agent 配置任务必需的工具、MCP 和技能。

Inline Agent 不创建独立 Agent 资源，因此不会出现在 Agent 列表中。任务运行时，系统会为该临时角色创建独立 Thread。

运行 Session

完成配置后，创建一个 Session，并把任务发送给主 Agent。无论主 Agent 选择预定义 Agent、Self 还是 Inline Agent，都使用相同的 Session 和 Thread 接口观察执行过程、处理工具结果或中断任务。

开始前，创建或复用 Environment，并记录 Environment ID。详情参见配置云环境。

配置运行所需环境变量：

示例脚本沿用 COORDINATOR_AGENT_ID 变量名表示承担协调职责的主 Agent。

创建 Session

一个 Session 承载一次多智能体任务。主 Agent 和每个子 Agent 分别使用独立的 Thread：

每个 Thread 都有稳定的 session_thread_id，并独立保存消息和推理上下文。parent_thread_id 记录创建关系：Main Thread 返回 null，子 Agent Thread 返回创建它的父 Thread ID。

同一 Session 中的 Thread 共享 Environment、Sandbox、文件系统和已绑定的 Vault 凭据，但不会自动共享对话历史。一个 Thread 写入文件后，其他 Thread 可以读取该文件；需要同时传递结论时，子 Agent 还应回传文件路径和摘要。

说明

预定义 Agent、Self 和 Inline Agent 只影响子 Agent 的配置来源。任务运行时，三类子 Agent 都在当前 Session 中使用独立 Thread，并通过同一组 Session 和 Thread API 管理。Inline Agent 是当前 Session 内的临时角色，不会创建 Agent 资源或新的 Session。

主流程使用两个终端。终端 A 接收 Session 事件流，终端 B 创建 Session、发送任务和查询结果。需要实时查看某个 Thread 的完整过程时，再打开终端 C。

在终端 B 创建 Session：

cURL

脚本将 Session ID 写入 SESSION_ID。确认该变量不为空后，再订阅事件流。此时只会创建 Main Thread。主 Agent 首次委派任务时，系统才会创建对应的子 Agent Thread。Session 会记录创建时使用的主 Agent 配置和运行限制，之后更新 Agent 不会影响这个 Session。

提交并观察任务

订阅 Session 事件

在终端 A 配置同一个 Session ID：

建立 Session 事件流：

cURL

终端 A 输出 : ready 后保持连接，再发送任务。通过 Session 事件流可以看到：

Session 的整体状态。

Thread 的创建、运行、空闲、重新调度和终止。

Thread 之间用于委派、汇报和补充要求的协作消息。

子 Agent 发起的自定义工具调用和需要客户端处理的工具授权事件。

自托管 Environment 中需要 Worker 执行的内置工具调用。

需要查看某个子 Agent 的思考、回复、工具结果、Span 或预览帧时，查询对应的 Thread 事件。

提交任务

用户消息统一发送给主 Agent。主 Agent 根据任务需要选择预定义 Agent、Self 或 Inline Agent：

cURL

使用 multiagent_20261001 时，任务投递成功只表示目标 Thread 已接收任务，不表示子 Agent 已完成。主 Agent 可以继续处理其他工作，子 Agent 的结果会在执行结束后异步返回。

主 Agent 首次向某个成员派发任务时，Session 事件流会出现 session.thread_created。需要补充要求时，可以继续使用原 Thread，不必重新创建上下文。

查看 Thread

在终端 B 列出当前 Session 的全部 Thread：

cURL

脚本将第一个子 Agent 的 Thread ID 写入 SESSION_THREAD_ID。检查其他 Thread 时，更新该变量，并在查询历史前清空分页标识：

查询该 Thread 的完整历史：

cURL

如果 Next page 不为空，保持 THREAD_EVENTS_PAGE 并重复执行，直到下一页标识为空。切换 Thread 前再次清空该变量。

查询 Thread 详情或列表时，stats 返回运行时长，usage 返回该 Thread 累计的模型 token、缓存和服务端工具用量。

需要实时查看该 Thread 时，在终端 C 建立事件流：

cURL

Thread 事件流输出 : ready 后，再补查一次历史。按事件 id 合并实时与历史结果，并忽略重复事件。Session 和 Thread 事件流中的消息到达顺序可能不同。可以通过 session_thread_id、from_session_thread_id 和 to_session_thread_id 找到一次委派及其返回结果。

判断本轮是否完成

正常事件轨迹如下：

只有同时满足以下条件，本轮任务才成功：

Main Thread 产生最终 agent.message。

Session 以 stop_reason.type=end_turn 进入 idle。

没有 Thread 停留在 running 或 rescheduling。

本轮没有出现需要处理的终止或错误事件。

注意

HTTP 200 只表示服务端已受理事件。session.status_idle 也不一定表示任务成功，仍需检查 stop_reason 和各 Thread 的状态。

管理 Session

继续委派和处理等待操作

Session 以 end_turn 结束后，可以继续向同一 Session 发送新的 user.message。消息仍发送给主 Agent。在任务中说明要继续处理的角色、已有结果和新增要求，主 Agent 可以复用原 Thread，也可以创建新的 Thread。

使用 multiagent_20261001 时，可以复用已有子 Agent Thread。任务接受、结果回投和父 Thread 唤醒规则参见选择协作模式。

同一个任务建议始终使用同一个 Session，以保留上下文。需要隔离新任务、变更 Environment，或让所有 Thread 统一使用一套新配置时，再创建新 Session。

Thread 状态

状态	含义
running	Thread 正在处理当前工作
idle	当前工作已暂停或结束，可以继续派发任务
rescheduling	Thread 正在从临时错误中自动恢复
archived	会话归档后子线程进入该状态，不能再接收任务，但仍可查询
terminated	线程已终止，不能再接收任何输入；历史协作模式的会话按事件还原线程时会出现
unknown	暂时无法判断 Thread 状态，需要继续查询后续事件

中断只结束当前执行。中断完成后，Thread 可以继续接收任务。

处理等待操作

Thread 等待工具确认或外部工具结果时，Session 会以 requires_action 进入 idle：

保持 Session 和目标 Thread 的事件流连接。如果连接已关闭，先重新建连并等待 : ready。

清空分页标识，并补查 Session 历史：

unset SESSION_EVENTS_PAGE

cURL

: "\\${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "\\${ARK_API_KEY:?Set ARK_API_KEY}"
: "\\${SESSION_ID:?Set SESSION_ID}"

request_args=(
--get
"$ARK_BASE_URL/sessions/$SESSION_ID/events"
--data-urlencode "limit=100"
--data-urlencode "order=asc"
)

if [[ -n \\${SESSION_EVENTS_PAGE:-} ]]; then
request_args+=(--data-urlencode "page=$SESSION_EVENTS_PAGE")
fi

if ! events=$(
curl -sS --fail-with-body \
"\\${request_args[@]}" \
-H "Authorization: Bearer $ARK_API_KEY"
); then
return 1 2>/dev/null || exit 1
fi

printf 'Events:\n'
jq -c '.data[]' <<<"$events"

export SESSION_EVENTS_PAGE
SESSION_EVENTS_PAGE=$(jq -r '.next_page // empty' <<<"$events")
printf 'Next page: %s\n' "$SESSION_EVENTS_PAGE"

从 session.thread_status_idle 中记录 session_thread_id 和全部 stop_reason.event_ids，再到对应 Thread 历史中找到这些事件。

对 agent.tool_use 或 agent.mcp_tool_use，设置要确认的 Thread ID 和工具调用 ID：

export SESSION_THREAD_ID="<SESSION_THREAD_ID>"
export TOOL_USE_ID="<TOOL_USE_ID>"

cURL

: "\\${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "\\${ARK_API_KEY:?Set ARK_API_KEY}"
: "\\${SESSION_ID:?Set SESSION_ID}"
: "\\${SESSION_THREAD_ID:?Set SESSION_THREAD_ID}"
: "\\${TOOL_USE_ID:?Set TOOL_USE_ID}"

payload=$(
jq -n \
--arg thread_id "$SESSION_THREAD_ID" \
--arg tool_use_id "$TOOL_USE_ID" \
'{
events: [{
type: "user.tool_confirmation",
session_thread_id: $thread_id,
tool_use_id: $tool_use_id,
result: "allow"
}]
}'
)

curl -sS --fail-with-body \
"$ARK_BASE_URL/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d "$payload"

对 agent.custom_tool_use，在你的应用中执行对应工具，再发送 user.custom_tool_result。请求必须携带 custom_tool_use_id。详情参见 Tools。

处理全部 event_ids 后继续观察。任务可能再次进入 requires_action；只有 Session 最终以 end_turn 结束，本轮任务才完成。

工具确认和工具结果必须携带原始调用 ID。发送新的 user.message 不能解除 requires_action。

中断 Thread 和升级 Session

中断 Thread

只中断一个 Thread 时，设置 SESSION_THREAD_ID；中断 Session 中的全部活跃 Thread 时，省略该变量：

cURL

中断不会回滚已经写入共享文件系统的内容，也不会删除 Thread。中断指定 Thread 后，等待该 Thread 进入 idle。中断全部 Thread 后，等待 Session 进入 idle。

升级 Session 配置

更新主 Agent 后，已有 Session 不会自动使用新配置。只有同时满足以下条件时，才升级 Session：

Session 当前为 idle，且上一轮以 end_turn 结束。

所有 Thread 都已结束当前工作。

没有等待处理的工具授权、工具结果，也没有子 Agent 等待其他 Thread 的回复。

当前没有其他升级请求。

注意

升级方向需要符合以下规则：

使用单 Agent 或 coordinator 的 Session 可以升级到 multiagent_20261001。

已使用 multiagent_20261001 的 Session 可以继续升级到该类型的新版本。

如需改回单 Agent，先将主 Agent 的 multiagent 设为 null，再把 Session 升级到这个新版本。

使用 multiagent_20261001 后，不能切回 coordinator。

设置更新主 Agent 后得到的版本号，然后创建升级任务：

cURL

等待 Session 使用目标版本恢复为 idle：

cURL

脚本默认每 2 秒查询一次，最多 60 次。只有状态为 idle，且 agent.id 和 agent.version 与目标一致时才返回成功。

升级完成后，新建的 Thread 使用升级后的配置，已经存在的 Thread 保留创建时的配置。如果升级超时、进入失败状态或需要所有 Thread 统一切换配置，请创建新 Session。

限制与排障

信号	含义	处理动作
SSE 连接中断	中断期间的事件不会自动推送到当前连接	先重建连接，再查询历史并按事件 ID 去重
requires_action	等待工具确认或外部工具结果	处理全部 stop_reason.event_ids
session.thread_status_rescheduled	Thread 正在从临时错误中自动恢复	继续等待自动恢复，不要同时发起手动重试
session.thread_status_terminated	Thread 已终止	查询 Thread 历史和错误事件，Session 空闲后重新派发任务
Thread 长时间保持 running	当前执行未结束	携带 session_thread_id 发送 user.interrupt
retries_exhausted	当前轮次重试次数已用尽	调整输入后重试；需要修改 Agent 配置时，更新后升级或新建 Session
InternalServiceError.MultiagentPolicyUnavailable	Multi Agent 策略暂时不可用	保持请求参数不变，稍后重试

使用自托管 Environment 时，不需要为每个子 Agent 单独配置工具执行能力。Worker 会监听 Session 事件流，接收主 Agent 和子 Agent 发起的内置工具调用，并按事件顺序执行。回传 user.tool_result 时必须携带 tool_use_id。详情参见 Tools。

运行限制

同一 Session 的 Thread 共享运行资源，但分别产生模型与运行资源用量。计费说明参见 Managed Agents。

如果进程故障发生在补充消息处理完成之前，恢复后先查询 Thread 历史和任务状态。只有确认消息尚未处理时，才重新发送。

清理资源

确认产物已转存后，使用精确 ID 删除本页创建的 Session。Session 仍在运行时，先中断全部 Thread 并等待 idle。默认保留主 Agent：

仅当主 Agent 不再被其他 Session 使用时，才将 DELETE_COORDINATOR 改为 yes：

cURL

命令不会删除成员 Agent 或 Environment。

警告

删除 Session 或 Agent 后无法恢复。只使用本页记录的精确 ID，不要按名称模糊匹配或批量删除共享资源。