文档中心
费用中心控制台

智能体接入 API 更新日志 ​

连接 AI 助手

本页按发布日期记录智能体开发服务平台（AgentWorks）供应用调用智能体的接口变更，覆盖 HTTP 和 WebSocket，并说明客户端需要做的调整。

不兼容变更速查 ​

使用以下旧接口或处理方式的客户端需要修改。选择对应条目查看变化和替代用法：

下文的 Bridge v1、Bridge v2 分别指使用 infini.bridge.v1、infini.bridge.v2 子协议的接入方式，用于区分旧客户端和新客户端。

2026-09-16 和 2026-09-24 没有更换请求格式或鉴权方式，但仍需检查回放与重连处理和自动重试事件。跨多次发布升级时，不要只检查接口移除项。

升级路径速查 ​

记录范围从 2026-09-15 开始，以下路径以 2026-09-24 发布为目标。更早发布的 API 变化不在本页覆盖范围内，不能根据这里没有记录就判断旧客户端兼容。

根据原客户端的接入方式和已适配的发布选择入口；不知道发布日期时，可以根据端点、子协议和请求格式识别接入方式。

客户端起点需要核对的发布修改入口
已适配 2026-09-16 的 Bridge v22026-09-24检查自动重试事件，无需修改地址或握手
已适配 2026-09-15 的 Bridge v22026-09-16、2026-09-24检查回放、重连和重试处理，无需重做 v1 迁移
旧 Bridge v1，通过 WebSocket 发送 message本页三次发布从迁移指南的 Bridge v1 起点直接修改到目标接口
旧 Direct Invoke，包括同步返回和 SSE本页三次发布从迁移指南的 Direct Invoke 起点调整接入，继续完成同页的事件与恢复处理
已使用 Bridge v2，但不清楚适配了哪次发布本页三次发布对照协议变化确认接入，再检查后续回放、重连和自动重试变化

旧 Invoke 调用方需要迁移原有的实例调用凭证；旧 Bridge 调用方则已使用绑定渠道账号的 wst_ Token，两者不要混用凭证步骤。更早或无法识别的接入，可对照原接入方式与字段，确认起点后再迁移。

跨多次发布升级时，核对起点之后、截至目标发布的所有相关变化，按目标接口一次完成修改；若后续条目已替代先前做法，以目标发布适用的做法为准。这不等于必须逐版安装平台或先实现已过时的中间客户端。

版本号和“必须修改”等标签的含义见版本与兼容性；完整接口用法见 API 参考。

2026-09-24：自动重试与错误信息 ​

本次影响 Bridge v2 的运行事件处理。HTTP 方法、请求格式、鉴权、/ws/v1 路径和 infini.bridge.v2 子协议均不变，没有移除或弃用现有业务接入接口。

客户端行动：保留现有提交和订阅代码，检查自动重试是否仍按“运行中”处理。 不要把带有错误原因的重试事件当作任务失败，也不要看到重试提示就再次提交原消息。

新增 ​

运行事件增加自动重试状态和可选的结构化错误信息。

自动重试事件 ​

  • 按用法检查。 影响解析 ev.d.lifecycle、显示进度或拼接业务结果的客户端。
  • 新增内容：lifecycle.phase = retry 表示平台正在自动重试。lifecycle.error.retry_info 可提供 fault_scope、run_attempt、max_retries 和 retry_checkpoint_id；lifecycle.error.code 可提供错误码。这些字段可能缺省，应保留不带次数的重试提示和未知错误的处理。
  • 处理建议：fault_scope = step 表示重试某次模型或工具调用，整次任务仍在运行；task 表示任务级重试。任务级重试不再发送新的 graph_start，仍对应原请求的 mid。将失败尝试的中间输出标记为作废或折叠，继续接收后续输出；只有主智能体的 success、error 或 cancelled 才结束等待。字段与示例见自动重试与错误信息。

变更 ​

任务失败后保留本次运行的上下文，方便查看失败位置和继续处理。

失败后的会话与业务操作 ​

  • 按用法检查。 影响在失败后继续同一会话，或自动重新提交业务任务的应用。
  • 变化：失败不再把上下文恢复成运行前的状态。后续对话可以继续使用失败尝试中留下的信息；这不表示外部写入已经撤销。
  • 处理建议：继续任务前先核对工具和业务系统中的实际结果。需要不沿用失败尝试的新对话时，创建新的业务 chat_id。自动重试期间仍保存已执行工具的处理记录，避免重复写入。见处理重试和失败后的上下文。

客户端检查 ​

在测试实例中启用相应容错设置，并确认：

  • 收到 retry 后仍接收原请求的事件，没有重新发送 SendMessage，也没有提前执行下一步业务流程。
  • 任务级重试前已显示的作废输出不会拼入最终业务结果；单步重试不会清空整个会话。
  • 停止、失败或取消后，应用结束对应请求的等待，旧中断不再提供可执行入口；外部操作结果另外核对。

2026-09-16：回放与重连修复 ​

比较范围为 2026-09-15 发布到本次发布，影响 Bridge v2 的历史回放和断线恢复。HTTP 方法、请求和帧字段、鉴权方式、/ws/v1 路径及 infini.bridge.v2 子协议均不变，本次没有新增、弃用或移除业务接入接口。

客户端行动：无需更换地址、凭证类型或请求格式；检查回放合并和游标重置处理。 如果客户端依赖“一帧对应一个原始文本增量”、要求 seq 连续或拒绝较小的重置游标，需要调整这些假设。

变更 ​

历史回放的帧数可能减少，客户端应按文本内容而不是帧数还原消息。

合并历史回放中的文本增量 ​

  • 按用法检查。 影响 WebSocket 历史回放中的回复文本和思考文本增量。
  • 变化：此前历史回放逐个发送文本增量；本次可将同一消息相邻的多个回复文本增量合并发送，思考文本单独合并。工具调用、工具结果、中断及生命周期事件不参与合并，实时输出方式不变。合并帧的外层 seq 使用最后一个原始事件的序号，最终文本不变。
  • 处理建议：依赖“一帧对应一个原始增量”或要求 seq 连续的客户端需调整；继续按消息追加文本，不按帧数计算消息数。序号此前也不保证连续。见消息和运行事件。

修复 ​

以下修复改善历史回放和断线恢复；已有的 reset 与 backpressure 处理仍需保留。

游标失效后可以恢复事件接收 ​

  • 按用法检查。 影响通过 since_seq 恢复订阅及处理 reset 的客户端。
  • 修复内容：修复客户端游标高于服务端现有事件位置时，订阅后无法继续收到事件的问题。服务端使用已有的 reset 通知重新同步；这是已有恢复机制的修复，不是新增帧类型。
  • 处理建议：收到 reset 后不再用旧游标过滤事件；reset.d.cursor 缺失时以 0 为恢复起点。同步历史期间暂存随后收到的事件，恢复后合并、去重。正常订阅会继续回放，不要求每次 reset 都重新订阅。见心跳、重连与补偿。

减少大量历史回放引起的断开 ​

  • 无需修改现有调用。 影响大量历史事件的回放，不改变 backpressure 错误格式或恢复方式。
  • 修复内容：此前大量历史事件可能因瞬间填满发送队列而断开；本次改善了这种情况。若客户端持续无法及时接收，仍可能收到 err.d.reason = backpressure 后断开。
  • 处理建议：保留按已处理游标重连的逻辑；收到此错误时检查接收速度，不要重新提交原业务消息。错误分支按 reason 判断，不依赖 message 文案。见 WebSocket 错误处理。

客户端检查 ​

用已有测试会话确认以下结果，无需修改已经正确实现的处理逻辑：

  • 实时输出和历史回放得到相同文本，合并增量不会导致漏字或重复。
  • 重连和 reset 后可以继续收到事件；保留已执行业务工具的去重记录，避免重复写入。

日常恢复规则统一见心跳、重连与补偿。

2026-09-15：业务接入接口不兼容升级 ​

比较基线为本次发布前的旧 Direct Invoke、Bridge v1 接入，目标为 2026-09-15 发布的 Bridge v2 接入。旧 Direct Invoke 不再作为本次发布的业务接入入口。消息提交改为 HTTP，WebSocket 改为订阅指定会话；不是仅替换地址或子协议名称就能完成的升级。

客户端行动：旧 Direct Invoke 和 Bridge v1 客户端必须迁移。 按旧版接入迁移指南区分起点并完成修改；该指南已合并截至 2026-09-24 的迁移要求。后续行为差异见回放和重连变化及自动重试事件。

新增 ​

新的业务接入方式通过 HTTP 提交消息，通过 WebSocket 订阅回复和运行事件。

HTTP 接口和会话订阅 ​

  • 必须修改（旧客户端）。 旧 Direct Invoke 和 Bridge v1 客户端需要采用新的消息提交与事件接收方式。
  • 新增内容：新增 HTTP SendMessage、RespondInterrupt、CancelRun、GetIdentity、ListMessages、ListPendingInterrupts；WebSocket 新增会话订阅、事件游标续传和 reset 恢复。
  • 处理建议：先迁移消息提交和会话订阅；取消运行、查询历史和查询待处理中断按应用需要接入。见修改消息提交和建立会话订阅。

新会话通知 ​

  • 按用法检查。opened 帧用于通知服务端新开启的会话，例如定时任务或子代理会话。
  • 处理建议：需要展示这类会话时，在收到通知后发送 sub 接收该会话事件；通知不提供离线补发保证。见控制回复和会话通知。

移除 ​

以下旧入口及帧用法已移除，不是“已弃用但仍可继续使用”的兼容入口。

旧 Direct Invoke 入口 ​

  • 必须修改。 影响通过旧实例调用接口接入的应用，包括同步返回和 SSE 用法。
  • 处理建议：从Direct Invoke 迁移起点建立 WebSocket 渠道账号和接入凭证，再完成同页的请求与事件处理。不能只替换原请求地址或凭证前缀。

连接后鉴权 ​

  • 必须修改。 影响发送 auth 或等待 auth_ok 的旧 Bridge 客户端。
  • 变化：旧版连接后发送 auth、等待 auth_ok 的流程被移除，客户端改为握手鉴权，并以 hello 确认就绪。子协议由 infini.bridge.v1 改为 infini.bridge.v2；路径仍为 /ws/v1。
  • 处理建议：旧 Bridge 调用方继续使用有效的 wst_ Token，无需换成 IAM 用户 Token 或改用 infini.bff.v1。握手后的时间字段由 auth_ok.server_time（Unix 纳秒）变为 hello.d.server_time（Unix 毫秒）。见迁移 Bridge v1 鉴权。

WebSocket 消息上行帧 ​

  • 必须修改。 影响使用 WebSocket message 帧发送业务消息的客户端。
  • 变化：WebSocket message 上行帧被移除，改为 HTTP SendMessage。message.meta 中的字段移到请求体根部，移除 type、message 等旧包装字段；新请求拒绝未知字段。
  • 处理建议：改用 HTTP 提交后，同时检查 HTTP 状态和 success_response，保存返回的消息及会话标识。见迁移消息提交。

WebSocket 中断响应上行帧 ​

  • 必须修改。 影响通过 WebSocket interrupt_response 帧回传审批或工具结果的客户端。
  • 变化：旧帧被移除，改为 HTTP RespondInterrupt。APPROVE、REJECT、RESPOND、ERROR 四种动作保持不变。
  • 处理建议：从 pending 事件取得待处理项，并保留原请求与会话的关联，再通过 HTTP 回传。见迁移中断响应。

变更 ​

以下变化影响旧客户端的会话路由、事件解析和连接管理，仅改用 HTTP 发消息还不够。

按会话订阅，默认会话类型改为 group ​

  • 必须修改。 影响依赖账号内广播的旧 Bridge 客户端；省略 chat_type 的请求还需核对会话归属。
  • 变化：接收范围由渠道账号内广播改为按会话订阅；客户端用服务端返回的会话标识执行 sub，用 unsub 取消订阅。默认 chat_type 从 p2p 改为 group，省略该字段的旧客户端需要核对会话处理。
  • 处理建议：明确指定需要的会话类型并建立订阅。继续使用 p2p 的客户端不能直接套用 group 的会话标识获取流程。见确认会话范围和建立会话订阅。

事件结构和运行结束判定 ​

  • 必须修改。 影响按旧 type 帧结构解析回复、工具事件和结束状态的客户端。
  • 变化：帧结构从 type 加负载字段，改为 t、sid、seq、mid、sub、d。客户端按 sid 关联会话、按 mid 关联请求；旧 message_stream_reply.done 改为主智能体的 lifecycle.phase 终态 success、error 或 cancelled。
  • 工具字段：工具调用参数由 tool_call.arguments 改为 tool_call.args，结果由 tool_call_result 改为 message_delta.tool_result。
  • 处理建议：更新帧解析与字段映射，用主智能体的运行终态判断完成。见迁移事件处理。

错误与心跳处理 ​

  • 必须修改。 影响统一按旧 error 帧处理失败，或使用旧应用层心跳的客户端。
  • 错误处理：旧版单一 error 帧处理需要区分 HTTP 请求失败、subd 订阅失败、err 连接错误，以及 lifecycle 运行失败。HTTP 200 也可能携带业务失败结果，不能只凭状态码判定成功。
  • 心跳格式：应用层心跳由 {"type":"PING"} 改为 {"t":"PING"}，客户端库仍需正常响应协议层 ping。
  • 处理建议：分别处理请求、订阅、连接和运行失败，并更新应用层心跳格式。见迁移错误与重连处理。

客户端迁移 ​

按迁移指南修改后，旧 Direct Invoke 和 Bridge v1 客户端都应完成迁移验证清单，核对消息与会话关联、运行终态、中断响应和断线恢复。

本次列出的旧鉴权及上行帧用法已移除，不是“已弃用但仍可继续使用”的兼容入口。历史变化用于判断迁移工作，目标接口的完整字段和限制以 API 参考为准。