OpenAI 列出子智能体轮次

2026-11-18 18:02 更新

get /agents/sessions/{session_id}/subagents/{subagent_id}/turns

列出此子智能体的全部轮次,包括恢复后进行的轮次。参见子智能体工作流。

路径参数

  • session_id: string

会话 ID。

minLength: 0, maxLength: 1048576

  • subagent_id: string

此会话中的子智能体 ID。

minLength: 0, maxLength: 1048576

查询参数

  • after: optional string

按选定顺序返回此资源 ID 之后的资源。

minLength: 0, maxLength: 1048576

  • limit: optional integer (default: 20)

返回资源的最大数量,范围为 1 至 100,默认为 20。

format: int64, minimum: 1, maximum: 100

  • order: optional "asc" or "desc" (default: "desc")

返回资源的排序方式,默认为 desc。

  • "asc"

按升序返回资源。

  • "desc"

按降序返回资源。

返回值

  • data: array of Turn

本页返回的资源,按指定顺序排列。

minItems: 0, maxItems: 2000

  • id: string

轮次 ID。

minLength: 0

  • agent_id: string

执行本轮的智能体 ID。

minLength: 0

  • completed_at: integer or null

轮次进入终态的 Unix 时间戳,单位为秒。

format: int64

  • created_at: integer

用于按创建时间排序的 Unix 时间戳,单位为秒。子智能体轮次优先使用开始时间,其次使用完成时间,前两者均不可用时使用子智能体打开的时间。

format: int64

  • error: SessionTurnError or null

可向客户显示的错误。仅轮次失败时为非空值。

  • code: "context_length_exceeded" or "max_output_tokens" or "usage_limit_exceeded" or 21 more

稳定的、可供程序识别的失败类别。

  • "context_length_exceeded"

请求超出模型的上下文窗口。

  • "max_output_tokens"

模型完成响应之前已达到输出词元上限。

  • "usage_limit_exceeded"

组织已达到用量、套餐或计费限制。

  • "api_key_spend_limit_exceeded"

API 密钥已达到强制支出上限。

  • "project_spend_limit_exceeded"

项目已达到强制支出上限。

  • "organization_spend_limit_exceeded"

组织已达到强制支出上限。

  • "organization_usage_limit_exceeded"

组织已达到 OpenAI 分配的用量上限。

  • "billing_not_active"

账户尚未启用计费。

  • "credit_balance_exhausted"

组织的 API 余额已经用尽。

  • "rate_limit_exceeded"

请求超过可用的速率限制。

  • "flex_unavailable"

Flex 处理暂时不可用。

  • "server_overloaded"

模型服务暂时过载。

  • "cyber_policy"

请求因安全策略被拒绝。

  • "misalignment_policy_violation"

请求被安全系统拦截。

  • "connection_failed"

请求未能连接到模型服务。

  • "server_error"

模型服务遇到意外错误。

  • "authentication_error"

API 凭证无效或权限不足。

  • "invalid_request"

请求包含无效输入或配置。

  • "resource_not_found"

请求的模型或资源不可用。

  • "sandbox_error"

请求未能在其执行环境中完成。

  • "executor_version_incompatible"

执行器必须升级后才能运行此轮。

  • "active_turn_not_steerable"

请求运行期间,会话无法接收额外输入。

  • "request_timeout"

模型服务响应前,请求已超时。

  • "internal_error"

意外的内部错误导致会话请求未能完成。

  • message: string

可向客户显示的失败原因。

minLength: 0

  • object: "agent.session.turn" (default: "agent.session.turn")

对象类型,固定为 agent.session.turn。

  • "agent.session.turn"

  • session_id: string

此轮次所属会话的 ID。

minLength: 0

  • started_at: integer or null

轮次开始时的 Unix 时间戳,单位为秒。

format: int64

  • status: "queued" or "in_progress" or "waiting" or 3 more

轮次当前的状态。

  • "queued"

轮次正在等待开始。

  • "in_progress"

轮次正在进行。

  • "waiting"

轮次正在等待外部输入。

  • "completed"

轮次已成功完成。

  • "failed"

轮次失败。

  • "cancelled"

轮次已取消。

  • subagent_id: string or null

执行此轮的子智能体 ID(如适用)。

minLength: 0

  • usage: TokenUsage or null

本轮可统计到的词元用量。用量未知时为 null,已记录的用量可能变化。

  • input_tokens: integer

智能体使用的输入词元数。

format: int64

  • input_tokens_details: object { cached_tokens }

智能体输入词元用量的明细。

  • cached_tokens: integer

从提示词缓存中读取的输入词元数。

format: int64

  • output_tokens: integer

智能体生成的输出词元数。

format: int64

  • output_tokens_details: object { reasoning_tokens }

智能体输出词元用量的明细。

  • reasoning_tokens: integer

用于推理的输出词元数。

format: int64

  • total_tokens: integer

智能体使用的输入词元与输出词元的总数。

format: int64

  • prompt_cache_options: optional object { ttl } or null

本轮开始时选用的提示词缓存时长,可继承会话的缓存生存时间。使用模型默认值或未记录缓存时长时为 null。

  • ttl: "30m" or "12h"

  • "30m"

  • "12h"

  • first_id: string or null

data 中第一项的资源 ID。当前页为空时为 null。

minLength: 0

  • has_more: boolean

当前页之后是否还有可获取的资源。

  • last_id: string or null

data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。

minLength: 0

  • object: "list" (default: "list")

对象类型,恒为 list。

  • "list"

示例

## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 SUBAGENT_ID 设置为目标子智能体的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/turns \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

200 响应示例

字段名、类型值和示例标识均按接口定义保留。

{
  "data": [
    {
      "id": "id",
      "agent_id": "agent_id",
      "completed_at": 0,
      "created_at": 0,
      "error": {
        "code": "context_length_exceeded",
        "message": "message"
      },
      "object": "agent.session.turn",
      "session_id": "session_id",
      "started_at": 0,
      "status": "queued",
      "subagent_id": "subagent_id",
      "usage": {
        "input_tokens": 0,
        "input_tokens_details": {
          "cached_tokens": 0
        },
        "output_tokens": 0,
        "output_tokens_details": {
          "reasoning_tokens": 0
        },
        "total_tokens": 0
      },
      "prompt_cache_options": {
        "ttl": "30m"
      }
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号