add-intent-router

添加 Intent Router

用一次 match() 调用替换决定消息去向的代码。Router 会对消息进行嵌入，查找最接近的示例措辞，按意图分组，应用阈值，然后按匹配度从高到低返回匹配的意图，并附上你为每个意图指定的目标。没有匹配项时返回空结果，而不是报错。路由及其措辞属于内容，而不是代码：先询问，再编写 intents.yaml，进行配置，然后加载，最后接入。

1. 探索

阅读项目：

• 找出 Agent 根据消息决定执行操作的位置：if "refund" in text、正则表达式表、match 语句、分类器提示词（“将此消息分类为以下某一类……”），或图中的路由节点或条件边。
• 列出所有可能的路由及其执行的操作：调用工具、移交给子 Agent、选择提示词，或直接回答。
• 找出真实措辞：测试固件、日志、if/else 中的关键词、分类器提示词中的示例。
• 异步 Agent？amatch 和 adefine 是对应的异步方法；其他所有方法都仅支持同步调用。

然后只向开发者询问以下五个问题，不要问其他问题。对方若不确定，就采用默认值。

询问	如果回答是	配置
目前有哪些路由？	一个列表	在 intents.yaml 中为每个路由配置一个意图。名称只能使用字母、数字、.、_ 和 -
为每个路由提供三到五个真实措辞	措辞	将其设为该意图的 examples。没有示例的意图永远不会匹配
每个路由要分发到哪里？	一个工具、一个子 Agent、一个提示词	target: {type, ref, args}。Router 会存储该配置，但不会解释它
	代码已经知道	不设置目标；根据意图名称分发
没有匹配项时应如何处理？	回退到通用 Agent（默认）	空结果时保留现有默认路径
	提出澄清问题	空结果时走该分支
使用哪种嵌入模型？	OpenAI（默认）	--provider openai --model text-embedding-3-small --dimensions 1536
	其他模型	iris intent-router service models 会列出部署提供的模型。Router 创建后，模型选择便固定下来

2. 从 MCP 获取最新信息

在编写代码前完成这一步。切勿凭记忆猜测框架 API。

• 框架文档：查询可用的文档 MCP（Context7 或框架自带的 MCP），了解已安装版本如何进行路由：条件边、移交或工具选择。
• Redis 文档：如果已连接 Redis 文档 MCP，用它查询 Intent Router 的概念（意图、示例、阈值）。
• 没有可用的 MCP：读取虚拟环境中已安装的软件包源码，并在报告中说明。

3. 配置

根据回答编写 intents.yaml 并提交：它是可供审查的路由记录。

intents:
  - name: track_order
    description: Where an order is and when it arrives
    examples: ["where is my order", "track my package", "has my parcel shipped yet"]
    target: {type: tool, ref: orders.track}
  - name: refund_request
    examples: ["I want my money back", "refund this order", "return and refund"]
    target: {type: agent, ref: refunds}
    minScore: 0.4   # stricter than the Router's default for this one

在自管理套件上，从终端进行配置。cloud 配置文件会因 cloud_unsupported 而拒绝控制平面命令：用户需在 Iris → Intent Router → New Intent Router 中创建 Router，并在 Iris → Access & Identity 中创建其密钥。本地堆栈需添加 --local（默认使用 127.0.0.1:9400 和 9401），或者让用户导出 IRIS_INTENT_ROUTER_SERVICE_URL、IRIS_INTENT_ROUTER_SERVICE_TOKEN、IRIS_INTENT_ROUTER_URL、IRIS_IDENTITY_URL 和 IRIS_IDENTITY_TOKEN。完整参考：iris intent-router <command> --help（例如 iris intent-router service create --help）。

iris --json --no-input intent-router service create --name support --provider openai --model text-embedding-3-small --dimensions 1536 --role read --dry-run
iris --json --no-input intent-router service create --name support --provider openai --model text-embedding-3-small --dimensions 1536 --role read --wait --write-env .env
iris --json --no-input intent-router service check <routerId from the result> --env-file .env

将 CLI 作为 Agent 运行

1. 始终将 --json --no-input 放在产品名称之前。标准输出中会得到一个 JSON 值，错误信息会以一个 JSON 值写入标准错误，且不会出现提示。
2. 先进行试运行：不会发送任何内容，并会列出所有缺失的设置。如果有任何缺失项，请停止，并在进行任何写入前交接（第 4 步）。
3. 始终使用 --write-env PATH（或在 service key 上使用 --write PATH）交付密钥。绝不要在没有指定文件的情况下运行带 --json 的 create 或 key：这会将密钥打印到对话记录中。
4. 遇到 credential_required 时，请停止。告知对方要设置哪个变量（details.env），并提供 details.obtain 链接。绝不要在聊天中索要密钥、通过命令行传递密钥，或回显、cat 或 grep 环境变量文件。
5. 遇到 resource_exists 时，询问是使用 --reuse，还是改选其他名称。绝不要通过删除来重试。如果 create 失败且 details.created: true，请运行 details.command 中的命令。

--write-env .env 会写入 IRIS_INTENT_ROUTER_URL、IRIS_INTENT_ROUTER_ID 和 IRIS_INTENT_ROUTER_API_KEY。将相同的三个名称及空值添加到 .env.example。绝不要提交 .env。

两个密钥，绝不是一个：

密钥	用途	生成方式
Agent（在 .env 中）	read：匹配和列出	在 create 上使用 --role read
Authoring，用于加载 intents.yaml	write	iris intent-router service key ROUTER_ID --role write --write .env.authoring；仅在运行 intents add 的 shell 中加载，绝不要放入 Agent 的 .env

使用 Authoring 密钥加载意图。intents add 是一个原子批次：已存在的名称会被替换，如果任何意图无效，则不会写入任何内容：

iris --json --no-input intent-router intents add --file intents.yaml
iris --json --no-input intent-router intents list --all

每次更改 intents.yaml 后，都要重新运行 intents add。

4. 接入决策点

在启动时创建一次：

from redis_iris import IntentRouter

router = IntentRouter.from_env()

用一次调用替换决策逻辑：

found = router.match(message)  # await router.amatch(...)
if found.best:
    route = found.best.name  # "track_order"
    target = found.best.target  # what intents.yaml attached, or None
    # dispatch exactly where the old if/else or classifier branch did
else:
    ...  # question 4: the existing fallback path

found.best.score 是分数，分数越高表示越接近。match(message, limit=3) 会返回接下来的候选项，min_score= 可在单次调用中覆盖所有阈值。若 limit 超过服务端上限，请求会被拒绝，而不是截断到上限。

接入位置（请在第 2 步确认名称）：

框架	替换内容
LangGraph	路由节点或条件边背后的函数：根据 found.best 返回下一个节点
OpenAI Agents SDK	分诊 Agent 或交接选择，仅限其只负责选择路由的情况
Google ADK	路由 Agent 或 before_agent_callback 中的选择逻辑
CrewAI	管理器的委派选择，仅限路由集合固定的情况
普通循环	if/else 或 match 语句

移除被替换的内容：关键词列表、正则表达式表、分类器提示词及其模型调用。保留分发代码；只移动选择逻辑。

如果设置缺失或服务中断，SDK 会抛出异常。请确认 Router 故障是否可以导致本轮失败；大多数 Agent 会捕获异常并采用问题 4 中的回退方案。

5. 验证

1. iris intent-router service check ROUTER_ID --env-file .env 会检查每一环：令牌、Router READY、Identity Service、授予 Router 权限的密钥，以及一次数据读取。
2. iris intent-router intents list --all 会显示 intents.yaml 中的所有意图及其示例数量。
3. iris intent-router match "<a phrasing that is not in the examples>" --limit 3 会将正确的意图排在首位。
4. iris intent-router match "<something no route covers>" 会返回空列表。
5. 针对每种情况各运行一次 Agent，并展示它采用了匹配到的路由和回退方案。
6. 取消设置 IRIS_INTENT_ROUTER_API_KEY，并确认 ConfigurationError 会指出该变量名。

首位意图不正确：向正确的意图添加不同表述，或提高其 minScore，然后重新运行 intents add。结果全部为空：降低 Router 或该意图的阈值（intents update NAME --min-score）。使用 noop 嵌入提供程序时，匹配依据是词汇重叠，而非语义。

6. 报告

列出五个问题的答案、intents.yaml 中的意图及示例数量、嵌入模型、生成的密钥及其角色、match() 的接入位置和替换内容、回退路径、验证输出，以及无法通过 MCP 确认的事项。