Skip to main content

列出 Subagent

分页查询 Session 的子 Agent 列表,查看名称、状态和生命周期时间。

接口

GET /agents/sessions/{session_id}/subagents 返回 Session 的子 Agent 列表。根 Agent 不作为子 Agent 返回。成功返回 200。查询不启动或恢复子 Agent,也不创建资源。

路径参数

session_id string (必选)Session ID,例如 sess_xxx

查询参数

limit integer (可选)每页数量,范围 1–100,默认 20order string (可选)排序方向,asc 或 desc,默认 descafter string (可选)上一页的 last_id;结果不包含游标项before 会被忽略,不用于反向分页。使用 order 和 after 翻页。

请求示例

curl --get "$BASE_URL/agents/sessions/sess_xxx/subagents" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "order=asc"

响应字段

列表信封:object string列表对象类型,固定为 listdata array<Subagent>当页子 Agent;空时为 []first_id string / null当页首项 ID。空页为 nulllast_id string / null当页末项 ID。空页为 null。后续 after 使用该值has_more boolean当前检索方向是否还有下一页Subagent 字段:active 可以空闲等待,不表示持续运行。历史查询不自行启动或恢复子 Agent。
id string稳定的子 Agent IDobject stringSubagent 对象类型,固定为 agent.session.subagentsession_id string所属 Sessionparent_agent_id string父 Agentname string / null展示名instructions array / null公开指令内容status stringSubagent 状态:active 或 closedopened_at integer打开时间,Unix 秒closed_at integer / null关闭时间,Unix 秒;未关闭时为 null

响应示例

{
  "object": "list",
  "data": [
    {
      "id": "subagent_xxx",
      "object": "agent.session.subagent",
      "session_id": "sess_xxx",
      "parent_agent_id": "agent_xxx",
      "name": "researcher",
      "instructions": null,
      "status": "active",
      "opened_at": 1794118835,
      "closed_at": null
    }
  ],
  "first_id": "subagent_xxx",
  "last_id": "subagent_xxx",
  "has_more": false
}
{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

错误码

HTTP 状态码错误类型 / 错误码解决方案
400invalid_request_error / invalid_request_error按查询参数说明修正 limit、order;使用本集合上一页返回的 last_id 作为 after
404not_found_error / not_found_error使用当前工作空间中存在且未删除的 Session ID
502server_error / agents_api_upstream_unavailable稍后重试;持续失败时提交工单并提供响应头中的 x-request-id