## Retrieve an agent session `beta.agents.sessions.retrieve(strsession_id) -> AgentSession` **get** `/agents/sessions/{session_id}` Retrieves the current state of a managed agent session. See [managing sessions](/api/docs/guides/agents-api/sessions/manage). ### Parameters - `session_id: str` ### Returns - `class AgentSession: …` A Managed Agents session. - `id: str` The ID of the session. - `agent: Agent` The agent running in the session. - `id: str` The ID of the agent. - `instructions: Optional[str]` Custom instructions appended to the agent's default base instructions. - `model: str` The model used by the agent. - `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. - `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. - `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. - `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. - `name: str` The name of the function. - `parameters: Dict[str, object]` A JSON Schema object describing the function's arguments. - `type: Literal["function"]` The type of the object. Always `function`. - `"function"` - `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. - `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. - `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. - `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. - `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. - `command: str` The command used to start the MCP server. - `cwd: str` The working directory used to start the MCP server. - `env_vars: List[str]` Environment variable names inherited from the execution environment. - `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. - `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. - `country: Optional[str]` The two-letter ISO country code, such as `US`. - `region: Optional[str]` The region or state name. - `timezone: Optional[str]` The IANA timezone, such as `America/Los_Angeles`. - `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"` - `created_at: int` The Unix timestamp, in seconds, when the session was created. - `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. - `capability_directories: List[str]` Directories that contain capabilities exposed to the agent. - `files: List[HostedEnvironmentFile]` Files available in the environment, excluding their contents. - `class HostedEnvironmentFileID: …` A file copied from the OpenAI Files API. - `id: str` The session-scoped ID of the file in the execution environment. - `file_id: str` The ID of the uploaded file. - `path: str` The file's absolute path inside the environment. - `size_bytes: int` The decoded file size in bytes. - `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. - `path: str` The file's absolute path inside the environment. - `size_bytes: int` The decoded file size in bytes. - `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. - `packages: EnvironmentResourceOpenAIHostedPackages` Packages installed in the environment. - `npm: List[str]` npm packages installed globally in the environment. - `python: List[str]` Python packages installed in the environment. - `system: List[str]` System packages installed in the environment. - `plugins: List[HostedPlugin]` Plugins installed in the environment, excluding their archive contents. - `description: str` The installed plugin description. - `name: str` The installed plugin name. - `type: Literal["inline"]` The type of the object. Always `inline`. - `"inline"` - `skills: List[HostedSkill]` Skills installed in the environment, excluding their archive contents. - `class HostedSkillReference: …` A skill installed from the Skills API. - `description: str` The installed skill description. - `name: str` The installed skill name. - `skill_id: str` The referenced skill ID. - `type: Literal["skill_reference"]` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: str` The concrete skill version installed for this session. - `class HostedSkillResourceInline: …` A skill installed from an inline ZIP archive. - `description: str` The installed skill description. - `name: str` The installed skill name. - `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. - `capability_directories: List[str]` Directories that contain capabilities exposed to the agent. - `remote_url: str` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `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`. - `error: Optional[str]` The error that caused the session to fail, if any. - `last_active_at: int` The Unix timestamp, in seconds, when the session was last active. - `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. - `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. - `fields: List[RequiredActionSessionRequiredActionResourceComputerUseApprovalRequestRequestComputerUseApprovalRequestKindResourceBrowserAuthenticationField]` Controls to render. All submitted values are sensitive. - `id: str` The field ID to submit as field_id in a fields entry. - `label: str` The label to display beside the control. - `required: bool` Whether this control requires a nonempty value. - `type: str` The rendering type, such as email, password, or text. - `options: List[RequiredActionSessionRequiredActionResourceComputerUseApprovalRequestRequestComputerUseApprovalRequestKindResourceBrowserAuthenticationOption]` Sign-in methods. Empty for a plain form. - `id: str` The option ID to submit as selected_option. - `field_ids: List[str]` IDs from the registered fields that this method accepts. - `label: str` The method label to display. - `reason: Optional[str]` Why the agent needs the user to sign in. - `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. - `reason: Optional[str]` The browser's explanation for this request, or null when unavailable. - `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. - `turn_id: str` The turn that requested approval. - `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. - `name: str` The function name. - `turn_id: str` The ID of the turn that requested the function call. - `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. - `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. - `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. - `output_tokens: int` The number of output tokens generated by the agent. - `output_tokens_details: OutputTokensDetails` A breakdown of the agent's output token usage. - `reasoning_tokens: int` The number of output tokens used for reasoning. - `total_tokens: int` The total number of input and output tokens used by the agent. - `vault_ids: List[str]` The IDs of vaults made available to the session. - `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. - `limit: int` The configured positive limit in USD cents. ### 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.retrieve( "session_id", ) print(agent_session.id) ``` #### Response ```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" } ] }, "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" ], "spend_control": { "consumed": 0, "limit": 1 } } ```