Sample - OpenAI API
POST/agents/sessions

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.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

7 body fields
metadataobjectoptional
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.
agentobjectoptional
Agent configuration. With `agent_id`, supplied fields override the saved agent for this session. Without `agent_id`, `model` is required.
agent_idstringoptional
The ID of a saved reusable agent. Omit `agent` to use its configuration unchanged.
environmentobjectrequired
An inline execution environment or a reference to an environment template.
vault_idsarrayoptional
The IDs of vaults made available to the session.
inputstring | arrayoptional
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.
streambooleanoptional
Whether to stream session events as server-sent events. Defaults to `false`.
Default:false

8 status codes
201The created session or its event stream.
metadataobjectrequired
Custom string key-value pairs attached to the session.
idstringrequired
The ID of the session.
objectstringrequired
The object type. Always `agent.session`.
Allowed:agent.sessionDefault:agent.session
created_atintegerrequired
The Unix timestamp, in seconds, when the session was created.
last_active_atintegerrequired
The Unix timestamp, in seconds, when the session was last active.
statusstringrequired
The current status of the session.
Allowed:idlein_progressrequires_actionfailed
required_actionsarray<object>required
Actions that must be completed before the session can continue.
errorstringrequired
The error that caused the session to fail, if any.
agentobjectrequired
The agent running in the session.
environmentobjectrequired
The execution environment for the session.
vault_idsarray<string>required
The IDs of vaults made available to the session.
usageobjectrequired
Best-effort token usage for the session, or null if unknown. Recorded usage may change.
400The request was invalid.
errorobjectrequired
The error returned by the API.
401Authentication or project context was missing.
errorobjectrequired
The error returned by the API.
403The API key lacks the required Responses permission.
errorobjectrequired
The error returned by the API.
404The requested session or event was not found.
errorobjectrequired
The error returned by the API.
409The request conflicted with the current session state.
errorobjectrequired
The error returned by the API.
500An internal error occurred.
errorobjectrequired
The error returned by the API.
503The service is temporarily unavailable.
errorobjectrequired
The error returned by the API.

Error handling

A 400 is returned: The request was invalid. A 401 is returned: Authentication or project context was missing. A 403 is returned: The API key lacks the required Responses permission. A 404 is returned: The requested session or event was not found. A 409 is returned: The request conflicted with the current session state. A 500 is returned: An internal error occurred. A 503 is returned: The service is temporarily unavailable.