Skip to main content

会话 WebSocket

千问办公企业旗舰版开发者文档:会话 WebSocket。

认证方式见APP开发者文档 → 认证接入。
  • 接口:GET/api/openapi/app/v1/sessions/chat-ws

用途

浏览器通过认证接入中的 createAppWebSocket 建立连接;服务端继续使用原有握手认证方式。连接后的消息协议不变。 建立双向会话连接,加入一个会话后接收历史重放、实时 ACP 事件和会话控制通知。单条连接同一时刻跟随一个会话;加入另一个会话会离开原会话。用户级跨会话通知使用独立的 notify-ws。 不要在 URL 中传 Token,也不要从浏览器构造可信身份 Header。HTTPS 页面使用 WSS。握手成功返回 101;认证、授权或服务不可用时握手失败,浏览器可能只暴露 error/1006,应通过现有 IAM 会话查询确认身份,不解析浏览器错误文字。

消息信封

字段类型说明
typestringcontrol:控制层;data:ACP 会话事件
payloadobjectJSON-RPC 2.0 对象。请求带 id/method/params,响应带相同 id 和 result 或 error;通知通常无 id
seqinteger,可省略data 帧的事件序号(发送路径提供时)。不要求连续;不能与 SSE 的 id 或 HTTP 分页 next_cursor 混用
payload.errorobjectcode、message、可选 data;控制失败与任务执行失败分开处理
字段为 camelCase;不要直接把 HTTP APP 接口的 snake_case 请求体发送到 WS。未知通知和扩展字段应容错。

加入、重放与实时订阅

发送 control/join,params.sessionId 为已有会话 ID,params.lastSeqId 为客户端确认消费的位置;首次使用 0。不要将仅收到但尚未处理的数据记为已消费。
{"type":"control","payload":{"jsonrpc":"2.0","id":"join-1","method":"join","params":{"sessionId":"session-1","lastSeqId":0}}}
正常顺序为 replay_start → data 历史帧 → replay_end → 状态快照 → join_ack,然后跟随实时事件。join_ack 是 method 通知,不要只等待具有请求 id 的 result。
控制消息关键字段 / 行为
replay_start、replay_end历史重放阶段边界,按 SDK 协议处理,不能把重放事件当成新消息重复追加
join_ackparams.sessionId、currentSeqId、accepted;accepted 表示接入,不表示任务完成
session_status会话状态变化;结合会话详情中的 current_turn、pending_action 刷新运行和待回答状态
sandbox_status沙箱生命周期变化;刷新相关沙箱展示
refresh_prompt_queue重新查询待执行消息队列
content_blocked撤回被标记的内容;不能仅提示错误而继续展示被撤回正文
ping、pong应用层心跳,使用 control 信封
data.payload 保留 ACP JSON-RPC:session/update 携带 agent_message_chunk、agent_thought_chunk、tool_call、tool_call_update、plan、session_info_update 等;session/request_permission 表示需要用户交互。result.stopReason 表示回合结束,不表示整个会话终止。按事件 ID、序号及聚合覆盖范围合并重放;工具更新为局部更新,不清空未提供字段。完整业务字段见“订阅实时事件”页,但 WS 信封和 SSE 信封不同。

发送操作

在 join_ack 接受后发送。控制请求使用唯一 id;ACK 表示受理,最终执行结果由后续事件和查询确认。
methodparams说明
new_promptsessionId、text;可选 fileInfoList(每项 fileName、ossId)提交输入;ossId 是已存在文件路径,不是上传接口。new_prompt_ack 可含 promptId、turnId、accepted
cancelsessionId请求取消当前执行;cancel_ack 不等于任务已停止
question_responsesessionId、toolCallId、outcome、optionId、updatedInput回答待处理交互。updatedInput 含 questions 与 answers;questions 项含 question/header/options/multiSelect,answers 为问题到答案字符串的映射。使用 SDK 适配,不直接复制 HTTP question-response 的 answers 格式
leavesessionId离开当前订阅;返回 result.sessionId,不删除会话、不取消任务
{"type":"control","payload":{"jsonrpc":"2.0","id":"prompt-1","method":"new_prompt","params":{"sessionId":"session-1","text":"分析这份数据"}}}
本页描述 APP 会话接入,不把实现中的其他运行时扩展视为已开放能力。HTTP + SSE 客户端继续使用文档中的 prompt、cancel、question-response 等 HTTP 操作;同一操作只选择一条发送路径。断线且未收到 ACK 时先查询服务端状态,不自动重发有副作用的操作。

心跳、错误和恢复

收到 control/ping 时发送下列消息;客户端也可主动 ping 并等待 pong。客户端实现可采用 30 秒 ping、10 秒等待回复;服务端间隔由部署配置决定,不能假定固定值。
{"type":"control","payload":{"jsonrpc":"2.0","method":"pong"}}
关闭情况客户端行为
1000正常关闭;结合会话状态决定是否还需订阅
1001、异常断线/1006、1013有上限的指数退避并加随机抖动;重连后重新 join、补历史
4001、1008认证过期或访问策略拒绝;停止自动重试,交由 IAM 登录/权限处理
4002会话不存在;停止订阅并刷新列表
4003、4008容量限制或限流;退避,不快速循环重连
4009历史代次失效;清理对应历史与游标,再重新加载
重放不等于严格恰好一次交付;客户端必须去重。退出登录、切换用户/组织、卸载应用时关闭旧连接并丢弃旧回调。不会因网络断开自动取消服务端任务。

消息交互示例

以下使用同一个示例会话 ID;实际接入时替换为当前用户拥有的会话 ID。每个代码块是一条独立 WebSocket 文本消息,示例省略其他历史帧和状态快照,不表示完整消息序列。

加入确认与文本增量

客户端先发送上文的 join 请求。服务端完成历史重放和状态快照后,发送加入确认通知:
{"type":"control","payload":{"jsonrpc":"2.0","method":"join_ack","params":{"sessionId":"session-1","currentSeqId":12,"accepted":true}}}
随后收到的文本增量示例:
{"type":"data","seq":13,"payload":{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"session-1","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"正在分析数据。"}}}}}
客户端解码外层 type,再处理 payload 的 ACP 事件;成功合并该事件后才能保存已消费序号 13。currentSeqId 是服务端水位,不能直接当作客户端已经消费的位置。文本增量也不表示回合已经完成。

断线续接

假设客户端已成功消费到序号 13,重新建立连接后发送:
{"type":"control","payload":{"jsonrpc":"2.0","id":"join-2","method":"join","params":{"sessionId":"session-1","lastSeqId":13}}}
服务端用以下两条控制通知标记重放边界,中间可能有 data 帧:
{"type":"control","payload":{"jsonrpc":"2.0","method":"replay_start","params":{"sessionId":"session-1"}}}
{"type":"control","payload":{"jsonrpc":"2.0","method":"replay_end","params":{"sessionId":"session-1"}}}
重放期间仍执行去重和聚合合并;重放结束后继续接收状态快照和 join_ack。若断线前的 new_prompt 是否受理不明确,先查询会话与消息状态,不随 join 自动重发输入。