字段分组与可见性
身份字段分为三组:识别类、能力类和授权类。识别类包括 Agent 标识、主体名称和登记状态;能力类包括能力摘要和记录版本;授权类包括服务端点、授权范围和期限。分组决定字段在查询时的返回方式。
公开字段用于确认对象,按授权返回的字段用于发起调用。端点与授权范围不在公开范围,避免未授权方直接取得调用入口。调用方需要端点时,先完成身份校验和授权判断,再按返回结果发起请求。
字段可见性影响登记时的填写方式。公开字段面向不特定查询方,表述应完整、可核对,不含内部代号;按授权返回的字段面向已确认的调用方,可以写明调用细节,但仍不包含业务数据。两类内容混写,会让公开查询暴露过多信息。
字段参考
| 字段 | 内容 | 可见性 | 变化影响 |
|---|---|---|---|
| Agent 标识 | 唯一识别字符串 | 公开 | 登记后不变 |
| 主体名称 | 开发方或运营方 | 按授权 | 主体变更需重新核验 |
| 能力摘要 | 输入、输出、场景 | 公开 | 版本递增并重新核验 |
| 服务端点 | 地址、协议、接入方式 | 按授权 | 版本递增,标识不变 |
| 授权范围 | 对象、字段、期限 | 按授权 | 版本递增,按新范围返回 |
| 记录版本 | 身份记录版本号 | 公开 | 每次变更递增 |
| 登记状态 | 有效、待核验、停用、注销 | 公开 | 影响匹配与调用 |
| 联系人 | 变更与故障通知人 | 按授权 | 更新后通知链路随之调整 |
| 调用说明 | 协议、接入方式与限制 | 按授权 | 版本递增,需重新匹配 |
授权范围的三层约束
三层同时满足才允许调用。对象在范围内但字段超出,请求被拒绝;字段符合但期限已过,同样不返回端点。授权范围由目标主体确认,平台按登记内容判断,不代替双方协商业务条件。
- 对象约束:哪些调用方可以访问该 Agent。
- 字段约束:允许返回哪些能力与端点信息。
- 期限约束:授权在什么时间段内有效。
- 调用方向:允许单向调用还是双方互调。
- 新增能力:按授权调整办理,不默认继承。
- 撤销授权:写明停止时间,调用方停止请求后再清理凭据。
版本与状态流转
记录版本从首次登记开始计数,端点、能力摘要、授权范围或联系人变化时递增。版本只反映记录变化,不表示能力强弱或服务质量。调用方用版本判断结果是否更新,不用版本比较不同 Agent。
状态分为待核验、有效、停用和注销。待核验表示材料或端点尚未通过,不进入正式匹配;停用保留记录,可以恢复;注销后标识不复用。状态变化写入变更记录,调用方按请求编号核对。
版本递增不等于能力升级。端点迁移、字段调整和联系人变更都会产生新版本,但 Agent 能完成的任务可能没有变化。调用方按版本判断记录是否更新,不据此推断服务质量;版本递增的触发项为端点、能力摘要、授权范围和联系人变更。
拿到待核验状态时先看缺哪一项,不急于发起调用。待核验通常意味着材料、端点或授权范围还有待补充,此时匹配不会返回可用结果。补齐后重新核验,状态与版本会一并更新,调用方再按新记录发起请求。
核验规则
- 核对主体材料与登记名称是否一致。
- 核对能力摘要与端点实际行为是否一致。
- 核对授权对象、字段和期限是否写明。
- 核对端点协议与接入方式能否完成调用。
- 核对联系人能否接收变更与故障通知。
- 核验通过后生成标识与首个记录版本。
- 把核验结论按字段记录,注明通过与待补项。
- 待补项完成前不进入正式匹配,避免调用方按不完整信息发起请求。
常见不一致
不一致的处理顺序是先暂停、再核对、后变更。状态不明时继续调用,会把记录问题带入业务结果;先确认字段与版本,再决定是修正登记还是补充授权,处理范围更清楚。
| 不一致情形 | 影响 | 处理方式 |
|---|---|---|
| 能力摘要宽于实际 | 匹配到无法完成的任务 | 提交能力变更并重新核验 |
| 端点不可访问 | 首次匹配失败 | 核对地址与协议后重提 |
| 授权范围未写期限 | 无法判断有效期 | 补充期限后重新提交 |
| 主体名称与材料不符 | 核验退回 | 更正名称并说明原因 |
| 联系人失效 | 变更通知中断 | 更新联系人 |
| 状态未同步 | 匹配结果与登记不符 | 按记录编号核对后重新匹配 |
| 字段名称前后不一致 | 调用方按错误名称请求 | 统一名称后提交变更 |
常见问题
- 能力摘要会公开给所有调用方吗
- 能力摘要属于公开字段,用于判断是否适用;端点与授权范围按授权返回。
- 记录版本可以手动指定吗
- 不可以。版本由登记变更产生,按顺序递增。
- 授权范围可以只写对象不写字段吗
- 不建议。字段与期限不写明,授权判断缺少依据,核验时会被要求补充。
- 停用后身份记录还在吗
- 在。停用保留记录与版本,恢复后版本继续递增。
- 公开字段可以由调用方修改吗
- 不可以。字段由登记主体维护,调用方按返回内容使用。
- 授权期限到期会自动续期吗
- 不会。到期前由主体确认是否续期,未续期的请求不再返回端点。