文档中心

Appearance

✨费用中心控制台

接入飞书机器人 ​

一体化智能体运行与协同平台（AgentWorks）通过飞书应用机器人和长连接接收消息，支持单聊、群聊和流式卡片回复；不需要为 AgentWorks 提供公网事件回调地址。

选择创建方式 ​

有飞书管理员可以完成扫码授权时，优先使用 扫码创建。这个流程由管理员在飞书侧选择创建新应用或使用已有应用，不需要在 AgentWorks 中手动填写 App ID 和 App Secret。

无法使用扫码授权时，再使用手动方式：

创建方式适用条件AgentWorks 中的操作
扫码创建飞书管理员可以扫码并授权新应用或已有应用填写账号、绑定和聊天策略，选择 生成二维码
手动创建已有应用凭证，或当前环境无法完成扫码授权在飞书开放平台完成应用配置，再填写 App ID 和 App Secret

手动准备飞书应用 ​

使用手动创建方式时，在飞书开放平台创建或选择一个企业自建应用，并为应用添加机器人能力。群聊中的自定义 Webhook 机器人不能接收这里需要的交互事件，不能替代应用机器人。

在应用的“凭证与基础信息”中取得 App ID 和 App Secret。只把 App Secret 交给负责配置渠道账号的人员。

手动开通消息和卡片能力 ​

使用手动创建方式时，按照飞书的应用配置说明配置应用身份权限。根据要启用的消息方式开通以下权限：

  • im:message.p2p_msg:readonly：读取用户发给机器人的单聊消息。
  • im:message.group_at_msg:readonly：在需要群聊时接收群中 @ 机器人的消息。
  • im:message:send_as_bot：以应用身份回复消息。
  • “创建与更新卡片”：创建并持续更新流式回复卡片。

AgentWorks 会尝试读取通讯录中的用户基本信息，用于补充用户名等调用方信息。没有通讯录读取权限时，AgentWorks 使用飞书 Open ID；只有业务确实需要姓名或其他身份字段时，才按飞书获取单个用户信息的最小权限要求扩大通讯录权限和数据范围。

手动使用长连接订阅事件 ​

使用手动创建方式时：

  1. 在飞书应用的事件配置中选择“使用长连接接收事件”。
  2. 添加 im.message.receive_v1 接收消息事件。
  3. 在需要工具确认或输入型中断时，为卡片配置添加 card.action.trigger 回调，并同样使用长连接。
  4. 发布应用版本，并确认测试人员或目标组织成员可以使用机器人。

飞书的使用长连接接收事件说明了长连接模式。平台运行环境需要访问飞书公网，但不需要配置 AgentWorks 的公网回调 URL。

创建飞书渠道账号 ​

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

  1. 打开 渠道账号。

    打开渠道账号

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

打开页面后，根据准备情况选择扫码创建或手动创建。

扫码创建 ​

  1. 选择 扫码创建。
  2. 填写 账号名称，在 绑定模式 中选择 实例绑定（agent_id 指向应用实例） 或 模板绑定（agent_id 指向 Agent 模板，用户需 /init），并配置单聊、群聊和工具调用显示策略。其中，“应用实例”就是智能体实例。两种模式的差异参见选择渠道绑定模式。
  3. 选择 生成二维码，让飞书管理员账号扫码。
  4. 在飞书侧选择创建新应用或选择已有应用，并完成授权。
  5. 等待页面显示 飞书机器人配置成功。创建的渠道账号会自动上线；打开账号详情检查 绑定目标和 聊天策略。

手动创建 ​

  1. 在 渠道账号 中选择 新建账号，在 渠道类型 中选择 飞书。
  2. 填写 账号名称、应用 ID（凭证）和应用密钥。
  3. 在 绑定模式 中选择 实例绑定（agent_id 指向应用实例） 或 模板绑定（agent_id 指向 Agent 模板，用户需 /init）。两种模式的差异参见选择渠道绑定模式。
  4. 配置 单聊允许的发送者 ID。
  5. 按需选择 禁用群聊，或填写 群聊允许的群 ID。
  6. 决定是否选择 展示工具调用详情。
  7. 选择 创建，然后选择 启用。

单聊允许列表为空时允许任意发送者；群聊未被禁用且群允许列表为空时允许任意群。生产账号应显式填写经过批准的用户和群 ID，而不是依赖空列表的开放行为。

完成任一创建流程后，可以选择 编辑渠道账号并设置 禁用单聊。启用后，所有单聊都会被拒绝，即使发送者 ID 已在单聊允许名单中。需要开放部分用户单聊时，应保持该选项关闭，再填写单聊允许名单；只提供群聊的机器人可以启用该选项。

验证消息往返 ​

启用后，先确认渠道账号状态变为 在线，再依次验证：

  1. 如果未禁用单聊，让获准用户向机器人发送单聊消息并收到回复。
  2. 如果启用群聊，在获准群中 @ 机器人并收到回复。
  3. 普通长回复会在同一张飞书卡片中持续更新，而不是只显示一个静态最终消息。
  4. 让机器人生成包含多个表格或较长内容的回复。内容超过单张卡片的承载范围时，AgentWorks 会发送带有“内容较长，剩余内容将在新卡片中继续展示”和“接上一张卡片继续”提示的续接卡片。确认各张卡片顺序连续，内容没有缺失或重复。
  5. 已启用工具调用详情时，使用可以并行调用两个只读工具的测试请求。确认每个工具调用与自己的结果对应，并分别显示正确的成功或失败状态。
  6. 使用会进入审批流程的工具请求，先验证模板规则的自动批准、自动拒绝和未命中结果；需要用户补充规则时，让调用在模板中保持未命中，再使用目标用户验证补充规则或人工审批。
  7. 主智能体模板配置了子代理且相关实例已经更新时，让子代理触发一次确认型审批。确认审批卡片出现在主智能体会话中，选择 ✅ 允许、⭐ 加白执行 或 ❌ 拒绝 后，智能体实例的 后台任务 不再停留在 等待审批。卡片包含一批待审批调用时，对整批操作选择 ✅ 全部允许、⭐ 全部加白执行 或 ❌ 全部拒绝。

智能体运行失败时，飞书卡片会显示失败信息。记录对应用户、时间和智能体实例，再到 Trace 和相关运行记录定位模型、工具、权限或外部服务问题；不要连续重试可能有副作用的请求。参见处理渠道中的运行错误和审批。

如果账号保持离线，优先检查 App ID、App Secret、应用版本、机器人能力、事件订阅和平台到飞书的公网连接。收到消息但无法回复时，再检查发送消息和卡片权限。

验证模板绑定和 /init ​

模板绑定不会在创建渠道账号时批量创建实例。使用尚未初始化的测试用户发送：

language-text
/init

如果智能体模板开放了必填参数，按照机器人返回的参数名再次发送：

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

确认 AgentWorks 创建智能体实例和用户绑定，随后普通消息进入该实例。再次发送 /init 应返回已经初始化的提示。

需要从非生产飞书应用开始，使用两位测试用户验证按用户开通实例、长回复、解绑和重新初始化时，参见构建按用户开通的飞书助手。

轮换 App Secret ​

每个渠道账号保存一组飞书凭证。修改凭证会中断旧连接并使用新凭证重新连接，因此需要按有短暂中断的轮换安排维护窗口。

  1. 选择业务低峰期并记录当前账号、绑定目标和允许列表。
  2. 在飞书侧生成或取得新 Secret，但先不要撤销仍在使用的凭证。
  3. 选择 编辑，同时填写 应用 ID（凭证）和新的应用密钥，然后选择 保存。
  4. 等待账号重新变为 在线，并完成一次单聊或群聊往返。
  5. 确认卡片更新和 /init 路径仍然正常。
  6. 再在飞书侧撤销旧 Secret。

如果保存后无法上线，恢复仍有效的旧凭证，重新检查连接，再安排下一次轮换。

停用或删除渠道账号 ​

临时停止或永久删除机器人渠道账号时，先选择 停用并确认状态已经变为 已停用。停用会断开长连接，但不会删除智能体模板、智能体实例、会话或模板绑定产生的用户实例。

永久移除前，先记录并处理用户绑定、专属智能体实例和外部飞书应用，再选择 删除。删除 AgentWorks 渠道账号会停止对应渠道连接，但不会删除飞书开放平台中的应用。

本页记录的飞书渠道流程以文本消息为支持范围。只有在目标租户中使用真实测试账号确认目标文件类型可用后，才把图片、音频或文件输入纳入业务验收。