## Update an agent **post** `/agents/{agent_id}` Updates a reusable agent. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Path Parameters - `agent_id: string` ### Body Parameters - `instructions: optional string or null` Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - `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. - `multi_agent: optional MultiAgentConfigParam 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. - `name: optional string or null` A replacement name. Omit to leave unchanged, or pass null to clear it. - `reasoning: optional AgentReasoningParam 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. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: optional "concise" or "detailed" or "auto" or null` The reasoning summary format requested from the model. - `"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. - `"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 or null` Configuration for text generated by the agent. - `format: optional TextFormatParam or null` The output format for generated text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: optional "low" or "medium" or "high" or null` The amount of text the model should produce. - `"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. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `transport: PersistedMcpTransportParam` The credential-free transport used to connect to the MCP server. - `HTTP object { server_url, type, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"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`. - `"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. - `"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. - `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`. - `"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. - `"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. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. ### Returns - `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. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` 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. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` 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. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The reasoning summary format requested from an agent. - `"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. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"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`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `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. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"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`. - `"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`. - `"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. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `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. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `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. - `type: "http"` The type of the object. Always `http`. - `"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. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"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`. - `"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. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. ### Example ```http curl https://api.openai.com/v1/agents/$AGENT_ID \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "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 } ```