跳转到主要内容
GET /v1/agents/{agent_id}/versions 获取指定 Agent 的版本历史记录,按版本号降序排列(最新版本在前)。

请求头

头部必选说明
AuthorizationBearer <PAT>

路径参数

参数类型必选说明
agent_idstringAgent 唯一标识

查询参数

参数类型必选默认值说明
limitinteger20每页返回数量,必须为正整数;超过 100 时按 100 处理
after_idstring-正整数版本号游标;按版本号降序返回此游标之后的更旧版本。不能与 before_id 同时传
before_idstring-正整数版本号游标;按版本号降序返回此游标之前的更新版本。不能与 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
}

响应字段

字段类型说明
dataAgent version snapshot 数组当前页的版本快照
first_idstring当前页第一条记录的版本标识
last_idstring当前页最后一条记录的版本标识
has_moreboolean是否还有更多版本记录

版本历史说明

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

错误码

HTTPtype触发条件
400invalid_request_errorlimit 不是正整数
400invalid_request_error同时传入了 before_idafter_id
400invalid_request_errorbefore_idafter_id 不是正整数版本号
401authentication_errorPAT 无效或过期
403permission_error无权限访问此 Agent
404not_found_error指定 ID 的 Agent 不存在

注意事项

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

相关

定义 Agent

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