文档中心

Appearance

✨费用中心控制台

通过 WebSocket 接入智能体 ​

WebSocket 接入适合把自有消息系统连接到智能体。连接采用 Bridge 协议 infini.bridge.v1，支持双向消息、流式响应、工具事件、中断和心跳。本文用于创建渠道账号、完成接入并验证运行；帧字段、鉴权方式和错误码见 WebSocket API 参考。

创建 WebSocket 渠道账号 ​

按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。

  1. 打开 渠道账号。

    打开渠道账号

    也可以从控制台左侧导航进入 渠道账号。

  2. 选择 新建账号，在 渠道类型 中选择 WebSocket，并填写 账号名称。

  3. 在 绑定模式 中选择 绑定 Agent 实例（默认） 或 绑定 Agent 模板，再通过 绑定对象 选择目标智能体实例或智能体模板。

  4. 按需选择 同步创建 Token（可一次创建多个）。为不同客户端填写不同的 Token 名称和有效期；同一个渠道账号内的 WebSocket Token 名称不能重复。

  5. 选择 创建。

  6. 也可以不在此时签发 Token，稍后从 凭证管理 的 WebSocket Token 页签创建。

  7. 每次创建 Token 后，立即保存返回的 wst_ Token。

Token 明文只在创建时显示。不要把它写入前端代码、日志或文档。

wst_ 绑定到 WebSocket 渠道账号，不直接绑定智能体模板或智能体实例。账号的绑定模式和绑定对象负责路由；因此 Token 创建页只要求选择渠道账号。

同一租户内，一个智能体实例或智能体模板只能绑定一个尚未删除的 WebSocket 渠道账号。已经停用的账号仍保留这个绑定目标。如果多个客户端需要连接同一个绑定目标，应在同一个渠道账号下分别创建 Token，而不是为同一个绑定目标创建多个渠道账号。

连接并完成鉴权 ​

  1. 使用目标部署为渠道账号提供的 WebSocket 地址。不要根据控制台地址自行拼接连接主机名。

  2. 推荐在 HTTP Upgrade 阶段通过子协议传递 Token：

    language-text
    Sec-WebSocket-Protocol: infini.bridge.v1, bearer.<base64url_token>

    base64url_token 是 wst_ Token 的无填充 Base64URL 编码。

  3. 确认连接成功，并且服务端只回显 infini.bridge.v1。

无法在 Upgrade 请求中附加 Token 时，可以改用帧内鉴权。两种方式的完整请求和错误处理见 WebSocket API 参考。

验证消息往返 ​

使用唯一的 msg_id、稳定的 user_id 和测试文本发送一条消息：

language-json
{
  "type": "message",
  "message": {
    "meta": {
      "msg_id": "3eeec74d-a4d4-4517-89ec-ef8aeb676666",
      "user_id": "user-001",
      "user_name": "Alice",
      "chat_type": "p2p",
      "chat_id": "chat-001"
    },
    "content": "帮我查询订单状态"
  }
}

检查结果：

  1. 收到与请求 msg_id 和 chat_id 对应的 message_reply 或 message_stream_reply。
  2. 流式文本能够按顺序累积，并以 done: true 结束本次运行。
  3. 同一个渠道账号有多个客户端时，各客户端能够按消息元数据筛选自己的回复。
  4. 收到 PING 时返回 PONG；断开连接后能够退避重连并重新鉴权。

完整消息字段、事件类型和心跳约定见 WebSocket API 参考。

验证中断和用户工具包 ​

智能体可能通过 message_stream_reply.interrupt 等待用户确认、用户输入或用户工具包执行结果。使用包含相应能力的测试智能体时：

  1. 确认客户端保存原中断的消息元数据和中断 ID。
  2. 对确认型中断返回 APPROVE 或 REJECT。
  3. 对用户工具包中断校验工具名称和参数，在业务系统中执行操作，再返回 RESPOND 或 ERROR。
  4. 确认智能体在收到响应后继续运行，并以 done: true 结束。

响应帧见 WebSocket API 参考，工具执行责任和结果格式见定义用户工具包。

轮换或撤销 Token ​

为同一渠道账号创建第二个 wst_，并使用不同于旧 Token 的 Token 名称。让客户端使用新 Token 建立并验证新连接，再选择 停用旧 Token。客户端必须重连；现有连接不能在原连接中更换 Token。

停用、删除或重置旧 Token 会阻止下一次鉴权，但不会主动关闭已经鉴权的连接。需要立即切断时，对渠道账号选择 停用，关闭该账号的全部连接。这个操作会同时影响该账号下使用其他 Token 的客户端，并停用该账号的所有 WebSocket Token。恢复步骤参见停用或删除 WebSocket 渠道账号。

选择 编辑并修改渠道账号的 绑定对象 后，应让客户端重连并重新执行消息往返测试，不要依赖保持在线的旧连接自动切换路由。

停用或删除 WebSocket 渠道账号 ​

选择 停用 WebSocket 渠道账号会关闭该账号的全部连接，并停用绑定到该账号的所有 WebSocket Token。重新启用渠道账号不会自动启用这些 Token；恢复账号时选择 启用。

临时停用后恢复服务：

  1. 对渠道账号选择 启用。
  2. 打开 凭证管理 的 WebSocket Token，只选择 启用或替换仍需要使用的 Token。
  3. 让客户端重新连接，并完成鉴权、心跳和消息往返测试。

永久删除账号时，先选择 停用并确认连接已经结束，再选择 删除。删除前应盘点客户端保存的 Token 和连接配置；删除平台内的渠道账号不会修改客户端配置。

处理模板绑定 ​

WebSocket 账号绑定智能体模板时，业务系统需要代表渠道用户发送 /init 消息。user_id 是用户绑定和专属实例创建的关键标识，必须稳定且不可被不同终端随意复用。

如果只需要把所有消息转发到一个运行实例，选择实例绑定，避免引入动态实例生命周期。