信号路由规则
面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/signal-bindings/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。
信号路由规则(Signal Binding)决定了外部传入的消息或业务事件如何路由到目标 Agent:
- AI 同事模式(
ai_colleague):将一个外部聊天应用或 CloudEvents 事件源连接到指定的单个 AI 同事;同一个 AI 同事也可通过多条规则同时接入多个不同平台。 - 发送者个人助理模式(
sender_personal_assistant)(飞书 / Lark 与 Slack 支持,此时agent_uid为null):在工作区内共享同一个个人助理机器人,将每条私聊消息(im_dm)自动路由给已匹配在职成员各自的个人助理(首次使用时自动创建),并将未识别发信人统一归入手动审核(来宾账号无法通过该模式接入)。
收到消息后,聊天渠道适配器会将其记录到对话(Conversation)中,并为解析出的目标 Agent 生成对应的信号(Signal);此外,CloudEvents Webhook 端点也能接收外部业务系统推送的事件,并将其转化为信号投递给目标 Agent。
如果尚未在 Slack、Microsoft Teams、飞书 / Lark 或钉钉后台创建机器人应用,请先参照 快速开始 完成平台侧接入配置。
创建路由规则
- 打开 Console 的信号路由页面,点击新增路由规则。
- 选择聊天渠道适配器与路由模式:指定某个 AI 同事(
ai_colleague模式),或在飞书 / Lark、Slack 下选择发送者的个人助理(sender_personal_assistant模式)。 - 填写便于辨识的规则名称,例如
support-slack或workspace-pa-feishu。 - 对于
ai_colleague规则,选择群聊消息处理模式(sender_personal_assistant规则仅处理私聊,并对未知发信人固定启用手动审核)。 - 从 Pod → 连接(Connections)(
Ankole.Connectors)中选择已有的平台应用连接(authConfigId),使聊天路由与目录同步 / 单点登录复用同一份应用凭据;或直接填写应用凭据写入Ankole.Connectors,随后保存规则。 - 前往对应的聊天客户端向机器人发送一条测试消息,确认目标 Agent 能够正常回复。
请为每个独立的机器人形象单独注册平台应用与路由规则:若多个 AI 同事需要各自独立的机器人身份,请分别为它们配置专属应用;共享个人助理机器人也应使用独立的应用入口,以便身份与消息流互不串扰。
选择群聊消息模式
Console 界面仅会展示当前所选聊天渠道实际支持的群聊模式:
| 模式 | 未明确 @ 提及 Agent 的群消息如何处理 |
|---|---|
| 仅处理明确提及 | Agent 既不会读取该消息,也不会作出回复。 |
| 记录未提及消息 | 消息会写入对话上下文,但不会立即唤醒 Agent;待后续有人 @ 提及 Agent 时,它可结合此前积累的群聊记录理解前因后果。 |
| 可主动介入 | Agent 会先评估当前讨论是否需要自己参与,仅在判断发言确有帮助时才主动回复。 |
Slack、Microsoft Teams 与飞书 / Lark 均完整支持以上三种模式;钉钉与企业微信受平台机制限制,仅能接收明确 @ 提及机器人的群消息,因此 Console 中只提供第一种模式。尤其需要注意,企业微信还存在无法撤回消息、群聊无法接收文件附件、机器人无法主动发起会话等诸多平台限制,不建议将其作为主力渠道;完整限制说明见 快速开始 中的企业微信标签页。
开启“可主动介入”并不意味着机器人会逢消息必回——它只是允许 Agent 在无人点名时自行评估一次是否应当搭话,且每批新消息仅触发一次判断。若想明确约定某个群的发言时机,可直接在群里向 Agent 下达一条频道常驻指令(例如“只有 CI 构建失败变红时才出声提醒”);如果觉得它插话过于频繁,可收紧常驻指令或角色说明;若该群只需被动一问一答,直接切回“仅处理明确提及”即可。详细的评估机制与常驻指令用法见 群聊主动介入。
选择未知发信人的处置
收到外部消息时,Ankole 先按发信人的稳定平台用户 ID 查找已绑定且状态为 active 的 Human Principal。目录同步、单点登录或管理员操作都可以建立这种绑定。默认的手动审核策略不会仅凭聊天资料中的邮箱或手机号将发信人关联至现有账号;仅使用邮箱验证码(Email OTP,SiteCredential)登录,也不会自动绑定其聊天账号。
规则中的自动映射账号失败时选项决定了如何处置这类未识别发信人:
| 选项 | 处理行为 |
|---|---|
| 手动审核(默认) | 发信人会进入控制台 身份 → 待绑定账号 待办列表。在管理员完成账号绑定前,点名该 Agent 的消息只会收到一条固定提示,引导对方联系管理员;消息正文既不会进入对话上下文,也不会被 Brain 收录学习。 |
| 自动创建独立账号 | 系统解析或创建账号后提供对话服务,适合允许外部人员提问的开放频道。首次绑定该 Provider 时,经过证实的邮箱若唯一匹配到某位状态为 active 的 Human 的资料邮箱、已验证个人登录邮箱或目录联系邮箱别名,且该 Human 尚未绑定该 Provider、未完成离职流程,系统会关联至该 Human。否则,系统按平台标识创建独立账号。邮箱匹配到多名人员或账号标识已被占用时,发信人无法接入,需由管理员显式绑定身份。 |
等待手动审核的发信人在群聊中未点名 Agent 的日常闲聊会被忽略。
各聊天平台的身份识别方式有所不同:
- Telegram、Discord、LINE 与 WhatsApp:没有预先绑定平台 ID 的发信人会被视为未知身份。若只允许已知用户接入,请保持手动审核,由管理员逐一关联账号。WhatsApp 手机号本身不会触发与现有 Human 手机号的自动关联。
- 电子邮件:系统在独立的
email命名空间中按发信地址匹配显式的email身份绑定或状态为 active 的 Human 已登记的联系邮箱。员工邮箱绑定可由目录同步或上游身份源登录建立,外部联系人可由管理员在此页面绑定。仅有 Email OTP 登录邮箱不等于已建立邮件渠道绑定。 - 飞书与 Lark 外部群:跨企业群中的外部租户成员没有本企业的员工 ID,可使用手动绑定或独立账号策略。管理员也可在用户首次发消息前预先绑定账号,例如提前把某位 Email OTP(
SiteCredential)用户与其聊天账号关联起来。
聊天内容如何成为 Brain 知识
信号路由规则只负责将消息分发给指定 Agent,本身不设知识可见性开关。当 Brain 从聊天记录中提炼沉淀知识时,会严格依据会话类型与已知参与人身份自动划定披露范围:
- 群聊:提炼出的知识可供该群对应的成员权限组全体成员及相关 Agent 检索使用;若所用聊天渠道无法同步群成员权限组,Brain 则不会从该群聊天中学习任何内容。
- 私聊:提炼出的知识默认仅对私聊本人及实际接待该会话的 Agent(绑定的 AI 同事或发信人的个人助理)可见,其他 Agent 无权读取。
在此基础上,明确属于公开常识或公司通告的事实可升级为租户内共享知识,而当事人明确要求保密的内容则可收紧为仅对发言人可见;其余常规交流均维持上述群聊或私聊默认边界。关于底层模型配置与检索逻辑,请参阅 Brain。
编辑、停用或启用
路由规则列表默认仅展示启用中的规则;如需查阅或恢复历史规则,可勾选打开“显示已停用”。
点击某条规则的“编辑”,即可查看非敏感配置项,或更换目标 AI 同事、调整群聊消息模式、切换 Ankole.Connectors 应用连接(authConfigId)或轮换聊天应用凭证。更改 ai_colleague 规则的目标 Agent 保存后,后续新流入的消息将立即转交新 Agent 处理。
出于安全考虑,已保存的 Token 与 Secret 不会回传至浏览器端。编辑规则时若将凭证输入框留空,服务端会继续沿用原有的加密值;只有填入新内容时才会覆盖更新。
点击“停用”会立即中止新消息接入,但完整保留规则配置、平台应用关联与历史会话链路;日后需要恢复服务时,只需在“显示已停用”列表中找到该规则并点击“启用”,无需推倒重建。
排查没有回复的问题
- 新建规则时找不到目标聊天渠道:Control Plane Plugin 严格属于站点级扩展(对应接口
/api/v2/site/control-plane-plugins),仅在全局站点维度可见,不会出现在租户级或单 Agent 级能力库中。请前往站点管理控制台(/site-admin-console),在 Agent 能力库 顶部将作用域切换为全局默认值,打开 Control Plane Plugins 标签页启用对应的渠道插件,并按提示重启控制面。 - 机器人在群里收不到消息:核查外部平台后台的事件订阅开关、接口权限及应用发布生效状态;此外,钉钉与企业微信群聊中必须明确
@提及机器人才能触发推送。 - 企业微信收发异常:请先对照 快速开始 中的企业微信说明排查平台侧硬性限制——常见原因包括机器人并非由超级管理员创建、未配置企业可信 IP 白名单,或用户尚未主动发消息激活会话。
- 规则保存成功但发消息无响应:确认目标 Agent 处于启用状态、模型档案配置有效,并在路由规则列表中检查该规则本身是否处于正常启用状态。
- 私聊对答正常、群聊毫无反应:检查当前规则所选的群聊消息模式,并确认已将机器人拉入目标群聊。
各聊天平台所需的具体权限项、订阅事件名与凭证获取方式,均以 快速开始 中对应平台的配置步骤为准。
此外,若希望钉钉机器人采用流式打字机卡片回复,需先前往钉钉卡片平台搭建一份 AI 卡片模板,具体步骤见 快速开始 钉钉标签页下的高级设置说明。