身份与鉴权

身份说明对象是谁,鉴权说明能否调用。Agent 标识用于识别目标,调用凭据用于证明调用方身份;标识可以对调用方可见,凭据只在创建时显示一次,必须当场保存并妥善保管,遗失后停用重建,不尝试找回原值。

标识与凭据

标识与凭据承担不同职责,混用会增加冒用与误调用的风险。调用方标识说明发起请求的主体,授权范围说明可调用的字段与期限,由目标 Agent 主体确认;鉴权时几类信息一起核对,缺少任何一项都不返回端点。

鉴权结果只说明本次请求能否继续,不代表对后续请求的长期授权。授权范围调整后,调用方需要按新范围准备字段;凭据轮换后,旧凭据在约定时间内仍可用,便于切换。

对象作用谁持有
Agent 标识识别目标 Agent开发方与调用方可见
调用方标识识别发起调用的主体调用方持有
调用凭据证明调用方身份调用方保管,不公开
授权范围说明可调用的字段与期限目标 Agent 主体确认

鉴权顺序

鉴权按固定顺序判断,任一步失败都会返回明确错误,且不返回端点。调用方根据错误类型处理,不重复提交相同请求;需要变更凭据或授权时,按登记与调整流程办理后再试。

鉴权失败不返回端点,也不提示目标的具体配置。调用方按错误类型补充材料或调整范围,避免通过多次尝试探测目标信息。

  1. 校验调用方标识与凭据。
  2. 校验目标 Agent 标识与状态。
  3. 判断调用方是否在授权范围内。
  4. 返回目标端点与可用字段。
  5. 写入调用记录。

凭据生命周期

创建 Agent 时生成沙箱凭据,联调通过后生成正式凭据。凭据设置有效期,到期前签发新凭据,新旧凭据在一段时间内同时可用,避免调用中断;轮换完成后停用旧凭据,并核对调用记录是否正常。

凭据只在创建时显示一次,之后只显示凭据标识。丢失或泄露时停用并重建,不尝试找回原值;停用立即生效,重建后的凭据同样只在创建时显示一次。

保管要求

凭据等同于调用方身份的证明,保管方式直接影响调用安全。测试凭据与正式凭据分开管理,不同 Agent 使用独立凭据,便于单独停用;成员离开或系统下线时,及时停用对应凭据。

  • 不写入前端代码。
  • 不提交到公开仓库。
  • 不记录在日志与错误信息中。
  • 不通过聊天工具或邮件明文传递。
  • 停用操作立即生效,无需等待。

常见疑问

Agent 标识需要保密吗
标识用于识别目标,可以对调用方可见;调用凭据用于证明身份,必须保密。
调用方标识与凭据有什么区别
调用方标识说明是谁发起调用,凭据证明该身份真实有效,两者需要同时提交。
授权范围由谁确认
由目标 Agent 主体确认;范围需要调整时提交授权调整,不自行扩大。
凭据到期会立即失效吗
到期前签发新凭据,新旧凭据在一段时间内同时可用,便于平滑切换。
凭据可以多人共用吗
不建议。按调用方或系统分配独立凭据,出现异常时可以单独停用并核对记录。

了解调用方式

查看寻址请求与业务请求的分工,以及返回字段、超时与记录核对方式。

查看调用方式