Skip to main content

获取 Subagent 的 Turn

获取指定子 Agent 的单个 Turn,查看状态、时间边界、错误和 Token 用量。

接口

GET /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id} 成功返回 200,响应体是单个 Turn。查询不启动或恢复子 Agent,也不创建资源。

路径参数

session_id string (必选)Session ID,例如 sess_xxxsubagent_id string (必选)稳定的子 Agent ID,例如 subagent_xxxturn_id string (必选)公开 Turn ID,例如 turn_xxx路径上下级必须匹配。Turn 不属于该子 Agent 或该 Session 时不返回数据。

请求示例

curl "$BASE_URL/agents/sessions/sess_xxx/subagents/subagent_xxx/turns/turn_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

响应字段

usage 包含 input_tokens、input_tokens_details.cached_tokens、output_tokens、output_tokens_details.reasoning_tokens 和 total_tokens。相关计数不齐时,整个 usage 为 null。id string公开 Turn IDobject stringTurn 对象类型,固定为 agent.session.turnsession_id string所属 Sessionagent_id string执行 Agentsubagent_id string / null子 Agent Turn 为对应子 Agent IDstatus stringTurn 状态:in_progress、waiting、completed、failed、cancelledcreated_at integer创建时间,Unix 秒started_at/completed_at integer / null开始时间和完成时间,Unix 秒。未到边界时为 nullerror object / nullTurn 级错误。
code string错误码message string错误说明
usage object / nullToken 用量。
input_tokens integer输入 Token 数input_tokens_details object输入 Token 明细。
cached_tokens integer命中缓存的输入 Token 数
output_tokens integer输出 Token 数output_tokens_details object输出 Token 明细。
reasoning_tokens integer推理 Token 数
total_tokens integer总 Token 数
waiting 不是成功终态。completed、failed、cancelled 才是终态。SSE 的 turn.created 事件中可能出现 queued,持久 Turn 从 in_progress 开始。

响应示例

{
  "id": "turn_xxx",
  "object": "agent.session.turn",
  "session_id": "sess_xxx",
  "agent_id": "agent_xxx",
  "subagent_id": "subagent_xxx",
  "status": "completed",
  "created_at": 1794118835,
  "started_at": 1794118836,
  "completed_at": 1794118840,
  "error": null,
  "usage": {
    "input_tokens": 512,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 128,
    "output_tokens_details": {"reasoning_tokens": 32},
    "total_tokens": 640
  }
}

错误码

HTTP 状态码错误类型 / 错误码解决方案
404not_found_error / not_found_error确认 Session、Subagent、Turn 存在且属于同一工作空间,并使用匹配的路径层级
502server_error / agents_api_upstream_unavailable稍后重试;持续失败时提交工单并提供响应头中的 x-request-id