Create an agent session
Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See running sessions.
Body ParametersJSONExpand Collapse
An inline execution environment or a reference to an environment template.
An inline execution environment or a reference to an environment template.
OpenAIHosted object { type, capability_directories, container_size, 10 more } An existing OpenAI-hosted environment or new inline/template-based hosted configuration.
An existing OpenAI-hosted environment or new inline/template-based hosted configuration.
Directories that contain capabilities exposed to the agent. Defaults to an empty list.
container_size: optional "small" or "medium" or "large"The hosted container size. Omission selects the medium tier.
The hosted container size. Omission selects the medium tier.
desktop: optional object { enabled } or nullDesktop provisioning. Omission or null inherits the template setting, or defaults to disabled.
Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled.
An existing prewarmed environment. Cannot be combined with a template or inline configuration.
A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy.
Files available before the agent starts. Defaults to an empty list.
Files available before the agent starts. Defaults to an empty list.
network: optional object { access, allowed_domains, blocked_domains } or nullNetwork access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled.
Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled.
packages: optional object { npm, python, system } or nullPackages to install in the environment. Defaults to empty package lists.
Packages to install in the environment. Defaults to empty package lists.
Plugins provided as inline ZIP archives. Defaults to an empty list.
Plugins provided as inline ZIP archives. Defaults to an empty list.
Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list.
Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list.
agent: optional object { instructions, model, multi_agent, 4 more } Agent configuration. With agent_id, supplied fields override the saved agent for this session. Without agent_id, model is required.
Agent configuration. With agent_id, supplied fields override the saved agent for this session. Without agent_id, model is required.
Additional instructions appended to the agent’s default base instructions. Omit to leave unchanged.
The model to use for the agent. The requested model name is preserved.
Configuration for model reasoning. Omit to keep the current settings; pass null to reset to the model’s default effort.
Configuration for model reasoning. Omit to keep the current settings; pass null to reset to the model’s default effort.
service_tier: optional "auto" or "default" or "flex" or 2 more or nullThe service tier used for model requests.
The service tier used for model requests.
Configuration for text generated by the agent.
Configuration for text generated by the agent.
Tools available to the agent. Omit to inherit, or pass null to clear them. The resolved tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
Tools available to the agent. Omit to inherit, or pass null to clear them. The resolved tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
Mcp object { server_label, transport, type, 5 more } Tools provided by a remote MCP server.
Tools provided by a remote MCP server.
A label used to identify the MCP server in tool calls.
The transport used to connect to the MCP server.
The transport used to connect to the MCP server.
The MCP tools the agent may call. All server tools are allowed when omitted.
connection_origin: optional "service" or "environment" or nullSelects where outbound MCP HTTP connections originate. Omitted or service uses the Managed Agents service network; environment uses the session’s selected environment.
Selects where outbound MCP HTTP connections originate. Omitted or service uses the Managed Agents service network; environment uses the session’s selected environment.
WebSearch object { type, allowed_domains, context_size, 2 more } Web search.
Web search.
context_size: optional "low" or "medium" or "high" or nullThe amount of search context made available to the model. Defaults to medium.
The amount of search context made available to the model. Defaults to medium.
The ID of a saved reusable agent. Omit agent to use its configuration unchanged.
Initial input to submit when the session is created. A string is shorthand for a single user message. Required when environment.type is none, or when stream is true for an environment that is not self_hosted; optional for self-hosted and non-streaming execution environments.
Initial input to submit when the session is created. A string is shorthand for a single user message. Required when environment.type is none, or when stream is true for an environment that is not self_hosted; optional for self-hosted and non-streaming execution environments.
array of AgentSessionInputMessageParam { content, role, type }
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.
ReturnsExpand Collapse
AgentSession object { id, agent, created_at, 10 more } A Managed Agents session.
A Managed Agents session.
agent: object { id, instructions, model, 6 more } The agent running in the session.
The agent running in the session.
Custom instructions appended to the agent’s default base instructions.
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.
The agent’s reasoning configuration.
The agent’s reasoning configuration.
service_tier: "auto" or "default" or "flex" or 3 moreThe effective service-tier policy for model requests. Defaults to auto.
The effective service-tier policy for model requests. Defaults to auto.
Configuration for text generated by the agent.
Configuration for text generated by the agent.
Tools available to the agent.
Tools available to the agent.
Mcp object { allowed_tools, connection_origin, credential_id, 5 more } Tools provided by a remote MCP server.
Tools provided by a remote MCP server.
The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL.
WebSearch object { allowed_domains, context_size, location, 2 more } Web search.
Web search.
Allowed search domains, or null when the search is unrestricted.
context_size: "low" or "medium" or "high"The amount of search context made available to the model. Defaults to medium.
The amount of search context made available to the model. Defaults to medium.
location: object { city, country, region, timezone } or nullApproximate location used to localize search results, if provided.
Approximate location used to localize search results, if provided.
The execution environment for the session.
The execution environment for the session.
None object { type } The session talks to CCA without selecting or provisioning an execution environment.
The session talks to CCA without selecting or provisioning an execution environment.
OpenAIHosted object { id, capability_directories, desktop, 7 more } An environment hosted by OpenAI.
An environment hosted by OpenAI.
Files available in the environment, excluding their contents.
Files available in the environment, excluding their contents.
network: object { access, allowed_domains } The effective network access policy for the environment.
The effective network access policy for the environment.
required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type } Actions that must be completed before the session can continue.
Actions that must be completed before the session can continue.
ComputerUseApprovalRequest object { request, request_id, turn_id, type } Respond to a computer-use request.
Respond to a computer-use request.
request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type } The information needed to render the request.
The information needed to render the request.
BrowserAuthentication object { credential_origin, fields, options, 2 more } A registered form awaiting the application’s response.
A registered form awaiting the application’s response.
The registered form or frame origin where values will be entered.
fields: array of object { id, label, required, type } Controls to render. All submitted values are sensitive.
Controls to render. All submitted values are sensitive.
Best-effort token usage for the session, or null if unknown. Recorded usage may change.
Best-effort token usage for the session, or null if unknown. Recorded usage may change.
Create an agent session
curl https://api.openai.com/v1/agents/sessions \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"environment": {
"type": "none"
}
}'{
"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
}
}Returns Examples
{
"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
}
}