--- title: "Create an agent session" method: POST path: "/agents/sessions" tags: ["Agents"] --- # Create an agent session `POST /agents/sessions` Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See [running sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions). ## Request body - CreateAgentSessionParams — Parameters for creating a Managed Agents session. - `metadata` object, nullable — Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map. - `agent` SessionAgentConfigParam — Agent configuration for a session. Omitted fields inherit from `agent_id` when supplied. Supplied objects and arrays replace the whole field; null resets nullable fields. - `model` string — The model to use for the agent. The requested model name is preserved. - `reasoning` ReasoningParam — Reasoning configuration for the agent. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' — The amount of reasoning effort the model should use. - `summary` 'concise' | 'detailed' | 'auto' — The reasoning summary format requested from the model. - `text` TextParam — Configuration for text generated by the agent. - `format` union — The output format for generated text. - object — Generates ordinary text without a structured-output constraint. - `type` 'text', required — The type of the object. Always `text`. - object — Constrains generated text to a JSON Schema. - `type` 'json_schema', required — The type of the object. Always `json_schema`. - `schema` object, required — The JSON Schema that generated text must match. - `verbosity` 'low' | 'medium' | 'high' — The amount of text the model should produce. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast' — The service tier used for model requests. - `instructions` string, nullable — Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - `multi_agent` MultiAgentConfigCurrentParam — Explicit configuration for creating and coordinating subagents. - `enabled` boolean, required — Whether subagent tools are enabled. - `max_concurrent_subagents` integer — Maximum number of subagents that may run concurrently. Defaults to 6. - `tools` AgentToolConfigParam[], nullable — Tools available to the agent. Omit to inherit, or pass null to clear them. - union — A tool available to the agent. - object — A function defined by the application. - `type` 'function', required — The type of the object. Always `function`. - `name` string, required — The name of the function. - `description` string, required — A description of what the function does. - `parameters` object, required — A JSON Schema object describing the function's arguments. - `defer_loading` boolean — Whether this function is deferred and discovered through tool search. Defaults to `false`. - object — Discovers deferred function tools and loads them into the model context. - `type` 'tool_search', required — The type of the object. Always `tool_search`. - object — Enables calling tools from model-generated code. - `type` 'programmatic_tool_calling', required — The type of the object. Always `programmatic_tool_calling`. - `enabled` boolean — Whether tools can be called from model-generated code. Defaults to `true`. - object — Tools provided by a remote MCP server. - `type` 'mcp', required — The type of the object. Always `mcp`. - `server_label` string, required — A label used to identify the MCP server in tool calls. - `credential_id` string, nullable — The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL. - `transport` union, required — The transport used to connect to an MCP server. - object — Connects to an MCP server over HTTP. - … - object — Starts an MCP server as a local process. - … - `request_metadata` object, nullable — Metadata included with requests to this MCP server. - `allowed_tools` string[], nullable — The MCP tools the agent may call. All server tools are allowed when omitted. - `required` boolean — Whether this MCP server must initialize before the first turn. Defaults to `false`. - `connection_origin` 'service' | 'environment' — Where outbound MCP HTTP connections originate. - object — Web search. - `type` 'web_search', required — The type of the object. Always `web_search`. - `mode` 'disabled' | 'cached' | 'live' — The source used for web search results. - `context_size` 'low' | 'medium' | 'high' — The amount of web search context made available to the model. - `allowed_domains` string[], nullable — Domains the search may include. - `location` WebSearchLocationParam — Approximate user location used to localize web search results. - `country` string, nullable — The two-letter ISO country code, such as `US`. - `region` string, nullable — The region or state name. - `city` string, nullable — The city name. - `timezone` string, nullable — The IANA timezone, such as `America/Los_Angeles`. - `agent_id` string — The ID of a saved reusable agent. Omit `agent` to use its configuration unchanged. - `environment` union, required — The execution environment and optional reusable template for a session. - object — Runs the agent without an execution environment. - `type` 'none', required — The type of the object. Always `none`. - object — An OpenAI-hosted environment, optionally based on a reusable template. - `type` 'openai_hosted', required — The type of the object. Always `openai_hosted`. - `packages` EnvironmentPackagesParam — Packages to install in an OpenAI-hosted environment. - `python` string[], nullable — Python packages to install. Defaults to an empty list. - `system` string[], nullable — System packages to install. Defaults to an empty list. - `npm` string[], nullable — npm packages to install globally. Defaults to an empty list. - `setup_commands` SetupCommandParam[], nullable — Ordered, confidential setup commands. Command bodies are never returned. - `command` string, required — The shell command to execute. - `cwd` string, nullable — The absolute working directory. Defaults to `/workspace`. - `network` NetworkPolicyParam — Network access for an OpenAI-hosted environment. - `access` 'enabled' | 'disabled' | 'restricted', required — The network access mode for an OpenAI-hosted environment. - `allowed_domains` string[], nullable — Domains the environment may access when network access is restricted. - `env` object, nullable — Environment variables made available to the agent. - `capability_directories` string[], nullable — Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `skills` HostedSkillParam[], nullable — Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - union — A skill installed in an OpenAI-hosted environment. - object — References a skill uploaded through the Skills API. - `type` 'skill_reference', required — The type of the object. Always `skill_reference`. - `skill_id` string, required — The ID of the skill created through `/v1/skills`. - `version` string, nullable — The skill version, a positive integer or `latest`; omission selects the default. - object — Supplies a skill ZIP directly in the session request. - `type` 'inline', required — The type of the object. Always `inline`. - `name` string, required — The skill name declared in `SKILL.md`. - `description` string, required — The skill description declared in `SKILL.md`. - `source` InlineCapabilitySourceParam, required — Provides ZIP bytes encoded with standard base64. - … - `plugins` HostedPluginParam[], nullable — Plugins provided as inline ZIP archives. Defaults to an empty list. - `type` 'inline', required — The type of the object. Always `inline`. - `name` string, required — The plugin name declared in `.codex-plugin/plugin.json`. - `description` string, required — The plugin description declared in `.codex-plugin/plugin.json`. - `source` InlineCapabilitySourceParam, required — Provides ZIP bytes encoded with standard base64. - `type` 'base64', required — The type of the object. Always `base64`. - `media_type` 'application/zip', required — The archive media type, always `application/zip`. - `data` string, required — Standard-base64 encoded ZIP archive bytes. - `files` HostedEnvironmentFileParam[], nullable — Files available before the agent starts. Defaults to an empty list. - union — A file materialized in an OpenAI-hosted execution environment. - object — A file previously uploaded through the OpenAI Files API. - `type` 'file_id', required — The type of the object. Always `file_id`. - `file_id` string, required — The ID of the uploaded file. - `path` string, required — The absolute destination path inside `/workspace`. - object — A file supplied directly as standard-base64 data. - `type` 'inline', required — The type of the object. Always `inline`. - `data` string, required — The standard-base64-encoded file contents. - `path` string, required — The absolute destination path inside `/workspace`. - `environment_template_id` string — A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy. - object — An application-hosted environment configured inline. - `type` 'self_hosted', required — The type of the object. Always `self_hosted`. - `workspace_directory` string, required — Absolute project directory inside the self-hosted environment. - `capability_directories` string[], nullable — Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `vault_ids` string[], nullable — The IDs of vaults made available to the session. - `input` union — Initial input submitted when creating a session. - string - InputMessageParam[] - `type` 'message' — The type of the input item. Always `message`. - `role` 'user', required — The role of the message author. Always `user`. - `content` InputContentParam[], required — The content of the message. - union — Content included in an input message. - object — Text input to the model. - `type` 'input_text', required — The type of the object. Always `input_text`. - `text` string, required — The text sent to the model. - object — Image input to the model. - `type` 'input_image', required — The type of the object. Always `input_image`. - `image_url` string, required — The URL of the image sent to the model. - `stream` boolean — Whether to stream session events as server-sent events. Defaults to `false`. ## Response `201` The created session or its event stream. - SessionResource — A Managed Agents session. - `metadata` object, required — Custom string key-value pairs attached to the session. - `id` string, required — The ID of the session. - `object` 'agent.session', required — The object type. Always `agent.session`. - `created_at` integer, required — The Unix timestamp, in seconds, when the session was created. - `last_active_at` integer, required — The Unix timestamp, in seconds, when the session was last active. - `status` 'idle' | 'in_progress' | 'requires_action' | 'failed', required — The current status of a session. - `required_actions` SessionRequiredActionResource[], required — Actions that must be completed before the session can continue. - union — An action that must be completed before a session can continue. - object — Run a function tool and submit its result. - `type` 'function_call', required — The type of the object. Always `function_call`. - `turn_id` string, required — The ID of the turn that requested the function call. - `call_id` string, required — The ID to include when submitting the function result. - `name` string, required — The function name. - `arguments` unknown, required - object — Reconnect a session environment. - `type` 'environment_connection', required — The type of the object. Always `environment_connection`. - `environment_id` string, required — The ID of the environment to reconnect. - `error` string, nullable, required — The error that caused the session to fail, if any. - `agent` SessionAgentResource, required — The effective agent configuration for a session. - `id` string, required — The ID of the agent. - `name` string, nullable, required — 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. - `model` string, required — The model used by the agent. - `reasoning` ReasoningResource, required — The reasoning configuration used by an agent. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', required — The amount of reasoning effort used by an agent. - `summary` 'concise' | 'detailed' | 'auto', required — The reasoning summary format requested from an agent. - `text` TextResource, required — The text configuration used by an agent. - `format` union, required — The effective output format for generated text. - object — Generates ordinary text without a structured-output constraint. - `type` 'text', required — The type of the object. Always `text`. - object — Constrains generated text to a JSON Schema. - `type` 'json_schema', required — The type of the object. Always `json_schema`. - `schema` object, required — The JSON Schema that generated text must match. - `verbosity` 'low' | 'medium' | 'high', required — The amount of text produced by an agent. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast', required — The service-tier policy configured for an agent. - `instructions` string, nullable, required — Custom instructions appended to the agent's default base instructions. - `tools` AgentToolResource[], required — Tools available to the agent. - union — A tool available to the agent. - object — A function defined by the application. - `type` 'function', required — The type of the object. Always `function`. - `name` string, required — The name of the function. - `description` string, required — A description of what the function does. - `parameters` object, required — A JSON Schema object describing the function's arguments. - `defer_loading` boolean, required — Whether the function is deferred and discovered through tool search. - object — Enables calling tools from model-generated code. - `type` 'programmatic_tool_calling', required — The type of the object. Always `programmatic_tool_calling`. - `enabled` boolean, required — Whether tools can be called from model-generated code. - object — Tools provided by a remote MCP server. - `type` 'mcp', required — The type of the object. Always `mcp`. - `server_label` string, required — A label used to identify the MCP server in tool calls. - `credential_id` string, nullable, required — The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `transport` union, required — The transport used to connect to an MCP server. - object — Connects to an MCP server over HTTP. - … - object — Starts an MCP server as a local process. - … - `request_metadata` object, required — Metadata included with requests to this MCP server. - `allowed_tools` string[], nullable, required — The MCP tools the agent may call. - `required` boolean, required — Whether this MCP server must initialize before the first turn. - `connection_origin` 'service' | 'environment', required — Where outbound MCP HTTP connections originate. - object — Web search. - `type` 'web_search', required — The type of the object. Always `web_search`. - `mode` 'disabled' | 'cached' | 'live', required — The source used for web search results. - `context_size` 'low' | 'medium' | 'high', required — The amount of web search context made available to the model. - `allowed_domains` string[], nullable, required — Allowed search domains, or `null` when the search is unrestricted. - `location` WebSearchLocationResource, required — Approximate user location used to localize web search results. - `country` string, nullable, required — The two-letter ISO country code, such as `US`. - `region` string, nullable, required — The region or state name. - `city` string, nullable, required — The city name. - `timezone` string, nullable, required — The IANA timezone, such as `America/Los_Angeles`. - `multi_agent` MultiAgentConfigResource, required — The resolved configuration for creating and coordinating subagents. - `enabled` boolean, required — Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents` integer, nullable, required — Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `environment` union, required — The execution environment for a session. - object — The session talks to CCA without selecting or provisioning an execution environment. - `type` 'none', required — The type of the object. Always `none`. - object — An environment hosted by OpenAI. - `type` 'openai_hosted', required — The type of the object. Always `openai_hosted`. - `id` string, required — The public ID of the environment. - `packages` EnvironmentPackagesResource, required — Packages installed in an OpenAI-hosted environment. - `python` string[], required — Python packages installed in the environment. - `system` string[], required — System packages installed in the environment. - `npm` string[], required — npm packages installed globally in the environment. - `network` NetworkPolicyResource, required — Network access for an OpenAI-hosted environment. - `access` 'enabled' | 'disabled' | 'restricted', required — The network access mode for an OpenAI-hosted environment. - `allowed_domains` string[], required — Domains the environment may access when network access is restricted. - `capability_directories` string[], required — Directories that contain capabilities exposed to the agent. - `skills` HostedSkillResource[], required — Skills installed in the environment, excluding their archive contents. - union — A skill installed in an OpenAI-hosted environment. - object — A skill installed from the Skills API. - `type` 'skill_reference', required — The type of the object. Always `skill_reference`. - `skill_id` string, required — The referenced skill ID. - `version` string, required — The concrete skill version installed for this session. - `name` string, required — The installed skill name. - `description` string, required — The installed skill description. - object — A skill installed from an inline ZIP archive. - `type` 'inline', required — The type of the object. Always `inline`. - `name` string, required — The installed skill name. - `description` string, required — The installed skill description. - `plugins` HostedPluginResource[], required — Plugins installed in the environment, excluding their archive contents. - `type` 'inline', required — The type of the object. Always `inline`. - `name` string, required — The installed plugin name. - `description` string, required — The installed plugin description. - `files` HostedEnvironmentFileResource[], required — Files available in the environment, excluding their contents. - union — Metadata for a file materialized in an OpenAI-hosted execution environment. - object — A file copied from the OpenAI Files API. - `type` 'file_id', required — The type of the object. Always `file_id`. - `id` string, required — The session-scoped ID of the file in the execution environment. - `file_id` string, required — The ID of the uploaded file. - `path` string, required — The file's absolute path inside the environment. - `size_bytes` integer, required — The decoded file size in bytes. - object — A file supplied inline when the session was created. - `type` 'inline', required — The type of the object. Always `inline`. - `id` string, required — The session-scoped ID of the file in the execution environment. - `path` string, required — The file's absolute path inside the environment. - `size_bytes` integer, required — The decoded file size in bytes. - object — An environment hosted by the application. - `type` 'self_hosted', required — The type of the object. Always `self_hosted`. - `remote_url` string, required — Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `id` string, required — The public ID of the environment. - `workspace_directory` string, required — The absolute project directory inside the environment. Defaults to `/workspace`. - `capability_directories` string[], required — Directories that contain capabilities exposed to the agent. - `vault_ids` string[], required — The IDs of vaults made available to the session. - `usage` TokenUsageResource, required — Recorded token usage for a session or turn. Usage is best effort and may change. - `input_tokens` integer, required — The number of input tokens used by the agent. - `input_tokens_details` InputTokensDetailsResource, required — A breakdown of input token usage for a session or turn. - `cached_tokens` integer, required — The number of input tokens retrieved from the prompt cache. - `output_tokens` integer, required — The number of output tokens generated by the agent. - `output_tokens_details` OutputTokensDetailsResource, required — A breakdown of output token usage for a session or turn. - `reasoning_tokens` integer, required — The number of output tokens used for reasoning. - `total_tokens` integer, required — The total number of input and output tokens used by the agent. ## Other responses - `400` — The request was invalid. - `401` — Authentication or project context was missing. - `403` — The API key lacks the required permission. - `404` — The requested session or event was not found. - `409` — The request conflicted with the current session state. - `500` — An internal error occurred. - `503` — The service is temporarily unavailable. ## Changes - **2026-09-11** `8c3c08961f62` — 5 warning - added the new `credit_balance_exhausted` enum value to the `oneOf[#/components/schemas/SessionEventAgentSessionTurnCancelled]/turn/error/anyOf[#/components/schemas/SessionTurnErrorResource]/code` response property for the response status `201` - added the new `credit_balance_exhausted` enum value to the `oneOf[#/components/schemas/SessionEventAgentSessionTurnCompleted]/turn/error/anyOf[#/components/schemas/SessionTurnErrorResource]/code` response property for the response status `201` - added the new `credit_balance_exhausted` enum value to the `oneOf[#/components/schemas/SessionEventAgentSessionTurnCreated]/turn/error/anyOf[#/components/schemas/SessionTurnErrorResource]/code` response property for the response status `201` - added the new `credit_balance_exhausted` enum value to the `oneOf[#/components/schemas/SessionEventAgentSessionTurnFailed]/turn/error/anyOf[#/components/schemas/SessionTurnErrorResource]/code` response property for the response status `201` - …1 more - **2026-09-10** `f2dae1a9aced` — 1 info - endpoint added [Change history](https://skmtc.dev/openai/apis/openapi/changes/agents/sessions/post.md) --- [API](https://skmtc.dev/openai/apis/openapi.md) · [All operations](https://skmtc.dev/openai/apis/openapi/llms.txt) · [OpenAPI document](https://skmtc.dev/openai/apis/openapi/revisions/c40bf0ba89d2?raw)