--- title: "Update an agent" method: POST path: "/agents/{agent_id}" tags: ["Agents"] --- # Update an agent `POST /agents/{agent_id}` ## Request - Base URL: `https://api.openai.com/v1` - URL: `https://api.openai.com/v1/agents/{agent_id}` - Auth: HTTP bearer Updates a reusable agent. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). ## Path parameters - `agent_id` string, required ## Request body - UpdateAgentParams: Fields to replace on an existing reusable agent. - `experimental` ExperimentalConfigOverridesParam: Experimental settings to update. Omitted settings keep their current values. - `time_awareness` boolean: Whether to give the model periodic current-time reminders. Omit to keep the current setting. - `model` string: The model to use for the agent. The requested model name is preserved. - `reasoning` ReasoningParam: Reasoning configuration for the agent. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': The amount of reasoning effort the model should use. - `summary` 'concise' | 'detailed' | 'auto': The reasoning summary format requested from the model. - `text` TextParam: Configuration for text generated by the agent. - `format` union: The output format for generated text. - object: Generates ordinary text without a structured-output constraint. - `type` 'text', required: The type of the object. Always `text`. - object: Constrains generated text to a JSON Schema. - `type` 'json_schema', required: The type of the object. Always `json_schema`. - `schema` object, required: The JSON Schema that generated text must match. - `verbosity` 'low' | 'medium' | 'high': The amount of text the model should produce. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast': The service tier used for model requests. - `instructions` string, nullable: Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - `multi_agent` MultiAgentConfigCurrentParam: Explicit configuration for creating and coordinating subagents. - `enabled` boolean, required: Whether subagent tools are enabled. - `max_concurrent_subagents` integer: Maximum number of subagents that may run concurrently. Defaults to 6. - `compaction` CompactionParam: Settings for compacting the agent's context. - `async` boolean, nullable: Whether to compact context in the background. Omission or null defaults to true. Set to false to use blocking compaction. Background compaction may increase token usage. - `metadata` object, nullable: 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. - `name` string, nullable: A replacement name. Omit to leave unchanged, or pass null to clear it. - `tools` PersistedAgentToolConfigParam[], nullable: Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The replacement must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. - union: A tool that can be stored on a reusable agent without session credentials. - object: A function defined by the application. - `type` 'function', required: The type of the object. Always `function`. - `name` string, required: The name of the function. - `description` string, required: A description of what the function does. - `parameters` object, required: A JSON Schema object describing the function's arguments. - `defer_loading` boolean: Whether this function is deferred and discovered through tool search. Defaults to `false`. - object: Discovers deferred function tools and loads them into the model context. - `type` 'tool_search', required: The type of the object. Always `tool_search`. - object: Enables calling tools from model-generated code. - `type` 'programmatic_tool_calling', required: The type of the object. Always `programmatic_tool_calling`. - `enabled` boolean: Whether tools can be called from model-generated code. Defaults to `true`. - object: Tools provided by a remote MCP server without stored credentials. - `type` 'mcp', required: The type of the object. Always `mcp`. - `server_label` string, required: A label used to identify the MCP server in tool calls. - `credential_id` string, nullable: The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL. - `transport` union, required: A credential-free transport used to connect to an MCP server. - object: Connects to an MCP server over HTTP. - `type` 'http', required: The type of the object. Always `http`. - `server_url` string, required: The URL of the MCP server. - `headers` object, nullable: Non-secret HTTP headers sent to the MCP server. - object: Starts an MCP server as a local process. - `type` 'stdio', required: The type of the object. Always `stdio`. - `command` string, required: The command used to start the MCP server. - `args` string[], nullable: Arguments passed to the MCP server command. - `cwd` string, required: The working directory used to start the MCP server. - `env_vars` string[], nullable: Environment variable names to inherit from the selected execution environment. - `request_metadata` object, nullable: Metadata included with requests to this MCP server. - `allowed_tools` string[], nullable: The MCP tools the agent may call. All server tools are allowed when omitted. - `required` boolean: Whether this MCP server must initialize before the first turn. Defaults to `false`. - `connection_origin` 'service' | 'environment': Where outbound MCP HTTP connections originate. - object: Web search. - `type` 'web_search', required: The type of the object. Always `web_search`. - `mode` 'disabled' | 'cached' | 'live': The source used for web search results. - `context_size` 'low' | 'medium' | 'high': The amount of web search context made available to the model. - `allowed_domains` string[], nullable: Domains the search may include. - `location` WebSearchLocationParam: Approximate user location used to localize web search results. - `country` string, nullable: The two-letter ISO country code, such as `US`. - `region` string, nullable: The region or state name. - `city` string, nullable: The city name. - `timezone` string, nullable: The IANA timezone, such as `America/Los_Angeles`. - object: Browser use in an OpenAI-hosted session. - `type` 'computer_use', required: The type of the object. Always `computer_use`. - `include_screenshots` boolean: Whether computer tool outputs include screenshots. Defaults to `false`. - object: Lets the agent manage its own scheduled wakeups. - `type` 'automations', required: The type of the object. Always `automations`. ## Response `200` The updated agent. - AgentResource: A reusable agent scoped to the caller's project. - `id` string, required: The ID of the reusable agent. - `object` 'agent', required: The object type. Always `agent`. - `created_at` integer, required: The Unix timestamp, in seconds, when the agent was created. - `updated_at` integer, required: The Unix timestamp, in seconds, when the agent was last updated. - `name` string, nullable, required: A human-readable name for the agent, or null if it is unnamed. - `metadata` object, required: Custom string key-value pairs attached to the agent. - `model` string, required: The requested model name used for inference. - `reasoning` ReasoningResource, required: The reasoning configuration used by an agent. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', required: The amount of reasoning effort used by an agent. - `summary` 'concise' | 'detailed' | 'auto', required: The reasoning summary format requested from an agent. - `text` TextResource, required: The text configuration used by an agent. - `format` union, required: The effective output format for generated text. - object: Generates ordinary text without a structured-output constraint. - `type` 'text', required: The type of the object. Always `text`. - object: Constrains generated text to a JSON Schema. - `type` 'json_schema', required: The type of the object. Always `json_schema`. - `schema` object, required: The JSON Schema that generated text must match. - `verbosity` 'low' | 'medium' | 'high', required: The amount of text produced by an agent. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast', required: The service-tier policy configured for an agent. - `instructions` string, nullable, required: Custom instructions appended to the agent's default base instructions. - `tools` PersistedAgentToolResource[], required: Tools available to the agent. - union: A credential-free tool available to a reusable agent. - object: A function defined by the application. - `type` 'function', required: The type of the object. Always `function`. - `name` string, required: The name of the function. - `description` string, required: A description of what the function does. - `parameters` object, required: A JSON Schema object describing the function's arguments. - `defer_loading` boolean, required: Whether the function is deferred and discovered through tool search. - object: Discovers deferred function tools and loads them into the model context. - `type` 'tool_search', required: The type of the object. Always `tool_search`. - object: Enables calling tools from model-generated code. - `type` 'programmatic_tool_calling', required: The type of the object. Always `programmatic_tool_calling`. - `enabled` boolean, required: Whether tools can be called from model-generated code. - object: Tools provided by a remote MCP server without stored credentials. - `type` 'mcp', required: The type of the object. Always `mcp`. - `server_label` string, required: A label used to identify the MCP server in tool calls. - `credential_id` string, nullable, required: The vault credential selected for this MCP server, if any. - `transport` union, required: A credential-free transport used to connect to an MCP server. - object: Connects to an MCP server over HTTP. - `type` 'http', required: The type of the object. Always `http`. - `server_url` string, required: The URL of the MCP server. - `headers` object, required: Non-secret HTTP headers sent to the MCP server. - object: Starts an MCP server as a local process. - `type` 'stdio', required: The type of the object. Always `stdio`. - `command` string, required: The command used to start the MCP server. - `args` string[], required: Arguments passed to the MCP server command. - `cwd` string, required: The working directory used to start the MCP server. - `env_vars` string[], required: Environment variable names inherited from the execution environment. - `request_metadata` object, required: Metadata included with requests to this MCP server. - `allowed_tools` string[], nullable, required: The MCP tools the agent may call, or null when all server tools are allowed. - `required` boolean, required: Whether this MCP server must initialize before the first turn. - `connection_origin` 'service' | 'environment', required: Where outbound MCP HTTP connections originate. - object: Web search. - `type` 'web_search', required: The type of the object. Always `web_search`. - `mode` 'disabled' | 'cached' | 'live', required: The source used for web search results. - `context_size` 'low' | 'medium' | 'high', required: The amount of web search context made available to the model. - `allowed_domains` string[], nullable, required: Allowed search domains, or `null` when the search is unrestricted. - `location` WebSearchLocationResource, required: Approximate user location used to localize web search results. - `country` string, nullable, required: The two-letter ISO country code, such as `US`. - `region` string, nullable, required: The region or state name. - `city` string, nullable, required: The city name. - `timezone` string, nullable, required: The IANA timezone, such as `America/Los_Angeles`. - object: Browser use in an OpenAI-hosted session. - `type` 'computer_use', required: The type of the object. Always `computer_use`. - `include_screenshots` boolean, required: Whether computer tool outputs include screenshots. - object: Lets the agent manage its own scheduled wakeups. - `type` 'automations', required: The type of the object. Always `automations`. - `multi_agent` MultiAgentConfigResource, required: The resolved configuration for creating and coordinating subagents. - `enabled` boolean, required: Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents` integer, nullable, required: Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `compaction` CompactionResource: The effective settings for compacting the agent's context. - `async` boolean, required: Whether context is compacted in the background. Defaults to true. - `experimental` ExperimentalConfigResource: The effective experimental settings for an agent. - `time_awareness` boolean, required: Whether the model receives periodic current-time reminders. ## Other responses - `400`: The request was invalid. - `401`: Authentication or project context was missing. - `403`: The API key lacks the required permission. - `404`: The requested session or event was not found. - `409`: The request conflicted with the current session state. - `500`: An internal error occurred. - `503`: The service is temporarily unavailable. ## Changes - **2026-10-29** `0a26f104d35f`: 2 info - added the new optional request property `experimental` - added the optional property `experimental` to the response with the `200` status - **2026-10-28** `81bec64c97ee`: 2 info - added the new optional request property `compaction` - added the optional property `compaction` to the response with the `200` status - **2026-10-23** `edf54d38a1a0`: 1 breaking, 3 info - added `#/components/schemas/PersistedAgentToolResourceAutomations` to the `tools/items/` response property `oneOf` list for the response status `200` - added `automations` discriminator mapping keys to the `tools/items/` request property - added `#/components/schemas/PersistedAgentToolConfigParamAutomations` to the `tools/items/` request property `oneOf` list - added `automations` discriminator mapping keys to the `tools/items/` response property for the response status `200` - **2026-10-16** `909d15009c82`: 1 info - added the new `ultrafast` enum value to the request property `service_tier/anyOf[#/components/schemas/ServiceTierParam]/` - **2026-10-05** `7f654af7f94f`: 1 info - endpoint added [Operation history](https://skmtc.dev/omnistack-sh/apis/openai-api/changes/agents/:agent_id/post.md) --- [API](https://skmtc.dev/omnistack-sh/apis/openai-api.md) - [All operations](https://skmtc.dev/omnistack-sh/apis/openai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnistack-sh/apis/openai-api/revisions/0a26f104d35f?raw)