Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference
API Reference
Beta
Agents

Update an agent

POST/agents/{agent_id}

Updates a reusable agent. See agent configuration.

Path ParametersExpand Collapse
agent_id: string
minLength0
maxLength1048576
Body ParametersJSONExpand Collapse
instructions: optional string or null

Additional instructions appended to the agent’s default base instructions. Omit to leave unchanged.

minLength0
maxLength1048576
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.

model: optional string

The model to use for the agent. The requested model name is preserved.

minLength0
maxLength1048576
multi_agent: optional MultiAgentConfigParam { enabled, max_concurrent_subagents } or null

Explicit configuration for creating and coordinating subagents.

enabled: boolean

Whether subagent tools are enabled.

max_concurrent_subagents: optional number

Maximum number of subagents that may run concurrently. Defaults to 6.

formatint64
minimum1
maximum4294967295
name: optional string or null

A replacement name. Omit to leave unchanged, or pass null to clear it.

minLength0
maxLength128
reasoning: optional AgentReasoningParam { effort, summary } or null

Reasoning configuration for the agent.

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

The amount of reasoning effort the model should use.

One of the following:
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: optional "concise" or "detailed" or "auto" or null

The reasoning summary format requested from the model.

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: optional "auto" or "default" or "flex" or 2 more or null

The service tier used for model requests.

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.

text: optional AgentTextParam { format, verbosity } or null

Configuration for text generated by the agent.

format: optional TextFormatParam or null

The output format for generated text.

One of the following:
Text object { type }

Generates ordinary text without a structured-output constraint.

type: "text"

The type of the object. Always text.

JSONSchema object { schema, type }

Constrains generated text to a JSON Schema.

schema: map[unknown]

The JSON Schema that generated text must match.

type: "json_schema"

The type of the object. Always json_schema.

verbosity: optional "low" or "medium" or "high" or null

The amount of text the model should produce.

One of the following:
"low"

Produces less text.

"medium"

Uses the default amount of text.

"high"

Produces more text.

tools: optional array of PersistedAgentToolParam or null

Tools available to the agent.

One of the following:
Function object { description, name, parameters, 2 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"

The type of the object. Always function.

defer_loading: optional boolean

Whether this function is deferred and discovered through tool search. Defaults to false.

ToolSearch object { type }

Discovers deferred function tools and loads them into the model context.

type: "tool_search"

The type of the object. Always tool_search.

ProgrammaticToolCalling object { type, enabled }

Enables calling tools from model-generated code.

type: "programmatic_tool_calling"

The type of the object. Always programmatic_tool_calling.

enabled: optional boolean

Whether tools can be called from model-generated code. Defaults to true.

Mcp object { server_label, transport, type, 5 more }

Tools provided by a remote MCP server without stored credentials.

server_label: string

A label used to identify the MCP server in tool calls.

minLength0
maxLength1048576
transport: PersistedMcpTransportParam

The credential-free transport used to connect to the MCP server.

One of the following:
HTTP object { server_url, type, headers }

Connects to an MCP server over HTTP.

server_url: string

The URL of the MCP server.

minLength0
maxLength1048576
type: "http"

The type of the object. Always http.

headers: optional map[string] or null

Non-secret HTTP headers sent to the MCP server.

Stdio object { command, cwd, type, 2 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"

The type of the object. Always stdio.

args: optional array of string or null

Arguments passed to the MCP server command.

env_vars: optional array of string or null

Environment variable names to inherit from the selected execution environment.

type: "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.

connection_origin: optional "service" or "environment" or null

Where outbound MCP HTTP connections originate.

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 vault credential selected for 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

Whether this MCP server must initialize before the first turn. Defaults to false.

WebSearch object { type, allowed_domains, context_size, 2 more }

Web search.

type: "web_search"

The type of the object. Always web_search.

allowed_domains: optional array of string or null

Domains the search may include.

context_size: optional "low" or "medium" or "high" or null

The amount of web search context made available to the model.

One of the following:
"low"
"medium"
"high"
location: optional object { city, country, region, timezone } or null

Approximate user location used to localize web 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.

One of the following:
"disabled"

Disables web search.

"cached"

Uses cached search results.

"live"

Searches the live web.

ReturnsExpand Collapse
Agent object { id, created_at, instructions, 10 more }

A reusable agent scoped to the caller’s project.

id: string

The ID of the reusable agent.

minLength0
created_at: number

The Unix timestamp, in seconds, when the agent was created.

formatint64
instructions: string or null

Custom instructions appended to the agent’s default base instructions.

minLength0
metadata: map[string]

Custom string key-value pairs attached to the agent.

model: string

The requested model name used for inference.

minLength0
multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

enabled: boolean

Whether subagent tools are enabled. Defaults to false.

max_concurrent_subagents: number 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

A human-readable name for the agent, or null if it is unnamed.

minLength0
object: "agent"

The object type. Always agent.

reasoning: AgentReasoning { effort, summary }

The resolved reasoning configuration, including the model default for an omitted effort.

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

The amount of reasoning effort used by an agent.

One of the following:
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: "concise" or "detailed" or "auto" or null

The reasoning summary format requested from an agent.

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 2 more

The resolved service-tier policy used for model requests.

One of the following:
"auto"
"default"
"flex"
"priority"
"fast"
text: AgentText { format, verbosity }

The resolved configuration for text generated by the agent.

format: TextFormat

The effective output format. Defaults to ordinary text.

One of the following:
Text object { type }

Generates ordinary text without a structured-output constraint.

type: "text"

The type of the object. Always text.

JSONSchema object { schema, type }

Constrains generated text to a JSON Schema.

schema: map[unknown]

The JSON Schema that generated text must match.

type: "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 PersistedAgentTool

Tools available to the agent.

One of the following:
Function object { defer_loading, description, name, 2 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"

The type of the object. Always function.

ToolSearch object { type }

Discovers deferred function tools and loads them into the model context.

type: "tool_search"

The type of the object. Always tool_search.

ProgrammaticToolCalling object { enabled, type }

Enables calling tools from model-generated code.

enabled: boolean

Whether tools can be called from model-generated code.

type: "programmatic_tool_calling"

The type of the object. Always programmatic_tool_calling.

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

Tools provided by a remote MCP server without stored credentials.

allowed_tools: array of string or null

The MCP tools the agent may call, or null when all server tools are allowed.

connection_origin: "service" or "environment"

Where outbound MCP HTTP connections originate.

One of the following:
"service"
"environment"
credential_id: string or null

The vault credential selected for this MCP server, if any.

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: PersistedMcpTransport

The credential-free transport used to connect to the MCP server.

One of the following:
HTTP object { headers, server_url, type }

Connects to an MCP server over HTTP.

headers: map[string]

Non-secret HTTP headers sent to the MCP server.

server_url: string

The URL of the MCP server.

minLength0
type: "http"

The type of the object. Always http.

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

Starts an MCP server as a local process.

args: array of string

Arguments passed to the MCP server command.

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.

type: "stdio"

The type of the object. Always stdio.

type: "mcp"

The type of the object. Always mcp.

WebSearch object { 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.

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 { city, country, region, timezone } or null

Approximate user location used to localize web search results.

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"

The type of the object. Always web_search.

updated_at: number

The Unix timestamp, in seconds, when the agent was last updated.

formatint64

Update an agent

curl https://api.openai.com/v1/agents/$AGENT_ID \
    -X POST \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"
{
  "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"
    }
  ],
  "updated_at": 0
}
Returns Examples
{
  "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"
    }
  ],
  "updated_at": 0
}