Multi Agent（多智能体协作）允许协调器 Agent 将任务委派给多个子智能体。子智能体使用各自的模型、系统提示词、技能和工具完成任务。协调器负责拆分任务并汇总结果。

本页从已有子智能体和 Environment 开始，演示如何创建协调器、运行任务、验证结果和处理异常。

选择并准备

Multi Agent 适合需要角色分工或并行处理的复杂任务。如果任务不需要独立上下文或角色边界，优先使用更简单的方式。

任务特征	推荐方式	适用场景
多个角色需要使用不同提示词、模型或工具	Multi Agent	代码审查、测试设计等多角色任务
单个 Agent 按固定步骤调用工具	Agent + 工具（Tools）	流程固定，不需要独立角色上下文
单个 Agent 复用操作说明	Agent + 技能（Skills）	需要沉淀流程，但不需要角色协作

开始前，完成以下准备：

创建 API Key，并配置为 ARK_API_KEY。详情请参见 API Key 管理。

创建两个子智能体，并记录 Agent ID 和版本号。详情请参见 Agent。

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

选择协调器模型，并确认本地已安装 curl 和 jq。

配置环境变量：

配置协调器

定义角色和委派规则

协调器的系统提示词需要说明每个子智能体的职责和输出。角色边界越明确，协调器越容易正确分配任务。

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

系统提示词还需要要求协调器先拆分和委派任务，收到全部结果后再汇总。下方 cURL 包含完整提示词。

创建协调器

在 multiagent.agents 中传入子智能体 ID 和版本号。显式填写版本后，子智能体发布新版本不会改变当前协调器。

cURL

脚本将协调器 ID 和版本号写入 COORDINATOR_AGENT_ID 和 COORDINATOR_AGENT_VERSION。字段说明请参见创建智能体。

也可以通过控制台配置：

进入 Agent 管理页面。

创建或编辑 Agent，在 04 能力扩展区域添加 Multi Agents。

选择子智能体，填写前面的系统提示词并保存。

记录协调器 Agent ID 和版本号。

运行任务

主流程使用两个终端。终端 A 接收主事件流，终端 B 创建 Session、发送任务和查询结果。需要实时观察子线程时，再打开终端 C。

1. 创建 Session

在终端 B 创建 Session：

cURL

脚本将 Session ID 写入 SESSION_ID：

2. 订阅主事件流

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

建立主事件流：

cURL

终端 A 输出 : ready 后保持连接。先建连再发送任务，可以避免遗漏实时事件。

3. 发送任务

回到终端 B，配置任务内容：

发送任务：

cURL

实时观察子线程（可选）

只在需要实时观察子智能体时执行以下步骤：

终端 A 收到 session.thread_created 后，记录 session_thread_id。

在终端 C 配置鉴权信息、Session ID 和子线程 ID：

export ARK_API_KEY="<ARK_API_KEY>"
export ARK_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export SESSION_ID="<SESSION_ID>"
export SESSION_THREAD_ID="<SESSION_THREAD_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}"

curl -sS -N --fail-with-body --max-time 600 \
"$ARK_BASE_URL/sessions/$SESSION_ID/threads/$SESSION_THREAD_ID/stream" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Accept: text/event-stream"

终端 C 输出 : ready 后，在终端 B 按“验证结果”中的方式补查该子线程历史。

按事件 id 合并实时和历史事件，忽略重复 ID。

每个子线程使用独立事件流。出现多个 session_thread_id 时，分别重复以上步骤。

4. 等待本轮结束

继续观察终端 A。正常事件轨迹如下：

收到 session.status_idle 后检查 stop_reason.type：

end_turn：本轮执行结束，按下一节验证结果。

requires_action：保持连接，处理全部待操作事件后继续观察。

retries_exhausted：调整输入后可以发送新任务；如果修改 Agent 配置，请创建新 Session。

验证结果

在终端 B 列出全部线程：

cURL

命令将第一个子线程 ID 写入 SESSION_THREAD_ID。检查其他子线程时，更新该变量并清空分页标识：

查询该子线程的完整历史：

cURL

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

主线程和各子线程使用独立事件流，不能根据跨流到达顺序判断执行顺序。使用 session_thread_id、from_session_thread_id 和 to_session_thread_id 关联委派与返回消息。

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

主线程产生最终 agent.message。

Session 以 stop_reason.type=end_turn 进入 idle。

没有子线程停留在 running 或 rescheduling。

本轮没有出现 session.thread_status_terminated。

处理异常状态

信号	含义	处理动作
SSE 连接中断	中断期间的事件不会自动回放	先重建连接，再查询历史并按事件 ID 去重
requires_action	等待工具确认或外部工具结果	处理全部 stop_reason.event_ids
session.thread_status_rescheduled	子线程正在自动重新调度	保持监听，不要并行手动重试
session.thread_status_terminated	子线程已终止	查询历史和错误事件，Session 空闲后重新分配任务
子线程长时间保持 running	子任务未结束	携带 session_thread_id 发送 user.interrupt
retries_exhausted	当前轮次重试次数已用尽	调整输入后重试；修改 Agent 配置后创建新 Session

处理等待操作

子线程以 requires_action 进入 idle 后，按以下步骤处理：

保持主事件流和目标子线程事件流连接。如果连接已关闭，先重新建连并等待 : ready，再补查历史。补查主线程前清空分页标识：

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。按“验证结果”中的方式补查子线程，并逐一找到这些事件。

对 agent.tool_use 或 agent.mcp_tool_use，配置关联 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。请求需要携带当前 session_thread_id 和 custom_tool_use_id。详情请参见 Tools。

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

本页主流程使用云环境，不覆盖自托管 Environment 的 user.tool_result 流程。自托管流程请参见 Tools。

中断线程

只停止一个子线程时，运行 export SESSION_THREAD_ID="<SESSION_THREAD_ID>"。停止全部活跃线程时，运行 unset SESSION_THREAD_ID。

cURL

中断指定子线程后等待该线程进入 idle；中断全部线程后等待 Session 进入 idle。

更新协作配置

新增、移除子智能体或切换版本时，先调用查询智能体详情查询协调器最新配置。更新请求需要携带当前 version，并整体提交匹配的系统提示词和 multiagent.agents。

通过 API 创建协调器时，创建脚本已导出 COORDINATOR_SYSTEM。如果通过控制台创建，请先将控制台使用的完整系统提示词配置到该变量。提示词必须与成员列表保持一致。

cURL

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

现有 Session 不会自动切换版本。只有 Session 处于 idle、上一轮以 end_turn 结束且没有其他升级请求时，才可以升级：

cURL

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

cURL

脚本默认每 2 秒查询一次，最多 60 次。只有状态为 idle，且 agent.id 和 agent.version 与目标一致时才返回成功；超时或进入失败状态时，请检查 Session 或创建新 Session。

使用限制

子智能体数量：单个协调器最多配置 20 个子智能体，详情请参见创建智能体。

委派层级：Multi Agent 只展开一层。multiagent.agents[].type 为 self 时复用协调器配置创建子线程，但不会继续复用协调器的 multiagent 列表。

版本快照：更新协调器不会修改已有 Session 的 Agent 快照。

资源消耗：协调器和子智能体分别产生模型与运行资源用量，详情请参见 Managed Agents 计费说明。

清理资源

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

仅当协调器不再被任何 Session 使用时，才将 DELETE_COORDINATOR 改为 yes。执行删除：

cURL

命令不会删除子智能体或 Environment。

火山方舟