AgentSpecs 管理
AgentSpecs 管理（AgentSpecs Registry）用来管理 Agent 规范包。它面向 Agent 平台、开发工具和 AI 应用，帮助团队分发标准化的 Agent 描述、资源和版本。
Agent 管理关注“可被发现和调用的 Agent 入口”。AgentSpecs 管理关注“描述 Agent 能力、行为和资源的规范包”。两者可以配合使用：平台可以先通过 AgentSpec 分发标准描述，再通过 Agent 管理暴露可调用的 Agent 实例。
适合解决的问题
- 多个团队需要复用同一份 Agent 规范，但不希望复制到各自仓库。
- Agent 规范需要版本化发布，并支持回滚和标签路由。
- 开发工具、Agent 平台或 AI 应用需要按名称、版本或标签获取 AgentSpec。
- 平台团队需要控制 AgentSpec 的公开范围、业务标签和上下线状态。
- AgentSpec 发布前需要经过审核、安全扫描或其他 Pipeline 检查。
AgentSpec 包含什么
在 Nacos 中，AgentSpec 通常由元数据、描述内容和资源信息组成。
| 内容 | 说明 |
|---|---|
| 基础信息 | 命名空间、名称、描述、业务标签、来源和可见范围 |
| 规范内容 | AgentSpec 的主要描述内容，用于表达 Agent 的能力、约束或使用方式 |
| 资源信息 | 与 AgentSpec 一起分发的资源文件或资源元数据 |
| 版本信息 | 版本号、状态、标签、更新时间和发布信息 |
AgentSpec 可以通过 ZIP 包上传，也可以通过草稿接口创建和更新。发布后，运行时应用可以通过客户端 API 查询或搜索可用 AgentSpec。
生命周期
AgentSpec 使用统一的 AI 资源生命周期。
上传或创建草稿 -> 更新草稿 -> 提交 -> 审核通过后发布为 online -> 下线或重新上线常见管理动作包括：
- 上传 ZIP 包或通过接口创建、更新草稿。已发布的规范包不能直接覆盖，修改时应创建新版本草稿。
- 提交草稿。有已启用且支持 AgentSpec 的 Pipeline 节点时进入
reviewing，否则直接发布上线。 - 查看审核结果。通过和拒绝都会进入
reviewed；通过后发布，拒绝后先重新编辑再修改，或重新提交以重跑检查。 - 发布或重新上线版本，由服务端自动更新
latest；用stable等自定义标签控制应用侧切换。 - 下线单个版本，或通过启用/禁用开关控制整个 AgentSpec 的可用性。启用资源不会自动上线草稿或已下线版本。
- 设置可见范围、查询版本详情或元数据。
管理员应急强制发布、标签和状态规则见 AI 资源生命周期。
运行时查询
AI 应用、Agent 平台或开发工具可以通过客户端 API 获取 AgentSpec：
- 按
name查询 AgentSpec。 - 按
version精确获取指定版本。 - 按
label获取标签指向的版本。 - 按关键词分页搜索 AgentSpec。
如果客户端已经缓存了内容，可以结合 API 的 md5 参数判断本地内容是否需要更新。具体请求参数和返回结构见 客户端 API。
给平台和运维人员的建议
- 用命名空间区分环境、租户或业务域，避免测试规范影响生产使用。
- 需要控制生产切换时使用
stable等自定义标签；latest由服务端自动维护。 - 对公开范围、业务标签和发布权限做统一约束。
- 对高风险 AgentSpec 启用 Pipeline 检查，避免未经审核的内容直接进入生产。
- 下线 AgentSpec 前先确认是否仍有 Agent 平台、开发工具或 AI 应用依赖该版本。