列出 Agent 版本

获取指定 Agent 的版本历史记录，按版本号降序排列。

GET /v1/agents/{agent_id}/versions

获取指定 Agent 的版本历史记录，按版本号降序排列（最新版本在前）。

​

请求头

头部	必选	说明
Authorization	是	Bearer <PAT>

​

路径参数

参数	类型	必选	说明
agent_id	string	是	Agent 唯一标识

​

查询参数

参数	类型	必选	默认值	说明
limit	integer	否	20	每页返回数量，必须为正整数；超过 100 时按 100 处理
after_id	string	否	-	正整数版本号游标；按版本号降序返回此游标之后的更旧版本。不能与 before_id 同时传
before_id	string	否	-	正整数版本号游标；按版本号降序返回此游标之前的更新版本。不能与 after_id 同时传

完整分页规范详见 分页。

​

示例请求

curl -X GET "https://api.qoder.com/api/v1/cloud/agents/agent_019eXXXX.../versions" \
  -H "Authorization: Bearer $QODER_PAT"

​

示例响应

HTTP 200 OK

{
  "data": [
    {
      "type": "agent",
      "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "name": "doc-test-agent-updated",
      "description": "用于 API 文档测试",
      "model": "ultimate",
      "system": "你是更新后的文档测试助手",
      "tools": [],
      "mcp_servers": [],
      "skills": [],
      "metadata": {},
      "version": 2,
      "archived_at": null,
      "created_at": "2026-05-18T15:26:39.61669Z",
      "updated_at": "2026-05-18T15:27:07.967138Z"
    },
    {
      "type": "agent",
      "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "name": "doc-test-agent",
      "description": "",
      "model": "ultimate",
      "system": "你是文档测试助手",
      "tools": [],
      "mcp_servers": [],
      "skills": [],
      "metadata": {},
      "version": 1,
      "archived_at": null,
      "created_at": "2026-05-18T15:26:39.61669Z",
      "updated_at": "2026-05-18T15:26:39.61669Z"
    }
  ],
  "first_id": "2",
  "last_id": "1",
  "has_more": false
}

​

响应字段

字段	类型	说明
data	Agent version snapshot 数组	当前页的版本快照
first_id	string	当前页第一条记录的版本标识
last_id	string	当前页最后一条记录的版本标识
has_more	boolean	是否还有更多版本记录

​

版本历史说明

• 创建 Agent 时会保存 version 1
• 每次通过 PUT 更新 Agent 都会保存下一个版本
• 每个版本保存当时的完整 Agent 快照
• 可用于审计变更历史或回滚参考

​

错误码

HTTP	type	触发条件
400	invalid_request_error	limit 不是正整数
400	invalid_request_error	同时传入了 before_id 和 after_id
400	invalid_request_error	before_id 或 after_id 不是正整数版本号
401	authentication_error	PAT 无效或过期
403	permission_error	无权限访问此 Agent
404	not_found_error	指定 ID 的 Agent 不存在

​

注意事项

• first_id 和 last_id 在此端点中对应版本号的字符串形式（如 "1"、"2"）
• 默认按版本号降序，最新版本在前
• 归档 Agent 不会新增版本快照
• 可配合 PUT 操作的 OCC 机制使用，追踪配置变更历史

​

相关

定义 Agent

创建可复用、可版本化的 Agent 配置。