OpenAI Agents 接口总览
智能体
创建智能体
post /agents
创建可复用智能体。此接口不存储凭证。参见智能体配置。
请求体参数
内容类型为 application/json。
model: string
智能体使用的模型。系统保留请求中的模型名称。
minLength: 0, maxLength: 1048576
compaction: optional object { async } or null
上下文压缩配置。省略或传 null 时采用阻塞式压缩。
async: optional boolean or null
是否在后台压缩上下文。省略或传 null 时默认为 false。设为 true 可启用后台压缩。后台压缩可能增加词元用量。
experimental: optional object { time_awareness } (default: {"time_awareness":false})
智能体的实验性设置。所有实验性功能默认关闭。
time_awareness: optional boolean (default: false)
模型是否会定期收到当前时间提醒。省略或传 null 时默认为 false。
instructions: optional string or null
附加到智能体默认基础指令之后的自定义指令。省略或设为 null 时,不附加自定义指令。
minLength: 0, maxLength: 1048576
metadata: optional map[string] or null
最多 16 个字符串键值对,键最长 64 个字符,值最长 512 个字符。省略或传 null 时默认为空映射。
multi_agent: optional MultiAgentConfigParam or null
创建和协调子智能体的配置。子智能体工具默认禁用。
enabled: boolean
是否启用子智能体工具。
max_concurrent_subagents: optional integer
可同时运行的子智能体数上限,默认为 6。
format: int64, minimum: 1, maximum: 4294967295
name: optional string or null
智能体的可读名称。省略或传 null 时,智能体保持未命名。
minLength: 0, maxLength: 128
reasoning: optional AgentReasoningParam or null
模型推理配置。省略时采用模型的默认推理强度。
effort: optional "none" or "minimal" or "low" or 4 more or null
模型使用的推理强度。省略时由模型选择。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: optional "concise" or "detailed" or "auto" or null
控制响应是否包含推理摘要。
"concise"
模型支持时,返回简明推理摘要。
"detailed"
模型支持时,返回详细推理摘要。
"auto"
自动选择模型支持的最详细摘要。
service_tier: optional "auto" or "default" or "flex" or 3 more or null
用于模型请求的服务层级,默认为 auto。
"auto"
自动选择服务层级。
"default"
使用默认服务层级。
"flex"
使用 Flex 服务层级。
"priority"
使用 Priority 服务层级。
"fast"
使用 Fast 服务层级。
"ultrafast"
使用 Ultrafast 服务层级。
text: optional AgentTextParam or null
生成文本的配置。默认为 text 格式和中等详细程度。
format: optional TextFormatParam or null
输出格式。省略时使用普通文本({"type": "text"})。
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: optional "low" or "medium" or "high" or null
模型应生成的文本量。与 Responses 一致,默认为 medium。
"low"
生成较少文本。
"medium"
使用默认文本量。
"high"
生成较多文本。
tools: optional array of PersistedAgentToolParam or null
智能体可用的工具。默认是空列表。工具列表采用紧凑 UTF-8 JSON 编码时,大小不得超过 3 MiB(3,145,728 字节)。
minItems: 0, maxItems: 2000
Function object { description, name, parameters, 3 more }
应用定义的函数。
description: string
说明函数的用途。
minLength: 0, maxLength: 1048576
name: string
函数名称。
minLength: 0, maxLength: 1048576
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean (default: false)
智能体是否无需等待函数结果即可继续。默认为 false。
defer_loading: optional boolean (default: false)
是否延迟加载函数并通过工具搜索发现。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
ProgrammaticToolCalling object { type, enabled }
允许模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
enabled: optional boolean (default: true)
是否允许从模型生成的代码调用工具。默认为 true。
Mcp object { server_label, transport, type, 5 more }
未配置已存储凭证的远程 MCP 服务器提供的工具。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0, maxLength: 1048576
transport: PersistedMcpTransportParam
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { server_url, type, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
headers: optional map[string] or null
发送给 MCP 服务器的非机密 HTTP 请求头。
Stdio object { command, cwd, type, 2 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
allowed_tools: optional array of string or null
智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。
minItems: 0, maxItems: 16384
connection_origin: optional "service" or "environment" or null
选择出站 MCP HTTP 连接的来源。
"service"
使用 Managed Agents 服务网络。
"environment"
使用会话的执行环境。
credential_id: optional string or null
为此 MCP 服务器选择的凭证库凭证。如果只有一条已附加凭证与服务器 URL 匹配,则可省略。
minLength: 0, maxLength: 1048576
request_metadata: optional map[unknown] or null
随请求发送给此 MCP 服务器的元数据。
required: optional boolean (default: false)
是否必须在第一轮前初始化此 MCP 服务器。默认为 false。
WebSearch object { type, allowed_domains, context_size, 2 more }
网页搜索。
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
allowed_domains: optional array of string or null
可纳入搜索范围的域名。
minItems: 0, maxItems: 16384
context_size: optional "low" or "medium" or "high" or null
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置。
city: optional string or null
城市名称。
minLength: 0, maxLength: 1048576
country: optional string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0, maxLength: 1048576
region: optional string or null
地区或州的名称。
minLength: 0, maxLength: 1048576
timezone: optional string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0, maxLength: 1048576
mode: optional "disabled" or "cached" or "live" or null
网页搜索结果的来源,默认为 live。
"disabled"
关闭网页搜索。
"cached"
使用缓存的搜索结果。
"live"
搜索实时网页。
ComputerUse object { type, include_screenshots }
在 OpenAI 托管会话中使用浏览器。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
include_screenshots: optional boolean (default: false)
计算机工具的输出是否包含屏幕截图。默认为 false。
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
返回值
Agent object { id, created_at, instructions, 12 more }
属于调用方项目的可复用智能体。
id: string
可复用智能体的 ID。
minLength: 0
created_at: integer
创建智能体时的 Unix 时间戳,单位为秒。
format: int64
instructions: string or null
附加到智能体默认基础指令之后的自定义指令。
minLength: 0
metadata: map[string]
附加到智能体的自定义字符串键值对。
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
object: "agent" (default: "agent")
对象类型,恒为 agent。
"agent"
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"
"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 PersistedAgentTool
智能体可用的工具。
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
智能体是否无需等待函数结果即可继续。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
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 工具。允许服务器上的全部工具时为 null。
minItems: 0, maxItems: 2000
connection_origin: "service" or "environment"
出站 MCP HTTP 连接的来源。
"service"
"environment"
credential_id: string or null
为此 MCP 服务器选择的凭证库凭证(如有)。
minLength: 0
request_metadata: map[unknown]
随请求发送给此 MCP 服务器的元数据。
required: boolean
是否必须在第一轮前初始化此 MCP 服务器。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0
transport: PersistedMcpTransport
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { headers, server_url, type }
通过 HTTP 连接到 MCP 服务器。
headers: map[string]
发送给 MCP 服务器的非机密 HTTP 请求头。
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"
updated_at: integer
上次更新智能体时的 Unix 时间戳,单位为秒。
format: int64
compaction: optional object { async }
当前生效的上下文压缩配置。
async: boolean
是否在后台压缩上下文。默认为 false。
experimental: optional object { time_awareness }
当前生效的实验性设置。
time_awareness: boolean
模型是否会定期收到当前时间提醒。
示例
## 从环境变量读取 API 密钥。
## 将请求体中的 model 占位值替换为项目可用的模型 ID。
curl https://api.openai.com/v1/agents \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "model"
}'
201 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"instructions": "instructions",
"metadata": {
"foo": "string"
},
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"name": "name",
"object": "agent",
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"updated_at": 0,
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
}
删除智能体
delete /agents/{agent_id}
删除可复用智能体。参见智能体配置。
路径参数
agent_id: string
可复用智能体的 ID。
minLength: 0, maxLength: 1048576
返回值
AgentDeleted object { id, deleted, object }
已删除的可复用智能体。
id: string
已删除智能体的 ID。
minLength: 0
deleted: boolean
智能体是否已删除。恒为 true。
object: "agent.deleted" (default: "agent.deleted")
对象类型,恒为 agent.deleted。
"agent.deleted"
示例
## 从环境变量读取 API 密钥。
## 将 AGENT_ID 设置为要操作的智能体 ID。
curl https://api.openai.com/v1/agents/$AGENT_ID \
-X DELETE \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"deleted": true,
"object": "agent.deleted"
}
列出智能体
get /agents
列出当前项目中的可复用智能体。参见智能体配置。
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of Agent
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
可复用智能体的 ID。
minLength: 0
created_at: integer
创建智能体时的 Unix 时间戳,单位为秒。
format: int64
instructions: string or null
附加到智能体默认基础指令之后的自定义指令。
minLength: 0
metadata: map[string]
附加到智能体的自定义字符串键值对。
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
object: "agent" (default: "agent")
对象类型,恒为 agent。
"agent"
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"
"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 PersistedAgentTool
智能体可用的工具。
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
智能体是否无需等待函数结果即可继续。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
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 工具。允许服务器上的全部工具时为 null。
minItems: 0, maxItems: 2000
connection_origin: "service" or "environment"
出站 MCP HTTP 连接的来源。
"service"
"environment"
credential_id: string or null
为此 MCP 服务器选择的凭证库凭证(如有)。
minLength: 0
request_metadata: map[unknown]
随请求发送给此 MCP 服务器的元数据。
required: boolean
是否必须在第一轮前初始化此 MCP 服务器。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0
transport: PersistedMcpTransport
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { headers, server_url, type }
通过 HTTP 连接到 MCP 服务器。
headers: map[string]
发送给 MCP 服务器的非机密 HTTP 请求头。
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"
updated_at: integer
上次更新智能体时的 Unix 时间戳,单位为秒。
format: int64
compaction: optional object { async }
当前生效的上下文压缩配置。
async: boolean
是否在后台压缩上下文。默认为 false。
experimental: optional object { time_awareness }
当前生效的实验性设置。
time_awareness: boolean
模型是否会定期收到当前时间提醒。
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
curl https://api.openai.com/v1/agents \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"created_at": 0,
"instructions": "instructions",
"metadata": {
"foo": "string"
},
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"name": "name",
"object": "agent",
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"updated_at": 0,
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取智能体
get /agents/{agent_id}
按 ID 获取可复用智能体。参见智能体配置。
路径参数
agent_id: string
可复用智能体的 ID。
minLength: 0, maxLength: 1048576
返回值
Agent object { id, created_at, instructions, 12 more }
属于调用方项目的可复用智能体。
id: string
可复用智能体的 ID。
minLength: 0
created_at: integer
创建智能体时的 Unix 时间戳,单位为秒。
format: int64
instructions: string or null
附加到智能体默认基础指令之后的自定义指令。
minLength: 0
metadata: map[string]
附加到智能体的自定义字符串键值对。
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
object: "agent" (default: "agent")
对象类型,恒为 agent。
"agent"
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"
"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 PersistedAgentTool
智能体可用的工具。
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
智能体是否无需等待函数结果即可继续。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
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 工具。允许服务器上的全部工具时为 null。
minItems: 0, maxItems: 2000
connection_origin: "service" or "environment"
出站 MCP HTTP 连接的来源。
"service"
"environment"
credential_id: string or null
为此 MCP 服务器选择的凭证库凭证(如有)。
minLength: 0
request_metadata: map[unknown]
随请求发送给此 MCP 服务器的元数据。
required: boolean
是否必须在第一轮前初始化此 MCP 服务器。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0
transport: PersistedMcpTransport
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { headers, server_url, type }
通过 HTTP 连接到 MCP 服务器。
headers: map[string]
发送给 MCP 服务器的非机密 HTTP 请求头。
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"
updated_at: integer
上次更新智能体时的 Unix 时间戳,单位为秒。
format: int64
compaction: optional object { async }
当前生效的上下文压缩配置。
async: boolean
是否在后台压缩上下文。默认为 false。
experimental: optional object { time_awareness }
当前生效的实验性设置。
time_awareness: boolean
模型是否会定期收到当前时间提醒。
示例
## 从环境变量读取 API 密钥。
## 将 AGENT_ID 设置为要操作的智能体 ID。
curl https://api.openai.com/v1/agents/$AGENT_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"instructions": "instructions",
"metadata": {
"foo": "string"
},
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"name": "name",
"object": "agent",
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"updated_at": 0,
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
}
更新智能体
post /agents/{agent_id}
更新可复用智能体。参见智能体配置。
路径参数
agent_id: string
可复用智能体的 ID。
minLength: 0, maxLength: 1048576
请求体参数
内容类型为 application/json。
compaction: optional object { async } or null
上下文压缩配置。省略时保留现有设置,传入对象时替换现有设置,传 null 或空对象时采用阻塞式压缩。
async: optional boolean or null
是否在后台压缩上下文。省略或传 null 时默认为 false。设为 true 可启用后台压缩。后台压缩可能增加词元用量。
experimental: optional object { time_awareness } (default: {})
按键合并的实验性设置。省略的设置保留现有值。
time_awareness: optional boolean
模型是否会定期收到当前时间提醒。省略时保留现有设置。
instructions: optional string or null
附加到智能体默认基础指令之后的自定义指令。省略时保留原值。
minLength: 0, maxLength: 1048576
metadata: optional map[string] or null
替换全部元数据。省略时保留原值,传 null 或 {} 可清除。最多 16 个字符串键值对,键最长 64 个字符,值最长 512 个字符。
model: optional string
智能体使用的模型。系统保留请求中的模型名称。
minLength: 0, maxLength: 1048576
multi_agent: optional MultiAgentConfigParam or null
创建和协调子智能体的配置。
enabled: boolean
是否启用子智能体工具。
max_concurrent_subagents: optional integer
可同时运行的子智能体数上限,默认为 6。
format: int64, minimum: 1, maximum: 4294967295
name: optional string or null
新的名称。省略时保留原值,传 null 可清除名称。
minLength: 0, maxLength: 128
reasoning: optional AgentReasoningParam or null
模型推理配置。省略时保留现有设置,传 null 时恢复模型的默认推理强度。
effort: optional "none" or "minimal" or "low" or 4 more or null
模型使用的推理强度。省略时由模型选择。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: optional "concise" or "detailed" or "auto" or null
控制响应是否包含推理摘要。
"concise"
模型支持时,返回简明推理摘要。
"detailed"
模型支持时,返回详细推理摘要。
"auto"
自动选择模型支持的最详细摘要。
service_tier: optional "auto" or "default" or "flex" or 3 more or null
用于模型请求的服务层级。
"auto"
自动选择服务层级。
"default"
使用默认服务层级。
"flex"
使用 Flex 服务层级。
"priority"
使用 Priority 服务层级。
"fast"
使用 Fast 服务层级。
"ultrafast"
使用 Ultrafast 服务层级。
text: optional AgentTextParam or null
智能体生成文本的配置。
format: optional TextFormatParam or null
输出格式。省略时使用普通文本({"type": "text"})。
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: optional "low" or "medium" or "high" or null
模型应生成的文本量。与 Responses 一致,默认为 medium。
"low"
生成较少文本。
"medium"
使用默认文本量。
"high"
生成较多文本。
tools: optional array of PersistedAgentToolParam or null
替换工具列表。省略时保留原值,传 null 可清除。替换后的列表采用紧凑 UTF-8 JSON 编码时,大小不得超过 3 MiB(3,145,728 字节)。
minItems: 0, maxItems: 2000
Function object { description, name, parameters, 3 more }
应用定义的函数。
description: string
说明函数的用途。
minLength: 0, maxLength: 1048576
name: string
函数名称。
minLength: 0, maxLength: 1048576
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean (default: false)
智能体是否无需等待函数结果即可继续。默认为 false。
defer_loading: optional boolean (default: false)
是否延迟加载函数并通过工具搜索发现。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
ProgrammaticToolCalling object { type, enabled }
允许模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
enabled: optional boolean (default: true)
是否允许从模型生成的代码调用工具。默认为 true。
Mcp object { server_label, transport, type, 5 more }
未配置已存储凭证的远程 MCP 服务器提供的工具。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0, maxLength: 1048576
transport: PersistedMcpTransportParam
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { server_url, type, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
headers: optional map[string] or null
发送给 MCP 服务器的非机密 HTTP 请求头。
Stdio object { command, cwd, type, 2 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
allowed_tools: optional array of string or null
智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。
minItems: 0, maxItems: 16384
connection_origin: optional "service" or "environment" or null
选择出站 MCP HTTP 连接的来源。
"service"
使用 Managed Agents 服务网络。
"environment"
使用会话的执行环境。
credential_id: optional string or null
为此 MCP 服务器选择的凭证库凭证。如果只有一条已附加凭证与服务器 URL 匹配,则可省略。
minLength: 0, maxLength: 1048576
request_metadata: optional map[unknown] or null
随请求发送给此 MCP 服务器的元数据。
required: optional boolean (default: false)
是否必须在第一轮前初始化此 MCP 服务器。默认为 false。
WebSearch object { type, allowed_domains, context_size, 2 more }
网页搜索。
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
allowed_domains: optional array of string or null
可纳入搜索范围的域名。
minItems: 0, maxItems: 16384
context_size: optional "low" or "medium" or "high" or null
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置。
city: optional string or null
城市名称。
minLength: 0, maxLength: 1048576
country: optional string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0, maxLength: 1048576
region: optional string or null
地区或州的名称。
minLength: 0, maxLength: 1048576
timezone: optional string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0, maxLength: 1048576
mode: optional "disabled" or "cached" or "live" or null
网页搜索结果的来源,默认为 live。
"disabled"
关闭网页搜索。
"cached"
使用缓存的搜索结果。
"live"
搜索实时网页。
ComputerUse object { type, include_screenshots }
在 OpenAI 托管会话中使用浏览器。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
include_screenshots: optional boolean (default: false)
计算机工具的输出是否包含屏幕截图。默认为 false。
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
返回值
Agent object { id, created_at, instructions, 12 more }
属于调用方项目的可复用智能体。
id: string
可复用智能体的 ID。
minLength: 0
created_at: integer
创建智能体时的 Unix 时间戳,单位为秒。
format: int64
instructions: string or null
附加到智能体默认基础指令之后的自定义指令。
minLength: 0
metadata: map[string]
附加到智能体的自定义字符串键值对。
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
object: "agent" (default: "agent")
对象类型,恒为 agent。
"agent"
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"
"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 PersistedAgentTool
智能体可用的工具。
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
智能体是否无需等待函数结果即可继续。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
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 工具。允许服务器上的全部工具时为 null。
minItems: 0, maxItems: 2000
connection_origin: "service" or "environment"
出站 MCP HTTP 连接的来源。
"service"
"environment"
credential_id: string or null
为此 MCP 服务器选择的凭证库凭证(如有)。
minLength: 0
request_metadata: map[unknown]
随请求发送给此 MCP 服务器的元数据。
required: boolean
是否必须在第一轮前初始化此 MCP 服务器。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0
transport: PersistedMcpTransport
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { headers, server_url, type }
通过 HTTP 连接到 MCP 服务器。
headers: map[string]
发送给 MCP 服务器的非机密 HTTP 请求头。
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"
updated_at: integer
上次更新智能体时的 Unix 时间戳,单位为秒。
format: int64
compaction: optional object { async }
当前生效的上下文压缩配置。
async: boolean
是否在后台压缩上下文。默认为 false。
experimental: optional object { time_awareness }
当前生效的实验性设置。
time_awareness: boolean
模型是否会定期收到当前时间提醒。
示例
## 从环境变量读取 API 密钥。
## 将 AGENT_ID 设置为要操作的智能体 ID。
curl https://api.openai.com/v1/agents/$AGENT_ID \
-X POST \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"instructions": "instructions",
"metadata": {
"foo": "string"
},
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"name": "name",
"object": "agent",
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"updated_at": 0,
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
}
示例
## 从环境变量读取 API 密钥。
## 将 AGENT_ID 设置为要操作的智能体 ID。
## Renamed 是示例名称,可改为所需名称。
## 1. 省略 reasoning,重命名时保留当前推理设置。
curl "https://api.openai.com/v1/agents/$AGENT_ID" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: agents=v1" \
-d '{"name": "Renamed"}'
## 2. 传入 null,恢复模型的默认推理设置。
curl "https://api.openai.com/v1/agents/$AGENT_ID" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: agents=v1" \
-d '{"reasoning": null}'
## 3. 传入对象,整体替换推理配置。
## 智能体使用的模型必须支持 low 推理强度。
curl "https://api.openai.com/v1/agents/$AGENT_ID" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: agents=v1" \
-d '{"reasoning": {"effort": "low"}}'
资源类型
Agent
Agent object { id, created_at, instructions, 12 more }
属于调用方项目的可复用智能体。
id: string
可复用智能体的 ID。
minLength: 0
created_at: integer
创建智能体时的 Unix 时间戳,单位为秒。
format: int64
instructions: string or null
附加到智能体默认基础指令之后的自定义指令。
minLength: 0
metadata: map[string]
附加到智能体的自定义字符串键值对。
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
object: "agent" (default: "agent")
对象类型,恒为 agent。
"agent"
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"
"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 PersistedAgentTool
智能体可用的工具。
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
智能体是否无需等待函数结果即可继续。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
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 工具。允许服务器上的全部工具时为 null。
minItems: 0, maxItems: 2000
connection_origin: "service" or "environment"
出站 MCP HTTP 连接的来源。
"service"
"environment"
credential_id: string or null
为此 MCP 服务器选择的凭证库凭证(如有)。
minLength: 0
request_metadata: map[unknown]
随请求发送给此 MCP 服务器的元数据。
required: boolean
是否必须在第一轮前初始化此 MCP 服务器。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0
transport: PersistedMcpTransport
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { headers, server_url, type }
通过 HTTP 连接到 MCP 服务器。
headers: map[string]
发送给 MCP 服务器的非机密 HTTP 请求头。
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"
updated_at: integer
上次更新智能体时的 Unix 时间戳,单位为秒。
format: int64
compaction: optional object { async }
当前生效的上下文压缩配置。
async: boolean
是否在后台压缩上下文。默认为 false。
experimental: optional object { time_awareness }
当前生效的实验性设置。
time_awareness: boolean
模型是否会定期收到当前时间提醒。
Agent Browser Authentication Cancel Param
AgentBrowserAuthenticationCancelParam object { action, type }
action: "cancel" (default: "cancel")
"cancel"
type: "browser_authentication" (default: "browser_authentication")
"browser_authentication"
Agent Browser Authentication Submit Param
AgentBrowserAuthenticationSubmitParam object { action, fields, type, selected_option }
action: "submit" (default: "submit")
"submit"
fields: array of object { field_id, value }
最多为必需操作中的 6 个活动字段提供值。提交的字段值映射与选定选项合计不得超过 120 KiB 的 JSON。
minItems: 0, maxItems: 6
field_id: string
必需操作提供的字段 ID。
minLength: 0, maxLength: 1048576
value: string
要填入已注册控件的值。
minLength: 0, maxLength: 16384
type: "browser_authentication" (default: "browser_authentication")
"browser_authentication"
selected_option: optional string or null
选中的方式。必需操作包含可选方式时,此项必填。
minLength: 0, maxLength: 1048576
Agent Browser Origin Access Param
AgentBrowserOriginAccessParam object { decision, type }
decision: "approve" or "deny" or "cancel"
允许、拒绝或取消所请求的源站访问。
"approve"
允许浏览器访问此源站。
"deny"
拒绝访问此源站。
"cancel"
关闭此请求,访问保持未获批准。
type: "browser_origin_access" (default: "browser_origin_access")
"browser_origin_access"
Agent Close Subagent Call Item
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
工具调用的状态。
"in_progress"
调用正在进行。
"completed"
调用已成功完成。
"failed"
调用失败。
"incomplete"
调用在完成前已停止。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "close_subagent_call" (default: "close_subagent_call")
条目类型,固定为 close_subagent_call。
"close_subagent_call"
Agent Command Execution Item
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
命令执行的状态。
"in_progress"
调用正在进行。
"completed"
调用已成功完成。
"failed"
调用失败。
"incomplete"
调用在完成前已停止。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "command_execution" (default: "command_execution")
条目类型,固定为 command_execution。
"command_execution"
Agent Content
AgentContent = OutputText or EncryptedContent { encrypted_content, type }
智能体之间交换的明文或加密内容部分。
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"
Agent Create Subagent Call Item
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。
"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
工具调用的状态。
"in_progress"
调用正在进行。
"completed"
调用已成功完成。
"failed"
调用失败。
"incomplete"
调用在完成前已停止。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "create_subagent_call" (default: "create_subagent_call")
条目类型,固定为 create_subagent_call。
"create_subagent_call"
Agent Deleted
AgentDeleted object { id, deleted, object }
已删除的可复用智能体。
id: string
已删除智能体的 ID。
minLength: 0
deleted: boolean
智能体是否已删除。恒为 true。
object: "agent.deleted" (default: "agent.deleted")
对象类型,恒为 agent.deleted。
"agent.deleted"
Agent Function Call Item
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"
Agent Function Call Output
AgentFunctionCallOutput = string or array of InputContent
作为函数结果提供的文本或模型输入内容。
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"
Agent Function Call Output Param
AgentFunctionCallOutputParam = string or array of InputContentParam
以文本或受支持的模型输入内容表示的函数结果。
string
minLength: 0, maxLength: 1048576
array of InputContentParam
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
text: string
发送给模型的文本。
minLength: 0, maxLength: 1048576
type: "input_text" (default: "input_text")
对象类型,固定为 input_text。
"input_text"
InputImage object { image_url, type }
提供给模型的图像输入。
image_url: string
发送给模型的图像 URL。
minLength: 0, maxLength: 1048576
type: "input_image" (default: "input_image")
对象类型,固定为 input_image。
"input_image"
Agent Function Call Status
AgentFunctionCallStatus = "in_progress" or "completed" or "failed" or "incomplete"
工具调用的状态。
"in_progress"
调用正在进行。
"completed"
调用已成功完成。
"failed"
调用失败。
"incomplete"
调用在完成前已停止。
Agent Interrupt Subagent Call Item
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
工具调用的状态。
"in_progress"
调用正在进行。
"completed"
调用已成功完成。
"failed"
调用失败。
"incomplete"
调用在完成前已停止。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "interrupt_subagent_call" (default: "interrupt_subagent_call")
条目类型,固定为 interrupt_subagent_call。
"interrupt_subagent_call"
Agent Mcp Call Item
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 工具调用的状态。
"in_progress"
调用正在进行。
"completed"
调用已成功完成。
"failed"
调用失败。
"incomplete"
调用在完成前已停止。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "mcp_call" (default: "mcp_call")
条目类型,固定为 mcp_call。
"mcp_call"
Agent Output Command Execution Output Delta Event
AgentOutputCommandExecutionOutputDeltaEvent object { delta, event_id, item_id, 5 more }
命令执行产生新增输出时发出。
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
Agent Output Item
AgentOutputItem = AgentSessionAssistantMessage or AgentReasoningItem or AgentFunctionCallItem or 11 more
智能体生成的输出条目。
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"
Agent Output Item Status
AgentOutputItemStatus = "in_progress" or "completed" or "incomplete"
智能体输出条目的状态。
"in_progress"
条目正在处理。
"completed"
条目处理已完成。
"incomplete"
条目在完成前已停止。
Agent Reasoning
AgentReasoning object { effort, summary }
智能体使用的推理配置。
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"
自动选择模型支持的最详细摘要。
Agent Reasoning Item
AgentReasoningItem object { id, status, summary, 2 more }
智能体生成的推理条目。
id: string
推理条目的 ID。
minLength: 0
status: AgentOutputItemStatus or null
推理条目的状态。
"in_progress"
条目正在处理。
"completed"
条目处理已完成。
"incomplete"
条目在完成前已停止。
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"
Agent Reasoning Param
AgentReasoningParam object { effort, summary }
智能体的推理配置。
effort: optional "none" or "minimal" or "low" or 4 more or null
模型使用的推理强度。省略时由模型选择。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: optional "concise" or "detailed" or "auto" or null
控制响应是否包含推理摘要。
"concise"
模型支持时,返回简明推理摘要。
"detailed"
模型支持时,返回详细推理摘要。
"auto"
自动选择模型支持的最详细摘要。
Agent Resume Subagent Call Item
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
工具调用的状态。
"in_progress"
调用正在进行。
"completed"
调用已成功完成。
"failed"
调用失败。
"incomplete"
调用在完成前已停止。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "resume_subagent_call" (default: "resume_subagent_call")
条目类型,固定为 resume_subagent_call。
"resume_subagent_call"
Agent Send Subagent Input Call Item
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 }
智能体生成的一段文本内容。
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
status: AgentFunctionCallStatus
工具调用的状态。
"in_progress"
调用正在进行。
"completed"
调用已成功完成。
"failed"
调用失败。
"incomplete"
调用在完成前已停止。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "send_subagent_input_call" (default: "send_subagent_input_call")
条目类型,固定为 send_subagent_input_call。
"send_subagent_input_call"
Agent Session
AgentSession object { id, agent, created_at, 11 more }
Managed Agents 会话。
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"
Agent Session Assistant Message
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"
Agent Session Created Event
AgentSessionCreatedEvent object { event_id, session, type, obfuscation }
创建会话时发出。
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
Agent Session Deleted
AgentSessionDeleted object { id, deleted, object }
已从公开 API 中移除的 Managed Agents 会话。底层资源清理可能仍在后台进行。
id: string
已删除会话的 ID。
minLength: 0
deleted: boolean
会话是否已从公开 API 中移除,恒为 true。底层资源可能仍在清理中。
object: "agent.session.deleted" (default: "agent.session.deleted")
对象类型,固定为 agent.session.deleted。
"agent.session.deleted"
Agent Session Environment Connected Event
AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 3 more }
会话环境连接时发出。
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
Agent Session Environment Disconnected Event
AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 3 more }
会话环境断开连接时发出。
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
Agent Session Environment Expired Event
AgentSessionEnvironmentExpiredEvent object { environment, event_id, session_id, 3 more }
已挂起的托管会话环境及其检查点过期后发出。
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
Agent Session Environment Failed Event
AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 3 more }
会话环境发生故障时发出。
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
Agent Session Environment Pending Event
AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 3 more }
准备会话环境时发出。
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
Agent Session Environment Ready Event
AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 3 more }
托管会话环境可以连接时发出。
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
Agent Session Environment Reset Event
AgentSessionEnvironmentResetEvent object { environment_id, event_id, reset_count, 4 more }
托管沙箱被替换后发出。对话历史保留,旧沙箱中的文件改动和进程不会延续到新沙箱。
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
Agent Session Environment State
AgentSessionEnvironmentState object { id, error, status, type }
会话环境的当前状态。
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
Agent Session Environment Suspended Event
AgentSessionEnvironmentSuspendedEvent object { environment, event_id, session_id, 3 more }
空闲的托管会话环境保存检查点并停止后发出。
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
Agent Session Error Event
AgentSessionErrorEvent object { error, event_id, session_id, 2 more }
轮次或会话失败时发出。
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
Agent Session Event
AgentSessionEvent = AgentSessionErrorEvent or AgentSessionEnvironmentReadyEvent or AgentSessionEnvironmentSuspendedEvent or 30 more
Managed Agents 会话发出的事件。
AgentSessionErrorEvent object { error, event_id, session_id, 2 more }
轮次或会话失败时发出。
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
AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 3 more }
托管会话环境可以连接时发出。
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
AgentSessionEnvironmentSuspendedEvent object { environment, event_id, session_id, 3 more }
空闲的托管会话环境保存检查点并停止后发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionEnvironmentExpiredEvent object { environment, event_id, session_id, 3 more }
已挂起的托管会话环境及其检查点过期后发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionEnvironmentResetEvent object { environment_id, event_id, reset_count, 4 more }
托管沙箱被替换后发出。对话历史保留,旧沙箱中的文件改动和进程不会延续到新沙箱。
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
AgentOutputCommandExecutionOutputDeltaEvent object { delta, event_id, item_id, 5 more }
命令执行产生新增输出时发出。
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
AgentSessionCreatedEvent object { event_id, session, type, obfuscation }
创建会话时发出。
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
AgentSessionTurnCreatedEvent object { event_id, session_id, turn, 3 more }
创建轮次时发出。
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,已记录的用量可能变化。
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
AgentSessionTurnInProgressEvent object { event_id, session_id, turn, 3 more }
轮次开始运行时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session_id: string
与事件关联的会话 ID。
minLength: 0
turn: Turn
轮次开始运行时的状态。
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
AgentSessionTurnCompletedEvent object { event_id, session_id, turn, 4 more }
轮次完成时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session_id: string
与事件关联的会话 ID。
minLength: 0
turn: Turn
已完成的轮次。
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
AgentSessionTurnFailedEvent object { event_id, session_id, turn, 4 more }
轮次失败时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session_id: string
与事件关联的会话 ID。
minLength: 0
turn: Turn
已失败的轮次。
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
AgentSessionTurnCancelledEvent object { event_id, session_id, turn, 4 more }
轮次取消时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session_id: string
与事件关联的会话 ID。
minLength: 0
turn: Turn
已取消的轮次。
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
AgentSessionTurnItemAddedEvent object { event_id, item, output_index, 4 more }
将条目添加到轮次时发出。
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
AgentSessionIdleEvent object { event_id, session, type, obfuscation }
会话进入空闲状态时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session: AgentSession
已进入空闲状态的会话。
type: "agent.session.idle" (default: "agent.session.idle")
对象类型,固定为 agent.session.idle。
"agent.session.idle"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionInProgressEvent object { event_id, session, type, obfuscation }
会话开始处理一轮交互时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session: AgentSession
已开始处理的会话。
type: "agent.session.in_progress" (default: "agent.session.in_progress")
对象类型,固定为 agent.session.in_progress。
"agent.session.in_progress"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionRequiresActionEvent object { event_id, session, type, obfuscation }
会话等待一个或多个必需操作时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session: AgentSession
会话及其当前必需操作。
type: "agent.session.requires_action" (default: "agent.session.requires_action")
对象类型,固定为 agent.session.requires_action。
"agent.session.requires_action"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionFailedEvent object { event_id, session, type, obfuscation }
会话失败时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session: AgentSession
已失败的会话。
type: "agent.session.failed" (default: "agent.session.failed")
对象类型,固定为 agent.session.failed。
"agent.session.failed"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 3 more }
准备会话环境时发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 3 more }
会话环境连接时发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 3 more }
会话环境断开连接时发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 3 more }
会话环境发生故障时发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionSubagentCreatedEvent object { event_id, subagent, type, obfuscation }
创建子智能体时发出。
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 }
智能体生成的一段文本内容。
EncryptedContent object { encrypted_content, type }
智能体之间交换的加密内容。
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
AgentSessionSubagentActiveEvent object { event_id, subagent, type, obfuscation }
已关闭的子智能体成功恢复时发出。
event_id: string
事件的唯一 ID。
minLength: 0
subagent: Subagent
已恢复的子智能体。
type: "agent.session.subagent.active" (default: "agent.session.subagent.active")
对象类型,固定为 agent.session.subagent.active。
"agent.session.subagent.active"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionSubagentClosedEvent object { event_id, subagent, type, obfuscation }
子智能体关闭时发出。
event_id: string
事件的唯一 ID。
minLength: 0
subagent: Subagent
已关闭的子智能体。
type: "agent.session.subagent.closed" (default: "agent.session.subagent.closed")
对象类型,固定为 agent.session.subagent.closed。
"agent.session.subagent.closed"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionTurnItemDoneEvent object { event_id, item, output_index, 4 more }
输出条目完成时发出。
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。
phase: "commentary" or "final_answer" or null
助手消息所处的阶段。
"commentary"
智能体工作时生成的过程说明。
"final_answer"
智能体的最终回答。
role: "assistant" (default: "assistant")
消息作者的角色,固定为 assistant。
"assistant"
status: AgentOutputItemStatus
消息的状态。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "message" (default: "message")
类型,固定为message。
"message"
AgentReasoningItem object { id, status, summary, 2 more }
智能体生成的推理条目。
AgentFunctionCallItem object { id, arguments, call_id, 4 more }
智能体生成的函数调用。
AgentMcpCallItem object { id, arguments, error, 6 more }
调用 MCP 服务器工具的记录。
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 }
智能体生成的网页搜索调用。
AgentCommandExecutionItem object { id, command, cwd, 6 more }
智能体生成的命令执行记录。
AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }
创建子智能体的请求。
AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }
向另一智能体发送输入的请求。
AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }
恢复子智能体的请求。
AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }
等待一个或多个子智能体的请求。
AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }
中断子智能体当前轮次的请求。该子智能体仍可使用。
AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }
关闭子智能体的请求。
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
AgentSessionTurnContentPartAddedEvent object { content_index, event_id, item_id, 6 more }
添加输出文本内容部分时发出。
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
初始内容部分。
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
AgentSessionTurnContentPartDoneEvent object { content_index, event_id, item_id, 6 more }
输出内容部分完成时发出。
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
已完成的内容部分。
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
AgentSessionTurnOutputTextDeltaEvent object { content_index, delta, event_id, 6 more }
向输出文本内容部分追加文本时发出。
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
AgentSessionTurnOutputTextDoneEvent object { content_index, event_id, item_id, 6 more }
输出文本内容部分完成时发出。
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
AgentSessionTurnReasoningSummaryPartAddedEvent object { event_id, item_id, output_index, 6 more }
添加推理摘要内容部分时发出。
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。
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
AgentSessionTurnReasoningSummaryPartDoneEvent object { event_id, item_id, output_index, 7 more }
推理摘要部分完成时发出。
event_id: string
事件的唯一 ID。
minLength: 0
item_id: string
推理条目的 ID。
minLength: 0
output_index: integer
条目在轮次输出中的索引。
format: int64, minimum: 0, maximum: 4294967295
part: SummaryText
已完成的摘要部分。
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
AgentSessionTurnReasoningSummaryTextDeltaEvent object { delta, event_id, item_id, 6 more }
向推理摘要追加文本时发出。
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
AgentSessionTurnReasoningSummaryTextDoneEvent object { event_id, item_id, output_index, 6 more }
推理摘要的内容部分完成时发出。
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
Agent Session Failed Event
AgentSessionFailedEvent object { event_id, session, type, obfuscation }
会话失败时发出。
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
Agent Session Idle Event
AgentSessionIdleEvent object { event_id, session, type, obfuscation }
会话进入空闲状态时发出。
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
Agent Session In Progress Event
AgentSessionInProgressEvent object { event_id, session, type, obfuscation }
会话开始处理一轮交互时发出。
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
Agent Session Input Message Param
AgentSessionInputMessageParam object { content, role, type }
提交到会话的用户消息。
content: array of InputContentParam
消息内容。
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
text: string
发送给模型的文本。
minLength: 0, maxLength: 1048576
type: "input_text" (default: "input_text")
对象类型,固定为 input_text。
"input_text"
InputImage object { image_url, type }
提供给模型的图像输入。
image_url: string
发送给模型的图像 URL。
minLength: 0, maxLength: 1048576
type: "input_image" (default: "input_image")
对象类型,固定为 input_image。
"input_image"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: optional "message" (default: "message")
输入条目类型,固定为 message。
"message"
Agent Session Input Param
AgentSessionInputParam = AgentSessionInputMcpApprovalRequestResult { request_id, response, type } or AgentSessionInputComputerUseApprovalRequestResult { request_id, response, type } or AgentSessionInputMessage { input, type } or 2 more
提交给现有会话的输入。
AgentSessionInputMcpApprovalRequestResult object { request_id, response, type }
响应待处理的 MCP 工具调用审批请求。
request_id: string
必需操作提供的不透明审批 ID。
minLength: 0, maxLength: 1048576
response: object { decision, type }
用户对待处理 MCP 工具调用的决定。
decision: "approve" or "deny" or "cancel"
取消此请求并关闭提示,会话和当前轮次仍然保留。
"approve"
"deny"
"cancel"
type: "mcp_tool_call" (default: "mcp_tool_call")
对象类型,固定为 mcp_tool_call。
"mcp_tool_call"
type: "agent.session.input.mcp_approval_request_result" (default: "agent.session.input.mcp_approval_request_result")
对象类型,固定为 agent.session.input.mcp_approval_request_result。
"agent.session.input.mcp_approval_request_result"
AgentSessionInputComputerUseApprovalRequestResult object { request_id, response, type }
响应待处理的计算机使用审批请求。
request_id: string
必需操作提供的已注册请求 ID。
minLength: 0, maxLength: 1048576
response: AgentBrowserAuthenticationSubmitParam or AgentBrowserAuthenticationCancelParam or AgentBrowserOriginAccessParam
此请求类型对应的响应。
AgentBrowserAuthenticationSubmitParam object { action, fields, type, selected_option }
action: "submit" (default: "submit")
"submit"
fields: array of object { field_id, value }
最多为必需操作中的 6 个活动字段提供值。提交的字段值映射与选定选项合计不得超过 120 KiB 的 JSON。
minItems: 0, maxItems: 6
field_id: string
必需操作提供的字段 ID。
minLength: 0, maxLength: 1048576
value: string
要填入已注册控件的值。
minLength: 0, maxLength: 16384
type: "browser_authentication" (default: "browser_authentication")
"browser_authentication"
selected_option: optional string or null
选中的方式。必需操作包含可选方式时,此项必填。
minLength: 0, maxLength: 1048576
AgentBrowserAuthenticationCancelParam object { action, type }
action: "cancel" (default: "cancel")
"cancel"
type: "browser_authentication" (default: "browser_authentication")
"browser_authentication"
AgentBrowserOriginAccessParam object { decision, type }
decision: "approve" or "deny" or "cancel"
允许、拒绝或取消所请求的源站访问。
"approve"
允许浏览器访问此源站。
"deny"
拒绝访问此源站。
"cancel"
关闭此请求,访问保持未获批准。
type: "browser_origin_access" (default: "browser_origin_access")
"browser_origin_access"
type: "agent.session.input.computer_use_approval_request_result" (default: "agent.session.input.computer_use_approval_request_result")
对象类型,固定为 agent.session.input.computer_use_approval_request_result。
"agent.session.input.computer_use_approval_request_result"
AgentSessionInputMessage object { input, type }
添加一条或多条用户消息并开始一轮交互。
input: array of AgentSessionInputMessageParam
要添加到会话的用户消息。
minItems: 0, maxItems: 16384
content: array of InputContentParam
消息内容。
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
text: string
发送给模型的文本。
minLength: 0, maxLength: 1048576
type: "input_text" (default: "input_text")
对象类型,固定为 input_text。
"input_text"
InputImage object { image_url, type }
提供给模型的图像输入。
image_url: string
发送给模型的图像 URL。
minLength: 0, maxLength: 1048576
type: "input_image" (default: "input_image")
对象类型,固定为 input_image。
"input_image"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: optional "message" (default: "message")
输入条目类型,固定为 message。
"message"
type: "agent.session.input.message" (default: "agent.session.input.message")
对象类型,固定为 agent.session.input.message。
"agent.session.input.message"
AgentSessionInputCancel object { type }
取消会话中正在进行的轮次。
type: "agent.session.input.cancel" (default: "agent.session.input.cancel")
对象类型,固定为 agent.session.input.cancel。
"agent.session.input.cancel"
AgentSessionInputToolResult object { call_id, success, turn_id, 3 more }
提交函数调用的结果。
call_id: string
函数调用 ID。
minLength: 0, maxLength: 1048576
success: boolean
函数调用是否成功。
turn_id: string
请求函数调用的轮次 ID。
minLength: 0, maxLength: 1048576
type: "agent.session.input.tool_result" (default: "agent.session.input.tool_result")
对象类型,固定为 agent.session.input.tool_result。
"agent.session.input.tool_result"
error: optional string or null
调用失败时返回的错误消息。
minLength: 0, maxLength: 1048576
output: optional AgentFunctionCallOutputParam or null
调用成功时返回的函数结果。
string
minLength: 0, maxLength: 1048576
array of InputContentParam
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
InputImage object { image_url, type }
提供给模型的图像输入。
Agent Session Item
AgentSessionItem = AgentSessionMessage or AgentReasoningItem or AgentFunctionCallItem or 14 more
与会话轮次关联的条目。
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"
Agent Session Message
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"
Agent Session Message Content
AgentSessionMessageContent = InputText { text, type } or InputImage { image_url, type } or OutputText { text, type }
会话消息中的一个内容部分。
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"
Agent Session Requires Action Event
AgentSessionRequiresActionEvent object { event_id, session, type, obfuscation }
会话等待一个或多个必需操作时发出。
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
Agent Session Subagent Active Event
AgentSessionSubagentActiveEvent object { event_id, subagent, type, obfuscation }
已关闭的子智能体成功恢复时发出。
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
Agent Session Subagent Closed Event
AgentSessionSubagentClosedEvent object { event_id, subagent, type, obfuscation }
子智能体关闭时发出。
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
Agent Session Subagent Created Event
AgentSessionSubagentCreatedEvent object { event_id, subagent, type, obfuscation }
创建子智能体时发出。
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
Agent Session Turn Cancelled Event
AgentSessionTurnCancelledEvent object { event_id, session_id, turn, 4 more }
轮次取消时发出。
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
Agent Session Turn Completed Event
AgentSessionTurnCompletedEvent object { event_id, session_id, turn, 4 more }
轮次完成时发出。
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
Agent Session Turn Content Part Added Event
AgentSessionTurnContentPartAddedEvent object { content_index, event_id, item_id, 6 more }
添加输出文本内容部分时发出。
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
Agent Session Turn Content Part Done Event
AgentSessionTurnContentPartDoneEvent object { content_index, event_id, item_id, 6 more }
输出内容部分完成时发出。
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
Agent Session Turn Created Event
AgentSessionTurnCreatedEvent object { event_id, session_id, turn, 3 more }
创建轮次时发出。
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
Agent Session Turn Failed Event
AgentSessionTurnFailedEvent object { event_id, session_id, turn, 4 more }
轮次失败时发出。
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
Agent Session Turn In Progress Event
AgentSessionTurnInProgressEvent object { event_id, session_id, turn, 3 more }
轮次开始运行时发出。
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
Agent Session Turn Item Added Event
AgentSessionTurnItemAddedEvent object { event_id, item, output_index, 4 more }
将条目添加到轮次时发出。
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
Agent Session Turn Item Done Event
AgentSessionTurnItemDoneEvent object { event_id, item, output_index, 4 more }
输出条目完成时发出。
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
Agent Session Turn Output Text Delta Event
AgentSessionTurnOutputTextDeltaEvent object { content_index, delta, event_id, 6 more }
向输出文本内容部分追加文本时发出。
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
Agent Session Turn Output Text Done Event
AgentSessionTurnOutputTextDoneEvent object { content_index, event_id, item_id, 6 more }
输出文本内容部分完成时发出。
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
Agent Session Turn Reasoning Summary Part Added Event
AgentSessionTurnReasoningSummaryPartAddedEvent object { event_id, item_id, output_index, 6 more }
添加推理摘要内容部分时发出。
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
Agent Session Turn Reasoning Summary Part Done Event
AgentSessionTurnReasoningSummaryPartDoneEvent object { event_id, item_id, output_index, 7 more }
推理摘要部分完成时发出。
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
Agent Session Turn Reasoning Summary Text Delta Event
AgentSessionTurnReasoningSummaryTextDeltaEvent object { delta, event_id, item_id, 6 more }
向推理摘要追加文本时发出。
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
Agent Session Turn Reasoning Summary Text Done Event
AgentSessionTurnReasoningSummaryTextDoneEvent object { event_id, item_id, output_index, 6 more }
推理摘要的内容部分完成时发出。
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
Agent Text
AgentText object { format, verbosity }
智能体使用的文本配置。
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"
Agent Text Param
AgentTextParam object { format, verbosity }
智能体生成文本的配置。
format: optional TextFormatParam or null
输出格式。省略时使用普通文本({"type": "text"})。
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: optional "low" or "medium" or "high" or null
模型应生成的文本量。与 Responses 一致,默认为 medium。
"low"
生成较少文本。
"medium"
使用默认文本量。
"high"
生成较多文本。
Agent Tool
AgentTool = Function { defer_loading, description, name, 3 more } or ProgrammaticToolCalling { enabled, type } or Mcp { allowed_tools, connection_origin, credential_id, 5 more } or 3 more
智能体可用的工具。
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"
Agent Tool Param
AgentToolParam = Function { description, name, parameters, 3 more } or ToolSearch { type } or ProgrammaticToolCalling { type, enabled } or 4 more
智能体可用的工具。
Function object { description, name, parameters, 3 more }
应用定义的函数。
description: string
说明函数的用途。
minLength: 0, maxLength: 1048576
name: string
函数名称。
minLength: 0, maxLength: 1048576
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean (default: false)
智能体是否无需等待函数结果即可继续。默认为 false。
defer_loading: optional boolean (default: false)
是否延迟加载函数并通过工具搜索发现。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
ProgrammaticToolCalling object { type, enabled }
允许模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
enabled: optional boolean (default: true)
是否允许从模型生成的代码调用工具。默认为 true。
Mcp object { server_label, transport, type, 5 more }
远程 MCP 服务器提供的工具。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0, maxLength: 1048576
transport: McpTransportParam
用于连接 MCP 服务器的传输方式。
HTTP object { server_url, type, authorization, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
authorization: optional string or null
发送给 MCP 服务器的授权值(如有)。
minLength: 0, maxLength: 1048576
headers: optional map[string] or null
发送给 MCP 服务器的附加 HTTP 请求头。
Stdio object { command, cwd, type, 3 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env: optional map[string] or null
为 MCP 服务器进程设置的环境变量。
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
allowed_tools: optional array of string or null
智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。
minItems: 0, maxItems: 16384
connection_origin: optional "service" or "environment" or null
选择出站 MCP HTTP 连接的来源。省略或设为 service 时使用 Managed Agents 服务网络,设为 environment 时使用会话选定的环境。
"service"
使用 Managed Agents 服务网络。
"environment"
使用会话的执行环境。
credential_id: optional string or null
用于验证此 MCP 服务器连接的已附加凭证库凭证。只有一条已附加凭证与服务器 URL 匹配时,可以省略。
minLength: 0, maxLength: 1048576
request_metadata: optional map[unknown] or null
随请求发送给此 MCP 服务器的元数据。
required: optional boolean (default: false)
是否必须在第一轮前初始化此 MCP 服务器。默认为 false。
WebSearch object { type, allowed_domains, context_size, 2 more }
网页搜索。
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
allowed_domains: optional array of string or null
可纳入搜索范围的域名。
minItems: 0, maxItems: 16384
context_size: optional "low" or "medium" or "high" or null
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置。
city: optional string or null
城市名称。
minLength: 0, maxLength: 1048576
country: optional string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0, maxLength: 1048576
region: optional string or null
地区或州的名称。
minLength: 0, maxLength: 1048576
timezone: optional string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0, maxLength: 1048576
mode: optional "disabled" or "cached" or "live" or null
网页搜索结果的来源,默认为 live。
"disabled"
关闭网页搜索。
"cached"
使用缓存的搜索结果。
"live"
搜索实时网页。
ComputerUse object { type, include_screenshots }
在 OpenAI 托管会话中使用浏览器。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
include_screenshots: optional boolean (default: false)
计算机工具的输出是否包含屏幕截图。默认为 false。
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
Agent Wait For Subagents Call Item
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
工具调用的状态。
"in_progress"
调用正在进行。
"completed"
调用已成功完成。
"failed"
调用失败。
"incomplete"
调用在完成前已停止。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "wait_for_subagents_call" (default: "wait_for_subagents_call")
条目类型,固定为 wait_for_subagents_call。
"wait_for_subagents_call"
Agent Web Search Call Item
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
网页搜索调用的状态。
"in_progress"
条目正在处理。
"completed"
条目处理已完成。
"incomplete"
条目在完成前已停止。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "web_search_call" (default: "web_search_call")
条目类型,固定为 web_search_call。
"web_search_call"
Environment
Environment = None { type } or OpenAIHosted { id, capability_directories, desktop, 7 more } or SelfHosted { id, capability_directories, remote_url, 2 more }
会话的执行环境。
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
Environment Param
EnvironmentParam = None { type } or OpenAIHosted { type, capability_directories, container_size, 10 more } or SelfHosted { type, workspace_directory, capability_directories }
会话的执行环境与可选的可复用模板。
None object { type }
在不配置执行环境的情况下运行智能体。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { type, capability_directories, container_size, 10 more }
现有的 OpenAI 托管环境,或通过内联配置或模板新建的托管环境。
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
container_size: optional "small" or "medium" or "large"
托管容器的规格。省略时选择中等规格。
"small"
"medium"
"large"
desktop: optional object { enabled } or null
桌面配置。省略或传入 null 时继承模板设置,无模板设置时默认禁用。
enabled: boolean
是否配置桌面及其浏览器代理。
env: optional map[string] or null
向智能体提供的环境变量。
environment_id: optional string
现有的预热环境。不能与模板或内联配置同时指定。
minLength: 9, maxLength: 256
environment_template_id: optional string
可复用的托管环境模板,在内联会话配置之前应用。省略的字段继承模板,网络覆盖配置只能保持或收紧模板的网络策略。
minLength: 0, maxLength: 64
files: optional array of HostedEnvironmentFileParam or null
智能体启动前可用的文件。默认为空列表。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: optional object { access, allowed_domains, blocked_domains } or null
环境的网络访问策略。省略时,由 API 版本决定是否启用网络访问。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: optional array of string or null
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 16384
blocked_domains: optional array of string or null
网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。
minItems: 0, maxItems: 100
packages: optional object { npm, python, system } or null
要安装到环境中的软件包。软件包列表默认为空。
npm: optional array of string or null
要全局安装的 npm 软件包。默认为空列表。
minItems: 0, maxItems: 16384
python: optional array of string or null
要安装的 Python 软件包。默认为空列表。
minItems: 0, maxItems: 16384
system: optional array of string or null
要安装的系统软件包。默认为空列表。
minItems: 0, maxItems: 16384
plugins: optional array of HostedPluginParam or null
以内联 ZIP 归档提供的插件。默认为空列表。
minItems: 0, maxItems: 32
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
setup_commands: optional array of SetupCommandParam or null
按顺序执行的机密初始化命令。响应始终省略命令正文。
minItems: 0, maxItems: 16
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
skills: optional array of HostedSkillParam or null
通过 ID 引用或以内联 ZIP 归档提供的技能。默认为空列表。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
SelfHosted object { type, workspace_directory, capability_directories }
以内联方式配置的应用托管环境。
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
自托管环境中的项目绝对路径。
minLength: 0, maxLength: 1048576
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
Hosted Environment File
HostedEnvironmentFile = HostedEnvironmentFileID or Inline { id, path, size_bytes, type }
写入 OpenAI 托管执行环境的文件元数据。
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"
Hosted Environment File ID
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"
Hosted Environment File Param
HostedEnvironmentFileParam = FileID { file_id, path, type } or Inline { data, path, type }
写入 OpenAI 托管执行环境的文件。
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
Hosted Plugin
HostedPlugin object { description, name, type }
从内联 ZIP 归档安装的插件。
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
Hosted Plugin Param
HostedPluginParam object { description, name, source, type }
在会话请求中直接提供插件 ZIP 文件。
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
Hosted Skill
HostedSkill = HostedSkillReference or Inline { description, name, type }
安装到 OpenAI 托管环境中的技能。
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"
Hosted Skill Param
HostedSkillParam = SkillReference { skill_id, type, version } or Inline { description, name, source, type }
安装到 OpenAI 托管环境中的技能。
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
Hosted Skill Reference
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 Capability Source Param
InlineCapabilitySourceParam object { data, media_type, type }
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
Input Content
InputContent = InputText { text, type } or InputImage { image_url, type }
会话条目中记录的用户提供内容。
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"
Input Content Param
InputContentParam = InputText { text, type } or InputImage { image_url, type }
输入消息包含的内容。
InputText object { text, type }
提供给模型的文本输入。
text: string
发送给模型的文本。
minLength: 0, maxLength: 1048576
type: "input_text" (default: "input_text")
对象类型,固定为 input_text。
"input_text"
InputImage object { image_url, type }
提供给模型的图像输入。
image_url: string
发送给模型的图像 URL。
minLength: 0, maxLength: 1048576
type: "input_image" (default: "input_image")
对象类型,固定为 input_image。
"input_image"
Mcp Transport
McpTransport = HTTP { server_url, type } or Stdio { args, command, cwd, 2 more }
用于连接 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"
Mcp Transport Param
McpTransportParam = HTTP { server_url, type, authorization, headers } or Stdio { command, cwd, type, 3 more }
用于连接 MCP 服务器的传输方式。
HTTP object { server_url, type, authorization, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
authorization: optional string or null
发送给 MCP 服务器的授权值(如有)。
minLength: 0, maxLength: 1048576
headers: optional map[string] or null
发送给 MCP 服务器的附加 HTTP 请求头。
Stdio object { command, cwd, type, 3 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env: optional map[string] or null
为 MCP 服务器进程设置的环境变量。
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
Multi Agent Config
MultiAgentConfig object { enabled, max_concurrent_subagents }
解析后用于创建和协调子智能体的配置。
enabled: boolean
是否启用子智能体工具。默认关闭。
max_concurrent_subagents: integer or null
可同时运行的子智能体数上限。禁用时为 null,启用时默认为 6。
format: int64, minimum: 1, maximum: 4294967295
Multi Agent Config Param
MultiAgentConfigParam object { enabled, max_concurrent_subagents }
创建和协调子智能体的显式配置。
enabled: boolean
是否启用子智能体工具。
max_concurrent_subagents: optional integer
可同时运行的子智能体数上限,默认为 6。
format: int64, minimum: 1, maximum: 4294967295
Output Text
OutputText object { text, type }
智能体生成的一段文本内容。
text: string
智能体生成的文本。
minLength: 0
type: "output_text" (default: "output_text")
内容类型,固定为 output_text。
"output_text"
Persisted Agent Tool
PersistedAgentTool = Function { defer_loading, description, name, 3 more } or ToolSearch { type } or ProgrammaticToolCalling { enabled, type } or 4 more
可由可复用智能体使用且无需凭证的工具。
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
智能体是否无需等待函数结果即可继续。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
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 工具。允许服务器上的全部工具时为 null。
minItems: 0, maxItems: 2000
connection_origin: "service" or "environment"
出站 MCP HTTP 连接的来源。
"service"
"environment"
credential_id: string or null
为此 MCP 服务器选择的凭证库凭证(如有)。
minLength: 0
request_metadata: map[unknown]
随请求发送给此 MCP 服务器的元数据。
required: boolean
是否必须在第一轮前初始化此 MCP 服务器。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0
transport: PersistedMcpTransport
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { headers, server_url, type }
通过 HTTP 连接到 MCP 服务器。
headers: map[string]
发送给 MCP 服务器的非机密 HTTP 请求头。
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"
Persisted Agent Tool Param
PersistedAgentToolParam = Function { description, name, parameters, 3 more } or ToolSearch { type } or ProgrammaticToolCalling { type, enabled } or 4 more
可保存到可复用智能体且无需会话凭证的工具。
Function object { description, name, parameters, 3 more }
应用定义的函数。
description: string
说明函数的用途。
minLength: 0, maxLength: 1048576
name: string
函数名称。
minLength: 0, maxLength: 1048576
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean (default: false)
智能体是否无需等待函数结果即可继续。默认为 false。
defer_loading: optional boolean (default: false)
是否延迟加载函数并通过工具搜索发现。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
ProgrammaticToolCalling object { type, enabled }
允许模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
enabled: optional boolean (default: true)
是否允许从模型生成的代码调用工具。默认为 true。
Mcp object { server_label, transport, type, 5 more }
未配置已存储凭证的远程 MCP 服务器提供的工具。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0, maxLength: 1048576
transport: PersistedMcpTransportParam
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { server_url, type, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
headers: optional map[string] or null
发送给 MCP 服务器的非机密 HTTP 请求头。
Stdio object { command, cwd, type, 2 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
allowed_tools: optional array of string or null
智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。
minItems: 0, maxItems: 16384
connection_origin: optional "service" or "environment" or null
选择出站 MCP HTTP 连接的来源。
"service"
使用 Managed Agents 服务网络。
"environment"
使用会话的执行环境。
credential_id: optional string or null
为此 MCP 服务器选择的凭证库凭证。如果只有一条已附加凭证与服务器 URL 匹配,则可省略。
minLength: 0, maxLength: 1048576
request_metadata: optional map[unknown] or null
随请求发送给此 MCP 服务器的元数据。
required: optional boolean (default: false)
是否必须在第一轮前初始化此 MCP 服务器。默认为 false。
WebSearch object { type, allowed_domains, context_size, 2 more }
网页搜索。
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
allowed_domains: optional array of string or null
可纳入搜索范围的域名。
minItems: 0, maxItems: 16384
context_size: optional "low" or "medium" or "high" or null
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置。
city: optional string or null
城市名称。
minLength: 0, maxLength: 1048576
country: optional string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0, maxLength: 1048576
region: optional string or null
地区或州的名称。
minLength: 0, maxLength: 1048576
timezone: optional string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0, maxLength: 1048576
mode: optional "disabled" or "cached" or "live" or null
网页搜索结果的来源,默认为 live。
"disabled"
关闭网页搜索。
"cached"
使用缓存的搜索结果。
"live"
搜索实时网页。
ComputerUse object { type, include_screenshots }
在 OpenAI 托管会话中使用浏览器。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
include_screenshots: optional boolean (default: false)
计算机工具的输出是否包含屏幕截图。默认为 false。
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
Persisted Mcp Transport
PersistedMcpTransport = HTTP { headers, server_url, type } or Stdio { args, command, cwd, 2 more }
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { headers, server_url, type }
通过 HTTP 连接到 MCP 服务器。
headers: map[string]
发送给 MCP 服务器的非机密 HTTP 请求头。
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"
Persisted Mcp Transport Param
PersistedMcpTransportParam = HTTP { server_url, type, headers } or Stdio { command, cwd, type, 2 more }
用于连接 MCP 服务器的无凭证传输方式。
HTTP object { server_url, type, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
headers: optional map[string] or null
发送给 MCP 服务器的非机密 HTTP 请求头。
Stdio object { command, cwd, type, 2 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
Session Error
SessionError object { code, message, param, type }
错误载荷,其公开字段与 Responses API 流式错误相同。
code: string or null
供程序识别的错误代码(如有)。
minLength: 0
message: string
可向客户显示的错误说明。
minLength: 0
param: string or null
与错误关联的请求参数(如有)。
minLength: 0
type: string
错误类型。
minLength: 0
Session Turn Error
SessionTurnError object { code, message }
可向客户显示的会话请求失败原因。
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
Setup Command Param
SetupCommandParam object { command, cwd }
托管智能体启动前执行的机密初始化命令。
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
Subagent
Subagent object { id, closed_at, instructions, 6 more }
在会话中创建的子智能体。
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"
子智能体已关闭。
Summary Text
SummaryText object { text, type }
推理摘要的内容部分。
text: string
推理摘要文本。
minLength: 0
type: "summary_text" (default: "summary_text")
内容类型,固定为 summary_text。
"summary_text"
Text Format
TextFormat = Text { type } or JSONSchema { schema, type }
生成文本实际采用的输出格式。
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"
Text Format Param
TextFormatParam = Text { type } or JSONSchema { schema, type }
生成文本的输出格式。
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"
Token Usage
TokenUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }
会话或轮次已记录的词元用量。统计按实际可取得的数据计算,可能变化。
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
Web Search Action
WebSearchAction = Search { queries, query, type } or OpenPage { type, url } or FindInPage { pattern, type, url } or Other { type }
网页搜索工具执行的操作。
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"
自动化任务
创建自动化任务
post /agents/automations
将自动化任务保存为活动状态,留待后续调用。
请求体参数
内容类型为 application/json。
create_automation_params: AutomationScheduleParam
创建自动化任务,留待后续调用。
Periodic object { expression, name, target, 3 more }
expression: string
定义计划触发时间的标准五字段 cron 表达式。
minLength: 1, maxLength: 256
name: string
自动化任务的可读名称。
minLength: 1, maxLength: 256
target: AutomationTargetParam
自动化调用的目标会话。
NewSession object { environment, input, type, 4 more }
每次调用均创建一个会话。
environment: EnvironmentParam
每个新会话的执行环境。
None object { type }
在不配置执行环境的情况下运行智能体。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { type, capability_directories, container_size, 10 more }
现有的 OpenAI 托管环境,或通过内联配置或模板新建的托管环境。
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
container_size: optional "small" or "medium" or "large"
托管容器的规格。省略时选择中等规格。
"small"
"medium"
"large"
desktop: optional object { enabled } or null
桌面配置。省略或传入 null 时继承模板设置,无模板设置时默认禁用。
enabled: boolean
是否配置桌面及其浏览器代理。
env: optional map[string] or null
向智能体提供的环境变量。
environment_id: optional string
现有的预热环境。不能与模板或内联配置同时指定。
minLength: 9, maxLength: 256
environment_template_id: optional string
可复用的托管环境模板,在内联会话配置之前应用。省略的字段继承模板,网络覆盖配置只能保持或收紧模板的网络策略。
minLength: 0, maxLength: 64
files: optional array of HostedEnvironmentFileParam or null
智能体启动前可用的文件。默认为空列表。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: optional object { access, allowed_domains, blocked_domains } or null
环境的网络访问策略。省略时,由 API 版本决定是否启用网络访问。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: optional array of string or null
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 16384
blocked_domains: optional array of string or null
网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。
minItems: 0, maxItems: 100
packages: optional object { npm, python, system } or null
要安装到环境中的软件包。软件包列表默认为空。
npm: optional array of string or null
要全局安装的 npm 软件包。默认为空列表。
minItems: 0, maxItems: 16384
python: optional array of string or null
要安装的 Python 软件包。默认为空列表。
minItems: 0, maxItems: 16384
system: optional array of string or null
要安装的系统软件包。默认为空列表。
minItems: 0, maxItems: 16384
plugins: optional array of HostedPluginParam or null
以内联 ZIP 归档提供的插件。默认为空列表。
minItems: 0, maxItems: 32
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
setup_commands: optional array of SetupCommandParam or null
按顺序执行的机密初始化命令。响应始终省略命令正文。
minItems: 0, maxItems: 16
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
skills: optional array of HostedSkillParam or null
通过 ID 引用或以内联 ZIP 归档提供的技能。默认为空列表。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
SelfHosted object { type, workspace_directory, capability_directories }
以内联方式配置的应用托管环境。
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
自托管环境中的项目绝对路径。
minLength: 0, maxLength: 1048576
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
input: array of AgentSessionInputMessageParam
提交给每个新会话的初始用户消息。
minItems: 0, maxItems: 16384
content: array of InputContentParam
消息内容。
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
text: string
发送给模型的文本。
minLength: 0, maxLength: 1048576
type: "input_text" (default: "input_text")
对象类型,固定为 input_text。
"input_text"
InputImage object { image_url, type }
提供给模型的图像输入。
image_url: string
发送给模型的图像 URL。
minLength: 0, maxLength: 1048576
type: "input_image" (default: "input_image")
对象类型,固定为 input_image。
"input_image"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: optional "message" (default: "message")
输入条目类型,固定为 message。
"message"
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
agent: optional object { compaction, experimental, instructions, 6 more }
内联智能体配置。agent 和 agent_id 必须且只能提供一个。
compaction: optional object { async } or null
上下文压缩配置。省略时保留现有设置,传入对象时替换现有设置,传 null 或空对象时采用阻塞式压缩。
async: optional boolean or null
是否在后台压缩上下文。省略或传 null 时默认为 false。设为 true 可启用后台压缩。后台压缩可能增加词元用量。
experimental: optional object { time_awareness } (default: {})
按键合并的实验性设置。省略的设置保留现有值。
time_awareness: optional boolean
模型是否会定期收到当前时间提醒。省略时保留现有设置。
instructions: optional string or null
附加到智能体默认基础指令之后的自定义指令。省略时保留原值。
minLength: 0, maxLength: 1048576
model: optional string
智能体使用的模型。系统保留请求中的模型名称。
minLength: 0, maxLength: 1048576
multi_agent: optional MultiAgentConfigParam or null
创建和协调子智能体的配置。
enabled: boolean
是否启用子智能体工具。
max_concurrent_subagents: optional integer
可同时运行的子智能体数上限,默认为 6。
format: int64, minimum: 1, maximum: 4294967295
reasoning: optional AgentReasoningParam or null
模型推理配置。省略时保留现有设置,传 null 时恢复模型的默认推理强度。
effort: optional "none" or "minimal" or "low" or 4 more or null
模型使用的推理强度。省略时由模型选择。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: optional "concise" or "detailed" or "auto" or null
控制响应是否包含推理摘要。
"concise"
模型支持时,返回简明推理摘要。
"detailed"
模型支持时,返回详细推理摘要。
"auto"
自动选择模型支持的最详细摘要。
service_tier: optional "auto" or "default" or "flex" or 3 more or null
用于模型请求的服务层级。
"auto"
自动选择服务层级。
"default"
使用默认服务层级。
"flex"
使用 Flex 服务层级。
"priority"
使用 Priority 服务层级。
"fast"
使用 Fast 服务层级。
"ultrafast"
使用 Ultrafast 服务层级。
text: optional AgentTextParam or null
智能体生成文本的配置。
format: optional TextFormatParam or null
输出格式。省略时使用普通文本({"type": "text"})。
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: optional "low" or "medium" or "high" or null
模型应生成的文本量。与 Responses 一致,默认为 medium。
"low"
生成较少文本。
"medium"
使用默认文本量。
"high"
生成较多文本。
tools: optional array of AgentToolParam or null
智能体可用的工具。省略时继承,传入 null 时清除。最终工具列表采用紧凑 UTF-8 JSON 编码时,大小不得超过 3 MiB(3,145,728 字节)。
minItems: 0, maxItems: 16384
Function object { description, name, parameters, 3 more }
应用定义的函数。
description: string
说明函数的用途。
minLength: 0, maxLength: 1048576
name: string
函数名称。
minLength: 0, maxLength: 1048576
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean (default: false)
智能体是否无需等待函数结果即可继续。默认为 false。
defer_loading: optional boolean (default: false)
是否延迟加载函数并通过工具搜索发现。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
ProgrammaticToolCalling object { type, enabled }
允许模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
enabled: optional boolean (default: true)
是否允许从模型生成的代码调用工具。默认为 true。
Mcp object { server_label, transport, type, 5 more }
远程 MCP 服务器提供的工具。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0, maxLength: 1048576
transport: McpTransportParam
用于连接 MCP 服务器的传输方式。
HTTP object { server_url, type, authorization, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
authorization: optional string or null
发送给 MCP 服务器的授权值(如有)。
minLength: 0, maxLength: 1048576
headers: optional map[string] or null
发送给 MCP 服务器的附加 HTTP 请求头。
Stdio object { command, cwd, type, 3 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env: optional map[string] or null
为 MCP 服务器进程设置的环境变量。
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
allowed_tools: optional array of string or null
智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。
minItems: 0, maxItems: 16384
connection_origin: optional "service" or "environment" or null
选择出站 MCP HTTP 连接的来源。省略或设为 service 时使用 Managed Agents 服务网络,设为 environment 时使用会话选定的环境。
"service"
使用 Managed Agents 服务网络。
"environment"
使用会话的执行环境。
credential_id: optional string or null
用于验证此 MCP 服务器连接的已附加凭证库凭证。只有一条已附加凭证与服务器 URL 匹配时,可以省略。
minLength: 0, maxLength: 1048576
request_metadata: optional map[unknown] or null
随请求发送给此 MCP 服务器的元数据。
required: optional boolean (default: false)
是否必须在第一轮前初始化此 MCP 服务器。默认为 false。
WebSearch object { type, allowed_domains, context_size, 2 more }
网页搜索。
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
allowed_domains: optional array of string or null
可纳入搜索范围的域名。
minItems: 0, maxItems: 16384
context_size: optional "low" or "medium" or "high" or null
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置。
city: optional string or null
城市名称。
minLength: 0, maxLength: 1048576
country: optional string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0, maxLength: 1048576
region: optional string or null
地区或州的名称。
minLength: 0, maxLength: 1048576
timezone: optional string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0, maxLength: 1048576
mode: optional "disabled" or "cached" or "live" or null
网页搜索结果的来源,默认为 live。
"disabled"
关闭网页搜索。
"cached"
使用缓存的搜索结果。
"live"
搜索实时网页。
ComputerUse object { type, include_screenshots }
在 OpenAI 托管会话中使用浏览器。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
include_screenshots: optional boolean (default: false)
计算机工具的输出是否包含屏幕截图。默认为 false。
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
agent_id: optional string
已保存的智能体 ID。agent 和 agent_id 必须且只能提供一个。
minLength: 0, maxLength: 64
metadata: optional map[string] or null
附加到每个新会话的元数据。
vault_ids: optional array of string or null
每个新会话可访问的凭证库 ID。
minItems: 0, maxItems: 16384
ExistingSession object { instructions, session_id, type }
向现有会话投递指令。
instructions: string
以自动化通知形式投递的指令。
minLength: 0, maxLength: 1048576
session_id: string
接收每次调用的会话。
minLength: 0, maxLength: 1048576
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释 cron 表达式的 IANA 时区。
minLength: 1, maxLength: 128
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
metadata: optional map[string]
Once object { name, run_at, target, 2 more }
name: string
自动化任务的可读名称。
minLength: 1, maxLength: 256
run_at: integer
将来时间的 Unix 时间戳,单位为秒。
format: int64
target: AutomationTargetParam
自动化调用的目标会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
metadata: optional map[string]
返回值
Automation = PeriodicAutomation or OneTimeAutomation
已保存的自动化任务及其计划。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
示例
## 从环境变量读取 API 密钥。
## 原文使用占位值。将 expression 换成五字段 cron 表达式、timezone 换成 IANA 时区。
## 将 name 换成任务名称,将 input 中的 text 换成实际指令。
curl https://api.openai.com/v1/agents/automations \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"expression": "x",
"name": "x",
"target": {
"environment": {
"type": "none"
},
"input": [
{
"content": [
{
"text": "text",
"type": "input_text"
}
],
"role": "user"
}
],
"type": "new_session"
},
"timezone": "x",
"type": "periodic"
}'
201 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"created_by": {
"type": "developer"
},
"expression": "expression",
"metadata": {
"foo": "string"
},
"name": "name",
"object": "agent.automation",
"status": "active",
"target": {
"agent": {
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"agent_id": "agent_id",
"environment": {
"type": "none"
},
"input": [
{
"content": [
{
"text": "text",
"type": "input_text"
}
],
"role": "user",
"type": "message"
}
],
"metadata": {
"foo": "string"
},
"type": "new_session",
"vault_ids": [
"string"
]
},
"timezone": "timezone",
"type": "periodic",
"pause_reason": "target_session_failed"
}
删除自动化任务
delete /agents/automations/{automation_id}
删除自动化任务并阻止后续调用,目标会话保留。
路径参数
automation_id: string
minLength: 0, maxLength: 1048576
返回值
AutomationDeleted object { id, deleted, object }
id: string
已删除的自动化任务 ID。
minLength: 0
deleted: boolean
恒为 true。
object: "agent.automation.deleted" (default: "agent.automation.deleted")
固定为 agent.automation.deleted。
"agent.automation.deleted"
示例
## 从环境变量读取 API 密钥。
## 将 AUTOMATION_ID 设置为目标自动化任务的 ID。
curl https://api.openai.com/v1/agents/automations/$AUTOMATION_ID \
-X DELETE \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"deleted": true,
"object": "agent.automation.deleted"
}
列出自动化任务
get /agents/automations
列出项目拥有的自动化任务,可按目标会话筛选。
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
session_id: optional string
匹配以现有会话为目标的任务,包括智能体创建的自动化任务。
minLength: 0, maxLength: 1048576
返回值
data: array of Automation
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
curl https://api.openai.com/v1/agents/automations \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"created_at": 0,
"created_by": {
"type": "developer"
},
"expression": "expression",
"metadata": {
"foo": "string"
},
"name": "name",
"object": "agent.automation",
"status": "active",
"target": {
"agent": {
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"agent_id": "agent_id",
"environment": {
"type": "none"
},
"input": [
{
"content": [
{
"text": "text",
"type": "input_text"
}
],
"role": "user",
"type": "message"
}
],
"metadata": {
"foo": "string"
},
"type": "new_session",
"vault_ids": [
"string"
]
},
"timezone": "timezone",
"type": "periodic",
"pause_reason": "target_session_failed"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
暂停自动化任务
post /agents/automations/{automation_id}/pause
暂停今后的计划投递,已经运行的会话继续执行。
路径参数
automation_id: string
minLength: 0, maxLength: 1048576
返回值
Automation = PeriodicAutomation or OneTimeAutomation
已保存的自动化任务及其计划。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
示例
## 从环境变量读取 API 密钥。
## 将 AUTOMATION_ID 设置为目标自动化任务的 ID。
curl https://api.openai.com/v1/agents/automations/$AUTOMATION_ID/pause \
-X POST \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"created_by": {
"type": "developer"
},
"expression": "expression",
"metadata": {
"foo": "string"
},
"name": "name",
"object": "agent.automation",
"status": "active",
"target": {
"agent": {
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"agent_id": "agent_id",
"environment": {
"type": "none"
},
"input": [
{
"content": [
{
"text": "text",
"type": "input_text"
}
],
"role": "user",
"type": "message"
}
],
"metadata": {
"foo": "string"
},
"type": "new_session",
"vault_ids": [
"string"
]
},
"timezone": "timezone",
"type": "periodic",
"pause_reason": "target_session_failed"
}
恢复自动化任务
post /agents/automations/{automation_id}/resume
恢复计划投递。如果一次性自动化任务没有待处理的调用,需提供将来的 run_at。
路径参数
automation_id: string
minLength: 0, maxLength: 1048576
返回值
Automation = PeriodicAutomation or OneTimeAutomation
已保存的自动化任务及其计划。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
示例
## 从环境变量读取 API 密钥。
## 将 AUTOMATION_ID 设置为目标自动化任务的 ID。
curl https://api.openai.com/v1/agents/automations/$AUTOMATION_ID/resume \
-X POST \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"created_by": {
"type": "developer"
},
"expression": "expression",
"metadata": {
"foo": "string"
},
"name": "name",
"object": "agent.automation",
"status": "active",
"target": {
"agent": {
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"agent_id": "agent_id",
"environment": {
"type": "none"
},
"input": [
{
"content": [
{
"text": "text",
"type": "input_text"
}
],
"role": "user",
"type": "message"
}
],
"metadata": {
"foo": "string"
},
"type": "new_session",
"vault_ids": [
"string"
]
},
"timezone": "timezone",
"type": "periodic",
"pause_reason": "target_session_failed"
}
获取自动化任务
get /agents/automations/{automation_id}
获取项目拥有的自动化任务。
路径参数
automation_id: string
minLength: 0, maxLength: 1048576
返回值
Automation = PeriodicAutomation or OneTimeAutomation
已保存的自动化任务及其计划。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
示例
## 从环境变量读取 API 密钥。
## 将 AUTOMATION_ID 设置为目标自动化任务的 ID。
curl https://api.openai.com/v1/agents/automations/$AUTOMATION_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"created_by": {
"type": "developer"
},
"expression": "expression",
"metadata": {
"foo": "string"
},
"name": "name",
"object": "agent.automation",
"status": "active",
"target": {
"agent": {
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"agent_id": "agent_id",
"environment": {
"type": "none"
},
"input": [
{
"content": [
{
"text": "text",
"type": "input_text"
}
],
"role": "user",
"type": "message"
}
],
"metadata": {
"foo": "string"
},
"type": "new_session",
"vault_ids": [
"string"
]
},
"timezone": "timezone",
"type": "periodic",
"pause_reason": "target_session_failed"
}
更新自动化任务
post /agents/automations/{automation_id}
更新所提供的字段。提供 target 或 metadata 时,会整体替换该字段。
路径参数
automation_id: string
minLength: 0, maxLength: 1048576
请求体参数
内容类型为 application/json。
expression: optional string
仅周期性自动化任务接受此字段。
minLength: 1, maxLength: 256
metadata: optional map[string]
替换全部元数据。省略时保留原值。
name: optional string
minLength: 1, maxLength: 256
run_at: optional integer
将来时间的 Unix 时间戳,单位为秒。仅在尚未生成一次性计划调用时接受。
format: int64
target: optional AutomationTargetParam
整体替换目标,保留目标类型和已有的创建者会话。
NewSession object { environment, input, type, 4 more }
每次调用均创建一个会话。
environment: EnvironmentParam
每个新会话的执行环境。
None object { type }
在不配置执行环境的情况下运行智能体。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { type, capability_directories, container_size, 10 more }
现有的 OpenAI 托管环境,或通过内联配置或模板新建的托管环境。
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
container_size: optional "small" or "medium" or "large"
托管容器的规格。省略时选择中等规格。
"small"
"medium"
"large"
desktop: optional object { enabled } or null
桌面配置。省略或传入 null 时继承模板设置,无模板设置时默认禁用。
enabled: boolean
是否配置桌面及其浏览器代理。
env: optional map[string] or null
向智能体提供的环境变量。
environment_id: optional string
现有的预热环境。不能与模板或内联配置同时指定。
minLength: 9, maxLength: 256
environment_template_id: optional string
可复用的托管环境模板,在内联会话配置之前应用。省略的字段继承模板,网络覆盖配置只能保持或收紧模板的网络策略。
minLength: 0, maxLength: 64
files: optional array of HostedEnvironmentFileParam or null
智能体启动前可用的文件。默认为空列表。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: optional object { access, allowed_domains, blocked_domains } or null
环境的网络访问策略。省略时,由 API 版本决定是否启用网络访问。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: optional array of string or null
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 16384
blocked_domains: optional array of string or null
网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。
minItems: 0, maxItems: 100
packages: optional object { npm, python, system } or null
要安装到环境中的软件包。软件包列表默认为空。
npm: optional array of string or null
要全局安装的 npm 软件包。默认为空列表。
minItems: 0, maxItems: 16384
python: optional array of string or null
要安装的 Python 软件包。默认为空列表。
minItems: 0, maxItems: 16384
system: optional array of string or null
要安装的系统软件包。默认为空列表。
minItems: 0, maxItems: 16384
plugins: optional array of HostedPluginParam or null
以内联 ZIP 归档提供的插件。默认为空列表。
minItems: 0, maxItems: 32
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
setup_commands: optional array of SetupCommandParam or null
按顺序执行的机密初始化命令。响应始终省略命令正文。
minItems: 0, maxItems: 16
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
skills: optional array of HostedSkillParam or null
通过 ID 引用或以内联 ZIP 归档提供的技能。默认为空列表。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
SelfHosted object { type, workspace_directory, capability_directories }
以内联方式配置的应用托管环境。
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
自托管环境中的项目绝对路径。
minLength: 0, maxLength: 1048576
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
input: array of AgentSessionInputMessageParam
提交给每个新会话的初始用户消息。
minItems: 0, maxItems: 16384
content: array of InputContentParam
消息内容。
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
text: string
发送给模型的文本。
minLength: 0, maxLength: 1048576
type: "input_text" (default: "input_text")
对象类型,固定为 input_text。
"input_text"
InputImage object { image_url, type }
提供给模型的图像输入。
image_url: string
发送给模型的图像 URL。
minLength: 0, maxLength: 1048576
type: "input_image" (default: "input_image")
对象类型,固定为 input_image。
"input_image"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: optional "message" (default: "message")
输入条目类型,固定为 message。
"message"
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
agent: optional object { compaction, experimental, instructions, 6 more }
内联智能体配置。agent 和 agent_id 必须且只能提供一个。
compaction: optional object { async } or null
上下文压缩配置。省略时保留现有设置,传入对象时替换现有设置,传 null 或空对象时采用阻塞式压缩。
async: optional boolean or null
是否在后台压缩上下文。省略或传 null 时默认为 false。设为 true 可启用后台压缩。后台压缩可能增加词元用量。
experimental: optional object { time_awareness } (default: {})
按键合并的实验性设置。省略的设置保留现有值。
time_awareness: optional boolean
模型是否会定期收到当前时间提醒。省略时保留现有设置。
instructions: optional string or null
附加到智能体默认基础指令之后的自定义指令。省略时保留原值。
minLength: 0, maxLength: 1048576
model: optional string
智能体使用的模型。系统保留请求中的模型名称。
minLength: 0, maxLength: 1048576
multi_agent: optional MultiAgentConfigParam or null
创建和协调子智能体的配置。
enabled: boolean
是否启用子智能体工具。
max_concurrent_subagents: optional integer
可同时运行的子智能体数上限,默认为 6。
format: int64, minimum: 1, maximum: 4294967295
reasoning: optional AgentReasoningParam or null
模型推理配置。省略时保留现有设置,传 null 时恢复模型的默认推理强度。
effort: optional "none" or "minimal" or "low" or 4 more or null
模型使用的推理强度。省略时由模型选择。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: optional "concise" or "detailed" or "auto" or null
控制响应是否包含推理摘要。
"concise"
模型支持时,返回简明推理摘要。
"detailed"
模型支持时,返回详细推理摘要。
"auto"
自动选择模型支持的最详细摘要。
service_tier: optional "auto" or "default" or "flex" or 3 more or null
用于模型请求的服务层级。
"auto"
自动选择服务层级。
"default"
使用默认服务层级。
"flex"
使用 Flex 服务层级。
"priority"
使用 Priority 服务层级。
"fast"
使用 Fast 服务层级。
"ultrafast"
使用 Ultrafast 服务层级。
text: optional AgentTextParam or null
智能体生成文本的配置。
format: optional TextFormatParam or null
输出格式。省略时使用普通文本({"type": "text"})。
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: optional "low" or "medium" or "high" or null
模型应生成的文本量。与 Responses 一致,默认为 medium。
"low"
生成较少文本。
"medium"
使用默认文本量。
"high"
生成较多文本。
tools: optional array of AgentToolParam or null
智能体可用的工具。省略时继承,传入 null 时清除。最终工具列表采用紧凑 UTF-8 JSON 编码时,大小不得超过 3 MiB(3,145,728 字节)。
minItems: 0, maxItems: 16384
Function object { description, name, parameters, 3 more }
应用定义的函数。
description: string
说明函数的用途。
minLength: 0, maxLength: 1048576
name: string
函数名称。
minLength: 0, maxLength: 1048576
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean (default: false)
智能体是否无需等待函数结果即可继续。默认为 false。
defer_loading: optional boolean (default: false)
是否延迟加载函数并通过工具搜索发现。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
ProgrammaticToolCalling object { type, enabled }
允许模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
enabled: optional boolean (default: true)
是否允许从模型生成的代码调用工具。默认为 true。
Mcp object { server_label, transport, type, 5 more }
远程 MCP 服务器提供的工具。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0, maxLength: 1048576
transport: McpTransportParam
用于连接 MCP 服务器的传输方式。
HTTP object { server_url, type, authorization, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
authorization: optional string or null
发送给 MCP 服务器的授权值(如有)。
minLength: 0, maxLength: 1048576
headers: optional map[string] or null
发送给 MCP 服务器的附加 HTTP 请求头。
Stdio object { command, cwd, type, 3 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env: optional map[string] or null
为 MCP 服务器进程设置的环境变量。
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
allowed_tools: optional array of string or null
智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。
minItems: 0, maxItems: 16384
connection_origin: optional "service" or "environment" or null
选择出站 MCP HTTP 连接的来源。省略或设为 service 时使用 Managed Agents 服务网络,设为 environment 时使用会话选定的环境。
"service"
使用 Managed Agents 服务网络。
"environment"
使用会话的执行环境。
credential_id: optional string or null
用于验证此 MCP 服务器连接的已附加凭证库凭证。只有一条已附加凭证与服务器 URL 匹配时,可以省略。
minLength: 0, maxLength: 1048576
request_metadata: optional map[unknown] or null
随请求发送给此 MCP 服务器的元数据。
required: optional boolean (default: false)
是否必须在第一轮前初始化此 MCP 服务器。默认为 false。
WebSearch object { type, allowed_domains, context_size, 2 more }
网页搜索。
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
allowed_domains: optional array of string or null
可纳入搜索范围的域名。
minItems: 0, maxItems: 16384
context_size: optional "low" or "medium" or "high" or null
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置。
city: optional string or null
城市名称。
minLength: 0, maxLength: 1048576
country: optional string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0, maxLength: 1048576
region: optional string or null
地区或州的名称。
minLength: 0, maxLength: 1048576
timezone: optional string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0, maxLength: 1048576
mode: optional "disabled" or "cached" or "live" or null
网页搜索结果的来源,默认为 live。
"disabled"
关闭网页搜索。
"cached"
使用缓存的搜索结果。
"live"
搜索实时网页。
ComputerUse object { type, include_screenshots }
在 OpenAI 托管会话中使用浏览器。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
include_screenshots: optional boolean (default: false)
计算机工具的输出是否包含屏幕截图。默认为 false。
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
agent_id: optional string
已保存的智能体 ID。agent 和 agent_id 必须且只能提供一个。
minLength: 0, maxLength: 64
metadata: optional map[string] or null
附加到每个新会话的元数据。
vault_ids: optional array of string or null
每个新会话可访问的凭证库 ID。
minItems: 0, maxItems: 16384
ExistingSession object { instructions, session_id, type }
向现有会话投递指令。
instructions: string
以自动化通知形式投递的指令。
minLength: 0, maxLength: 1048576
session_id: string
接收每次调用的会话。
minLength: 0, maxLength: 1048576
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: optional string
仅周期性自动化任务接受此字段。
minLength: 1, maxLength: 128
返回值
Automation = PeriodicAutomation or OneTimeAutomation
已保存的自动化任务及其计划。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
示例
## 从环境变量读取 API 密钥。
## 将 AUTOMATION_ID 设置为目标自动化任务的 ID。
curl https://api.openai.com/v1/agents/automations/$AUTOMATION_ID \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{}'
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"created_by": {
"type": "developer"
},
"expression": "expression",
"metadata": {
"foo": "string"
},
"name": "name",
"object": "agent.automation",
"status": "active",
"target": {
"agent": {
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"agent_id": "agent_id",
"environment": {
"type": "none"
},
"input": [
{
"content": [
{
"text": "text",
"type": "input_text"
}
],
"role": "user",
"type": "message"
}
],
"metadata": {
"foo": "string"
},
"type": "new_session",
"vault_ids": [
"string"
]
},
"timezone": "timezone",
"type": "periodic",
"pause_reason": "target_session_failed"
}
资源类型
Automation
Automation = PeriodicAutomation or OneTimeAutomation
已保存的自动化任务及其计划。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
Automation Agent Config
AutomationAgentConfig object { instructions, model, multi_agent, 6 more }
内联智能体配置,不含生成的会话局部标识。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
Automation Created By
AutomationCreatedBy = Developer { type } or Agent { session_id, tool_call_id, type }
自动化任务的创建方式。一次调用如何启动由其他字段描述。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
Automation Deleted
AutomationDeleted object { id, deleted, object }
id: string
已删除的自动化任务 ID。
minLength: 0
deleted: boolean
恒为 true。
object: "agent.automation.deleted" (default: "agent.automation.deleted")
固定为 agent.automation.deleted。
"agent.automation.deleted"
Automation Environment
AutomationEnvironment = None { type } or OpenAIHosted { capability_directories, container_size, desktop, 8 more } or SelfHosted { capability_directories, environment_id, type, workspace_directory }
调用创建会话前保存的环境选择。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
Automation Schedule Param
AutomationScheduleParam = Periodic { expression, name, target, 3 more } or Once { name, run_at, target, 2 more }
创建自动化任务,留待后续调用。
Periodic object { expression, name, target, 3 more }
expression: string
定义计划触发时间的标准五字段 cron 表达式。
minLength: 1, maxLength: 256
name: string
自动化任务的可读名称。
minLength: 1, maxLength: 256
target: AutomationTargetParam
自动化调用的目标会话。
NewSession object { environment, input, type, 4 more }
每次调用均创建一个会话。
environment: EnvironmentParam
每个新会话的执行环境。
None object { type }
在不配置执行环境的情况下运行智能体。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { type, capability_directories, container_size, 10 more }
现有的 OpenAI 托管环境,或通过内联配置或模板新建的托管环境。
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
container_size: optional "small" or "medium" or "large"
托管容器的规格。省略时选择中等规格。
"small"
"medium"
"large"
desktop: optional object { enabled } or null
桌面配置。省略或传入 null 时继承模板设置,无模板设置时默认禁用。
enabled: boolean
是否配置桌面及其浏览器代理。
env: optional map[string] or null
向智能体提供的环境变量。
environment_id: optional string
现有的预热环境。不能与模板或内联配置同时指定。
minLength: 9, maxLength: 256
environment_template_id: optional string
可复用的托管环境模板,在内联会话配置之前应用。省略的字段继承模板,网络覆盖配置只能保持或收紧模板的网络策略。
minLength: 0, maxLength: 64
files: optional array of HostedEnvironmentFileParam or null
智能体启动前可用的文件。默认为空列表。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: optional object { access, allowed_domains, blocked_domains } or null
环境的网络访问策略。省略时,由 API 版本决定是否启用网络访问。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: optional array of string or null
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 16384
blocked_domains: optional array of string or null
网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。
minItems: 0, maxItems: 100
packages: optional object { npm, python, system } or null
要安装到环境中的软件包。软件包列表默认为空。
npm: optional array of string or null
要全局安装的 npm 软件包。默认为空列表。
minItems: 0, maxItems: 16384
python: optional array of string or null
要安装的 Python 软件包。默认为空列表。
minItems: 0, maxItems: 16384
system: optional array of string or null
要安装的系统软件包。默认为空列表。
minItems: 0, maxItems: 16384
plugins: optional array of HostedPluginParam or null
以内联 ZIP 归档提供的插件。默认为空列表。
minItems: 0, maxItems: 32
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
setup_commands: optional array of SetupCommandParam or null
按顺序执行的机密初始化命令。响应始终省略命令正文。
minItems: 0, maxItems: 16
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
skills: optional array of HostedSkillParam or null
通过 ID 引用或以内联 ZIP 归档提供的技能。默认为空列表。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
SelfHosted object { type, workspace_directory, capability_directories }
以内联方式配置的应用托管环境。
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
自托管环境中的项目绝对路径。
minLength: 0, maxLength: 1048576
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
input: array of AgentSessionInputMessageParam
提交给每个新会话的初始用户消息。
minItems: 0, maxItems: 16384
content: array of InputContentParam
消息内容。
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
text: string
发送给模型的文本。
minLength: 0, maxLength: 1048576
type: "input_text" (default: "input_text")
对象类型,固定为 input_text。
"input_text"
InputImage object { image_url, type }
提供给模型的图像输入。
image_url: string
发送给模型的图像 URL。
minLength: 0, maxLength: 1048576
type: "input_image" (default: "input_image")
对象类型,固定为 input_image。
"input_image"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: optional "message" (default: "message")
输入条目类型,固定为 message。
"message"
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
agent: optional object { compaction, experimental, instructions, 6 more }
内联智能体配置。agent 和 agent_id 必须且只能提供一个。
compaction: optional object { async } or null
上下文压缩配置。省略时保留现有设置,传入对象时替换现有设置,传 null 或空对象时采用阻塞式压缩。
async: optional boolean or null
是否在后台压缩上下文。省略或传 null 时默认为 false。设为 true 可启用后台压缩。后台压缩可能增加词元用量。
experimental: optional object { time_awareness } (default: {})
按键合并的实验性设置。省略的设置保留现有值。
time_awareness: optional boolean
模型是否会定期收到当前时间提醒。省略时保留现有设置。
instructions: optional string or null
附加到智能体默认基础指令之后的自定义指令。省略时保留原值。
minLength: 0, maxLength: 1048576
model: optional string
智能体使用的模型。系统保留请求中的模型名称。
minLength: 0, maxLength: 1048576
multi_agent: optional MultiAgentConfigParam or null
创建和协调子智能体的配置。
enabled: boolean
是否启用子智能体工具。
max_concurrent_subagents: optional integer
可同时运行的子智能体数上限,默认为 6。
format: int64, minimum: 1, maximum: 4294967295
reasoning: optional AgentReasoningParam or null
模型推理配置。省略时保留现有设置,传 null 时恢复模型的默认推理强度。
effort: optional "none" or "minimal" or "low" or 4 more or null
模型使用的推理强度。省略时由模型选择。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: optional "concise" or "detailed" or "auto" or null
控制响应是否包含推理摘要。
"concise"
模型支持时,返回简明推理摘要。
"detailed"
模型支持时,返回详细推理摘要。
"auto"
自动选择模型支持的最详细摘要。
service_tier: optional "auto" or "default" or "flex" or 3 more or null
用于模型请求的服务层级。
"auto"
自动选择服务层级。
"default"
使用默认服务层级。
"flex"
使用 Flex 服务层级。
"priority"
使用 Priority 服务层级。
"fast"
使用 Fast 服务层级。
"ultrafast"
使用 Ultrafast 服务层级。
text: optional AgentTextParam or null
智能体生成文本的配置。
format: optional TextFormatParam or null
输出格式。省略时使用普通文本({"type": "text"})。
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: optional "low" or "medium" or "high" or null
模型应生成的文本量。与 Responses 一致,默认为 medium。
"low"
生成较少文本。
"medium"
使用默认文本量。
"high"
生成较多文本。
tools: optional array of AgentToolParam or null
智能体可用的工具。省略时继承,传入 null 时清除。最终工具列表采用紧凑 UTF-8 JSON 编码时,大小不得超过 3 MiB(3,145,728 字节)。
minItems: 0, maxItems: 16384
Function object { description, name, parameters, 3 more }
应用定义的函数。
description: string
说明函数的用途。
minLength: 0, maxLength: 1048576
name: string
函数名称。
minLength: 0, maxLength: 1048576
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean (default: false)
智能体是否无需等待函数结果即可继续。默认为 false。
defer_loading: optional boolean (default: false)
是否延迟加载函数并通过工具搜索发现。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
ProgrammaticToolCalling object { type, enabled }
允许模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
enabled: optional boolean (default: true)
是否允许从模型生成的代码调用工具。默认为 true。
Mcp object { server_label, transport, type, 5 more }
远程 MCP 服务器提供的工具。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0, maxLength: 1048576
transport: McpTransportParam
用于连接 MCP 服务器的传输方式。
HTTP object { server_url, type, authorization, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
authorization: optional string or null
发送给 MCP 服务器的授权值(如有)。
minLength: 0, maxLength: 1048576
headers: optional map[string] or null
发送给 MCP 服务器的附加 HTTP 请求头。
Stdio object { command, cwd, type, 3 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env: optional map[string] or null
为 MCP 服务器进程设置的环境变量。
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
allowed_tools: optional array of string or null
智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。
minItems: 0, maxItems: 16384
connection_origin: optional "service" or "environment" or null
选择出站 MCP HTTP 连接的来源。省略或设为 service 时使用 Managed Agents 服务网络,设为 environment 时使用会话选定的环境。
"service"
使用 Managed Agents 服务网络。
"environment"
使用会话的执行环境。
credential_id: optional string or null
用于验证此 MCP 服务器连接的已附加凭证库凭证。只有一条已附加凭证与服务器 URL 匹配时,可以省略。
minLength: 0, maxLength: 1048576
request_metadata: optional map[unknown] or null
随请求发送给此 MCP 服务器的元数据。
required: optional boolean (default: false)
是否必须在第一轮前初始化此 MCP 服务器。默认为 false。
WebSearch object { type, allowed_domains, context_size, 2 more }
网页搜索。
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
allowed_domains: optional array of string or null
可纳入搜索范围的域名。
minItems: 0, maxItems: 16384
context_size: optional "low" or "medium" or "high" or null
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置。
city: optional string or null
城市名称。
minLength: 0, maxLength: 1048576
country: optional string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0, maxLength: 1048576
region: optional string or null
地区或州的名称。
minLength: 0, maxLength: 1048576
timezone: optional string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0, maxLength: 1048576
mode: optional "disabled" or "cached" or "live" or null
网页搜索结果的来源,默认为 live。
"disabled"
关闭网页搜索。
"cached"
使用缓存的搜索结果。
"live"
搜索实时网页。
ComputerUse object { type, include_screenshots }
在 OpenAI 托管会话中使用浏览器。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
include_screenshots: optional boolean (default: false)
计算机工具的输出是否包含屏幕截图。默认为 false。
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
agent_id: optional string
已保存的智能体 ID。agent 和 agent_id 必须且只能提供一个。
minLength: 0, maxLength: 64
metadata: optional map[string] or null
附加到每个新会话的元数据。
vault_ids: optional array of string or null
每个新会话可访问的凭证库 ID。
minItems: 0, maxItems: 16384
ExistingSession object { instructions, session_id, type }
向现有会话投递指令。
instructions: string
以自动化通知形式投递的指令。
minLength: 0, maxLength: 1048576
session_id: string
接收每次调用的会话。
minLength: 0, maxLength: 1048576
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释 cron 表达式的 IANA 时区。
minLength: 1, maxLength: 128
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
metadata: optional map[string]
Once object { name, run_at, target, 2 more }
name: string
自动化任务的可读名称。
minLength: 1, maxLength: 256
run_at: integer
将来时间的 Unix 时间戳,单位为秒。
format: int64
target: AutomationTargetParam
自动化调用的目标会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
metadata: optional map[string]
Automation Target
AutomationTarget = NewSession { agent, agent_id, environment, 4 more } or ExistingSession { instructions, session_id, type }
已保存的目标配置,省略仅在请求中传入的机密值。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
Automation Target Param
AutomationTargetParam = NewSession { environment, input, type, 4 more } or ExistingSession { instructions, session_id, type }
自动化调用的目标会话。
NewSession object { environment, input, type, 4 more }
每次调用均创建一个会话。
environment: EnvironmentParam
每个新会话的执行环境。
None object { type }
在不配置执行环境的情况下运行智能体。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { type, capability_directories, container_size, 10 more }
现有的 OpenAI 托管环境,或通过内联配置或模板新建的托管环境。
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
container_size: optional "small" or "medium" or "large"
托管容器的规格。省略时选择中等规格。
"small"
"medium"
"large"
desktop: optional object { enabled } or null
桌面配置。省略或传入 null 时继承模板设置,无模板设置时默认禁用。
enabled: boolean
是否配置桌面及其浏览器代理。
env: optional map[string] or null
向智能体提供的环境变量。
environment_id: optional string
现有的预热环境。不能与模板或内联配置同时指定。
minLength: 9, maxLength: 256
environment_template_id: optional string
可复用的托管环境模板,在内联会话配置之前应用。省略的字段继承模板,网络覆盖配置只能保持或收紧模板的网络策略。
minLength: 0, maxLength: 64
files: optional array of HostedEnvironmentFileParam or null
智能体启动前可用的文件。默认为空列表。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: optional object { access, allowed_domains, blocked_domains } or null
环境的网络访问策略。省略时,由 API 版本决定是否启用网络访问。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: optional array of string or null
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 16384
blocked_domains: optional array of string or null
网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。
minItems: 0, maxItems: 100
packages: optional object { npm, python, system } or null
要安装到环境中的软件包。软件包列表默认为空。
npm: optional array of string or null
要全局安装的 npm 软件包。默认为空列表。
minItems: 0, maxItems: 16384
python: optional array of string or null
要安装的 Python 软件包。默认为空列表。
minItems: 0, maxItems: 16384
system: optional array of string or null
要安装的系统软件包。默认为空列表。
minItems: 0, maxItems: 16384
plugins: optional array of HostedPluginParam or null
以内联 ZIP 归档提供的插件。默认为空列表。
minItems: 0, maxItems: 32
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
setup_commands: optional array of SetupCommandParam or null
按顺序执行的机密初始化命令。响应始终省略命令正文。
minItems: 0, maxItems: 16
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
skills: optional array of HostedSkillParam or null
通过 ID 引用或以内联 ZIP 归档提供的技能。默认为空列表。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
SelfHosted object { type, workspace_directory, capability_directories }
以内联方式配置的应用托管环境。
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
自托管环境中的项目绝对路径。
minLength: 0, maxLength: 1048576
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
input: array of AgentSessionInputMessageParam
提交给每个新会话的初始用户消息。
minItems: 0, maxItems: 16384
content: array of InputContentParam
消息内容。
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
text: string
发送给模型的文本。
minLength: 0, maxLength: 1048576
type: "input_text" (default: "input_text")
对象类型,固定为 input_text。
"input_text"
InputImage object { image_url, type }
提供给模型的图像输入。
image_url: string
发送给模型的图像 URL。
minLength: 0, maxLength: 1048576
type: "input_image" (default: "input_image")
对象类型,固定为 input_image。
"input_image"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: optional "message" (default: "message")
输入条目类型,固定为 message。
"message"
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
agent: optional object { compaction, experimental, instructions, 6 more }
内联智能体配置。agent 和 agent_id 必须且只能提供一个。
compaction: optional object { async } or null
上下文压缩配置。省略时保留现有设置,传入对象时替换现有设置,传 null 或空对象时采用阻塞式压缩。
async: optional boolean or null
是否在后台压缩上下文。省略或传 null 时默认为 false。设为 true 可启用后台压缩。后台压缩可能增加词元用量。
experimental: optional object { time_awareness } (default: {})
按键合并的实验性设置。省略的设置保留现有值。
time_awareness: optional boolean
模型是否会定期收到当前时间提醒。省略时保留现有设置。
instructions: optional string or null
附加到智能体默认基础指令之后的自定义指令。省略时保留原值。
minLength: 0, maxLength: 1048576
model: optional string
智能体使用的模型。系统保留请求中的模型名称。
minLength: 0, maxLength: 1048576
multi_agent: optional MultiAgentConfigParam or null
创建和协调子智能体的配置。
enabled: boolean
是否启用子智能体工具。
max_concurrent_subagents: optional integer
可同时运行的子智能体数上限,默认为 6。
format: int64, minimum: 1, maximum: 4294967295
reasoning: optional AgentReasoningParam or null
模型推理配置。省略时保留现有设置,传 null 时恢复模型的默认推理强度。
effort: optional "none" or "minimal" or "low" or 4 more or null
模型使用的推理强度。省略时由模型选择。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: optional "concise" or "detailed" or "auto" or null
控制响应是否包含推理摘要。
"concise"
模型支持时,返回简明推理摘要。
"detailed"
模型支持时,返回详细推理摘要。
"auto"
自动选择模型支持的最详细摘要。
service_tier: optional "auto" or "default" or "flex" or 3 more or null
用于模型请求的服务层级。
"auto"
自动选择服务层级。
"default"
使用默认服务层级。
"flex"
使用 Flex 服务层级。
"priority"
使用 Priority 服务层级。
"fast"
使用 Fast 服务层级。
"ultrafast"
使用 Ultrafast 服务层级。
text: optional AgentTextParam or null
智能体生成文本的配置。
format: optional TextFormatParam or null
输出格式。省略时使用普通文本({"type": "text"})。
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: optional "low" or "medium" or "high" or null
模型应生成的文本量。与 Responses 一致,默认为 medium。
"low"
生成较少文本。
"medium"
使用默认文本量。
"high"
生成较多文本。
tools: optional array of AgentToolParam or null
智能体可用的工具。省略时继承,传入 null 时清除。最终工具列表采用紧凑 UTF-8 JSON 编码时,大小不得超过 3 MiB(3,145,728 字节)。
minItems: 0, maxItems: 16384
Function object { description, name, parameters, 3 more }
应用定义的函数。
description: string
说明函数的用途。
minLength: 0, maxLength: 1048576
name: string
函数名称。
minLength: 0, maxLength: 1048576
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean (default: false)
智能体是否无需等待函数结果即可继续。默认为 false。
defer_loading: optional boolean (default: false)
是否延迟加载函数并通过工具搜索发现。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
ProgrammaticToolCalling object { type, enabled }
允许模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
enabled: optional boolean (default: true)
是否允许从模型生成的代码调用工具。默认为 true。
Mcp object { server_label, transport, type, 5 more }
远程 MCP 服务器提供的工具。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0, maxLength: 1048576
transport: McpTransportParam
用于连接 MCP 服务器的传输方式。
HTTP object { server_url, type, authorization, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
authorization: optional string or null
发送给 MCP 服务器的授权值(如有)。
minLength: 0, maxLength: 1048576
headers: optional map[string] or null
发送给 MCP 服务器的附加 HTTP 请求头。
Stdio object { command, cwd, type, 3 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env: optional map[string] or null
为 MCP 服务器进程设置的环境变量。
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
allowed_tools: optional array of string or null
智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。
minItems: 0, maxItems: 16384
connection_origin: optional "service" or "environment" or null
选择出站 MCP HTTP 连接的来源。省略或设为 service 时使用 Managed Agents 服务网络,设为 environment 时使用会话选定的环境。
"service"
使用 Managed Agents 服务网络。
"environment"
使用会话的执行环境。
credential_id: optional string or null
用于验证此 MCP 服务器连接的已附加凭证库凭证。只有一条已附加凭证与服务器 URL 匹配时,可以省略。
minLength: 0, maxLength: 1048576
request_metadata: optional map[unknown] or null
随请求发送给此 MCP 服务器的元数据。
required: optional boolean (default: false)
是否必须在第一轮前初始化此 MCP 服务器。默认为 false。
WebSearch object { type, allowed_domains, context_size, 2 more }
网页搜索。
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
allowed_domains: optional array of string or null
可纳入搜索范围的域名。
minItems: 0, maxItems: 16384
context_size: optional "low" or "medium" or "high" or null
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置。
city: optional string or null
城市名称。
minLength: 0, maxLength: 1048576
country: optional string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0, maxLength: 1048576
region: optional string or null
地区或州的名称。
minLength: 0, maxLength: 1048576
timezone: optional string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0, maxLength: 1048576
mode: optional "disabled" or "cached" or "live" or null
网页搜索结果的来源,默认为 live。
"disabled"
关闭网页搜索。
"cached"
使用缓存的搜索结果。
"live"
搜索实时网页。
ComputerUse object { type, include_screenshots }
在 OpenAI 托管会话中使用浏览器。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
include_screenshots: optional boolean (default: false)
计算机工具的输出是否包含屏幕截图。默认为 false。
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
agent_id: optional string
已保存的智能体 ID。agent 和 agent_id 必须且只能提供一个。
minLength: 0, maxLength: 64
metadata: optional map[string] or null
附加到每个新会话的元数据。
vault_ids: optional array of string or null
每个新会话可访问的凭证库 ID。
minItems: 0, maxItems: 16384
ExistingSession object { instructions, session_id, type }
向现有会话投递指令。
instructions: string
以自动化通知形式投递的指令。
minLength: 0, maxLength: 1048576
session_id: string
接收每次调用的会话。
minLength: 0, maxLength: 1048576
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
One Time Automation
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
Periodic Automation
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
自动化调用
手动触发自动化任务
post /agents/automations/{automation_id}/invocations
将一次手动投递加入队列,原有计划保持不变。
路径参数
automation_id: string
minLength: 0, maxLength: 1048576
返回值
AutomationInvocation object { id, automation_id, created_at, 7 more }
自动化任务尝试投递一次的记录。
id: string
调用 ID。
minLength: 0
automation_id: string
此调用所属的自动化任务。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
error: object { code, message } or null
不可恢复的投递失败信息。未发生失败时为 null。
code: string
机器可读的错误代码。
minLength: 0
message: string
对投递失败原因的公开说明。
minLength: 0
object: "agent.automation.invocation" (default: "agent.automation.invocation")
固定为 agent.automation.invocation。
"agent.automation.invocation"
scheduled_at: integer or null
预定触发时间的 Unix 时间戳,单位为秒。手动运行时为 null。
format: int64
session_id: string or null
目标会话或新建会话的 ID。会话尚未确定时为 null。
minLength: 0
skip_reason: "pending_delivery" or null (default: "pending_delivery")
本次触发被跳过的原因。未跳过时为 null。
"pending_delivery"
source: AutomationInvocationSource
该调用是手动触发还是按计划触发。
Manual object { type }
type: "manual" (default: "manual")
对象类型,固定为 manual。
"manual"
Automation object { automation, type }
automation: Automation
本次触发时的自动化任务快照,返回内容省略机密值。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
type: "automation" (default: "automation")
对象类型,固定为 automation。
"automation"
status: "queued" or "completed" or "failed" or "skipped"
投递状态。投递完成后仍需单独确认智能体任务的执行结果。
"queued"
"completed"
"failed"
"skipped"
示例
## 从环境变量读取 API 密钥。
## 将 AUTOMATION_ID 设置为目标自动化任务的 ID。
curl https://api.openai.com/v1/agents/automations/$AUTOMATION_ID/invocations \
-X POST \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
返回的示例状态为 pending_delivery,表示尚待投递。
{
"id": "id",
"automation_id": "automation_id",
"created_at": 0,
"error": {
"code": "code",
"message": "message"
},
"object": "agent.automation.invocation",
"scheduled_at": 0,
"session_id": "session_id",
"skip_reason": "pending_delivery",
"source": {
"type": "manual"
},
"status": "queued"
}
列出自动化调用记录
get /agents/automations/{automation_id}/invocations
列出项目所拥有的自动化任务的投递记录。
路径参数
automation_id: string
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of AutomationInvocation
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
调用 ID。
minLength: 0
automation_id: string
此调用所属的自动化任务。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
error: object { code, message } or null
不可恢复的投递失败信息。未发生失败时为 null。
code: string
机器可读的错误代码。
minLength: 0
message: string
对投递失败原因的公开说明。
minLength: 0
object: "agent.automation.invocation" (default: "agent.automation.invocation")
固定为 agent.automation.invocation。
"agent.automation.invocation"
scheduled_at: integer or null
预定触发时间的 Unix 时间戳,单位为秒。手动运行时为 null。
format: int64
session_id: string or null
目标会话或新建会话的 ID。会话尚未确定时为 null。
minLength: 0
skip_reason: "pending_delivery" or null (default: "pending_delivery")
本次触发被跳过的原因。未跳过时为 null。
"pending_delivery"
source: AutomationInvocationSource
该调用是手动触发还是按计划触发。
Manual object { type }
type: "manual" (default: "manual")
对象类型,固定为 manual。
"manual"
Automation object { automation, type }
automation: Automation
本次触发时的自动化任务快照,返回内容省略机密值。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
type: "automation" (default: "automation")
对象类型,固定为 automation。
"automation"
status: "queued" or "completed" or "failed" or "skipped"
投递状态。投递完成后仍需单独确认智能体任务的执行结果。
"queued"
"completed"
"failed"
"skipped"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 AUTOMATION_ID 设置为目标自动化任务的 ID。
curl https://api.openai.com/v1/agents/automations/$AUTOMATION_ID/invocations \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
返回的示例状态为 pending_delivery,表示尚待投递。
{
"data": [
{
"id": "id",
"automation_id": "automation_id",
"created_at": 0,
"error": {
"code": "code",
"message": "message"
},
"object": "agent.automation.invocation",
"scheduled_at": 0,
"session_id": "session_id",
"skip_reason": "pending_delivery",
"source": {
"type": "manual"
},
"status": "queued"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取自动化调用记录
get /agents/automations/{automation_id}/invocations/{invocation_id}
获取项目所拥有的自动化任务的一条投递记录。
路径参数
automation_id: string
minLength: 0, maxLength: 1048576
invocation_id: string
minLength: 0, maxLength: 1048576
返回值
AutomationInvocation object { id, automation_id, created_at, 7 more }
自动化任务尝试投递一次的记录。
id: string
调用 ID。
minLength: 0
automation_id: string
此调用所属的自动化任务。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
error: object { code, message } or null
不可恢复的投递失败信息。未发生失败时为 null。
code: string
机器可读的错误代码。
minLength: 0
message: string
对投递失败原因的公开说明。
minLength: 0
object: "agent.automation.invocation" (default: "agent.automation.invocation")
固定为 agent.automation.invocation。
"agent.automation.invocation"
scheduled_at: integer or null
预定触发时间的 Unix 时间戳,单位为秒。手动运行时为 null。
format: int64
session_id: string or null
目标会话或新建会话的 ID。会话尚未确定时为 null。
minLength: 0
skip_reason: "pending_delivery" or null (default: "pending_delivery")
本次触发被跳过的原因。未跳过时为 null。
"pending_delivery"
source: AutomationInvocationSource
该调用是手动触发还是按计划触发。
Manual object { type }
type: "manual" (default: "manual")
对象类型,固定为 manual。
"manual"
Automation object { automation, type }
automation: Automation
本次触发时的自动化任务快照,返回内容省略机密值。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
type: "automation" (default: "automation")
对象类型,固定为 automation。
"automation"
status: "queued" or "completed" or "failed" or "skipped"
投递状态。投递完成后仍需单独确认智能体任务的执行结果。
"queued"
"completed"
"failed"
"skipped"
示例
## 从环境变量读取 API 密钥。
## 将 AUTOMATION_ID 设置为目标自动化任务的 ID。
## 将 INVOCATION_ID 设置为要查询的调用记录的 ID。
curl https://api.openai.com/v1/agents/automations/$AUTOMATION_ID/invocations/$INVOCATION_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
返回的示例状态为 pending_delivery,表示尚待投递。
{
"id": "id",
"automation_id": "automation_id",
"created_at": 0,
"error": {
"code": "code",
"message": "message"
},
"object": "agent.automation.invocation",
"scheduled_at": 0,
"session_id": "session_id",
"skip_reason": "pending_delivery",
"source": {
"type": "manual"
},
"status": "queued"
}
资源类型
Automation Invocation
AutomationInvocation object { id, automation_id, created_at, 7 more }
自动化任务尝试投递一次的记录。
id: string
调用 ID。
minLength: 0
automation_id: string
此调用所属的自动化任务。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
error: object { code, message } or null
不可恢复的投递失败信息。未发生失败时为 null。
code: string
机器可读的错误代码。
minLength: 0
message: string
对投递失败原因的公开说明。
minLength: 0
object: "agent.automation.invocation" (default: "agent.automation.invocation")
固定为 agent.automation.invocation。
"agent.automation.invocation"
scheduled_at: integer or null
预定触发时间的 Unix 时间戳,单位为秒。手动运行时为 null。
format: int64
session_id: string or null
目标会话或新建会话的 ID。会话尚未确定时为 null。
minLength: 0
skip_reason: "pending_delivery" or null (default: "pending_delivery")
本次触发被跳过的原因。未跳过时为 null。
"pending_delivery"
source: AutomationInvocationSource
该调用是手动触发还是按计划触发。
Manual object { type }
type: "manual" (default: "manual")
对象类型,固定为 manual。
"manual"
Automation object { automation, type }
automation: Automation
本次触发时的自动化任务快照,返回内容省略机密值。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
type: "automation" (default: "automation")
对象类型,固定为 automation。
"automation"
status: "queued" or "completed" or "failed" or "skipped"
投递状态。投递完成后仍需单独确认智能体任务的执行结果。
"queued"
"completed"
"failed"
"skipped"
Automation Invocation Source
AutomationInvocationSource = Manual { type } or Automation { automation, type }
Manual object { type }
type: "manual" (default: "manual")
对象类型,固定为 manual。
"manual"
Automation object { automation, type }
automation: Automation
本次触发时的自动化任务快照,返回内容省略机密值。
PeriodicAutomation object { id, created_at, created_by, 9 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
Developer object { type }
type: "developer" (default: "developer")
对象类型,固定为 developer。
"developer"
Agent object { session_id, tool_call_id, type }
session_id: string
创建该自动化任务的会话,也是任务的目标会话。
minLength: 0
tool_call_id: string
创建自动化任务的工具调用。
minLength: 0
type: "agent" (default: "agent")
对象类型,固定为 agent。
"agent"
expression: string
确定计划触发时间的 cron 表达式。
minLength: 0
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
status: "active" or "paused"
计划投递处于活动还是暂停状态。
"active"
"paused"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
NewSession object { agent, agent_id, environment, 4 more }
agent: AutomationAgentConfig or null
内联智能体配置。配置了 agent_id 时为 null。
instructions: string or null
自定义指令。未设置时为 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
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"
"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
模型是否会定期收到当前时间提醒。
agent_id: string or null
已保存智能体的引用。使用内联智能体配置时为 null。
minLength: 0
environment: AutomationEnvironment
用于选择执行环境的配置或引用。
None object { type }
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { capability_directories, container_size, desktop, 8 more }
托管环境的选择配置。返回内容省略机密的初始化命令和变量。
capability_directories: array of string or null
目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。
minItems: 0, maxItems: 2000
container_size: "small" or "medium" or "large" or null
配置的容器规格。传入 null 时使用创建时的默认规格。
"small"
"medium"
"large"
desktop: object { enabled } or null
桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。
enabled: boolean
环境是否配置桌面及浏览器代理。
environment_id: string or null
现有环境的引用。配置新环境时为 null。
minLength: 0
environment_template_id: string or null
模板引用。未选用模板时为 null。
minLength: 0
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null
文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains } or null
网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system } or null
软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。
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 or null
插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null
技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。
minItems: 0, maxItems: 2000
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
SelfHosted object { capability_directories, environment_id, type, workspace_directory }
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
environment_id: string or null
现有的环境注册记录。传入 null 时创建会话专属环境。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境中的项目绝对路径。
minLength: 0
input: array of object { content, role, type }
向每个新会话投递的初始输入。
minItems: 0, maxItems: 2000
content: 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"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: map[string]
附加到每个新会话的元数据。
type: "new_session" (default: "new_session")
对象类型,固定为 new_session。
"new_session"
vault_ids: array of string
每个新会话可使用的凭证库。
minItems: 0, maxItems: 2000
ExistingSession object { instructions, session_id, type }
instructions: string
保存的指令,以自动化通知形式投递。
minLength: 0
session_id: string
接收每次调用的会话。
minLength: 0
type: "existing_session" (default: "existing_session")
对象类型,固定为 existing_session。
"existing_session"
timezone: string
用于解释此表达式的时区。
minLength: 0
type: "periodic" (default: "periodic")
对象类型,固定为 periodic。
"periodic"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
OneTimeAutomation object { id, created_at, created_by, 8 more }
周期性和一次性自动化任务共有的字段。
id: string
自动化任务 ID。
minLength: 0
created_at: integer
创建时间的 Unix 时间戳,单位为秒。
format: int64
created_by: AutomationCreatedBy
服务记录的来源信息,调用方不能设置此字段。
metadata: map[string]
附加到自动化任务的自定义字符串键值对。
name: string
自动化任务的显示名称。
minLength: 0
object: "agent.automation" (default: "agent.automation")
固定为 agent.automation。
"agent.automation"
run_at: integer
计划触发时间的 Unix 时间戳,单位为秒。
format: int64
status: "active" or "paused" or "completed"
完成状态表示计划已结束。智能体任务的完成状态需单独确认。
"active"
"paused"
"completed"
target: AutomationTarget
接收调用投递的会话配置或现有会话。
type: "once" (default: "once")
对象类型,固定为 once。
"once"
pause_reason: optional "target_session_failed" or null (default: "target_session_failed")
服务暂停当前计划的原因。其他计划为 null。
"target_session_failed"
type: "automation" (default: "automation")
对象类型,固定为 automation。
"automation"
智能体环境
创建智能体环境
post /agents/environments
在创建会话之前创建 OpenAI 托管环境。需要预热 Beta 功能的访问权限。
请求头参数
"Idempotency-Key": optional string
minLength: 1, maxLength: 256
请求体参数
内容类型为 application/json。
environment: object { type, capability_directories, desktop, 8 more }
必填的托管类型及其配置。
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
desktop: optional object { enabled } or null
桌面配置。省略或传入 null 时继承模板设置,无模板设置时默认禁用。
enabled: boolean
是否配置桌面及其浏览器代理。
env: optional map[string] or null
向智能体提供的环境变量。
environment_template_id: optional string
先于内联配置应用的可复用托管环境模板。省略的字段继承模板,网络覆盖配置只能保持或收紧模板的网络策略。
minLength: 0, maxLength: 64
files: optional array of HostedEnvironmentFileParam or null
智能体启动前可用的文件。默认为空列表。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: optional object { access, allowed_domains, blocked_domains } or null
环境的网络访问策略。省略时,由 API 版本决定是否启用网络访问。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: optional array of string or null
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 16384
blocked_domains: optional array of string or null
网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。
minItems: 0, maxItems: 100
packages: optional object { npm, python, system } or null
要安装到环境中的软件包。软件包列表默认为空。
npm: optional array of string or null
要全局安装的 npm 软件包。默认为空列表。
minItems: 0, maxItems: 16384
python: optional array of string or null
要安装的 Python 软件包。默认为空列表。
minItems: 0, maxItems: 16384
system: optional array of string or null
要安装的系统软件包。默认为空列表。
minItems: 0, maxItems: 16384
plugins: optional array of HostedPluginParam or null
以内联 ZIP 归档提供的插件。默认为空列表。
minItems: 0, maxItems: 32
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
setup_commands: optional array of SetupCommandParam or null
按顺序执行的机密初始化命令。响应始终省略命令正文。
minItems: 0, maxItems: 16
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
skills: optional array of HostedSkillParam or null
通过 ID 引用或以内联 ZIP 归档提供的技能。默认为空列表。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
vault_ids: optional array of string or null
OpenAI 托管环境可访问的凭证库 ID,最多 10 个。
minItems: 0, maxItems: 10
返回值
EnvironmentInfo object { id, files, object, 4 more }
可返回的独立执行环境资源的元数据。
id: string
环境 ID。
minLength: 0
files: array of HostedEnvironmentFile
环境中已安装的文件。响应省略文件内容。
minItems: 0, maxItems: 2000
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"
object: "agent.environment" (default: "agent.environment")
对象类型,固定为 agent.environment。
"agent.environment"
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"
status: "pending" or "ready" or "connected" or 4 more
环境当前的连接状态。
"pending"
"ready"
环境已成功配置,可附加到会话或投入使用。
"connected"
"disconnected"
"suspended"
沙箱已停止,可从其私有检查点恢复。
"expired"
"failed"
type: "openai_hosted" or "self_hosted"
环境由 OpenAI 还是由应用托管。
"openai_hosted"
"self_hosted"
示例
## 从环境变量读取 API 密钥。
curl https://api.openai.com/v1/agents/environments \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"environment": {
"type": "openai_hosted"
}
}'
201 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"files": [
{
"id": "id",
"file_id": "file_id",
"path": "path",
"size_bytes": 0,
"type": "file_id"
}
],
"object": "agent.environment",
"plugins": [
{
"description": "description",
"name": "name",
"type": "inline"
}
],
"skills": [
{
"description": "description",
"name": "name",
"skill_id": "skill_id",
"type": "skill_reference",
"version": "version"
}
],
"status": "pending",
"type": "openai_hosted"
}
列出智能体环境
get /agents/environments
列出当前身份验证主体拥有的 OpenAI 托管环境。需要预热 Beta 功能的访问权限。
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
type: optional "openai_hosted"
要列出的托管类型,默认为 openai_hosted。
"openai_hosted"
返回值
data: array of EnvironmentInfo
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
环境 ID。
minLength: 0
files: array of HostedEnvironmentFile
环境中已安装的文件。响应省略文件内容。
minItems: 0, maxItems: 2000
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"
object: "agent.environment" (default: "agent.environment")
对象类型,固定为 agent.environment。
"agent.environment"
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"
status: "pending" or "ready" or "connected" or 4 more
环境当前的连接状态。
"pending"
"ready"
环境已成功配置,可附加到会话或投入使用。
"connected"
"disconnected"
"suspended"
沙箱已停止,可从其私有检查点恢复。
"expired"
"failed"
type: "openai_hosted" or "self_hosted"
环境由 OpenAI 还是由应用托管。
"openai_hosted"
"self_hosted"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
curl https://api.openai.com/v1/agents/environments \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"files": [
{
"id": "id",
"file_id": "file_id",
"path": "path",
"size_bytes": 0,
"type": "file_id"
}
],
"object": "agent.environment",
"plugins": [
{
"description": "description",
"name": "name",
"type": "inline"
}
],
"skills": [
{
"description": "description",
"name": "name",
"skill_id": "skill_id",
"type": "skill_reference",
"version": "version"
}
],
"status": "pending",
"type": "openai_hosted"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取智能体环境
get /agents/environments/{environment_id}
获取执行环境的连接状态及可返回的已安装资源元数据。参见环境生命周期。
路径参数
environment_id: string
环境 ID。
minLength: 0, maxLength: 1048576
返回值
EnvironmentInfo object { id, files, object, 4 more }
可返回的独立执行环境资源的元数据。
id: string
环境 ID。
minLength: 0
files: array of HostedEnvironmentFile
环境中已安装的文件。响应省略文件内容。
minItems: 0, maxItems: 2000
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"
object: "agent.environment" (default: "agent.environment")
对象类型,固定为 agent.environment。
"agent.environment"
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"
status: "pending" or "ready" or "connected" or 4 more
环境当前的连接状态。
"pending"
"ready"
环境已成功配置,可附加到会话或投入使用。
"connected"
"disconnected"
"suspended"
沙箱已停止,可从其私有检查点恢复。
"expired"
"failed"
type: "openai_hosted" or "self_hosted"
环境由 OpenAI 还是由应用托管。
"openai_hosted"
"self_hosted"
示例
## 从环境变量读取 API 密钥。
## 将 ENVIRONMENT_ID 设置为目标环境的 ID。
curl https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"files": [
{
"id": "id",
"file_id": "file_id",
"path": "path",
"size_bytes": 0,
"type": "file_id"
}
],
"object": "agent.environment",
"plugins": [
{
"description": "description",
"name": "name",
"type": "inline"
}
],
"skills": [
{
"description": "description",
"name": "name",
"skill_id": "skill_id",
"type": "skill_reference",
"version": "version"
}
],
"status": "pending",
"type": "openai_hosted"
}
资源类型
Environment Info
EnvironmentInfo object { id, files, object, 4 more }
可返回的独立执行环境资源的元数据。
id: string
环境 ID。
minLength: 0
files: array of HostedEnvironmentFile
环境中已安装的文件。响应省略文件内容。
minItems: 0, maxItems: 2000
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"
object: "agent.environment" (default: "agent.environment")
对象类型,固定为 agent.environment。
"agent.environment"
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"
status: "pending" or "ready" or "connected" or 4 more
环境当前的连接状态。
"pending"
"ready"
环境已成功配置,可附加到会话或投入使用。
"connected"
"disconnected"
"suspended"
沙箱已停止,可从其私有检查点恢复。
"expired"
"failed"
type: "openai_hosted" or "self_hosted"
环境由 OpenAI 还是由应用托管。
"openai_hosted"
"self_hosted"
环境文件
写入智能体环境文件
post /agents/environments/{environment_id}/files
将内联字节或 Files API 文件复制到已连接的执行环境中。同一路径已有普通文件时会替换该文件。请在两轮之间上传,等待写入成功后再开始下一轮。参见环境文件。
路径参数
environment_id: string
环境 ID。
minLength: 0, maxLength: 1048576
请求体参数
内容类型为 application/json。
hosted_environment_file_param: HostedEnvironmentFileParam
写入 OpenAI 托管执行环境的文件。
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
返回值
EnvironmentFile object { environment_id, object, path, size_bytes }
执行环境中当前存在的文件。
environment_id: string
存放此文件的环境 ID。
minLength: 0
object: "agent.environment.file" (default: "agent.environment.file")
对象类型,固定为 agent.environment.file。
"agent.environment.file"
path: string
环境工作区内文件的绝对路径。
minLength: 0
size_bytes: integer
文件大小,单位为字节。
format: int64, minimum: 0
示例
## 从环境变量读取 API 密钥。
## 将 ENVIRONMENT_ID 设置为目标环境的 ID。
## 此官方示例仅展示请求地址和请求头。发送前请按上方参数补充 JSON 请求体及 Content-Type 请求头。
curl https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID/files \
-X POST \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
201 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"environment_id": "environment_id",
"object": "agent.environment.file",
"path": "path",
"size_bytes": 0
}
列出智能体环境文件
get /agents/environments/{environment_id}/files
列出已连接执行环境中当前存在的文件。可按目录筛选,使用由服务端生成的不透明游标分页。参见环境文件。
路径参数
environment_id: string
环境 ID。
minLength: 0, maxLength: 1048576
查询参数
limit: optional integer or null
每次最多返回的文件数,范围为 1 至 100。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc"
按路径各组成部分排序,区分大小写。默认降序。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
page: optional string
上一页返回的不透明游标。翻页时保持路径、排序方式和数量上限一致。
minLength: 0, maxLength: 1048576
path: optional string or null
仅列出此工作区绝对路径下的文件。
minLength: 0, maxLength: 1048576
返回值
data: array of EnvironmentFile
当前页的文件。
minItems: 0, maxItems: 2000
environment_id: string
存放此文件的环境 ID。
minLength: 0
object: "agent.environment.file" (default: "agent.environment.file")
对象类型,固定为 agent.environment.file。
"agent.environment.file"
path: string
环境工作区内文件的绝对路径。
minLength: 0
size_bytes: integer
文件大小,单位为字节。
format: int64, minimum: 0
has_more: boolean
此页之后是否还有文件。
next: string or null
用于请求下一页的不透明游标(如有)。
minLength: 0
object: "page" (default: "page")
对象类型,固定为 page。
"page"
示例
## 从环境变量读取 API 密钥。
## 将 ENVIRONMENT_ID 设置为目标环境的 ID。
curl https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID/files \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"environment_id": "environment_id",
"object": "agent.environment.file",
"path": "path",
"size_bytes": 0
}
],
"has_more": true,
"next": "next",
"object": "page"
}
资源类型
Environment File
EnvironmentFile object { environment_id, object, path, size_bytes }
执行环境中当前存在的文件。
environment_id: string
存放此文件的环境 ID。
minLength: 0
object: "agent.environment.file" (default: "agent.environment.file")
对象类型,固定为 agent.environment.file。
"agent.environment.file"
path: string
环境工作区内文件的绝对路径。
minLength: 0
size_bytes: integer
文件大小,单位为字节。
format: int64, minimum: 0
环境模板
创建智能体环境模板
post /agents/environments/templates
创建可复用的环境配置。响应省略机密的初始化命令和环境变量值。参见复用托管配置。
请求体参数
内容类型为 application/json。
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
desktop: optional object { enabled } or null
桌面配置。省略或传入 null 时继承模板设置,无模板设置时默认禁用。
enabled: boolean
是否配置桌面及其浏览器代理。
env: optional map[string] or null
向智能体提供的环境变量。
files: optional array of HostedEnvironmentFileParam or null
智能体启动前可用的文件。默认为空列表。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
name: optional string or null
模板的可选显示名称。
minLength: 1, maxLength: 256
network: optional object { access, allowed_domains, blocked_domains } or null
环境的网络访问策略。省略时,由 API 版本决定是否启用网络访问。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: optional array of string or null
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 16384
blocked_domains: optional array of string or null
网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。
minItems: 0, maxItems: 100
packages: optional object { npm, python, system } or null
要安装到环境中的软件包。软件包列表默认为空。
npm: optional array of string or null
要全局安装的 npm 软件包。默认为空列表。
minItems: 0, maxItems: 16384
python: optional array of string or null
要安装的 Python 软件包。默认为空列表。
minItems: 0, maxItems: 16384
system: optional array of string or null
要安装的系统软件包。默认为空列表。
minItems: 0, maxItems: 16384
plugins: optional array of HostedPluginParam or null
以内联 ZIP 归档提供的插件。默认为空列表。
minItems: 0, maxItems: 32
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
setup_commands: optional array of SetupCommandParam or null
按顺序执行的机密初始化命令。响应始终省略命令正文。
minItems: 0, maxItems: 16
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
skills: optional array of HostedSkillParam or null
通过 ID 引用或以内联 ZIP 归档提供的技能。默认为空列表。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
返回值
EnvironmentTemplate object { id, capability_directories, created_at, 9 more }
可复用的配置,用于为每个会话创建新的 OpenAI 托管环境。
id: string
可复用的环境模板 ID。
minLength: 0
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
created_at: integer
模板创建时的 Unix 时间戳,单位为秒。
format: int64
desktop: object { enabled }
每个 OpenAI 托管环境的桌面配置。
enabled: boolean
环境是否配置桌面及浏览器代理。
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }
可返回的文件元数据,省略文件内容和会话范围的文件 ID。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
name: string or null
模板的可选显示名称。
minLength: 0
network: object { access, allowed_domains }
每个 OpenAI 托管环境的运行时网络访问配置。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
object: "agent.environment.template" (default: "agent.environment.template")
对象类型,固定为 agent.environment.template。
"agent.environment.template"
packages: object { npm, python, system }
每次新建 OpenAI 托管环境时安装的软件包。
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: 32
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }
可返回的技能元数据,保留尚未解析的版本选择值。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
updated_at: integer
模板上次更新时的 Unix 时间戳,单位为秒。
format: int64
示例
## 从环境变量读取 API 密钥。
## 此官方示例仅展示请求地址和请求头。发送前请按上方参数补充 JSON 请求体及 Content-Type 请求头。
curl https://api.openai.com/v1/agents/environments/templates \
-X POST \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
201 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"capability_directories": [
"string"
],
"created_at": 0,
"desktop": {
"enabled": true
},
"files": [
{
"file_id": "file_id",
"path": "path",
"type": "file_id"
}
],
"name": "name",
"network": {
"access": "enabled",
"allowed_domains": [
"string"
]
},
"object": "agent.environment.template",
"packages": {
"npm": [
"string"
],
"python": [
"string"
],
"system": [
"string"
]
},
"plugins": [
{
"description": "description",
"name": "name",
"type": "inline"
}
],
"skills": [
{
"skill_id": "skill_id",
"type": "skill_reference",
"version": "version"
}
],
"updated_at": 0
}
删除智能体环境模板
delete /agents/environments/templates/{environment_template_id}
删除可复用的环境配置及模板的所有机密输入。参见复用托管配置。
路径参数
environment_template_id: string
可复用的环境模板 ID。
minLength: 0, maxLength: 1048576
返回值
EnvironmentTemplateDeleted object { id, deleted, object }
已删除的可复用环境模板。
id: string
已删除的环境模板 ID。
minLength: 0
deleted: boolean
环境模板是否已删除,恒为 true。
object: "agent.environment.template.deleted" (default: "agent.environment.template.deleted")
对象类型,固定为 agent.environment.template.deleted。
"agent.environment.template.deleted"
示例
## 从环境变量读取 API 密钥。
## 将 ENVIRONMENT_TEMPLATE_ID 设置为目标环境模板的 ID。
curl https://api.openai.com/v1/agents/environments/templates/$ENVIRONMENT_TEMPLATE_ID \
-X DELETE \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"deleted": true,
"object": "agent.environment.template.deleted"
}
列出智能体环境模板
get /agents/environments/templates
列出可复用的环境模板。响应省略机密值。参见复用托管配置。
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of EnvironmentTemplate
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
可复用的环境模板 ID。
minLength: 0
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
created_at: integer
模板创建时的 Unix 时间戳,单位为秒。
format: int64
desktop: object { enabled }
每个 OpenAI 托管环境的桌面配置。
enabled: boolean
环境是否配置桌面及浏览器代理。
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }
可返回的文件元数据,省略文件内容和会话范围的文件 ID。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
name: string or null
模板的可选显示名称。
minLength: 0
network: object { access, allowed_domains }
每个 OpenAI 托管环境的运行时网络访问配置。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
object: "agent.environment.template" (default: "agent.environment.template")
对象类型,固定为 agent.environment.template。
"agent.environment.template"
packages: object { npm, python, system }
每次新建 OpenAI 托管环境时安装的软件包。
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: 32
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }
可返回的技能元数据,保留尚未解析的版本选择值。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
updated_at: integer
模板上次更新时的 Unix 时间戳,单位为秒。
format: int64
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
curl https://api.openai.com/v1/agents/environments/templates \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"capability_directories": [
"string"
],
"created_at": 0,
"desktop": {
"enabled": true
},
"files": [
{
"file_id": "file_id",
"path": "path",
"type": "file_id"
}
],
"name": "name",
"network": {
"access": "enabled",
"allowed_domains": [
"string"
]
},
"object": "agent.environment.template",
"packages": {
"npm": [
"string"
],
"python": [
"string"
],
"system": [
"string"
]
},
"plugins": [
{
"description": "description",
"name": "name",
"type": "inline"
}
],
"skills": [
{
"skill_id": "skill_id",
"type": "skill_reference",
"version": "version"
}
],
"updated_at": 0
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取智能体环境模板
get /agents/environments/templates/{environment_template_id}
获取可复用的环境配置。响应省略机密值。参见复用托管配置。
路径参数
environment_template_id: string
可复用的环境模板 ID。
minLength: 0, maxLength: 1048576
返回值
EnvironmentTemplate object { id, capability_directories, created_at, 9 more }
可复用的配置,用于为每个会话创建新的 OpenAI 托管环境。
id: string
可复用的环境模板 ID。
minLength: 0
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
created_at: integer
模板创建时的 Unix 时间戳,单位为秒。
format: int64
desktop: object { enabled }
每个 OpenAI 托管环境的桌面配置。
enabled: boolean
环境是否配置桌面及浏览器代理。
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }
可返回的文件元数据,省略文件内容和会话范围的文件 ID。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
name: string or null
模板的可选显示名称。
minLength: 0
network: object { access, allowed_domains }
每个 OpenAI 托管环境的运行时网络访问配置。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
object: "agent.environment.template" (default: "agent.environment.template")
对象类型,固定为 agent.environment.template。
"agent.environment.template"
packages: object { npm, python, system }
每次新建 OpenAI 托管环境时安装的软件包。
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: 32
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }
可返回的技能元数据,保留尚未解析的版本选择值。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
updated_at: integer
模板上次更新时的 Unix 时间戳,单位为秒。
format: int64
示例
## 从环境变量读取 API 密钥。
## 将 ENVIRONMENT_TEMPLATE_ID 设置为目标环境模板的 ID。
curl https://api.openai.com/v1/agents/environments/templates/$ENVIRONMENT_TEMPLATE_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"capability_directories": [
"string"
],
"created_at": 0,
"desktop": {
"enabled": true
},
"files": [
{
"file_id": "file_id",
"path": "path",
"type": "file_id"
}
],
"name": "name",
"network": {
"access": "enabled",
"allowed_domains": [
"string"
]
},
"object": "agent.environment.template",
"packages": {
"npm": [
"string"
],
"python": [
"string"
],
"system": [
"string"
]
},
"plugins": [
{
"description": "description",
"name": "name",
"type": "inline"
}
],
"skills": [
{
"skill_id": "skill_id",
"type": "skill_reference",
"version": "version"
}
],
"updated_at": 0
}
更新智能体环境模板
post /agents/environments/templates/{environment_template_id}
更新可复用的环境配置。响应省略机密值。参见复用托管配置。
路径参数
environment_template_id: string
可复用的环境模板 ID。
minLength: 0, maxLength: 1048576
请求体参数
内容类型为 application/json。
capability_directories: optional array of string or null
用于向智能体提供能力的目录。
minItems: 0, maxItems: 16384
desktop: optional object { enabled } or null
用于替换现有配置的桌面配置。传入 null 可禁用桌面。
enabled: boolean
是否配置桌面及其浏览器代理。
env: optional map[string] or null
用于替换现有值的机密环境变量值。
files: optional array of HostedEnvironmentFileParam or null
用于替换现有配置的文件配置。每次创建新会话时按该配置写入文件。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
name: optional string or null
新的显示名称。传入 null 可清除名称。
minLength: 1, maxLength: 256
network: optional object { access, allowed_domains, blocked_domains } or null
初始化完成后的网络访问策略。省略时保留当前策略,传入 null 时恢复默认策略。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: optional array of string or null
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 16384
blocked_domains: optional array of string or null
网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。
minItems: 0, maxItems: 100
packages: optional object { npm, python, system } or null
在运行时网络策略生效前安装的软件包。
npm: optional array of string or null
要全局安装的 npm 软件包。默认为空列表。
minItems: 0, maxItems: 16384
python: optional array of string or null
要安装的 Python 软件包。默认为空列表。
minItems: 0, maxItems: 16384
system: optional array of string or null
要安装的系统软件包。默认为空列表。
minItems: 0, maxItems: 16384
plugins: optional array of HostedPluginParam or null
用于替换现有配置的插件配置。每次创建新会话时按该配置安装插件。
minItems: 0, maxItems: 32
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
setup_commands: optional array of SetupCommandParam or null
用于替换现有命令的机密初始化命令。返回的资源始终省略这些命令。
minItems: 0, maxItems: 16
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
skills: optional array of HostedSkillParam or null
用于替换现有配置的技能配置。每次创建新会话时按该配置安装技能。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
返回值
EnvironmentTemplate object { id, capability_directories, created_at, 9 more }
可复用的配置,用于为每个会话创建新的 OpenAI 托管环境。
id: string
可复用的环境模板 ID。
minLength: 0
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
created_at: integer
模板创建时的 Unix 时间戳,单位为秒。
format: int64
desktop: object { enabled }
每个 OpenAI 托管环境的桌面配置。
enabled: boolean
环境是否配置桌面及浏览器代理。
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }
可返回的文件元数据,省略文件内容和会话范围的文件 ID。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
name: string or null
模板的可选显示名称。
minLength: 0
network: object { access, allowed_domains }
每个 OpenAI 托管环境的运行时网络访问配置。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
object: "agent.environment.template" (default: "agent.environment.template")
对象类型,固定为 agent.environment.template。
"agent.environment.template"
packages: object { npm, python, system }
每次新建 OpenAI 托管环境时安装的软件包。
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: 32
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }
可返回的技能元数据,保留尚未解析的版本选择值。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
updated_at: integer
模板上次更新时的 Unix 时间戳,单位为秒。
format: int64
示例
## 从环境变量读取 API 密钥。
## 将 ENVIRONMENT_TEMPLATE_ID 设置为目标环境模板的 ID。
## 此官方示例仅展示请求地址和请求头。发送前请按上方参数补充 JSON 请求体及 Content-Type 请求头。
curl https://api.openai.com/v1/agents/environments/templates/$ENVIRONMENT_TEMPLATE_ID \
-X POST \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"capability_directories": [
"string"
],
"created_at": 0,
"desktop": {
"enabled": true
},
"files": [
{
"file_id": "file_id",
"path": "path",
"type": "file_id"
}
],
"name": "name",
"network": {
"access": "enabled",
"allowed_domains": [
"string"
]
},
"object": "agent.environment.template",
"packages": {
"npm": [
"string"
],
"python": [
"string"
],
"system": [
"string"
]
},
"plugins": [
{
"description": "description",
"name": "name",
"type": "inline"
}
],
"skills": [
{
"skill_id": "skill_id",
"type": "skill_reference",
"version": "version"
}
],
"updated_at": 0
}
资源类型
Environment Template
EnvironmentTemplate object { id, capability_directories, created_at, 9 more }
可复用的配置,用于为每个会话创建新的 OpenAI 托管环境。
id: string
可复用的环境模板 ID。
minLength: 0
capability_directories: array of string
用于向智能体提供能力的目录。
minItems: 0, maxItems: 2000
created_at: integer
模板创建时的 Unix 时间戳,单位为秒。
format: int64
desktop: object { enabled }
每个 OpenAI 托管环境的桌面配置。
enabled: boolean
环境是否配置桌面及浏览器代理。
files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }
可返回的文件元数据,省略文件内容和会话范围的文件 ID。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
项目范围内的 Files API 引用,每个会话独立解析。
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { path, size_bytes, type }
机密内联文件内容的元数据。
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
内联文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
name: string or null
模板的可选显示名称。
minLength: 0
network: object { access, allowed_domains }
每个 OpenAI 托管环境的运行时网络访问配置。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
object: "agent.environment.template" (default: "agent.environment.template")
对象类型,固定为 agent.environment.template。
"agent.environment.template"
packages: object { npm, python, system }
每次新建 OpenAI 托管环境时安装的软件包。
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: 32
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }
可返回的技能元数据,保留尚未解析的版本选择值。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
每次启动会话时都通过 Skills API 重新解析的技能。
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string or null
请求的版本选择值,包含 latest 选项。
minLength: 0
Inline object { description, name, type }
可以安全返回的内联技能归档元数据。
description: string
SKILL.md 中声明的技能描述。
minLength: 0
name: string
SKILL.md 中声明的技能名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
updated_at: integer
模板上次更新时的 Unix 时间戳,单位为秒。
format: int64
Environment Template Deleted
EnvironmentTemplateDeleted object { id, deleted, object }
已删除的可复用环境模板。
id: string
已删除的环境模板 ID。
minLength: 0
deleted: boolean
环境模板是否已删除,恒为 true。
object: "agent.environment.template.deleted" (default: "agent.environment.template.deleted")
对象类型,固定为 agent.environment.template.deleted。
"agent.environment.template.deleted"
会话
创建智能体会话
post /agents/sessions
创建托管智能体会话,可以同时提交初始输入。接口返回会话,或在 stream 为 true 时流式返回会话事件。参见运行会话。
请求体参数
内容类型为 application/json。
environment: EnvironmentParam
内联执行环境,或对环境模板的引用。
None object { type }
在不配置执行环境的情况下运行智能体。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { type, capability_directories, container_size, 10 more }
现有的 OpenAI 托管环境,或通过内联配置或模板新建的托管环境。
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
container_size: optional "small" or "medium" or "large"
托管容器的规格。省略时选择中等规格。
"small"
"medium"
"large"
desktop: optional object { enabled } or null
桌面配置。省略或传入 null 时继承模板设置,无模板设置时默认禁用。
enabled: boolean
是否配置桌面及其浏览器代理。
env: optional map[string] or null
向智能体提供的环境变量。
environment_id: optional string
现有的预热环境。不能与模板或内联配置同时指定。
minLength: 9, maxLength: 256
environment_template_id: optional string
可复用的托管环境模板,在内联会话配置之前应用。省略的字段继承模板,网络覆盖配置只能保持或收紧模板的网络策略。
minLength: 0, maxLength: 64
files: optional array of HostedEnvironmentFileParam or null
智能体启动前可用的文件。默认为空列表。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: optional object { access, allowed_domains, blocked_domains } or null
环境的网络访问策略。省略时,由 API 版本决定是否启用网络访问。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: optional array of string or null
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 16384
blocked_domains: optional array of string or null
网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。
minItems: 0, maxItems: 100
packages: optional object { npm, python, system } or null
要安装到环境中的软件包。软件包列表默认为空。
npm: optional array of string or null
要全局安装的 npm 软件包。默认为空列表。
minItems: 0, maxItems: 16384
python: optional array of string or null
要安装的 Python 软件包。默认为空列表。
minItems: 0, maxItems: 16384
system: optional array of string or null
要安装的系统软件包。默认为空列表。
minItems: 0, maxItems: 16384
plugins: optional array of HostedPluginParam or null
以内联 ZIP 归档提供的插件。默认为空列表。
minItems: 0, maxItems: 32
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
setup_commands: optional array of SetupCommandParam or null
按顺序执行的机密初始化命令。响应始终省略命令正文。
minItems: 0, maxItems: 16
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
skills: optional array of HostedSkillParam or null
通过 ID 引用或以内联 ZIP 归档提供的技能。默认为空列表。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
SelfHosted object { type, workspace_directory, capability_directories }
以内联方式配置的应用托管环境。
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
自托管环境中的项目绝对路径。
minLength: 0, maxLength: 1048576
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
agent: optional object { compaction, experimental, instructions, 6 more }
智能体配置。提供 agent_id 时,本次传入的字段覆盖该会话使用的已保存配置。省略 agent_id 时,必须提供 model。
compaction: optional object { async } or null
上下文压缩配置。省略时保留现有设置,传入对象时替换现有设置,传 null 或空对象时采用阻塞式压缩。
async: optional boolean or null
是否在后台压缩上下文。省略或传 null 时默认为 false。设为 true 可启用后台压缩。后台压缩可能增加词元用量。
experimental: optional object { time_awareness } (default: {})
按键合并的实验性设置。省略的设置保留现有值。
time_awareness: optional boolean
模型是否会定期收到当前时间提醒。省略时保留现有设置。
instructions: optional string or null
附加到智能体默认基础指令之后的自定义指令。省略时保留原值。
minLength: 0, maxLength: 1048576
model: optional string
智能体使用的模型。系统保留请求中的模型名称。
minLength: 0, maxLength: 1048576
multi_agent: optional MultiAgentConfigParam or null
创建和协调子智能体的配置。
enabled: boolean
是否启用子智能体工具。
max_concurrent_subagents: optional integer
可同时运行的子智能体数上限,默认为 6。
format: int64, minimum: 1, maximum: 4294967295
reasoning: optional AgentReasoningParam or null
模型推理配置。省略时保留现有设置,传 null 时恢复模型的默认推理强度。
effort: optional "none" or "minimal" or "low" or 4 more or null
模型使用的推理强度。省略时由模型选择。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: optional "concise" or "detailed" or "auto" or null
控制响应是否包含推理摘要。
"concise"
模型支持时,返回简明推理摘要。
"detailed"
模型支持时,返回详细推理摘要。
"auto"
自动选择模型支持的最详细摘要。
service_tier: optional "auto" or "default" or "flex" or 3 more or null
用于模型请求的服务层级。
"auto"
自动选择服务层级。
"default"
使用默认服务层级。
"flex"
使用 Flex 服务层级。
"priority"
使用 Priority 服务层级。
"fast"
使用 Fast 服务层级。
"ultrafast"
使用 Ultrafast 服务层级。
text: optional AgentTextParam or null
智能体生成文本的配置。
format: optional TextFormatParam or null
输出格式。省略时使用普通文本({"type": "text"})。
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: optional "low" or "medium" or "high" or null
模型应生成的文本量。与 Responses 一致,默认为 medium。
"low"
生成较少文本。
"medium"
使用默认文本量。
"high"
生成较多文本。
tools: optional array of AgentToolParam or null
智能体可用的工具。省略时继承,传入 null 时清除。最终工具列表采用紧凑 UTF-8 JSON 编码时,大小不得超过 3 MiB(3,145,728 字节)。
minItems: 0, maxItems: 16384
Function object { description, name, parameters, 3 more }
应用定义的函数。
description: string
说明函数的用途。
minLength: 0, maxLength: 1048576
name: string
函数名称。
minLength: 0, maxLength: 1048576
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean (default: false)
智能体是否无需等待函数结果即可继续。默认为 false。
defer_loading: optional boolean (default: false)
是否延迟加载函数并通过工具搜索发现。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
ProgrammaticToolCalling object { type, enabled }
允许模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
enabled: optional boolean (default: true)
是否允许从模型生成的代码调用工具。默认为 true。
Mcp object { server_label, transport, type, 5 more }
远程 MCP 服务器提供的工具。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0, maxLength: 1048576
transport: McpTransportParam
用于连接 MCP 服务器的传输方式。
HTTP object { server_url, type, authorization, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
authorization: optional string or null
发送给 MCP 服务器的授权值(如有)。
minLength: 0, maxLength: 1048576
headers: optional map[string] or null
发送给 MCP 服务器的附加 HTTP 请求头。
Stdio object { command, cwd, type, 3 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env: optional map[string] or null
为 MCP 服务器进程设置的环境变量。
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
allowed_tools: optional array of string or null
智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。
minItems: 0, maxItems: 16384
connection_origin: optional "service" or "environment" or null
选择出站 MCP HTTP 连接的来源。省略或设为 service 时使用 Managed Agents 服务网络,设为 environment 时使用会话选定的环境。
"service"
使用 Managed Agents 服务网络。
"environment"
使用会话的执行环境。
credential_id: optional string or null
用于验证此 MCP 服务器连接的已附加凭证库凭证。只有一条已附加凭证与服务器 URL 匹配时,可以省略。
minLength: 0, maxLength: 1048576
request_metadata: optional map[unknown] or null
随请求发送给此 MCP 服务器的元数据。
required: optional boolean (default: false)
是否必须在第一轮前初始化此 MCP 服务器。默认为 false。
WebSearch object { type, allowed_domains, context_size, 2 more }
网页搜索。
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
allowed_domains: optional array of string or null
可纳入搜索范围的域名。
minItems: 0, maxItems: 16384
context_size: optional "low" or "medium" or "high" or null
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置。
city: optional string or null
城市名称。
minLength: 0, maxLength: 1048576
country: optional string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0, maxLength: 1048576
region: optional string or null
地区或州的名称。
minLength: 0, maxLength: 1048576
timezone: optional string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0, maxLength: 1048576
mode: optional "disabled" or "cached" or "live" or null
网页搜索结果的来源,默认为 live。
"disabled"
关闭网页搜索。
"cached"
使用缓存的搜索结果。
"live"
搜索实时网页。
ComputerUse object { type, include_screenshots }
在 OpenAI 托管会话中使用浏览器。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
include_screenshots: optional boolean (default: false)
计算机工具的输出是否包含屏幕截图。默认为 false。
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
agent_id: optional string
已保存的可复用智能体 ID。省略 agent 时直接使用已保存的配置。
minLength: 0, maxLength: 64
input: optional string or array of AgentSessionInputMessageParam or null
创建会话时提交的初始输入。字符串是单条用户消息的简写。environment.type 为 none 时必填。非 self_hosted 环境开启 stream: true 时也必填。自托管和非流式执行环境中,此字段可选。
string
minLength: 1, maxLength: 1048576
array of AgentSessionInputMessageParam
minItems: 0, maxItems: 16384
content: array of InputContentParam
消息内容。
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
text: string
发送给模型的文本。
minLength: 0, maxLength: 1048576
type: "input_text" (default: "input_text")
对象类型,固定为 input_text。
"input_text"
InputImage object { image_url, type }
提供给模型的图像输入。
image_url: string
发送给模型的图像 URL。
minLength: 0, maxLength: 1048576
type: "input_image" (default: "input_image")
对象类型,固定为 input_image。
"input_image"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: optional "message" (default: "message")
输入条目类型,固定为 message。
"message"
metadata: optional map[string] or null
最多 16 个字符串键值对,键最长 64 个字符,值最长 512 个字符。省略或传 null 时默认为空映射。
prompt_cache_options: optional object { ttl } or null
此会话各轮次采用的默认提示词缓存时长。省略时使用模型默认值。
ttl: optional "30m" or "12h" (default: "30m")
新提示词缓存条目的最短保留时长。默认为 30 分钟。
"30m"
"12h"
review: optional "none" or "auto_review"
操作审查模式。省略时采用 none。
"none"
沿用现有执行行为,自动操作审查处于关闭状态。
"auto_review"
对适用操作进行自动审查。拒绝需要转入手动审批的操作。
stream: optional boolean (default: false)
是否使用服务端发送事件(SSE)流式返回会话事件。默认为 false。
stream_options: optional object { include_obfuscation }
事件流选项。仅在 stream 为 true 时允许使用。
include_obfuscation: optional boolean (default: true)
是否在此连接的事件中加入混淆填充数据。默认为 true。
vault_ids: optional array of string or null
本会话可访问的凭证库 ID。
minItems: 0, maxItems: 16384
返回值
AgentSession object { id, agent, created_at, 11 more }
Managed Agents 会话。
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"
示例
## 从环境变量读取 API 密钥。
## 官方示例只展示环境设置。environment.type 为 none 时,请按上方说明补充 input。
## 按实际情况指定已保存的 agent_id,或在 agent 中提供 model。
curl https://api.openai.com/v1/agents/sessions \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"environment": {
"type": "none"
}
}'
201 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"agent": {
"id": "id",
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"name": "name",
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"created_at": 0,
"environment": {
"type": "none"
},
"error": "error",
"last_active_at": 0,
"metadata": {
"foo": "string"
},
"object": "agent.session",
"required_actions": [
{
"request": {
"arguments": {},
"message": "message",
"name": "name",
"server_label": "server_label",
"type": "mcp_tool_call"
},
"request_id": "request_id",
"turn_id": "turn_id",
"type": "mcp_approval_request"
}
],
"status": "idle",
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"vault_ids": [
"string"
],
"prompt_cache_options": {
"ttl": "30m"
},
"review": "none"
}
删除智能体会话
delete /agents/sessions/{session_id}
从公开 API 中移除托管智能体会话,并返回删除确认。如果后端执行已经结束,删除会取消仍开放的公开轮次并丢弃未发布的输出。仍在运行的执行必须先取消。底层资源清理可能在后台继续。参见管理会话。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
返回值
AgentSessionDeleted object { id, deleted, object }
已从公开 API 中移除的 Managed Agents 会话。底层资源清理可能仍在后台进行。
id: string
已删除会话的 ID。
minLength: 0
deleted: boolean
会话是否已从公开 API 中移除,恒为 true。底层资源可能仍在清理中。
object: "agent.session.deleted" (default: "agent.session.deleted")
对象类型,固定为 agent.session.deleted。
"agent.session.deleted"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \
-X DELETE \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"deleted": true,
"object": "agent.session.deleted"
}
列出智能体会话
get /agents/sessions
按指定排序方式列出托管智能体会话,使用基于 ID 的分页。参见管理会话。
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
agent_id: optional string
仅返回根智能体 ID 为此值的会话。省略时返回所有智能体的会话。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
metadata: optional map[string]
使用 metadata[key]=value 提供完全匹配的字符串条件。所有键值对都必须匹配。最多 16 对,键长为 1 至 64 个字符,值最长为 512 个字符。新会话及元数据更新可能过一段时间才会反映到筛选结果中。
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of AgentSession
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
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"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
curl https://api.openai.com/v1/agents/sessions \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"agent": {
"id": "id",
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"name": "name",
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"created_at": 0,
"environment": {
"type": "none"
},
"error": "error",
"last_active_at": 0,
"metadata": {
"foo": "string"
},
"object": "agent.session",
"required_actions": [
{
"request": {
"arguments": {},
"message": "message",
"name": "name",
"server_label": "server_label",
"type": "mcp_tool_call"
},
"request_id": "request_id",
"turn_id": "turn_id",
"type": "mcp_approval_request"
}
],
"status": "idle",
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"vault_ids": [
"string"
],
"prompt_cache_options": {
"ttl": "30m"
},
"review": "none"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取智能体会话
get /agents/sessions/{session_id}
获取托管智能体会话的当前状态。参见管理会话。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
返回值
AgentSession object { id, agent, created_at, 11 more }
Managed Agents 会话。
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"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"agent": {
"id": "id",
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"name": "name",
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"created_at": 0,
"environment": {
"type": "none"
},
"error": "error",
"last_active_at": 0,
"metadata": {
"foo": "string"
},
"object": "agent.session",
"required_actions": [
{
"request": {
"arguments": {},
"message": "message",
"name": "name",
"server_label": "server_label",
"type": "mcp_tool_call"
},
"request_id": "request_id",
"turn_id": "turn_id",
"type": "mcp_approval_request"
}
],
"status": "idle",
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"vault_ids": [
"string"
],
"prompt_cache_options": {
"ttl": "30m"
},
"review": "none"
}
更新智能体会话
post /agents/sessions/{session_id}
更新会话的工具、元数据、模型、推理强度、服务层级或默认提示词缓存时长。模型设置在后续轮次生效,省略的字段保留原值。参见管理会话。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
请求体参数
内容类型为 application/json。
agent: optional object { model, reasoning, service_tier, tools }
要为本会话更新的智能体设置。省略的字段保留原值。
model: optional string
后续轮次使用的模型。省略时保留当前模型。
minLength: 0, maxLength: 1048576
reasoning: optional object { effort }
要更新的推理设置。省略时保留当前推理强度。
effort: optional "none" or "minimal" or "low" or 4 more or null
省略时保留当前推理强度。传入 null 时使用模型的默认推理强度。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
service_tier: optional "auto" or "default" or "flex" or 3 more or null
省略时保留当前服务层级。传入 null 时恢复为 auto。
"auto"
自动选择服务层级。
"default"
使用默认服务层级。
"flex"
使用 Flex 服务层级。
"priority"
使用 Priority 服务层级。
"fast"
使用 Fast 服务层级。
"ultrafast"
使用 Ultrafast 服务层级。
tools: optional array of AgentToolParam or null
替换会话工具。函数与 MCP 服务器在下一次模型调用时变更,内置工具最迟在下一轮变更。省略时保留当前工具,传入 null 或空数组时清除。
minItems: 0, maxItems: 16384
Function object { description, name, parameters, 3 more }
应用定义的函数。
description: string
说明函数的用途。
minLength: 0, maxLength: 1048576
name: string
函数名称。
minLength: 0, maxLength: 1048576
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean (default: false)
智能体是否无需等待函数结果即可继续。默认为 false。
defer_loading: optional boolean (default: false)
是否延迟加载函数并通过工具搜索发现。
ToolSearch object { type }
发现延迟加载的函数工具,并将其加载到模型上下文。
type: "tool_search" (default: "tool_search")
对象类型,恒为 tool_search。
"tool_search"
ProgrammaticToolCalling object { type, enabled }
允许模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
enabled: optional boolean (default: true)
是否允许从模型生成的代码调用工具。默认为 true。
Mcp object { server_label, transport, type, 5 more }
远程 MCP 服务器提供的工具。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0, maxLength: 1048576
transport: McpTransportParam
用于连接 MCP 服务器的传输方式。
HTTP object { server_url, type, authorization, headers }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0, maxLength: 1048576
type: "http" (default: "http")
对象类型,恒为 http。
"http"
authorization: optional string or null
发送给 MCP 服务器的授权值(如有)。
minLength: 0, maxLength: 1048576
headers: optional map[string] or null
发送给 MCP 服务器的附加 HTTP 请求头。
Stdio object { command, cwd, type, 3 more }
以本地进程方式启动 MCP 服务器。
command: string
用于启动 MCP 服务器的命令。
minLength: 0, maxLength: 1048576
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0, maxLength: 1048576
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
args: optional array of string or null
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 16384
env: optional map[string] or null
为 MCP 服务器进程设置的环境变量。
env_vars: optional array of string or null
要从选定执行环境继承的环境变量名称。
minItems: 0, maxItems: 16384
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
allowed_tools: optional array of string or null
智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。
minItems: 0, maxItems: 16384
connection_origin: optional "service" or "environment" or null
选择出站 MCP HTTP 连接的来源。省略或设为 service 时使用 Managed Agents 服务网络,设为 environment 时使用会话选定的环境。
"service"
使用 Managed Agents 服务网络。
"environment"
使用会话的执行环境。
credential_id: optional string or null
用于验证此 MCP 服务器连接的已附加凭证库凭证。只有一条已附加凭证与服务器 URL 匹配时,可以省略。
minLength: 0, maxLength: 1048576
request_metadata: optional map[unknown] or null
随请求发送给此 MCP 服务器的元数据。
required: optional boolean (default: false)
是否必须在第一轮前初始化此 MCP 服务器。默认为 false。
WebSearch object { type, allowed_domains, context_size, 2 more }
网页搜索。
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
allowed_domains: optional array of string or null
可纳入搜索范围的域名。
minItems: 0, maxItems: 16384
context_size: optional "low" or "medium" or "high" or null
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置。
city: optional string or null
城市名称。
minLength: 0, maxLength: 1048576
country: optional string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0, maxLength: 1048576
region: optional string or null
地区或州的名称。
minLength: 0, maxLength: 1048576
timezone: optional string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0, maxLength: 1048576
mode: optional "disabled" or "cached" or "live" or null
网页搜索结果的来源,默认为 live。
"disabled"
关闭网页搜索。
"cached"
使用缓存的搜索结果。
"live"
搜索实时网页。
ComputerUse object { type, include_screenshots }
在 OpenAI 托管会话中使用浏览器。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
include_screenshots: optional boolean (default: false)
计算机工具的输出是否包含屏幕截图。默认为 false。
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
metadata: optional map[string] or null
替换全部元数据。省略时保留原值,传 null 或 {} 可清除。最多 16 个字符串键值对,键最长 64 个字符,值最长 512 个字符。
prompt_cache_options: optional object { ttl } or null
后续轮次采用的默认提示词缓存时长。传入 null 可清除会话默认值。
ttl: optional "30m" or "12h" (default: "30m")
新提示词缓存条目的最短保留时长。默认为 30 分钟。
"30m"
"12h"
review: optional "none" or "auto_review"
新建根轮次的默认操作审查模式。既有轮次及其子智能体沿用各自的审查模式。
"none"
沿用现有执行行为,自动操作审查处于关闭状态。
"auto_review"
对适用操作进行自动审查。拒绝需要转入手动审批的操作。
返回值
AgentSession object { id, agent, created_at, 11 more }
Managed Agents 会话。
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"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 此官方示例仅展示请求地址和请求头。发送前请按上方参数补充 JSON 请求体及 Content-Type 请求头。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \
-X POST \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"agent": {
"id": "id",
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"name": "name",
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"created_at": 0,
"environment": {
"type": "none"
},
"error": "error",
"last_active_at": 0,
"metadata": {
"foo": "string"
},
"object": "agent.session",
"required_actions": [
{
"request": {
"arguments": {},
"message": "message",
"name": "name",
"server_label": "server_label",
"type": "mcp_tool_call"
},
"request_id": "request_id",
"turn_id": "turn_id",
"type": "mcp_approval_request"
}
],
"status": "idle",
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"vault_ids": [
"string"
],
"prompt_cache_options": {
"ttl": "30m"
},
"review": "none"
}
会话产物
下载会话产物内容
get /agents/sessions/{session_id}/artifacts/{artifact_id}/content
下载不可变会话产物的字节。执行环境过期后仍可下载。参见会话产物。
路径参数
session_id: string
拥有此产物的会话 ID。
minLength: 0, maxLength: 1048576
artifact_id: string
不可变会话产物的 ID。
minLength: 0, maxLength: 1048576
返回值
file
内容类型为 application/octet-stream。
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 ARTIFACT_ID 设置为目标产物的 ID。
## 响应为二进制内容。下载文件时可给 curl 添加 --output 及目标文件名。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts/$ARTIFACT_ID/content \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
删除会话产物
delete /agents/sessions/{session_id}/artifacts/{artifact_id}
删除不可变会话产物。执行环境中的原文件和原始 Files API 对象均保留。参见会话产物。
路径参数
session_id: string
拥有此产物的会话 ID。
minLength: 0, maxLength: 1048576
artifact_id: string
不可变会话产物的 ID。
minLength: 0, maxLength: 1048576
返回值
SessionArtifactDeleted object { id, deleted, object }
不可变会话产物的删除确认。
id: string
已删除会话产物的 ID。
minLength: 0
deleted: boolean
会话产物是否已删除,恒为 true。
object: "agent.session.artifact.deleted" (default: "agent.session.artifact.deleted")
对象类型,固定为 agent.session.artifact.deleted。
"agent.session.artifact.deleted"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 ARTIFACT_ID 设置为目标产物的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts/$ARTIFACT_ID \
-X DELETE \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"deleted": true,
"object": "agent.session.artifact.deleted"
}
列出会话产物
get /agents/sessions/{session_id}/artifacts
列出托管会话已完成轮次发布的不可变产物。参见会话产物。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
environment_id: optional string or null
仅列出由此环境生成的产物。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of SessionArtifact
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
不可变产物的 ID。
minLength: 0
created_at: integer
产物发布时的 Unix 时间戳,单位为秒。
format: int64
environment_id: string
生成产物的环境 ID。
minLength: 0
object: "agent.session.artifact" (default: "agent.session.artifact")
对象类型,固定为 agent.session.artifact。
"agent.session.artifact"
path: string
文件在执行环境中的原始绝对路径。
minLength: 0
session_id: string
拥有此产物的会话 ID。
minLength: 0
size_bytes: integer
不可变产物的大小,单位为字节。
format: int64, minimum: 0
turn_id: string
发布此产物的已完成轮次 ID。
minLength: 0
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"created_at": 0,
"environment_id": "environment_id",
"object": "agent.session.artifact",
"path": "path",
"session_id": "session_id",
"size_bytes": 0,
"turn_id": "turn_id"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取会话产物元数据
get /agents/sessions/{session_id}/artifacts/{artifact_id}
获取某个持久会话产物的不可变元数据。参见会话产物。
路径参数
session_id: string
拥有此产物的会话 ID。
minLength: 0, maxLength: 1048576
artifact_id: string
不可变会话产物的 ID。
minLength: 0, maxLength: 1048576
返回值
SessionArtifact object { id, created_at, environment_id, 5 more }
由托管会话中已完成的轮次发布的不可变文件。
id: string
不可变产物的 ID。
minLength: 0
created_at: integer
产物发布时的 Unix 时间戳,单位为秒。
format: int64
environment_id: string
生成产物的环境 ID。
minLength: 0
object: "agent.session.artifact" (default: "agent.session.artifact")
对象类型,固定为 agent.session.artifact。
"agent.session.artifact"
path: string
文件在执行环境中的原始绝对路径。
minLength: 0
session_id: string
拥有此产物的会话 ID。
minLength: 0
size_bytes: integer
不可变产物的大小,单位为字节。
format: int64, minimum: 0
turn_id: string
发布此产物的已完成轮次 ID。
minLength: 0
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 ARTIFACT_ID 设置为目标产物的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts/$ARTIFACT_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"environment_id": "environment_id",
"object": "agent.session.artifact",
"path": "path",
"session_id": "session_id",
"size_bytes": 0,
"turn_id": "turn_id"
}
资源类型
Session Artifact
SessionArtifact object { id, created_at, environment_id, 5 more }
由托管会话中已完成的轮次发布的不可变文件。
id: string
不可变产物的 ID。
minLength: 0
created_at: integer
产物发布时的 Unix 时间戳,单位为秒。
format: int64
environment_id: string
生成产物的环境 ID。
minLength: 0
object: "agent.session.artifact" (default: "agent.session.artifact")
对象类型,固定为 agent.session.artifact。
"agent.session.artifact"
path: string
文件在执行环境中的原始绝对路径。
minLength: 0
session_id: string
拥有此产物的会话 ID。
minLength: 0
size_bytes: integer
不可变产物的大小,单位为字节。
format: int64, minimum: 0
turn_id: string
发布此产物的已完成轮次 ID。
minLength: 0
Session Artifact Deleted
SessionArtifactDeleted object { id, deleted, object }
不可变会话产物的删除确认。
id: string
已删除会话产物的 ID。
minLength: 0
deleted: boolean
会话产物是否已删除,恒为 true。
object: "agent.session.artifact.deleted" (default: "agent.session.artifact.deleted")
对象类型,固定为 agent.session.artifact.deleted。
"agent.session.artifact.deleted"
会话事件
提交会话输入事件
post /agents/sessions/{session_id}/events
向托管智能体会话提交消息、取消、工具结果或计算机使用审批响应事件。如果后端执行已结束,但该轮仍显示为开放,可通过取消将其恢复到已取消状态。未发布的输出将被丢弃,已保存的结果、已发布的文件和已有的终态结果均会保留。HTTP 202 表示已受理,最终完成状态需另行确认。参见会话事件。
请求头参数
"Idempotency-Key": optional string
minLength: 1, maxLength: 256
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
请求体参数
内容类型为 application/json。
events: array of AgentSessionInputParam
要提交到会话的输入事件。
minItems: 0, maxItems: 16384
AgentSessionInputMcpApprovalRequestResult object { request_id, response, type }
响应待处理的 MCP 工具调用审批请求。
request_id: string
必需操作提供的不透明审批 ID。
minLength: 0, maxLength: 1048576
response: object { decision, type }
用户对待处理 MCP 工具调用的决定。
decision: "approve" or "deny" or "cancel"
取消此请求并关闭提示,会话和当前轮次仍然保留。
"approve"
"deny"
"cancel"
type: "mcp_tool_call" (default: "mcp_tool_call")
对象类型,固定为 mcp_tool_call。
"mcp_tool_call"
type: "agent.session.input.mcp_approval_request_result" (default: "agent.session.input.mcp_approval_request_result")
对象类型,固定为 agent.session.input.mcp_approval_request_result。
"agent.session.input.mcp_approval_request_result"
AgentSessionInputComputerUseApprovalRequestResult object { request_id, response, type }
响应待处理的计算机使用审批请求。
request_id: string
必需操作提供的已注册请求 ID。
minLength: 0, maxLength: 1048576
response: AgentBrowserAuthenticationSubmitParam or AgentBrowserAuthenticationCancelParam or AgentBrowserOriginAccessParam
此请求类型对应的响应。
AgentBrowserAuthenticationSubmitParam object { action, fields, type, selected_option }
action: "submit" (default: "submit")
"submit"
fields: array of object { field_id, value }
最多为必需操作中的 6 个活动字段提供值。提交的字段值映射与选定选项合计不得超过 120 KiB 的 JSON。
minItems: 0, maxItems: 6
field_id: string
必需操作提供的字段 ID。
minLength: 0, maxLength: 1048576
value: string
要填入已注册控件的值。
minLength: 0, maxLength: 16384
type: "browser_authentication" (default: "browser_authentication")
"browser_authentication"
selected_option: optional string or null
选中的方式。必需操作包含可选方式时,此项必填。
minLength: 0, maxLength: 1048576
AgentBrowserAuthenticationCancelParam object { action, type }
action: "cancel" (default: "cancel")
"cancel"
type: "browser_authentication" (default: "browser_authentication")
"browser_authentication"
AgentBrowserOriginAccessParam object { decision, type }
decision: "approve" or "deny" or "cancel"
允许、拒绝或取消所请求的源站访问。
"approve"
允许浏览器访问此源站。
"deny"
拒绝访问此源站。
"cancel"
关闭此请求,访问保持未获批准。
type: "browser_origin_access" (default: "browser_origin_access")
"browser_origin_access"
type: "agent.session.input.computer_use_approval_request_result" (default: "agent.session.input.computer_use_approval_request_result")
对象类型,固定为 agent.session.input.computer_use_approval_request_result。
"agent.session.input.computer_use_approval_request_result"
AgentSessionInputMessage object { input, type }
添加一条或多条用户消息并开始一轮交互。
input: array of AgentSessionInputMessageParam
要添加到会话的用户消息。
minItems: 0, maxItems: 16384
content: array of InputContentParam
消息内容。
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
text: string
发送给模型的文本。
minLength: 0, maxLength: 1048576
type: "input_text" (default: "input_text")
对象类型,固定为 input_text。
"input_text"
InputImage object { image_url, type }
提供给模型的图像输入。
image_url: string
发送给模型的图像 URL。
minLength: 0, maxLength: 1048576
type: "input_image" (default: "input_image")
对象类型,固定为 input_image。
"input_image"
role: "user" (default: "user")
消息作者的角色,固定为 user。
"user"
type: optional "message" (default: "message")
输入条目类型,固定为 message。
"message"
type: "agent.session.input.message" (default: "agent.session.input.message")
对象类型,固定为 agent.session.input.message。
"agent.session.input.message"
AgentSessionInputCancel object { type }
取消会话中正在进行的轮次。
type: "agent.session.input.cancel" (default: "agent.session.input.cancel")
对象类型,固定为 agent.session.input.cancel。
"agent.session.input.cancel"
AgentSessionInputToolResult object { call_id, success, turn_id, 3 more }
提交函数调用的结果。
call_id: string
函数调用 ID。
minLength: 0, maxLength: 1048576
success: boolean
函数调用是否成功。
turn_id: string
请求函数调用的轮次 ID。
minLength: 0, maxLength: 1048576
type: "agent.session.input.tool_result" (default: "agent.session.input.tool_result")
对象类型,固定为 agent.session.input.tool_result。
"agent.session.input.tool_result"
error: optional string or null
调用失败时返回的错误消息。
minLength: 0, maxLength: 1048576
output: optional AgentFunctionCallOutputParam or null
调用成功时返回的函数结果。
string
minLength: 0, maxLength: 1048576
array of InputContentParam
minItems: 0, maxItems: 16384
InputText object { text, type }
提供给模型的文本输入。
InputImage object { image_url, type }
提供给模型的图像输入。
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 request_id 替换为本会话待审批请求的实际 ID,按用户的审批决定提交。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/events \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"events": [
{
"request_id": "request_id",
"response": {
"decision": "approve",
"type": "mcp_tool_call"
},
"type": "agent.session.input.mcp_approval_request_result"
}
]
}'
流式接收会话事件
get /agents/sessions/{session_id}/events
流式接收智能体会话的实时事件。参见会话事件。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
查询参数
include_obfuscation: optional boolean (default: true)
是否在此连接的事件中加入混淆填充数据。默认为 true。
返回值
AgentSessionEvent = AgentSessionErrorEvent or AgentSessionEnvironmentReadyEvent or AgentSessionEnvironmentSuspendedEvent or 30 more
Managed Agents 会话发出的事件。
AgentSessionErrorEvent object { error, event_id, session_id, 2 more }
轮次或会话失败时发出。
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
AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 3 more }
托管会话环境可以连接时发出。
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
AgentSessionEnvironmentSuspendedEvent object { environment, event_id, session_id, 3 more }
空闲的托管会话环境保存检查点并停止后发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionEnvironmentExpiredEvent object { environment, event_id, session_id, 3 more }
已挂起的托管会话环境及其检查点过期后发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionEnvironmentResetEvent object { environment_id, event_id, reset_count, 4 more }
托管沙箱被替换后发出。对话历史保留,旧沙箱中的文件改动和进程不会延续到新沙箱。
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
AgentOutputCommandExecutionOutputDeltaEvent object { delta, event_id, item_id, 5 more }
命令执行产生新增输出时发出。
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
AgentSessionCreatedEvent object { event_id, session, type, obfuscation }
创建会话时发出。
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
AgentSessionTurnCreatedEvent object { event_id, session_id, turn, 3 more }
创建轮次时发出。
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,已记录的用量可能变化。
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
AgentSessionTurnInProgressEvent object { event_id, session_id, turn, 3 more }
轮次开始运行时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session_id: string
与事件关联的会话 ID。
minLength: 0
turn: Turn
轮次开始运行时的状态。
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
AgentSessionTurnCompletedEvent object { event_id, session_id, turn, 4 more }
轮次完成时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session_id: string
与事件关联的会话 ID。
minLength: 0
turn: Turn
已完成的轮次。
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
AgentSessionTurnFailedEvent object { event_id, session_id, turn, 4 more }
轮次失败时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session_id: string
与事件关联的会话 ID。
minLength: 0
turn: Turn
已失败的轮次。
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
AgentSessionTurnCancelledEvent object { event_id, session_id, turn, 4 more }
轮次取消时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session_id: string
与事件关联的会话 ID。
minLength: 0
turn: Turn
已取消的轮次。
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
AgentSessionTurnItemAddedEvent object { event_id, item, output_index, 4 more }
将条目添加到轮次时发出。
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
AgentSessionIdleEvent object { event_id, session, type, obfuscation }
会话进入空闲状态时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session: AgentSession
已进入空闲状态的会话。
type: "agent.session.idle" (default: "agent.session.idle")
对象类型,固定为 agent.session.idle。
"agent.session.idle"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionInProgressEvent object { event_id, session, type, obfuscation }
会话开始处理一轮交互时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session: AgentSession
已开始处理的会话。
type: "agent.session.in_progress" (default: "agent.session.in_progress")
对象类型,固定为 agent.session.in_progress。
"agent.session.in_progress"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionRequiresActionEvent object { event_id, session, type, obfuscation }
会话等待一个或多个必需操作时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session: AgentSession
会话及其当前必需操作。
type: "agent.session.requires_action" (default: "agent.session.requires_action")
对象类型,固定为 agent.session.requires_action。
"agent.session.requires_action"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionFailedEvent object { event_id, session, type, obfuscation }
会话失败时发出。
event_id: string
事件的唯一 ID。
minLength: 0
session: AgentSession
已失败的会话。
type: "agent.session.failed" (default: "agent.session.failed")
对象类型,固定为 agent.session.failed。
"agent.session.failed"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 3 more }
准备会话环境时发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 3 more }
会话环境连接时发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 3 more }
会话环境断开连接时发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 3 more }
会话环境发生故障时发出。
environment: AgentSessionEnvironmentState
环境的当前状态。
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
AgentSessionSubagentCreatedEvent object { event_id, subagent, type, obfuscation }
创建子智能体时发出。
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 }
智能体生成的一段文本内容。
EncryptedContent object { encrypted_content, type }
智能体之间交换的加密内容。
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
AgentSessionSubagentActiveEvent object { event_id, subagent, type, obfuscation }
已关闭的子智能体成功恢复时发出。
event_id: string
事件的唯一 ID。
minLength: 0
subagent: Subagent
已恢复的子智能体。
type: "agent.session.subagent.active" (default: "agent.session.subagent.active")
对象类型,固定为 agent.session.subagent.active。
"agent.session.subagent.active"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionSubagentClosedEvent object { event_id, subagent, type, obfuscation }
子智能体关闭时发出。
event_id: string
事件的唯一 ID。
minLength: 0
subagent: Subagent
已关闭的子智能体。
type: "agent.session.subagent.closed" (default: "agent.session.subagent.closed")
对象类型,固定为 agent.session.subagent.closed。
"agent.session.subagent.closed"
obfuscation: optional string
随机字母数字填充。启用流混淆时提供。
minLength: 0
AgentSessionTurnItemDoneEvent object { event_id, item, output_index, 4 more }
输出条目完成时发出。
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。
phase: "commentary" or "final_answer" or null
助手消息所处的阶段。
"commentary"
智能体工作时生成的过程说明。
"final_answer"
智能体的最终回答。
role: "assistant" (default: "assistant")
消息作者的角色,固定为 assistant。
"assistant"
status: AgentOutputItemStatus
消息的状态。
turn_id: string
包含此条目的轮次 ID。
minLength: 0
type: "message" (default: "message")
类型,固定为message。
"message"
AgentReasoningItem object { id, status, summary, 2 more }
智能体生成的推理条目。
AgentFunctionCallItem object { id, arguments, call_id, 4 more }
智能体生成的函数调用。
AgentMcpCallItem object { id, arguments, error, 6 more }
调用 MCP 服务器工具的记录。
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 }
智能体生成的网页搜索调用。
AgentCommandExecutionItem object { id, command, cwd, 6 more }
智能体生成的命令执行记录。
AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }
创建子智能体的请求。
AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }
向另一智能体发送输入的请求。
AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }
恢复子智能体的请求。
AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }
等待一个或多个子智能体的请求。
AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }
中断子智能体当前轮次的请求。该子智能体仍可使用。
AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }
关闭子智能体的请求。
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
AgentSessionTurnContentPartAddedEvent object { content_index, event_id, item_id, 6 more }
添加输出文本内容部分时发出。
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
初始内容部分。
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
AgentSessionTurnContentPartDoneEvent object { content_index, event_id, item_id, 6 more }
输出内容部分完成时发出。
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
已完成的内容部分。
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
AgentSessionTurnOutputTextDeltaEvent object { content_index, delta, event_id, 6 more }
向输出文本内容部分追加文本时发出。
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
AgentSessionTurnOutputTextDoneEvent object { content_index, event_id, item_id, 6 more }
输出文本内容部分完成时发出。
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
AgentSessionTurnReasoningSummaryPartAddedEvent object { event_id, item_id, output_index, 6 more }
添加推理摘要内容部分时发出。
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。
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
AgentSessionTurnReasoningSummaryPartDoneEvent object { event_id, item_id, output_index, 7 more }
推理摘要部分完成时发出。
event_id: string
事件的唯一 ID。
minLength: 0
item_id: string
推理条目的 ID。
minLength: 0
output_index: integer
条目在轮次输出中的索引。
format: int64, minimum: 0, maximum: 4294967295
part: SummaryText
已完成的摘要部分。
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
AgentSessionTurnReasoningSummaryTextDeltaEvent object { delta, event_id, item_id, 6 more }
向推理摘要追加文本时发出。
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
AgentSessionTurnReasoningSummaryTextDoneEvent object { event_id, item_id, output_index, 6 more }
推理摘要的内容部分完成时发出。
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
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 持续接收事件时,可以给 curl 添加 --no-buffer。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/events \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
会话条目
列出会话条目
get /agents/sessions/{session_id}/items
列出会话根智能体生成的条目,包括它与子智能体的交互。每个子智能体有独立的条目历史。参见检查智能体输出。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of AgentSessionItem
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
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"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/items \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"content": [
{
"text": "text",
"type": "input_text"
}
],
"phase": "commentary",
"role": "user",
"status": "in_progress",
"turn_id": "turn_id",
"type": "message"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
子智能体
列出会话子智能体
get /agents/sessions/{session_id}/subagents
列出会话中的子智能体,包括嵌套及已关闭的子智能体。参见子智能体工作流。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of Subagent
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
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"
子智能体已关闭。
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"closed_at": 0,
"instructions": [
{
"text": "text",
"type": "output_text"
}
],
"name": "name",
"object": "agent.session.subagent",
"opened_at": 0,
"parent_agent_id": "parent_agent_id",
"session_id": "session_id",
"status": "active"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取会话子智能体
get /agents/sessions/{session_id}/subagents/{subagent_id}
获取属于此会话的子智能体。参见子智能体工作流。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
subagent_id: string
此会话中的子智能体 ID。
minLength: 0, maxLength: 1048576
返回值
Subagent object { id, closed_at, instructions, 6 more }
在会话中创建的子智能体。
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"
子智能体已关闭。
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 SUBAGENT_ID 设置为目标子智能体的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"closed_at": 0,
"instructions": [
{
"text": "text",
"type": "output_text"
}
],
"name": "name",
"object": "agent.session.subagent",
"opened_at": 0,
"parent_agent_id": "parent_agent_id",
"session_id": "session_id",
"status": "active"
}
会话条目
列出子智能体条目
get /agents/sessions/{session_id}/subagents/{subagent_id}/items
列出此子智能体在所有轮次中生成的自身条目。参见子智能体工作流。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
subagent_id: string
此会话中的子智能体 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of AgentSessionItem
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
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"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 SUBAGENT_ID 设置为目标子智能体的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/items \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"content": [
{
"text": "text",
"type": "input_text"
}
],
"phase": "commentary",
"role": "user",
"status": "in_progress",
"turn_id": "turn_id",
"type": "message"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
轮次
列出子智能体轮次
get /agents/sessions/{session_id}/subagents/{subagent_id}/turns
列出此子智能体的全部轮次,包括恢复后进行的轮次。参见子智能体工作流。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
subagent_id: string
此会话中的子智能体 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of Turn
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
轮次 ID。
minLength: 0
agent_id: string
执行本轮的智能体 ID。
minLength: 0
completed_at: integer or null
轮次进入终态的 Unix 时间戳,单位为秒。
format: int64
created_at: integer
用于按创建时间排序的 Unix 时间戳,单位为秒。子智能体轮次优先使用开始时间,其次使用完成时间,前两者均不可用时使用子智能体打开的时间。
format: int64
error: SessionTurnError or null
可向客户显示的错误。仅轮次失败时为非空值。
code: "context_length_exceeded" or "max_output_tokens" or "usage_limit_exceeded" or 21 more
稳定的、可供程序识别的失败类别。
"context_length_exceeded"
请求超出模型的上下文窗口。
"max_output_tokens"
模型完成响应之前已达到输出词元上限。
"usage_limit_exceeded"
组织已达到用量、套餐或计费限制。
"api_key_spend_limit_exceeded"
API 密钥已达到强制支出上限。
"project_spend_limit_exceeded"
项目已达到强制支出上限。
"organization_spend_limit_exceeded"
组织已达到强制支出上限。
"organization_usage_limit_exceeded"
组织已达到 OpenAI 分配的用量上限。
"billing_not_active"
账户尚未启用计费。
"credit_balance_exhausted"
组织的 API 余额已经用尽。
"rate_limit_exceeded"
请求超过可用的速率限制。
"flex_unavailable"
Flex 处理暂时不可用。
"server_overloaded"
模型服务暂时过载。
"cyber_policy"
请求因安全策略被拒绝。
"misalignment_policy_violation"
请求被安全系统拦截。
"connection_failed"
请求未能连接到模型服务。
"server_error"
模型服务遇到意外错误。
"authentication_error"
API 凭证无效或权限不足。
"invalid_request"
请求包含无效输入或配置。
"resource_not_found"
请求的模型或资源不可用。
"sandbox_error"
请求未能在其执行环境中完成。
"executor_version_incompatible"
执行器必须升级后才能运行此轮。
"active_turn_not_steerable"
请求运行期间,会话无法接收额外输入。
"request_timeout"
模型服务响应前,请求已超时。
"internal_error"
意外的内部错误导致会话请求未能完成。
message: string
可向客户显示的失败原因。
minLength: 0
object: "agent.session.turn" (default: "agent.session.turn")
对象类型,固定为 agent.session.turn。
"agent.session.turn"
session_id: string
此轮次所属会话的 ID。
minLength: 0
started_at: integer or null
轮次开始时的 Unix 时间戳,单位为秒。
format: int64
status: "queued" or "in_progress" or "waiting" or 3 more
轮次当前的状态。
"queued"
轮次正在等待开始。
"in_progress"
轮次正在进行。
"waiting"
轮次正在等待外部输入。
"completed"
轮次已成功完成。
"failed"
轮次失败。
"cancelled"
轮次已取消。
subagent_id: string or null
执行此轮的子智能体 ID(如适用)。
minLength: 0
usage: TokenUsage or null
本轮可统计到的词元用量。用量未知时为 null,已记录的用量可能变化。
input_tokens: integer
智能体使用的输入词元数。
format: int64
input_tokens_details: object { cached_tokens }
智能体输入词元用量的明细。
cached_tokens: integer
从提示词缓存中读取的输入词元数。
format: int64
output_tokens: integer
智能体生成的输出词元数。
format: int64
output_tokens_details: object { reasoning_tokens }
智能体输出词元用量的明细。
reasoning_tokens: integer
用于推理的输出词元数。
format: int64
total_tokens: integer
智能体使用的输入词元与输出词元的总数。
format: int64
prompt_cache_options: optional object { ttl } or null
本轮开始时选用的提示词缓存时长,可继承会话的缓存生存时间。使用模型默认值或未记录缓存时长时为 null。
ttl: "30m" or "12h"
"30m"
"12h"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 SUBAGENT_ID 设置为目标子智能体的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/turns \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"agent_id": "agent_id",
"completed_at": 0,
"created_at": 0,
"error": {
"code": "context_length_exceeded",
"message": "message"
},
"object": "agent.session.turn",
"session_id": "session_id",
"started_at": 0,
"status": "queued",
"subagent_id": "subagent_id",
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"prompt_cache_options": {
"ttl": "30m"
}
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取子智能体轮次
get /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}
获取属于此子智能体的一轮交互。参见子智能体工作流。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
subagent_id: string
此会话中的子智能体 ID。
minLength: 0, maxLength: 1048576
turn_id: string
属于此子智能体的轮次 ID。
minLength: 0, maxLength: 1048576
返回值
Turn object { id, agent_id, completed_at, 9 more }
会话轮次的标准公开表示。
id: string
轮次 ID。
minLength: 0
agent_id: string
执行本轮的智能体 ID。
minLength: 0
completed_at: integer or null
轮次进入终态的 Unix 时间戳,单位为秒。
format: int64
created_at: integer
用于按创建时间排序的 Unix 时间戳,单位为秒。子智能体轮次优先使用开始时间,其次使用完成时间,前两者均不可用时使用子智能体打开的时间。
format: int64
error: SessionTurnError or null
可向客户显示的错误。仅轮次失败时为非空值。
code: "context_length_exceeded" or "max_output_tokens" or "usage_limit_exceeded" or 21 more
稳定的、可供程序识别的失败类别。
"context_length_exceeded"
请求超出模型的上下文窗口。
"max_output_tokens"
模型完成响应之前已达到输出词元上限。
"usage_limit_exceeded"
组织已达到用量、套餐或计费限制。
"api_key_spend_limit_exceeded"
API 密钥已达到强制支出上限。
"project_spend_limit_exceeded"
项目已达到强制支出上限。
"organization_spend_limit_exceeded"
组织已达到强制支出上限。
"organization_usage_limit_exceeded"
组织已达到 OpenAI 分配的用量上限。
"billing_not_active"
账户尚未启用计费。
"credit_balance_exhausted"
组织的 API 余额已经用尽。
"rate_limit_exceeded"
请求超过可用的速率限制。
"flex_unavailable"
Flex 处理暂时不可用。
"server_overloaded"
模型服务暂时过载。
"cyber_policy"
请求因安全策略被拒绝。
"misalignment_policy_violation"
请求被安全系统拦截。
"connection_failed"
请求未能连接到模型服务。
"server_error"
模型服务遇到意外错误。
"authentication_error"
API 凭证无效或权限不足。
"invalid_request"
请求包含无效输入或配置。
"resource_not_found"
请求的模型或资源不可用。
"sandbox_error"
请求未能在其执行环境中完成。
"executor_version_incompatible"
执行器必须升级后才能运行此轮。
"active_turn_not_steerable"
请求运行期间,会话无法接收额外输入。
"request_timeout"
模型服务响应前,请求已超时。
"internal_error"
意外的内部错误导致会话请求未能完成。
message: string
可向客户显示的失败原因。
minLength: 0
object: "agent.session.turn" (default: "agent.session.turn")
对象类型,固定为 agent.session.turn。
"agent.session.turn"
session_id: string
此轮次所属会话的 ID。
minLength: 0
started_at: integer or null
轮次开始时的 Unix 时间戳,单位为秒。
format: int64
status: "queued" or "in_progress" or "waiting" or 3 more
轮次当前的状态。
"queued"
轮次正在等待开始。
"in_progress"
轮次正在进行。
"waiting"
轮次正在等待外部输入。
"completed"
轮次已成功完成。
"failed"
轮次失败。
"cancelled"
轮次已取消。
subagent_id: string or null
执行此轮的子智能体 ID(如适用)。
minLength: 0
usage: TokenUsage or null
本轮可统计到的词元用量。用量未知时为 null,已记录的用量可能变化。
input_tokens: integer
智能体使用的输入词元数。
format: int64
input_tokens_details: object { cached_tokens }
智能体输入词元用量的明细。
cached_tokens: integer
从提示词缓存中读取的输入词元数。
format: int64
output_tokens: integer
智能体生成的输出词元数。
format: int64
output_tokens_details: object { reasoning_tokens }
智能体输出词元用量的明细。
reasoning_tokens: integer
用于推理的输出词元数。
format: int64
total_tokens: integer
智能体使用的输入词元与输出词元的总数。
format: int64
prompt_cache_options: optional object { ttl } or null
本轮开始时选用的提示词缓存时长,可继承会话的缓存生存时间。使用模型默认值或未记录缓存时长时为 null。
ttl: "30m" or "12h"
"30m"
"12h"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 SUBAGENT_ID 设置为目标子智能体的 ID。
## 将 TURN_ID 设置为目标轮次的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/turns/$TURN_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"agent_id": "agent_id",
"completed_at": 0,
"created_at": 0,
"error": {
"code": "context_length_exceeded",
"message": "message"
},
"object": "agent.session.turn",
"session_id": "session_id",
"started_at": 0,
"status": "queued",
"subagent_id": "subagent_id",
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"prompt_cache_options": {
"ttl": "30m"
}
}
会话条目
列出子智能体轮次条目
get /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items
列出此子智能体某一轮次中的条目。参见子智能体工作流。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
subagent_id: string
此会话中的子智能体 ID。
minLength: 0, maxLength: 1048576
turn_id: string
属于此子智能体的轮次 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of AgentSessionItem
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
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"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 SUBAGENT_ID 设置为目标子智能体的 ID。
## 将 TURN_ID 设置为目标轮次的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/turns/$TURN_ID/items \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"content": [
{
"text": "text",
"type": "input_text"
}
],
"phase": "commentary",
"role": "user",
"status": "in_progress",
"turn_id": "turn_id",
"type": "message"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
追踪记录
列出会话追踪记录
get /agents/sessions/{session_id}/traces
以 OTLP JSON 格式列出已发布的根轮次追踪记录,按轮次创建时间及 ID 排序。未发布的记录会被跳过。每页返回读取时可用的数据,稍后生成的记录要在后续请求中读取。单次请求的追踪数据读取和 JSON 响应均受 16 MiB 限制。超出时减少单次请求的记录数量。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of SessionTrace
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
根轮次 ID。可用作分页锚点。
minLength: 0
created_at: integer
创建根轮次时的 Unix 时间戳,单位为秒。
format: int64
object: "agent.session.trace" (default: "agent.session.trace")
对象类型,固定为 agent.session.trace。
"agent.session.trace"
otlp: map[unknown]
包含 resourceSpans 的 OTLP JSON ExportTraceServiceRequest。响应只包含读取时已经发布的数据。
session_id: string
此追踪记录所属的会话。
minLength: 0
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/traces \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"created_at": 0,
"object": "agent.session.trace",
"otlp": {
"foo": "bar"
},
"session_id": "session_id"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
资源类型
Session Trace
SessionTrace object { id, created_at, object, 2 more }
id: string
根轮次 ID。可用作分页锚点。
minLength: 0
created_at: integer
创建根轮次时的 Unix 时间戳,单位为秒。
format: int64
object: "agent.session.trace" (default: "agent.session.trace")
对象类型,固定为 agent.session.trace。
"agent.session.trace"
otlp: map[unknown]
包含 resourceSpans 的 OTLP JSON ExportTraceServiceRequest。响应只包含读取时已经发布的数据。
session_id: string
此追踪记录所属的会话。
minLength: 0
轮次
列出会话轮次
get /agents/sessions/{session_id}/turns
按创建时间和轮次 ID 列出轮次。在指定排序下,游标 after 对应的轮次不会包含在返回结果中。参见会话轮次。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of Turn
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
轮次 ID。
minLength: 0
agent_id: string
执行本轮的智能体 ID。
minLength: 0
completed_at: integer or null
轮次进入终态的 Unix 时间戳,单位为秒。
format: int64
created_at: integer
用于按创建时间排序的 Unix 时间戳,单位为秒。子智能体轮次优先使用开始时间,其次使用完成时间,前两者均不可用时使用子智能体打开的时间。
format: int64
error: SessionTurnError or null
可向客户显示的错误。仅轮次失败时为非空值。
code: "context_length_exceeded" or "max_output_tokens" or "usage_limit_exceeded" or 21 more
稳定的、可供程序识别的失败类别。
"context_length_exceeded"
请求超出模型的上下文窗口。
"max_output_tokens"
模型完成响应之前已达到输出词元上限。
"usage_limit_exceeded"
组织已达到用量、套餐或计费限制。
"api_key_spend_limit_exceeded"
API 密钥已达到强制支出上限。
"project_spend_limit_exceeded"
项目已达到强制支出上限。
"organization_spend_limit_exceeded"
组织已达到强制支出上限。
"organization_usage_limit_exceeded"
组织已达到 OpenAI 分配的用量上限。
"billing_not_active"
账户尚未启用计费。
"credit_balance_exhausted"
组织的 API 余额已经用尽。
"rate_limit_exceeded"
请求超过可用的速率限制。
"flex_unavailable"
Flex 处理暂时不可用。
"server_overloaded"
模型服务暂时过载。
"cyber_policy"
请求因安全策略被拒绝。
"misalignment_policy_violation"
请求被安全系统拦截。
"connection_failed"
请求未能连接到模型服务。
"server_error"
模型服务遇到意外错误。
"authentication_error"
API 凭证无效或权限不足。
"invalid_request"
请求包含无效输入或配置。
"resource_not_found"
请求的模型或资源不可用。
"sandbox_error"
请求未能在其执行环境中完成。
"executor_version_incompatible"
执行器必须升级后才能运行此轮。
"active_turn_not_steerable"
请求运行期间,会话无法接收额外输入。
"request_timeout"
模型服务响应前,请求已超时。
"internal_error"
意外的内部错误导致会话请求未能完成。
message: string
可向客户显示的失败原因。
minLength: 0
object: "agent.session.turn" (default: "agent.session.turn")
对象类型,固定为 agent.session.turn。
"agent.session.turn"
session_id: string
此轮次所属会话的 ID。
minLength: 0
started_at: integer or null
轮次开始时的 Unix 时间戳,单位为秒。
format: int64
status: "queued" or "in_progress" or "waiting" or 3 more
轮次当前的状态。
"queued"
轮次正在等待开始。
"in_progress"
轮次正在进行。
"waiting"
轮次正在等待外部输入。
"completed"
轮次已成功完成。
"failed"
轮次失败。
"cancelled"
轮次已取消。
subagent_id: string or null
执行此轮的子智能体 ID(如适用)。
minLength: 0
usage: TokenUsage or null
本轮可统计到的词元用量。用量未知时为 null,已记录的用量可能变化。
input_tokens: integer
智能体使用的输入词元数。
format: int64
input_tokens_details: object { cached_tokens }
智能体输入词元用量的明细。
cached_tokens: integer
从提示词缓存中读取的输入词元数。
format: int64
output_tokens: integer
智能体生成的输出词元数。
format: int64
output_tokens_details: object { reasoning_tokens }
智能体输出词元用量的明细。
reasoning_tokens: integer
用于推理的输出词元数。
format: int64
total_tokens: integer
智能体使用的输入词元与输出词元的总数。
format: int64
prompt_cache_options: optional object { ttl } or null
本轮开始时选用的提示词缓存时长,可继承会话的缓存生存时间。使用模型默认值或未记录缓存时长时为 null。
ttl: "30m" or "12h"
"30m"
"12h"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/turns \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"agent_id": "agent_id",
"completed_at": 0,
"created_at": 0,
"error": {
"code": "context_length_exceeded",
"message": "message"
},
"object": "agent.session.turn",
"session_id": "session_id",
"started_at": 0,
"status": "queued",
"subagent_id": "subagent_id",
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"prompt_cache_options": {
"ttl": "30m"
}
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取会话轮次
get /agents/sessions/{session_id}/turns/{turn_id}
获取轮次的当前状态、时间戳、用量和错误信息。轮次不属于此会话时返回 404。参见会话轮次。
路径参数
session_id: string
此轮次所属会话的 ID。
minLength: 0, maxLength: 1048576
turn_id: string
轮次 ID。
minLength: 0, maxLength: 1048576
返回值
Turn object { id, agent_id, completed_at, 9 more }
会话轮次的标准公开表示。
id: string
轮次 ID。
minLength: 0
agent_id: string
执行本轮的智能体 ID。
minLength: 0
completed_at: integer or null
轮次进入终态的 Unix 时间戳,单位为秒。
format: int64
created_at: integer
用于按创建时间排序的 Unix 时间戳,单位为秒。子智能体轮次优先使用开始时间,其次使用完成时间,前两者均不可用时使用子智能体打开的时间。
format: int64
error: SessionTurnError or null
可向客户显示的错误。仅轮次失败时为非空值。
code: "context_length_exceeded" or "max_output_tokens" or "usage_limit_exceeded" or 21 more
稳定的、可供程序识别的失败类别。
"context_length_exceeded"
请求超出模型的上下文窗口。
"max_output_tokens"
模型完成响应之前已达到输出词元上限。
"usage_limit_exceeded"
组织已达到用量、套餐或计费限制。
"api_key_spend_limit_exceeded"
API 密钥已达到强制支出上限。
"project_spend_limit_exceeded"
项目已达到强制支出上限。
"organization_spend_limit_exceeded"
组织已达到强制支出上限。
"organization_usage_limit_exceeded"
组织已达到 OpenAI 分配的用量上限。
"billing_not_active"
账户尚未启用计费。
"credit_balance_exhausted"
组织的 API 余额已经用尽。
"rate_limit_exceeded"
请求超过可用的速率限制。
"flex_unavailable"
Flex 处理暂时不可用。
"server_overloaded"
模型服务暂时过载。
"cyber_policy"
请求因安全策略被拒绝。
"misalignment_policy_violation"
请求被安全系统拦截。
"connection_failed"
请求未能连接到模型服务。
"server_error"
模型服务遇到意外错误。
"authentication_error"
API 凭证无效或权限不足。
"invalid_request"
请求包含无效输入或配置。
"resource_not_found"
请求的模型或资源不可用。
"sandbox_error"
请求未能在其执行环境中完成。
"executor_version_incompatible"
执行器必须升级后才能运行此轮。
"active_turn_not_steerable"
请求运行期间,会话无法接收额外输入。
"request_timeout"
模型服务响应前,请求已超时。
"internal_error"
意外的内部错误导致会话请求未能完成。
message: string
可向客户显示的失败原因。
minLength: 0
object: "agent.session.turn" (default: "agent.session.turn")
对象类型,固定为 agent.session.turn。
"agent.session.turn"
session_id: string
此轮次所属会话的 ID。
minLength: 0
started_at: integer or null
轮次开始时的 Unix 时间戳,单位为秒。
format: int64
status: "queued" or "in_progress" or "waiting" or 3 more
轮次当前的状态。
"queued"
轮次正在等待开始。
"in_progress"
轮次正在进行。
"waiting"
轮次正在等待外部输入。
"completed"
轮次已成功完成。
"failed"
轮次失败。
"cancelled"
轮次已取消。
subagent_id: string or null
执行此轮的子智能体 ID(如适用)。
minLength: 0
usage: TokenUsage or null
本轮可统计到的词元用量。用量未知时为 null,已记录的用量可能变化。
input_tokens: integer
智能体使用的输入词元数。
format: int64
input_tokens_details: object { cached_tokens }
智能体输入词元用量的明细。
cached_tokens: integer
从提示词缓存中读取的输入词元数。
format: int64
output_tokens: integer
智能体生成的输出词元数。
format: int64
output_tokens_details: object { reasoning_tokens }
智能体输出词元用量的明细。
reasoning_tokens: integer
用于推理的输出词元数。
format: int64
total_tokens: integer
智能体使用的输入词元与输出词元的总数。
format: int64
prompt_cache_options: optional object { ttl } or null
本轮开始时选用的提示词缓存时长,可继承会话的缓存生存时间。使用模型默认值或未记录缓存时长时为 null。
ttl: "30m" or "12h"
"30m"
"12h"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 TURN_ID 设置为目标轮次的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/turns/$TURN_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"agent_id": "agent_id",
"completed_at": 0,
"created_at": 0,
"error": {
"code": "context_length_exceeded",
"message": "message"
},
"object": "agent.session.turn",
"session_id": "session_id",
"started_at": 0,
"status": "queued",
"subagent_id": "subagent_id",
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"prompt_cache_options": {
"ttl": "30m"
}
}
资源类型
Turn
Turn object { id, agent_id, completed_at, 9 more }
会话轮次的标准公开表示。
id: string
轮次 ID。
minLength: 0
agent_id: string
执行本轮的智能体 ID。
minLength: 0
completed_at: integer or null
轮次进入终态的 Unix 时间戳,单位为秒。
format: int64
created_at: integer
用于按创建时间排序的 Unix 时间戳,单位为秒。子智能体轮次优先使用开始时间,其次使用完成时间,前两者均不可用时使用子智能体打开的时间。
format: int64
error: SessionTurnError or null
可向客户显示的错误。仅轮次失败时为非空值。
code: "context_length_exceeded" or "max_output_tokens" or "usage_limit_exceeded" or 21 more
稳定的、可供程序识别的失败类别。
"context_length_exceeded"
请求超出模型的上下文窗口。
"max_output_tokens"
模型完成响应之前已达到输出词元上限。
"usage_limit_exceeded"
组织已达到用量、套餐或计费限制。
"api_key_spend_limit_exceeded"
API 密钥已达到强制支出上限。
"project_spend_limit_exceeded"
项目已达到强制支出上限。
"organization_spend_limit_exceeded"
组织已达到强制支出上限。
"organization_usage_limit_exceeded"
组织已达到 OpenAI 分配的用量上限。
"billing_not_active"
账户尚未启用计费。
"credit_balance_exhausted"
组织的 API 余额已经用尽。
"rate_limit_exceeded"
请求超过可用的速率限制。
"flex_unavailable"
Flex 处理暂时不可用。
"server_overloaded"
模型服务暂时过载。
"cyber_policy"
请求因安全策略被拒绝。
"misalignment_policy_violation"
请求被安全系统拦截。
"connection_failed"
请求未能连接到模型服务。
"server_error"
模型服务遇到意外错误。
"authentication_error"
API 凭证无效或权限不足。
"invalid_request"
请求包含无效输入或配置。
"resource_not_found"
请求的模型或资源不可用。
"sandbox_error"
请求未能在其执行环境中完成。
"executor_version_incompatible"
执行器必须升级后才能运行此轮。
"active_turn_not_steerable"
请求运行期间,会话无法接收额外输入。
"request_timeout"
模型服务响应前,请求已超时。
"internal_error"
意外的内部错误导致会话请求未能完成。
message: string
可向客户显示的失败原因。
minLength: 0
object: "agent.session.turn" (default: "agent.session.turn")
对象类型,固定为 agent.session.turn。
"agent.session.turn"
session_id: string
此轮次所属会话的 ID。
minLength: 0
started_at: integer or null
轮次开始时的 Unix 时间戳,单位为秒。
format: int64
status: "queued" or "in_progress" or "waiting" or 3 more
轮次当前的状态。
"queued"
轮次正在等待开始。
"in_progress"
轮次正在进行。
"waiting"
轮次正在等待外部输入。
"completed"
轮次已成功完成。
"failed"
轮次失败。
"cancelled"
轮次已取消。
subagent_id: string or null
执行此轮的子智能体 ID(如适用)。
minLength: 0
usage: TokenUsage or null
本轮可统计到的词元用量。用量未知时为 null,已记录的用量可能变化。
input_tokens: integer
智能体使用的输入词元数。
format: int64
input_tokens_details: object { cached_tokens }
智能体输入词元用量的明细。
cached_tokens: integer
从提示词缓存中读取的输入词元数。
format: int64
output_tokens: integer
智能体生成的输出词元数。
format: int64
output_tokens_details: object { reasoning_tokens }
智能体输出词元用量的明细。
reasoning_tokens: integer
用于推理的输出词元数。
format: int64
total_tokens: integer
智能体使用的输入词元与输出词元的总数。
format: int64
prompt_cache_options: optional object { ttl } or null
本轮开始时选用的提示词缓存时长,可继承会话的缓存生存时间。使用模型默认值或未记录缓存时长时为 null。
ttl: "30m" or "12h"
"30m"
"12h"
会话条目
列出会话轮次条目
get /agents/sessions/{session_id}/turns/{turn_id}/items
列出根智能体某一轮次中的条目,包括该轮次与子智能体的交互。参见检查智能体输出。
路径参数
session_id: string
此轮次所属会话的 ID。
minLength: 0, maxLength: 1048576
turn_id: string
轮次 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of AgentSessionItem
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
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"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 TURN_ID 设置为目标轮次的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/turns/$TURN_ID/items \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"content": [
{
"text": "text",
"type": "input_text"
}
],
"phase": "commentary",
"role": "user",
"status": "in_progress",
"turn_id": "turn_id",
"type": "message"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
凭证库
创建凭证库
post /vaults
为当前项目创建凭证库。参见凭证库指南。
请求体参数
内容类型为 application/json。
metadata: optional map[string] or null
要与凭证库关联的键值对,例如应用或团队标识。
name: optional string
保存前去除名称首尾空白,处理后长度必须为 1 至 256 个 UTF-8 字节。
minLength: 1, maxLength: 1048576
返回值
Vault object { id, created_at, metadata, 2 more }
供 MCP 服务器和 OpenAI 托管环境使用的凭证集合。
id: string
凭证库 ID。
minLength: 0
created_at: integer
凭证库创建时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
与凭证库关联的键值对,例如应用或团队标识。
name: string or null
凭证库的可读名称(如已设置)。
minLength: 0
object: "vault" (default: "vault")
对象类型,固定为 vault。
"vault"
示例
## 从环境变量读取 API 密钥。
curl https://api.openai.com/v1/vaults \
-X POST \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
201 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"metadata": {
"foo": "string"
},
"name": "name",
"object": "vault"
}
删除凭证库
delete /vaults/{vault_id}
删除凭证库及其中的全部凭证。参见凭证库指南。
路径参数
vault_id: string
凭证库 ID。
minLength: 0, maxLength: 1048576
返回值
VaultDeleted object { id, deleted, object }
凭证库的删除确认。
id: string
已删除凭证库的 ID。
minLength: 0
deleted: boolean
资源是否已删除,恒为 true。
object: "vault.deleted" (default: "vault.deleted")
对象类型,固定为 vault.deleted。
"vault.deleted"
示例
## 从环境变量读取 API 密钥。
## 将 VAULT_ID 设置为目标凭证库的 ID。
## 删除凭证库也会删除其中的全部凭证,执行前请核对目标 ID。
curl https://api.openai.com/v1/vaults/$VAULT_ID \
-X DELETE \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"deleted": true,
"object": "vault.deleted"
}
列出凭证库
get /vaults
使用基于 ID 的分页列出凭证库。参见凭证库指南。
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
metadata: optional map[string]
使用 metadata[key]=value 提供精确匹配的字符串条件。所有键值对都必须匹配。最多 16 对,键长为 1 至 64 个字符,值最长为 512 个字符。筛选结果采用最终一致性,元数据变更可能延迟显示。
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
status: optional VaultStatusFilter
按单个状态或状态列表筛选,例如 status=active 或 status[]=active&status[]=archived。默认包含两种状态。
VaultStatus = "active" or "archived"
凭证库或凭证当前为活动或已归档状态。
"active"
"archived"
array of VaultStatus
minItems: 0, maxItems: 16384
"active"
"archived"
返回值
data: array of Vault
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
凭证库 ID。
minLength: 0
created_at: integer
凭证库创建时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
与凭证库关联的键值对,例如应用或团队标识。
name: string or null
凭证库的可读名称(如已设置)。
minLength: 0
object: "vault" (default: "vault")
对象类型,固定为 vault。
"vault"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
curl https://api.openai.com/v1/vaults \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"created_at": 0,
"metadata": {
"foo": "string"
},
"name": "name",
"object": "vault"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取凭证库
get /vaults/{vault_id}
按 ID 获取凭证库。参见凭证库指南。
路径参数
vault_id: string
凭证库 ID。
minLength: 0, maxLength: 1048576
返回值
Vault object { id, created_at, metadata, 2 more }
供 MCP 服务器和 OpenAI 托管环境使用的凭证集合。
id: string
凭证库 ID。
minLength: 0
created_at: integer
凭证库创建时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
与凭证库关联的键值对,例如应用或团队标识。
name: string or null
凭证库的可读名称(如已设置)。
minLength: 0
object: "vault" (default: "vault")
对象类型,固定为 vault。
"vault"
示例
## 从环境变量读取 API 密钥。
## 将 VAULT_ID 设置为目标凭证库的 ID。
curl https://api.openai.com/v1/vaults/$VAULT_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"metadata": {
"foo": "string"
},
"name": "name",
"object": "vault"
}
更新凭证库
post /vaults/{vault_id}
更新活动凭证库的名称或元数据。省略的字段保留原值。参见凭证库指南。
路径参数
vault_id: string
凭证库 ID。
minLength: 0, maxLength: 1048576
请求体参数
内容类型为 application/json。
metadata: optional map[string]
替换全部元数据。省略时保留原值,传入 {} 时清除。最多 16 个字符串键值对,键最长 64 个字符,值最长 512 个字符。
name: optional string or null
新的名称。省略时保留原名称,传入 null 时清除。保存前去除首尾空白,处理后长度必须为 1 至 256 个 UTF-8 字节。
minLength: 1, maxLength: 1048576
返回值
Vault object { id, created_at, metadata, 2 more }
供 MCP 服务器和 OpenAI 托管环境使用的凭证集合。
id: string
凭证库 ID。
minLength: 0
created_at: integer
凭证库创建时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
与凭证库关联的键值对,例如应用或团队标识。
name: string or null
凭证库的可读名称(如已设置)。
minLength: 0
object: "vault" (default: "vault")
对象类型,固定为 vault。
"vault"
示例
## 从环境变量读取 API 密钥。
## 将 VAULT_ID 设置为目标凭证库的 ID。
curl https://api.openai.com/v1/vaults/$VAULT_ID \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{}'
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"created_at": 0,
"metadata": {
"foo": "string"
},
"name": "name",
"object": "vault"
}
资源类型
Vault
Vault object { id, created_at, metadata, 2 more }
供 MCP 服务器和 OpenAI 托管环境使用的凭证集合。
id: string
凭证库 ID。
minLength: 0
created_at: integer
凭证库创建时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
与凭证库关联的键值对,例如应用或团队标识。
name: string or null
凭证库的可读名称(如已设置)。
minLength: 0
object: "vault" (default: "vault")
对象类型,固定为 vault。
"vault"
Vault Deleted
VaultDeleted object { id, deleted, object }
凭证库的删除确认。
id: string
已删除凭证库的 ID。
minLength: 0
deleted: boolean
资源是否已删除,恒为 true。
object: "vault.deleted" (default: "vault.deleted")
对象类型,固定为 vault.deleted。
"vault.deleted"
Vault Status
VaultStatus = "active" or "archived"
凭证库或凭证当前为活动或已归档状态。
"active"
"archived"
Vault Status Filter
VaultStatusFilter = VaultStatus or array of VaultStatus
列出凭证库或凭证时纳入结果的一个或多个生命周期状态。
VaultStatus = "active" or "archived"
凭证库或凭证当前为活动或已归档状态。
"active"
"archived"
array of VaultStatus
minItems: 0, maxItems: 16384
"active"
"archived"
凭证
创建凭证库凭证
post /vaults/{vault_id}/credentials
创建凭证库凭证。机密值只写,响应始终省略。参见凭证库指南。
路径参数
vault_id: string
凭证库 ID。
minLength: 0, maxLength: 1048576
请求体参数
内容类型为 application/json。
auth: CredentialAuthCreateParam
身份验证方式和待存储的只写机密值。
McpOauth object { access_token, mcp_server_url, type, 2 more }
用于 HTTPS MCP 目标的 OAuth 凭证。
access_token: string
只写的 OAuth 访问令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0, maxLength: 1048576
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
expires_at: optional string or null
OAuth 访问令牌的过期时间,格式为 RFC 3339 时间戳(如已知)。
minLength: 0, maxLength: 1048576
refresh: optional object { client_id, refresh_token, token_endpoint, 3 more } or null
HTTPS OAuth 令牌端点的可选刷新配置。
client_id: string
获取新访问令牌时使用的 OAuth 客户端 ID。
minLength: 0, maxLength: 1048576
refresh_token: string
要存储的刷新令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
token_endpoint: string
用于用刷新令牌换取新访问令牌的 HTTPS OAuth 令牌端点。
minLength: 0, maxLength: 1048576
token_endpoint_auth: McpOauthTokenEndpointAuthCreateParam
OAuth 客户端向令牌端点进行身份验证的方式。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { client_secret, type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
client_secret: string
要存储的 OAuth 客户端密钥。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { client_secret, type }
在令牌请求体中发送客户端 ID 和密钥。
client_secret: string
要存储的 OAuth 客户端密钥。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
resource: optional string or null
刷新时要发送给 OAuth 令牌端点的资源 URI(如有必要)。
minLength: 0, maxLength: 1048576
scope: optional string or null
刷新时要请求的 OAuth 权限范围,以空格分隔(如有必要)。
minLength: 0, maxLength: 1048576
StaticBearer object { token, mcp_server_url, type }
用于 MCP 服务器的 Bearer 令牌。此类型不支持 OAuth 自动刷新。
token: string
要存储的 Bearer 令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0, maxLength: 1048576
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { networking, secret_name, secret_value, type }
仅用于 OpenAI 托管环境的 HTTP 凭证。沙箱收到的环境变量包含占位符。发送请求时原样使用该值。出站代理只对获准且使用 443 或 8443 端口的 HTTPS 目标将占位符替换为密钥。沙箱代码无法读取真实密钥,也无法在本地计算中使用它,例如给请求签名。
networking: CredentialNetworkingParam
代理可以替换此密钥的目标。环境网络策略也必须允许访问这些目标。
Unrestricted object { type }
允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。
type: "unrestricted" (default: "unrestricted")
对象类型,固定为 unrestricted。
"unrestricted"
Limited object { allowed_hosts, type }
仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。
allowed_hosts: array of string
允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。
minItems: 1, maxItems: 16
type: "limited" (default: "limited")
对象类型,固定为 limited。
"limited"
secret_name: string
接收占位符的环境变量名,例如 SERVICE_API_KEY。可使用 ASCII 字母、数字和下划线,首字符必须为字母或下划线。以 CODEX_ 开头的名称以及托管代理或证书的变量名均为保留名称。
minLength: 1, maxLength: 1048576
secret_value: string
要存储的只写密钥。凭证资源始终省略该值,沙箱代码也无法直接取得。该值不得为空,不得包含回车符、换行符或 NUL 字节。
minLength: 1, maxLength: 1048576
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
name: string
保存前去除名称首尾空白,处理后长度必须为 1 至 256 个 UTF-8 字节。
minLength: 1, maxLength: 1048576
metadata: optional map[string]
最多 16 个字符串键值对,键最长 64 个字符,值最长 512 个字符。默认为空映射。
返回值
Credential object { id, auth, created_at, 5 more }
已存储凭证的元数据。响应始终省略机密值。
id: string
凭证 ID。
minLength: 0
auth: CredentialAuth
凭证的身份验证方式和非机密配置。
McpOauth object { expires_at, mcp_server_url, refresh, type }
OAuth 凭证的非机密元数据。响应始终省略令牌和客户端密钥。
expires_at: string or null
OAuth 访问令牌的过期时间,格式为 RFC 3339 时间戳(如已知)。
minLength: 0
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
refresh: object { client_id, resource, scope, 2 more } or null
可返回的非机密刷新元数据,省略刷新令牌和 OAuth 客户端密钥。
client_id: string
获取新访问令牌时使用的 OAuth 客户端 ID。
minLength: 0
resource: string or null
刷新时发送给 OAuth 令牌端点的资源 URI(如已配置)。
minLength: 0
scope: string or null
刷新时请求的 OAuth 权限范围,以空格分隔(如已配置)。
minLength: 0
token_endpoint: string
用于刷新的 HTTPS OAuth 令牌端点。
minLength: 0
token_endpoint_auth: McpOauthTokenEndpointAuth
OAuth 客户端向令牌端点进行身份验证的方式。响应省略客户端密钥。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { type }
在令牌请求体中发送客户端 ID 和密钥。
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
StaticBearer object { mcp_server_url, type }
Bearer 令牌凭证的元数据。此类凭证不支持 OAuth 自动刷新。
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { networking, secret_name, type }
仅用于 OpenAI 托管环境的 HTTP 凭证元数据。沙箱代码收到的是占位符。代理只对获准且使用 443 或 8443 端口的 HTTPS 目标将占位符替换为密钥。沙箱代码无法使用真实密钥进行本地计算,此资源的响应也始终省略真实密钥。
networking: CredentialNetworking
代理可将占位符替换为密钥的目标,受环境网络策略约束。
Unrestricted object { type }
允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。
type: "unrestricted" (default: "unrestricted")
对象类型,固定为 unrestricted。
"unrestricted"
Limited object { allowed_hosts, type }
仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。
allowed_hosts: array of string
允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。
minItems: 1, maxItems: 16
type: "limited" (default: "limited")
对象类型,固定为 limited。
"limited"
secret_name: string
沙箱内用于接收占位符的环境变量名。
minLength: 0
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
created_at: integer
凭证创建时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
应用定义的键值对,与此凭证关联。
name: string
凭证的可读名称。
minLength: 0
object: "vault.credential" (default: "vault.credential")
对象类型,固定为 vault.credential。
"vault.credential"
updated_at: integer
凭证上次更新时的 Unix 时间戳,单位为秒。
format: int64
vault_id: string
此凭证所属凭证库的 ID。
minLength: 0
示例
## 从环境变量读取 API 密钥。
## 将 VAULT_ID 设置为目标凭证库的 ID。
## access_token、mcp_server_url 和 name 均为占位值。请通过机密管理流程提供真实令牌。
curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"auth": {
"access_token": "access_token",
"mcp_server_url": "mcp_server_url",
"type": "mcp_oauth"
},
"name": "x"
}'
201 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"auth": {
"expires_at": "expires_at",
"mcp_server_url": "mcp_server_url",
"refresh": {
"client_id": "client_id",
"resource": "resource",
"scope": "scope",
"token_endpoint": "token_endpoint",
"token_endpoint_auth": {
"type": "none"
}
},
"type": "mcp_oauth"
},
"created_at": 0,
"metadata": {
"foo": "string"
},
"name": "name",
"object": "vault.credential",
"updated_at": 0,
"vault_id": "vault_id"
}
删除凭证库凭证
delete /vaults/{vault_id}/credentials/{credential_id}
删除凭证库凭证。参见凭证库指南。
路径参数
vault_id: string
凭证库 ID。
minLength: 0, maxLength: 1048576
credential_id: string
凭证库凭证的 ID。
minLength: 0, maxLength: 1048576
返回值
CredentialDeleted object { id, deleted, object }
凭证库凭证的删除确认。
id: string
已删除凭证的 ID。
minLength: 0
deleted: boolean
资源是否已删除,恒为 true。
object: "vault.credential.deleted" (default: "vault.credential.deleted")
对象类型,固定为 vault.credential.deleted。
"vault.credential.deleted"
示例
## 从环境变量读取 API 密钥。
## 将 VAULT_ID 设置为目标凭证库的 ID。
## 将 CREDENTIAL_ID 设置为目标凭证的 ID。
curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \
-X DELETE \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"deleted": true,
"object": "vault.credential.deleted"
}
列出凭证库凭证
get /vaults/{vault_id}/credentials
使用基于 ID 的分页列出凭证库内的凭证,响应省略机密值。参见凭证库指南。
路径参数
vault_id: string
凭证库 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
metadata: optional map[string]
使用 metadata[key]=value 提供精确匹配的字符串条件。所有键值对都必须匹配。最多 16 对,键长为 1 至 64 个字符,值最长为 512 个字符。筛选结果采用最终一致性,元数据变更可能延迟显示。
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
status: optional VaultStatusFilter
按单个状态或状态列表筛选,例如 status=active 或 status[]=active&status[]=archived。默认包含两种状态。
VaultStatus = "active" or "archived"
凭证库或凭证当前为活动或已归档状态。
"active"
"archived"
array of VaultStatus
minItems: 0, maxItems: 16384
"active"
"archived"
返回值
data: array of Credential
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
凭证 ID。
minLength: 0
auth: CredentialAuth
凭证的身份验证方式和非机密配置。
McpOauth object { expires_at, mcp_server_url, refresh, type }
OAuth 凭证的非机密元数据。响应始终省略令牌和客户端密钥。
expires_at: string or null
OAuth 访问令牌的过期时间,格式为 RFC 3339 时间戳(如已知)。
minLength: 0
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
refresh: object { client_id, resource, scope, 2 more } or null
可返回的非机密刷新元数据,省略刷新令牌和 OAuth 客户端密钥。
client_id: string
获取新访问令牌时使用的 OAuth 客户端 ID。
minLength: 0
resource: string or null
刷新时发送给 OAuth 令牌端点的资源 URI(如已配置)。
minLength: 0
scope: string or null
刷新时请求的 OAuth 权限范围,以空格分隔(如已配置)。
minLength: 0
token_endpoint: string
用于刷新的 HTTPS OAuth 令牌端点。
minLength: 0
token_endpoint_auth: McpOauthTokenEndpointAuth
OAuth 客户端向令牌端点进行身份验证的方式。响应省略客户端密钥。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { type }
在令牌请求体中发送客户端 ID 和密钥。
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
StaticBearer object { mcp_server_url, type }
Bearer 令牌凭证的元数据。此类凭证不支持 OAuth 自动刷新。
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { networking, secret_name, type }
仅用于 OpenAI 托管环境的 HTTP 凭证元数据。沙箱代码收到的是占位符。代理只对获准且使用 443 或 8443 端口的 HTTPS 目标将占位符替换为密钥。沙箱代码无法使用真实密钥进行本地计算,此资源的响应也始终省略真实密钥。
networking: CredentialNetworking
代理可将占位符替换为密钥的目标,受环境网络策略约束。
Unrestricted object { type }
允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。
type: "unrestricted" (default: "unrestricted")
对象类型,固定为 unrestricted。
"unrestricted"
Limited object { allowed_hosts, type }
仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。
allowed_hosts: array of string
允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。
minItems: 1, maxItems: 16
type: "limited" (default: "limited")
对象类型,固定为 limited。
"limited"
secret_name: string
沙箱内用于接收占位符的环境变量名。
minLength: 0
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
created_at: integer
凭证创建时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
应用定义的键值对,与此凭证关联。
name: string
凭证的可读名称。
minLength: 0
object: "vault.credential" (default: "vault.credential")
对象类型,固定为 vault.credential。
"vault.credential"
updated_at: integer
凭证上次更新时的 Unix 时间戳,单位为秒。
format: int64
vault_id: string
此凭证所属凭证库的 ID。
minLength: 0
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 VAULT_ID 设置为目标凭证库的 ID。
curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"auth": {
"expires_at": "expires_at",
"mcp_server_url": "mcp_server_url",
"refresh": {
"client_id": "client_id",
"resource": "resource",
"scope": "scope",
"token_endpoint": "token_endpoint",
"token_endpoint_auth": {
"type": "none"
}
},
"type": "mcp_oauth"
},
"created_at": 0,
"metadata": {
"foo": "string"
},
"name": "name",
"object": "vault.credential",
"updated_at": 0,
"vault_id": "vault_id"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
获取凭证库凭证
get /vaults/{vault_id}/credentials/{credential_id}
获取凭证库凭证的元数据。响应省略机密值。参见凭证库指南。
路径参数
vault_id: string
凭证库 ID。
minLength: 0, maxLength: 1048576
credential_id: string
凭证库凭证的 ID。
minLength: 0, maxLength: 1048576
返回值
Credential object { id, auth, created_at, 5 more }
已存储凭证的元数据。响应始终省略机密值。
id: string
凭证 ID。
minLength: 0
auth: CredentialAuth
凭证的身份验证方式和非机密配置。
McpOauth object { expires_at, mcp_server_url, refresh, type }
OAuth 凭证的非机密元数据。响应始终省略令牌和客户端密钥。
expires_at: string or null
OAuth 访问令牌的过期时间,格式为 RFC 3339 时间戳(如已知)。
minLength: 0
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
refresh: object { client_id, resource, scope, 2 more } or null
可返回的非机密刷新元数据,省略刷新令牌和 OAuth 客户端密钥。
client_id: string
获取新访问令牌时使用的 OAuth 客户端 ID。
minLength: 0
resource: string or null
刷新时发送给 OAuth 令牌端点的资源 URI(如已配置)。
minLength: 0
scope: string or null
刷新时请求的 OAuth 权限范围,以空格分隔(如已配置)。
minLength: 0
token_endpoint: string
用于刷新的 HTTPS OAuth 令牌端点。
minLength: 0
token_endpoint_auth: McpOauthTokenEndpointAuth
OAuth 客户端向令牌端点进行身份验证的方式。响应省略客户端密钥。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { type }
在令牌请求体中发送客户端 ID 和密钥。
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
StaticBearer object { mcp_server_url, type }
Bearer 令牌凭证的元数据。此类凭证不支持 OAuth 自动刷新。
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { networking, secret_name, type }
仅用于 OpenAI 托管环境的 HTTP 凭证元数据。沙箱代码收到的是占位符。代理只对获准且使用 443 或 8443 端口的 HTTPS 目标将占位符替换为密钥。沙箱代码无法使用真实密钥进行本地计算,此资源的响应也始终省略真实密钥。
networking: CredentialNetworking
代理可将占位符替换为密钥的目标,受环境网络策略约束。
Unrestricted object { type }
允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。
type: "unrestricted" (default: "unrestricted")
对象类型,固定为 unrestricted。
"unrestricted"
Limited object { allowed_hosts, type }
仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。
allowed_hosts: array of string
允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。
minItems: 1, maxItems: 16
type: "limited" (default: "limited")
对象类型,固定为 limited。
"limited"
secret_name: string
沙箱内用于接收占位符的环境变量名。
minLength: 0
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
created_at: integer
凭证创建时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
应用定义的键值对,与此凭证关联。
name: string
凭证的可读名称。
minLength: 0
object: "vault.credential" (default: "vault.credential")
对象类型,固定为 vault.credential。
"vault.credential"
updated_at: integer
凭证上次更新时的 Unix 时间戳,单位为秒。
format: int64
vault_id: string
此凭证所属凭证库的 ID。
minLength: 0
示例
## 从环境变量读取 API 密钥。
## 将 VAULT_ID 设置为目标凭证库的 ID。
## 将 CREDENTIAL_ID 设置为目标凭证的 ID。
curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"auth": {
"expires_at": "expires_at",
"mcp_server_url": "mcp_server_url",
"refresh": {
"client_id": "client_id",
"resource": "resource",
"scope": "scope",
"token_endpoint": "token_endpoint",
"token_endpoint_auth": {
"type": "none"
}
},
"type": "mcp_oauth"
},
"created_at": 0,
"metadata": {
"foo": "string"
},
"name": "name",
"object": "vault.credential",
"updated_at": 0,
"vault_id": "vault_id"
}
更新凭证库凭证
post /vaults/{vault_id}/credentials/{credential_id}
更新凭证元数据或轮换其只写密钥。参见凭证库指南。
路径参数
vault_id: string
凭证库 ID。
minLength: 0, maxLength: 1048576
credential_id: string
凭证库凭证的 ID。
minLength: 0, maxLength: 1048576
请求体参数
内容类型为 application/json。
auth: optional CredentialAuthRotateParam
此凭证现有身份验证方式使用的替换值。
McpOauth object { type, access_token, expires_at, refresh }
轮换用于 HTTPS MCP 目标的 OAuth 凭证。
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
access_token: optional string or null
用于替换现有值的只写 OAuth 访问令牌。
minLength: 0, maxLength: 1048576
expires_at: optional string or null
新的过期时间,格式为 RFC 3339 时间戳。传入 null 时清除。省略时保留原过期时间,除非同时提供新访问令牌,此时清除原过期时间。
minLength: 0, maxLength: 1048576
refresh: optional object { refresh_token, scope, token_endpoint_auth } or null
可选的只写更新,用于刷新令牌和客户端密钥。
refresh_token: optional string or null
新的刷新令牌。省略或传入 null 时沿用已存储的令牌。资源响应始终省略该值。
minLength: 0, maxLength: 1048576
scope: optional string or null
刷新请求使用的新版 OAuth 权限范围,以空格分隔。省略时保留原范围,传入 null 时停止发送 scope 参数。
minLength: 0, maxLength: 1048576
token_endpoint_auth: optional McpOauthTokenEndpointAuthRotateParam or null
为现有令牌端点身份验证方式更新客户端密钥。
ClientSecretBasic object { type, client_secret }
更新使用 HTTP Basic 身份验证发送的凭证。
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
client_secret: optional string or null
新的 OAuth 客户端密钥。省略或传入 null 时沿用已存储的密钥。资源响应始终省略该值。
minLength: 0, maxLength: 1048576
ClientSecretPost object { type, client_secret }
更新在令牌请求体中发送的凭证。
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
client_secret: optional string or null
新的 OAuth 客户端密钥。省略或传入 null 时沿用已存储的密钥。资源响应始终省略该值。
minLength: 0, maxLength: 1048576
StaticBearer object { token, type }
替换此凭证为 MCP 服务器使用的 Bearer 令牌。
token: string
新的 Bearer 令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { secret_value, type }
替换 OpenAI 托管环境凭证的密钥。环境变量名和网络配置保持原值。
secret_value: string
用于替换现有值的只写密钥。凭证资源始终省略该值,沙箱代码也无法直接取得。该值不得为空,不得包含回车符、换行符或 NUL 字节。
minLength: 1, maxLength: 1048576
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
metadata: optional map[string]
替换全部元数据。省略时保留原值,传入 {} 时清除。最多 16 个字符串键值对,键最长 64 个字符,值最长 512 个字符。
返回值
Credential object { id, auth, created_at, 5 more }
已存储凭证的元数据。响应始终省略机密值。
id: string
凭证 ID。
minLength: 0
auth: CredentialAuth
凭证的身份验证方式和非机密配置。
McpOauth object { expires_at, mcp_server_url, refresh, type }
OAuth 凭证的非机密元数据。响应始终省略令牌和客户端密钥。
expires_at: string or null
OAuth 访问令牌的过期时间,格式为 RFC 3339 时间戳(如已知)。
minLength: 0
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
refresh: object { client_id, resource, scope, 2 more } or null
可返回的非机密刷新元数据,省略刷新令牌和 OAuth 客户端密钥。
client_id: string
获取新访问令牌时使用的 OAuth 客户端 ID。
minLength: 0
resource: string or null
刷新时发送给 OAuth 令牌端点的资源 URI(如已配置)。
minLength: 0
scope: string or null
刷新时请求的 OAuth 权限范围,以空格分隔(如已配置)。
minLength: 0
token_endpoint: string
用于刷新的 HTTPS OAuth 令牌端点。
minLength: 0
token_endpoint_auth: McpOauthTokenEndpointAuth
OAuth 客户端向令牌端点进行身份验证的方式。响应省略客户端密钥。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { type }
在令牌请求体中发送客户端 ID 和密钥。
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
StaticBearer object { mcp_server_url, type }
Bearer 令牌凭证的元数据。此类凭证不支持 OAuth 自动刷新。
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { networking, secret_name, type }
仅用于 OpenAI 托管环境的 HTTP 凭证元数据。沙箱代码收到的是占位符。代理只对获准且使用 443 或 8443 端口的 HTTPS 目标将占位符替换为密钥。沙箱代码无法使用真实密钥进行本地计算,此资源的响应也始终省略真实密钥。
networking: CredentialNetworking
代理可将占位符替换为密钥的目标,受环境网络策略约束。
Unrestricted object { type }
允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。
type: "unrestricted" (default: "unrestricted")
对象类型,固定为 unrestricted。
"unrestricted"
Limited object { allowed_hosts, type }
仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。
allowed_hosts: array of string
允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。
minItems: 1, maxItems: 16
type: "limited" (default: "limited")
对象类型,固定为 limited。
"limited"
secret_name: string
沙箱内用于接收占位符的环境变量名。
minLength: 0
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
created_at: integer
凭证创建时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
应用定义的键值对,与此凭证关联。
name: string
凭证的可读名称。
minLength: 0
object: "vault.credential" (default: "vault.credential")
对象类型,固定为 vault.credential。
"vault.credential"
updated_at: integer
凭证上次更新时的 Unix 时间戳,单位为秒。
format: int64
vault_id: string
此凭证所属凭证库的 ID。
minLength: 0
示例
## 从环境变量读取 API 密钥。
## 将 VAULT_ID 设置为目标凭证库的 ID。
## 将 CREDENTIAL_ID 设置为目标凭证的 ID。
curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"metadata": {}
}'
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"auth": {
"expires_at": "expires_at",
"mcp_server_url": "mcp_server_url",
"refresh": {
"client_id": "client_id",
"resource": "resource",
"scope": "scope",
"token_endpoint": "token_endpoint",
"token_endpoint_auth": {
"type": "none"
}
},
"type": "mcp_oauth"
},
"created_at": 0,
"metadata": {
"foo": "string"
},
"name": "name",
"object": "vault.credential",
"updated_at": 0,
"vault_id": "vault_id"
}
资源类型
Credential
Credential object { id, auth, created_at, 5 more }
已存储凭证的元数据。响应始终省略机密值。
id: string
凭证 ID。
minLength: 0
auth: CredentialAuth
凭证的身份验证方式和非机密配置。
McpOauth object { expires_at, mcp_server_url, refresh, type }
OAuth 凭证的非机密元数据。响应始终省略令牌和客户端密钥。
expires_at: string or null
OAuth 访问令牌的过期时间,格式为 RFC 3339 时间戳(如已知)。
minLength: 0
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
refresh: object { client_id, resource, scope, 2 more } or null
可返回的非机密刷新元数据,省略刷新令牌和 OAuth 客户端密钥。
client_id: string
获取新访问令牌时使用的 OAuth 客户端 ID。
minLength: 0
resource: string or null
刷新时发送给 OAuth 令牌端点的资源 URI(如已配置)。
minLength: 0
scope: string or null
刷新时请求的 OAuth 权限范围,以空格分隔(如已配置)。
minLength: 0
token_endpoint: string
用于刷新的 HTTPS OAuth 令牌端点。
minLength: 0
token_endpoint_auth: McpOauthTokenEndpointAuth
OAuth 客户端向令牌端点进行身份验证的方式。响应省略客户端密钥。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { type }
在令牌请求体中发送客户端 ID 和密钥。
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
StaticBearer object { mcp_server_url, type }
Bearer 令牌凭证的元数据。此类凭证不支持 OAuth 自动刷新。
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { networking, secret_name, type }
仅用于 OpenAI 托管环境的 HTTP 凭证元数据。沙箱代码收到的是占位符。代理只对获准且使用 443 或 8443 端口的 HTTPS 目标将占位符替换为密钥。沙箱代码无法使用真实密钥进行本地计算,此资源的响应也始终省略真实密钥。
networking: CredentialNetworking
代理可将占位符替换为密钥的目标,受环境网络策略约束。
Unrestricted object { type }
允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。
type: "unrestricted" (default: "unrestricted")
对象类型,固定为 unrestricted。
"unrestricted"
Limited object { allowed_hosts, type }
仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。
allowed_hosts: array of string
允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。
minItems: 1, maxItems: 16
type: "limited" (default: "limited")
对象类型,固定为 limited。
"limited"
secret_name: string
沙箱内用于接收占位符的环境变量名。
minLength: 0
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
created_at: integer
凭证创建时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
应用定义的键值对,与此凭证关联。
name: string
凭证的可读名称。
minLength: 0
object: "vault.credential" (default: "vault.credential")
对象类型,固定为 vault.credential。
"vault.credential"
updated_at: integer
凭证上次更新时的 Unix 时间戳,单位为秒。
format: int64
vault_id: string
此凭证所属凭证库的 ID。
minLength: 0
Credential Auth
CredentialAuth = McpOauth { expires_at, mcp_server_url, refresh, type } or StaticBearer { mcp_server_url, type } or EnvironmentVariable { networking, secret_name, type }
凭证库凭证的身份验证配置,省略机密值。
McpOauth object { expires_at, mcp_server_url, refresh, type }
OAuth 凭证的非机密元数据。响应始终省略令牌和客户端密钥。
expires_at: string or null
OAuth 访问令牌的过期时间,格式为 RFC 3339 时间戳(如已知)。
minLength: 0
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
refresh: object { client_id, resource, scope, 2 more } or null
可返回的非机密刷新元数据,省略刷新令牌和 OAuth 客户端密钥。
client_id: string
获取新访问令牌时使用的 OAuth 客户端 ID。
minLength: 0
resource: string or null
刷新时发送给 OAuth 令牌端点的资源 URI(如已配置)。
minLength: 0
scope: string or null
刷新时请求的 OAuth 权限范围,以空格分隔(如已配置)。
minLength: 0
token_endpoint: string
用于刷新的 HTTPS OAuth 令牌端点。
minLength: 0
token_endpoint_auth: McpOauthTokenEndpointAuth
OAuth 客户端向令牌端点进行身份验证的方式。响应省略客户端密钥。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { type }
在令牌请求体中发送客户端 ID 和密钥。
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
StaticBearer object { mcp_server_url, type }
Bearer 令牌凭证的元数据。此类凭证不支持 OAuth 自动刷新。
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { networking, secret_name, type }
仅用于 OpenAI 托管环境的 HTTP 凭证元数据。沙箱代码收到的是占位符。代理只对获准且使用 443 或 8443 端口的 HTTPS 目标将占位符替换为密钥。沙箱代码无法使用真实密钥进行本地计算,此资源的响应也始终省略真实密钥。
networking: CredentialNetworking
代理可将占位符替换为密钥的目标,受环境网络策略约束。
Unrestricted object { type }
允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。
type: "unrestricted" (default: "unrestricted")
对象类型,固定为 unrestricted。
"unrestricted"
Limited object { allowed_hosts, type }
仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。
allowed_hosts: array of string
允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。
minItems: 1, maxItems: 16
type: "limited" (default: "limited")
对象类型,固定为 limited。
"limited"
secret_name: string
沙箱内用于接收占位符的环境变量名。
minLength: 0
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
Credential Auth Create Param
CredentialAuthCreateParam = McpOauth { access_token, mcp_server_url, type, 2 more } or StaticBearer { token, mcp_server_url, type } or EnvironmentVariable { networking, secret_name, secret_value, type }
用于 MCP 服务器或 OpenAI 托管环境的身份验证凭证。
McpOauth object { access_token, mcp_server_url, type, 2 more }
用于 HTTPS MCP 目标的 OAuth 凭证。
access_token: string
只写的 OAuth 访问令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0, maxLength: 1048576
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
expires_at: optional string or null
OAuth 访问令牌的过期时间,格式为 RFC 3339 时间戳(如已知)。
minLength: 0, maxLength: 1048576
refresh: optional object { client_id, refresh_token, token_endpoint, 3 more } or null
HTTPS OAuth 令牌端点的可选刷新配置。
client_id: string
获取新访问令牌时使用的 OAuth 客户端 ID。
minLength: 0, maxLength: 1048576
refresh_token: string
要存储的刷新令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
token_endpoint: string
用于用刷新令牌换取新访问令牌的 HTTPS OAuth 令牌端点。
minLength: 0, maxLength: 1048576
token_endpoint_auth: McpOauthTokenEndpointAuthCreateParam
OAuth 客户端向令牌端点进行身份验证的方式。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { client_secret, type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
client_secret: string
要存储的 OAuth 客户端密钥。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { client_secret, type }
在令牌请求体中发送客户端 ID 和密钥。
client_secret: string
要存储的 OAuth 客户端密钥。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
resource: optional string or null
刷新时要发送给 OAuth 令牌端点的资源 URI(如有必要)。
minLength: 0, maxLength: 1048576
scope: optional string or null
刷新时要请求的 OAuth 权限范围,以空格分隔(如有必要)。
minLength: 0, maxLength: 1048576
StaticBearer object { token, mcp_server_url, type }
用于 MCP 服务器的 Bearer 令牌。此类型不支持 OAuth 自动刷新。
token: string
要存储的 Bearer 令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0, maxLength: 1048576
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { networking, secret_name, secret_value, type }
仅用于 OpenAI 托管环境的 HTTP 凭证。沙箱收到的环境变量包含占位符。发送请求时原样使用该值。出站代理只对获准且使用 443 或 8443 端口的 HTTPS 目标将占位符替换为密钥。沙箱代码无法读取真实密钥,也无法在本地计算中使用它,例如给请求签名。
networking: CredentialNetworkingParam
代理可以替换此密钥的目标。环境网络策略也必须允许访问这些目标。
Unrestricted object { type }
允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。
type: "unrestricted" (default: "unrestricted")
对象类型,固定为 unrestricted。
"unrestricted"
Limited object { allowed_hosts, type }
仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。
allowed_hosts: array of string
允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。
minItems: 1, maxItems: 16
type: "limited" (default: "limited")
对象类型,固定为 limited。
"limited"
secret_name: string
接收占位符的环境变量名,例如 SERVICE_API_KEY。可使用 ASCII 字母、数字和下划线,首字符必须为字母或下划线。以 CODEX_ 开头的名称以及托管代理或证书的变量名均为保留名称。
minLength: 1, maxLength: 1048576
secret_value: string
要存储的只写密钥。凭证资源始终省略该值,沙箱代码也无法直接取得。该值不得为空,不得包含回车符、换行符或 NUL 字节。
minLength: 1, maxLength: 1048576
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
Credential Auth Rotate Param
CredentialAuthRotateParam = McpOauth { type, access_token, expires_at, refresh } or StaticBearer { token, type } or EnvironmentVariable { secret_value, type }
更新凭证库中的凭证,同时保留原身份验证方式和目标配置。
McpOauth object { type, access_token, expires_at, refresh }
轮换用于 HTTPS MCP 目标的 OAuth 凭证。
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
access_token: optional string or null
用于替换现有值的只写 OAuth 访问令牌。
minLength: 0, maxLength: 1048576
expires_at: optional string or null
新的过期时间,格式为 RFC 3339 时间戳。传入 null 时清除。省略时保留原过期时间,除非同时提供新访问令牌,此时清除原过期时间。
minLength: 0, maxLength: 1048576
refresh: optional object { refresh_token, scope, token_endpoint_auth } or null
可选的只写更新,用于刷新令牌和客户端密钥。
refresh_token: optional string or null
新的刷新令牌。省略或传入 null 时沿用已存储的令牌。资源响应始终省略该值。
minLength: 0, maxLength: 1048576
scope: optional string or null
刷新请求使用的新版 OAuth 权限范围,以空格分隔。省略时保留原范围,传入 null 时停止发送 scope 参数。
minLength: 0, maxLength: 1048576
token_endpoint_auth: optional McpOauthTokenEndpointAuthRotateParam or null
为现有令牌端点身份验证方式更新客户端密钥。
ClientSecretBasic object { type, client_secret }
更新使用 HTTP Basic 身份验证发送的凭证。
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
client_secret: optional string or null
新的 OAuth 客户端密钥。省略或传入 null 时沿用已存储的密钥。资源响应始终省略该值。
minLength: 0, maxLength: 1048576
ClientSecretPost object { type, client_secret }
更新在令牌请求体中发送的凭证。
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
client_secret: optional string or null
新的 OAuth 客户端密钥。省略或传入 null 时沿用已存储的密钥。资源响应始终省略该值。
minLength: 0, maxLength: 1048576
StaticBearer object { token, type }
替换此凭证为 MCP 服务器使用的 Bearer 令牌。
token: string
新的 Bearer 令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { secret_value, type }
替换 OpenAI 托管环境凭证的密钥。环境变量名和网络配置保持原值。
secret_value: string
用于替换现有值的只写密钥。凭证资源始终省略该值,沙箱代码也无法直接取得。该值不得为空,不得包含回车符、换行符或 NUL 字节。
minLength: 1, maxLength: 1048576
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
Credential Deleted
CredentialDeleted object { id, deleted, object }
凭证库凭证的删除确认。
id: string
已删除凭证的 ID。
minLength: 0
deleted: boolean
资源是否已删除,恒为 true。
object: "vault.credential.deleted" (default: "vault.credential.deleted")
对象类型,固定为 vault.credential.deleted。
"vault.credential.deleted"
Credential Networking
CredentialNetworking = Unrestricted { type } or Limited { allowed_hosts, type }
环境变量凭证允许使用的目标。环境的网络访问权限由网络策略另行控制。
Unrestricted object { type }
允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。
type: "unrestricted" (default: "unrestricted")
对象类型,固定为 unrestricted。
"unrestricted"
Limited object { allowed_hosts, type }
仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。
allowed_hosts: array of string
允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。
minItems: 1, maxItems: 16
type: "limited" (default: "limited")
对象类型,固定为 limited。
"limited"
Credential Networking Param
CredentialNetworkingParam = Unrestricted { type } or Limited { allowed_hosts, type }
环境变量凭证允许使用的目标。环境的网络访问权限由网络策略另行控制。
Unrestricted object { type }
允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。
type: "unrestricted" (default: "unrestricted")
对象类型,固定为 unrestricted。
"unrestricted"
Limited object { allowed_hosts, type }
仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。
allowed_hosts: array of string
允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。
minItems: 1, maxItems: 16
type: "limited" (default: "limited")
对象类型,固定为 limited。
"limited"
Mcp OAuth Token Endpoint Auth
McpOauthTokenEndpointAuth = None { type } or ClientSecretBasic { type } or ClientSecretPost { type }
OAuth 令牌刷新使用的客户端身份验证方式。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { type }
在令牌请求体中发送客户端 ID 和密钥。
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
Mcp OAuth Token Endpoint Auth Create Param
McpOauthTokenEndpointAuthCreateParam = None { type } or ClientSecretBasic { client_secret, type } or ClientSecretPost { client_secret, type }
OAuth 令牌刷新使用的客户端身份验证凭证。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { client_secret, type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
client_secret: string
要存储的 OAuth 客户端密钥。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { client_secret, type }
在令牌请求体中发送客户端 ID 和密钥。
client_secret: string
要存储的 OAuth 客户端密钥。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
Mcp OAuth Token Endpoint Auth Rotate Param
McpOauthTokenEndpointAuthRotateParam = ClientSecretBasic { type, client_secret } or ClientSecretPost { type, client_secret }
更新客户端密钥并保留凭证原有的 OAuth 身份验证方式。
ClientSecretBasic object { type, client_secret }
更新使用 HTTP Basic 身份验证发送的凭证。
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
client_secret: optional string or null
新的 OAuth 客户端密钥。省略或传入 null 时沿用已存储的密钥。资源响应始终省略该值。
minLength: 0, maxLength: 1048576
ClientSecretPost object { type, client_secret }
更新在令牌请求体中发送的凭证。
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
client_secret: optional string or null
新的 OAuth 客户端密钥。省略或传入 null 时沿用已存储的密钥。资源响应始终省略该值。
minLength: 0, maxLength: 1048576

TRAE-AI编程


更多建议: