OpenAI 获取子智能体轮次
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"
}
}
查看本轮生成的条目时,可调用列出子智能体轮次条目。

TRAE-AI编程


更多建议: