列出 Agents

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

GET /v1/agents

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

​

请求头

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

​

查询参数

参数	类型	必选	默认值	说明
limit	integer	否	20	每页返回数量，必须为正整数；超过 100 时按 100 处理
after_id	string	否	-	游标分页，按当前 ID 降序返回此 ID 之后的记录。不能与 before_id 同时传
before_id	string	否	-	游标分页，按当前 ID 降序返回此 ID 之前的记录。不能与 after_id 同时传
include_archived	boolean	否	false	设为 true 时包含已归档的 Agent
created_at[gte]	string	否	-	仅返回创建时间大于或等于该 RFC 3339 时间戳的 Agent
created_at[lte]	string	否	-	仅返回创建时间小于或等于该 RFC 3339 时间戳的 Agent

完整分页规范详见 分页。

​

示例请求

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

​

示例响应

HTTP 200 OK

{
  "data": [
    {
      "type": "agent",
      "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "name": "doc-test-agent",
      "description": "",
      "model": "ultimate",
      "system": "你是文档测试助手",
      "tools": [],
      "mcp_servers": [],
      "skills": [],
      "metadata": {},
      "version": 1,
      "archived": false,
      "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": {},
      "version": 2,
      "archived": false,
      "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
}

​

响应字段

字段	类型	说明
data	Agent 对象数组	当前页的 Agent
first_id	string	当前页第一条记录的 ID
last_id	string	当前页最后一条记录的 ID
has_more	boolean	是否还有更多数据

​

分页用法

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

curl "https://api.qoder.com/api/v1/cloud/agents?limit=20&after_id=agent_019eYYYY..." \
  -H "Authorization: Bearer $QODER_PAT"

向前翻页（获取上一页）：

curl "https://api.qoder.com/api/v1/cloud/agents?limit=20&before_id=agent_019eXXXX..." \
  -H "Authorization: Bearer $QODER_PAT"

​

错误码

HTTP	type	触发条件
400	invalid_request_error	limit 不是正整数
400	invalid_request_error	同时传入了 before_id 和 after_id
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 方式

​

相关

定义 Agent

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