当一次任务需要代码审查、测试设计等不同角色共同完成时,可以使用 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判断任务已经结束,还是正在等待外部操作。
coordinator 模式#
coordinator 适合由主 Agent 依次调用固定成员、并在每次调用中直接等待结果的任务。它遵循以下规则:
- 每次委派创建一个一次性子 Thread。
- 主 Agent 会等待子 Agent 完成任务,收到结果后再继续处理。
- 子 Agent 的最终输出作为本次委派的工具结果返回给委派方。
- 委派完成后,一次性子 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。
以下示例使用两个固定成员:
| 角色 | 职责 |
|---|---|
| 代码审查员 | 检查代码质量、架构和安全风险,输出问题与修改建议 |
| 测试工程师 | 设计测试用例,说明覆盖范围和未覆盖风险 |
配置本地环境变量:
export ARK_API_KEY="<ARK_API_KEY>"
export ARK_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export COORDINATOR_MODEL_ID="<MODEL_ID>"
export REVIEWER_AGENT_ID="<REVIEWER_AGENT_ID>"
export REVIEWER_AGENT_VERSION="<REVIEWER_AGENT_VERSION>"
export TESTER_AGENT_ID="<TESTER_AGENT_ID>"
export TESTER_AGENT_VERSION="<TESTER_AGENT_VERSION>"
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 统一汇总。
以下提示词片段可以作为起点:
你负责完成产品方案,并根据任务复杂度选择协作方式。
- 代码审查交给代码审查员。
- 测试设计交给测试工程师。
- 多个同类子任务可以创建 Self 并行处理。
- 无法预设的专业角色可以按需创建 Inline Agent。
委派时说明职责、背景、预期产物和文件路径。
收到全部必要结果后,汇总为一个最终答复。
创建主 Agent#
以下 cURL 使用两个预定义 Agent、一个 Self 和已启用的 Inline Agent 创建主 Agent,并锁定预定义 Agent 的版本:
: "${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "${ARK_API_KEY:?Set ARK_API_KEY}"
: "${COORDINATOR_MODEL_ID:?Set COORDINATOR_MODEL_ID}"
: "${REVIEWER_AGENT_ID:?Set REVIEWER_AGENT_ID}"
: "${REVIEWER_AGENT_VERSION:?Set REVIEWER_AGENT_VERSION}"
: "${TESTER_AGENT_ID:?Set TESTER_AGENT_ID}"
: "${TESTER_AGENT_VERSION:?Set TESTER_AGENT_VERSION}"
COORDINATOR_SYSTEM='你有以下团队成员:
【代码审查员】
- 检查代码质量、架构和安全风险。
- 输出问题列表、严重程度和修改建议。
- 不负责编写新功能。
【测试工程师】
- 设计测试用例并检查覆盖范围。
- 输出测试用例、覆盖范围和未覆盖风险。
- 不修改产品需求。
先拆分任务,再分别委派。收到全部结果后,汇总为最终结论。'
export COORDINATOR_SYSTEM
main_agent_payload=$(
jq -n \
--arg model_id "$COORDINATOR_MODEL_ID" \
--arg system "$COORDINATOR_SYSTEM" \
--arg reviewer_id "$REVIEWER_AGENT_ID" \
--argjson reviewer_version "$REVIEWER_AGENT_VERSION" \
--arg tester_id "$TESTER_AGENT_ID" \
--argjson tester_version "$TESTER_AGENT_VERSION" \
'{
name: "engineering-lead",
model: {id: $model_id},
system: $system,
multiagent: {
type: "multiagent_20261001",
subagents: {
type: "enabled",
inline_agents: {type: "enabled"},
predefined_agents: [
{type: "agent", id: $reviewer_id, version: $reviewer_version},
{type: "agent", id: $tester_id, version: $tester_version},
{type: "self"}
]
}
}
}'
)
main_agent=$(
curl -sS --fail-with-body "$ARK_BASE_URL/agents" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d "$main_agent_payload"
)
export COORDINATOR_AGENT_ID
export COORDINATOR_AGENT_VERSION
COORDINATOR_AGENT_ID=$(jq -er '.id' <<<"$main_agent")
COORDINATOR_AGENT_VERSION=$(jq -er '.version' <<<"$main_agent")
printf 'Main Agent ID: %s\n' "$COORDINATOR_AGENT_ID"
printf 'Main Agent version: %s\n' "$COORDINATOR_AGENT_VERSION"
脚本将主 Agent ID 和版本号写入 COORDINATOR_AGENT_ID 和 COORDINATOR_AGENT_VERSION。确认这两个变量均不为空后,再创建 Session。字段说明参见 创建智能体。
脚本提交的核心配置如下:
{
"type": "multiagent_20261001",
"subagents": {
"type": "enabled",
"inline_agents": {"type": "enabled"},
"predefined_agents": [
{"type": "agent", "id": "<AGENT_ID>", "version": 1},
{"type": "self"}
]
}
}
subagents 决定主 Agent 能否创建子 Agent,以及可以使用哪些子 Agent 来源:
subagents.type设为disabled时,主 Agent 不派生子 Agent。inline_agents.type设为disabled时,主 Agent 只能从predefined_agents中选择成员。- 没有预定义成员时,传入
predefined_agents: []。
子 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 凭据。
配置限制
- 固定成员列表最多包含 20 项。
- 同一 Session 默认最多包含 20 个 Thread,包括 Main Thread;账号和项目可以配置其他上限。
- 使用
multiagent_20261001时,一个 Session 最多派生 3 层子 Agent,包括预定义 Agent、Self 和 Inline Agent。 - 更新主 Agent 不会修改已有 Session 正在使用的配置。
- 主 Agent 和子 Agent 分别产生模型与运行资源用量,详情参见 模型价格。
更新并检查配置#
需要新增、移除预定义成员或切换成员版本时,先调用 查询智能体详情 查询主 Agent。更新请求必须携带返回的 version,以免覆盖其他更新。以下示例整体提交 predefined_agents 和匹配的系统提示词。
export COORDINATOR_AGENT_VERSION="<LATEST_VERSION>"
COORDINATOR_PREDEFINED_AGENTS_JSON=$(
jq -n \
--arg reviewer_id "$REVIEWER_AGENT_ID" \
--argjson reviewer_version "$REVIEWER_AGENT_VERSION" \
--arg tester_id "$TESTER_AGENT_ID" \
--argjson tester_version "$TESTER_AGENT_VERSION" \
'[
{type: "agent", id: $reviewer_id, version: $reviewer_version},
{type: "agent", id: $tester_id, version: $tester_version},
{type: "self"}
]'
)
export COORDINATOR_PREDEFINED_AGENTS_JSON
创建脚本已导出 COORDINATOR_SYSTEM。更新前,确认该变量保存的是主 Agent 当前使用的完整系统提示词。
: "${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "${ARK_API_KEY:?Set ARK_API_KEY}"
: "${COORDINATOR_AGENT_ID:?Set COORDINATOR_AGENT_ID}"
: "${COORDINATOR_AGENT_VERSION:?Set COORDINATOR_AGENT_VERSION}"
: "${COORDINATOR_SYSTEM:?Set COORDINATOR_SYSTEM}"
: "${COORDINATOR_PREDEFINED_AGENTS_JSON:?Set COORDINATOR_PREDEFINED_AGENTS_JSON}"
update_payload=$(
jq -n \
--argjson version "$COORDINATOR_AGENT_VERSION" \
--arg system "$COORDINATOR_SYSTEM" \
--argjson predefined_agents "$COORDINATOR_PREDEFINED_AGENTS_JSON" \
'{
version: $version,
system: $system,
multiagent: {
type: "multiagent_20261001",
subagents: {
type: "enabled",
inline_agents: {type: "enabled"},
predefined_agents: $predefined_agents
}
}
}'
)
main_agent=$(
curl -sS --fail-with-body \
"$ARK_BASE_URL/agents/$COORDINATOR_AGENT_ID" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d "$update_payload"
)
export COORDINATOR_AGENT_VERSION
COORDINATOR_AGENT_VERSION=$(jq -er '.version' <<<"$main_agent")
printf 'Main Agent version: %s\n' "$COORDINATOR_AGENT_VERSION"
脚本将新版本号写入 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。详情参见 配置云环境。
配置运行所需环境变量:
export ARK_API_KEY="<ARK_API_KEY>"
export ARK_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export COORDINATOR_AGENT_ID="<MAIN_AGENT_ID>"
export ENVIRONMENT_ID="<ENVIRONMENT_ID>"
示例脚本沿用 COORDINATOR_AGENT_ID 变量名表示承担协调职责的主 Agent。
创建 Session#
一个 Session 承载一次多智能体任务。主 Agent 和每个子 Agent 分别使用独立的 Thread:
Session
└── Main Thread
├── Thread A:预定义 Agent
├── Thread B:Self
└── Thread C:Inline Agent
每个 Thread 都有稳定的 session_thread_id,并独立保存消息和推理上下文。parent_thread_id 记录创建关系:Main Thread 返回 null,子 Agent Thread 返回创建它的父 Thread ID。
同一 Session 中的 Thread 共享 Environment、Sandbox、文件系统和已绑定的 Vault 凭据,但不会自动共享对话历史。一个 Thread 写入文件后,其他 Thread 可以读取该文件;需要同时传递结论时,子 Agent 还应回传文件路径和摘要。
主流程使用两个终端。终端 A 接收 Session 事件流,终端 B 创建 Session、发送任务和查询结果。需要实时查看某个 Thread 的完整过程时,再打开终端 C。
在终端 B 创建 Session:
: "${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "${ARK_API_KEY:?Set ARK_API_KEY}"
: "${COORDINATOR_AGENT_ID:?Set COORDINATOR_AGENT_ID}"
: "${ENVIRONMENT_ID:?Set ENVIRONMENT_ID}"
payload=$(
jq -n \
--arg agent_id "$COORDINATOR_AGENT_ID" \
--arg environment_id "$ENVIRONMENT_ID" \
'{
agent: $agent_id,
environment_id: $environment_id,
title: "Multi Agent task"
}'
)
session=$(
curl -sS --fail-with-body "$ARK_BASE_URL/sessions" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d "$payload"
)
export SESSION_ID
SESSION_ID=$(jq -er '.id' <<<"$session")
printf 'Session ID: %s\n' "$SESSION_ID"
脚本将 Session ID 写入 SESSION_ID。确认该变量不为空后,再订阅事件流。此时只会创建 Main Thread。主 Agent 首次委派任务时,系统才会创建对应的子 Agent Thread。Session 会记录创建时使用的主 Agent 配置和运行限制,之后更新 Agent 不会影响这个 Session。
提交并观察任务#
订阅 Session 事件
在终端 A 配置同一个 Session 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>"
建立 Session 事件流:
: "${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "${ARK_API_KEY:?Set ARK_API_KEY}"
: "${SESSION_ID:?Set SESSION_ID}"
curl -sS -N --fail-with-body --max-time 600 \
"$ARK_BASE_URL/sessions/$SESSION_ID/events/stream" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Accept: text/event-stream"
终端 A 输出 : ready 后保持连接,再发送任务。通过 Session 事件流可以看到:
- Session 的整体状态。
- Thread 的创建、运行、空闲、重新调度和终止。
- Thread 之间用于委派、汇报和补充要求的协作消息。
- 子 Agent 发起的自定义工具调用和需要客户端处理的工具授权事件。
- 自托管 Environment 中需要 Worker 执行的内置工具调用。
需要查看某个子 Agent 的思考、回复、工具结果、Span 或预览帧时,查询对应的 Thread 事件。
提交任务
用户消息统一发送给主 Agent。主 Agent 根据任务需要选择预定义 Agent、Self 或 Inline Agent:
TASK_TEXT=$(cat <<'EOF'
评审以下 Python 登录接口实现。安排合适的子 Agent 分析代码质量、安全风险和测试覆盖,最后汇总结论。
def login(username, password):
key = f"login_failures:{username}"
failures = int(redis.get(key) or 0)
if failures >= 5:
return {"ok": False, "reason": "locked"}
if not verify_password(username, password):
redis.incr(key)
redis.expire(key, 1800)
return {"ok": False, "reason": "denied"}
redis.delete(key)
return {"ok": True}
EOF
)
export TASK_TEXT
: "${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "${ARK_API_KEY:?Set ARK_API_KEY}"
: "${SESSION_ID:?Set SESSION_ID}"
: "${TASK_TEXT:?Set TASK_TEXT}"
payload=$(
jq -n --arg text "$TASK_TEXT" \
'{events: [{type: "user.message", content: [{type: "text", text: $text}]}]}'
)
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"
使用 multiagent_20261001 时,任务投递成功只表示目标 Thread 已接收任务,不表示子 Agent 已完成。主 Agent 可以继续处理其他工作,子 Agent 的结果会在执行结束后异步返回。
主 Agent 首次向某个成员派发任务时,Session 事件流会出现 session.thread_created。需要补充要求时,可以继续使用原 Thread,不必重新创建上下文。
查看 Thread
在终端 B 列出当前 Session 的全部 Thread:
: "${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "${ARK_API_KEY:?Set ARK_API_KEY}"
: "${SESSION_ID:?Set SESSION_ID}"
threads=$(
curl -sS --fail-with-body \
"$ARK_BASE_URL/sessions/$SESSION_ID/threads?limit=100" \
-H "Authorization: Bearer $ARK_API_KEY"
)
printf 'Agent\tThread ID\tParent Thread ID\tStatus\n'
jq -r '.data[] | [.agent_name, .id, (.parent_thread_id // "-"), .status] | @tsv' <<<"$threads"
export SESSION_THREAD_ID
if ! SESSION_THREAD_ID=$(
jq -er 'first(.data[] | select(.parent_thread_id != null and .status != "archived" and .status != "terminated") | .id)' \
<<<"$threads"
); then
printf 'No active child thread is available yet.\n' >&2
return 1 2>/dev/null || exit 1
fi
printf 'Selected child thread ID: %s\n' "$SESSION_THREAD_ID"
脚本将第一个子 Agent 的 Thread ID 写入 SESSION_THREAD_ID。检查其他 Thread 时,更新该变量,并在查询历史前清空分页标识:
export SESSION_THREAD_ID="<SESSION_THREAD_ID>"
unset THREAD_EVENTS_PAGE
查询该 Thread 的完整历史:
: "${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}"
request_args=(
--get
"$ARK_BASE_URL/sessions/$SESSION_ID/threads/$SESSION_THREAD_ID/events"
--data-urlencode "limit=100"
--data-urlencode "order=asc"
)
if [[ -n ${THREAD_EVENTS_PAGE:-} ]]; then
request_args+=(--data-urlencode "page=$THREAD_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 THREAD_EVENTS_PAGE
THREAD_EVENTS_PAGE=$(jq -r '.next_page // empty' <<<"$events")
printf 'Next page: %s\n' "$THREAD_EVENTS_PAGE"
如果 Next page 不为空,保持 THREAD_EVENTS_PAGE 并重复执行,直到下一页标识为空。切换 Thread 前再次清空该变量。
查询 Thread 详情或列表时,stats 返回运行时长,usage 返回该 Thread 累计的模型 token、缓存和服务端工具用量。
需要实时查看该 Thread 时,在终端 C 建立事件流:
: "${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"
Thread 事件流输出 : ready 后,再补查一次历史。按事件 id 合并实时与历史结果,并忽略重复事件。Session 和 Thread 事件流中的消息到达顺序可能不同。可以通过 session_thread_id、from_session_thread_id 和 to_session_thread_id 找到一次委派及其返回结果。
判断本轮是否完成
正常事件轨迹如下:
session.thread_created
agent.thread_message_sent
session.thread_status_idle
agent.message
session.status_idle
只有同时满足以下条件,本轮任务才成功:
- Main Thread 产生最终
agent.message。 - Session 以
stop_reason.type=end_turn进入idle。 - 没有 Thread 停留在
running或rescheduling。 - 本轮没有出现需要处理的终止或错误事件。
管理 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
: "${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>"
: "${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 时,省略该变量:
# 中断指定 Thread
export SESSION_THREAD_ID="<SESSION_THREAD_ID>"
# 中断全部活跃 Thread
# unset SESSION_THREAD_ID
: "${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "${ARK_API_KEY:?Set ARK_API_KEY}"
: "${SESSION_ID:?Set SESSION_ID}"
if [[ -n ${SESSION_THREAD_ID:-} ]]; then
payload=$(
jq -n --arg thread_id "$SESSION_THREAD_ID" \
'{events: [{type: "user.interrupt", session_thread_id: $thread_id}]}'
)
else
payload=$(jq -n '{events: [{type: "user.interrupt"}]}')
fi
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"
中断不会回滚已经写入共享文件系统的内容,也不会删除 Thread。中断指定 Thread 后,等待该 Thread 进入 idle。中断全部 Thread 后,等待 Session 进入 idle。
升级 Session 配置
更新主 Agent 后,已有 Session 不会自动使用新配置。只有同时满足以下条件时,才升级 Session:
- Session 当前为
idle,且上一轮以end_turn结束。 - 所有 Thread 都已结束当前工作。
- 没有等待处理的工具授权、工具结果,也没有子 Agent 等待其他 Thread 的回复。
- 当前没有其他升级请求。
设置更新主 Agent 后得到的版本号,然后创建升级任务:
export COORDINATOR_AGENT_VERSION="<TARGET_AGENT_VERSION>"
: "${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "${ARK_API_KEY:?Set ARK_API_KEY}"
: "${SESSION_ID:?Set SESSION_ID}"
: "${COORDINATOR_AGENT_ID:?Set COORDINATOR_AGENT_ID}"
: "${COORDINATOR_AGENT_VERSION:?Set COORDINATOR_AGENT_VERSION}"
payload=$(
jq -n \
--arg agent_id "$COORDINATOR_AGENT_ID" \
--argjson version "$COORDINATOR_AGENT_VERSION" \
'{agent: {type: "agent_with_upgrades", id: $agent_id, version: $version}}'
)
curl -sS --fail-with-body \
"$ARK_BASE_URL/sessions/$SESSION_ID/upgrades" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d "$payload"
等待 Session 使用目标版本恢复为 idle:
: "${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "${ARK_API_KEY:?Set ARK_API_KEY}"
: "${SESSION_ID:?Set SESSION_ID}"
: "${COORDINATOR_AGENT_ID:?Set COORDINATOR_AGENT_ID}"
: "${COORDINATOR_AGENT_VERSION:?Set COORDINATOR_AGENT_VERSION}"
: "${SESSION_UPGRADE_MAX_ATTEMPTS:=60}"
: "${SESSION_UPGRADE_INTERVAL_SECONDS:=2}"
upgrade_result="timeout"
for ((attempt = 1; attempt <= SESSION_UPGRADE_MAX_ATTEMPTS; attempt++)); do
session=$(
curl -sS --fail-with-body \
"$ARK_BASE_URL/sessions/$SESSION_ID" \
-H "Authorization: Bearer $ARK_API_KEY"
) || {
upgrade_result="request_failed"
break
}
session_status=$(jq -er '.status' <<<"$session") || {
upgrade_result="invalid_response"
break
}
session_agent_id=$(jq -r '.agent.id // empty' <<<"$session")
session_agent_version=$(jq -r '.agent.version // empty' <<<"$session")
printf 'Attempt %s: status=%s, agent=%s, version=%s\n' \
"$attempt" \
"$session_status" \
"$session_agent_id" \
"$session_agent_version"
if [[
$session_status == "idle" &&
$session_agent_id == "$COORDINATOR_AGENT_ID" &&
$session_agent_version == "$COORDINATOR_AGENT_VERSION"
]]; then
upgrade_result="completed"
break
fi
case "$session_status" in
terminated | failed)
upgrade_result="$session_status"
break
;;
esac
sleep "$SESSION_UPGRADE_INTERVAL_SECONDS"
done
if [[ $upgrade_result != "completed" ]]; then
printf 'Session upgrade did not complete: %s\n' "$upgrade_result" >&2
false
fi
脚本默认每 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:
export CONFIRM_DELETE="yes"
export DELETE_COORDINATOR="no"
仅当主 Agent 不再被其他 Session 使用时,才将 DELETE_COORDINATOR 改为 yes:
: "${ARK_BASE_URL:?Set ARK_BASE_URL}"
: "${ARK_API_KEY:?Set ARK_API_KEY}"
: "${SESSION_ID:?Set SESSION_ID}"
: "${CONFIRM_DELETE:?Set CONFIRM_DELETE to yes}"
: "${DELETE_COORDINATOR:=no}"
if [[ $CONFIRM_DELETE != "yes" ]]; then
printf 'Set CONFIRM_DELETE=yes to delete the recorded resources.\n' >&2
return 1 2>/dev/null || exit 1
fi
curl -sS --fail-with-body \
"$ARK_BASE_URL/sessions/$SESSION_ID" \
-X DELETE \
-H "Authorization: Bearer $ARK_API_KEY"
if [[ $DELETE_COORDINATOR == "yes" ]]; then
: "${COORDINATOR_AGENT_ID:?Set COORDINATOR_AGENT_ID}"
curl -sS --fail-with-body \
"$ARK_BASE_URL/agents/$COORDINATOR_AGENT_ID" \
-X DELETE \
-H "Authorization: Bearer $ARK_API_KEY"
fi
命令不会删除成员 Agent 或 Environment。
相关文档