OpenAI 智能体流式事件类型

2026-11-18 18:02 更新

agent.session.environment.ready

托管会话环境可以连接时发出。

结构定义

结构名称为 SessionEventAgentSessionEnvironmentReady。

  • environment: AgentSessionEnvironmentState

环境的当前状态。

  • id: string

环境的公开 ID。

minLength: 0

  • error: object { code, message, type } or null

准备环境时报告的错误(如有)。

  • code: string

机器可读的错误代码。

minLength: 0

  • message: string

便于阅读的错误消息。

minLength: 0

  • type: string

错误类型。

minLength: 0

  • status: "pending" or "ready" or "connected" or 4 more

环境的连接状态。

  • "pending"

正在准备环境。

  • "ready"

环境已就绪,可以连接。

  • "connected"

环境已连接。

  • "disconnected"

环境已断开连接。

  • "suspended"

环境已停止,可从其私有检查点恢复。

  • "expired"

环境及其私有检查点已过期。

  • "failed"

环境连接失败。

  • type: string

环境类型。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.environment.ready" (default: "agent.session.environment.ready")

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

  • "agent.session.environment.ready"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.environment.ready",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "environment": {
    "id": "id",
    "type": "type",
    "status": "pending",
    "error": {
      "type": "type",
      "code": "code",
      "message": "message"
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.environment.suspended

空闲的托管会话环境保存检查点并停止后发出。

结构定义

结构名称为 SessionEventAgentSessionEnvironmentSuspended。

  • environment: AgentSessionEnvironmentState

环境的当前状态。

  • id: string

环境的公开 ID。

minLength: 0

  • error: object { code, message, type } or null

准备环境时报告的错误(如有)。

  • code: string

机器可读的错误代码。

minLength: 0

  • message: string

便于阅读的错误消息。

minLength: 0

  • type: string

错误类型。

minLength: 0

  • status: "pending" or "ready" or "connected" or 4 more

环境的连接状态。

  • "pending"

正在准备环境。

  • "ready"

环境已就绪,可以连接。

  • "connected"

环境已连接。

  • "disconnected"

环境已断开连接。

  • "suspended"

环境已停止,可从其私有检查点恢复。

  • "expired"

环境及其私有检查点已过期。

  • "failed"

环境连接失败。

  • type: string

环境类型。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.environment.suspended" (default: "agent.session.environment.suspended")

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

  • "agent.session.environment.suspended"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.environment.suspended",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "environment": {
    "id": "id",
    "type": "type",
    "status": "pending",
    "error": {
      "type": "type",
      "code": "code",
      "message": "message"
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.environment.expired

已挂起的托管会话环境及其检查点过期后发出。

结构定义

结构名称为 SessionEventAgentSessionEnvironmentExpired。

  • environment: AgentSessionEnvironmentState

环境的当前状态。

  • id: string

环境的公开 ID。

minLength: 0

  • error: object { code, message, type } or null

准备环境时报告的错误(如有)。

  • code: string

机器可读的错误代码。

minLength: 0

  • message: string

便于阅读的错误消息。

minLength: 0

  • type: string

错误类型。

minLength: 0

  • status: "pending" or "ready" or "connected" or 4 more

环境的连接状态。

  • "pending"

正在准备环境。

  • "ready"

环境已就绪,可以连接。

  • "connected"

环境已连接。

  • "disconnected"

环境已断开连接。

  • "suspended"

环境已停止,可从其私有检查点恢复。

  • "expired"

环境及其私有检查点已过期。

  • "failed"

环境连接失败。

  • type: string

环境类型。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.environment.expired" (default: "agent.session.environment.expired")

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

  • "agent.session.environment.expired"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.environment.expired",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "environment": {
    "id": "id",
    "type": "type",
    "status": "pending",
    "error": {
      "type": "type",
      "code": "code",
      "message": "message"
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.environment.reset

托管沙箱被替换后发出。对话历史保留,旧沙箱中的文件改动和进程不会延续到新沙箱。

结构定义

结构名称为 SessionEventAgentSessionEnvironmentReset。

  • environment_id: string

保持稳定的环境 ID,替换沙箱时沿用此 ID。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • reset_count: integer

单调递增的重置序号。同一次重置的重复通知使用相同序号。

format: int64, minimum: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

关联的轮次(如适用)。

minLength: 0

  • type: "agent.session.environment.reset" (default: "agent.session.environment.reset")

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

  • "agent.session.environment.reset"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.environment.reset",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "environment_id": "environment_id",
  "reset_count": 0,
  "obfuscation": "obfuscation"
}

agent.output.command_execution_output.delta

命令执行产生新增输出时发出。

结构定义

结构名称为 SessionEventAgentOutputCommandExecutionOutputDelta。

  • delta: string

此次追加的输出文本。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item_id: string

命令执行条目的 ID。

minLength: 0

  • output_index: integer

条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.output.command_execution_output.delta" (default: "agent.output.command_execution_output.delta")

对象类型,固定为 agent.output.command_execution_output.delta。

  • "agent.output.command_execution_output.delta"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.output.command_execution_output.delta",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "item_id": "item_id",
  "output_index": 0,
  "delta": "delta",
  "obfuscation": "obfuscation"
}

agent.session.created

创建会话时发出。

结构定义

结构名称为 SessionEventAgentSessionCreated。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session: AgentSession

新创建的会话。

  • id: string

会话 ID。

minLength: 0

  • agent: object { id, instructions, model, 8 more }

在会话内运行的智能体。

  • id: string

智能体的 ID。

minLength: 0

  • instructions: string or null

附加到智能体默认基础指令之后的自定义指令。

minLength: 0

  • model: string

智能体使用的模型。

minLength: 0

  • multi_agent: MultiAgentConfig

创建和协调子智能体的配置。

  • enabled: boolean

是否启用子智能体工具。默认关闭。

  • max_concurrent_subagents: integer or null

可同时运行的子智能体数上限。禁用时为 null,启用时默认为 6。

format: int64, minimum: 1, maximum: 4294967295

  • name: string or null

创建会话时可复用智能体的名称。没有保存名称时为 null。之后修改智能体名称不会改变此值。

minLength: 0

  • reasoning: AgentReasoning

智能体的推理配置。

  • effort: "none" or "minimal" or "low" or 4 more or null

请求的推理强度。由模型选择推理强度时为 null。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • summary: "concise" or "detailed" or "auto" or null

请求的推理摘要格式。禁用摘要时为 null。

  • "concise"

模型支持时,返回简明推理摘要。

  • "detailed"

模型支持时,返回详细推理摘要。

  • "auto"

自动选择模型支持的最详细摘要。

  • service_tier: "auto" or "default" or "flex" or 3 more

模型请求实际采用的服务层级策略。默认为 auto。

  • "auto"

  • "default"

  • "flex"

  • "priority"

  • "fast"

  • "ultrafast"

  • text: AgentText

智能体生成文本的配置。

  • format: TextFormat

当前生效的输出格式,默认为普通文本。

  • Text object { type }

生成普通文本,无结构化输出限制。

  • type: "text" (default: "text")

对象类型,恒为 text。

  • "text"

  • JSONSchema object { schema, type }

将生成的文本限制为符合指定 JSON Schema。

  • schema: map[unknown]

生成的文本必须符合的 JSON Schema。

  • type: "json_schema" (default: "json_schema")

对象类型,恒为 json_schema。

  • "json_schema"

  • verbosity: "low" or "medium" or "high"

智能体生成文本的量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • tools: array of AgentTool

智能体可用的工具。

minItems: 0, maxItems: 2000

  • Function object { defer_loading, description, name, 3 more }

应用定义的函数。

  • defer_loading: boolean

函数是否延迟加载并通过工具搜索发现。

  • description: string

说明函数的用途。

minLength: 0

  • name: string

函数名称。

minLength: 0

  • parameters: map[unknown]

描述函数参数的 JSON Schema 对象。

  • type: "function" (default: "function")

对象类型,恒为 function。

  • "function"

  • async: optional boolean

智能体是否无需等待函数结果即可继续。

  • ProgrammaticToolCalling object { enabled, type }

允许模型生成的代码调用工具。

  • enabled: boolean

是否允许从模型生成的代码调用工具。

  • type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

对象类型,恒为 programmatic_tool_calling。

  • "programmatic_tool_calling"

  • Mcp object { allowed_tools, connection_origin, credential_id, 5 more }

远程 MCP 服务器提供的工具。

  • allowed_tools: array of string or null

智能体可调用的 MCP 工具。

minItems: 0, maxItems: 2000

  • connection_origin: "service" or "environment"

出站 MCP HTTP 连接的来源。

  • "service"

  • "environment"

  • credential_id: string or null

为此 MCP 服务器选用的已附加凭证库凭证(如有)。只有一条已附加凭证与服务器 URL 匹配时,可以省略。

minLength: 0

  • request_metadata: map[unknown]

随请求发送给此 MCP 服务器的元数据。

  • required: boolean

是否必须在第一轮前初始化此 MCP 服务器。

  • server_label: string

用于在工具调用中标识 MCP 服务器的标签。

minLength: 0

  • transport: McpTransport

用于连接 MCP 服务器的传输方式。

  • HTTP object { server_url, type }

通过 HTTP 连接到 MCP 服务器。

  • server_url: string

MCP 服务器的 URL。

minLength: 0

  • type: "http" (default: "http")

对象类型,恒为 http。

  • "http"

  • Stdio object { args, command, cwd, 2 more }

以本地进程方式启动 MCP 服务器。

  • args: array of string

传递给 MCP 服务器启动命令的参数。

minItems: 0, maxItems: 2000

  • command: string

用于启动 MCP 服务器的命令。

minLength: 0

  • cwd: string

用于启动 MCP 服务器的工作目录。

minLength: 0

  • env_vars: array of string

从执行环境继承的环境变量名称。

minItems: 0, maxItems: 2000

  • type: "stdio" (default: "stdio")

对象类型,恒为 stdio。

  • "stdio"

  • type: "mcp" (default: "mcp")

对象类型,恒为 mcp。

  • "mcp"

  • WebSearch object { allowed_domains, context_size, location, 2 more }

网页搜索。

  • allowed_domains: array of string or null

允许搜索的域名。搜索范围不受限制时为 null。

minItems: 0, maxItems: 2000

  • context_size: "low" or "medium" or "high"

向模型提供的搜索上下文量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • location: object { city, country, region, timezone } or null

用于按地理位置调整搜索结果的近似位置(如果提供)。

  • city: string or null

城市名称。

minLength: 0

  • country: string or null

两个字母的 ISO 国家或地区代码,例如 US。

minLength: 0

  • region: string or null

地区或州的名称。

minLength: 0

  • timezone: string or null

IANA 时区,例如 America/Los_Angeles。

minLength: 0

  • mode: "disabled" or "cached" or "live"

网页搜索结果的来源。

  • "disabled"

  • "cached"

  • "live"

  • type: "web_search" (default: "web_search")

对象类型,恒为 web_search。

  • "web_search"

  • ComputerUse object { include_screenshots, type }

在 OpenAI 托管会话中使用浏览器。

  • include_screenshots: boolean

计算机工具的输出是否包含屏幕截图。

  • type: "computer_use" (default: "computer_use")

对象类型,恒为 computer_use。

  • "computer_use"

  • Automations object { type }

允许智能体安排自身的定时唤醒。

  • type: "automations" (default: "automations")

对象类型,恒为 automations。

  • "automations"

  • compaction: optional object { async }

当前生效的上下文压缩配置。

  • async: boolean

是否在后台压缩上下文。默认为 false。

  • experimental: optional object { time_awareness }

当前生效的实验性设置。

  • time_awareness: boolean

模型是否会定期收到当前时间提醒。

  • created_at: integer

会话创建时的 Unix 时间戳,单位为秒。

format: int64

  • environment: Environment

会话的执行环境。

  • None object { type }

会话与 CCA 通信,无需选择或配置执行环境。

  • type: "none" (default: "none")

对象类型,固定为 none。

  • "none"

  • OpenAIHosted object { id, capability_directories, desktop, 7 more }

OpenAI 托管的环境。

  • id: string

环境的公开 ID。

minLength: 0

  • capability_directories: array of string

包含可向智能体提供的能力的目录。

minItems: 0, maxItems: 2000

  • desktop: object { enabled }

当前生效的桌面配置。

  • enabled: boolean

环境是否配置桌面及浏览器代理。

  • files: array of HostedEnvironmentFile

环境中的可用文件。响应省略文件内容。

minItems: 0, maxItems: 50

  • HostedEnvironmentFileID object { id, file_id, path, 2 more }

从 OpenAI Files API 复制的文件。

  • id: string

执行环境中会话范围内的文件 ID。

minLength: 0

  • file_id: string

已上传文件的 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "file_id" (default: "file_id")

对象类型,固定为 file_id。

  • "file_id"

  • Inline object { id, path, size_bytes, type }

创建会话时以内联方式提供的文件。

  • id: string

执行环境中会话范围内的文件 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • network: object { access, allowed_domains }

当前生效的环境网络访问策略。

  • access: "enabled" or "disabled" or "restricted"

环境的网络访问模式。

  • "enabled"

允许不受限制的网络访问。

  • "disabled"

关闭网络访问。

  • "restricted"

应用配置的域名访问限制。

  • allowed_domains: array of string

网络访问受限时,环境可以访问的域名。

minItems: 0, maxItems: 2000

  • packages: object { npm, python, system }

在环境中安装的软件包。

  • npm: array of string

在环境中全局安装的 npm 软件包。

minItems: 0, maxItems: 16384

  • python: array of string

已安装到环境中的 Python 软件包。

minItems: 0, maxItems: 16384

  • system: array of string

已安装到环境中的系统软件包。

minItems: 0, maxItems: 16384

  • plugins: array of HostedPlugin

在环境中安装的插件。响应省略其归档内容。

minItems: 0, maxItems: 2000

  • description: string

已安装插件的描述。

minLength: 0

  • name: string

已安装插件的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • skills: array of HostedSkill

在环境中安装的技能。响应省略其归档内容。

minItems: 0, maxItems: 2000

  • HostedSkillReference object { description, name, skill_id, 2 more }

从 Skills API 安装的技能。

  • description: string

已安装技能的描述。

minLength: 0

  • name: string

已安装技能的名称。

minLength: 0

  • skill_id: string

引用的技能 ID。

minLength: 0

  • type: "skill_reference" (default: "skill_reference")

对象类型,固定为 skill_reference。

  • "skill_reference"

  • version: string

此会话实际安装的技能版本。

minLength: 0

  • Inline object { description, name, type }

从内联 ZIP 归档安装的技能。

  • description: string

已安装技能的描述。

minLength: 0

  • name: string

已安装技能的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • type: "openai_hosted" (default: "openai_hosted")

对象类型,固定为 openai_hosted。

  • "openai_hosted"

  • container_size: optional "small" or "medium" or "large" or null

实际使用的 CPU 和内存规格。规格未知或超出公开规格范围时为 null。

  • "small"

  • "medium"

  • "large"

  • SelfHosted object { id, capability_directories, remote_url, 2 more }

应用托管的环境。

  • id: string

环境的公开 ID。

minLength: 0

  • capability_directories: array of string

包含可向智能体提供的能力的目录。

minItems: 0, maxItems: 2000

  • remote_url: string

连接此环境时,将此 URL 原样传给 codex exec-server --remote。

minLength: 0

  • type: "self_hosted" (default: "self_hosted")

对象类型,固定为 self_hosted。

  • "self_hosted"

  • workspace_directory: string

环境内项目目录的绝对路径,默认为 /workspace。

minLength: 0

  • error: string or null

导致会话失败的错误(如有)。

minLength: 0

  • last_active_at: integer

会话最后一次活跃时的 Unix 时间戳,单位为秒。

format: int64

  • metadata: map[string]

附加到会话的自定义字符串键值对。

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

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

  • "agent.session"

  • required_actions: array of McpApprovalRequest { request, request_id, turn_id, type } or ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }

会话继续之前必须完成的操作。

minItems: 0, maxItems: 2000

  • McpApprovalRequest object { request, request_id, turn_id, type }

响应 MCP 工具调用的审批请求。

  • request: object { arguments, message, name, 2 more }

呈现 MCP 审批所需的信息。

  • arguments: unknown

JSON 格式的工具参数。CCA 未提供时为 null。

  • message: string

minLength: 0

  • name: string or null

工具的名称。CCA 未提供时为 null。

minLength: 0

  • server_label: string

minLength: 0

  • type: "mcp_tool_call" (default: "mcp_tool_call")

对象类型,固定为 mcp_tool_call。

  • "mcp_tool_call"

  • request_id: string

响应时需要原样返回的不透明审批 ID。

minLength: 0

  • turn_id: string

请求审批的轮次。

minLength: 0

  • type: "mcp_approval_request" (default: "mcp_approval_request")

对象类型,固定为 mcp_approval_request。

  • "mcp_approval_request"

  • ComputerUseApprovalRequest object { request, request_id, turn_id, type }

响应计算机使用请求。

  • request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }

呈现该请求所需的信息。

  • BrowserAuthentication object { credential_origin, fields, options, 2 more }

等待应用响应的已注册表单。

  • credential_origin: string or null

将在其上填写值的已注册表单或框架的源站。

minLength: 0

  • fields: array of object { id, label, required, type }

要呈现的表单控件。所有提交的值均为敏感数据。

minItems: 0, maxItems: 2000

  • id: string

提交 fields 条目时要用作 field_id 的字段 ID。

minLength: 0

  • label: string

显示在控件旁的标签。

minLength: 0

  • required: boolean

此控件是否需要非空值。

  • type: string

控件的呈现类型,例如电子邮件、密码或文本。

minLength: 0

  • options: array of object { id, field_ids, label }

登录方式。普通表单中为空。

minItems: 0, maxItems: 2000

  • id: string

作为 selected_option 提交的选项 ID。

minLength: 0

  • field_ids: array of string

此方法接受的已注册字段 ID。

minItems: 0, maxItems: 2000

  • label: string

要显示的方式标签。

minLength: 0

  • reason: string or null

智能体需要用户登录的原因。

minLength: 0

  • type: "browser_authentication" (default: "browser_authentication")

对象类型,固定为 browser_authentication。

  • "browser_authentication"

  • BrowserOriginAccess object { origin, reason, type }

等待应用审批决定的浏览器源站。

  • origin: string

浏览器要访问且需要授权的源站。

minLength: 0

  • reason: string or null

浏览器对本请求的说明。无法取得时为 null。

minLength: 0

  • type: "browser_origin_access" (default: "browser_origin_access")

对象类型,固定为 browser_origin_access。

  • "browser_origin_access"

  • request_id: string

响应时需要原样返回的已注册请求 ID。

minLength: 0

  • turn_id: string

请求审批的轮次。

minLength: 0

  • type: "computer_use_approval_request" (default: "computer_use_approval_request")

对象类型,固定为 computer_use_approval_request。

  • "computer_use_approval_request"

  • FunctionCall object { arguments, call_id, name, 2 more }

运行函数工具并提交其结果。

  • arguments: unknown

模型提供的参数。

  • call_id: string

提交函数结果时应包含的 ID。

minLength: 0

  • name: string

函数的名称。

minLength: 0

  • turn_id: string

请求函数调用的轮次 ID。

minLength: 0

  • type: "function_call" (default: "function_call")

对象类型,固定为 function_call。

  • "function_call"

  • EnvironmentConnection object { environment_id, type }

重新连接会话环境。

  • environment_id: string

要重新连接的环境 ID。

minLength: 0

  • type: "environment_connection" (default: "environment_connection")

对象类型,固定为 environment_connection。

  • "environment_connection"

  • status: "idle" or "in_progress" or "requires_action" or "failed"

会话当前的状态。

  • "idle"

会话没有正在进行的轮次,可以接收输入。托管环境可能仍在配置中。

  • "in_progress"

会话正在处理一轮交互。

  • "requires_action"

会话正在等待一个或多个必需操作。

  • "failed"

会话已失败。

  • 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

  • vault_ids: array of string

本会话可访问的凭证库 ID。

minItems: 0, maxItems: 2000

  • prompt_cache_options: optional object { ttl } or null

此会话各轮次采用的默认提示词缓存时长(如已配置)。

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

  • "30m"

  • "12h"

  • review: optional "none" or "auto_review"

应用于本会话中适用操作的审查方式。审查模式为 none 且自动审查未启用时,响应省略此字段。字段省略表示 none。

  • "none"

  • "auto_review"

  • type: "agent.session.created" (default: "agent.session.created")

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

  • "agent.session.created"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.created",
  "event_id": "event_id",
  "session": {
    "prompt_cache_options": {
      "ttl": "30m"
    },
    "review": "none",
    "metadata": {
      "foo": "string"
    },
    "id": "id",
    "object": "agent.session",
    "created_at": 0,
    "last_active_at": 0,
    "status": "idle",
    "required_actions": [
      {
        "type": "mcp_approval_request",
        "turn_id": "turn_id",
        "request_id": "request_id",
        "request": {
          "type": "mcp_tool_call",
          "server_label": "server_label",
          "name": "name",
          "arguments": {},
          "message": "message"
        }
      }
    ],
    "error": "error",
    "agent": {
      "id": "id",
      "name": "name",
      "model": "model",
      "reasoning": {
        "effort": "none",
        "summary": "concise"
      },
      "text": {
        "format": {
          "type": "text"
        },
        "verbosity": "low"
      },
      "service_tier": "auto",
      "instructions": "instructions",
      "tools": [
        {
          "type": "function",
          "name": "name",
          "description": "description",
          "parameters": {
            "foo": "bar"
          },
          "defer_loading": true,
          "async": true
        }
      ],
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 1
      },
      "compaction": {
        "async": true
      },
      "experimental": {
        "time_awareness": true
      }
    },
    "environment": {
      "type": "none"
    },
    "vault_ids": [
      "string"
    ],
    "usage": {
      "input_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.created

创建轮次时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnCreated。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn: Turn

轮次创建时的状态。

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

  • turn_id: string

与事件关联的轮次 ID。

minLength: 0

  • type: "agent.session.turn.created" (default: "agent.session.turn.created")

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

  • "agent.session.turn.created"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.created",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "turn": {
    "prompt_cache_options": {
      "ttl": "30m"
    },
    "id": "id",
    "object": "agent.session.turn",
    "session_id": "session_id",
    "agent_id": "agent_id",
    "subagent_id": "subagent_id",
    "status": "queued",
    "created_at": 0,
    "started_at": 0,
    "completed_at": 0,
    "error": {
      "code": "context_length_exceeded",
      "message": "message"
    },
    "usage": {
      "input_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.in_progress

轮次开始运行时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnInProgress。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn: Turn

轮次开始运行时的状态。

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

  • turn_id: string

与事件关联的轮次 ID。

minLength: 0

  • type: "agent.session.turn.in_progress" (default: "agent.session.turn.in_progress")

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

  • "agent.session.turn.in_progress"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.in_progress",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "turn": {
    "prompt_cache_options": {
      "ttl": "30m"
    },
    "id": "id",
    "object": "agent.session.turn",
    "session_id": "session_id",
    "agent_id": "agent_id",
    "subagent_id": "subagent_id",
    "status": "queued",
    "created_at": 0,
    "started_at": 0,
    "completed_at": 0,
    "error": {
      "code": "context_length_exceeded",
      "message": "message"
    },
    "usage": {
      "input_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.completed

轮次完成时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnCompleted。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn: Turn

已完成的轮次。

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

  • turn_id: string

与事件关联的轮次 ID。

minLength: 0

  • type: "agent.session.turn.completed" (default: "agent.session.turn.completed")

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

  • "agent.session.turn.completed"

  • usage: TokenUsage or null

本轮根智能体的词元用量(如能取得)。

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.completed",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "turn": {
    "prompt_cache_options": {
      "ttl": "30m"
    },
    "id": "id",
    "object": "agent.session.turn",
    "session_id": "session_id",
    "agent_id": "agent_id",
    "subagent_id": "subagent_id",
    "status": "queued",
    "created_at": 0,
    "started_at": 0,
    "completed_at": 0,
    "error": {
      "code": "context_length_exceeded",
      "message": "message"
    },
    "usage": {
      "input_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0
    }
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.failed

轮次失败时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnFailed。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn: Turn

已失败的轮次。

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

  • turn_id: string

与事件关联的轮次 ID。

minLength: 0

  • type: "agent.session.turn.failed" (default: "agent.session.turn.failed")

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

  • "agent.session.turn.failed"

  • usage: TokenUsage or null

本轮根智能体的词元用量(如能取得)。

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.failed",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "turn": {
    "prompt_cache_options": {
      "ttl": "30m"
    },
    "id": "id",
    "object": "agent.session.turn",
    "session_id": "session_id",
    "agent_id": "agent_id",
    "subagent_id": "subagent_id",
    "status": "queued",
    "created_at": 0,
    "started_at": 0,
    "completed_at": 0,
    "error": {
      "code": "context_length_exceeded",
      "message": "message"
    },
    "usage": {
      "input_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0
    }
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.cancelled

轮次取消时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnCancelled。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn: Turn

已取消的轮次。

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

  • turn_id: string

与事件关联的轮次 ID。

minLength: 0

  • type: "agent.session.turn.cancelled" (default: "agent.session.turn.cancelled")

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

  • "agent.session.turn.cancelled"

  • usage: TokenUsage or null

本轮根智能体的词元用量(如能取得)。

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.cancelled",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "turn": {
    "prompt_cache_options": {
      "ttl": "30m"
    },
    "id": "id",
    "object": "agent.session.turn",
    "session_id": "session_id",
    "agent_id": "agent_id",
    "subagent_id": "subagent_id",
    "status": "queued",
    "created_at": 0,
    "started_at": 0,
    "completed_at": 0,
    "error": {
      "code": "context_length_exceeded",
      "message": "message"
    },
    "usage": {
      "input_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0
    }
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.item.added

将条目添加到轮次时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnItemAdded。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item: AgentSessionItem

新添加的条目。

  • AgentSessionMessage object { id, content, phase, 4 more }

记录在会话中的用户消息或助手消息。

  • id: string or null

此条目的 ID。未记录 ID 的旧版用户消息返回 null。

minLength: 0

  • content: array of AgentSessionMessageContent

消息内容。用户消息含输入文本或图像,助手消息含输出文本。

minItems: 0, maxItems: 2000

  • InputText object { text, type }

用户提供的文本。

  • text: string

用户提供的文本。

minLength: 0

  • type: "input_text" (default: "input_text")

对象类型,固定为 input_text。

  • "input_text"

  • InputImage object { image_url, type }

用户提供的图像。

  • image_url: string

用户提供的图像 URL,可以是以 Base64 编码的 data URL。

minLength: 0

  • type: "input_image" (default: "input_image")

对象类型,固定为 input_image。

  • "input_image"

  • OutputText object { text, type }

助手生成的文本。

  • text: string

助手生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

对象类型,固定为 output_text。

  • "output_text"

  • phase: "commentary" or "final_answer" or null

助手消息所处的阶段。用户消息的此字段为 null。

  • "commentary"

智能体工作时生成的过程说明。

  • "final_answer"

智能体的最终回答。

  • role: "user" or "assistant"

消息作者的角色。

  • "user"

  • "assistant"

  • status: AgentOutputItemStatus

消息的状态。用户消息始终为 completed。

  • "in_progress"

条目正在处理。

  • "completed"

条目处理已完成。

  • "incomplete"

条目在完成前已停止。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "message" (default: "message")

类型,固定为message。

  • "message"

  • AgentReasoningItem object { id, status, summary, 2 more }

智能体生成的推理条目。

  • id: string

推理条目的 ID。

minLength: 0

  • status: AgentOutputItemStatus or null

推理条目的状态。

  • summary: array of SummaryText

智能体生成的推理摘要。

minItems: 0, maxItems: 2000

  • text: string

推理摘要文本。

minLength: 0

  • type: "summary_text" (default: "summary_text")

内容类型,固定为 summary_text。

  • "summary_text"

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "reasoning" (default: "reasoning")

条目类型,固定为 reasoning。

  • "reasoning"

  • AgentFunctionCallItem object { id, arguments, call_id, 4 more }

智能体生成的函数调用。

  • id: string

函数调用条目的 ID。

minLength: 0

  • arguments: unknown

要传给函数的参数。

  • call_id: string

用于提交函数结果的 ID。

minLength: 0

  • name: string

要调用的函数名称。

minLength: 0

  • status: AgentFunctionCallStatus

函数调用的状态。

  • "in_progress"

调用正在进行。

  • "completed"

调用已成功完成。

  • "failed"

调用失败。

  • "incomplete"

调用在完成前已停止。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "function_call" (default: "function_call")

条目类型,固定为 function_call。

  • "function_call"

  • FunctionCallOutput object { id, call_id, error, 4 more }

为函数调用提供的结果。

  • id: string

函数调用输出条目的 ID。

minLength: 0

  • call_id: string

生成此输出的函数调用 ID。

minLength: 0

  • error: string or null

调用失败时的错误消息。

minLength: 0

  • output: AgentFunctionCallOutput or null

调用成功时的函数结果。

  • string

minLength: 0

  • array of InputContent

minItems: 0, maxItems: 2000

  • InputText object { text, type }

记录在会话条目中的文本输入。

  • text: string

提供给智能体的文本。

minLength: 0

  • type: "input_text" (default: "input_text")

对象类型,固定为 input_text。

  • "input_text"

  • InputImage object { image_url, type }

记录在会话条目中的图像输入。

  • image_url: string

提供给智能体的图像 URL,可以是以 Base64 编码的 data URL。

minLength: 0

  • type: "input_image" (default: "input_image")

对象类型,固定为 input_image。

  • "input_image"

  • status: AgentFunctionCallStatus

函数调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "function_call_output" (default: "function_call_output")

条目类型,固定为 function_call_output。

  • "function_call_output"

  • AgentMessage object { id, content, recipient_agent_id, 3 more }

智能体线程之间交换的消息。

  • id: string

消息 ID。

minLength: 0

  • content: array of AgentContent

智能体之间交换的内容。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • text: string

智能体生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

内容类型,固定为 output_text。

  • "output_text"

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • encrypted_content: string

加密内容载荷。

minLength: 0

  • type: "encrypted_content" (default: "encrypted_content")

内容类型,固定为 encrypted_content。

  • "encrypted_content"

  • recipient_agent_id: string

接收方智能体的 ID 或名称。

minLength: 0

  • sender_agent_id: string

发送方智能体的 ID 或名称。

minLength: 0

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "agent_message" (default: "agent_message")

条目类型,固定为 agent_message。

  • "agent_message"

  • AgentMcpCallItem object { id, arguments, error, 6 more }

调用 MCP 服务器工具的记录。

  • id: string

MCP 调用条目的 ID。

minLength: 0

  • arguments: unknown

传给 MCP 工具的参数。

  • error: unknown

MCP 工具返回的错误(如果有)。

  • name: string

MCP 工具名称。

minLength: 0

  • output: unknown

MCP 工具返回的输出(如果有)。

  • server_label: string

MCP服务器标签。

minLength: 0

  • status: AgentFunctionCallStatus

MCP 工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "mcp_call" (default: "mcp_call")

条目类型,固定为 mcp_call。

  • "mcp_call"

  • ComputerUseCall object { id, output, status, 3 more }

平台提供的计算机使用功能的一次执行。

  • id: string

活动条目的 ID。

minLength: 0

  • output: object { image_url, type } or null

模型发出的最后一张屏幕截图。未启用返回截图,或调用未生成截图时为 null。

  • image_url: string

完整的 JPEG 图像,表示为 Base64 data URL。

minLength: 0

  • type: "computer_screenshot" (default: "computer_screenshot")

内容类型,固定为 computer_screenshot。

  • "computer_screenshot"

  • status: AgentFunctionCallStatus

活动的执行状态。

  • title: string or null

模型生成的活动说明(如果有)。

minLength: 0

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "computer_use_call" (default: "computer_use_call")

条目类型,固定为 computer_use_call。

  • "computer_use_call"

  • ComputerUseApprovalRequest object { id, request, request_id, 2 more }

已发出登录请求的历史记录,其中省略凭证。

  • id: string

稳定的历史条目 ID。

minLength: 0

  • request: object { credential_origin, fields, options, 2 more }

等待应用响应的已注册表单。

  • credential_origin: string or null

将在其上填写值的已注册表单或框架的源站。

minLength: 0

  • fields: array of object { id, label, required, type }

要呈现的表单控件。所有提交的值均为敏感数据。

minItems: 0, maxItems: 2000

  • id: string

提交 fields 条目时要用作 field_id 的字段 ID。

minLength: 0

  • label: string

显示在控件旁的标签。

minLength: 0

  • required: boolean

此控件是否需要非空值。

  • type: string

控件的呈现类型,例如电子邮件、密码或文本。

minLength: 0

  • options: array of object { id, field_ids, label }

登录方式。普通表单中为空。

minItems: 0, maxItems: 2000

  • id: string

作为 selected_option 提交的选项 ID。

minLength: 0

  • field_ids: array of string

此方法接受的已注册字段 ID。

minItems: 0, maxItems: 2000

  • label: string

要显示的方式标签。

minLength: 0

  • reason: string or null

智能体需要用户登录的原因。

minLength: 0

  • type: "browser_authentication" (default: "browser_authentication")

对象类型,固定为 browser_authentication。

  • "browser_authentication"

  • request_id: string

minLength: 0

  • turn_id: string

minLength: 0

  • type: "computer_use_approval_request" (default: "computer_use_approval_request")

条目类型,固定为 computer_use_approval_request。

  • "computer_use_approval_request"

  • ComputerUseApprovalRequestResult object { id, request_id, response, 2 more }

已受理响应的记录,其中省略凭证。实际是否完成需另外确认。

  • id: string

稳定的历史条目 ID。

minLength: 0

  • request_id: string

此条目响应的已注册请求。

minLength: 0

  • response: Submit { action, selected_option, type } or Cancel { action, type }

已受理的响应,其中省略提交的凭证值。

  • Submit object { action, selected_option, type }

  • action: "submit" (default: "submit")

  • "submit"

  • selected_option: string or null

选中的登录方式。未提供候选方式时为 null。

minLength: 0

  • type: "browser_authentication" (default: "browser_authentication")

  • "browser_authentication"

  • Cancel object { action, type }

  • action: "cancel" (default: "cancel")

  • "cancel"

  • type: "browser_authentication" (default: "browser_authentication")

  • "browser_authentication"

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "computer_use_approval_request_result" (default: "computer_use_approval_request_result")

  • "computer_use_approval_request_result"

  • AgentWebSearchCallItem object { id, action, status, 2 more }

智能体生成的网页搜索调用。

  • id: string

网页搜索调用 ID。

minLength: 0

  • action: WebSearchAction or null

网页搜索工具执行的操作。

  • Search object { queries, query, type }

一条或一组搜索查询。

  • queries: array of string or null

使用多条查询时的搜索查询列表。

minItems: 0, maxItems: 2000

  • query: string or null

使用单条查询时的搜索查询。

minLength: 0

  • type: "search" (default: "search")

对象类型,固定为 search。

  • "search"

  • OpenPage object { type, url }

打开网页。

  • type: "open_page" (default: "open_page")

对象类型,固定为 open_page。

  • "open_page"

  • url: string or null

打开的网页的 URL。

minLength: 0

  • FindInPage object { pattern, type, url }

在网页中查找文本。

  • pattern: string or null

要查找的文本模式。

minLength: 0

  • type: "find_in_page" (default: "find_in_page")

对象类型,固定为 find_in_page。

  • "find_in_page"

  • url: string or null

执行查找操作的网页 URL。

minLength: 0

  • Other object { type }

其他网页搜索操作。

  • type: "other" (default: "other")

对象类型,固定为 other。

  • "other"

  • status: AgentOutputItemStatus

网页搜索调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "web_search_call" (default: "web_search_call")

条目类型,固定为 web_search_call。

  • "web_search_call"

  • AgentCommandExecutionItem object { id, command, cwd, 6 more }

智能体生成的命令执行记录。

  • id: string

命令执行条目的 ID。

minLength: 0

  • command: string

执行过的命令。

minLength: 0

  • cwd: string or null

执行命令时使用的工作目录。

minLength: 0

  • duration_ms: integer or null

命令执行时长,单位为毫秒。

format: int64

  • exit_code: integer or null

命令执行结束后的进程退出码。

format: int64

  • output: string or null

命令输出(如果有)。

minLength: 0

  • status: AgentFunctionCallStatus

命令执行的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "command_execution" (default: "command_execution")

条目类型,固定为 command_execution。

  • "command_execution"

  • AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }

创建子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • agent_id: string

请求创建子智能体的智能体 ID。

minLength: 0

  • content: array of AgentContent

交给新建智能体的任务。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • model: string or null

为新建的子智能体指定的模型。

minLength: 0

  • reasoning_effort: string or null

为新建的子智能体指定的推理强度。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "create_subagent_call" (default: "create_subagent_call")

条目类型,固定为 create_subagent_call。

  • "create_subagent_call"

  • AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }

向另一智能体发送输入的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • content: array of AgentContent

发给接收方智能体的输入。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • recipient_agent_id: string

接收输入的智能体 ID。

minLength: 0

  • sender_agent_id: string

发送输入的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "send_subagent_input_call" (default: "send_subagent_input_call")

条目类型,固定为 send_subagent_input_call。

  • "send_subagent_input_call"

  • AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

恢复子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_id: string

要恢复的智能体 ID。

minLength: 0

  • sender_agent_id: string

发起恢复请求的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "resume_subagent_call" (default: "resume_subagent_call")

条目类型,固定为 resume_subagent_call。

  • "resume_subagent_call"

  • AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }

等待一个或多个子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_ids: array of string

要等待的智能体 ID 列表。

minItems: 0, maxItems: 2000

  • sender_agent_id: string

等待结果的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "wait_for_subagents_call" (default: "wait_for_subagents_call")

条目类型,固定为 wait_for_subagents_call。

  • "wait_for_subagents_call"

  • AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

中断子智能体当前轮次的请求。该子智能体仍可使用。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_id: string

要中断的智能体 ID。

minLength: 0

  • sender_agent_id: string

发起中断请求的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "interrupt_subagent_call" (default: "interrupt_subagent_call")

条目类型,固定为 interrupt_subagent_call。

  • "interrupt_subagent_call"

  • AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

关闭子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_id: string

要关闭的智能体 ID。

minLength: 0

  • sender_agent_id: string

发起关闭请求的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "close_subagent_call" (default: "close_subagent_call")

条目类型,固定为 close_subagent_call。

  • "close_subagent_call"

  • output_index: integer or null

当条目属于智能体输出时,该条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.turn.item.added" (default: "agent.session.turn.item.added")

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

  • "agent.session.turn.item.added"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.item.added",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "output_index": 0,
  "item": {
    "type": "message",
    "id": "id",
    "turn_id": "turn_id",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "text"
      }
    ],
    "status": "in_progress",
    "phase": "commentary"
  },
  "obfuscation": "obfuscation"
}

agent.session.idle

会话进入空闲状态时发出。

结构定义

结构名称为 SessionEventAgentSessionIdle。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session: AgentSession

已进入空闲状态的会话。

  • id: string

会话 ID。

minLength: 0

  • agent: object { id, instructions, model, 8 more }

在会话内运行的智能体。

  • id: string

智能体的 ID。

minLength: 0

  • instructions: string or null

附加到智能体默认基础指令之后的自定义指令。

minLength: 0

  • model: string

智能体使用的模型。

minLength: 0

  • multi_agent: MultiAgentConfig

创建和协调子智能体的配置。

  • enabled: boolean

是否启用子智能体工具。默认关闭。

  • max_concurrent_subagents: integer or null

可同时运行的子智能体数上限。禁用时为 null,启用时默认为 6。

format: int64, minimum: 1, maximum: 4294967295

  • name: string or null

创建会话时可复用智能体的名称。没有保存名称时为 null。之后修改智能体名称不会改变此值。

minLength: 0

  • reasoning: AgentReasoning

智能体的推理配置。

  • effort: "none" or "minimal" or "low" or 4 more or null

请求的推理强度。由模型选择推理强度时为 null。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • summary: "concise" or "detailed" or "auto" or null

请求的推理摘要格式。禁用摘要时为 null。

  • "concise"

模型支持时,返回简明推理摘要。

  • "detailed"

模型支持时,返回详细推理摘要。

  • "auto"

自动选择模型支持的最详细摘要。

  • service_tier: "auto" or "default" or "flex" or 3 more

模型请求实际采用的服务层级策略。默认为 auto。

  • "auto"

  • "default"

  • "flex"

  • "priority"

  • "fast"

  • "ultrafast"

  • text: AgentText

智能体生成文本的配置。

  • format: TextFormat

当前生效的输出格式,默认为普通文本。

  • Text object { type }

生成普通文本,无结构化输出限制。

  • type: "text" (default: "text")

对象类型,恒为 text。

  • "text"

  • JSONSchema object { schema, type }

将生成的文本限制为符合指定 JSON Schema。

  • schema: map[unknown]

生成的文本必须符合的 JSON Schema。

  • type: "json_schema" (default: "json_schema")

对象类型,恒为 json_schema。

  • "json_schema"

  • verbosity: "low" or "medium" or "high"

智能体生成文本的量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • tools: array of AgentTool

智能体可用的工具。

minItems: 0, maxItems: 2000

  • Function object { defer_loading, description, name, 3 more }

应用定义的函数。

  • defer_loading: boolean

函数是否延迟加载并通过工具搜索发现。

  • description: string

说明函数的用途。

minLength: 0

  • name: string

函数名称。

minLength: 0

  • parameters: map[unknown]

描述函数参数的 JSON Schema 对象。

  • type: "function" (default: "function")

对象类型,恒为 function。

  • "function"

  • async: optional boolean

智能体是否无需等待函数结果即可继续。

  • ProgrammaticToolCalling object { enabled, type }

允许模型生成的代码调用工具。

  • enabled: boolean

是否允许从模型生成的代码调用工具。

  • type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

对象类型,恒为 programmatic_tool_calling。

  • "programmatic_tool_calling"

  • Mcp object { allowed_tools, connection_origin, credential_id, 5 more }

远程 MCP 服务器提供的工具。

  • allowed_tools: array of string or null

智能体可调用的 MCP 工具。

minItems: 0, maxItems: 2000

  • connection_origin: "service" or "environment"

出站 MCP HTTP 连接的来源。

  • "service"

  • "environment"

  • credential_id: string or null

为此 MCP 服务器选用的已附加凭证库凭证(如有)。只有一条已附加凭证与服务器 URL 匹配时,可以省略。

minLength: 0

  • request_metadata: map[unknown]

随请求发送给此 MCP 服务器的元数据。

  • required: boolean

是否必须在第一轮前初始化此 MCP 服务器。

  • server_label: string

用于在工具调用中标识 MCP 服务器的标签。

minLength: 0

  • transport: McpTransport

用于连接 MCP 服务器的传输方式。

  • HTTP object { server_url, type }

通过 HTTP 连接到 MCP 服务器。

  • server_url: string

MCP 服务器的 URL。

minLength: 0

  • type: "http" (default: "http")

对象类型,恒为 http。

  • "http"

  • Stdio object { args, command, cwd, 2 more }

以本地进程方式启动 MCP 服务器。

  • args: array of string

传递给 MCP 服务器启动命令的参数。

minItems: 0, maxItems: 2000

  • command: string

用于启动 MCP 服务器的命令。

minLength: 0

  • cwd: string

用于启动 MCP 服务器的工作目录。

minLength: 0

  • env_vars: array of string

从执行环境继承的环境变量名称。

minItems: 0, maxItems: 2000

  • type: "stdio" (default: "stdio")

对象类型,恒为 stdio。

  • "stdio"

  • type: "mcp" (default: "mcp")

对象类型,恒为 mcp。

  • "mcp"

  • WebSearch object { allowed_domains, context_size, location, 2 more }

网页搜索。

  • allowed_domains: array of string or null

允许搜索的域名。搜索范围不受限制时为 null。

minItems: 0, maxItems: 2000

  • context_size: "low" or "medium" or "high"

向模型提供的搜索上下文量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • location: object { city, country, region, timezone } or null

用于按地理位置调整搜索结果的近似位置(如果提供)。

  • city: string or null

城市名称。

minLength: 0

  • country: string or null

两个字母的 ISO 国家或地区代码,例如 US。

minLength: 0

  • region: string or null

地区或州的名称。

minLength: 0

  • timezone: string or null

IANA 时区,例如 America/Los_Angeles。

minLength: 0

  • mode: "disabled" or "cached" or "live"

网页搜索结果的来源。

  • "disabled"

  • "cached"

  • "live"

  • type: "web_search" (default: "web_search")

对象类型,恒为 web_search。

  • "web_search"

  • ComputerUse object { include_screenshots, type }

在 OpenAI 托管会话中使用浏览器。

  • include_screenshots: boolean

计算机工具的输出是否包含屏幕截图。

  • type: "computer_use" (default: "computer_use")

对象类型,恒为 computer_use。

  • "computer_use"

  • Automations object { type }

允许智能体安排自身的定时唤醒。

  • type: "automations" (default: "automations")

对象类型,恒为 automations。

  • "automations"

  • compaction: optional object { async }

当前生效的上下文压缩配置。

  • async: boolean

是否在后台压缩上下文。默认为 false。

  • experimental: optional object { time_awareness }

当前生效的实验性设置。

  • time_awareness: boolean

模型是否会定期收到当前时间提醒。

  • created_at: integer

会话创建时的 Unix 时间戳,单位为秒。

format: int64

  • environment: Environment

会话的执行环境。

  • None object { type }

会话与 CCA 通信,无需选择或配置执行环境。

  • type: "none" (default: "none")

对象类型,固定为 none。

  • "none"

  • OpenAIHosted object { id, capability_directories, desktop, 7 more }

OpenAI 托管的环境。

  • id: string

环境的公开 ID。

minLength: 0

  • capability_directories: array of string

包含可向智能体提供的能力的目录。

minItems: 0, maxItems: 2000

  • desktop: object { enabled }

当前生效的桌面配置。

  • enabled: boolean

环境是否配置桌面及浏览器代理。

  • files: array of HostedEnvironmentFile

环境中的可用文件。响应省略文件内容。

minItems: 0, maxItems: 50

  • HostedEnvironmentFileID object { id, file_id, path, 2 more }

从 OpenAI Files API 复制的文件。

  • id: string

执行环境中会话范围内的文件 ID。

minLength: 0

  • file_id: string

已上传文件的 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "file_id" (default: "file_id")

对象类型,固定为 file_id。

  • "file_id"

  • Inline object { id, path, size_bytes, type }

创建会话时以内联方式提供的文件。

  • id: string

执行环境中会话范围内的文件 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • network: object { access, allowed_domains }

当前生效的环境网络访问策略。

  • access: "enabled" or "disabled" or "restricted"

环境的网络访问模式。

  • "enabled"

允许不受限制的网络访问。

  • "disabled"

关闭网络访问。

  • "restricted"

应用配置的域名访问限制。

  • allowed_domains: array of string

网络访问受限时,环境可以访问的域名。

minItems: 0, maxItems: 2000

  • packages: object { npm, python, system }

在环境中安装的软件包。

  • npm: array of string

在环境中全局安装的 npm 软件包。

minItems: 0, maxItems: 16384

  • python: array of string

已安装到环境中的 Python 软件包。

minItems: 0, maxItems: 16384

  • system: array of string

已安装到环境中的系统软件包。

minItems: 0, maxItems: 16384

  • plugins: array of HostedPlugin

在环境中安装的插件。响应省略其归档内容。

minItems: 0, maxItems: 2000

  • description: string

已安装插件的描述。

minLength: 0

  • name: string

已安装插件的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • skills: array of HostedSkill

在环境中安装的技能。响应省略其归档内容。

minItems: 0, maxItems: 2000

  • HostedSkillReference object { description, name, skill_id, 2 more }

从 Skills API 安装的技能。

  • description: string

已安装技能的描述。

minLength: 0

  • name: string

已安装技能的名称。

minLength: 0

  • skill_id: string

引用的技能 ID。

minLength: 0

  • type: "skill_reference" (default: "skill_reference")

对象类型,固定为 skill_reference。

  • "skill_reference"

  • version: string

此会话实际安装的技能版本。

minLength: 0

  • Inline object { description, name, type }

从内联 ZIP 归档安装的技能。

  • description: string

已安装技能的描述。

minLength: 0

  • name: string

已安装技能的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • type: "openai_hosted" (default: "openai_hosted")

对象类型,固定为 openai_hosted。

  • "openai_hosted"

  • container_size: optional "small" or "medium" or "large" or null

实际使用的 CPU 和内存规格。规格未知或超出公开规格范围时为 null。

  • "small"

  • "medium"

  • "large"

  • SelfHosted object { id, capability_directories, remote_url, 2 more }

应用托管的环境。

  • id: string

环境的公开 ID。

minLength: 0

  • capability_directories: array of string

包含可向智能体提供的能力的目录。

minItems: 0, maxItems: 2000

  • remote_url: string

连接此环境时,将此 URL 原样传给 codex exec-server --remote。

minLength: 0

  • type: "self_hosted" (default: "self_hosted")

对象类型,固定为 self_hosted。

  • "self_hosted"

  • workspace_directory: string

环境内项目目录的绝对路径,默认为 /workspace。

minLength: 0

  • error: string or null

导致会话失败的错误(如有)。

minLength: 0

  • last_active_at: integer

会话最后一次活跃时的 Unix 时间戳,单位为秒。

format: int64

  • metadata: map[string]

附加到会话的自定义字符串键值对。

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

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

  • "agent.session"

  • required_actions: array of McpApprovalRequest { request, request_id, turn_id, type } or ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }

会话继续之前必须完成的操作。

minItems: 0, maxItems: 2000

  • McpApprovalRequest object { request, request_id, turn_id, type }

响应 MCP 工具调用的审批请求。

  • request: object { arguments, message, name, 2 more }

呈现 MCP 审批所需的信息。

  • arguments: unknown

JSON 格式的工具参数。CCA 未提供时为 null。

  • message: string

minLength: 0

  • name: string or null

工具的名称。CCA 未提供时为 null。

minLength: 0

  • server_label: string

minLength: 0

  • type: "mcp_tool_call" (default: "mcp_tool_call")

对象类型,固定为 mcp_tool_call。

  • "mcp_tool_call"

  • request_id: string

响应时需要原样返回的不透明审批 ID。

minLength: 0

  • turn_id: string

请求审批的轮次。

minLength: 0

  • type: "mcp_approval_request" (default: "mcp_approval_request")

对象类型,固定为 mcp_approval_request。

  • "mcp_approval_request"

  • ComputerUseApprovalRequest object { request, request_id, turn_id, type }

响应计算机使用请求。

  • request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }

呈现该请求所需的信息。

  • BrowserAuthentication object { credential_origin, fields, options, 2 more }

等待应用响应的已注册表单。

  • credential_origin: string or null

将在其上填写值的已注册表单或框架的源站。

minLength: 0

  • fields: array of object { id, label, required, type }

要呈现的表单控件。所有提交的值均为敏感数据。

minItems: 0, maxItems: 2000

  • id: string

提交 fields 条目时要用作 field_id 的字段 ID。

minLength: 0

  • label: string

显示在控件旁的标签。

minLength: 0

  • required: boolean

此控件是否需要非空值。

  • type: string

控件的呈现类型,例如电子邮件、密码或文本。

minLength: 0

  • options: array of object { id, field_ids, label }

登录方式。普通表单中为空。

minItems: 0, maxItems: 2000

  • id: string

作为 selected_option 提交的选项 ID。

minLength: 0

  • field_ids: array of string

此方法接受的已注册字段 ID。

minItems: 0, maxItems: 2000

  • label: string

要显示的方式标签。

minLength: 0

  • reason: string or null

智能体需要用户登录的原因。

minLength: 0

  • type: "browser_authentication" (default: "browser_authentication")

对象类型,固定为 browser_authentication。

  • "browser_authentication"

  • BrowserOriginAccess object { origin, reason, type }

等待应用审批决定的浏览器源站。

  • origin: string

浏览器要访问且需要授权的源站。

minLength: 0

  • reason: string or null

浏览器对本请求的说明。无法取得时为 null。

minLength: 0

  • type: "browser_origin_access" (default: "browser_origin_access")

对象类型,固定为 browser_origin_access。

  • "browser_origin_access"

  • request_id: string

响应时需要原样返回的已注册请求 ID。

minLength: 0

  • turn_id: string

请求审批的轮次。

minLength: 0

  • type: "computer_use_approval_request" (default: "computer_use_approval_request")

对象类型,固定为 computer_use_approval_request。

  • "computer_use_approval_request"

  • FunctionCall object { arguments, call_id, name, 2 more }

运行函数工具并提交其结果。

  • arguments: unknown

模型提供的参数。

  • call_id: string

提交函数结果时应包含的 ID。

minLength: 0

  • name: string

函数的名称。

minLength: 0

  • turn_id: string

请求函数调用的轮次 ID。

minLength: 0

  • type: "function_call" (default: "function_call")

对象类型,固定为 function_call。

  • "function_call"

  • EnvironmentConnection object { environment_id, type }

重新连接会话环境。

  • environment_id: string

要重新连接的环境 ID。

minLength: 0

  • type: "environment_connection" (default: "environment_connection")

对象类型,固定为 environment_connection。

  • "environment_connection"

  • status: "idle" or "in_progress" or "requires_action" or "failed"

会话当前的状态。

  • "idle"

会话没有正在进行的轮次,可以接收输入。托管环境可能仍在配置中。

  • "in_progress"

会话正在处理一轮交互。

  • "requires_action"

会话正在等待一个或多个必需操作。

  • "failed"

会话已失败。

  • 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

  • vault_ids: array of string

本会话可访问的凭证库 ID。

minItems: 0, maxItems: 2000

  • prompt_cache_options: optional object { ttl } or null

此会话各轮次采用的默认提示词缓存时长(如已配置)。

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

  • "30m"

  • "12h"

  • review: optional "none" or "auto_review"

应用于本会话中适用操作的审查方式。审查模式为 none 且自动审查未启用时,响应省略此字段。字段省略表示 none。

  • "none"

  • "auto_review"

  • type: "agent.session.idle" (default: "agent.session.idle")

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

  • "agent.session.idle"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.idle",
  "event_id": "event_id",
  "session": {
    "prompt_cache_options": {
      "ttl": "30m"
    },
    "review": "none",
    "metadata": {
      "foo": "string"
    },
    "id": "id",
    "object": "agent.session",
    "created_at": 0,
    "last_active_at": 0,
    "status": "idle",
    "required_actions": [
      {
        "type": "mcp_approval_request",
        "turn_id": "turn_id",
        "request_id": "request_id",
        "request": {
          "type": "mcp_tool_call",
          "server_label": "server_label",
          "name": "name",
          "arguments": {},
          "message": "message"
        }
      }
    ],
    "error": "error",
    "agent": {
      "id": "id",
      "name": "name",
      "model": "model",
      "reasoning": {
        "effort": "none",
        "summary": "concise"
      },
      "text": {
        "format": {
          "type": "text"
        },
        "verbosity": "low"
      },
      "service_tier": "auto",
      "instructions": "instructions",
      "tools": [
        {
          "type": "function",
          "name": "name",
          "description": "description",
          "parameters": {
            "foo": "bar"
          },
          "defer_loading": true,
          "async": true
        }
      ],
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 1
      },
      "compaction": {
        "async": true
      },
      "experimental": {
        "time_awareness": true
      }
    },
    "environment": {
      "type": "none"
    },
    "vault_ids": [
      "string"
    ],
    "usage": {
      "input_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.in_progress

会话开始处理一轮交互时发出。

结构定义

结构名称为 SessionEventAgentSessionInProgress。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session: AgentSession

已开始处理的会话。

  • id: string

会话 ID。

minLength: 0

  • agent: object { id, instructions, model, 8 more }

在会话内运行的智能体。

  • id: string

智能体的 ID。

minLength: 0

  • instructions: string or null

附加到智能体默认基础指令之后的自定义指令。

minLength: 0

  • model: string

智能体使用的模型。

minLength: 0

  • multi_agent: MultiAgentConfig

创建和协调子智能体的配置。

  • enabled: boolean

是否启用子智能体工具。默认关闭。

  • max_concurrent_subagents: integer or null

可同时运行的子智能体数上限。禁用时为 null,启用时默认为 6。

format: int64, minimum: 1, maximum: 4294967295

  • name: string or null

创建会话时可复用智能体的名称。没有保存名称时为 null。之后修改智能体名称不会改变此值。

minLength: 0

  • reasoning: AgentReasoning

智能体的推理配置。

  • effort: "none" or "minimal" or "low" or 4 more or null

请求的推理强度。由模型选择推理强度时为 null。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • summary: "concise" or "detailed" or "auto" or null

请求的推理摘要格式。禁用摘要时为 null。

  • "concise"

模型支持时,返回简明推理摘要。

  • "detailed"

模型支持时,返回详细推理摘要。

  • "auto"

自动选择模型支持的最详细摘要。

  • service_tier: "auto" or "default" or "flex" or 3 more

模型请求实际采用的服务层级策略。默认为 auto。

  • "auto"

  • "default"

  • "flex"

  • "priority"

  • "fast"

  • "ultrafast"

  • text: AgentText

智能体生成文本的配置。

  • format: TextFormat

当前生效的输出格式,默认为普通文本。

  • Text object { type }

生成普通文本,无结构化输出限制。

  • type: "text" (default: "text")

对象类型,恒为 text。

  • "text"

  • JSONSchema object { schema, type }

将生成的文本限制为符合指定 JSON Schema。

  • schema: map[unknown]

生成的文本必须符合的 JSON Schema。

  • type: "json_schema" (default: "json_schema")

对象类型,恒为 json_schema。

  • "json_schema"

  • verbosity: "low" or "medium" or "high"

智能体生成文本的量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • tools: array of AgentTool

智能体可用的工具。

minItems: 0, maxItems: 2000

  • Function object { defer_loading, description, name, 3 more }

应用定义的函数。

  • defer_loading: boolean

函数是否延迟加载并通过工具搜索发现。

  • description: string

说明函数的用途。

minLength: 0

  • name: string

函数名称。

minLength: 0

  • parameters: map[unknown]

描述函数参数的 JSON Schema 对象。

  • type: "function" (default: "function")

对象类型,恒为 function。

  • "function"

  • async: optional boolean

智能体是否无需等待函数结果即可继续。

  • ProgrammaticToolCalling object { enabled, type }

允许模型生成的代码调用工具。

  • enabled: boolean

是否允许从模型生成的代码调用工具。

  • type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

对象类型,恒为 programmatic_tool_calling。

  • "programmatic_tool_calling"

  • Mcp object { allowed_tools, connection_origin, credential_id, 5 more }

远程 MCP 服务器提供的工具。

  • allowed_tools: array of string or null

智能体可调用的 MCP 工具。

minItems: 0, maxItems: 2000

  • connection_origin: "service" or "environment"

出站 MCP HTTP 连接的来源。

  • "service"

  • "environment"

  • credential_id: string or null

为此 MCP 服务器选用的已附加凭证库凭证(如有)。只有一条已附加凭证与服务器 URL 匹配时,可以省略。

minLength: 0

  • request_metadata: map[unknown]

随请求发送给此 MCP 服务器的元数据。

  • required: boolean

是否必须在第一轮前初始化此 MCP 服务器。

  • server_label: string

用于在工具调用中标识 MCP 服务器的标签。

minLength: 0

  • transport: McpTransport

用于连接 MCP 服务器的传输方式。

  • HTTP object { server_url, type }

通过 HTTP 连接到 MCP 服务器。

  • server_url: string

MCP 服务器的 URL。

minLength: 0

  • type: "http" (default: "http")

对象类型,恒为 http。

  • "http"

  • Stdio object { args, command, cwd, 2 more }

以本地进程方式启动 MCP 服务器。

  • args: array of string

传递给 MCP 服务器启动命令的参数。

minItems: 0, maxItems: 2000

  • command: string

用于启动 MCP 服务器的命令。

minLength: 0

  • cwd: string

用于启动 MCP 服务器的工作目录。

minLength: 0

  • env_vars: array of string

从执行环境继承的环境变量名称。

minItems: 0, maxItems: 2000

  • type: "stdio" (default: "stdio")

对象类型,恒为 stdio。

  • "stdio"

  • type: "mcp" (default: "mcp")

对象类型,恒为 mcp。

  • "mcp"

  • WebSearch object { allowed_domains, context_size, location, 2 more }

网页搜索。

  • allowed_domains: array of string or null

允许搜索的域名。搜索范围不受限制时为 null。

minItems: 0, maxItems: 2000

  • context_size: "low" or "medium" or "high"

向模型提供的搜索上下文量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • location: object { city, country, region, timezone } or null

用于按地理位置调整搜索结果的近似位置(如果提供)。

  • city: string or null

城市名称。

minLength: 0

  • country: string or null

两个字母的 ISO 国家或地区代码,例如 US。

minLength: 0

  • region: string or null

地区或州的名称。

minLength: 0

  • timezone: string or null

IANA 时区,例如 America/Los_Angeles。

minLength: 0

  • mode: "disabled" or "cached" or "live"

网页搜索结果的来源。

  • "disabled"

  • "cached"

  • "live"

  • type: "web_search" (default: "web_search")

对象类型,恒为 web_search。

  • "web_search"

  • ComputerUse object { include_screenshots, type }

在 OpenAI 托管会话中使用浏览器。

  • include_screenshots: boolean

计算机工具的输出是否包含屏幕截图。

  • type: "computer_use" (default: "computer_use")

对象类型,恒为 computer_use。

  • "computer_use"

  • Automations object { type }

允许智能体安排自身的定时唤醒。

  • type: "automations" (default: "automations")

对象类型,恒为 automations。

  • "automations"

  • compaction: optional object { async }

当前生效的上下文压缩配置。

  • async: boolean

是否在后台压缩上下文。默认为 false。

  • experimental: optional object { time_awareness }

当前生效的实验性设置。

  • time_awareness: boolean

模型是否会定期收到当前时间提醒。

  • created_at: integer

会话创建时的 Unix 时间戳,单位为秒。

format: int64

  • environment: Environment

会话的执行环境。

  • None object { type }

会话与 CCA 通信,无需选择或配置执行环境。

  • type: "none" (default: "none")

对象类型,固定为 none。

  • "none"

  • OpenAIHosted object { id, capability_directories, desktop, 7 more }

OpenAI 托管的环境。

  • id: string

环境的公开 ID。

minLength: 0

  • capability_directories: array of string

包含可向智能体提供的能力的目录。

minItems: 0, maxItems: 2000

  • desktop: object { enabled }

当前生效的桌面配置。

  • enabled: boolean

环境是否配置桌面及浏览器代理。

  • files: array of HostedEnvironmentFile

环境中的可用文件。响应省略文件内容。

minItems: 0, maxItems: 50

  • HostedEnvironmentFileID object { id, file_id, path, 2 more }

从 OpenAI Files API 复制的文件。

  • id: string

执行环境中会话范围内的文件 ID。

minLength: 0

  • file_id: string

已上传文件的 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "file_id" (default: "file_id")

对象类型,固定为 file_id。

  • "file_id"

  • Inline object { id, path, size_bytes, type }

创建会话时以内联方式提供的文件。

  • id: string

执行环境中会话范围内的文件 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • network: object { access, allowed_domains }

当前生效的环境网络访问策略。

  • access: "enabled" or "disabled" or "restricted"

环境的网络访问模式。

  • "enabled"

允许不受限制的网络访问。

  • "disabled"

关闭网络访问。

  • "restricted"

应用配置的域名访问限制。

  • allowed_domains: array of string

网络访问受限时,环境可以访问的域名。

minItems: 0, maxItems: 2000

  • packages: object { npm, python, system }

在环境中安装的软件包。

  • npm: array of string

在环境中全局安装的 npm 软件包。

minItems: 0, maxItems: 16384

  • python: array of string

已安装到环境中的 Python 软件包。

minItems: 0, maxItems: 16384

  • system: array of string

已安装到环境中的系统软件包。

minItems: 0, maxItems: 16384

  • plugins: array of HostedPlugin

在环境中安装的插件。响应省略其归档内容。

minItems: 0, maxItems: 2000

  • description: string

已安装插件的描述。

minLength: 0

  • name: string

已安装插件的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • skills: array of HostedSkill

在环境中安装的技能。响应省略其归档内容。

minItems: 0, maxItems: 2000

  • HostedSkillReference object { description, name, skill_id, 2 more }

从 Skills API 安装的技能。

  • description: string

已安装技能的描述。

minLength: 0

  • name: string

已安装技能的名称。

minLength: 0

  • skill_id: string

引用的技能 ID。

minLength: 0

  • type: "skill_reference" (default: "skill_reference")

对象类型,固定为 skill_reference。

  • "skill_reference"

  • version: string

此会话实际安装的技能版本。

minLength: 0

  • Inline object { description, name, type }

从内联 ZIP 归档安装的技能。

  • description: string

已安装技能的描述。

minLength: 0

  • name: string

已安装技能的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • type: "openai_hosted" (default: "openai_hosted")

对象类型,固定为 openai_hosted。

  • "openai_hosted"

  • container_size: optional "small" or "medium" or "large" or null

实际使用的 CPU 和内存规格。规格未知或超出公开规格范围时为 null。

  • "small"

  • "medium"

  • "large"

  • SelfHosted object { id, capability_directories, remote_url, 2 more }

应用托管的环境。

  • id: string

环境的公开 ID。

minLength: 0

  • capability_directories: array of string

包含可向智能体提供的能力的目录。

minItems: 0, maxItems: 2000

  • remote_url: string

连接此环境时,将此 URL 原样传给 codex exec-server --remote。

minLength: 0

  • type: "self_hosted" (default: "self_hosted")

对象类型,固定为 self_hosted。

  • "self_hosted"

  • workspace_directory: string

环境内项目目录的绝对路径,默认为 /workspace。

minLength: 0

  • error: string or null

导致会话失败的错误(如有)。

minLength: 0

  • last_active_at: integer

会话最后一次活跃时的 Unix 时间戳,单位为秒。

format: int64

  • metadata: map[string]

附加到会话的自定义字符串键值对。

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

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

  • "agent.session"

  • required_actions: array of McpApprovalRequest { request, request_id, turn_id, type } or ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }

会话继续之前必须完成的操作。

minItems: 0, maxItems: 2000

  • McpApprovalRequest object { request, request_id, turn_id, type }

响应 MCP 工具调用的审批请求。

  • request: object { arguments, message, name, 2 more }

呈现 MCP 审批所需的信息。

  • arguments: unknown

JSON 格式的工具参数。CCA 未提供时为 null。

  • message: string

minLength: 0

  • name: string or null

工具的名称。CCA 未提供时为 null。

minLength: 0

  • server_label: string

minLength: 0

  • type: "mcp_tool_call" (default: "mcp_tool_call")

对象类型,固定为 mcp_tool_call。

  • "mcp_tool_call"

  • request_id: string

响应时需要原样返回的不透明审批 ID。

minLength: 0

  • turn_id: string

请求审批的轮次。

minLength: 0

  • type: "mcp_approval_request" (default: "mcp_approval_request")

对象类型,固定为 mcp_approval_request。

  • "mcp_approval_request"

  • ComputerUseApprovalRequest object { request, request_id, turn_id, type }

响应计算机使用请求。

  • request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }

呈现该请求所需的信息。

  • BrowserAuthentication object { credential_origin, fields, options, 2 more }

等待应用响应的已注册表单。

  • credential_origin: string or null

将在其上填写值的已注册表单或框架的源站。

minLength: 0

  • fields: array of object { id, label, required, type }

要呈现的表单控件。所有提交的值均为敏感数据。

minItems: 0, maxItems: 2000

  • id: string

提交 fields 条目时要用作 field_id 的字段 ID。

minLength: 0

  • label: string

显示在控件旁的标签。

minLength: 0

  • required: boolean

此控件是否需要非空值。

  • type: string

控件的呈现类型,例如电子邮件、密码或文本。

minLength: 0

  • options: array of object { id, field_ids, label }

登录方式。普通表单中为空。

minItems: 0, maxItems: 2000

  • id: string

作为 selected_option 提交的选项 ID。

minLength: 0

  • field_ids: array of string

此方法接受的已注册字段 ID。

minItems: 0, maxItems: 2000

  • label: string

要显示的方式标签。

minLength: 0

  • reason: string or null

智能体需要用户登录的原因。

minLength: 0

  • type: "browser_authentication" (default: "browser_authentication")

对象类型,固定为 browser_authentication。

  • "browser_authentication"

  • BrowserOriginAccess object { origin, reason, type }

等待应用审批决定的浏览器源站。

  • origin: string

浏览器要访问且需要授权的源站。

minLength: 0

  • reason: string or null

浏览器对本请求的说明。无法取得时为 null。

minLength: 0

  • type: "browser_origin_access" (default: "browser_origin_access")

对象类型,固定为 browser_origin_access。

  • "browser_origin_access"

  • request_id: string

响应时需要原样返回的已注册请求 ID。

minLength: 0

  • turn_id: string

请求审批的轮次。

minLength: 0

  • type: "computer_use_approval_request" (default: "computer_use_approval_request")

对象类型,固定为 computer_use_approval_request。

  • "computer_use_approval_request"

  • FunctionCall object { arguments, call_id, name, 2 more }

运行函数工具并提交其结果。

  • arguments: unknown

模型提供的参数。

  • call_id: string

提交函数结果时应包含的 ID。

minLength: 0

  • name: string

函数的名称。

minLength: 0

  • turn_id: string

请求函数调用的轮次 ID。

minLength: 0

  • type: "function_call" (default: "function_call")

对象类型,固定为 function_call。

  • "function_call"

  • EnvironmentConnection object { environment_id, type }

重新连接会话环境。

  • environment_id: string

要重新连接的环境 ID。

minLength: 0

  • type: "environment_connection" (default: "environment_connection")

对象类型,固定为 environment_connection。

  • "environment_connection"

  • status: "idle" or "in_progress" or "requires_action" or "failed"

会话当前的状态。

  • "idle"

会话没有正在进行的轮次,可以接收输入。托管环境可能仍在配置中。

  • "in_progress"

会话正在处理一轮交互。

  • "requires_action"

会话正在等待一个或多个必需操作。

  • "failed"

会话已失败。

  • 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

  • vault_ids: array of string

本会话可访问的凭证库 ID。

minItems: 0, maxItems: 2000

  • prompt_cache_options: optional object { ttl } or null

此会话各轮次采用的默认提示词缓存时长(如已配置)。

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

  • "30m"

  • "12h"

  • review: optional "none" or "auto_review"

应用于本会话中适用操作的审查方式。审查模式为 none 且自动审查未启用时,响应省略此字段。字段省略表示 none。

  • "none"

  • "auto_review"

  • type: "agent.session.in_progress" (default: "agent.session.in_progress")

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

  • "agent.session.in_progress"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.in_progress",
  "event_id": "event_id",
  "session": {
    "prompt_cache_options": {
      "ttl": "30m"
    },
    "review": "none",
    "metadata": {
      "foo": "string"
    },
    "id": "id",
    "object": "agent.session",
    "created_at": 0,
    "last_active_at": 0,
    "status": "idle",
    "required_actions": [
      {
        "type": "mcp_approval_request",
        "turn_id": "turn_id",
        "request_id": "request_id",
        "request": {
          "type": "mcp_tool_call",
          "server_label": "server_label",
          "name": "name",
          "arguments": {},
          "message": "message"
        }
      }
    ],
    "error": "error",
    "agent": {
      "id": "id",
      "name": "name",
      "model": "model",
      "reasoning": {
        "effort": "none",
        "summary": "concise"
      },
      "text": {
        "format": {
          "type": "text"
        },
        "verbosity": "low"
      },
      "service_tier": "auto",
      "instructions": "instructions",
      "tools": [
        {
          "type": "function",
          "name": "name",
          "description": "description",
          "parameters": {
            "foo": "bar"
          },
          "defer_loading": true,
          "async": true
        }
      ],
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 1
      },
      "compaction": {
        "async": true
      },
      "experimental": {
        "time_awareness": true
      }
    },
    "environment": {
      "type": "none"
    },
    "vault_ids": [
      "string"
    ],
    "usage": {
      "input_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.requires_action

会话等待一个或多个必需操作时发出。

结构定义

结构名称为 SessionEventAgentSessionRequiresAction。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session: AgentSession

会话及其当前必需操作。

  • id: string

会话 ID。

minLength: 0

  • agent: object { id, instructions, model, 8 more }

在会话内运行的智能体。

  • id: string

智能体的 ID。

minLength: 0

  • instructions: string or null

附加到智能体默认基础指令之后的自定义指令。

minLength: 0

  • model: string

智能体使用的模型。

minLength: 0

  • multi_agent: MultiAgentConfig

创建和协调子智能体的配置。

  • enabled: boolean

是否启用子智能体工具。默认关闭。

  • max_concurrent_subagents: integer or null

可同时运行的子智能体数上限。禁用时为 null,启用时默认为 6。

format: int64, minimum: 1, maximum: 4294967295

  • name: string or null

创建会话时可复用智能体的名称。没有保存名称时为 null。之后修改智能体名称不会改变此值。

minLength: 0

  • reasoning: AgentReasoning

智能体的推理配置。

  • effort: "none" or "minimal" or "low" or 4 more or null

请求的推理强度。由模型选择推理强度时为 null。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • summary: "concise" or "detailed" or "auto" or null

请求的推理摘要格式。禁用摘要时为 null。

  • "concise"

模型支持时,返回简明推理摘要。

  • "detailed"

模型支持时,返回详细推理摘要。

  • "auto"

自动选择模型支持的最详细摘要。

  • service_tier: "auto" or "default" or "flex" or 3 more

模型请求实际采用的服务层级策略。默认为 auto。

  • "auto"

  • "default"

  • "flex"

  • "priority"

  • "fast"

  • "ultrafast"

  • text: AgentText

智能体生成文本的配置。

  • format: TextFormat

当前生效的输出格式,默认为普通文本。

  • Text object { type }

生成普通文本,无结构化输出限制。

  • type: "text" (default: "text")

对象类型,恒为 text。

  • "text"

  • JSONSchema object { schema, type }

将生成的文本限制为符合指定 JSON Schema。

  • schema: map[unknown]

生成的文本必须符合的 JSON Schema。

  • type: "json_schema" (default: "json_schema")

对象类型,恒为 json_schema。

  • "json_schema"

  • verbosity: "low" or "medium" or "high"

智能体生成文本的量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • tools: array of AgentTool

智能体可用的工具。

minItems: 0, maxItems: 2000

  • Function object { defer_loading, description, name, 3 more }

应用定义的函数。

  • defer_loading: boolean

函数是否延迟加载并通过工具搜索发现。

  • description: string

说明函数的用途。

minLength: 0

  • name: string

函数名称。

minLength: 0

  • parameters: map[unknown]

描述函数参数的 JSON Schema 对象。

  • type: "function" (default: "function")

对象类型,恒为 function。

  • "function"

  • async: optional boolean

智能体是否无需等待函数结果即可继续。

  • ProgrammaticToolCalling object { enabled, type }

允许模型生成的代码调用工具。

  • enabled: boolean

是否允许从模型生成的代码调用工具。

  • type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

对象类型,恒为 programmatic_tool_calling。

  • "programmatic_tool_calling"

  • Mcp object { allowed_tools, connection_origin, credential_id, 5 more }

远程 MCP 服务器提供的工具。

  • allowed_tools: array of string or null

智能体可调用的 MCP 工具。

minItems: 0, maxItems: 2000

  • connection_origin: "service" or "environment"

出站 MCP HTTP 连接的来源。

  • "service"

  • "environment"

  • credential_id: string or null

为此 MCP 服务器选用的已附加凭证库凭证(如有)。只有一条已附加凭证与服务器 URL 匹配时,可以省略。

minLength: 0

  • request_metadata: map[unknown]

随请求发送给此 MCP 服务器的元数据。

  • required: boolean

是否必须在第一轮前初始化此 MCP 服务器。

  • server_label: string

用于在工具调用中标识 MCP 服务器的标签。

minLength: 0

  • transport: McpTransport

用于连接 MCP 服务器的传输方式。

  • HTTP object { server_url, type }

通过 HTTP 连接到 MCP 服务器。

  • server_url: string

MCP 服务器的 URL。

minLength: 0

  • type: "http" (default: "http")

对象类型,恒为 http。

  • "http"

  • Stdio object { args, command, cwd, 2 more }

以本地进程方式启动 MCP 服务器。

  • args: array of string

传递给 MCP 服务器启动命令的参数。

minItems: 0, maxItems: 2000

  • command: string

用于启动 MCP 服务器的命令。

minLength: 0

  • cwd: string

用于启动 MCP 服务器的工作目录。

minLength: 0

  • env_vars: array of string

从执行环境继承的环境变量名称。

minItems: 0, maxItems: 2000

  • type: "stdio" (default: "stdio")

对象类型,恒为 stdio。

  • "stdio"

  • type: "mcp" (default: "mcp")

对象类型,恒为 mcp。

  • "mcp"

  • WebSearch object { allowed_domains, context_size, location, 2 more }

网页搜索。

  • allowed_domains: array of string or null

允许搜索的域名。搜索范围不受限制时为 null。

minItems: 0, maxItems: 2000

  • context_size: "low" or "medium" or "high"

向模型提供的搜索上下文量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • location: object { city, country, region, timezone } or null

用于按地理位置调整搜索结果的近似位置(如果提供)。

  • city: string or null

城市名称。

minLength: 0

  • country: string or null

两个字母的 ISO 国家或地区代码,例如 US。

minLength: 0

  • region: string or null

地区或州的名称。

minLength: 0

  • timezone: string or null

IANA 时区,例如 America/Los_Angeles。

minLength: 0

  • mode: "disabled" or "cached" or "live"

网页搜索结果的来源。

  • "disabled"

  • "cached"

  • "live"

  • type: "web_search" (default: "web_search")

对象类型,恒为 web_search。

  • "web_search"

  • ComputerUse object { include_screenshots, type }

在 OpenAI 托管会话中使用浏览器。

  • include_screenshots: boolean

计算机工具的输出是否包含屏幕截图。

  • type: "computer_use" (default: "computer_use")

对象类型,恒为 computer_use。

  • "computer_use"

  • Automations object { type }

允许智能体安排自身的定时唤醒。

  • type: "automations" (default: "automations")

对象类型,恒为 automations。

  • "automations"

  • compaction: optional object { async }

当前生效的上下文压缩配置。

  • async: boolean

是否在后台压缩上下文。默认为 false。

  • experimental: optional object { time_awareness }

当前生效的实验性设置。

  • time_awareness: boolean

模型是否会定期收到当前时间提醒。

  • created_at: integer

会话创建时的 Unix 时间戳,单位为秒。

format: int64

  • environment: Environment

会话的执行环境。

  • None object { type }

会话与 CCA 通信,无需选择或配置执行环境。

  • type: "none" (default: "none")

对象类型,固定为 none。

  • "none"

  • OpenAIHosted object { id, capability_directories, desktop, 7 more }

OpenAI 托管的环境。

  • id: string

环境的公开 ID。

minLength: 0

  • capability_directories: array of string

包含可向智能体提供的能力的目录。

minItems: 0, maxItems: 2000

  • desktop: object { enabled }

当前生效的桌面配置。

  • enabled: boolean

环境是否配置桌面及浏览器代理。

  • files: array of HostedEnvironmentFile

环境中的可用文件。响应省略文件内容。

minItems: 0, maxItems: 50

  • HostedEnvironmentFileID object { id, file_id, path, 2 more }

从 OpenAI Files API 复制的文件。

  • id: string

执行环境中会话范围内的文件 ID。

minLength: 0

  • file_id: string

已上传文件的 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "file_id" (default: "file_id")

对象类型,固定为 file_id。

  • "file_id"

  • Inline object { id, path, size_bytes, type }

创建会话时以内联方式提供的文件。

  • id: string

执行环境中会话范围内的文件 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • network: object { access, allowed_domains }

当前生效的环境网络访问策略。

  • access: "enabled" or "disabled" or "restricted"

环境的网络访问模式。

  • "enabled"

允许不受限制的网络访问。

  • "disabled"

关闭网络访问。

  • "restricted"

应用配置的域名访问限制。

  • allowed_domains: array of string

网络访问受限时,环境可以访问的域名。

minItems: 0, maxItems: 2000

  • packages: object { npm, python, system }

在环境中安装的软件包。

  • npm: array of string

在环境中全局安装的 npm 软件包。

minItems: 0, maxItems: 16384

  • python: array of string

已安装到环境中的 Python 软件包。

minItems: 0, maxItems: 16384

  • system: array of string

已安装到环境中的系统软件包。

minItems: 0, maxItems: 16384

  • plugins: array of HostedPlugin

在环境中安装的插件。响应省略其归档内容。

minItems: 0, maxItems: 2000

  • description: string

已安装插件的描述。

minLength: 0

  • name: string

已安装插件的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • skills: array of HostedSkill

在环境中安装的技能。响应省略其归档内容。

minItems: 0, maxItems: 2000

  • HostedSkillReference object { description, name, skill_id, 2 more }

从 Skills API 安装的技能。

  • description: string

已安装技能的描述。

minLength: 0

  • name: string

已安装技能的名称。

minLength: 0

  • skill_id: string

引用的技能 ID。

minLength: 0

  • type: "skill_reference" (default: "skill_reference")

对象类型,固定为 skill_reference。

  • "skill_reference"

  • version: string

此会话实际安装的技能版本。

minLength: 0

  • Inline object { description, name, type }

从内联 ZIP 归档安装的技能。

  • description: string

已安装技能的描述。

minLength: 0

  • name: string

已安装技能的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • type: "openai_hosted" (default: "openai_hosted")

对象类型,固定为 openai_hosted。

  • "openai_hosted"

  • container_size: optional "small" or "medium" or "large" or null

实际使用的 CPU 和内存规格。规格未知或超出公开规格范围时为 null。

  • "small"

  • "medium"

  • "large"

  • SelfHosted object { id, capability_directories, remote_url, 2 more }

应用托管的环境。

  • id: string

环境的公开 ID。

minLength: 0

  • capability_directories: array of string

包含可向智能体提供的能力的目录。

minItems: 0, maxItems: 2000

  • remote_url: string

连接此环境时,将此 URL 原样传给 codex exec-server --remote。

minLength: 0

  • type: "self_hosted" (default: "self_hosted")

对象类型,固定为 self_hosted。

  • "self_hosted"

  • workspace_directory: string

环境内项目目录的绝对路径,默认为 /workspace。

minLength: 0

  • error: string or null

导致会话失败的错误(如有)。

minLength: 0

  • last_active_at: integer

会话最后一次活跃时的 Unix 时间戳,单位为秒。

format: int64

  • metadata: map[string]

附加到会话的自定义字符串键值对。

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

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

  • "agent.session"

  • required_actions: array of McpApprovalRequest { request, request_id, turn_id, type } or ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }

会话继续之前必须完成的操作。

minItems: 0, maxItems: 2000

  • McpApprovalRequest object { request, request_id, turn_id, type }

响应 MCP 工具调用的审批请求。

  • request: object { arguments, message, name, 2 more }

呈现 MCP 审批所需的信息。

  • arguments: unknown

JSON 格式的工具参数。CCA 未提供时为 null。

  • message: string

minLength: 0

  • name: string or null

工具的名称。CCA 未提供时为 null。

minLength: 0

  • server_label: string

minLength: 0

  • type: "mcp_tool_call" (default: "mcp_tool_call")

对象类型,固定为 mcp_tool_call。

  • "mcp_tool_call"

  • request_id: string

响应时需要原样返回的不透明审批 ID。

minLength: 0

  • turn_id: string

请求审批的轮次。

minLength: 0

  • type: "mcp_approval_request" (default: "mcp_approval_request")

对象类型,固定为 mcp_approval_request。

  • "mcp_approval_request"

  • ComputerUseApprovalRequest object { request, request_id, turn_id, type }

响应计算机使用请求。

  • request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }

呈现该请求所需的信息。

  • BrowserAuthentication object { credential_origin, fields, options, 2 more }

等待应用响应的已注册表单。

  • credential_origin: string or null

将在其上填写值的已注册表单或框架的源站。

minLength: 0

  • fields: array of object { id, label, required, type }

要呈现的表单控件。所有提交的值均为敏感数据。

minItems: 0, maxItems: 2000

  • id: string

提交 fields 条目时要用作 field_id 的字段 ID。

minLength: 0

  • label: string

显示在控件旁的标签。

minLength: 0

  • required: boolean

此控件是否需要非空值。

  • type: string

控件的呈现类型,例如电子邮件、密码或文本。

minLength: 0

  • options: array of object { id, field_ids, label }

登录方式。普通表单中为空。

minItems: 0, maxItems: 2000

  • id: string

作为 selected_option 提交的选项 ID。

minLength: 0

  • field_ids: array of string

此方法接受的已注册字段 ID。

minItems: 0, maxItems: 2000

  • label: string

要显示的方式标签。

minLength: 0

  • reason: string or null

智能体需要用户登录的原因。

minLength: 0

  • type: "browser_authentication" (default: "browser_authentication")

对象类型,固定为 browser_authentication。

  • "browser_authentication"

  • BrowserOriginAccess object { origin, reason, type }

等待应用审批决定的浏览器源站。

  • origin: string

浏览器要访问且需要授权的源站。

minLength: 0

  • reason: string or null

浏览器对本请求的说明。无法取得时为 null。

minLength: 0

  • type: "browser_origin_access" (default: "browser_origin_access")

对象类型,固定为 browser_origin_access。

  • "browser_origin_access"

  • request_id: string

响应时需要原样返回的已注册请求 ID。

minLength: 0

  • turn_id: string

请求审批的轮次。

minLength: 0

  • type: "computer_use_approval_request" (default: "computer_use_approval_request")

对象类型,固定为 computer_use_approval_request。

  • "computer_use_approval_request"

  • FunctionCall object { arguments, call_id, name, 2 more }

运行函数工具并提交其结果。

  • arguments: unknown

模型提供的参数。

  • call_id: string

提交函数结果时应包含的 ID。

minLength: 0

  • name: string

函数的名称。

minLength: 0

  • turn_id: string

请求函数调用的轮次 ID。

minLength: 0

  • type: "function_call" (default: "function_call")

对象类型,固定为 function_call。

  • "function_call"

  • EnvironmentConnection object { environment_id, type }

重新连接会话环境。

  • environment_id: string

要重新连接的环境 ID。

minLength: 0

  • type: "environment_connection" (default: "environment_connection")

对象类型,固定为 environment_connection。

  • "environment_connection"

  • status: "idle" or "in_progress" or "requires_action" or "failed"

会话当前的状态。

  • "idle"

会话没有正在进行的轮次,可以接收输入。托管环境可能仍在配置中。

  • "in_progress"

会话正在处理一轮交互。

  • "requires_action"

会话正在等待一个或多个必需操作。

  • "failed"

会话已失败。

  • 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

  • vault_ids: array of string

本会话可访问的凭证库 ID。

minItems: 0, maxItems: 2000

  • prompt_cache_options: optional object { ttl } or null

此会话各轮次采用的默认提示词缓存时长(如已配置)。

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

  • "30m"

  • "12h"

  • review: optional "none" or "auto_review"

应用于本会话中适用操作的审查方式。审查模式为 none 且自动审查未启用时,响应省略此字段。字段省略表示 none。

  • "none"

  • "auto_review"

  • type: "agent.session.requires_action" (default: "agent.session.requires_action")

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

  • "agent.session.requires_action"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.requires_action",
  "event_id": "event_id",
  "session": {
    "prompt_cache_options": {
      "ttl": "30m"
    },
    "review": "none",
    "metadata": {
      "foo": "string"
    },
    "id": "id",
    "object": "agent.session",
    "created_at": 0,
    "last_active_at": 0,
    "status": "idle",
    "required_actions": [
      {
        "type": "mcp_approval_request",
        "turn_id": "turn_id",
        "request_id": "request_id",
        "request": {
          "type": "mcp_tool_call",
          "server_label": "server_label",
          "name": "name",
          "arguments": {},
          "message": "message"
        }
      }
    ],
    "error": "error",
    "agent": {
      "id": "id",
      "name": "name",
      "model": "model",
      "reasoning": {
        "effort": "none",
        "summary": "concise"
      },
      "text": {
        "format": {
          "type": "text"
        },
        "verbosity": "low"
      },
      "service_tier": "auto",
      "instructions": "instructions",
      "tools": [
        {
          "type": "function",
          "name": "name",
          "description": "description",
          "parameters": {
            "foo": "bar"
          },
          "defer_loading": true,
          "async": true
        }
      ],
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 1
      },
      "compaction": {
        "async": true
      },
      "experimental": {
        "time_awareness": true
      }
    },
    "environment": {
      "type": "none"
    },
    "vault_ids": [
      "string"
    ],
    "usage": {
      "input_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.failed

会话失败时发出。

结构定义

结构名称为 SessionEventAgentSessionFailed。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session: AgentSession

已失败的会话。

  • id: string

会话 ID。

minLength: 0

  • agent: object { id, instructions, model, 8 more }

在会话内运行的智能体。

  • id: string

智能体的 ID。

minLength: 0

  • instructions: string or null

附加到智能体默认基础指令之后的自定义指令。

minLength: 0

  • model: string

智能体使用的模型。

minLength: 0

  • multi_agent: MultiAgentConfig

创建和协调子智能体的配置。

  • enabled: boolean

是否启用子智能体工具。默认关闭。

  • max_concurrent_subagents: integer or null

可同时运行的子智能体数上限。禁用时为 null,启用时默认为 6。

format: int64, minimum: 1, maximum: 4294967295

  • name: string or null

创建会话时可复用智能体的名称。没有保存名称时为 null。之后修改智能体名称不会改变此值。

minLength: 0

  • reasoning: AgentReasoning

智能体的推理配置。

  • effort: "none" or "minimal" or "low" or 4 more or null

请求的推理强度。由模型选择推理强度时为 null。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • summary: "concise" or "detailed" or "auto" or null

请求的推理摘要格式。禁用摘要时为 null。

  • "concise"

模型支持时,返回简明推理摘要。

  • "detailed"

模型支持时,返回详细推理摘要。

  • "auto"

自动选择模型支持的最详细摘要。

  • service_tier: "auto" or "default" or "flex" or 3 more

模型请求实际采用的服务层级策略。默认为 auto。

  • "auto"

  • "default"

  • "flex"

  • "priority"

  • "fast"

  • "ultrafast"

  • text: AgentText

智能体生成文本的配置。

  • format: TextFormat

当前生效的输出格式,默认为普通文本。

  • Text object { type }

生成普通文本,无结构化输出限制。

  • type: "text" (default: "text")

对象类型,恒为 text。

  • "text"

  • JSONSchema object { schema, type }

将生成的文本限制为符合指定 JSON Schema。

  • schema: map[unknown]

生成的文本必须符合的 JSON Schema。

  • type: "json_schema" (default: "json_schema")

对象类型,恒为 json_schema。

  • "json_schema"

  • verbosity: "low" or "medium" or "high"

智能体生成文本的量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • tools: array of AgentTool

智能体可用的工具。

minItems: 0, maxItems: 2000

  • Function object { defer_loading, description, name, 3 more }

应用定义的函数。

  • defer_loading: boolean

函数是否延迟加载并通过工具搜索发现。

  • description: string

说明函数的用途。

minLength: 0

  • name: string

函数名称。

minLength: 0

  • parameters: map[unknown]

描述函数参数的 JSON Schema 对象。

  • type: "function" (default: "function")

对象类型,恒为 function。

  • "function"

  • async: optional boolean

智能体是否无需等待函数结果即可继续。

  • ProgrammaticToolCalling object { enabled, type }

允许模型生成的代码调用工具。

  • enabled: boolean

是否允许从模型生成的代码调用工具。

  • type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

对象类型,恒为 programmatic_tool_calling。

  • "programmatic_tool_calling"

  • Mcp object { allowed_tools, connection_origin, credential_id, 5 more }

远程 MCP 服务器提供的工具。

  • allowed_tools: array of string or null

智能体可调用的 MCP 工具。

minItems: 0, maxItems: 2000

  • connection_origin: "service" or "environment"

出站 MCP HTTP 连接的来源。

  • "service"

  • "environment"

  • credential_id: string or null

为此 MCP 服务器选用的已附加凭证库凭证(如有)。只有一条已附加凭证与服务器 URL 匹配时,可以省略。

minLength: 0

  • request_metadata: map[unknown]

随请求发送给此 MCP 服务器的元数据。

  • required: boolean

是否必须在第一轮前初始化此 MCP 服务器。

  • server_label: string

用于在工具调用中标识 MCP 服务器的标签。

minLength: 0

  • transport: McpTransport

用于连接 MCP 服务器的传输方式。

  • HTTP object { server_url, type }

通过 HTTP 连接到 MCP 服务器。

  • server_url: string

MCP 服务器的 URL。

minLength: 0

  • type: "http" (default: "http")

对象类型,恒为 http。

  • "http"

  • Stdio object { args, command, cwd, 2 more }

以本地进程方式启动 MCP 服务器。

  • args: array of string

传递给 MCP 服务器启动命令的参数。

minItems: 0, maxItems: 2000

  • command: string

用于启动 MCP 服务器的命令。

minLength: 0

  • cwd: string

用于启动 MCP 服务器的工作目录。

minLength: 0

  • env_vars: array of string

从执行环境继承的环境变量名称。

minItems: 0, maxItems: 2000

  • type: "stdio" (default: "stdio")

对象类型,恒为 stdio。

  • "stdio"

  • type: "mcp" (default: "mcp")

对象类型,恒为 mcp。

  • "mcp"

  • WebSearch object { allowed_domains, context_size, location, 2 more }

网页搜索。

  • allowed_domains: array of string or null

允许搜索的域名。搜索范围不受限制时为 null。

minItems: 0, maxItems: 2000

  • context_size: "low" or "medium" or "high"

向模型提供的搜索上下文量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • location: object { city, country, region, timezone } or null

用于按地理位置调整搜索结果的近似位置(如果提供)。

  • city: string or null

城市名称。

minLength: 0

  • country: string or null

两个字母的 ISO 国家或地区代码,例如 US。

minLength: 0

  • region: string or null

地区或州的名称。

minLength: 0

  • timezone: string or null

IANA 时区,例如 America/Los_Angeles。

minLength: 0

  • mode: "disabled" or "cached" or "live"

网页搜索结果的来源。

  • "disabled"

  • "cached"

  • "live"

  • type: "web_search" (default: "web_search")

对象类型,恒为 web_search。

  • "web_search"

  • ComputerUse object { include_screenshots, type }

在 OpenAI 托管会话中使用浏览器。

  • include_screenshots: boolean

计算机工具的输出是否包含屏幕截图。

  • type: "computer_use" (default: "computer_use")

对象类型,恒为 computer_use。

  • "computer_use"

  • Automations object { type }

允许智能体安排自身的定时唤醒。

  • type: "automations" (default: "automations")

对象类型,恒为 automations。

  • "automations"

  • compaction: optional object { async }

当前生效的上下文压缩配置。

  • async: boolean

是否在后台压缩上下文。默认为 false。

  • experimental: optional object { time_awareness }

当前生效的实验性设置。

  • time_awareness: boolean

模型是否会定期收到当前时间提醒。

  • created_at: integer

会话创建时的 Unix 时间戳,单位为秒。

format: int64

  • environment: Environment

会话的执行环境。

  • None object { type }

会话与 CCA 通信,无需选择或配置执行环境。

  • type: "none" (default: "none")

对象类型,固定为 none。

  • "none"

  • OpenAIHosted object { id, capability_directories, desktop, 7 more }

OpenAI 托管的环境。

  • id: string

环境的公开 ID。

minLength: 0

  • capability_directories: array of string

包含可向智能体提供的能力的目录。

minItems: 0, maxItems: 2000

  • desktop: object { enabled }

当前生效的桌面配置。

  • enabled: boolean

环境是否配置桌面及浏览器代理。

  • files: array of HostedEnvironmentFile

环境中的可用文件。响应省略文件内容。

minItems: 0, maxItems: 50

  • HostedEnvironmentFileID object { id, file_id, path, 2 more }

从 OpenAI Files API 复制的文件。

  • id: string

执行环境中会话范围内的文件 ID。

minLength: 0

  • file_id: string

已上传文件的 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "file_id" (default: "file_id")

对象类型,固定为 file_id。

  • "file_id"

  • Inline object { id, path, size_bytes, type }

创建会话时以内联方式提供的文件。

  • id: string

执行环境中会话范围内的文件 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • network: object { access, allowed_domains }

当前生效的环境网络访问策略。

  • access: "enabled" or "disabled" or "restricted"

环境的网络访问模式。

  • "enabled"

允许不受限制的网络访问。

  • "disabled"

关闭网络访问。

  • "restricted"

应用配置的域名访问限制。

  • allowed_domains: array of string

网络访问受限时,环境可以访问的域名。

minItems: 0, maxItems: 2000

  • packages: object { npm, python, system }

在环境中安装的软件包。

  • npm: array of string

在环境中全局安装的 npm 软件包。

minItems: 0, maxItems: 16384

  • python: array of string

已安装到环境中的 Python 软件包。

minItems: 0, maxItems: 16384

  • system: array of string

已安装到环境中的系统软件包。

minItems: 0, maxItems: 16384

  • plugins: array of HostedPlugin

在环境中安装的插件。响应省略其归档内容。

minItems: 0, maxItems: 2000

  • description: string

已安装插件的描述。

minLength: 0

  • name: string

已安装插件的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • skills: array of HostedSkill

在环境中安装的技能。响应省略其归档内容。

minItems: 0, maxItems: 2000

  • HostedSkillReference object { description, name, skill_id, 2 more }

从 Skills API 安装的技能。

  • description: string

已安装技能的描述。

minLength: 0

  • name: string

已安装技能的名称。

minLength: 0

  • skill_id: string

引用的技能 ID。

minLength: 0

  • type: "skill_reference" (default: "skill_reference")

对象类型,固定为 skill_reference。

  • "skill_reference"

  • version: string

此会话实际安装的技能版本。

minLength: 0

  • Inline object { description, name, type }

从内联 ZIP 归档安装的技能。

  • description: string

已安装技能的描述。

minLength: 0

  • name: string

已安装技能的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • type: "openai_hosted" (default: "openai_hosted")

对象类型,固定为 openai_hosted。

  • "openai_hosted"

  • container_size: optional "small" or "medium" or "large" or null

实际使用的 CPU 和内存规格。规格未知或超出公开规格范围时为 null。

  • "small"

  • "medium"

  • "large"

  • SelfHosted object { id, capability_directories, remote_url, 2 more }

应用托管的环境。

  • id: string

环境的公开 ID。

minLength: 0

  • capability_directories: array of string

包含可向智能体提供的能力的目录。

minItems: 0, maxItems: 2000

  • remote_url: string

连接此环境时,将此 URL 原样传给 codex exec-server --remote。

minLength: 0

  • type: "self_hosted" (default: "self_hosted")

对象类型,固定为 self_hosted。

  • "self_hosted"

  • workspace_directory: string

环境内项目目录的绝对路径,默认为 /workspace。

minLength: 0

  • error: string or null

导致会话失败的错误(如有)。

minLength: 0

  • last_active_at: integer

会话最后一次活跃时的 Unix 时间戳,单位为秒。

format: int64

  • metadata: map[string]

附加到会话的自定义字符串键值对。

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

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

  • "agent.session"

  • required_actions: array of McpApprovalRequest { request, request_id, turn_id, type } or ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }

会话继续之前必须完成的操作。

minItems: 0, maxItems: 2000

  • McpApprovalRequest object { request, request_id, turn_id, type }

响应 MCP 工具调用的审批请求。

  • request: object { arguments, message, name, 2 more }

呈现 MCP 审批所需的信息。

  • arguments: unknown

JSON 格式的工具参数。CCA 未提供时为 null。

  • message: string

minLength: 0

  • name: string or null

工具的名称。CCA 未提供时为 null。

minLength: 0

  • server_label: string

minLength: 0

  • type: "mcp_tool_call" (default: "mcp_tool_call")

对象类型,固定为 mcp_tool_call。

  • "mcp_tool_call"

  • request_id: string

响应时需要原样返回的不透明审批 ID。

minLength: 0

  • turn_id: string

请求审批的轮次。

minLength: 0

  • type: "mcp_approval_request" (default: "mcp_approval_request")

对象类型,固定为 mcp_approval_request。

  • "mcp_approval_request"

  • ComputerUseApprovalRequest object { request, request_id, turn_id, type }

响应计算机使用请求。

  • request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }

呈现该请求所需的信息。

  • BrowserAuthentication object { credential_origin, fields, options, 2 more }

等待应用响应的已注册表单。

  • credential_origin: string or null

将在其上填写值的已注册表单或框架的源站。

minLength: 0

  • fields: array of object { id, label, required, type }

要呈现的表单控件。所有提交的值均为敏感数据。

minItems: 0, maxItems: 2000

  • id: string

提交 fields 条目时要用作 field_id 的字段 ID。

minLength: 0

  • label: string

显示在控件旁的标签。

minLength: 0

  • required: boolean

此控件是否需要非空值。

  • type: string

控件的呈现类型,例如电子邮件、密码或文本。

minLength: 0

  • options: array of object { id, field_ids, label }

登录方式。普通表单中为空。

minItems: 0, maxItems: 2000

  • id: string

作为 selected_option 提交的选项 ID。

minLength: 0

  • field_ids: array of string

此方法接受的已注册字段 ID。

minItems: 0, maxItems: 2000

  • label: string

要显示的方式标签。

minLength: 0

  • reason: string or null

智能体需要用户登录的原因。

minLength: 0

  • type: "browser_authentication" (default: "browser_authentication")

对象类型,固定为 browser_authentication。

  • "browser_authentication"

  • BrowserOriginAccess object { origin, reason, type }

等待应用审批决定的浏览器源站。

  • origin: string

浏览器要访问且需要授权的源站。

minLength: 0

  • reason: string or null

浏览器对本请求的说明。无法取得时为 null。

minLength: 0

  • type: "browser_origin_access" (default: "browser_origin_access")

对象类型,固定为 browser_origin_access。

  • "browser_origin_access"

  • request_id: string

响应时需要原样返回的已注册请求 ID。

minLength: 0

  • turn_id: string

请求审批的轮次。

minLength: 0

  • type: "computer_use_approval_request" (default: "computer_use_approval_request")

对象类型,固定为 computer_use_approval_request。

  • "computer_use_approval_request"

  • FunctionCall object { arguments, call_id, name, 2 more }

运行函数工具并提交其结果。

  • arguments: unknown

模型提供的参数。

  • call_id: string

提交函数结果时应包含的 ID。

minLength: 0

  • name: string

函数的名称。

minLength: 0

  • turn_id: string

请求函数调用的轮次 ID。

minLength: 0

  • type: "function_call" (default: "function_call")

对象类型,固定为 function_call。

  • "function_call"

  • EnvironmentConnection object { environment_id, type }

重新连接会话环境。

  • environment_id: string

要重新连接的环境 ID。

minLength: 0

  • type: "environment_connection" (default: "environment_connection")

对象类型,固定为 environment_connection。

  • "environment_connection"

  • status: "idle" or "in_progress" or "requires_action" or "failed"

会话当前的状态。

  • "idle"

会话没有正在进行的轮次,可以接收输入。托管环境可能仍在配置中。

  • "in_progress"

会话正在处理一轮交互。

  • "requires_action"

会话正在等待一个或多个必需操作。

  • "failed"

会话已失败。

  • 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

  • vault_ids: array of string

本会话可访问的凭证库 ID。

minItems: 0, maxItems: 2000

  • prompt_cache_options: optional object { ttl } or null

此会话各轮次采用的默认提示词缓存时长(如已配置)。

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

  • "30m"

  • "12h"

  • review: optional "none" or "auto_review"

应用于本会话中适用操作的审查方式。审查模式为 none 且自动审查未启用时,响应省略此字段。字段省略表示 none。

  • "none"

  • "auto_review"

  • type: "agent.session.failed" (default: "agent.session.failed")

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

  • "agent.session.failed"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.failed",
  "event_id": "event_id",
  "session": {
    "prompt_cache_options": {
      "ttl": "30m"
    },
    "review": "none",
    "metadata": {
      "foo": "string"
    },
    "id": "id",
    "object": "agent.session",
    "created_at": 0,
    "last_active_at": 0,
    "status": "idle",
    "required_actions": [
      {
        "type": "mcp_approval_request",
        "turn_id": "turn_id",
        "request_id": "request_id",
        "request": {
          "type": "mcp_tool_call",
          "server_label": "server_label",
          "name": "name",
          "arguments": {},
          "message": "message"
        }
      }
    ],
    "error": "error",
    "agent": {
      "id": "id",
      "name": "name",
      "model": "model",
      "reasoning": {
        "effort": "none",
        "summary": "concise"
      },
      "text": {
        "format": {
          "type": "text"
        },
        "verbosity": "low"
      },
      "service_tier": "auto",
      "instructions": "instructions",
      "tools": [
        {
          "type": "function",
          "name": "name",
          "description": "description",
          "parameters": {
            "foo": "bar"
          },
          "defer_loading": true,
          "async": true
        }
      ],
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 1
      },
      "compaction": {
        "async": true
      },
      "experimental": {
        "time_awareness": true
      }
    },
    "environment": {
      "type": "none"
    },
    "vault_ids": [
      "string"
    ],
    "usage": {
      "input_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.environment.pending

准备会话环境时发出。

结构定义

结构名称为 SessionEventAgentSessionEnvironmentPending。

  • environment: AgentSessionEnvironmentState

环境的当前状态。

  • id: string

环境的公开 ID。

minLength: 0

  • error: object { code, message, type } or null

准备环境时报告的错误(如有)。

  • code: string

机器可读的错误代码。

minLength: 0

  • message: string

便于阅读的错误消息。

minLength: 0

  • type: string

错误类型。

minLength: 0

  • status: "pending" or "ready" or "connected" or 4 more

环境的连接状态。

  • "pending"

正在准备环境。

  • "ready"

环境已就绪,可以连接。

  • "connected"

环境已连接。

  • "disconnected"

环境已断开连接。

  • "suspended"

环境已停止,可从其私有检查点恢复。

  • "expired"

环境及其私有检查点已过期。

  • "failed"

环境连接失败。

  • type: string

环境类型。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.environment.pending" (default: "agent.session.environment.pending")

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

  • "agent.session.environment.pending"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.environment.pending",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "environment": {
    "id": "id",
    "type": "type",
    "status": "pending",
    "error": {
      "type": "type",
      "code": "code",
      "message": "message"
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.environment.connected

会话环境连接时发出。

结构定义

结构名称为 SessionEventAgentSessionEnvironmentConnected。

  • environment: AgentSessionEnvironmentState

环境的当前状态。

  • id: string

环境的公开 ID。

minLength: 0

  • error: object { code, message, type } or null

准备环境时报告的错误(如有)。

  • code: string

机器可读的错误代码。

minLength: 0

  • message: string

便于阅读的错误消息。

minLength: 0

  • type: string

错误类型。

minLength: 0

  • status: "pending" or "ready" or "connected" or 4 more

环境的连接状态。

  • "pending"

正在准备环境。

  • "ready"

环境已就绪,可以连接。

  • "connected"

环境已连接。

  • "disconnected"

环境已断开连接。

  • "suspended"

环境已停止,可从其私有检查点恢复。

  • "expired"

环境及其私有检查点已过期。

  • "failed"

环境连接失败。

  • type: string

环境类型。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.environment.connected" (default: "agent.session.environment.connected")

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

  • "agent.session.environment.connected"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.environment.connected",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "environment": {
    "id": "id",
    "type": "type",
    "status": "pending",
    "error": {
      "type": "type",
      "code": "code",
      "message": "message"
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.environment.disconnected

会话环境断开连接时发出。

结构定义

结构名称为 SessionEventAgentSessionEnvironmentDisconnected。

  • environment: AgentSessionEnvironmentState

环境的当前状态。

  • id: string

环境的公开 ID。

minLength: 0

  • error: object { code, message, type } or null

准备环境时报告的错误(如有)。

  • code: string

机器可读的错误代码。

minLength: 0

  • message: string

便于阅读的错误消息。

minLength: 0

  • type: string

错误类型。

minLength: 0

  • status: "pending" or "ready" or "connected" or 4 more

环境的连接状态。

  • "pending"

正在准备环境。

  • "ready"

环境已就绪,可以连接。

  • "connected"

环境已连接。

  • "disconnected"

环境已断开连接。

  • "suspended"

环境已停止,可从其私有检查点恢复。

  • "expired"

环境及其私有检查点已过期。

  • "failed"

环境连接失败。

  • type: string

环境类型。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.environment.disconnected" (default: "agent.session.environment.disconnected")

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

  • "agent.session.environment.disconnected"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.environment.disconnected",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "environment": {
    "id": "id",
    "type": "type",
    "status": "pending",
    "error": {
      "type": "type",
      "code": "code",
      "message": "message"
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.environment.failed

会话环境发生故障时发出。

结构定义

结构名称为 SessionEventAgentSessionEnvironmentFailed。

  • environment: AgentSessionEnvironmentState

环境的当前状态。

  • id: string

环境的公开 ID。

minLength: 0

  • error: object { code, message, type } or null

准备环境时报告的错误(如有)。

  • code: string

机器可读的错误代码。

minLength: 0

  • message: string

便于阅读的错误消息。

minLength: 0

  • type: string

错误类型。

minLength: 0

  • status: "pending" or "ready" or "connected" or 4 more

环境的连接状态。

  • "pending"

正在准备环境。

  • "ready"

环境已就绪,可以连接。

  • "connected"

环境已连接。

  • "disconnected"

环境已断开连接。

  • "suspended"

环境已停止,可从其私有检查点恢复。

  • "expired"

环境及其私有检查点已过期。

  • "failed"

环境连接失败。

  • type: string

环境类型。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.environment.failed" (default: "agent.session.environment.failed")

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

  • "agent.session.environment.failed"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.environment.failed",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "environment": {
    "id": "id",
    "type": "type",
    "status": "pending",
    "error": {
      "type": "type",
      "code": "code",
      "message": "message"
    }
  },
  "obfuscation": "obfuscation"
}

agent.session.subagent.created

创建子智能体时发出。

结构定义

结构名称为 SessionEventAgentSessionSubagentCreated。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • subagent: Subagent

新创建的子智能体。

  • id: string

子智能体 ID。

minLength: 0

  • closed_at: integer or null

子智能体关闭时的 Unix 时间戳,单位为秒。子智能体活动期间为 null,恢复运行后也适用。

format: int64

  • instructions: array of AgentContent or null

初始任务内容。无法取得时为 null。仅能提供预览时,文本可包含图像或音频的占位符。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • text: string

智能体生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

内容类型,固定为 output_text。

  • "output_text"

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • encrypted_content: string

加密内容载荷。

minLength: 0

  • type: "encrypted_content" (default: "encrypted_content")

内容类型,固定为 encrypted_content。

  • "encrypted_content"

  • name: string or null

运行器分配的昵称。无法取得时为 null。

minLength: 0

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

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

  • "agent.session.subagent"

  • opened_at: integer

子智能体首次打开时的 Unix 时间戳,单位为秒。恢复运行时此值保持不变。

format: int64

  • parent_agent_id: string

创建此子智能体的智能体 ID。

minLength: 0

  • session_id: string

所属会话的 ID。

minLength: 0

  • status: "active" or "closed"

子智能体当前的状态。

  • "active"

子智能体仍可使用,包括在两轮之间空闲时。

  • "closed"

子智能体已关闭。

  • type: "agent.session.subagent.created" (default: "agent.session.subagent.created")

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

  • "agent.session.subagent.created"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.subagent.created",
  "event_id": "event_id",
  "subagent": {
    "id": "id",
    "object": "agent.session.subagent",
    "session_id": "session_id",
    "name": "name",
    "instructions": [
      {
        "type": "output_text",
        "text": "text"
      }
    ],
    "parent_agent_id": "parent_agent_id",
    "status": "active",
    "opened_at": 0,
    "closed_at": 0
  },
  "obfuscation": "obfuscation"
}

agent.session.subagent.active

已关闭的子智能体成功恢复时发出。

结构定义

结构名称为 SessionEventAgentSessionSubagentActive。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • subagent: Subagent

已恢复的子智能体。

  • id: string

子智能体 ID。

minLength: 0

  • closed_at: integer or null

子智能体关闭时的 Unix 时间戳,单位为秒。子智能体活动期间为 null,恢复运行后也适用。

format: int64

  • instructions: array of AgentContent or null

初始任务内容。无法取得时为 null。仅能提供预览时,文本可包含图像或音频的占位符。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • text: string

智能体生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

内容类型,固定为 output_text。

  • "output_text"

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • encrypted_content: string

加密内容载荷。

minLength: 0

  • type: "encrypted_content" (default: "encrypted_content")

内容类型,固定为 encrypted_content。

  • "encrypted_content"

  • name: string or null

运行器分配的昵称。无法取得时为 null。

minLength: 0

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

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

  • "agent.session.subagent"

  • opened_at: integer

子智能体首次打开时的 Unix 时间戳,单位为秒。恢复运行时此值保持不变。

format: int64

  • parent_agent_id: string

创建此子智能体的智能体 ID。

minLength: 0

  • session_id: string

所属会话的 ID。

minLength: 0

  • status: "active" or "closed"

子智能体当前的状态。

  • "active"

子智能体仍可使用,包括在两轮之间空闲时。

  • "closed"

子智能体已关闭。

  • type: "agent.session.subagent.active" (default: "agent.session.subagent.active")

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

  • "agent.session.subagent.active"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.subagent.active",
  "event_id": "event_id",
  "subagent": {
    "id": "id",
    "object": "agent.session.subagent",
    "session_id": "session_id",
    "name": "name",
    "instructions": [
      {
        "type": "output_text",
        "text": "text"
      }
    ],
    "parent_agent_id": "parent_agent_id",
    "status": "active",
    "opened_at": 0,
    "closed_at": 0
  },
  "obfuscation": "obfuscation"
}

agent.session.subagent.closed

子智能体关闭时发出。

结构定义

结构名称为 SessionEventAgentSessionSubagentClosed。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • subagent: Subagent

已关闭的子智能体。

  • id: string

子智能体 ID。

minLength: 0

  • closed_at: integer or null

子智能体关闭时的 Unix 时间戳,单位为秒。子智能体活动期间为 null,恢复运行后也适用。

format: int64

  • instructions: array of AgentContent or null

初始任务内容。无法取得时为 null。仅能提供预览时,文本可包含图像或音频的占位符。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • text: string

智能体生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

内容类型,固定为 output_text。

  • "output_text"

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • encrypted_content: string

加密内容载荷。

minLength: 0

  • type: "encrypted_content" (default: "encrypted_content")

内容类型,固定为 encrypted_content。

  • "encrypted_content"

  • name: string or null

运行器分配的昵称。无法取得时为 null。

minLength: 0

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

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

  • "agent.session.subagent"

  • opened_at: integer

子智能体首次打开时的 Unix 时间戳,单位为秒。恢复运行时此值保持不变。

format: int64

  • parent_agent_id: string

创建此子智能体的智能体 ID。

minLength: 0

  • session_id: string

所属会话的 ID。

minLength: 0

  • status: "active" or "closed"

子智能体当前的状态。

  • "active"

子智能体仍可使用,包括在两轮之间空闲时。

  • "closed"

子智能体已关闭。

  • type: "agent.session.subagent.closed" (default: "agent.session.subagent.closed")

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

  • "agent.session.subagent.closed"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.subagent.closed",
  "event_id": "event_id",
  "subagent": {
    "id": "id",
    "object": "agent.session.subagent",
    "session_id": "session_id",
    "name": "name",
    "instructions": [
      {
        "type": "output_text",
        "text": "text"
      }
    ],
    "parent_agent_id": "parent_agent_id",
    "status": "active",
    "opened_at": 0,
    "closed_at": 0
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.item.done

输出条目完成时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnItemDone。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item: AgentOutputItem

已完成的输出条目。

  • AgentSessionAssistantMessage object { id, content, phase, 4 more }

智能体生成的助手消息。

  • id: string

消息 ID。

minLength: 0

  • content: array of OutputText

消息内容。

minItems: 0, maxItems: 2000

  • text: string

智能体生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

内容类型,固定为 output_text。

  • "output_text"

  • phase: "commentary" or "final_answer" or null

助手消息所处的阶段。

  • "commentary"

智能体工作时生成的过程说明。

  • "final_answer"

智能体的最终回答。

  • role: "assistant" (default: "assistant")

消息作者的角色,固定为 assistant。

  • "assistant"

  • status: AgentOutputItemStatus

消息的状态。

  • "in_progress"

条目正在处理。

  • "completed"

条目处理已完成。

  • "incomplete"

条目在完成前已停止。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "message" (default: "message")

类型,固定为message。

  • "message"

  • AgentReasoningItem object { id, status, summary, 2 more }

智能体生成的推理条目。

  • id: string

推理条目的 ID。

minLength: 0

  • status: AgentOutputItemStatus or null

推理条目的状态。

  • summary: array of SummaryText

智能体生成的推理摘要。

minItems: 0, maxItems: 2000

  • text: string

推理摘要文本。

minLength: 0

  • type: "summary_text" (default: "summary_text")

内容类型,固定为 summary_text。

  • "summary_text"

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "reasoning" (default: "reasoning")

条目类型,固定为 reasoning。

  • "reasoning"

  • AgentFunctionCallItem object { id, arguments, call_id, 4 more }

智能体生成的函数调用。

  • id: string

函数调用条目的 ID。

minLength: 0

  • arguments: unknown

要传给函数的参数。

  • call_id: string

用于提交函数结果的 ID。

minLength: 0

  • name: string

要调用的函数名称。

minLength: 0

  • status: AgentFunctionCallStatus

函数调用的状态。

  • "in_progress"

调用正在进行。

  • "completed"

调用已成功完成。

  • "failed"

调用失败。

  • "incomplete"

调用在完成前已停止。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "function_call" (default: "function_call")

条目类型,固定为 function_call。

  • "function_call"

  • AgentMcpCallItem object { id, arguments, error, 6 more }

调用 MCP 服务器工具的记录。

  • id: string

MCP 调用条目的 ID。

minLength: 0

  • arguments: unknown

传给 MCP 工具的参数。

  • error: unknown

MCP 工具返回的错误(如果有)。

  • name: string

MCP 工具名称。

minLength: 0

  • output: unknown

MCP 工具返回的输出(如果有)。

  • server_label: string

MCP服务器标签。

minLength: 0

  • status: AgentFunctionCallStatus

MCP 工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "mcp_call" (default: "mcp_call")

条目类型,固定为 mcp_call。

  • "mcp_call"

  • ComputerUseCall object { id, output, status, 3 more }

平台提供的计算机使用功能的一次执行。

  • id: string

活动条目的 ID。

minLength: 0

  • output: object { image_url, type } or null

模型发出的最后一张屏幕截图。未启用返回截图,或调用未生成截图时为 null。

  • image_url: string

完整的 JPEG 图像,表示为 Base64 data URL。

minLength: 0

  • type: "computer_screenshot" (default: "computer_screenshot")

内容类型,固定为 computer_screenshot。

  • "computer_screenshot"

  • status: AgentFunctionCallStatus

活动的执行状态。

  • title: string or null

模型生成的活动说明(如果有)。

minLength: 0

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "computer_use_call" (default: "computer_use_call")

条目类型,固定为 computer_use_call。

  • "computer_use_call"

  • ComputerUseApprovalRequest object { id, request, request_id, 2 more }

已发出登录请求的历史记录,其中省略凭证。

  • id: string

稳定的历史条目 ID。

minLength: 0

  • request: object { credential_origin, fields, options, 2 more }

等待应用响应的已注册表单。

  • credential_origin: string or null

将在其上填写值的已注册表单或框架的源站。

minLength: 0

  • fields: array of object { id, label, required, type }

要呈现的表单控件。所有提交的值均为敏感数据。

minItems: 0, maxItems: 2000

  • id: string

提交 fields 条目时要用作 field_id 的字段 ID。

minLength: 0

  • label: string

显示在控件旁的标签。

minLength: 0

  • required: boolean

此控件是否需要非空值。

  • type: string

控件的呈现类型,例如电子邮件、密码或文本。

minLength: 0

  • options: array of object { id, field_ids, label }

登录方式。普通表单中为空。

minItems: 0, maxItems: 2000

  • id: string

作为 selected_option 提交的选项 ID。

minLength: 0

  • field_ids: array of string

此方法接受的已注册字段 ID。

minItems: 0, maxItems: 2000

  • label: string

要显示的方式标签。

minLength: 0

  • reason: string or null

智能体需要用户登录的原因。

minLength: 0

  • type: "browser_authentication" (default: "browser_authentication")

对象类型,固定为 browser_authentication。

  • "browser_authentication"

  • request_id: string

minLength: 0

  • turn_id: string

minLength: 0

  • type: "computer_use_approval_request" (default: "computer_use_approval_request")

条目类型,固定为 computer_use_approval_request。

  • "computer_use_approval_request"

  • AgentWebSearchCallItem object { id, action, status, 2 more }

智能体生成的网页搜索调用。

  • id: string

网页搜索调用 ID。

minLength: 0

  • action: WebSearchAction or null

网页搜索工具执行的操作。

  • Search object { queries, query, type }

一条或一组搜索查询。

  • queries: array of string or null

使用多条查询时的搜索查询列表。

minItems: 0, maxItems: 2000

  • query: string or null

使用单条查询时的搜索查询。

minLength: 0

  • type: "search" (default: "search")

对象类型,固定为 search。

  • "search"

  • OpenPage object { type, url }

打开网页。

  • type: "open_page" (default: "open_page")

对象类型,固定为 open_page。

  • "open_page"

  • url: string or null

打开的网页的 URL。

minLength: 0

  • FindInPage object { pattern, type, url }

在网页中查找文本。

  • pattern: string or null

要查找的文本模式。

minLength: 0

  • type: "find_in_page" (default: "find_in_page")

对象类型,固定为 find_in_page。

  • "find_in_page"

  • url: string or null

执行查找操作的网页 URL。

minLength: 0

  • Other object { type }

其他网页搜索操作。

  • type: "other" (default: "other")

对象类型,固定为 other。

  • "other"

  • status: AgentOutputItemStatus

网页搜索调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "web_search_call" (default: "web_search_call")

条目类型,固定为 web_search_call。

  • "web_search_call"

  • AgentCommandExecutionItem object { id, command, cwd, 6 more }

智能体生成的命令执行记录。

  • id: string

命令执行条目的 ID。

minLength: 0

  • command: string

执行过的命令。

minLength: 0

  • cwd: string or null

执行命令时使用的工作目录。

minLength: 0

  • duration_ms: integer or null

命令执行时长,单位为毫秒。

format: int64

  • exit_code: integer or null

命令执行结束后的进程退出码。

format: int64

  • output: string or null

命令输出(如果有)。

minLength: 0

  • status: AgentFunctionCallStatus

命令执行的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "command_execution" (default: "command_execution")

条目类型,固定为 command_execution。

  • "command_execution"

  • AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }

创建子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • agent_id: string

请求创建子智能体的智能体 ID。

minLength: 0

  • content: array of AgentContent

交给新建智能体的任务。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • text: string

智能体生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

内容类型,固定为 output_text。

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • encrypted_content: string

加密内容载荷。

minLength: 0

  • type: "encrypted_content" (default: "encrypted_content")

内容类型,固定为 encrypted_content。

  • "encrypted_content"

  • model: string or null

为新建的子智能体指定的模型。

minLength: 0

  • reasoning_effort: string or null

为新建的子智能体指定的推理强度。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "create_subagent_call" (default: "create_subagent_call")

条目类型,固定为 create_subagent_call。

  • "create_subagent_call"

  • AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }

向另一智能体发送输入的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • content: array of AgentContent

发给接收方智能体的输入。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • recipient_agent_id: string

接收输入的智能体 ID。

minLength: 0

  • sender_agent_id: string

发送输入的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "send_subagent_input_call" (default: "send_subagent_input_call")

条目类型,固定为 send_subagent_input_call。

  • "send_subagent_input_call"

  • AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

恢复子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_id: string

要恢复的智能体 ID。

minLength: 0

  • sender_agent_id: string

发起恢复请求的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "resume_subagent_call" (default: "resume_subagent_call")

条目类型,固定为 resume_subagent_call。

  • "resume_subagent_call"

  • AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }

等待一个或多个子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_ids: array of string

要等待的智能体 ID 列表。

minItems: 0, maxItems: 2000

  • sender_agent_id: string

等待结果的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "wait_for_subagents_call" (default: "wait_for_subagents_call")

条目类型,固定为 wait_for_subagents_call。

  • "wait_for_subagents_call"

  • AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

中断子智能体当前轮次的请求。该子智能体仍可使用。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_id: string

要中断的智能体 ID。

minLength: 0

  • sender_agent_id: string

发起中断请求的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "interrupt_subagent_call" (default: "interrupt_subagent_call")

条目类型,固定为 interrupt_subagent_call。

  • "interrupt_subagent_call"

  • AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

关闭子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_id: string

要关闭的智能体 ID。

minLength: 0

  • sender_agent_id: string

发起关闭请求的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "close_subagent_call" (default: "close_subagent_call")

条目类型,固定为 close_subagent_call。

  • "close_subagent_call"

  • output_index: integer

输出条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.turn.item.done" (default: "agent.session.turn.item.done")

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

  • "agent.session.turn.item.done"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.item.done",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "output_index": 0,
  "item": {
    "type": "message",
    "id": "id",
    "turn_id": "turn_id",
    "role": "assistant",
    "status": "in_progress",
    "content": [
      {
        "type": "output_text",
        "text": "text"
      }
    ],
    "phase": "commentary"
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.content_part.added

添加输出文本内容部分时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnContentPartAdded。

  • content_index: integer

内容部分在消息中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item_id: string

消息条目的 ID。

minLength: 0

  • output_index: integer

条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • part: OutputText

初始内容部分。

  • text: string

智能体生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

内容类型,固定为 output_text。

  • "output_text"

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.turn.content_part.added" (default: "agent.session.turn.content_part.added")

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

  • "agent.session.turn.content_part.added"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.content_part.added",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "item_id": "item_id",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "output_text",
    "text": "text"
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.content_part.done

输出内容部分完成时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnContentPartDone。

  • content_index: integer

内容部分在消息中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item_id: string

消息条目的 ID。

minLength: 0

  • output_index: integer

条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • part: OutputText

已完成的内容部分。

  • text: string

智能体生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

内容类型,固定为 output_text。

  • "output_text"

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.turn.content_part.done" (default: "agent.session.turn.content_part.done")

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

  • "agent.session.turn.content_part.done"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.content_part.done",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "item_id": "item_id",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "output_text",
    "text": "text"
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.output_text.delta

向输出文本内容部分追加文本时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnOutputTextDelta。

  • content_index: integer

内容部分在消息中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • delta: string

此次追加的文本。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item_id: string

消息条目的 ID。

minLength: 0

  • output_index: integer

条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.turn.output_text.delta" (default: "agent.session.turn.output_text.delta")

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

  • "agent.session.turn.output_text.delta"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.output_text.delta",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "item_id": "item_id",
  "output_index": 0,
  "content_index": 0,
  "delta": "delta",
  "obfuscation": "obfuscation"
}

agent.session.turn.output_text.done

输出文本内容部分完成时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnOutputTextDone。

  • content_index: integer

内容部分在消息中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item_id: string

消息条目的 ID。

minLength: 0

  • output_index: integer

条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • text: string

完整的输出文本。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.turn.output_text.done" (default: "agent.session.turn.output_text.done")

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

  • "agent.session.turn.output_text.done"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.output_text.done",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "item_id": "item_id",
  "output_index": 0,
  "content_index": 0,
  "text": "text",
  "obfuscation": "obfuscation"
}

agent.session.turn.reasoning_summary_part.added

添加推理摘要内容部分时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnReasoningSummaryPartAdded。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item_id: string

推理条目的 ID。

minLength: 0

  • output_index: integer

条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • part: SummaryText

初始摘要部分。

  • text: string

推理摘要文本。

minLength: 0

  • type: "summary_text" (default: "summary_text")

内容类型,固定为 summary_text。

  • "summary_text"

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • summary_index: integer

摘要内容部分的索引。

format: int64, minimum: 0, maximum: 4294967295

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.turn.reasoning_summary_part.added" (default: "agent.session.turn.reasoning_summary_part.added")

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

  • "agent.session.turn.reasoning_summary_part.added"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.reasoning_summary_part.added",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "item_id": "item_id",
  "output_index": 0,
  "summary_index": 0,
  "part": {
    "type": "summary_text",
    "text": "text"
  },
  "obfuscation": "obfuscation"
}

agent.session.turn.reasoning_summary_part.done

推理摘要部分完成时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnReasoningSummaryPartDone。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item_id: string

推理条目的 ID。

minLength: 0

  • output_index: integer

条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • part: SummaryText

已完成的摘要部分。

  • text: string

推理摘要文本。

minLength: 0

  • type: "summary_text" (default: "summary_text")

内容类型,固定为 summary_text。

  • "summary_text"

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • status: "incomplete" or null

摘要生成中断时,此字段为 incomplete。

  • "incomplete"

  • summary_index: integer

摘要部分的索引。

format: int64, minimum: 0, maximum: 4294967295

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.turn.reasoning_summary_part.done" (default: "agent.session.turn.reasoning_summary_part.done")

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

  • "agent.session.turn.reasoning_summary_part.done"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.reasoning_summary_part.done",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "item_id": "item_id",
  "output_index": 0,
  "summary_index": 0,
  "part": {
    "type": "summary_text",
    "text": "text"
  },
  "status": "incomplete",
  "obfuscation": "obfuscation"
}

agent.session.turn.reasoning_summary_text.delta

向推理摘要追加文本时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnReasoningSummaryTextDelta。

  • delta: string

此次追加的摘要文本。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item_id: string

推理条目的 ID。

minLength: 0

  • output_index: integer

条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • summary_index: integer

摘要内容部分的索引。

format: int64, minimum: 0, maximum: 4294967295

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.turn.reasoning_summary_text.delta" (default: "agent.session.turn.reasoning_summary_text.delta")

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

  • "agent.session.turn.reasoning_summary_text.delta"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.reasoning_summary_text.delta",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "item_id": "item_id",
  "output_index": 0,
  "summary_index": 0,
  "delta": "delta",
  "obfuscation": "obfuscation"
}

agent.session.turn.reasoning_summary_text.done

推理摘要的内容部分完成时发出。

结构定义

结构名称为 SessionEventAgentSessionTurnReasoningSummaryTextDone。

  • event_id: string

事件的唯一 ID。

minLength: 0

  • item_id: string

推理条目的 ID。

minLength: 0

  • output_index: integer

条目在轮次输出中的索引。

format: int64, minimum: 0, maximum: 4294967295

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • summary_index: integer

摘要内容部分的索引。

format: int64, minimum: 0, maximum: 4294967295

  • text: string

完整的推理摘要文本。

minLength: 0

  • turn_id: string or null

与事件关联的轮次 ID(如适用)。

minLength: 0

  • type: "agent.session.turn.reasoning_summary_text.done" (default: "agent.session.turn.reasoning_summary_text.done")

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

  • "agent.session.turn.reasoning_summary_text.done"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "agent.session.turn.reasoning_summary_text.done",
  "event_id": "event_id",
  "session_id": "session_id",
  "turn_id": "turn_id",
  "item_id": "item_id",
  "output_index": 0,
  "summary_index": 0,
  "text": "text",
  "obfuscation": "obfuscation"
}

error

轮次或会话失败时发出。

结构定义

结构名称为 SessionEventError。

  • error: SessionError

发生的错误。

  • code: string or null

供程序识别的错误代码(如有)。

minLength: 0

  • message: string

可向客户显示的错误说明。

minLength: 0

  • param: string or null

与错误关联的请求参数(如有)。

minLength: 0

  • type: string

错误类型。

minLength: 0

  • event_id: string

事件的唯一 ID。

minLength: 0

  • session_id: string

与事件关联的会话 ID。

minLength: 0

  • type: "error" (default: "error")

对象类型,固定为 error。

  • "error"

  • obfuscation: optional string

随机字母数字填充。启用流混淆时提供。

minLength: 0

示例

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

{
  "type": "error",
  "event_id": "event_123",
  "session_id": "sess_123",
  "error": {
    "type": "server_error",
    "code": null,
    "message": "The session failed due to an internal server error.",
    "param": null
  }
}

可使用流式接收会话事件接口获取这些事件。

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

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号