实施范围与前置条件
实施范围包括 Agent 身份、能力摘要、服务端点、授权范围和联系人。身份解决调用哪个对象,能力摘要解决能做什么,端点解决从哪里调用,授权范围解决谁可以调用哪些字段。四项在实施阶段一次厘清,后续变更会少很多。
前置条件有三项:Agent 有稳定用途和可说明的能力边界,端点可访问并能处理请求,主体能承担变更通知与故障处理。条件不具备时先补齐,再进入登记,避免标识生成后无法完成首次匹配。
实施前还要确定验证方式。由谁发起首次匹配、在什么环境验证、通过标准有哪些、失败后由谁修正,提前写明可以避免登记完成后无人接手测试。验证不只是跑通一次调用,还要确认返回字段落在授权范围内。
能力清单编写方法
能力清单是匹配的依据。描述过宽会带来无关候选,描述过窄会漏掉可用目标。编写时以调用方能判断是否适用为标准,不追求覆盖全部技术细节,也不把营销表述写入能力摘要。
- 按任务描述能力,写清输入类型、输出字段和适用场景。
- 区分必备能力与可选能力,避免把内部实现细节写入摘要。
- 标明能力边界,说明不处理的任务类型。
- 不同版本的能力分别说明,不把新旧行为混在一条描述里。
- 能力摘要与实际端点行为一致,核验时以端点为准。
- 涉及字段范围时,与授权范围使用同一套名称。
- 同一能力的多版本并存时,写明适用条件,避免调用方按旧说明发起请求。
- 不把尚未提供的能力写入摘要,核验与首次匹配都会以端点实际行为为准。
多 Agent 拆分原则
一个主体登记多个 Agent 时,按用途和授权对象拆分。审批、检索、报表、通知承担不同任务,调用方和字段范围也不同,放在同一标识下会让授权判断失真。
拆分不按部署数量决定。同一能力部署在多台机器上,仍可作为一个 Agent 登记,端点变化通过版本更新。反之,同一进程内承担两种对外能力,应按能力分别登记,便于调用方按任务选择。
拆分过细也有代价。每个 Agent 都要独立维护能力说明、端点、凭据和记录,数量过多会增加通知与核对成本。按对外可感知的任务边界划分,既能控制授权范围,也不会让管理负担超出实际需要。
| 情形 | 处理方式 | 原因 |
|---|---|---|
| 不同任务类型 | 分别登记 | 授权对象与字段不同 |
| 同一能力的多副本 | 合并登记 | 对外表现为同一能力 |
| 测试与生产 | 分别登记,测试标识停用 | 避免测试结果进入正式匹配 |
| 跨部门共用 | 按部门授权,分别登记 | 范围互不覆盖 |
| 临时试点 | 单独登记,到期停用 | 便于回收与记录 |
实施步骤
- 梳理 Agent 清单,标注用途、能力、端点与责任人。
- 按能力与授权对象确定拆分方式,形成登记清单。
- 准备主体证明、能力说明、端点信息和授权范围。
- 提交材料,配合核验能力摘要与端点行为是否一致。
- 取得测试标识与凭据,完成一次匹配和调用。
- 核对返回的端点、版本与可用字段。
- 停用测试标识,切换正式标识并进入业务调用。
- 保存首次匹配的记录编号,作为上线依据。
- 上线前确认调用方已取得正式标识,测试标识停止使用。
首次匹配验证清单
| 验证项 | 通过标准 | 不通过时 |
|---|---|---|
| 身份 | 返回标识与登记一致 | 核对登记信息 |
| 端点 | 可访问并能处理请求 | 核对协议与接入方式 |
| 版本 | 与登记版本一致 | 重新匹配,不使用旧结果 |
| 授权 | 仅返回范围内字段 | 核对授权对象与字段 |
| 记录 | 生成请求编号,结果状态可查 | 核对请求是否写入记录 |
| 凭据 | 在有效期内且未跨主体 | 更换凭据后重试 |
| 授权期限 | 到期时间与续期状态可查 | 核对授权记录与期限 |
上线后维护
维护的节奏与业务变更同步。计划内的端点迁移提前通知,计划外的故障先暂停相关标识,再核对记录,避免调用方在状态不明时继续请求。
每次变更后复核匹配结果。确认目标仍能被找到、返回字段仍在范围内、版本已更新。只确认端点可访问还不够,授权范围或能力摘要的变化同样会影响调用方。
- 端点或能力变化时提交变更,标识保持不变。
- 授权对象调整后通知调用方重新匹配。
- 凭据按 Agent 独立管理,到期前完成更换。
- 调用记录按请求编号保存,便于核对范围。
- 停止服务的 Agent 办理停用或注销,避免出现在匹配结果中。
- 新增 Agent 按登记清单逐个提交,不批量混写。
常见问题
- 测试标识可以长期使用吗
- 不可以。测试标识只用于接入验证,验证完成后停用,正式调用使用正式标识。
- 一个 Agent 可以有多个端点吗
- 端点按登记内容记录。需要多入口时在实施阶段说明,由核验确认接入方式。
- 能力描述写多细合适
- 以调用方能判断是否适用为准,写清输入、输出、场景和边界即可。
- 上线后发现能力描述不准怎么办
- 提交能力变更,重新核验后再进入匹配结果。
- 实施阶段需要准备测试环境吗
- 需要。首次匹配在测试标识下完成,确认端点与字段后再切换正式标识。
- 多个团队共用一个 Agent 怎么授权
- 按团队分别确认授权对象与字段,必要时拆分为多个 Agent,避免范围互相覆盖。