Update an agent session
POST
/agents/sessions/{session_id}Updates session tools, metadata, model, reasoning effort, service tier, or the default prompt cache lifetime. Model settings apply to subsequent turns. Omitted fields are unchanged. See managing sessions.
Update an agent session
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \
-X POST \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"200 — Example
{
"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"
}Body ParametersJSON
agent: optional object { model, reasoning, service_tier, tools } Agent settings to update on this session. Omitted fields stay unchanged.
agent: optional object { model, reasoning, service_tier, tools }
Agent settings to update on this session. Omitted fields stay unchanged.
model: optional string The model for subsequent turns. Omit to keep the current model.
minLength0 maxLength1048576 reasoning: optional { effort } Reasoning settings to update. Omit to keep the current effort.
effort: optional "none" or "minimal" or "low" or 4 more or null Omit to keep the current effort. Null selects the model’s default effort.
One of the following: "none" "minimal" "low" "medium" "high" "xhigh" "max" service_tier: optional "auto" or "default" or "flex" or 3 more or null Omit to keep the current tier. Null resets it to auto.
One of the following: "auto" Selects the service tier automatically.
"default" Uses the default service tier.
"flex" Uses the flex service tier.
"priority" Uses the priority service tier.
"fast" Uses the fast service tier.
"ultrafast" Uses the ultrafast service tier.
tools: optional array of AgentToolParam or null Replaces the session tools. Functions and MCP servers change on the next model call. Built-in tools change by the next turn. Omit to keep the current tools, or pass null or an empty array to clear them.
minItems0 maxItems16384 One of the following: Function { description, name, parameters, 3 more } A function defined by the application.
description: string A description of what the function does.
minLength0 maxLength1048576 name: string The name of the function.
minLength0 maxLength1048576 parameters: map[unknown] A JSON Schema object describing the function’s arguments.
type: "function" (default: "function") The type of the object. Always function.
async: optional boolean (default: false) Whether the agent continues without waiting for the function result. Defaults to false.
defer_loading: optional boolean (default: false) Whether this function is deferred and discovered through tool search. Defaults to false.
ToolSearch { type } Discovers deferred function tools and loads them into the model context.
type: "tool_search" (default: "tool_search") The type of the object. Always tool_search.
ProgrammaticToolCalling { type, enabled } Enables calling tools from model-generated code.
type: "programmatic_tool_calling" (default: "programmatic_tool_calling") The type of the object. Always programmatic_tool_calling.
enabled: optional boolean (default: true) Whether tools can be called from model-generated code. Defaults to true.
Mcp { server_label, transport, type, 5 more } Tools provided by a remote MCP server.
server_label: string A label used to identify the MCP server in tool calls.
minLength0 maxLength1048576 transport: McpTransportParam The transport used to connect to the MCP server.
One of the following: HTTP { server_url, type, authorization, headers } Connects to an MCP server over HTTP.
server_url: string The URL of the MCP server.
minLength0 maxLength1048576 type: "http" (default: "http") The type of the object. Always http.
authorization: optional string or null The authorization value sent to the MCP server, if any.
minLength0 maxLength1048576 headers: optional map[string] or null Additional HTTP headers sent to the MCP server.
Stdio { command, cwd, type, 3 more } Starts an MCP server as a local process.
command: string The command used to start the MCP server.
minLength0 maxLength1048576 cwd: string The working directory used to start the MCP server.
minLength0 maxLength1048576 type: "stdio" (default: "stdio") The type of the object. Always stdio.
args: optional array of string or null Arguments passed to the MCP server command.
minItems0 maxItems16384 env: optional map[string] or null Environment variables set for the MCP server process.
env_vars: optional array of string or null Environment variable names to inherit from the selected execution environment.
minItems0 maxItems16384 type: "mcp" (default: "mcp") The type of the object. Always mcp.
allowed_tools: optional array of string or null The MCP tools the agent may call. All server tools are allowed when omitted.
minItems0 maxItems16384 connection_origin: optional "service" or "environment" or null Selects where outbound MCP HTTP connections originate. Omitted or service uses the Managed Agents service network; environment uses the session’s selected environment.
One of the following: "service" Uses the Managed Agents service network.
"environment" Uses the session’s execution environment.
credential_id: optional string or null The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL.
minLength0 maxLength1048576 request_metadata: optional map[unknown] or null Metadata included with requests to this MCP server.
required: optional boolean (default: false) Whether this MCP server must initialize before the first turn. Defaults to false.
WebSearch { type, allowed_domains, context_size, 2 more } Web search.
type: "web_search" (default: "web_search") The type of the object. Always web_search.
allowed_domains: optional array of string or null Domains the search may include.
minItems0 maxItems16384 context_size: optional "low" or "medium" or "high" or null The amount of search context made available to the model. Defaults to medium.
One of the following: "low" "medium" "high" location: optional object or null Approximate location used to localize search results.
city: optional string or null The city name.
minLength0 maxLength1048576 country: optional string or null The two-letter ISO country code, such as US.
minLength0 maxLength1048576 region: optional string or null The region or state name.
minLength0 maxLength1048576 timezone: optional string or null The IANA timezone, such as America/Los_Angeles.
minLength0 maxLength1048576 mode: optional "disabled" or "cached" or "live" or null The source used for web search results. Defaults to live.
One of the following: "disabled" Disables web search.
"cached" Uses cached search results.
"live" Searches the live web.
ComputerUse { type, include_screenshots } Browser use in an OpenAI-hosted session.
type: "computer_use" (default: "computer_use") The type of the object. Always computer_use.
include_screenshots: optional boolean (default: false) Whether computer tool outputs include screenshots. Defaults to false.
Automations { type } Lets the agent manage its own scheduled wakeups.
type: "automations" (default: "automations") The type of the object. Always automations.
metadata: optional map[string] or null
Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters.
prompt_cache_options: optional object { ttl } or nullDefault prompt cache lifetime for future turns. Send null to clear the session default.
prompt_cache_options: optional object { ttl } or null
Default prompt cache lifetime for future turns. Send null to clear the session default.
ttl: optional "30m" or "12h" (default: "30m") Minimum lifetime for new prompt cache entries. Defaults to 30 minutes.
One of the following: "30m" "12h"
Returns
AgentSession object { id, agent, created_at, 11 more } A Managed Agents session.
AgentSession object { id, agent, created_at, 11 more }
A Managed Agents session.
id: string The ID of the session.
minLength0 agent: { id, instructions, model, 8 more } The agent running in the session.
id: string The ID of the agent.
minLength0 instructions: string or null Custom instructions appended to the agent’s default base instructions.
minLength0 model: string The model used by the agent.
minLength0 multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents } Configuration for creating and coordinating subagents.
enabled: boolean Whether subagent tools are enabled. Defaults to false.
max_concurrent_subagents: integer or null Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.
formatint64 minimum1 maximum4294967295 name: string or null The reusable agent’s name when the session was created, or null if no name was saved. Later changes to the agent’s name do not affect this value.
minLength0 reasoning: AgentReasoning { effort, summary } The agent’s reasoning configuration.
effort: "none" or "minimal" or "low" or 4 more or null The requested reasoning effort, or null when the model selects its own default.
One of the following: "none" "minimal" "low" "medium" "high" "xhigh" "max" summary: "concise" or "detailed" or "auto" or null The requested reasoning summary format, or null when summaries are disabled.
One of the following: "concise" Returns a concise reasoning summary when supported.
"detailed" Returns a detailed reasoning summary when supported.
"auto" Automatically selects the most detailed summary supported by the model.
service_tier: "auto" or "default" or "flex" or 3 more The effective service-tier policy for model requests. Defaults to auto.
One of the following: "auto" "default" "flex" "priority" "fast" "ultrafast" text: AgentText { format, verbosity } Configuration for text generated by the agent.
format: TextFormat The effective output format. Defaults to ordinary text.
One of the following: Text { type } Generates ordinary text without a structured-output constraint.
type: "text" (default: "text") The type of the object. Always text.
JSONSchema { schema, type } Constrains generated text to a JSON Schema.
schema: map[unknown] The JSON Schema that generated text must match.
type: "json_schema" (default: "json_schema") The type of the object. Always json_schema.
verbosity: "low" or "medium" or "high" The amount of text produced by the agent. Defaults to medium.
One of the following: "low" "medium" "high" tools: array of AgentTool Tools available to the agent.
minItems0 maxItems2000 One of the following: Function { defer_loading, description, name, 3 more } A function defined by the application.
defer_loading: boolean Whether the function is deferred and discovered through tool search.
description: string A description of what the function does.
minLength0 name: string The name of the function.
minLength0 parameters: map[unknown] A JSON Schema object describing the function’s arguments.
type: "function" (default: "function") The type of the object. Always function.
async: optional boolean Whether the agent continues without waiting for the function result.
ProgrammaticToolCalling { enabled, type } Enables calling tools from model-generated code.
enabled: boolean Whether tools can be called from model-generated code.
type: "programmatic_tool_calling" (default: "programmatic_tool_calling") The type of the object. Always programmatic_tool_calling.
Mcp { allowed_tools, connection_origin, credential_id, 5 more } Tools provided by a remote MCP server.
allowed_tools: array of string or null The MCP tools the agent may call.
minItems0 maxItems2000 connection_origin: "service" or "environment" Where outbound MCP HTTP connections originate.
One of the following: "service" "environment" credential_id: string or null The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL.
minLength0 request_metadata: map[unknown] Metadata included with requests to this MCP server.
required: boolean Whether this MCP server must initialize before the first turn.
server_label: string A label used to identify the MCP server in tool calls.
minLength0 transport: McpTransport The transport used to connect to the MCP server.
One of the following: HTTP { server_url, type } Connects to an MCP server over HTTP.
server_url: string The URL of the MCP server.
minLength0 type: "http" (default: "http") The type of the object. Always http.
Stdio { args, command, cwd, 2 more } Starts an MCP server as a local process.
args: array of string Arguments passed to the MCP server command.
minItems0 maxItems2000 command: string The command used to start the MCP server.
minLength0 cwd: string The working directory used to start the MCP server.
minLength0 env_vars: array of string Environment variable names inherited from the execution environment.
minItems0 maxItems2000 type: "stdio" (default: "stdio") The type of the object. Always stdio.
type: "mcp" (default: "mcp") The type of the object. Always mcp.
WebSearch { allowed_domains, context_size, location, 2 more } Web search.
allowed_domains: array of string or null Allowed search domains, or null when the search is unrestricted.
minItems0 maxItems2000 context_size: "low" or "medium" or "high" The amount of search context made available to the model. Defaults to medium.
One of the following: "low" "medium" "high" location: object or null Approximate location used to localize search results, if provided.
city: string or null The city name.
minLength0 country: string or null The two-letter ISO country code, such as US.
minLength0 region: string or null The region or state name.
minLength0 timezone: string or null The IANA timezone, such as America/Los_Angeles.
minLength0 mode: "disabled" or "cached" or "live" The source used for web search results.
One of the following: "disabled" "cached" "live" type: "web_search" (default: "web_search") The type of the object. Always web_search.
ComputerUse { include_screenshots, type } Browser use in an OpenAI-hosted session.
include_screenshots: boolean Whether computer tool outputs include screenshots.
type: "computer_use" (default: "computer_use") The type of the object. Always computer_use.
Automations { type } Lets the agent manage its own scheduled wakeups.
type: "automations" (default: "automations") The type of the object. Always automations.
compaction: optional { async } The effective context compaction settings.
async: boolean Whether context is compacted in the background. Defaults to true.
experimental: optional { time_awareness } The effective experimental settings for the agent.
time_awareness: boolean Whether the model receives periodic current-time reminders.
created_at: integer The Unix timestamp, in seconds, when the session was created.
formatint64 environment: Environment The execution environment for the session.
One of the following: None { type } The session talks to CCA without selecting or provisioning an execution environment.
type: "none" (default: "none") The type of the object. Always none.
OpenAIHosted { id, capability_directories, desktop, 7 more } An environment hosted by OpenAI.
id: string The public ID of the environment.
minLength0 capability_directories: array of string Directories that contain capabilities exposed to the agent.
minItems0 maxItems2000 desktop: { enabled } The effective desktop configuration.
enabled: boolean Whether the environment provisions a desktop and browser proxy.
files: array of HostedEnvironmentFile Files available in the environment, excluding their contents.
minItems0 maxItems50 One of the following: HostedEnvironmentFileID { id, file_id, path, 2 more } A file copied from the OpenAI Files API.
id: string The session-scoped ID of the file in the execution environment.
minLength0 file_id: string The ID of the uploaded file.
minLength0 path: string The file’s absolute path inside the environment.
minLength0 size_bytes: integer The decoded file size in bytes.
formatint64 minimum0 type: "file_id" (default: "file_id") The type of the object. Always file_id.
Inline { id, path, size_bytes, type } A file supplied inline when the session was created.
id: string The session-scoped ID of the file in the execution environment.
minLength0 path: string The file’s absolute path inside the environment.
minLength0 size_bytes: integer The decoded file size in bytes.
formatint64 minimum0 type: "inline" (default: "inline") The type of the object. Always inline.
network: { access, allowed_domains } The effective network access policy for the environment.
access: "enabled" or "disabled" or "restricted" The environment’s network access mode.
One of the following: "enabled" Allows unrestricted network access.
"disabled" Disables network access.
"restricted" Applies the configured domain restrictions.
allowed_domains: array of string Domains the environment may access when network access is restricted.
minItems0 maxItems2000 packages: { npm, python, system } Packages installed in the environment.
npm: array of string npm packages installed globally in the environment.
minItems0 maxItems16384 python: array of string Python packages installed in the environment.
minItems0 maxItems16384 system: array of string System packages installed in the environment.
minItems0 maxItems16384 plugins: array of HostedPlugin { description, name, type } Plugins installed in the environment, excluding their archive contents.
minItems0 maxItems2000 description: string The installed plugin description.
minLength0 name: string The installed plugin name.
minLength0 type: "inline" (default: "inline") The type of the object. Always inline.
skills: array of HostedSkill Skills installed in the environment, excluding their archive contents.
minItems0 maxItems2000 One of the following: HostedSkillReference { description, name, skill_id, 2 more } A skill installed from the Skills API.
description: string The installed skill description.
minLength0 name: string The installed skill name.
minLength0 skill_id: string The referenced skill ID.
minLength0 type: "skill_reference" (default: "skill_reference") The type of the object. Always skill_reference.
version: string The concrete skill version installed for this session.
minLength0 Inline { description, name, type } A skill installed from an inline ZIP archive.
description: string The installed skill description.
minLength0 name: string The installed skill name.
minLength0 type: "inline" (default: "inline") The type of the object. Always inline.
type: "openai_hosted" (default: "openai_hosted") The type of the object. Always openai_hosted.
container_size: optional "small" or "medium" or "large" or null The effective CPU and memory tier, or null when unknown or outside the public tiers.
One of the following: "small" "medium" "large" SelfHosted { id, capability_directories, remote_url, 2 more } An environment hosted by the application.
id: string The public ID of the environment.
minLength0 capability_directories: array of string Directories that contain capabilities exposed to the agent.
minItems0 maxItems2000 remote_url: string Pass this URL unchanged to codex exec-server --remote when connecting this environment.
minLength0 type: "self_hosted" (default: "self_hosted") The type of the object. Always self_hosted.
workspace_directory: string The absolute project directory inside the environment. Defaults to /workspace.
minLength0 error: string or null The error that caused the session to fail, if any.
minLength0 last_active_at: integer The Unix timestamp, in seconds, when the session was last active.
formatint64 metadata: map[string] Custom string key-value pairs attached to the session.
object: "agent.session" (default: "agent.session") The object type. Always agent.session.
required_actions: array of McpApprovalRequest or ComputerUseApprovalRequest or FunctionCall or EnvironmentConnection Actions that must be completed before the session can continue.
minItems0 maxItems2000 One of the following: McpApprovalRequest { request, request_id, turn_id, type } Respond to an MCP tool-call approval request.
request: { arguments, message, name, 2 more } Information for presenting an MCP approval.
arguments: unknown The tool arguments as JSON, or null when CCA does not provide them.
message: string minLength0 name: string or null The tool name, or null when CCA does not provide it.
minLength0 server_label: string minLength0 type: "mcp_tool_call" (default: "mcp_tool_call") The type of the object. Always mcp_tool_call.
request_id: string The opaque approval ID to echo when responding.
minLength0 turn_id: string The turn that requested approval.
minLength0 type: "mcp_approval_request" (default: "mcp_approval_request") The type of the object. Always mcp_approval_request.
ComputerUseApprovalRequest { request, request_id, turn_id, type } Respond to a computer-use request.
request: BrowserAuthentication or BrowserOriginAccess The information needed to render the request.
One of the following: BrowserAuthentication { credential_origin, fields, options, 2 more } A registered form awaiting the application’s response.
credential_origin: string or null The registered form or frame origin where values will be entered.
minLength0 fields: array of { id, label, required, type } Controls to render. All submitted values are sensitive.
minItems0 maxItems2000 id: string The field ID to submit as field_id in a fields entry.
minLength0 label: string The label to display beside the control.
minLength0 required: boolean Whether this control requires a nonempty value.
type: string The rendering type, such as email, password, or text.
minLength0 options: array of { id, field_ids, label } Sign-in methods. Empty for a plain form.
minItems0 maxItems2000 id: string The option ID to submit as selected_option.
minLength0 field_ids: array of string IDs from the registered fields that this method accepts.
minItems0 maxItems2000 label: string The method label to display.
minLength0 reason: string or null Why the agent needs the user to sign in.
minLength0 type: "browser_authentication" (default: "browser_authentication") The type of the object. Always browser_authentication.
BrowserOriginAccess { origin, reason, type } A browser origin awaiting the application’s approval decision.
origin: string The origin the browser needs permission to access.
minLength0 reason: string or null The browser’s explanation for this request, or null when unavailable.
minLength0 type: "browser_origin_access" (default: "browser_origin_access") The type of the object. Always browser_origin_access.
request_id: string The registered request ID to echo when responding.
minLength0 turn_id: string The turn that requested approval.
minLength0 type: "computer_use_approval_request" (default: "computer_use_approval_request") The type of the object. Always computer_use_approval_request.
FunctionCall { arguments, call_id, name, 2 more } Run a function tool and submit its result.
arguments: unknown The arguments supplied by the model.
call_id: string The ID to include when submitting the function result.
minLength0 name: string The function name.
minLength0 turn_id: string The ID of the turn that requested the function call.
minLength0 type: "function_call" (default: "function_call") The type of the object. Always function_call.
EnvironmentConnection { environment_id, type } Reconnect a session environment.
environment_id: string The ID of the environment to reconnect.
minLength0 type: "environment_connection" (default: "environment_connection") The type of the object. Always environment_connection.
status: "idle" or "in_progress" or "requires_action" or "failed" The current status of the session.
One of the following: "idle" The session has no turn in progress and is ready for input. A hosted environment may still be provisioning.
"in_progress" The session is processing a turn.
"requires_action" The session is waiting for one or more required actions.
"failed" The session failed.
usage: TokenUsage or null Best-effort token usage for the session, or null if unknown. Recorded usage may change.
input_tokens: integer The number of input tokens used by the agent.
formatint64 input_tokens_details: { cached_tokens } A breakdown of the agent’s input token usage.
cached_tokens: integer The number of input tokens retrieved from the prompt cache.
formatint64 output_tokens: integer The number of output tokens generated by the agent.
formatint64 output_tokens_details: { reasoning_tokens } A breakdown of the agent’s output token usage.
reasoning_tokens: integer The number of output tokens used for reasoning.
formatint64 total_tokens: integer The total number of input and output tokens used by the agent.
formatint64 vault_ids: array of string The IDs of vaults made available to the session.
minItems0 maxItems2000 prompt_cache_options: optional object or null Default prompt cache lifetime for turns in this session, when configured.
ttl: "30m" or "12h" One of the following: "30m" "12h" review: optional "none" or "auto_review" Review applied to eligible actions in this session. Omitted when review is none and automatic review is not enabled. Omission means none.
One of the following: "none" "auto_review"
Returns Examples
200 — Example
{
"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"
}