与 Managed Agents 的通信基于事件。接入时，先建立 SSE 并等待 : ready，再发送事件并接收完整事件，最后根据 stop_reason 判断结果。如需展示用量或记账，再读取累计用量快照。连接中断后，先建立新流，再通过历史事件接口补齐中断窗口。

准备工作

开始前你需要：

已创建的 API Key：配置为环境变量 ARK_API_KEY，详情请参见 API Key 管理。

已创建的 Agent：详情请参见定义 Agent。

已创建的 Environment：详情请参见配置云环境。

本章节示例的 Base URL 与鉴权方式详情请参见 Base URL 及鉴权。

本地需要安装 curl 和 jq。

核心交互流程

以下流程适用于云端环境和自托管环境中的业务应用：

通过 GET /sessions/{session_id}/events/stream 建立 SSE。

等待服务端返回 : ready。

通过 POST /sessions/{session_id}/events 发送 user.message。

持续接收 agent.*、session.* 和 span.* 事件。

仅在收到后续 session.status_idle 且 stop_reason.type=end_turn 时，将本轮判定为正常结束。

如需展示用量或记账，读取 session.status_idle 前返回的 session.usage 累计用量快照。session.usage 不是本轮完成判断条件。

正常完成一轮任务时，事件按以下顺序流转：

业务应用建立 SSE、发送消息并以 session.status_idle 和 end_turn 判断本轮正常结束的顺序

客户端先建立 SSE 并等待 : ready，再发送 user.message，避免漏掉连接建立前已经产生的事件。

session.status_running 表示 Agent 已开始处理任务；span.* 和 agent.thinking 按任务执行过程产生，完整回复由 agent.message 返回。

本轮收尾时，服务端依次返回最后一个 session.thread_status_idle、session.usage 和 session.status_idle。无论 stop_reason 是什么，Session 进入 idle 前都会返回 session.usage。

收到 agent.message 或 session.usage 都不代表本轮结束。客户端继续读取事件，只有 session.status_idle 且 stop_reason.type=end_turn 表示正常结束。

如需直接复用完整实现，请参见运行完整示例。

理解事件通信

接口职责

根据不同用途选择对应接口：

接口	客户端动作	返回内容和限制
GET /sessions/{session_id}/events/stream	建立 SSE 并等待 : ready，实时接收事件	只推送连接建立后产生的事件，不回放历史事件
POST /sessions/{session_id}/events	发送 user.* 或 system.message 事件	HTTP 200 只表示事件已受理，不表示 Agent 已处理或本轮已结束
GET /sessions/{session_id}/events	分页查询已持久化的完整事件，用于历史查看和断线补查	不包含 event_start、event_delta 预览帧，也不提供实时推送
GET /sessions/{session_id}	查询 Session 最新状态、累计用量和配置快照	不返回完整事件历史或 Agent 回复内容

事件模型

事件类型遵循 {domain}.{action} 命名约定。先根据事件域判断方向和职责，再根据完整的 type 读取对应结构。

事件域	方向	说明
user.*、system.message	客户端发送至 Session	提交用户消息、动态系统提示词、中断、工具确认或工具结果
agent.*	Session 发送至客户端	返回消息、思考过程、工具调用和主子线程通信事件
session.*	Session 发送至客户端	返回 Session 或子线程的运行、等待、重调度、终止、错误状态和累计用量
span.*	Session 发送至客户端	返回模型调用的过程和结果

每个完整事件都包含 id、type 和 processed_at。processed_at 为 null 时，表示事件已进入队列但尚未完成处理。完整事件类型、字段、取值和嵌套结构，详情请参见会话事件结构参考。

运行环境差异

两种环境中的业务应用共用 Session Events API。Environment 类型只改变主 Agent 的 Bash 和文件工具的执行位置，不改变其他工具的执行方：

对比项	云端环境	自托管环境
Session 事件	业务应用建立 Session SSE 并发送事件	业务应用建立 Session SSE 并发送事件
主 Agent 的 bash、read、write、edit、glob、grep	方舟云沙箱执行，通过 agent.tool_result 返回结果	企业 Worker 和 Sandbox 执行，通过 user.tool_result 回传结果
web_fetch、web_search 和多模态工具	方舟侧执行	方舟侧执行
MCP 工具	方舟侧执行	方舟侧执行
自定义工具	业务应用执行	业务应用执行
额外链路	无	Worker Poll/Ack Work、建立 Worker SSE 并维持 Heartbeat

自托管环境中，业务应用不直接调用 Work API。Worker 的部署与运行机制，详情请参见配置并运行自托管环境。

发送事件

客户端通过 POST /sessions/{session_id}/events 向 Session 发送 user.message 事件，content 是一个块数组，可混合文本（text）、图片（image）、文档（document）、视频（video）四类块。

图片 image 的 source.type 支持三种：base64（内联 base64，需带 media_type）、url（公网可访问 URL）、file（已上传文件 ID，字段为 file_id）。

文档 document 的 source.type 支持四种：file（已上传文件 ID）、url（公网可访问 URL）、base64（内联 base64，需带 media_type）、text（直接内联纯文本，media_type: text/plain + data 字段）；可选 title 与 context 字段为文档附加标题与背景说明。

视频 video 的 source.type 支持三种：base64（内联 Base64，需带 media_type 和 data）、url（公网可访问 URL）、file（已上传视频文件 ID，字段为 file_id）。三种来源均可通过 fps 设置抽帧频率，取值范围为 0.2～5。

同一请求的 content 数组可混合多个图片、文档或视频块。

如需为当前轮次动态追加系统提示词，可在 events 数组里 user.message 后紧跟一个 system.message，详情请参见动态系统提示词。

常见内容组合示例

纯文本

文本 + 图片（URL）

文本 + 图片（base64）

文本 + 图片（file_id）

文本 + 文档（file_id）

文本 + 文档（内联纯文本）

文本 + 文档（base64 PDF）

文本 + 文档（URL）

文本 + 多附件混合

请求体的 events 字段是事件数组，服务端按入队顺序串行处理。

运行中继续发送消息

Session 处于 running 状态时，你仍可以继续发送 user.message。服务端会先接收事件并写入待处理队列，等当前 Agent 执行到可调度边界后再把队列中的消息送入后续模型请求。常见边界包括当前模型请求结束、工具执行结果返回、当前回合结束等。

这种设计适合连续对话、实时追加约束、长任务中补充材料等场景。客户端不需要为了发送下一条消息轮询等待 idle，但仍需要通过 SSE 观察事件处理进度：

HTTP 响应成功只表示事件已被服务端接收，不表示 Agent 已经处理完这条消息。

返回事件的 processed_at 为 null 时，表示该事件仍在队列中，等待前序事件处理完成。

多条排队消息可能在后续一次模型请求中合并处理，Agent 不一定为每条消息生成一条独立回复。

如果待处理队列已满，接口会返回 HTTP 409。此时不要快速重试，应等待 Agent 消费队列，或按业务需要发送 user.interrupt 中断当前执行。

动态系统提示词

除了在定义 Agent 时配置的固定系统提示词，客户端还可以在发送 user.message 的同一请求末尾追加一个 system.message，为当前轮次动态注入额外指令；固定系统提示词、运行时 system.message 与用户消息拼接后一起送入模型。

对比项	Agent 定义的系统提示词	运行时 system.message 事件
位置	创建 Agent 时设置	发 Events 时传入
生效	创建 Session 时拼入，整个 Session 生命周期内固定	每次发送后追加到 Session 的系统角色上下文

同一请求需要区分 API 提交顺序和模型上下文顺序：

阶段	顺序	说明
API 请求中的 events 数组	先发送 user.message，再发送 system.message	system.message 必须紧跟在 user.message 后面，并且是数组的最后一个元素
进入模型前的上下文	依次为 Agent 系统提示词、历史 system.message、本轮 system.message 和本轮 user.message	服务端先将本轮 system.message 追加到系统角色上下文，再发起本轮模型调用

模型上下文实际展开如下，省略普通会话历史。

轮次	上下文展开
首轮	[Agent 系统提示词] [首轮 system.message] [首轮 user.message]
次轮	[Agent 系统提示词] [首轮 system.message] [次轮 system.message] [次轮 user.message]

system.message 按追加（append-only）语义写入 Session 的系统角色上下文，不支持替换或清空。后续每次模型调用都会携带该 Session 内全部历史 system.message 内容。需要重置系统提示词时，必须新建 Session。

单独发送 system.message、未紧跟 user.message 或未放在 events 数组末尾，都会返回 HTTP 400 InvalidPayload。

Curl

请求成功返回 HTTP 200，响应 data 数组按入参顺序包含服务端已受理的事件。

接收并处理事件

业务应用通过已经建立的 SSE 连接接收完整事件，并根据 type 更新状态、展示回复或进入对应分支。agent.message、agent.thinking 和 agent.tool_result 等完整事件会写入事件历史；客户端应记录事件 ID，用于断线补查时去重。

展示预览内容

需要在完整消息生成前更新界面时，通过 event_deltas 指定要预览的事件类型。当前支持 agent.message 和 agent.thinking：

多值可以重复传入，例如 ?event_deltas=agent.message&event_deltas=agent.thinking；也可以使用逗号分隔，例如 ?event_deltas=agent.message,agent.thinking。

预览内容从 event_start、重复 event_delta 到完整 agent.message 或 agent.thinking 事件的顺序

预览开始：事件 event_start 标识一个预览事件开始，并给出完整事件将使用的 ID。

预览增量：事件 event_delta 按 event_id 和内容块 index 追加增量内容，同一事件可以返回多次。

预览帧标识：每个预览帧的顶层 id 和 processed_at 标识该帧自身；使用 event_start.event.id 或 event_delta.event_id 关联最终完整事件。

完整事件：事件 agent.message 或 agent.thinking 返回最终完整内容。

预览帧不写入事件历史，也可能在连接中断时不完整。界面可以使用预览帧实时更新，持久化和业务判断应以完整事件为准。参数写法和响应格式，详情请参见流式获取会话事件。

判断本轮结果

不要使用 HTTP 响应成功、agent.message 或 SSE 连接关闭作为本轮结束条件。客户端应继续读取状态事件，并根据以下结果处理：

Session 即将进入 idle 时，服务端会先返回 session.usage，再返回 session.status_idle。session.usage 只提供最新累计用量，不提供本轮处理结果；无论 stop_reason 为 end_turn、requires_action 还是 retries_exhausted，都应继续读取后续状态事件。

状态事件	停止原因	客户端动作
session.status_idle	end_turn	本轮正常结束，可以发送下一条消息
session.status_idle	requires_action	本轮尚未结束，根据 event_ids 回传工具确认或工具结果
session.status_idle	retries_exhausted	当前轮次重试次数已用尽；本轮结束，但仍可发送新的输入
session.status_rescheduled	不适用	方舟正在自动恢复，继续监听，不要重复发送原事件
session.status_terminated	不适用	Session 已进入终态，停止发送事件
session.deleted	不适用	Session 已被删除，结束事件流，不要重连或发送事件

收到 session.error 时，还需要检查 error.retry_status.type：

retrying：服务端正在自动重试，继续监听。

exhausted：当前轮次重试耗尽，等待对应的 session.status_idle。

terminal：Session 将进入终止状态，停止发送新事件。

完整状态迁移，详情请参见管理 Session。

处理工具确认

当工具权限策略要求执行前确认时，按以下步骤解除 requires_action：

接收 agent.tool_use 或 agent.mcp_tool_use 事件。

接收 session.status_idle，确认 stop_reason.type=requires_action。

遍历 stop_reason.event_ids，为每个待处理事件发送一条 user.tool_confirmation。将事件 ID 原样填入 tool_use_id，并将 result 设置为 allow 或 deny。

所有需要处理的确认事件处理完成后，Session 返回 session.status_running 并继续当前任务。

拒绝工具调用时，可以通过 deny_message 返回具体原因。Agent 会据此选择其他工具、降级处理，或说明无法继续执行。此阶段不要发送新的 user.message 替代确认。

工具权限策略的配置方法，详情请参见工具权限策略。

断线重连与历史补查

SSE 接口不支持从断点自动续传。要补齐中断期间产生的事件，按以下顺序处理：

调用 GET /sessions/{session_id}/events/stream 打开新的事件流，并等待 : ready。

调用 GET /sessions/{session_id}/events 查询历史事件。首次请求省略 page。

响应包含 next_page 时，将该值原样作为下一次请求的 page，直到不再返回 next_page。

按事件 ID 合并历史事件和新事件流中的实时事件，跳过已经处理的事件。

收到 session.deleted 表示 Session 已被删除，不属于可恢复的连接中断。此时结束事件流，不要重连或补查历史。

必须先建立新流再查询历史。如果先查历史再重连，历史查询结束到新流建立之间仍会留下新的监听空窗。本页的完整示例实现了该顺序和事件去重。

运行完整示例

以下 run_session_turn 函数串联 SSE 建连、事件发送、结果判断和断线补查。SSE 意外断开时，函数先建立新流，再分页查询历史事件，并按事件 ID 去重。

完整 cURL 函数

配置鉴权信息和已有 Session ID，然后调用函数：

正常完成时，函数输出完整的 agent.message，并以状态码 0 退出。其他结果使用非零状态码：

状态码	结果	处理方式
0	end_turn，且已收到 agent.message	本轮正常结束
2	requires_action	根据输出的事件 ID 回传工具确认或工具结果
3	retries_exhausted	当前轮次失败，可以修正输入后重新发送
4	Session 终止、被删除或发生不可恢复错误	停止向当前 Session 发送事件
5	状态事件缺少有效停止原因，或正常结束前未收到完整回复	查询历史事件和错误信息后再决定是否重试

中断和继续使用 Session

中断 Session

客户端发送 user.interrupt 事件可中断 Agent 当前执行。中断会清空尚未被调度的待处理消息，避免旧消息在中断后继续触发模型调用。

如果你只是补充当前任务的信息，直接继续发送 user.message 即可，消息会按队列顺序处理；如果你要放弃当前执行并切换到新任务，先发送 user.interrupt，等 Session 回到 idle 后再发送新的 user.message：

Curl

继续使用空闲 Session

在 Session 仍处于 idle 且尚未终止时，按发送消息流程发送包含真实任务内容的 user.message，Session 会从 idle 变为 running。

如果需要继续保留沙箱状态，在当前期限到期前发送一条 content 非空的 user.message。Session 完成本轮任务并再次进入 idle 后，平台重新计算 14 天保留期。省略 content 或传入空数组不会刷新保留期。

需要长期保留事件和 Agent 产物时，将必要数据保存到自己的存储。保留与删除影响，详情请参见数据保留与删除影响。

观测与排查

跟踪用量

根据统计范围选择对应事件：

Session 累计用量：读取 session.usage 事件的 usage。该事件在 Session 每次进入 idle 前返回最新累计快照；如需计算本轮增量，将本次快照减去上一次 session.usage 快照。

单次模型请求用量：读取 span.model_request_end 事件的 model_usage，用于分析某次模型调用的 token 消耗和推理速度。

以下 session.usage 示例包含会话累计运行时长、模型 token 和服务端搜索请求次数：

session.usage.id 由对应的 session.status_idle 事件 ID 生成，格式为 sevt-usg-<idle_event_id>；两条事件的 processed_at 相同。客户端应保留服务端返回顺序，不要仅按 processed_at 排序或去重。当前事件中的 cache_creation 两个字段固定返回 0。

需要查询服务端记录的最新累计用量和时长时，调用 GET /sessions/{session_id} 读取 Session 的 usage 和 stats；需要按线程排查消耗和启动耗时时，调用 GET /sessions/{session_id}/threads/{thread_id} 读取当前线程的 usage 和 stats。存量 Session 的统计完整性边界，详情请参见管理 Session 。

span.model_request_end 携带的 model_usage 只记录本次模型请求：

model_usage 字段含义：

input_tokens：未缓存输入 token。

output_tokens：全部输出 token。

cache_creation_input_tokens：本次请求写入提示词缓存的输入 token 数。

cache_read_input_tokens：本次请求从提示词缓存读取的输入 token 数。

speed：本次请求速度档位。

控制台可观测性

控制台 Managed Agents 提供 Session 的可视化时间线视图：

Session 列表：全部 Session 及其状态、创建时间、模型。

追踪视图：Session 内事件按时间排序展示，仅对开发者与管理员可见。

工具执行：每次工具调用及其结果。

调试技巧

关注 session.error：根据 error.retry_status.type 判断服务端会重试、结束当前轮次还是终止 Session。

检查工具结果：失败的工具调用通常解释了 Agent 异常行为的原因。

跟踪 token 用量：监控消耗以优化提示并降低成本。

火山方舟