## Update an agent session

`beta.agents.sessions.update(strsession_id, SessionUpdateParams**kwargs)  -> AgentSession`

**post** `/agents/sessions/{session_id}`

Updates session tools, metadata, model, reasoning effort, service tier, or the default prompt cache lifetime. Model settings apply to subsequent turns. Omitted fields are unchanged. See [managing sessions](/api/docs/guides/agents-api/sessions/manage).

### Parameters

- `session_id: str`

  `minLength: 0`, `maxLength: 1048576`

- `agent: Optional[Agent]`

  Agent settings to update on this session. Omitted fields stay unchanged.

  - `model: Optional[str]`

    The model for subsequent turns. Omit to keep the current model.

    `minLength: 0`, `maxLength: 1048576`

  - `reasoning: Optional[AgentReasoning]`

    Reasoning settings to update. Omit to keep the current effort.

    - `effort: Optional[Literal["none", "minimal", "low", 4 more]]`

      Omit to keep the current effort. Null selects the model's default effort.

      - `"none"`

      - `"minimal"`

      - `"low"`

      - `"medium"`

      - `"high"`

      - `"xhigh"`

      - `"max"`

  - `service_tier: Optional[Literal["auto", "default", "flex", 3 more]]`

    Omit to keep the current tier. Null resets it to auto.

    - `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.
    - `ultrafast` - Uses the ultrafast service tier.

    - `"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.

    - `"ultrafast"`

      Uses the ultrafast service tier.

  - `tools: Optional[Iterable[AgentToolParam]]`

    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.

    `minItems: 0`, `maxItems: 16384`

    - `class AgentToolConfigParamFunction: …`

      A function defined by the application.

      - `description: str`

        A description of what the function does.

        `minLength: 0`, `maxLength: 1048576`

      - `name: str`

        The name of the function.

        `minLength: 0`, `maxLength: 1048576`

      - `parameters: Dict[str, object]`

        A JSON Schema object describing the function's arguments.

      - `type: Literal["function"]`

        The type of the object. Always `function`.

        - `"function"`

      - `async_: Optional[bool]`

        Whether the agent continues without waiting for the function result. Defaults to `false`.

      - `defer_loading: Optional[bool]`

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

    - `class AgentToolConfigParamToolSearch: …`

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

      - `type: Literal["tool_search"]`

        The type of the object. Always `tool_search`.

        - `"tool_search"`

    - `class AgentToolConfigParamProgrammaticToolCalling: …`

      Enables calling tools from model-generated code.

      - `type: Literal["programmatic_tool_calling"]`

        The type of the object. Always `programmatic_tool_calling`.

        - `"programmatic_tool_calling"`

      - `enabled: Optional[bool]`

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

    - `class AgentToolConfigParamMcp: …`

      Tools provided by a remote MCP server.

      - `server_label: str`

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

        `minLength: 0`, `maxLength: 1048576`

      - `transport: McpTransportParam`

        The transport used to connect to the MCP server.

        - `class McpTransportConfigParamHTTP: …`

          Connects to an MCP server over HTTP.

          - `server_url: str`

            The URL of the MCP server.

            `minLength: 0`, `maxLength: 1048576`

          - `type: Literal["http"]`

            The type of the object. Always `http`.

            - `"http"`

          - `authorization: Optional[str]`

            The authorization value sent to the MCP server, if any.

            `minLength: 0`, `maxLength: 1048576`

          - `headers: Optional[Dict[str, str]]`

            Additional HTTP headers sent to the MCP server.

        - `class McpTransportConfigParamStdio: …`

          Starts an MCP server as a local process.

          - `command: str`

            The command used to start the MCP server.

            `minLength: 0`, `maxLength: 1048576`

          - `cwd: str`

            The working directory used to start the MCP server.

            `minLength: 0`, `maxLength: 1048576`

          - `type: Literal["stdio"]`

            The type of the object. Always `stdio`.

            - `"stdio"`

          - `args: Optional[List[str]]`

            Arguments passed to the MCP server command.

            `minItems: 0`, `maxItems: 16384`

          - `env: Optional[Dict[str, str]]`

            Environment variables set for the MCP server process.

          - `env_vars: Optional[List[str]]`

            Environment variable names to inherit from the selected execution environment.

            `minItems: 0`, `maxItems: 16384`

      - `type: Literal["mcp"]`

        The type of the object. Always `mcp`.

        - `"mcp"`

      - `allowed_tools: Optional[List[str]]`

        The MCP tools the agent may call. All server tools are allowed when omitted.

        `minItems: 0`, `maxItems: 16384`

      - `connection_origin: Optional[Literal["service", "environment"]]`

        Selects where outbound MCP HTTP connections originate. Omitted or `service` uses the Managed Agents service network; `environment` uses the session's selected environment.

        - `"service"`

          Uses the Managed Agents service network.

        - `"environment"`

          Uses the session's execution environment.

      - `credential_id: Optional[str]`

        The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL.

        `minLength: 0`, `maxLength: 1048576`

      - `request_metadata: Optional[Dict[str, object]]`

        Metadata included with requests to this MCP server.

      - `required: Optional[bool]`

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

    - `class AgentToolConfigParamWebSearch: …`

      Web search.

      - `type: Literal["web_search"]`

        The type of the object. Always `web_search`.

        - `"web_search"`

      - `allowed_domains: Optional[List[str]]`

        Domains the search may include.

        `minItems: 0`, `maxItems: 16384`

      - `context_size: Optional[Literal["low", "medium", "high"]]`

        The amount of search context made available to the model. Defaults to `medium`.

        - `"low"`

        - `"medium"`

        - `"high"`

      - `location: Optional[AgentToolConfigParamWebSearchLocation]`

        Approximate location used to localize search results.

        - `city: Optional[str]`

          The city name.

          `minLength: 0`, `maxLength: 1048576`

        - `country: Optional[str]`

          The two-letter ISO country code, such as `US`.

          `minLength: 0`, `maxLength: 1048576`

        - `region: Optional[str]`

          The region or state name.

          `minLength: 0`, `maxLength: 1048576`

        - `timezone: Optional[str]`

          The IANA timezone, such as `America/Los_Angeles`.

          `minLength: 0`, `maxLength: 1048576`

      - `mode: Optional[Literal["disabled", "cached", "live"]]`

        The source used for web search results. Defaults to `live`.

        - `"disabled"`

          Disables web search.

        - `"cached"`

          Uses cached search results.

        - `"live"`

          Searches the live web.

    - `class AgentToolConfigParamComputerUse: …`

      Browser use in an OpenAI-hosted session.

      - `type: Literal["computer_use"]`

        The type of the object. Always `computer_use`.

        - `"computer_use"`

      - `include_screenshots: Optional[bool]`

        Whether computer tool outputs include screenshots. Defaults to `false`.

    - `class AgentToolConfigParamAutomations: …`

      Lets the agent manage its own scheduled wakeups.

      - `type: Literal["automations"]`

        The type of the object. Always `automations`.

        - `"automations"`

- `metadata: Optional[Dict[str, str]]`

  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.

- `prompt_cache_options: Optional[PromptCacheOptions]`

  Default prompt cache lifetime for future turns. Send null to clear the session default.

  - `ttl: Optional[Literal["30m", "12h"]]`

    Minimum lifetime for new prompt cache entries. Defaults to 30 minutes.

    - `"30m"`

    - `"12h"`

- `review: Optional[Literal["none", "auto_review"]]`

  Default action review for new root turns. Existing turns and their subagents keep their review mode.

  - `"none"`

    Keep the existing execution behavior without automatic action review.

  - `"auto_review"`

    Review eligible actions automatically. Deny manual approval fallbacks.

- `spend_control: Optional[SpendControl]`

  Omit to retain the limit; null or a null limit removes it without resetting spend.

  - `limit: Optional[int]`

    Positive USD cents, or null to remove the limit.

    `format: int64`, `minimum: 1`, `maximum: 4503599627370495`

### Returns

- `class AgentSession: …`

  A Managed Agents session.

  - `id: str`

    The ID of the session.

    `minLength: 0`

  - `agent: Agent`

    The agent running in the session.

    - `id: str`

      The ID of the agent.

      `minLength: 0`

    - `instructions: Optional[str]`

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

      `minLength: 0`

    - `model: str`

      The model used by the agent.

      `minLength: 0`

    - `multi_agent: MultiAgentConfig`

      Configuration for creating and coordinating subagents.

      - `enabled: bool`

        Whether subagent tools are enabled. Defaults to false.

      - `max_concurrent_subagents: Optional[int]`

        Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.

        `format: int64`, `minimum: 1`, `maximum: 4294967295`

    - `name: Optional[str]`

      The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value.

      `minLength: 0`

    - `reasoning: AgentReasoning`

      The agent's reasoning configuration.

      - `effort: Optional[Literal["none", "minimal", "low", 4 more]]`

        The requested reasoning effort, or `null` when the model selects its own default.

        - `"none"`

        - `"minimal"`

        - `"low"`

        - `"medium"`

        - `"high"`

        - `"xhigh"`

        - `"max"`

      - `summary: Optional[Literal["concise", "detailed", "auto"]]`

        The requested reasoning summary format, or `null` when summaries are disabled.

        - `"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: Literal["auto", "default", "flex", 3 more]`

      The effective service-tier policy for model requests. Defaults to `auto`.

      - `"auto"`

      - `"default"`

      - `"flex"`

      - `"priority"`

      - `"fast"`

      - `"ultrafast"`

    - `text: AgentText`

      Configuration for text generated by the agent.

      - `format: TextFormat`

        The effective output format. Defaults to ordinary text.

        - `class TextFormatResourceText: …`

          Generates ordinary text without a structured-output constraint.

          - `type: Literal["text"]`

            The type of the object. Always `text`.

            - `"text"`

        - `class TextFormatResourceJSONSchema: …`

          Constrains generated text to a JSON Schema.

          - `schema: Dict[str, object]`

            The JSON Schema that generated text must match.

          - `type: Literal["json_schema"]`

            The type of the object. Always `json_schema`.

            - `"json_schema"`

      - `verbosity: Literal["low", "medium", "high"]`

        The amount of text produced by the agent. Defaults to `medium`.

        - `"low"`

        - `"medium"`

        - `"high"`

    - `tools: List[AgentTool]`

      Tools available to the agent.

      `minItems: 0`, `maxItems: 2000`

      - `class AgentToolResourceFunction: …`

        A function defined by the application.

        - `defer_loading: bool`

          Whether the function is deferred and discovered through tool search.

        - `description: str`

          A description of what the function does.

          `minLength: 0`

        - `name: str`

          The name of the function.

          `minLength: 0`

        - `parameters: Dict[str, object]`

          A JSON Schema object describing the function's arguments.

        - `type: Literal["function"]`

          The type of the object. Always `function`.

          - `"function"`

        - `async_: Optional[bool]`

          Whether the agent continues without waiting for the function result.

      - `class AgentToolResourceProgrammaticToolCalling: …`

        Enables calling tools from model-generated code.

        - `enabled: bool`

          Whether tools can be called from model-generated code.

        - `type: Literal["programmatic_tool_calling"]`

          The type of the object. Always `programmatic_tool_calling`.

          - `"programmatic_tool_calling"`

      - `class AgentToolResourceMcp: …`

        Tools provided by a remote MCP server.

        - `allowed_tools: Optional[List[str]]`

          The MCP tools the agent may call.

          `minItems: 0`, `maxItems: 2000`

        - `connection_origin: Literal["service", "environment"]`

          Where outbound MCP HTTP connections originate.

          - `"service"`

          - `"environment"`

        - `credential_id: Optional[str]`

          The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL.

          `minLength: 0`

        - `request_metadata: Dict[str, object]`

          Metadata included with requests to this MCP server.

        - `required: bool`

          Whether this MCP server must initialize before the first turn.

        - `server_label: str`

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

          `minLength: 0`

        - `transport: McpTransport`

          The transport used to connect to the MCP server.

          - `class McpTransportResourceHTTP: …`

            Connects to an MCP server over HTTP.

            - `server_url: str`

              The URL of the MCP server.

              `minLength: 0`

            - `type: Literal["http"]`

              The type of the object. Always `http`.

              - `"http"`

          - `class McpTransportResourceStdio: …`

            Starts an MCP server as a local process.

            - `args: List[str]`

              Arguments passed to the MCP server command.

              `minItems: 0`, `maxItems: 2000`

            - `command: str`

              The command used to start the MCP server.

              `minLength: 0`

            - `cwd: str`

              The working directory used to start the MCP server.

              `minLength: 0`

            - `env_vars: List[str]`

              Environment variable names inherited from the execution environment.

              `minItems: 0`, `maxItems: 2000`

            - `type: Literal["stdio"]`

              The type of the object. Always `stdio`.

              - `"stdio"`

        - `type: Literal["mcp"]`

          The type of the object. Always `mcp`.

          - `"mcp"`

      - `class AgentToolResourceWebSearch: …`

        Web search.

        - `allowed_domains: Optional[List[str]]`

          Allowed search domains, or `null` when the search is unrestricted.

          `minItems: 0`, `maxItems: 2000`

        - `context_size: Literal["low", "medium", "high"]`

          The amount of search context made available to the model. Defaults to `medium`.

          - `"low"`

          - `"medium"`

          - `"high"`

        - `location: Optional[AgentToolResourceWebSearchLocation]`

          Approximate location used to localize search results, if provided.

          - `city: Optional[str]`

            The city name.

            `minLength: 0`

          - `country: Optional[str]`

            The two-letter ISO country code, such as `US`.

            `minLength: 0`

          - `region: Optional[str]`

            The region or state name.

            `minLength: 0`

          - `timezone: Optional[str]`

            The IANA timezone, such as `America/Los_Angeles`.

            `minLength: 0`

        - `mode: Literal["disabled", "cached", "live"]`

          The source used for web search results.

          - `"disabled"`

          - `"cached"`

          - `"live"`

        - `type: Literal["web_search"]`

          The type of the object. Always `web_search`.

          - `"web_search"`

      - `class AgentToolResourceComputerUse: …`

        Browser use in an OpenAI-hosted session.

        - `include_screenshots: bool`

          Whether computer tool outputs include screenshots.

        - `type: Literal["computer_use"]`

          The type of the object. Always `computer_use`.

          - `"computer_use"`

      - `class AgentToolResourceAutomations: …`

        Lets the agent manage its own scheduled wakeups.

        - `type: Literal["automations"]`

          The type of the object. Always `automations`.

          - `"automations"`

    - `compaction: Optional[AgentCompaction]`

      The effective context compaction settings.

      - `async_: bool`

        Whether context is compacted in the background. Defaults to true.

    - `experimental: Optional[AgentExperimental]`

      The effective experimental settings for the agent.

      - `time_awareness: bool`

        Whether the model receives periodic current-time reminders.

  - `created_at: int`

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

    `format: int64`

  - `environment: Environment`

    The execution environment for the session.

    - `class EnvironmentResourceNone: …`

      The session talks to CCA without selecting or provisioning an execution environment.

      - `type: Literal["none"]`

        The type of the object. Always `none`.

        - `"none"`

    - `class EnvironmentResourceOpenAIHosted: …`

      An environment hosted by OpenAI.

      - `id: str`

        The public ID of the environment.

        `minLength: 0`

      - `capability_directories: List[str]`

        Directories that contain capabilities exposed to the agent.

        `minItems: 0`, `maxItems: 2000`

      - `files: List[HostedEnvironmentFile]`

        Files available in the environment, excluding their contents.

        `minItems: 0`, `maxItems: 50`

        - `class HostedEnvironmentFileID: …`

          A file copied from the OpenAI Files API.

          - `id: str`

            The session-scoped ID of the file in the execution environment.

            `minLength: 0`

          - `file_id: str`

            The ID of the uploaded file.

            `minLength: 0`

          - `path: str`

            The file's absolute path inside the environment.

            `minLength: 0`

          - `size_bytes: int`

            The decoded file size in bytes.

            `format: int64`, `minimum: 0`

          - `type: Literal["file_id"]`

            The type of the object. Always `file_id`.

            - `"file_id"`

        - `class HostedEnvironmentFileResourceInline: …`

          A file supplied inline when the session was created.

          - `id: str`

            The session-scoped ID of the file in the execution environment.

            `minLength: 0`

          - `path: str`

            The file's absolute path inside the environment.

            `minLength: 0`

          - `size_bytes: int`

            The decoded file size in bytes.

            `format: int64`, `minimum: 0`

          - `type: Literal["inline"]`

            The type of the object. Always `inline`.

            - `"inline"`

      - `network: EnvironmentResourceOpenAIHostedNetwork`

        The effective network access policy for the environment.

        - `access: Literal["enabled", "disabled", "restricted"]`

          The environment's network access mode.

          - `"enabled"`

            Allows unrestricted network access.

          - `"disabled"`

            Disables network access.

          - `"restricted"`

            Applies the configured domain restrictions.

        - `allowed_domains: List[str]`

          Domains the environment may access when network access is restricted.

          `minItems: 0`, `maxItems: 2000`

      - `packages: EnvironmentResourceOpenAIHostedPackages`

        Packages installed in the environment.

        - `npm: List[str]`

          npm packages installed globally in the environment.

          `minItems: 0`, `maxItems: 16384`

        - `python: List[str]`

          Python packages installed in the environment.

          `minItems: 0`, `maxItems: 16384`

        - `system: List[str]`

          System packages installed in the environment.

          `minItems: 0`, `maxItems: 16384`

      - `plugins: List[HostedPlugin]`

        Plugins installed in the environment, excluding their archive contents.

        `minItems: 0`, `maxItems: 2000`

        - `description: str`

          The installed plugin description.

          `minLength: 0`

        - `name: str`

          The installed plugin name.

          `minLength: 0`

        - `type: Literal["inline"]`

          The type of the object. Always `inline`.

          - `"inline"`

      - `skills: List[HostedSkill]`

        Skills installed in the environment, excluding their archive contents.

        `minItems: 0`, `maxItems: 2000`

        - `class HostedSkillReference: …`

          A skill installed from the Skills API.

          - `description: str`

            The installed skill description.

            `minLength: 0`

          - `name: str`

            The installed skill name.

            `minLength: 0`

          - `skill_id: str`

            The referenced skill ID.

            `minLength: 0`

          - `type: Literal["skill_reference"]`

            The type of the object. Always `skill_reference`.

            - `"skill_reference"`

          - `version: str`

            The concrete skill version installed for this session.

            `minLength: 0`

        - `class HostedSkillResourceInline: …`

          A skill installed from an inline ZIP archive.

          - `description: str`

            The installed skill description.

            `minLength: 0`

          - `name: str`

            The installed skill name.

            `minLength: 0`

          - `type: Literal["inline"]`

            The type of the object. Always `inline`.

            - `"inline"`

      - `type: Literal["openai_hosted"]`

        The type of the object. Always `openai_hosted`.

        - `"openai_hosted"`

      - `container_size: Optional[Literal["small", "medium", "large"]]`

        The effective CPU and memory tier, or null when unknown or outside the public tiers.

        - `"small"`

        - `"medium"`

        - `"large"`

      - `desktop: Optional[EnvironmentResourceOpenAIHostedDesktop]`

        The effective desktop configuration.

        - `enabled: bool`

          Whether the environment provisions a desktop and browser proxy.

    - `class EnvironmentResourceSelfHosted: …`

      An environment hosted by the application.

      - `id: str`

        The public ID of the environment.

        `minLength: 0`

      - `capability_directories: List[str]`

        Directories that contain capabilities exposed to the agent.

        `minItems: 0`, `maxItems: 2000`

      - `remote_url: str`

        Pass this URL unchanged to `codex exec-server --remote` when connecting this environment.

        `minLength: 0`

      - `type: Literal["self_hosted"]`

        The type of the object. Always `self_hosted`.

        - `"self_hosted"`

      - `workspace_directory: str`

        The absolute project directory inside the environment. Defaults to `/workspace`.

        `minLength: 0`

  - `error: Optional[str]`

    The error that caused the session to fail, if any.

    `minLength: 0`

  - `last_active_at: int`

    The Unix timestamp, in seconds, when the session was last active.

    `format: int64`

  - `metadata: Dict[str, str]`

    Custom string key-value pairs attached to the session.

  - `object: Literal["agent.session"]`

    The object type. Always `agent.session`.

    - `"agent.session"`

  - `required_actions: List[RequiredAction]`

    Actions that must be completed before the session can continue.

    `minItems: 0`, `maxItems: 2000`

    - `class RequiredActionSessionRequiredActionResourceComputerUseApprovalRequest: …`

      Respond to a computer-use request.

      - `request: RequiredActionSessionRequiredActionResourceComputerUseApprovalRequestRequest`

        The information needed to render the request.

        - `class RequiredActionSessionRequiredActionResourceComputerUseApprovalRequestRequestComputerUseApprovalRequestKindResourceBrowserAuthentication: …`

          A registered form awaiting the application's response.

          - `credential_origin: Optional[str]`

            The registered form or frame origin where values will be entered.

            `minLength: 0`

          - `fields: List[RequiredActionSessionRequiredActionResourceComputerUseApprovalRequestRequestComputerUseApprovalRequestKindResourceBrowserAuthenticationField]`

            Controls to render. All submitted values are sensitive.

            `minItems: 0`, `maxItems: 2000`

            - `id: str`

              The field ID to submit as field_id in a fields entry.

              `minLength: 0`

            - `label: str`

              The label to display beside the control.

              `minLength: 0`

            - `required: bool`

              Whether this control requires a nonempty value.

            - `type: str`

              The rendering type, such as email, password, or text.

              `minLength: 0`

          - `options: List[RequiredActionSessionRequiredActionResourceComputerUseApprovalRequestRequestComputerUseApprovalRequestKindResourceBrowserAuthenticationOption]`

            Sign-in methods. Empty for a plain form.

            `minItems: 0`, `maxItems: 2000`

            - `id: str`

              The option ID to submit as selected_option.

              `minLength: 0`

            - `field_ids: List[str]`

              IDs from the registered fields that this method accepts.

              `minItems: 0`, `maxItems: 2000`

            - `label: str`

              The method label to display.

              `minLength: 0`

          - `reason: Optional[str]`

            Why the agent needs the user to sign in.

            `minLength: 0`

          - `type: Literal["browser_authentication"]`

            The type of the object. Always `browser_authentication`.

            - `"browser_authentication"`

        - `class RequiredActionSessionRequiredActionResourceComputerUseApprovalRequestRequestComputerUseApprovalRequestKindResourceBrowserOriginAccess: …`

          A browser origin awaiting the application's approval decision.

          - `origin: str`

            The origin the browser needs permission to access.

            `minLength: 0`

          - `reason: Optional[str]`

            The browser's explanation for this request, or null when unavailable.

            `minLength: 0`

          - `type: Literal["browser_origin_access"]`

            The type of the object. Always `browser_origin_access`.

            - `"browser_origin_access"`

      - `request_id: str`

        The registered request ID to echo when responding.

        `minLength: 0`

      - `turn_id: str`

        The turn that requested approval.

        `minLength: 0`

      - `type: Literal["computer_use_approval_request"]`

        The type of the object. Always `computer_use_approval_request`.

        - `"computer_use_approval_request"`

    - `class RequiredActionSessionRequiredActionResourceFunctionCall: …`

      Run a function tool and submit its result.

      - `arguments: object`

        The arguments supplied by the model.

      - `call_id: str`

        The ID to include when submitting the function result.

        `minLength: 0`

      - `name: str`

        The function name.

        `minLength: 0`

      - `turn_id: str`

        The ID of the turn that requested the function call.

        `minLength: 0`

      - `type: Literal["function_call"]`

        The type of the object. Always `function_call`.

        - `"function_call"`

    - `class RequiredActionSessionRequiredActionResourceEnvironmentConnection: …`

      Reconnect a session environment.

      - `environment_id: str`

        The ID of the environment to reconnect.

        `minLength: 0`

      - `type: Literal["environment_connection"]`

        The type of the object. Always `environment_connection`.

        - `"environment_connection"`

  - `status: Literal["idle", "in_progress", "requires_action", "failed"]`

    The current status of the session.

    - `"idle"`

      The session has no turn in progress and is ready for input. A hosted environment may still be provisioning.

    - `"in_progress"`

      The session is processing a turn.

    - `"requires_action"`

      The session is waiting for one or more required actions.

    - `"failed"`

      The session failed.

  - `usage: Optional[TokenUsage]`

    Best-effort token usage for the session, or null if unknown. Recorded usage may change.

    - `input_tokens: int`

      The number of input tokens used by the agent.

      `format: int64`

    - `input_tokens_details: InputTokensDetails`

      A breakdown of the agent's input token usage.

      - `cached_tokens: int`

        The number of input tokens retrieved from the prompt cache.

        `format: int64`

    - `output_tokens: int`

      The number of output tokens generated by the agent.

      `format: int64`

    - `output_tokens_details: OutputTokensDetails`

      A breakdown of the agent's output token usage.

      - `reasoning_tokens: int`

        The number of output tokens used for reasoning.

        `format: int64`

    - `total_tokens: int`

      The total number of input and output tokens used by the agent.

      `format: int64`

  - `vault_ids: List[str]`

    The IDs of vaults made available to the session.

    `minItems: 0`, `maxItems: 2000`

  - `prompt_cache_options: Optional[PromptCacheOptions]`

    Default prompt cache lifetime for turns in this session, when configured.

    - `ttl: Literal["30m", "12h"]`

      - `"30m"`

      - `"12h"`

  - `review: Optional[Literal["none", "auto_review"]]`

    Review applied to eligible actions in this session. Omitted when review is none and automatic review is not enabled. Omission means none.

    - `"none"`

    - `"auto_review"`

  - `spend_control: Optional[SpendControl]`

    Configured spending limit and best-effort consumption, in USD cents. Unlimited sessions omit this object.

    - `consumed: Optional[int]`

      Best-effort recorded spend floored to whole USD cents, or null when unavailable.

      `minimum: 0`

    - `limit: int`

      The configured positive limit in USD cents.

      `format: int64`, `minimum: 1`, `maximum: 4503599627370495`

### Example

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
agent_session = client.beta.agents.sessions.update(
    session_id="session_id",
)
print(agent_session.id)
```

#### 200 — Example

```json
{
  "id": "id",
  "agent": {
    "id": "id",
    "instructions": "instructions",
    "model": "model",
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 1
    },
    "name": "name",
    "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",
        "async": true
      }
    ],
    "compaction": {
      "async": true
    },
    "experimental": {
      "time_awareness": true
    }
  },
  "created_at": 0,
  "environment": {
    "type": "none"
  },
  "error": "error",
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "object": "agent.session",
  "required_actions": [
    {
      "request": {
        "credential_origin": "credential_origin",
        "fields": [
          {
            "id": "id",
            "label": "label",
            "required": true,
            "type": "type"
          }
        ],
        "options": [
          {
            "id": "id",
            "field_ids": [
              "string"
            ],
            "label": "label"
          }
        ],
        "reason": "reason",
        "type": "browser_authentication"
      },
      "request_id": "request_id",
      "turn_id": "turn_id",
      "type": "computer_use_approval_request"
    }
  ],
  "status": "idle",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "vault_ids": [
    "string"
  ],
  "prompt_cache_options": {
    "ttl": "30m"
  },
  "review": "none",
  "spend_control": {
    "consumed": 0,
    "limit": 1
  }
}
```
