OpenAI 获取子智能体轮次

2026-11-18 18:02 更新

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

获取属于此子智能体的一轮交互。参见子智能体工作流。

路径参数

  • session_id: string

会话 ID。

minLength: 0, maxLength: 1048576

  • subagent_id: string

此会话中的子智能体 ID。

minLength: 0, maxLength: 1048576

  • turn_id: string

属于此子智能体的轮次 ID。

minLength: 0, maxLength: 1048576

返回值

  • Turn object { id, agent_id, completed_at, 9 more }

会话轮次的标准公开表示。

  • 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"

示例

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

200 响应示例

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

{
  "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"
  }
}

查看本轮生成的条目时,可调用列出子智能体轮次条目。

以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号