匹配的作用
调用方通常面临两种情形:已经知道目标标识,需要确认端点和版本;或者只掌握能力要求,需要找到可用的 Agent。匹配分别处理这两种情形,并在返回前按授权范围过滤。
匹配不评价 Agent 的业务效果,也不返回实时运行状态。结果以登记记录为准,调用方使用前应核对版本。
匹配的前提是双方都完成登记。调用方需要有有效标识和凭据,目标需要处于有效状态;任一方记录失效时,匹配不会返回可用结果。
两种匹配方式
两种方式可以组合使用。先按能力条件筛选,再用标识确认具体目标,适用于跨主体协作中的目标确认。
能力条件应写成可核对的要求,包括输入类型、输出字段和适用场景。条件过宽会得到较多候选,条件过窄可能没有结果,调用方可以按需调整。
| 方式 | 输入 | 适用场景 |
|---|---|---|
| 标识匹配 | 完整 Agent 标识 | 已知目标,确认端点和版本 |
| 能力匹配 | 能力条件、输入输出要求 | 不确定目标,筛选可用 Agent |
匹配步骤
候选 Agent 不在授权范围内时,不出现在结果中。结果不返回部分字段,避免调用方误用未授权能力。
匹配步骤按顺序执行。凭据无效时不查询候选,授权不通过时不返回端点,版本不一致时不拼接结果。
版本不一致时不拼接结果,调用方重新匹配后再取端点。
- 校验调用方标识和凭据。
- 按标识或能力条件查询候选 Agent。
- 按授权范围过滤候选结果。
- 返回标识、能力摘要、端点、版本和状态。
- 写入匹配记录。
返回内容
返回内容不包含业务正文,也不包含目标 Agent 的内部运行信息。
- Agent 标识:目标 Agent 的唯一标识。
- 能力摘要:输入、输出和适用场景。
- 服务端点:调用入口、协议和接入方式。
- 记录版本:用于确认当前记录。
- 登记状态:有效、待核验、停用或注销。
结果使用与失败处理
匹配结果按记录版本返回。端点和版本变化后,旧结果可能失效,调用方应重新匹配,不使用缓存中的旧端点。
调用失败时先核对错误类型,再检查标识、版本、授权和端点。重复请求不能绕过授权限制。
返回结果可以缓存,但缓存时间不宜过长。端点和版本变化后,缓存结果需要作废,调用方重新匹配后再使用。
- 无匹配结果:放宽能力条件或核对授权范围。
- 标识不存在:核对标识是否完整。
- 无权限:检查调用方标识和授权对象。
- 版本不一致:重新匹配,不使用旧结果。