> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 列出 Agent 版本

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

`GET /api/v1/cloud/agents/{agent_id}/versions`

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

## 请求头

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

## 路径参数

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

## 查询参数

| 参数      | 类型      | 必选 | 默认值 | 说明                                                    |
| ------- | ------- | -- | --- | ----------------------------------------------------- |
| `limit` | integer | 否  | 20  | 每页返回数量，范围 1-100；超过 100 返回 `400 invalid_request_error` |
| `page`  | string  | 否  | -   | 上一次响应 `next_page` 返回的游标                               |

完整分页规范详见 [分页](/zh/cloud-agents/api/conventions/pagination)。

## 示例请求

```bash theme={null}
curl -X GET "https://api.qoder.com/api/v1/cloud/agents/agent_019eXXXX.../versions" \
  -H "Authorization: Bearer $QODER_PAT"
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "type": "agent",
      "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "name": "doc-test-agent-updated",
      "description": "用于 API 文档测试",
      "model": "ultimate",
      "system": "你是更新后的文档测试助手",
      "tools": [],
      "mcp_servers": [],
      "skills": [],
      "metadata": {},
      "multiagent": null,
      "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": {},
      "multiagent": null,
      "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,
  "next_page": null
}
```

## 响应字段

| 字段          | 类型                                                                                      | 说明                                               |
| ----------- | --------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `data`      | [Agent version snapshot](/zh/cloud-agents/api/agents/schemas#agent-version-snapshot) 数组 | 当前页的版本快照                                         |
| `first_id`  | string                                                                                  | 当前页第一条记录的版本标识                                    |
| `last_id`   | string                                                                                  | 当前页最后一条记录的版本标识                                   |
| `has_more`  | boolean                                                                                 | 是否还有更多版本记录                                       |
| `next_page` | string\|null                                                                            | 下一页游标。`has_more` 为 true 时等于 `last_id`，否则为 `null` |

## 版本历史说明

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

## 错误码

| HTTP | type                    | 触发条件              |
| ---- | ----------------------- | ----------------- |
| 400  | `invalid_request_error` | `limit` 不是正整数     |
| 400  | `invalid_request_error` | 分页游标非法            |
| 400  | `invalid_request_error` | `page` 不是正整数版本号游标 |
| 401  | `authentication_error`  | PAT 无效或过期         |
| 403  | `permission_error`      | 无权限访问此 Agent      |
| 404  | `not_found_error`       | 指定 ID 的 Agent 不存在 |

## 注意事项

* `first_id` 和 `last_id` 在此端点中对应版本号的字符串形式（如 `"1"`、`"2"`）
* 默认按版本号降序，最新版本在前
* 归档 Agent 不会新增版本快照
* 可配合 `POST /api/v1/cloud/agents/{agent_id}` 的 OCC 机制使用，追踪配置变更历史

## 相关

<CardGroup cols={2}>
  <Card title="定义 Agent" icon="user-gear" href="/zh/cloud-agents/define-agent">
    创建可复用、可版本化的 Agent 配置。
  </Card>
</CardGroup>