Skip to main content

订阅实时事件

千问办公企业旗舰版开发者文档:订阅实时事件。

认证方式见APP开发者文档 → 认证接入。
  • 模块:会话服务(session)
  • 接口:GET/api/openapi/app/v1/sessions/{session_id}/events/stream

请求参数

重连使用新 Token 并保留已确认的事件游标,不把 Token 放到 URL。
参数位置类型必填说明
session_idpathstring是APP 会话 ID,供其他 APP 接口使用。
cursorqueryinteger (int64)否从此位置之后恢复;省略或空值仅订阅后续事件,0 请求从会话开头补流。优先使用已处理的消息边界 SSE id;不要要求序号连续。与 Last-Event-ID 同时传入时必须一致,否则 422。
Last-Event-IDheaderinteger (int64)否SSE 恢复位置。使用 fetch 的客户端成功处理 session_event 后保存该帧显式 id,在重连请求中自行设置本头;不加一、不要求序号连续。与 cursor 同传必须一致,否则 422。
include_statusqueryboolean否默认 true;false 仅抑制 session_status,不抑制 session_event、content_blocked、done、error。

响应

HTTP说明
200请求成功
default错误响应。按 code 判断具体错误,不能仅依赖 HTTP 状态码,多种错误可能共用状态码。
媒体类型:text/event-stream。

如何阅读一条 SSE 消息

本接口持续返回 SSE 文本。每个空行结束一帧,data 才是 JSON;网络读取块不等于完整的一帧。
层次判别字段含义
SSE 帧eventsession_event 为业务事件;其余为状态、撤回、结束、订阅错误
APP 业务事件data.type / method / sub_type判断是文本、工具调用、问题还是回合结果
Agent 载荷data.rawmethod 消息读取 params,结果读取 result,协议错误读取 error
一轮执行结束看 prompt_response,会话终止看 done/session_terminated。 一轮结束后会话仍能接收下一条 Prompt,SSE 可继续保持。业务事件中的 error 也不等于 SSE 的 error:前者描述执行问题,后者描述订阅故障。

四种标识不要混用

标识用途
SSE id完整消息边界的恢复位置,处理完成后保存
data.id业务消息标识;同一文本的片段与聚合消息可共用
data.seq_id当前事件对象覆盖的起始序号
data.seq_ids当前对象覆盖的全部序号;聚合消息可以覆盖多个序号
按外层 session_id、turn_id 调用 APP 接口。raw 内的 sessionId 是运行时标识,不能直接替代它们。

帧包装与公共字段

每帧以空行结束。event 表示消息类型,data 是该类型的 JSON 对象;id 是可选的恢复位置,不等于 JSON 中业务事件的 id。
字段类型说明
eventstringsession_event、session_status、content_blocked、done 或 error。
dataJSON object结构见下方对应字段表。
id十进制整数字符串,可省略仅 session_event 的消息边界帧发送。处理中间文本片段时通常省略;收到边界且处理完成后保存。
retryinteger初始连接发送 2000,单位毫秒,供支持此字段的 SSE 客户端决定重连间隔。
: connected 和 : heartbeat 是 SSE 注释,不是 JSON 事件,也不更新业务游标。连接断开不等于任务结束;只有明确的状态和终止帧能说明会话生命周期。

session_event:Event

字段类型必填契约说明
created_atstring是记录时间;排序使用序号。有时间元数据时为 ISO 8601,实时消息缺少时间元数据时当前实现返回空字符串。
idstring是业务消息标识;同一消息的多个片段及历史聚合对象可共用。
methodstring / null是method 类的协议方法;result/error 时为 null。
rawobject是原始 Agent 协议消息;method 读 params、结果读 result、协议错误读 error。详见下方业务载荷字段。
seq_idinteger是此对象覆盖的起始序号;聚合消息不能只用它作为恢复位置。
seq_idsarray<integer>是对象覆盖的序号。单片段追加内容;同一 id 的聚合完整消息替换已有片段。最大值是覆盖末端,但实时片段尚不一定构成可恢复边界,持久化恢复位置应使用 SSE id。序号可能因过滤而跳跃。
session_idstring是APP 会话 ID,供其他 APP 接口使用。
sub_typestring / null是session/update 的 sessionUpdate,或带 stopReason 结果对应的 prompt_response;其他情况可为 null。
turn_idstring / null是所属回合 ID;回合外事件为 null。
typestring是raw 的 JSON-RPC 类别:method、result、error。

常用业务事件的载荷字段

以下路径相对 data.raw。session/update 的子类型由 params.update.sessionUpdate 指定;未识别的事件应容错,不能让整个订阅失败。并非每轮都会出现所有类型。
场景type / method / sub_type载荷位置
本轮输入method / session/prompt / nullparams
回复文本method / session/update / agent_message_chunkparams.update
思考内容(运行时提供时)method / session/update / agent_thought_chunkparams.update
工具调用、进度结果method / session/update / tool_call、tool_call_updateparams.update
执行计划快照method / session/update / planparams.update
文件产物method / session/update / barn_file_msgparams.update
请求用户回答method / session/request_permission / nullparams
用户回答回显result / null / nullresult
一轮结束result / null / prompt_responseresult
执行错误通知method / session/update / errorparams.update
JSON-RPC 错误error / null / nullerror
取消请求method / session/cancel / nullparams

输入和文本内容

字段类型必填/条件说明
params.sessionIdstringsession/prompt 必填运行时会话标识
params.promptarray(object)session/prompt 必填输入内容块数组;文本块包含 type=text、text=输入文字
update.sessionUpdatestring文本事件agent_message_chunk 或 agent_thought_chunk
update.contentobject文本事件必填一个 ContentBlock,不能假定所有内容块都是文字
update.content.typestring内容块判别字段text 表示文本;其他类型按对应内容块处理
update.content.textstringtype=text 时必填当前片段或聚合消息的文本
update.content.annotationsobject/null可选内容注解
update._metaobject/null可选扩展元数据,无稳定兼容保证;客户端使用 SSE id,不自行依赖内部标记推算恢复位置
同一业务 id 的实时文本片段按序号追加,重复片段不重复展示。历史聚合对象覆盖多个 seq_ids 时替换该 id 已展示的文本,不能再次追加。非文本 ContentBlock 可为图像、音频、资源引用或嵌入资源;不支持的类型应降级展示,不能直接读取 text。

工具调用与更新

下表字段相对 params.update。tool_call 必填 toolCallId/title;tool_call_update 仅 toolCallId 必填,其他字段是局部更新,未携带的字段保持原值。
字段类型说明
sessionUpdatestringtool_call 或 tool_call_update
toolCallIdstring会话内工具调用标识,用于合并后续更新
titlestring;更新可为 null工具调用展示标题
kindstring;更新可为 nullread、edit、delete、move、search、execute、think、fetch、switch_mode、other
statusstring;更新可为 nullpending、in_progress、completed、failed;不代表整个回合状态
rawInput / rawOutput任意 JSON工具自定义输入输出,没有统一业务字段,不保证是文字
contentarray(object);更新可为 null工具产出;更新携带时替换该集合
locationsarray(object);更新可为 null受影响文件位置;更新携带时替换该集合
locations[].pathstring必填文件路径
locations[].lineinteger/null可选行号
content[].type子字段说明
contentcontent(必填 ContentBlock)文本需先确认 content.type=text,再取 content.text
diffpath、newText(必填);oldText(可选,可为 null)文件路径、新旧内容
terminalterminalId(必填 string)终端标识;此事件不提供终端读取接口

计划和文件产物

以下字段相对 params.update。
事件字段类型必填说明
plansessionUpdatestring是plan
planentriesarray(object)是完整计划快照,每次替换旧计划
planentries[].contentstring是步骤说明
planentries[].prioritystring是high、medium、low
planentries[].statusstring是pending、in_progress、completed
barn_file_msgsessionUpdatestring是barn_file_msg
barn_file_msgbarnIdstring是Barn 存储标识,不是下载 URL
barn_file_msgfilePathstring是文件路径
barn_file_msgmimeTypestring是MIME 类型
barn_file_msgsize非负 integer是文件大小,字节
输出目录中的文件不一定产生 barn_file_msg,完整产物仍需查询“会话产物”接口。

用户问题与回答

session/request_permission 的字段相对 params:
字段类型必填说明
sessionIdstring是运行时会话标识
toolCallobject是ToolCallUpdate,toolCallId 必填
optionsarray(object)是协议权限选项,不等于问题答案选项
options[].optionIdstring是权限选项标识
options[].namestring是选项名称
options[].kindstring是权限选项种类
toolCall.rawInput.questionsarray(object)条件字段当前问题提取器从此位置读取;不是每种工具输入都含 questions
questions[].questionstring是问题正文
questions[].headerstring否短标题
questions[].multi_selectboolean否是否多选
questions[].optionsarray(object)否业务答案选项;每项 label 必填,description 可选
推荐读取“会话状态”接口中的 pending_action,按其 tool_call_id 和问题顺序调用“回答问题”接口。不要把协议权限 options 直接作为该接口的 answers。 用户回答回显为 result/null/null,契约中的 result.answers 为可选二维字符串数组,每道题对应一组答案。result/null 是开放结果,先确认 answers 存在再解析;这不是回合结束信号,也不是回答请求体的格式。

一轮结束、执行错误与取消

位置字段类型/存在条件说明
resultstopReasonstring当前转换器据此判定 prompt_response;常见 end_turn、max_tokens、max_turn_requests、refusal、cancelled
resultfinal_messagestring/null,可省略最后连续文本,不代表完整回答;在工具调用后结束可能没有此字段
resultsessionUpdate契约声明必填 string契约值 prompt_response;当前实时转换仅检查 stopReason,实际结果可能没有 sessionUpdate,不能依赖它分派
params.updatesessionUpdatestringerror,表示执行错误通知
params.updatemessagestring,可省略执行错误说明
errorcodeintegerJSON-RPC 错误码
errormessagestringJSON-RPC 错误文字
errordata任意 JSON,可省略由生产者决定的错误上下文
params(session/cancel)sessionIdstring,可省略取消请求中的运行时会话标识,不单独证明取消完成
收到 prompt_response 后查询回合详情确认最终状态;stopReason=end_turn 本身不保证成功。业务失败与订阅错误分开处理。

控制帧字段

session_status

字段类型必填说明
session_idstring是当前会话 ID。 APP 会话 ID,供其他 APP 接口使用。
statusstring是当前会话状态,与查询会话接口一致;容忍未知值。
status_infostring否生产者提供的补充状态文字,不用于程序分支。

content_blocked

字段类型必填说明
session_idstring是需撤回内容的会话 ID。 APP 会话 ID,供其他 APP 接口使用。
turn_idstring否需撤回内容的回合 ID;收到时移除已展示的该回合内容。 所属回合 ID;回合外事件为 null。
reasonstring契约要求撤回原因,例如 content_safety_violation;开放枚举。运行时透传生产者字段,调用方需容错处理缺失。
状态和撤回帧由生产者消息转换得到,可能带有额外字段;不要将其当作固定封闭对象。控制帧不进入历史事件补流,断线期间的 content_blocked 不保证能重放。

done

字段类型必填说明
reasonstring是当前发送路径使用 session_terminated(会话结束,不再重连);契约还预留 idle_timeout、server_shutdown,但当前 handler 未发现对应发送路径。
final_seq_idinteger (int64)是连接结束时服务端处理水位;不应假定一定等于最近一个消息边界 SSE id。

error

字段类型必填说明
codestring是resync_required:需要分页补流;client_too_slow:消费过慢;internal_error:内部错误。未知值按流错误处理。
messagestring否供排查的错误文字,不解析其文本做程序判断。
resume_frominteger (int64)是服务端出错时的处理水位,不是数量。当前代码未区分完整消息边界,不能无条件覆盖客户端最后确认的边界游标。
poll_urlstring否resync_required 时提供的同源绝对路径,用于分页查询事件;其他错误通常省略。

完整连续示例

下面是按当前转换逻辑构造的协议示例,不是线上抓包。session-1、turn-1 等是便于阅读的占位标识,真实调用使用服务端返回值。工具不是每轮必经步骤,示例未展示其他可能出现的事件。

一轮工具执行与文本回答

: connected
retry: 2000

event: session_status
data: {"session_id":"session-1","status":"running"}

id: 10
event: session_event
data: {"id":"prompt-1","session_id":"session-1","turn_id":"turn-1","seq_id":10,"seq_ids":[10],"type":"method","method":"session/prompt","sub_type":null,"raw":{"jsonrpc":"2.0","method":"session/prompt","params":{"sessionId":"runtime-1","prompt":[{"type":"text","text":"计算 1+1"}],"_meta":{"event_id":"prompt-1","seq_id":10,"created_at":1792544400000,"turn_id":"turn-1"}}},"created_at":"2026-10-21T01:00:00.000000+00:00"}

id: 11
event: session_event
data: {"id":"tool-event-1","session_id":"session-1","turn_id":"turn-1","seq_id":11,"seq_ids":[11],"type":"method","method":"session/update","sub_type":"tool_call","raw":{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"runtime-1","update":{"sessionUpdate":"tool_call","toolCallId":"tool-1","title":"计算","kind":"execute","status":"in_progress","rawInput":{"expression":"1+1"}},"_meta":{"event_id":"tool-event-1","seq_id":11,"created_at":1792544400000,"turn_id":"turn-1"}}},"created_at":"2026-10-21T01:00:00.000000+00:00"}

id: 12
event: session_event
data: {"id":"tool-event-2","session_id":"session-1","turn_id":"turn-1","seq_id":12,"seq_ids":[12],"type":"method","method":"session/update","sub_type":"tool_call_update","raw":{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"runtime-1","update":{"sessionUpdate":"tool_call_update","toolCallId":"tool-1","status":"completed","content":[{"type":"content","content":{"type":"text","text":"2"}}]},"_meta":{"event_id":"tool-event-2","seq_id":12,"created_at":1792544400000,"turn_id":"turn-1"}}},"created_at":"2026-10-21T01:00:00.000000+00:00"}

event: session_event
data: {"id":"reply-1","session_id":"session-1","turn_id":"turn-1","seq_id":13,"seq_ids":[13],"type":"method","method":"session/update","sub_type":"agent_message_chunk","raw":{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"runtime-1","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"结果是"},"_meta":{"atom_id":"atom-1","target_event_id":"reply-1","is_final":false}},"_meta":{"event_id":"reply-1","seq_id":13,"created_at":1792544400000,"turn_id":"turn-1"}}},"created_at":"2026-10-21T01:00:00.000000+00:00"}

id: 14
event: session_event
data: {"id":"reply-1","session_id":"session-1","turn_id":"turn-1","seq_id":14,"seq_ids":[14],"type":"method","method":"session/update","sub_type":"agent_message_chunk","raw":{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"runtime-1","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"2。"},"_meta":{"atom_id":"atom-1","target_event_id":"reply-1","is_final":true}},"_meta":{"event_id":"reply-1","seq_id":14,"created_at":1792544400000,"turn_id":"turn-1"}}},"created_at":"2026-10-21T01:00:00.000000+00:00"}

id: 15
event: session_event
data: {"id":"result-1","session_id":"session-1","turn_id":"turn-1","seq_id":15,"seq_ids":[15],"type":"result","method":null,"sub_type":"prompt_response","raw":{"jsonrpc":"2.0","id":"request-1","result":{"stopReason":"end_turn","final_message":"结果是2。"},"_meta":{"event_id":"result-1","seq_id":15,"created_at":1792544400000,"turn_id":"turn-1"}},"created_at":"2026-10-21T01:00:00.000000+00:00"}

event: session_status
data: {"session_id":"session-1","status":"idle"}

: heartbeat
处理顺序:
  1. 本轮 Prompt 开始,保存边界 10。
  2. 展示工具执行和结果,保存边界 11、12。
  3. 收到 seq=13,追加“结果是”;没有 SSE id,恢复位置仍为 12。
  4. 收到 seq=14,追加“2。”;处理完成后保存边界 14。
  5. 收到 prompt_response,本轮已结束,查询回合详情确认最终状态。
  6. 会话进入 idle 后仍继续监听下一轮,不等待 done 才结束本轮展示。

断线后完整消息替换片段

假设收到 seq=13 后断线,从已确认边界 12 恢复。历史可能返回覆盖 13、14 的聚合消息:
id: 14
event: session_event
data: {"id":"reply-1","session_id":"session-1","turn_id":"turn-1","seq_id":13,"seq_ids":[13,14],"type":"method","method":"session/update","sub_type":"agent_message_chunk","raw":{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"runtime-1","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"结果是2。"}},"_meta":{"event_id":"reply-1","seq_id":13,"created_at":1792544400000,"turn_id":"turn-1","seq_ids":[13,14]}}},"created_at":"2026-10-21T01:00:00.000000+00:00"}
将 reply-1 的“结果是”替换为“结果是2。”,不能追加成“结果是结果是2。”。此时 data.seq_id=13,而 SSE id=14。

会话稍后终止

这是后续会话终止时的帧,不是每轮回答结束必发:
event: session_status
data: {"session_id":"session-1","status":"terminated"}

event: done
data: {"reason":"session_terminated","final_seq_id":15}

撤回与订阅错误的独立分支

以下两个分支是独立示例,不代表会发生在上面的成功流程之后:
event: content_blocked
data: {"session_id":"session-1","turn_id":"turn-1","reason":"content_safety_violation"}
event: error
data: {"code":"resync_required","message":"the stream requires history replay","resume_from":13,"poll_url":"/api/openapi/app/v1/sessions/session-1/events"}
错误中的 13 是处理水位。如果最后确认的消息边界是 12,不能直接用 13 覆盖它。

当前实现与恢复限制

按 event 分派消息;session_event 的 id 用于关联同一消息,seq_ids 用于区分片段和聚合结果,不能仅按业务 id 丢弃所有重复帧。先处理完整边界帧,再保存 SSE id。收到 done/session_terminated 后停止订阅;收到 error 或无终止帧的断线时结合查询会话状态、分页事件接口恢复。 当前恢复边界:错误帧的 resume_from 可能包含尚未完成的片段;Redis 窗口失效后,数据库最新序号查询也存在聚合覆盖末端未计入的边界。因此保留已确认的 SSE 消息边界,补流允许重放并按事件规则合并,不承诺任意断线下严格不重不漏。分页接口的 next_cursor 用于其自身翻页,不能假定与 SSE 消息边界 id 完全等价。本次仅补文档,不修改恢复算法。 当前消息边界判断依赖生产者的 atom_id/is_final 标记;标记缺失时实现按独立消息边界处理。_meta 无稳定兼容保证,客户端仍应以服务端 SSE id 为恢复依据。