OpenAI 更新智能体会话

2026-11-19 18:01 更新

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"

对适用操作进行自动审查。拒绝需要转入手动审批的操作。

  • vault_ids: optional array of string or null

替换会话引用的凭证库。省略此字段时保留现有引用,传入 null 或空数组 [] 时清除所有引用。

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 密钥。
## 将 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"
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号