> ## 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.

# 列出 Agents

> 获取当前账户下的 Agent 列表，支持游标分页。

`GET /api/v1/cloud/agents`

获取当前账户下的 Agent 列表。默认不包含已归档 Agent；传 `include_archived=true` 时会包含已归档 Agent。

## 请求头

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

## 查询参数

| 参数                 | 类型      | 必选 | 默认值     | 说明                                                    |
| ------------------ | ------- | -- | ------- | ----------------------------------------------------- |
| `limit`            | integer | 否  | 20      | 每页返回数量，范围 1-100；超过 100 返回 `400 invalid_request_error` |
| `page`             | string  | 否  | -       | 上一次响应 `next_page` 返回的游标                               |
| `include_archived` | boolean | 否  | `false` | 设为 `true` 时包含已归档的 Agent                               |
| `created_at[gte]`  | string  | 否  | -       | 仅返回创建时间大于或等于该 RFC 3339 时间戳的 Agent                     |
| `created_at[lte]`  | string  | 否  | -       | 仅返回创建时间小于或等于该 RFC 3339 时间戳的 Agent                     |

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

## 示例请求

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

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "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"
    },
    {
      "type": "agent",
      "id": "agent_019eYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
      "name": "test-agent-e2e",
      "description": "E2E 测试用 Agent",
      "model": "ultimate",
      "system": "你是一个测试助手",
      "tools": [],
      "mcp_servers": [],
      "skills": [],
      "metadata": {},
      "multiagent": null,
      "version": 2,
      "archived_at": null,
      "created_at": "2026-05-18T03:04:33.952256Z",
      "updated_at": "2026-05-18T03:05:28.023697Z"
    }
  ],
  "first_id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "last_id": "agent_019eYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
  "has_more": true,
  "next_page": "agent_019eYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
}
```

## 响应字段

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

## 分页用法

向后翻页（获取下一页）：

```bash theme={null}
curl "https://api.qoder.com/api/v1/cloud/agents?limit=20&page=agent_019eYYYY..." \
  -H "Authorization: Bearer $QODER_PAT"
```

## 错误码

| HTTP | type                    | 触发条件                                                 |
| ---- | ----------------------- | ---------------------------------------------------- |
| 400  | `invalid_request_error` | `limit` 不是正整数                                        |
| 400  | `invalid_request_error` | 分页游标非法                                               |
| 400  | `invalid_request_error` | `created_at[gte]` 或 `created_at[lte]` 不是 RFC 3339 时间 |
| 401  | `authentication_error`  | PAT 无效或过期                                            |
| 403  | `permission_error`      | 无权限执行此操作                                             |

## 注意事项

* 默认按 ID 降序排列
* 已归档的 Agent 不会出现在默认列表中；传 `include_archived=true` 可包含已归档 Agent
* 使用游标分页（cursor-based pagination），不支持 offset 方式

## 相关

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