寻址匹配

匹配解决调用方要找哪个 Agent。匹配可以按标识精确查询,也可以按能力条件筛选,再由授权范围过滤结果。匹配结果只包含授权范围内的字段,调用方在正式调用前应确认端点和记录版本。匹配记录只用于核对目标,不承载业务内容。

匹配的作用

调用方通常面临两种情形:已经知道目标标识,需要确认端点和版本;或者只掌握能力要求,需要找到可用的 Agent。匹配分别处理这两种情形,并在返回前按授权范围过滤。

匹配不评价 Agent 的业务效果,也不返回实时运行状态。结果以登记记录为准,调用方使用前应核对版本。

匹配的前提是双方都完成登记。调用方需要有有效标识和凭据,目标需要处于有效状态;任一方记录失效时,匹配不会返回可用结果。

两种匹配方式

两种方式可以组合使用。先按能力条件筛选,再用标识确认具体目标,适用于跨主体协作中的目标确认。

能力条件应写成可核对的要求,包括输入类型、输出字段和适用场景。条件过宽会得到较多候选,条件过窄可能没有结果,调用方可以按需调整。

方式输入适用场景
标识匹配完整 Agent 标识已知目标,确认端点和版本
能力匹配能力条件、输入输出要求不确定目标,筛选可用 Agent

匹配步骤

候选 Agent 不在授权范围内时,不出现在结果中。结果不返回部分字段,避免调用方误用未授权能力。

匹配步骤按顺序执行。凭据无效时不查询候选,授权不通过时不返回端点,版本不一致时不拼接结果。

版本不一致时不拼接结果,调用方重新匹配后再取端点。

  1. 校验调用方标识和凭据。
  2. 按标识或能力条件查询候选 Agent。
  3. 按授权范围过滤候选结果。
  4. 返回标识、能力摘要、端点、版本和状态。
  5. 写入匹配记录。

返回内容

返回内容不包含业务正文,也不包含目标 Agent 的内部运行信息。

  • Agent 标识:目标 Agent 的唯一标识。
  • 能力摘要:输入、输出和适用场景。
  • 服务端点:调用入口、协议和接入方式。
  • 记录版本:用于确认当前记录。
  • 登记状态:有效、待核验、停用或注销。

结果使用与失败处理

匹配结果按记录版本返回。端点和版本变化后,旧结果可能失效,调用方应重新匹配,不使用缓存中的旧端点。

调用失败时先核对错误类型,再检查标识、版本、授权和端点。重复请求不能绕过授权限制。

返回结果可以缓存,但缓存时间不宜过长。端点和版本变化后,缓存结果需要作废,调用方重新匹配后再使用。

  • 无匹配结果:放宽能力条件或核对授权范围。
  • 标识不存在:核对标识是否完整。
  • 无权限:检查调用方标识和授权对象。
  • 版本不一致:重新匹配,不使用旧结果。

按身份与能力查找 Agent

先完成 Agent 身份登记,再按标识或能力条件发起匹配。调用前确认端点、版本和授权范围。

申请接入