文档中心

Appearance

控制台

通过渠道提供智能体 ​

智能体开发服务平台（AgentWorks）的渠道账号连接飞书、QQ 或 WebSocket 消息入口，并决定消息应进入已有智能体实例，还是为渠道用户动态创建专属实例。

三类渠道的消息范围和接入方式如下；上线前请以目标部署的可见配置和真实账号测试为准：

渠道消息与回复接入方式
飞书支持单聊和群聊；流式回复飞书应用机器人长连接
QQ单聊可配置，无群聊设置；非流式回复QQ WebSocket C2C
WebSocket支持单聊和群聊；流式回复infini.bridge.v1 协议

分别参见接入飞书机器人、接入 QQ 机器人和通过 WebSocket 接入智能体。需要创建、切换或清空渠道中的对话时，参见管理渠道会话。

渠道账号页面中的 WebSocket、飞书和 QQ 渠道类型及账号操作

绑定模式：使用已有实例还是按用户创建 ​

选择 绑定模式 前，先判断渠道账号应始终使用一个已经配置好的智能体实例，还是应在每位渠道用户首次使用时为其创建专属实例：

  • 需要复用一个已经配置并验证的智能体实例，并把它作为渠道账号的固定运行目标时，使用实例绑定。这个账号可以只供一位用户使用，也可以供多位用户使用。
  • 需要平台在每位用户首次使用时分别创建智能体实例时，使用模板绑定，按用户开通专属实例。

多位用户进入同一个已有实例时，仍可以通过不同渠道会话分开对话；但实例配置及其关联资源可能由这些用户共同使用。

新建飞书渠道账号时可以选择实例绑定或需要用户执行 /init 的模板绑定

使用已有智能体实例（实例绑定） ​

实例绑定适合将一个已经配置并验证的智能体实例作为渠道账号的固定运行目标。它不会按渠道用户动态创建实例。该渠道账号可以只供一位用户使用，也可以供多位用户使用；面向多位用户时，只需分开对话时，使用共享实例和不同渠道会话。这种方式常用于企业 FAQ、制度问答和公共服务台。

所有通过该渠道账号进入智能体实例的用户和会话都会使用该实例关联的沙箱。智能体模板选择沙箱模板时，该智能体实例使用为它创建的沙箱实例；选择现有沙箱实例时，还可能与其他智能体实例复用同一个沙箱。

注意

多位用户使用已有实例时也会共享沙箱状态

如果渠道任务会写入文件、运行脚本、使用用户专用凭证或并发执行，一个用户的操作可能影响其他用户。需要按渠道用户分开这些内容时，使用模板绑定和 /init 创建用户专属智能体实例，并让智能体模板选择 沙箱 - 模板。参见了解共享沙箱的影响。

选择这种模式后，按照绑定已有智能体实例完成配置。

为每位用户按需开通实例（模板绑定） ​

对于面向多位用户的渠道账号，只需分开对话时，使用共享实例和不同渠道会话。如果每位用户需要分别管理智能体实例的参数、运行状态或生命周期，请选择 模板绑定（agent_id 指向 Agent 模板，用户需 /init）。

这种方式适合需要为每位用户分别维护运行状态的场景，例如个人工作助手、客户专属助手、培训教练和研发运维助手。

选择这种方式后：

  • 不需要提前为所有潜在用户创建智能体实例。
  • 同一个智能体模板可以供不同用户按需开通。
  • 用户首次完成 /init 时，平台为该用户创建智能体实例并保存用户绑定。
  • 每位用户的实例参数、运行状态和生命周期可以分别管理。

注意

每人一个智能体实例不等于资源完全隔离

专属智能体实例表示运行对象可以分别管理，不自动保证记忆、数据和权限彼此独立。沙箱、记忆、凭证和外部账号是否独立，取决于智能体模板实际引用的资源：

  • 沙箱 - 模板：每个通过 /init 创建的智能体实例会获得一个沙箱实例。
  • 沙箱 - 实例：这些智能体实例仍会复用同一个现有沙箱。新建渠道会话不会创建新的沙箱。
  • 记忆 - 模板：为每个新智能体实例准备独立记忆库。
  • 记忆 - 实例：不同用户的智能体实例连接同一个现有记忆库。
  • MCP 凭证和业务系统账号：可能仍由多个智能体实例共享。

需要保存用户私有数据时，请同时检查沙箱、记忆、MCP 凭证、业务账号，以及外部服务实际收到的凭证和调用方上下文。

如果环境中没有可选的 记忆 - 模板，请联系平台管理员提供相应资源，或者由业务系统管理按用户区分的长期记忆。参见模板和实例如何影响资源。

选择这种模式后，按照首次使用时创建专属实例完成配置。

配置渠道绑定 ​

根据前面选择的绑定模式执行对应过程：

选择的模式配置过程
使用已有智能体实例绑定已有智能体实例
为每位用户按需开通实例首次使用时创建专属实例

绑定已有智能体实例 ​

这种方式不会为每个用户创建新智能体实例。渠道账号可以面向一位或多位用户；面向多位用户时，不同用户仍可使用各自的渠道会话分开对话。

开始前，请先创建并验证要绑定的智能体实例。

  1. 打开 渠道账号。

    打开渠道账号

  2. 选择 新建账号，并在 渠道类型 中选择所需渠道。

  3. 根据渠道选择实例绑定方式：

    • 飞书或 QQ：选择 实例绑定（agent_id 指向应用实例）。“应用实例”指智能体实例。
    • WebSocket：选择 绑定 Agent 实例（默认）。相关绑定限制和多客户端 Token 配置参见通过 WebSocket 接入智能体。

  4. 选择目标 智能体实例。

  5. 填写渠道应用凭证及允许名单。

  6. 选择 创建。创建的渠道账号会自动上线。

首次使用时创建专属实例 ​

模板绑定分为管理员配置和渠道用户初始化两个阶段。

开始前，请完成以下准备：

  • 创建并验证一个可复用的智能体模板。
  • 确认所有必需的实例参数可以由用户或管理员提供。例如，业务模板可以自行定义 CUSTOMER_ID 或 REGION 等参数；这些名称仅为自定义业务参数示例，不是 AgentWorks 预置的配置项。应在创建渠道账号前确认这些值由管理员预先配置，还是由用户通过 /init KEY=VALUE 提供。

完成准备后，管理员按以下步骤创建渠道账号：

  1. 打开 渠道账号。

    打开渠道账号

  2. 选择 新建账号，并在 渠道类型 中选择所需渠道。

  3. 根据渠道选择模板绑定方式：

    • 飞书或 QQ：选择 模板绑定（agent_id 指向 Agent 模板，用户需 /init）。
    • WebSocket：选择 绑定 Agent 模板，并按通过 WebSocket 接入智能体中的绑定限制规划渠道账号和 Token。

  4. 选择目标 Agent 模板。

  5. 选择 创建。

重要

动态创建不是批量预创建。每个用户只在发送 /init 时触发一次智能体实例创建。上线前应评估实例数量、外部能力资源和后续清理责任。

渠道账号创建完成后，渠道用户首次使用时发送：

language-text
/init

如果模板要求参数，可以在同一条命令中传入 KEY=VALUE：

language-text
/init CUSTOMER_ID=customer-001 REGION=cn-east

CUSTOMER_ID 和 REGION 是智能体模板创建者定义的示例参数名，不是 AgentWorks 提供的配置值。首次发送不带参数的 /init 时，平台会返回模板实际要求的参数名、类型和默认值；再次发送时应使用返回的准确名称。

/init 使用空格分隔 KEY=VALUE，参数值不能包含空格。只通过渠道填写客户编号、区域或工作区等非敏感配置，不要在飞书或 QQ 消息中传递密码、访问令牌或完整 Authorization Header。智能体模板引用 MCP 模板时，参数名与 MCP 字段的映射方法参见让飞书或 QQ 用户通过 /init 填写 MCP 参数。

模板绑定的首次使用和后续路由过程如下：

图表预览

该时序只适用于模板绑定。实例绑定跳过 /init 和动态创建，消息直接进入渠道账号选择的现有智能体实例。

平台会创建智能体实例并保存渠道用户绑定。后续消息进入该实例。如果用户已经完成初始化，再次发送 /init 会返回已初始化提示。

需要使用两位测试用户完整验证飞书模板绑定、按用户开通和配置个人工作助手、用户绑定和重新初始化时，参见构建按用户开通的飞书个人工作助手。需要进一步让这些实例使用同一项员工知识服务时，参见构建共享制度知识的飞书员工服务助手。

配置渠道参数 ​

智能体模板表单可以保存飞书或 QQ 的渠道参数，并选择模板绑定或实例绑定。创建或更新测试智能体实例后，在 渠道账号 中确认出现预期账号和绑定关系，再完成真实消息往返测试。

飞书或 QQ 账号创建后，需要检查账号状态、会话、用户绑定或定时任务时，参见创建账号后继续管理消息、用户和任务。WebSocket 的连接信息、Token 和消息协议使用不同的管理入口，参见通过 WebSocket 接入智能体。

区分渠道路由和 WebSocket Token ​

渠道账号保存实例绑定或模板绑定的路由选择。wst_ WebSocket Token 只允许客户端连接一个 WebSocket 渠道账号，并不直接绑定智能体模板或智能体实例。

同一租户内，一个智能体实例或智能体模板只能绑定一个尚未删除的 WebSocket 渠道账号。停用账号不会释放这个绑定目标。多个客户端需要连接同一个绑定目标时，应为同一个 WebSocket 渠道账号创建多个 Token，不要重复创建渠道账号。

修改 WebSocket 渠道账号的绑定目标后，应让客户端重新连接并通过测试消息确认实际路由，不要依赖已建立的连接自动切换目标。

管理渠道用户绑定 ​

在渠道详情的 会话管理 和 用户绑定 中检查路由，并按需为用户绑定配置补充自动批准规则。用户规则不会直接拒绝调用；deny 或未命中会继续人工审批。

用户绑定和智能体实例具有独立生命周期。用户不再使用该服务时，应先删除用户绑定；删除绑定不会删除对应的智能体实例。如果原智能体实例及其能力资源也不再需要，还必须在 智能体实例 中分别检查并处理。

删除操作路径、普通消息验证、重新执行 /init 的时机，以及需要立即阻止访问时的处理方式，参见管理渠道账号与用户绑定。

处理渠道失败和审批 ​

渠道返回失败信息时，记录渠道用户、发送时间和完整错误信息，并在目标智能体实例中查找同一时间的 Trace。不要立即重复发送可能产生副作用的请求。

消息已经进入智能体执行 ​

找到对应 Trace，说明消息已经进入智能体执行过程。继续检查模型、工具、审批、子代理和外部能力。

  1. 核对失败发生在普通回复、工具调用还是子代理任务中。
  2. 在飞书中看到同一轮响应包含多个工具调用时，展开每个调用，核对工具名称、参数、状态和结果，找出失败或仍在等待的操作。
  3. 如果飞书会话中出现子代理审批卡片，核对操作和参数后选择 ✅ 允许、⭐ 加白执行 或 ❌ 拒绝。对应后台任务会在 等待审批 和继续运行之间切换。
  4. 涉及子代理时，打开 后台任务检查对应任务。
  5. 根据 Trace 中的失败位置检查 模型凭证、MCP Server、沙箱运行记录或其他外部能力，然后使用同一测试输入复测。

消息没有进入智能体执行 ​

没有对应 Trace 时，检查渠道账号状态、绑定目标、用户绑定和智能体实例状态。

  1. 打开 渠道账号，确认目标账号已经启用并处于在线状态。
  2. 对于实例绑定，确认绑定的智能体实例仍然存在并且可以运行。
  3. 对于模板绑定，在渠道账号的 用户绑定 中确认该用户已经绑定到有效智能体实例；尚未初始化时，让用户发送 /init。
  4. 修复状态或绑定后，先发送不会修改业务数据的固定测试消息。仍然失败时，把渠道账号、用户、发送时间和完整错误信息交给管理员排查。

渠道中的失败信息用于及时告知用户。Trace 和运行记录用于定位已经开始的智能体执行；没有对应记录时，应从渠道账号和绑定关系开始排查。参见排查智能体实例运行问题和处理子代理的确认审批。

处理初始化问题 ​

  • 提示当前渠道不支持 /init：账号不是模板绑定。
  • 提示缺少参数：按照返回的参数名重新发送 /init KEY=VALUE。
  • 用户消息没有回复：检查允许名单、渠道账号状态和智能体实例状态。
  • 初始化后配置错误：对对应智能体实例选择 编辑，不要只修改渠道用户绑定。