Create a session, bind it to an agent and runtime environment, and submit the first input.
Endpoint
POST /agents/sessions
A non-streaming request returns 201 JSON; with stream=true, the response is 201 text/event-stream. A 201 means the session and first input were accepted, not that the turn has completed.
Request bodyenvironmentobject (required)Runtime environment, see belowagent_id string / null (conditional)Saved agent ID; up to 64 charactersagent object (conditional)Inline agent configuration, when provided with agent_id, acts as session-level overrides, and fields not overridden keep the saved values
Properties model string (conditional)Model ID; required for inline creation; can be inherited when referencing a saved agent. The create precheck allows up to 256 characters, and the model must match a model available in the current workspace. For available models, see Available models.instructions string / null (optional)System instructions, up to 1,048,576 Unicode characters; merged into the system prompt at executionname string / null (optional)Display name; removed from the execution configuration
reasoning effort string / null (optional)Reasoning effort, none, minimal, low, medium, high, xhigh, max, or ultra; returns none when unspecifiedsummary string / null (optional)Reasoning summary type, auto, concise, detailed, or none; returns auto when unspecified. The string none differs from JSON null
text format object / null (optional)Text format configuration; only type: text is accepted; unknown fields are rejected, omitted or null becomes {"type":"text"}verbosity string / null (optional)Output verbosity, only medium is accepted, omitted or null becomes mediumarray (optional)Tool list, omitted becomes an empty list, an explicit null is not accepted. Up to 32 function tools and 16 MCP servers
Properties
function type string (required)Tool type, fixed as functionname string (required)Function name, 1-64 bytes with characters A-Za-z0-9_.:-; must be unique within the agentdescription string (required)Function description, must be non-empty after trimming and no more than 1024 bytesparameters object (required)Parameter definition; must be a JSON Schema with type: object
mcp type string (required)Tool type, fixed as mcpserver_label string (required)MCP server label, 1-64 bytes and unique within the agenttransport object (required)HTTP or stdio transport configuration
Properties type string (required)Transport type, http or stdioserver_url string (conditional)MCP server URL; service accepts only Model Studio locator URLs (/api/v1/mcps/{code}/mcp); environment accepts ordinary HTTP addresses reachable from the environmentheaders object<string,string> / null (optional)Additional HTTP headersauthorization string / null (optional)Used only for the HTTP branch with connection_origin=environmentcommand string (conditional)Command to start the servercwd string (conditional)Absolute path; stdio requires an environmentargs array<string> (optional)Command argumentsarray<string> / null (optional)Allowed tool names; null means no filterconnection_origin string (optional)Connection origin, service or environment, defaults to servicerequired boolean (optional)Whether MCP initialization must succeed
web_search type string (required)Tool type, fixed as web_searchobject / null (optional)Multi-agent configuration, omitted or null disables subagents, when the object is present, enabled can be omitted and defaults to false, an explicit null is rejected
Properties max_concurrent_subagents integer (optional)Maximum concurrent subagents, an explicit value requires enabled=true and must be 1..32, an explicit null is rejected, when enabled, omitted defaults to 6, when disabled, the returned value is nullstring or array / null (conditional)First input. A string is shorthand for one user text message; an empty string is rejected
Properties role string (required)Message role, fixed as usertype string (optional)Message type, if set, only messagecontent array (required)Message content; cannot be empty
Properties type string (required)Content part type; input_text or input_imagetext string (conditional)Text content; up to 1,048,576 characters; the same item cannot also contain image_urlimage_url string (conditional)Image URL; up to 1,048,576 characters; the same item cannot also contain text; URL reachability is not guaranteedobject / null (optional)Metadata, string key-value pairs, up to 16 items; key up to 64 characters, value up to 512 characters; null values are not acceptedstream boolean (optional)Whether to return an SSE stream, when true, the create response is an SSE stream that ends after the session becomes idle or failed, omitted is false, and null is invalidvault_ids array<string> / null (optional)Vaults to attach, up to 10, omitted or null becomes [] | Request example |
Environment
| Form | Description |
|---|---|
{"type":"none"} | No sandbox; no built-in shell or file tools |
{"type":"openai_hosted"} | Create a managed environment with the inline configuration |
{"type":"openai_hosted","environment_id":"..."} | Reference an existing environment; do not add files, skills, or other configuration at the same time |
self_hosted is not supported. Creating a session that references the environment can fail before preparation completes; confirm the status is ready before using the environment.
When referencing an existing environment,
vault_ids must match the vault_ids used to create the environment. You cannot add new vaults on the session.Agent configuration
agent is used for inline creation or to override a saved agent. When agent_id is also provided, top-level replacement applies: omitted fields keep the saved values, and an explicit null follows the field's own rule. The final effective configuration runs the same precheck as an inline configuration.
Example with both fields: {"agent_id":"agent_xxx","agent":{"instructions":"Reply with OK only"},"environment":{"type":"none"},"input":"Reply with OK only"}.
agent.id is generated in the response or comes from a saved agent and cannot be specified inline. Unknown fields such as agent.metadata, compaction, and experimental are rejected. A tool of one type must not carry fields from another branch; a boolean null is not equivalent to an omitted field.
Message and content
When input is an array, each item is a user message. Unknown fields in message and content are rejected.
Unknown top-level fields are rejected. The request body limit is 16 MiB. After removing instructions, the compact JSON of agent + metadata + environment is limited to 1,310,720 bytes.
Response fieldsnull when the fields are incomplete. The status in the create response can be in_progress. HTTP 201 means the session and first input were accepted, not that the turn succeeded; use the turn's terminal state or the SSE agent.session.idle event to determine the end of the turn.id stringSession ID; reuse it for follow-up turnsobject stringSession object type, fixed as agent.sessioncreated_at integerCreation time in Unix secondslast_active_at integerLast activity time in Unix seconds; not a version number or lockstatus stringSession status: idle, in_progress, requires_action, or failedagent objectEffective agent snapshot.
Properties id stringAgent ID; inline configurations return a session snapshot ID, not a reusable saved agent, and it cannot be retrieved through Agent GETmodel stringModel IDinstructions string / nullCustom instructionsname string / nullDisplay namereasoning object / nullReasoning configuration, contains effort and summarytext object / nullText output configuration; contains format and verbositytools arrayTool configurationmulti_agent object / nullSubagent configuration; contains enabled and max_concurrent_subagentsobjectSafe environment summary; only type for none.
Properties type stringEnvironment type; none or openai_hostedid stringEnvironment ID, omitted when there is no authoritative valuestatus stringEnvironment status: omitted when there is no authoritative valueenvironment_template_id stringEnvironment template ID, omitted when there is no authoritative valueworkspace_directory stringWorkspace directory, omitted when there is no authoritative valueerror string / nullEnvironment error description, omitted when there is no authoritative valuedesktop object / nullDesktop settings; contains enabledcapability_directories array<string> / nullCapability discovery directoriesnetwork object / nullNetwork policy; contains access and allowed_domainspackages object / nullPackage lists; contains npm, python, and systemfiles arraySafe environment file metadataskills arraySafe skill metadataplugins arrayPlugin information; [] for managed environmentsobjectSession metadata; an empty value is {}vault_ids array<string>Vault IDs recorded at creationrequired_actions arrayFunction calls that need client handling; [] when empty.
Properties type stringItem type, fixed as function_callturn_id stringPublic turn IDcall_id stringFunction call IDname stringFunction namearguments objectParsed call argumentsstring / nullSession-level error message, different from a turn's structured errorusage object / nullToken usage.
Properties input_tokens integerNumber of input tokensinput_tokens_details objectInput token details.
Properties cached_tokens integerNumber of input tokens that hit the cacheintegerNumber of output tokensoutput_tokens_details objectOutput token details.
Properties reasoning_tokens integerNumber of reasoning tokensintegerTotal number of tokensobjectSpend control; returned only when a historical record has a value; creation and update do not accept writes.
Properties limit integerSpending limit in centsconsumed integer / nullConsumed amount in cents | Response example |
Error codes
Business errors return an error object with type, code, message, and param. Common errors:
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / missing_required_parameter | Provide environment, for example {"type":"none"} or {"type":"openai_hosted"} |
400 | invalid_request_error / specific code depends on the field | Provide input for the applicable case; provide agent.model when there is no agent_id |
400 | invalid_request_error / invalid_type, invalid_value, unknown_parameter, invalid_json | Remove unknown fields, fix field types and enum values, and send valid JSON |
400 | invalid_request_error / specific code depends on the field | Shorten metadata, vault_ids, or the string field as described |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | not_found_error / not_found_error | Use a resource ID that exists in the current workspace |
502 | server_error / agents_api_upstream_unavailable | Retry later. If it keeps failing, submit a ticket with the x-request-id from the response headers |
503 | server_error / specific service error code | Retry later. If it keeps failing, submit a ticket with x-request-id |