操作场景
当同一个 Agent API 下挂载了多个能力不同的 Dify Agent（例如 HR 助手、IT 助手、财务助手），希望由网关根据用户提交的 task 语义自动选择最合适的 Agent 时，可使用 AI 语义路由。
开启 AI 语义路由后，网关会对用户 task 做向量编码并在 ES 中做 KNN 检索，与目标 Agent 组的语义描述做相似度匹配，按置信度排序后将请求路由至最优 Agent；置信度低于阈值时，自动路由至兜底 Agent。使用该能力无需在客户端指定具体 Agent 入口。
本能力适用于 Dify 协议的 Agent API，后端服务模式选择 Auto（基于语义） 时生效。
前提条件
已创建 AI 网关实例。
已准备可用的 Elasticsearch 集群（腾讯云 ES），且集群已部署 Embedding 模型。
已创建至少一个 Dify Agent 服务。
说明：
语义路由的检索引擎为 ES 向量检索（dense_vector + KNN），复用 ES 集群内置的 Embedding 模型，无需额外采购向量数据库。
操作步骤
步骤1：创建 ES 全局配置
1. 登录 AI 网关控制台，选择目标 AI 网关实例进入详情页面，在左侧导航栏单击全局配置。
2. 单击新建，在配置类型中选择 ES。
3. 填写以下参数：
地址：ES 集群访问地址。
端口：ES 集群访问端口。
用户名：ES 集群用户名。
密码：ES 集群密码。
Embedding 模型（model_id）：从 ES 集群的 _inference 端点拉取的模型列表中选择。
描述：配置说明（选填）。
4. 单击保存。
步骤2：为 Dify Agent 服务配置语义信息
1. 在左侧导航栏单击 Agent 管理 > Agent 服务，进入 Agent 服务列表。
2. 单击目标 Dify Agent 服务的名称，进入服务详情页面。
3. 在语义配置页签，填写以下参数：
语义描述：该 Agent 的能力与适用场景说明，50 ~ 200 字，需覆盖核心业务场景。
适用场景：口语化的意图描述列表，最多 10 条。
示例输入：典型的 task 原句列表，最多 10 条。
4. 单击保存。
说明：
语义描述、适用场景、示例输入是语义匹配的输入源，内容越贴近真实用户问法，路由准确率越高。未配置时在语义配置页签展示未配置提示。
步骤3：创建 Agent API 并选择 Auto（基于语义）模式
1. 在左侧导航栏单击 Agent 管理 > Agent API，进入 Agent API 列表。
2. 单击新建，填写以下参数：
API 名称：Agent API 的名称（必填）。
请求协议：选择 Dify。
Base Path：API 的基础路径（必填）。
后端 Agent 服务：请求协议为 Dify 时显示。
3. 在后端服务模式中，选择 Auto（基于语义）。
4. 配置 Auto 模式参数：
ES 全局配置：单选下拉，从已创建的 ES 类型全局配置中选择。选择后自动带出 Embedding 模型（model_id），该字段只读、不可修改。
目标 Agent 组：单击 添加 Agent，从已创建的 Dify Agent 服务中选择 2 ~ 10 个 Agent，卡片列表展示各 Agent 的索引状态。
可用 API 端点：选完 Agent 后自动展示端点预览表格，该表格只读。
置信度阈值：滑块调节，默认 0.7。
兜底 Agent：从目标 Agent 组中选择，必填。
5. 单击保存，完成创建。开启语义路由时，系统会自动创建 ES 索引与 ingest pipeline，索引名为 agent_api_{apiId}。
注意：
Auto 模式存在以下约束，请在创建前确认：
不显示应用类型字段。
不支持手动配置路由规则。
不提供路由调试工具。
创建完成后，路由管理页签只读，不支持新建、编辑、删除路由规则。
步骤4：查看语义路由配置与路由结果
1. 在 Agent API 列表单击目标 API 名称，进入详情页。
2. 在语义路由页签查看以下信息：
Auto 模式开启状态标识。
目标 Agent 组，含各 Agent 的索引状态与是否参与路由。
置信度阈值与兜底 Agent。
3. 如需调整 Agent 组，单击编辑 Agent 组。
4. 在路由管理页签查看路由列表，该列表在 Auto 模式下只读，后端服务列带 Auto 标记，无操作按钮。
5. 在 AgentCard 页签查看各 Agent 的 AgentCard JSON 预览。
说明：
路由决策流程为：对用户 task 做向量编码 → 在 ES 中做 KNN 检索（仅索引状态正常的 Agent 参与）→ 取置信度最高的 Agent → 若最高置信度不低于阈值则路由至该 Agent，否则路由至兜底 Agent。
参数说明
ES 全局配置字段
字段名 | 说明 | 是否必填 |
地址 | ES 集群访问地址 | 必填 |
端口 | ES 集群访问端口 | 必填 |
用户名 | ES 集群用户名 | 必填 |
密码 | ES 集群密码 | 必填 |
Embedding 模型（model_id） | 从 _inference 端点拉取的模型 | 必填 |
描述 | 配置说明 | 选填 |
语义配置字段
字段名 | 说明 | 约束 |
semanticDesc（语义描述） | 该 Agent 的能力与适用场景说明 | 50 ~ 200 字 |
scenarios（适用场景） | 口语化意图描述列表 | 最多 10 条 |
examples（示例输入） | 典型 task 原句列表 | 最多 10 条 |
indexStatus（索引状态） | ES 文档写入状态 | pending / indexing / ready / failed |
Auto 模式表单字段
字段名 | 说明 | 默认值 |
ES 全局配置 | 单选，选项来自已创建的 ES 类型全局配置 | 无 |
Embedding 模型（model_id） | 随所选 ES 全局配置自动带出 | 只读，不可修改 |
目标 Agent 组 | 参与语义路由的 Dify Agent 服务集合 | 2 ~ 10 个 |
置信度阈值 | 命中该阈值才路由至匹配到的 Agent | 0.7 |
兜底 Agent | 置信度均低于阈值时路由到的 Agent | 必填，从组内选择 |
