千问办公企业旗舰版开发者文档:订阅实时事件。
认证方式见APP开发者文档 → 认证接入。
重连使用新 Token 并保留已确认的事件游标,不把 Token 放到 URL。
媒体类型:
本接口持续返回 SSE 文本。每个空行结束一帧,data 才是 JSON;网络读取块不等于完整的一帧。
一轮执行结束看 prompt_response,会话终止看 done/session_terminated。 一轮结束后会话仍能接收下一条 Prompt,SSE 可继续保持。业务事件中的 error 也不等于 SSE 的 error:前者描述执行问题,后者描述订阅故障。
按外层 session_id、turn_id 调用 APP 接口。raw 内的 sessionId 是运行时标识,不能直接替代它们。
每帧以空行结束。
以下路径相对 data.raw。session/update 的子类型由 params.update.sessionUpdate 指定;未识别的事件应容错,不能让整个订阅失败。并非每轮都会出现所有类型。
同一业务 id 的实时文本片段按序号追加,重复片段不重复展示。历史聚合对象覆盖多个 seq_ids 时替换该 id 已展示的文本,不能再次追加。非文本 ContentBlock 可为图像、音频、资源引用或嵌入资源;不支持的类型应降级展示,不能直接读取 text。
下表字段相对 params.update。tool_call 必填 toolCallId/title;tool_call_update 仅 toolCallId 必填,其他字段是局部更新,未携带的字段保持原值。
以下字段相对 params.update。
输出目录中的文件不一定产生 barn_file_msg,完整产物仍需查询“会话产物”接口。
session/request_permission 的字段相对 params:
推荐读取“会话状态”接口中的 pending_action,按其 tool_call_id 和问题顺序调用“回答问题”接口。不要把协议权限 options 直接作为该接口的 answers。
用户回答回显为 result/null/null,契约中的 result.answers 为可选二维字符串数组,每道题对应一组答案。result/null 是开放结果,先确认 answers 存在再解析;这不是回合结束信号,也不是回答请求体的格式。
收到 prompt_response 后查询回合详情确认最终状态;stopReason=end_turn 本身不保证成功。业务失败与订阅错误分开处理。
状态和撤回帧由生产者消息转换得到,可能带有额外字段;不要将其当作固定封闭对象。控制帧不进入历史事件补流,断线期间的 content_blocked 不保证能重放。
下面是按当前转换逻辑构造的协议示例,不是线上抓包。session-1、turn-1 等是便于阅读的占位标识,真实调用使用服务端返回值。工具不是每轮必经步骤,示例未展示其他可能出现的事件。
处理顺序:
假设收到 seq=13 后断线,从已确认边界 12 恢复。历史可能返回覆盖 13、14 的聚合消息:
将 reply-1 的“结果是”替换为“结果是2。”,不能追加成“结果是结果是2。”。此时 data.seq_id=13,而 SSE id=14。
这是后续会话终止时的帧,不是每轮回答结束必发:
以下两个分支是独立示例,不代表会发生在上面的成功流程之后:
错误中的 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 为恢复依据。
- 模块:会话服务(session)
- 接口:GET
/api/openapi/app/v1/sessions/{session_id}/events/stream
请求参数
重连使用新 Token 并保留已确认的事件游标,不把 Token 放到 URL。
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| session_id | path | string | 是 | APP 会话 ID,供其他 APP 接口使用。 |
| cursor | query | integer (int64) | 否 | 从此位置之后恢复;省略或空值仅订阅后续事件,0 请求从会话开头补流。优先使用已处理的消息边界 SSE id;不要要求序号连续。与 Last-Event-ID 同时传入时必须一致,否则 422。 |
| Last-Event-ID | header | integer (int64) | 否 | SSE 恢复位置。使用 fetch 的客户端成功处理 session_event 后保存该帧显式 id,在重连请求中自行设置本头;不加一、不要求序号连续。与 cursor 同传必须一致,否则 422。 |
| include_status | query | boolean | 否 | 默认 true;false 仅抑制 session_status,不抑制 session_event、content_blocked、done、error。 |
响应
| HTTP | 说明 |
|---|---|
| 200 | 请求成功 |
| default | 错误响应。按 code 判断具体错误,不能仅依赖 HTTP 状态码,多种错误可能共用状态码。 |
text/event-stream。
如何阅读一条 SSE 消息
本接口持续返回 SSE 文本。每个空行结束一帧,data 才是 JSON;网络读取块不等于完整的一帧。
| 层次 | 判别字段 | 含义 |
|---|---|---|
| SSE 帧 | event | session_event 为业务事件;其余为状态、撤回、结束、订阅错误 |
| APP 业务事件 | data.type / method / sub_type | 判断是文本、工具调用、问题还是回合结果 |
| Agent 载荷 | data.raw | method 消息读取 params,结果读取 result,协议错误读取 error |
四种标识不要混用
| 标识 | 用途 |
|---|---|
| SSE id | 完整消息边界的恢复位置,处理完成后保存 |
| data.id | 业务消息标识;同一文本的片段与聚合消息可共用 |
| data.seq_id | 当前事件对象覆盖的起始序号 |
| data.seq_ids | 当前对象覆盖的全部序号;聚合消息可以覆盖多个序号 |
帧包装与公共字段
每帧以空行结束。event 表示消息类型,data 是该类型的 JSON 对象;id 是可选的恢复位置,不等于 JSON 中业务事件的 id。
| 字段 | 类型 | 说明 |
|---|---|---|
| event | string | session_event、session_status、content_blocked、done 或 error。 |
| data | JSON object | 结构见下方对应字段表。 |
| id | 十进制整数字符串,可省略 | 仅 session_event 的消息边界帧发送。处理中间文本片段时通常省略;收到边界且处理完成后保存。 |
| retry | integer | 初始连接发送 2000,单位毫秒,供支持此字段的 SSE 客户端决定重连间隔。 |
: connected 和 : heartbeat 是 SSE 注释,不是 JSON 事件,也不更新业务游标。连接断开不等于任务结束;只有明确的状态和终止帧能说明会话生命周期。
session_event:Event
| 字段 | 类型 | 必填 | 契约说明 |
|---|---|---|---|
| created_at | string | 是 | 记录时间;排序使用序号。有时间元数据时为 ISO 8601,实时消息缺少时间元数据时当前实现返回空字符串。 |
| id | string | 是 | 业务消息标识;同一消息的多个片段及历史聚合对象可共用。 |
| method | string / null | 是 | method 类的协议方法;result/error 时为 null。 |
| raw | object | 是 | 原始 Agent 协议消息;method 读 params、结果读 result、协议错误读 error。详见下方业务载荷字段。 |
| seq_id | integer | 是 | 此对象覆盖的起始序号;聚合消息不能只用它作为恢复位置。 |
| seq_ids | array<integer> | 是 | 对象覆盖的序号。单片段追加内容;同一 id 的聚合完整消息替换已有片段。最大值是覆盖末端,但实时片段尚不一定构成可恢复边界,持久化恢复位置应使用 SSE id。序号可能因过滤而跳跃。 |
| session_id | string | 是 | APP 会话 ID,供其他 APP 接口使用。 |
| sub_type | string / null | 是 | session/update 的 sessionUpdate,或带 stopReason 结果对应的 prompt_response;其他情况可为 null。 |
| turn_id | string / null | 是 | 所属回合 ID;回合外事件为 null。 |
| type | string | 是 | raw 的 JSON-RPC 类别:method、result、error。 |
常用业务事件的载荷字段
以下路径相对 data.raw。session/update 的子类型由 params.update.sessionUpdate 指定;未识别的事件应容错,不能让整个订阅失败。并非每轮都会出现所有类型。
| 场景 | type / method / sub_type | 载荷位置 |
|---|---|---|
| 本轮输入 | method / session/prompt / null | params |
| 回复文本 | method / session/update / agent_message_chunk | params.update |
| 思考内容(运行时提供时) | method / session/update / agent_thought_chunk | params.update |
| 工具调用、进度结果 | method / session/update / tool_call、tool_call_update | params.update |
| 执行计划快照 | method / session/update / plan | params.update |
| 文件产物 | method / session/update / barn_file_msg | params.update |
| 请求用户回答 | method / session/request_permission / null | params |
| 用户回答回显 | result / null / null | result |
| 一轮结束 | result / null / prompt_response | result |
| 执行错误通知 | method / session/update / error | params.update |
| JSON-RPC 错误 | error / null / null | error |
| 取消请求 | method / session/cancel / null | params |
输入和文本内容
| 字段 | 类型 | 必填/条件 | 说明 |
|---|---|---|---|
| params.sessionId | string | session/prompt 必填 | 运行时会话标识 |
| params.prompt | array(object) | session/prompt 必填 | 输入内容块数组;文本块包含 type=text、text=输入文字 |
| update.sessionUpdate | string | 文本事件 | agent_message_chunk 或 agent_thought_chunk |
| update.content | object | 文本事件必填 | 一个 ContentBlock,不能假定所有内容块都是文字 |
| update.content.type | string | 内容块判别字段 | text 表示文本;其他类型按对应内容块处理 |
| update.content.text | string | type=text 时必填 | 当前片段或聚合消息的文本 |
| update.content.annotations | object/null | 可选 | 内容注解 |
| update._meta | object/null | 可选 | 扩展元数据,无稳定兼容保证;客户端使用 SSE id,不自行依赖内部标记推算恢复位置 |
工具调用与更新
下表字段相对 params.update。tool_call 必填 toolCallId/title;tool_call_update 仅 toolCallId 必填,其他字段是局部更新,未携带的字段保持原值。
| 字段 | 类型 | 说明 |
|---|---|---|
| sessionUpdate | string | tool_call 或 tool_call_update |
| toolCallId | string | 会话内工具调用标识,用于合并后续更新 |
| title | string;更新可为 null | 工具调用展示标题 |
| kind | string;更新可为 null | read、edit、delete、move、search、execute、think、fetch、switch_mode、other |
| status | string;更新可为 null | pending、in_progress、completed、failed;不代表整个回合状态 |
| rawInput / rawOutput | 任意 JSON | 工具自定义输入输出,没有统一业务字段,不保证是文字 |
| content | array(object);更新可为 null | 工具产出;更新携带时替换该集合 |
| locations | array(object);更新可为 null | 受影响文件位置;更新携带时替换该集合 |
| locations[].path | string | 必填文件路径 |
| locations[].line | integer/null | 可选行号 |
| content[].type | 子字段 | 说明 |
|---|---|---|
| content | content(必填 ContentBlock) | 文本需先确认 content.type=text,再取 content.text |
| diff | path、newText(必填);oldText(可选,可为 null) | 文件路径、新旧内容 |
| terminal | terminalId(必填 string) | 终端标识;此事件不提供终端读取接口 |
计划和文件产物
以下字段相对 params.update。
| 事件 | 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| plan | sessionUpdate | string | 是 | plan |
| plan | entries | array(object) | 是 | 完整计划快照,每次替换旧计划 |
| plan | entries[].content | string | 是 | 步骤说明 |
| plan | entries[].priority | string | 是 | high、medium、low |
| plan | entries[].status | string | 是 | pending、in_progress、completed |
| barn_file_msg | sessionUpdate | string | 是 | barn_file_msg |
| barn_file_msg | barnId | string | 是 | Barn 存储标识,不是下载 URL |
| barn_file_msg | filePath | string | 是 | 文件路径 |
| barn_file_msg | mimeType | string | 是 | MIME 类型 |
| barn_file_msg | size | 非负 integer | 是 | 文件大小,字节 |
用户问题与回答
session/request_permission 的字段相对 params:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sessionId | string | 是 | 运行时会话标识 |
| toolCall | object | 是 | ToolCallUpdate,toolCallId 必填 |
| options | array(object) | 是 | 协议权限选项,不等于问题答案选项 |
| options[].optionId | string | 是 | 权限选项标识 |
| options[].name | string | 是 | 选项名称 |
| options[].kind | string | 是 | 权限选项种类 |
| toolCall.rawInput.questions | array(object) | 条件字段 | 当前问题提取器从此位置读取;不是每种工具输入都含 questions |
| questions[].question | string | 是 | 问题正文 |
| questions[].header | string | 否 | 短标题 |
| questions[].multi_select | boolean | 否 | 是否多选 |
| questions[].options | array(object) | 否 | 业务答案选项;每项 label 必填,description 可选 |
一轮结束、执行错误与取消
| 位置 | 字段 | 类型/存在条件 | 说明 |
|---|---|---|---|
| result | stopReason | string | 当前转换器据此判定 prompt_response;常见 end_turn、max_tokens、max_turn_requests、refusal、cancelled |
| result | final_message | string/null,可省略 | 最后连续文本,不代表完整回答;在工具调用后结束可能没有此字段 |
| result | sessionUpdate | 契约声明必填 string | 契约值 prompt_response;当前实时转换仅检查 stopReason,实际结果可能没有 sessionUpdate,不能依赖它分派 |
| params.update | sessionUpdate | string | error,表示执行错误通知 |
| params.update | message | string,可省略 | 执行错误说明 |
| error | code | integer | JSON-RPC 错误码 |
| error | message | string | JSON-RPC 错误文字 |
| error | data | 任意 JSON,可省略 | 由生产者决定的错误上下文 |
| params(session/cancel) | sessionId | string,可省略 | 取消请求中的运行时会话标识,不单独证明取消完成 |
控制帧字段
session_status
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| session_id | string | 是 | 当前会话 ID。 APP 会话 ID,供其他 APP 接口使用。 |
| status | string | 是 | 当前会话状态,与查询会话接口一致;容忍未知值。 |
| status_info | string | 否 | 生产者提供的补充状态文字,不用于程序分支。 |
content_blocked
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| session_id | string | 是 | 需撤回内容的会话 ID。 APP 会话 ID,供其他 APP 接口使用。 |
| turn_id | string | 否 | 需撤回内容的回合 ID;收到时移除已展示的该回合内容。 所属回合 ID;回合外事件为 null。 |
| reason | string | 契约要求 | 撤回原因,例如 content_safety_violation;开放枚举。运行时透传生产者字段,调用方需容错处理缺失。 |
done
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reason | string | 是 | 当前发送路径使用 session_terminated(会话结束,不再重连);契约还预留 idle_timeout、server_shutdown,但当前 handler 未发现对应发送路径。 |
| final_seq_id | integer (int64) | 是 | 连接结束时服务端处理水位;不应假定一定等于最近一个消息边界 SSE id。 |
error
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | string | 是 | resync_required:需要分页补流;client_too_slow:消费过慢;internal_error:内部错误。未知值按流错误处理。 |
| message | string | 否 | 供排查的错误文字,不解析其文本做程序判断。 |
| resume_from | integer (int64) | 是 | 服务端出错时的处理水位,不是数量。当前代码未区分完整消息边界,不能无条件覆盖客户端最后确认的边界游标。 |
| poll_url | string | 否 | resync_required 时提供的同源绝对路径,用于分页查询事件;其他错误通常省略。 |
完整连续示例
下面是按当前转换逻辑构造的协议示例,不是线上抓包。session-1、turn-1 等是便于阅读的占位标识,真实调用使用服务端返回值。工具不是每轮必经步骤,示例未展示其他可能出现的事件。
一轮工具执行与文本回答
- 本轮 Prompt 开始,保存边界 10。
- 展示工具执行和结果,保存边界 11、12。
- 收到 seq=13,追加“结果是”;没有 SSE id,恢复位置仍为 12。
- 收到 seq=14,追加“2。”;处理完成后保存边界 14。
- 收到 prompt_response,本轮已结束,查询回合详情确认最终状态。
- 会话进入 idle 后仍继续监听下一轮,不等待 done 才结束本轮展示。