开发者接入指南

自助接入的难点不在提交,而在登记信息能否支撑调用方找到目标。名称、能力、端点、回调与授权一次写清,沙箱联调与后续变更都会省事;凭据只在创建时显示一次,需要当场保存。凭据保存与使用情况可在记录中核对。

适用对象与接入前提

一个人维护一个或多个 Agent 的独立开发者,适合按自助流程接入。需要统一管理多个 Agent 的小团队,也可以按主体登记后分别创建,每个 Agent 独立标识、独立凭据。

接入方需要自行维护端点、凭据与回调地址,并对 Agent 的业务结果负责。平台处理身份、端点、授权与调用记录,不替 Agent 执行业务任务,也不保存业务正文。

接入前先确认三件事:Agent 的用途是否单一、端点是否可访问、回调地址是否能够接收验证。三项不成立时,联调阶段会反复退回,切换正式也会被推迟。

登记前要确定的五项信息

登记信息决定调用方能否找到目标,也决定寻址返回什么。名称与用途写清,调用方才能判断是否匹配;能力、端点、回调与授权写清,联调时才有核对依据。

五项信息一次写全,比先填后改更省事。端点与回调在后续变更中需要重新核对,登记时写得准确,变更时改动范围也小。

信息要确定的内容影响
名称与用途对外名称、服务场景、使用对象调用方按用途判断是否匹配
能力说明输入、输出、适用请求类型调用方按能力筛选目标
服务端点地址、协议类型、调用方式寻址返回的地址来源
回调地址接收验证与通知的地址变更后需要重新验证
授权范围授权对象、字段范围、期限决定调用方能否取得端点

五步接入的操作要点

五步顺序固定,每一步都有确认结果。跳步会让后续核对缺少依据,尤其是沙箱阶段直接使用正式凭据,测试流量会进入正式环境,记录也难以区分。

每一步完成后再进入下一步。注册与创建阶段核对主体与用途,沙箱阶段核对端点与错误返回,正式阶段核对凭据切换与首次调用。

  1. 自助注册:提交开发者主体、联系人与用途说明,进入待核对状态。
  2. 创建 Agent:填写名称、能力说明、服务端点与回调地址,形成登记记录。
  3. 配置沙箱:取得沙箱凭据,配置测试端点与回调,确认沙箱环境可用。
  4. 联调测试:完成一次正常调用与一次错误调用,核对返回字段、记录版本与错误说明。
  5. 切换正式:生成正式凭据,停用沙箱凭据,启用正式标识并观察首次调用。

沙箱联调的核对项

沙箱用于验证端点、回调与错误返回。联调通过的标准是调用方能够按标识取得端点,并且成功与失败都能被识别;只测成功请求,错误处理仍然没有验证。

联调阶段不使用正式凭据,也不把沙箱凭据用于正式流量。测试完成后停用沙箱凭据,再切换正式凭据;沙箱阶段的调用记录保留,可用于对照正式启用后的返回结果。

  • 正常调用是否返回端点、记录版本与可用字段。
  • 错误调用是否返回明确错误类型,不应返回空结果。
  • 回调地址是否完成验证,验证未完成前不用于正式调用。
  • 请求字段与登记的能力说明是否一致。
  • 调用记录是否包含记录编号、调用方、目标与时间。
  • 授权范围外的请求是否被拒绝,且不返回端点。

切换正式的注意事项

正式凭据只在创建时显示一次,需要当场保存。切换前确认调用方已按正式标识配置,切换后停用沙箱凭据,避免两套凭据同时可用。

正式启用后先观察首次调用的记录,确认端点、版本与授权范围符合预期,再扩大调用范围。首次调用就出现字段不一致时,先修正登记或请求,不用重试掩盖问题。

端点、能力说明、授权范围或联系人变化通过变更事项更新,标识保持不变,不需要重新接入。注销则不同,标识不再复用,需要按首次接入重新办理。

多个 Agent 与团队协作

每个 Agent 使用独立标识与独立凭据,便于单独停用与排查。按用途拆分后,停用其中一个不会影响其他服务,调用方也只需要按对应标识重新寻址。

团队协作时把凭据保管、回调验证与变更提交落实到人。成员离开或系统下线时,及时停用对应凭据,不把凭据留在共享位置等待下次清理。

  • 测试凭据与正式凭据分开保管,不交叉使用。
  • 凭据不写入前端代码、公开仓库与日志。
  • 凭据不通过聊天工具或邮件明文传递。
  • 回调地址变更后重新验证,验证完成前不用于正式流量。
  • 授权范围按调用方分别说明,不用一份宽范围授权覆盖多个用途。

上线后的维护与边界

上线后按调用记录核对目标、版本与状态。出现失败时先看错误类型,再核对标识、凭据、授权与端点;跨环节反复尝试通常不会解决问题,还会增加无效调用。

平台不保存业务正文,不评价 Agent 输出,也不保证业务结果。业务侧的幂等、重试与数据处理由调用方与 Agent 约定,平台只记录寻址与调用状态。

端点迁移、能力调整或授权变化都属于登记信息更新。更新后按标识重新寻址,调用方不需要逐个通知修改地址。

个人开发者可以接入吗
可以。提交主体信息与 Agent 材料,按独立开发者流程登记。
测试转正式需要重新提交材料吗
不需要。联调通过后切换正式凭据,登记信息继续有效。
一个开发者可以登记多个 Agent 吗
可以。每个 Agent 独立标识、独立凭据,按用途分别管理。

从登记信息开始接入

把名称、能力、端点、回调与授权写清,按五步完成登记、沙箱联调与正式切换。

申请接入