用途
add-intent-router 是 Redis agent-skills 中的一项技能,用于把智能体现有的手写路由逻辑替换为 Redis Iris Intent Router。被替换的逻辑包括关键词 if/else 链、正则表达式表、match 语句,或只为选择路由而发起的分类器 LLM 调用(如“把这条消息归类为以下之一……”)。替换后,代码中只需一次 match() 调用,就能决定消息去向。
主要能力
- 语义匹配:Router 将消息嵌入,找出最近的示例短语,按意图分组,应用阈值,按匹配程度从高到低返回意图。
- 附带目标:每个意图可携带 target(类型、引用、参数),Router 仅存储不解释。
- 空结果非错误:没有匹配时返回空结果,而非报错。
- 配置即内容:路由和示例短语以 intents.yaml 形式管理,便于评审。
- 同步/异步:提供 match 与 amatch、define 与 adefine 等异步方法;其余方法仅同步。
使用方式
流程分为六步:
- 发现:阅读项目,找出智能体决定消息去向的位置,列出所有路由及其作用、真实短语(测试夹具、日志、关键词、分类器提示中的示例),并向开发者询问五个问题:现有路由是什么、每条路由三到五个真实短语、每条路由分派到什么、无匹配时怎么办(默认回退到通用智能体)、用哪个嵌入模型(默认 OpenAI text-embedding-3-small,1536 维)。
- 获取最新事实:写代码前通过 MCP 查询框架文档(如 Context7)和 Redis 文档,了解已安装版本的路由方式(条件边、handoff、工具选择)及 Intent Router 概念(意图、示例、阈值)。无 MCP 时阅读虚拟环境中的包源码,并在报告中说明。
- 配置:根据回答编写 intents.yaml 并提交。文件包含意图名称(字母、数字、.、_、-)、描述、示例短语、target,以及可选的 minScore。然后用 CLI 创建服务:
iris --json --no-input intent-router service create --name support --provider openai --model text-embedding-3-small --dimensions 1536 --role read --dry-run- 正式创建加
--wait --write-env .env。 - 用
service check校验。 - 使用两个密钥:agent 用 read 角色(在 .env),加载 intents.yaml 用 write 角色(仅用于运行 intents add 的 shell,不放入 agent 的 .env)。
- 用
iris --json --no-input intent-router intents add --file intents.yaml原子批量加载意图。
- 接入决策点:启动时创建一次
IntentRouter.from_env(),用found = router.match(message)替换原决策;found.best含 name、target、score;无匹配则走原有回退路径。match(message, limit=3)返回后续候选,min_score=可单次覆盖阈值。需替换的位置包括 LangGraph 的路由节点或条件边函数、OpenAI Agents SDK 的 triage agent 或 handoff 选择、Google ADK 的路由 agent 或 before_agent_callback、CrewAI 管理者的委派选择、普通循环中的 if/else 或 match 语句。替换后删除关键词列表、正则表、分类器提示及其模型调用,保留分派代码。 - 验证:运行
service check确认各环节通过;intents list --all查看意图及示例数;用未出现在示例中的短语测试 match;用无路由覆盖的内容测试应返回空列表;分别运行智能体确认走匹配路由与回退路径;取消设置IRIS_INTENT_ROUTER_API_KEY并确认报 ConfigurationError 并点名该变量。若意图匹配错误,可补充短语或提高 minScore 后重跑 intents add;若全空,可降低 Router 或意图阈值(intents update NAME --min-score)。使用 noop 嵌入提供者时,匹配是词面重叠而非语义。 - 报告:列出五个问题的回答、intents.yaml 中的意图与示例数、嵌入模型、生成的密钥及角色、match() 的接入位置及被替换内容、回退路径、验证输出,以及无法通过 MCP 确认的事项。
适用场景
适用于原本用关键词、正则或分类器 LLM 调用决定消息路由的智能体(LangGraph、OpenAI Agents SDK、Google ADK、CrewAI 或普通循环),希望以可配置、可评审的意图匹配方式替代手写路由逻辑。
限制
- 嵌入模型一旦 Router 创建即固定,选择需谨慎。
- 云环境拒绝控制面命令(cloud_unsupported),需在 Iris 界面手动创建 Router 和密钥。
- 凭证缺失时须停止并告知用户设置哪个变量,不得在聊天中索取或回显密钥。
- 不得把密钥打印到终端;始终用 --write-env 输出到文件。
- intents add 为原子批量,任一意图无效则不写入。
- noop 嵌入提供者下匹配为词面重叠而非语义。
- SDK 在缺少设置或服务中断时抛错;需决定 Router 故障是否使该轮失败,多数智能体捕获后走回退路径。