## Update an agent `Agent beta().agents().update(AgentUpdateParamsparams = AgentUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **post** `/agents/{agent_id}` Updates a reusable agent. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Parameters - `AgentUpdateParams params` - `Optional agentId` - `Optional instructions` Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - `Optional metadata` 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. - `Optional model` The model to use for the agent. The requested model name is preserved. - `Optional multiAgent` Configuration for creating and coordinating subagents. - `Optional name` A replacement name. Omit to leave unchanged, or pass null to clear it. - `Optional reasoning` Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort. - `Optional serviceTier` The service tier used for model requests. - `AUTO("auto")` Selects the service tier automatically. - `DEFAULT("default")` Uses the default service tier. - `FLEX("flex")` Uses the flex service tier. - `PRIORITY("priority")` Uses the priority service tier. - `FAST("fast")` Uses the fast service tier. - `Optional text` Configuration for text generated by the agent. - `Optional> tools` Tools available to the agent. - `Function` - `String description` A description of what the function does. - `String name` The name of the function. - `Parameters parameters` A JSON Schema object describing the function's arguments. - `JsonValue; type "function"constant` The type of the object. Always `function`. - `FUNCTION("function")` - `Optional deferLoading` Whether this function is deferred and discovered through tool search. Defaults to `false`. - `JsonValue;` - `JsonValue; type "tool_search"constant` The type of the object. Always `tool_search`. - `TOOL_SEARCH("tool_search")` - `ProgrammaticToolCalling` - `JsonValue; type "programmatic_tool_calling"constant` The type of the object. Always `programmatic_tool_calling`. - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - `Optional enabled` Whether tools can be called from model-generated code. Defaults to `true`. - `Mcp` - `String serverLabel` A label used to identify the MCP server in tool calls. - `PersistedMcpTransportParam transport` The credential-free transport used to connect to the MCP server. - `Http` - `String serverUrl` The URL of the MCP server. - `JsonValue; type "http"constant` The type of the object. Always `http`. - `HTTP("http")` - `Optional headers` Non-secret HTTP headers sent to the MCP server. - `Stdio` - `String command` The command used to start the MCP server. - `String cwd` The working directory used to start the MCP server. - `JsonValue; type "stdio"constant` The type of the object. Always `stdio`. - `STDIO("stdio")` - `Optional> args` Arguments passed to the MCP server command. - `Optional> envVars` Environment variable names to inherit from the selected execution environment. - `JsonValue; type "mcp"constant` The type of the object. Always `mcp`. - `MCP("mcp")` - `Optional> allowedTools` The MCP tools the agent may call. All server tools are allowed when omitted. - `Optional connectionOrigin` Selects where outbound MCP HTTP connections originate. - `SERVICE("service")` Uses the Managed Agents service network. - `ENVIRONMENT("environment")` Uses the session's execution environment. - `Optional credentialId` The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL. - `Optional requestMetadata` Metadata included with requests to this MCP server. - `Optional required` Whether this MCP server must initialize before the first turn. Defaults to `false`. - `WebSearch` - `JsonValue; type "web_search"constant` The type of the object. Always `web_search`. - `WEB_SEARCH("web_search")` - `Optional> allowedDomains` Domains the search may include. - `Optional contextSize` The amount of search context made available to the model. Defaults to `medium`. - `LOW("low")` - `MEDIUM("medium")` - `HIGH("high")` - `Optional location` Approximate location used to localize search results. - `Optional city` The city name. - `Optional country` The two-letter ISO country code, such as `US`. - `Optional region` The region or state name. - `Optional timezone` The IANA timezone, such as `America/Los_Angeles`. - `Optional mode` The source used for web search results. Defaults to `live`. - `DISABLED("disabled")` Disables web search. - `CACHED("cached")` Uses cached search results. - `LIVE("live")` Searches the live web. ### Returns - `class Agent:` A reusable agent scoped to the caller's project. - `String id` The ID of the reusable agent. - `long createdAt` The Unix timestamp, in seconds, when the agent was created. - `Optional instructions` Custom instructions appended to the agent's default base instructions. - `Metadata metadata` Custom string key-value pairs attached to the agent. - `String model` The requested model name used for inference. - `MultiAgentConfig multiAgent` The resolved configuration for creating and coordinating subagents. - `boolean enabled` Whether subagent tools are enabled. Defaults to false. - `Optional maxConcurrentSubagents` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `Optional name` A human-readable name for the agent, or null if it is unnamed. - `JsonValue; object_ "agent"constant` The object type. Always `agent`. - `AGENT("agent")` - `AgentReasoning reasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `Optional effort` The requested reasoning effort, or `null` when the model selects its own default. - `NONE("none")` - `MINIMAL("minimal")` - `LOW("low")` - `MEDIUM("medium")` - `HIGH("high")` - `XHIGH("xhigh")` - `MAX("max")` - `Optional summary` The requested reasoning summary format, or `null` when summaries are disabled. - `CONCISE("concise")` Returns a concise reasoning summary when supported. - `DETAILED("detailed")` Returns a detailed reasoning summary when supported. - `AUTO("auto")` Automatically selects the most detailed summary supported by the model. - `ServiceTier serviceTier` The resolved service-tier policy used for model requests. - `AUTO("auto")` - `DEFAULT("default")` - `FLEX("flex")` - `PRIORITY("priority")` - `FAST("fast")` - `AgentText text` The resolved configuration for text generated by the agent. - `TextFormat format` The effective output format. Defaults to ordinary text. - `JsonValue;` - `JsonValue; type "text"constant` The type of the object. Always `text`. - `TEXT("text")` - `JsonSchema` - `Schema schema` The JSON Schema that generated text must match. - `JsonValue; type "json_schema"constant` The type of the object. Always `json_schema`. - `JSON_SCHEMA("json_schema")` - `Verbosity verbosity` The amount of text produced by the agent. Defaults to `medium`. - `LOW("low")` - `MEDIUM("medium")` - `HIGH("high")` - `List tools` Tools available to the agent. - `Function` - `boolean deferLoading` Whether the function is deferred and discovered through tool search. - `String description` A description of what the function does. - `String name` The name of the function. - `Parameters parameters` A JSON Schema object describing the function's arguments. - `JsonValue; type "function"constant` The type of the object. Always `function`. - `FUNCTION("function")` - `JsonValue;` - `JsonValue; type "tool_search"constant` The type of the object. Always `tool_search`. - `TOOL_SEARCH("tool_search")` - `ProgrammaticToolCalling` - `boolean enabled` Whether tools can be called from model-generated code. - `JsonValue; type "programmatic_tool_calling"constant` The type of the object. Always `programmatic_tool_calling`. - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - `Mcp` - `Optional> allowedTools` The MCP tools the agent may call, or null when all server tools are allowed. - `ConnectionOrigin connectionOrigin` Where outbound MCP HTTP connections originate. - `SERVICE("service")` - `ENVIRONMENT("environment")` - `Optional credentialId` The vault credential selected for this MCP server, if any. - `RequestMetadata requestMetadata` Metadata included with requests to this MCP server. - `boolean required` Whether this MCP server must initialize before the first turn. - `String serverLabel` A label used to identify the MCP server in tool calls. - `PersistedMcpTransport transport` The credential-free transport used to connect to the MCP server. - `Http` - `Headers headers` Non-secret HTTP headers sent to the MCP server. - `String serverUrl` The URL of the MCP server. - `JsonValue; type "http"constant` The type of the object. Always `http`. - `HTTP("http")` - `Stdio` - `List args` Arguments passed to the MCP server command. - `String command` The command used to start the MCP server. - `String cwd` The working directory used to start the MCP server. - `List envVars` Environment variable names inherited from the execution environment. - `JsonValue; type "stdio"constant` The type of the object. Always `stdio`. - `STDIO("stdio")` - `JsonValue; type "mcp"constant` The type of the object. Always `mcp`. - `MCP("mcp")` - `WebSearch` - `Optional> allowedDomains` Allowed search domains, or `null` when the search is unrestricted. - `ContextSize contextSize` The amount of search context made available to the model. Defaults to `medium`. - `LOW("low")` - `MEDIUM("medium")` - `HIGH("high")` - `Optional location` Approximate location used to localize search results, if provided. - `Optional city` The city name. - `Optional country` The two-letter ISO country code, such as `US`. - `Optional region` The region or state name. - `Optional timezone` The IANA timezone, such as `America/Los_Angeles`. - `Mode mode` The source used for web search results. - `DISABLED("disabled")` - `CACHED("cached")` - `LIVE("live")` - `JsonValue; type "web_search"constant` The type of the object. Always `web_search`. - `WEB_SEARCH("web_search")` - `long updatedAt` The Unix timestamp, in seconds, when the agent was last updated. ### Example ```java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.agents.Agent; import com.openai.models.beta.agents.AgentUpdateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Agent agent = client.beta().agents().update("agent_id"); } } ``` #### 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 } ```