OpenAI Agents 接口总览

2026-11-18 18:02 更新

智能体

创建智能体

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

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

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号