You need to enable JavaScript to run this app.
文档中心
火山方舟

火山方舟

复制全文
下载 pdf
会话事件
会话事件结构参考
复制全文
下载 pdf
会话事件结构参考
托管智能体会话通过事件实现客户端与服务端之间的双向通信。客户端可以发送消息、控制指令和工具执行结果;服务端会推送 Agent 回复、Session 状态、累计用量和模型调用信息。流式订阅还可以返回用于增量展示内容的瞬时预览帧。本参考文档说明各类事件和预览帧的结构、字段含义与触发时机。​
说明​
  • 事件流使用说明:如需发送、实时接收或断线补查事件,请参见 Session 事件流。​
  • 客户端发送事件时,公共字段中的 id、processed_at 等由服务端自动生成,客户端仅需要填写事件类型(type)和对应业务字段即可。​
  • system.message 必须与一条 user.message 放在同一个 events 数组中,并紧跟在该 user.message 后发送;单独发送 system.message 会被服务端拒绝。​
  • 多态对象通过 type 字段区分具体结构。客户端应先读取 type,再按对应变体解析其余字段。​
  • 事件 ID、结果评估 ID 和线程 ID 分别以 sevt-、outc- 和 sthr- 开头。​
  • user.message 的 content[] 支持 video 内容块:​
  • fps:抽帧频率,取值范围为 0.2~5;省略时使用下游模型的默认策略。​
  • source.type:视频来源类型,支持以下取值:​
  • url:使用公网可访问的视频 URL。可处理的视频大小以下游模型的输入限制为准。​
  • base64:使用 Base64 编码的视频,媒体类型支持 video/mp4、video/x-msvideo 和 video/quicktime。​
  • file:使用 Files API 上传的视频文件 ID。​
  • event_start 和 event_delta 仅在流式接口通过 event_deltas 参数显式订阅后返回,不写入事件历史。每个预览帧都有独立的顶层 id 和 processed_at;使用 event_start.event.id 或 event_delta.event_id 关联最终完整事件。​
  • Session 事件接口返回完整的会话主线程事件。子 Agent 线程只有生命周期、协作消息、自定义工具调用和需要客户端处理的工具授权事件会返回;自托管 Environment 中需要宿主执行的内置工具调用也会返回。思考、普通回复、Span 和预览帧,以及服务端生成的工具执行结果不返回;客户端回传的工具结果和授权回复仍会返回。​
  • 流式响应可能为线程内事件补充 session_thread_id,事件历史接口可能省略该字段。下方事件结构仅列出事件自身定义的字段。​
  • Session 进入 idle 状态时,无论本轮停止原因为何,服务端都会按最后一个 session.thread_status_idle、session.usage、session.status_idle 的顺序返回本轮收尾事件。​
  • session.usage 的 id 为 sevt-usg-<对应的 session.status_idle 事件 ID>,processed_at 与该 session.status_idle 相同。客户端应保留服务端返回顺序,不要仅按 processed_at 排序或去重。​
客户端发送事件(请求)​
user.message​
用户向智能体发送消息时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
session_id string | Session ID​
​
processed_at string | 处理时间​
​
content object[] | 消息内容​
​
​​
system.message​
客户端向会话注入系统提示词时触发,必须作为同一 events 数组中 user.message 后的下一个事件发送​
type string | 事件类型​
​
id string | 事件 ID​
​
session_id string | Session ID​
​
processed_at string | 处理时间​
​
content object[] 必选 | 消息内容​
​
​​
user.interrupt​
用户发送中断指令,终止正在运行的线程/会话时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
session_id string | Session ID​
​
processed_at string | 处理时间​
​
session_thread_id string | 线程 ID​
​
​​
user.tool_confirmation​
用户对需要确认的工具调用进行批准/拒绝操作时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
session_id string | Session ID​
​
processed_at string | 处理时间​
​
result string 必选 | 确认结果​
​
tool_use_id string 必选 | 工具调用 ID​
​
deny_message string | 拒绝理由​
​
session_thread_id string | 线程 ID​
​
​​
user.tool_result​
自托管 Environment 中的 Worker 完成内置工具调用后,客户端回传执行结果时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
session_id string | Session ID​
​
processed_at string | 处理时间​
​
tool_use_id string 必选 | 工具调用 ID​
​
content object[] | 结果内容​
​
is_error boolean | 是否错误​
​
session_thread_id string | 线程 ID​
​
​​
user.custom_tool_result​
客户端本地执行完自定义工具(custom 类型工具,如生图、生视频等场景)后回传结果时触发。通过 custom_tool_use_id 关联对应的 agent.custom_tool_use 事件。​
type string | 事件类型​
​
id string | 事件 ID​
​
session_id string | Session ID​
​
processed_at string | 处理时间​
​
custom_tool_use_id string 必选 | 自定义工具调用 ID​
​
content object[] | 结果内容​
​
is_error boolean | 是否错误​
​
session_thread_id string | 线程 ID​
​
​​
服务端推送事件(响应)​
agent.message​
智能体生成回复消息时触发,包括最终回复以及工具调用前后的中间文本(随模型行为不同而不同)​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
content object[] | 回复内容​
​
​​
agent.thinking​
智能体生成思考内容时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
content object[] | 思考内容​
​
​​
agent.tool_use​
智能体决定调用内置工具时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
name string | 工具名称​
​
input object | 输入参数​
​
evaluated_permission string | 权限结果​
​
session_thread_id string | 线程 ID​
​
​​
agent.tool_result​
内置工具执行完成并返回结果时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
tool_use_id string | 工具调用 ID​
​
content object[] | 结果内容​
​
is_error boolean | 是否错误​
​
​​
agent.mcp_tool_use​
智能体决定调用 MCP 服务提供的工具时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
mcp_server_name string | MCP 服务名​
​
name string | 工具名称​
​
input object | 输入参数​
​
evaluated_permission string | 权限结果​
​
session_thread_id string | 线程 ID​
​
​​
agent.mcp_tool_result​
MCP 工具执行完成并返回结果时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
mcp_tool_use_id string | MCP 工具调用 ID​
​
content object[] | 结果内容​
​
is_error boolean | 是否错误​
​
​​
agent.custom_tool_use​
智能体决定调用客户端提供的自定义工具(custom 类型工具,如生图、生视频等场景)时触发。客户端执行工具后,通过 user.custom_tool_result 回传结果;custom_tool_use_id 需与本事件 id 一一匹配。​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
name string | 工具名称​
​
input object | 输入参数​
​
session_thread_id string | 线程 ID​
​
​​
agent.thread_message_received​
多智能体场景下,当前线程收到其他线程/智能体发来的消息时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
content object[] | 消息内容​
​
from_session_thread_id string | 来源线程 ID​
​
from_agent_name string | 来源智能体名称​
​
​​
agent.thread_message_sent​
多智能体场景下,当前线程向其他线程/智能体发送消息时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
content object[] | 消息内容​
​
to_session_thread_id string | 目标线程 ID​
​
to_agent_name string | 目标智能体名称​
​
​​
agent.thread_context_compacted​
线程上下文达到长度限制,自动进行摘要压缩时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
​​
session.error​
会话执行过程中发生错误时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
error object | 错误详情​
​
​​
session.deleted​
会话被删除时触发。收到该事件后,该会话不会再产生后续事件,客户端应结束当前流式连接​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
​​
session.thread_created​
多智能体会话中新线程创建成功时触发。Session 事件接口会返回该通知;子线程内部的完整执行过程需订阅或查询对应线程​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
agent_name string | 智能体名称​
​
session_thread_id string | 线程 ID​
​
​​
session.status_running​
会话开始处理任务、状态变为 running 时触发。只要会话内任一未归档线程开始执行任务或进入重调度,会话就会进入 running​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
​​
session.usage​
会话即将进入空闲状态时触发。无论本轮停止原因为何,服务端都会在最后一个 session.thread_status_idle 之后、session.status_idle 之前返回会话的最新累计用量快照​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
usage object | 累计用量​
​
​​
session.status_idle​
会话内没有正在运行或重调度的线程时触发,状态变为 idle。仍有线程等待工具授权或外部结果时,stop_reason.type 为 requires_action​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
stop_reason object | 停止原因​
​
​​
session.status_rescheduled​
会话因临时错误进入自动恢复和重新调度过程时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
​​
session.status_terminated​
会话进入终态时触发。该状态下不能继续发送事件;retries_exhausted 仅表示当前轮次结束,不代表会话终止​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
​​
session.thread_status_running​
线程开始处理任务,进入运行状态时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
agent_name string | 智能体名称​
​
session_thread_id string | 线程 ID​
​
​​
session.thread_status_idle​
线程处理完当前任务,进入空闲状态时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
agent_name string | 智能体名称​
​
session_thread_id string | 线程 ID​
​
stop_reason object | 停止原因​
​
​​
session.thread_status_rescheduled​
线程因临时错误进入自动恢复和重新调度过程时触发。Session 事件接口也会返回子线程的该状态通知​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
agent_name string | 智能体名称​
​
session_thread_id string | 线程 ID​
​
​​
session.thread_status_terminated​
线程被终止时触发。Session 事件接口也会返回子线程的该状态通知​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
agent_name string | 智能体名称​
​
session_thread_id string | 线程 ID​
​
​​
span.model_request_start​
开始调用大模型时触发,用于链路追踪​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
​​
span.model_request_end​
大模型调用完成时触发​
type string | 事件类型​
​
id string | 事件 ID​
​
processed_at string | 处理时间​
​
model_request_start_id string | 开始事件 ID​
​
model_usage object | token 用量​
​
is_error boolean | 是否错误​
​
​​
流式预览帧(SSE)​
event_start​
通过 event_deltas 订阅 agent.message 或 agent.thinking 的增量预览后,服务端开始推送对应事件时触发​
type string | 帧类型​
​
id string | 预览帧 ID​
​
processed_at string | 生成时间​
​
event object | 预览事件​
​
​​
event_delta​
被订阅事件生成新的文本片段时触发,客户端按 event_id 和 index 累积内容​
type string | 帧类型​
​
id string | 预览帧 ID​
​
processed_at string | 生成时间​
​
event_id string | 事件 ID​
​
delta object | 内容增量​
​
​​
​
最近更新时间:2026.11.04 18:12:42
这个页面对您有帮助吗?
有用
有用
无用
无用