# 获取智能体列表 (/zh-CN/api-reference/api-ref/conversational-ai/list) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 检索符合指定条件的智能体列表。 - OpenAPI: /openapi/conversational-ai/rest-api.zh-CN.yaml - Operation ID: get-agent-list - Method: GET - Path: /v2/projects/{appid}/agents - Endpoint: https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/{appid}/agents ## Servers - https://api.agora.io/cn/api/conversational-ai-agent :::warning[注意] 该接口仅支持查询最近 7 天内创建的智能体列表。 ::: ## Authorization This endpoint requires authentication. - `Basic Auth` - `Agora Token` ## Parameters - `Authorization` (header, required, string) - 发送 HTTP 请求时,你可以从以下鉴权方式中任选其一: 1. **使用 Token 认证(推荐)**:参考[实现 HTTP 鉴权](/zh-CN/ai/build/http-basic-auth#使用-token-认证)生成 Token 并填入 `Authorization` Header。传参示例:`Authorization: agora token="007abcxxxxxxx123"`。 2. **使用 Basic Auth**:参考[实现 HTTP 鉴权](/zh-CN/ai/build/http-basic-auth#使用-http-基本认证)生成 Base64 编码的 `Authorization` 字段。传参示例:`Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=`。 - Example: `agora token="007abcxxxxxxx123"` - `appid` (path, required, string) - 你的项目使用的 [App ID](/zh-CN/ai/get-started/enable-service#%E8%8E%B7%E5%8F%96-app-id)。 - `channel` (query, optional, string) - 查询指定频道名下的智能体列表。 - `from_time` (query, optional, integer) - 查询列表开始时间戳 (s),默认为 1 天前。 - `to_time` (query, optional, integer) - 查询列表结束时间戳 (s),默认为当前时刻。 - `state` (query, optional, string) - 指定需要查询智能体的状态,单次查询不支持指定多种状态: - `IDLE` (0):空闲状态的智能体。 - `STARTING` (1):正在启动的智能体。 - `RUNNING` (2):正在运行的智能体。 - `STOPPING` (3):正在停止的智能体。 - `STOPPED` (4):已完成退出的智能体。 - `FAILED` (6):执行失败的智能体。 - Default: `2` - `limit` (query, optional, integer) - 分页获取单次返回的最大条数。 - Default: `20` - `cursor` (query, optional, string) - 分页游标,即分页起始位置的 `agent_id`。 ## Request body No request body. ## Responses ### 200 - 若返回的状态码为 `200` 则表示请求成功。响应包体中包含本次请求的结果。 - 若返回的状态码不为 `200` 则表示请求失败。响应包体中包含错误的类别和描述,你可以参考[响应状态码](/zh-CN/api-reference/conversational-ai/rest-api/api/response-code)了解可能的原因。 - `data` (object) - `data.count` (integer) - 本次返回的智能体数量。 - `data.list` (array) - 满足条件的智能体列表。 - `data.list.items` (object) - `data.list.items.start_ts` (integer) - 智能体创建时间戳。 - `data.list.items.status` (string) - 智能体运行状态: - `IDLE` (0):空闲状态的智能体。 - `STARTING` (1):正在启动的智能体。 - `RUNNING` (2):正在运行的智能体。 - `STOPPING` (3):正在停止的智能体。 - `STOPPED` (4):已完成退出的智能体。 - `FAILED` (6):执行失败的智能体。 - `data.list.items.agent_id` (string) - 智能体唯一标识。 - `meta` (object) - 返回列表的元信息。 - `meta.cursor` (string) - 分页游标。 - `meta.total` (integer) - 满足本次查询条件的智能体总数量。 - `status` (string) - 请求状态。 ## Response examples ### 200 ```json { "data": { "count": 1, "list": [ { "start_ts": 1735035893, "status": "RUNNING", "agent_id": "1NT29X11GQSxxxxx80BEIN56XF" } ] }, "meta": { "cursor": "", "total": 1 }, "status": "ok" } ```