Skip to main content

列出 Agent

分页列出当前工作空间中的 Agent。

接口

GET /agents 成功返回 200 和列表信封,data 为 Agent 对象数组。

查询参数

limit integer (可选)每页数量,默认 20;建议使用 1..100order string (可选)排序方向,asc 或 desc,默认 descafter string (可选)上一页的 last_id;不包含游标项before string (可选)上一页的 first_id,用于反向翻页,不能与 after 同时使用;游标必须是当前工作空间中有效的 Agent同时传 after 和 before 返回 400。翻页时首次不传 after,后续传上一页的 last_id;反向翻页使用 first_id 作为 before。has_more 表示当前扫描方向还有结果。列表按 Agent ID 字典序排序,不保证按 created_at 稳定排序,也不提供并发写入下的快照隔离。

请求示例

curl -sS "$BASE_URL/agents?limit=20&order=desc" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

响应字段

object string列表对象类型,固定为 listdata array当页 Agent 对象,空时为 []first_id string / null当页首项 ID。空页为 nulllast_id string / null当页末项 ID。空页为 nullhas_more boolean当前扫描方向是否还有下一页

Agent 字段

id stringAgent ID,按不透明字符串使用object stringAgent 对象类型,固定为 agentcreated_at integer创建时间的 Unix 秒时间戳updated_at integer最近修改时间的 Unix 秒时间戳,不是版本号name string / null展示名称metadata object / null元数据,保存的字符串键值对model string保存的模型 IDreasoning object / null推理配置。两项均可为 null。
effort string / null推理强度:none、minimal、low、medium、high、xhigh、maxsummary string / null推理摘要:concise、detailed、auto
text object / null文本输出配置。
format object输出格式。
type string / null输出格式类型,固定为 text
verbosity string / null输出详细程度,low、medium、high
instructions string / null保存的自定义指令tools array / null保存的工具配置;每个分支只返回本分支字段
function objectFunction 工具配置,返回 name、description、parametersmcp objectMCP 工具配置,返回 server_label、transport、allowed_tools、required、connection_origin;transport 为 http 或 stdioweb_search objectWeb Search 工具配置,返回 type 和已保存的配置
multi_agent object / null子 Agent 配置。
enabled boolean是否启用子 Agent 工具max_concurrent_subagents integer / null最大并发子 Agent 数;不补默认值
未设置的可选字段可能返回 null。

响应示例

{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

错误码

业务错误返回 error 对象,包含 type、code、message 和 param。常见错误如下:
HTTP 状态码错误类型 / 错误码解决方案
400invalid_request_error / invalid_request_error按查询参数说明修正 limit、order
401authentication_error / invalid_api_key在请求头携带有效的 Authorization: Bearer $DASHSCOPE_API_KEY
404not_found_error / not_found_error使用本集合上一页返回的 last_id 作为 after
500server_error / server_error稍后重试;持续失败时提交工单并提供 x-request-id