{"command":{"effect":"write","timeoutSeconds":120,"inputSchema":{"type":"object","description":"Updates session tools, metadata, model, reasoning effort, or service tier. Model settings apply to subsequent turns. Omitted fields are unchanged. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).","properties":{"path":{"type":"object","properties":{"session_id":{"type":"string","minLength":0,"maxLength":1048576,"description":"The ID of the session."}},"required":["session_id"],"additionalProperties":false},"body":{"$ref":"#/definitions/UpdateAgentSessionParams"}},"required":["path"],"additionalProperties":false,"definitions":{"UpdateAgentSessionParams":{"type":"object","properties":{"review":{"$ref":"#/definitions/SessionReviewParam"},"agent":{"$ref":"#/definitions/UpdateSessionAgentParam"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string","minLength":0,"maxLength":512},"propertyNames":{"type":"string","minLength":1,"maxLength":64},"minProperties":0,"maxProperties":16,"description":"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."}},"additionalProperties":false,"description":"Fields to update on an existing session."},"SessionReviewParam":{"type":"string","enum":["none","auto_review"],"description":"Review applied to eligible actions in a session."},"UpdateSessionAgentParam":{"type":"object","properties":{"tools":{"type":["array","null"],"items":{"$ref":"#/definitions/AgentToolConfigParam"},"minItems":0,"maxItems":16384,"description":"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."},"model":{"type":"string","minLength":0,"maxLength":1048576,"description":"The model for subsequent turns. Omit to keep the current model."},"reasoning":{"$ref":"#/definitions/UpdateSessionReasoningParam"},"service_tier":{"anyOf":[{"$ref":"#/definitions/ServiceTierParam"},{"type":"null"}],"description":"Omit to keep the current tier. Null resets it to auto."}},"additionalProperties":false,"description":"Agent settings that can change after session creation."},"AgentToolConfigParam":{"oneOf":[{"$ref":"#/definitions/AgentToolConfigParamFunction"},{"$ref":"#/definitions/AgentToolConfigParamToolSearch"},{"$ref":"#/definitions/AgentToolConfigParamProgrammaticToolCalling"},{"$ref":"#/definitions/AgentToolConfigParamMcp"},{"$ref":"#/definitions/AgentToolConfigParamWebSearch"},{"$ref":"#/definitions/AgentToolConfigParamComputerUse"},{"$ref":"#/definitions/AgentToolConfigParamAutomations"}],"description":"A tool available to the agent."},"UpdateSessionReasoningParam":{"type":"object","properties":{"effort":{"anyOf":[{"$ref":"#/definitions/ReasoningEffortParam"},{"type":"null"}],"description":"Omit to keep the current effort. Null selects the model's default effort."}},"additionalProperties":false,"description":"Reasoning effort for subsequent turns. The reasoning summary stays unchanged."},"ServiceTierParam":{"type":"string","enum":["auto","default","flex","priority","fast","ultrafast"],"description":"The service tier used for model requests."},"AgentToolConfigParamFunction":{"type":"object","properties":{"type":{"type":"string","enum":["function"],"default":"function","description":"The type of the object. Always `function`."},"name":{"type":"string","minLength":0,"maxLength":1048576,"description":"The name of the function."},"description":{"type":"string","minLength":0,"maxLength":1048576,"description":"A description of what the function does."},"parameters":{"type":"object","additionalProperties":{},"propertyNames":{"type":"string","minLength":1,"maxLength":256},"minProperties":0,"maxProperties":1024,"description":"A JSON Schema object describing the function's arguments."},"defer_loading":{"type":"boolean","default":false,"description":"Whether this function is deferred and discovered through tool search. Defaults to `false`."}},"required":["type","name","description","parameters"],"additionalProperties":false,"description":"A function defined by the application."},"AgentToolConfigParamToolSearch":{"type":"object","properties":{"type":{"type":"string","enum":["tool_search"],"default":"tool_search","description":"The type of the object. Always `tool_search`."}},"required":["type"],"additionalProperties":false,"description":"Discovers deferred function tools and loads them into the model context."},"AgentToolConfigParamProgrammaticToolCalling":{"type":"object","properties":{"type":{"type":"string","enum":["programmatic_tool_calling"],"default":"programmatic_tool_calling","description":"The type of the object. Always `programmatic_tool_calling`."},"enabled":{"type":"boolean","default":true,"description":"Whether tools can be called from model-generated code. Defaults to `true`."}},"required":["type"],"additionalProperties":false,"description":"Enables calling tools from model-generated code."},"AgentToolConfigParamMcp":{"type":"object","properties":{"type":{"type":"string","enum":["mcp"],"default":"mcp","description":"The type of the object. Always `mcp`."},"server_label":{"type":"string","minLength":0,"maxLength":1048576,"description":"A label used to identify the MCP server in tool calls."},"credential_id":{"type":["string","null"],"minLength":0,"maxLength":1048576,"description":"The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL."},"transport":{"$ref":"#/definitions/McpTransportConfigParam"},"request_metadata":{"type":["object","null"],"additionalProperties":{},"propertyNames":{"type":"string","minLength":1,"maxLength":256},"minProperties":0,"maxProperties":1024,"description":"Metadata included with requests to this MCP server."},"allowed_tools":{"type":["array","null"],"items":{"type":"string","minLength":0,"maxLength":1048576},"minItems":0,"maxItems":16384,"description":"The MCP tools the agent may call. All server tools are allowed when omitted."},"required":{"type":"boolean","default":false,"description":"Whether this MCP server must initialize before the first turn. Defaults to `false`."},"connection_origin":{"anyOf":[{"$ref":"#/definitions/McpConnectionOriginParam"},{"type":"null"}],"description":"Selects where outbound MCP HTTP connections originate. Omitted or `service` uses the Managed Agents service network; `environment` uses the session's selected environment."}},"required":["type","server_label","transport"],"additionalProperties":false,"description":"Tools provided by a remote MCP server."},"AgentToolConfigParamWebSearch":{"type":"object","properties":{"type":{"type":"string","enum":["web_search"],"default":"web_search","description":"The type of the object. Always `web_search`."},"mode":{"anyOf":[{"$ref":"#/definitions/WebSearchModeParam"},{"type":"null"}],"description":"The source used for web search results. Defaults to `live`."},"context_size":{"anyOf":[{"$ref":"#/definitions/WebSearchContextSizeParam"},{"type":"null"}],"description":"The amount of search context made available to the model. Defaults to `medium`."},"allowed_domains":{"type":["array","null"],"items":{"type":"string","minLength":0,"maxLength":1048576},"minItems":0,"maxItems":16384,"description":"Domains the search may include."},"location":{"anyOf":[{"$ref":"#/definitions/WebSearchLocationParam"},{"type":"null"}],"description":"Approximate location used to localize search results."}},"required":["type"],"additionalProperties":false,"description":"Web search."},"AgentToolConfigParamComputerUse":{"type":"object","properties":{"type":{"type":"string","enum":["computer_use"],"default":"computer_use","description":"The type of the object. Always `computer_use`."},"include_screenshots":{"type":"boolean","default":false,"description":"Whether computer tool outputs include screenshots. Defaults to `false`."}},"required":["type"],"additionalProperties":false,"description":"Browser use in an OpenAI-hosted session."},"AgentToolConfigParamAutomations":{"type":"object","properties":{"type":{"type":"string","enum":["automations"],"default":"automations","description":"The type of the object. Always `automations`."}},"required":["type"],"additionalProperties":false,"description":"Lets the agent manage its own scheduled wakeups."},"ReasoningEffortParam":{"type":"string","enum":["none","minimal","low","medium","high","xhigh","max"],"description":"The amount of reasoning effort the model should use."},"McpTransportConfigParam":{"oneOf":[{"$ref":"#/definitions/McpTransportConfigParamHttp"},{"$ref":"#/definitions/McpTransportConfigParamStdio"}],"description":"The transport used to connect to an MCP server."},"McpConnectionOriginParam":{"type":"string","enum":["service","environment"],"description":"Where outbound MCP HTTP connections originate."},"WebSearchModeParam":{"type":"string","enum":["disabled","cached","live"],"description":"The source used for web search results."},"WebSearchContextSizeParam":{"type":"string","enum":["low","medium","high"],"description":"The amount of web search context made available to the model."},"WebSearchLocationParam":{"type":"object","properties":{"country":{"type":["string","null"],"minLength":0,"maxLength":1048576,"description":"The two-letter ISO country code, such as `US`."},"region":{"type":["string","null"],"minLength":0,"maxLength":1048576,"description":"The region or state name."},"city":{"type":["string","null"],"minLength":0,"maxLength":1048576,"description":"The city name."},"timezone":{"type":["string","null"],"minLength":0,"maxLength":1048576,"description":"The IANA timezone, such as `America/Los_Angeles`."}},"additionalProperties":false,"description":"Approximate user location used to localize web search results."},"McpTransportConfigParamHttp":{"type":"object","properties":{"type":{"type":"string","enum":["http"],"default":"http","description":"The type of the object. Always `http`."},"server_url":{"type":"string","minLength":0,"maxLength":1048576,"description":"The URL of the MCP server."},"authorization":{"type":["string","null"],"minLength":0,"maxLength":1048576,"description":"The authorization value sent to the MCP server, if any."},"headers":{"type":["object","null"],"additionalProperties":{"type":"string","minLength":0,"maxLength":1048576},"propertyNames":{"type":"string","minLength":1,"maxLength":256},"minProperties":0,"maxProperties":1024,"description":"Additional HTTP headers sent to the MCP server."}},"required":["type","server_url"],"additionalProperties":false,"description":"Connects to an MCP server over HTTP."},"McpTransportConfigParamStdio":{"type":"object","properties":{"type":{"type":"string","enum":["stdio"],"default":"stdio","description":"The type of the object. Always `stdio`."},"command":{"type":"string","minLength":0,"maxLength":1048576,"description":"The command used to start the MCP server."},"args":{"type":["array","null"],"items":{"type":"string","minLength":0,"maxLength":1048576},"minItems":0,"maxItems":16384,"description":"Arguments passed to the MCP server command."},"cwd":{"type":"string","minLength":0,"maxLength":1048576,"description":"The working directory used to start the MCP server."},"env":{"type":["object","null"],"additionalProperties":{"type":"string","minLength":0,"maxLength":1048576},"propertyNames":{"type":"string","minLength":1,"maxLength":256},"minProperties":0,"maxProperties":1024,"description":"Environment variables set for the MCP server process."},"env_vars":{"type":["array","null"],"items":{"type":"string","minLength":0,"maxLength":1048576},"minItems":0,"maxItems":16384,"description":"Environment variable names to inherit from the selected execution environment."}},"required":["type","command","cwd"],"additionalProperties":false,"description":"Starts an MCP server as a local process."}}},"name":"Update an agent session","id":"openai.updateagentsession","example":{"path":{"session_id":"example"}},"maxRequests":1,"summary":false}}