Skip to main content
Create a session bound to an agent. Provide either agent_id or agent (id or name). Post events to the session to run turns.

Endpoint

Authentication

Authorization: Bearer <api_key> or Authorization: ApiKey <key>. Optional if AGENT_CLOUD_API_KEY is unset.

Request body

string
Agent id (preferred). One of agent_id or agent is required.
string
Agent id or human-friendly name (fallback when agent_id is omitted).
string
Session-level instructions appended to the agent’s instructions.

Response

string
Session id (sess_<hex>).
string
Always agent.session.
object
Snapshot of the bound agent (id, optional name / instructions / model, plus reasoning, multi_agent, service_tier).
string
Session-level instructions, if set.
string
Starts as idle.
integer
Epoch milliseconds.

Example