Skip to main content

Create session

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 body

environment object (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
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
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
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 medium
tools array (optional)Tool list, omitted becomes an empty list, an explicit null is not accepted. Up to 32 function tools and 16 MCP servers
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
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
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 arguments
allowed_tools array<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
type string (required)Tool type, fixed as web_search
multi_agent object / 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
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 null
input string or array / null (conditional)First input. A string is shorthand for one user text message; an empty string is rejected
role string (required)Message role, fixed as usertype string (optional)Message type, if set, only messagecontent array (required)Message content; cannot be empty
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 guaranteed
metadata object / 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

curl -sS -X POST "$BASE_URL/agents/sessions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "qwen3.8-max",
      "instructions": "Answer briefly."
    },
    "environment": {"type": "none"},
    "input": "Hello"
  }'

Environment

FormDescription
{"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
For fields, limits, and asynchronous preparation, see Environment. 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 fields

null 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.
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_subagents
environment objectSafe environment summary; only type for none.
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 environments
metadata objectSession metadata; an empty value is {}vault_ids array<string>Vault IDs recorded at creationrequired_actions arrayFunction calls that need client handling; [] when empty.
type stringItem type, fixed as function_callturn_id stringPublic turn IDcall_id stringFunction call IDname stringFunction namearguments objectParsed call arguments
error string / nullSession-level error message, different from a turn's structured errorusage object / nullToken usage.
input_tokens integerNumber of input tokensinput_tokens_details objectInput token details.
cached_tokens integerNumber of input tokens that hit the cache
output_tokens integerNumber of output tokensoutput_tokens_details objectOutput token details.
reasoning_tokens integerNumber of reasoning tokens
total_tokens integerTotal number of tokens
spend_control objectSpend control; returned only when a historical record has a value; creation and update do not accept writes.
limit integerSpending limit in centsconsumed integer / nullConsumed amount in cents

Response example

{
  "id": "sess_xxx",
  "object": "agent.session",
  "created_at": 1794118835,
  "last_active_at": 1794118835,
  "status": "in_progress",
  "agent": {
    "id": "agent_xxx",
    "model": "qwen3.8-max",
    "instructions": "Answer briefly.",
    "reasoning": {"effort": "none", "summary": "auto"},
    "text": {"format": {"type": "text"}, "verbosity": "medium"},
    "tools": [],
    "multi_agent": {"enabled": false, "max_concurrent_subagents": null},
    "name": null
  },
  "environment": {"type": "none"},
  "metadata": {},
  "required_actions": [],
  "vault_ids": [],
  "error": null,
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 0,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 0
  }
}

Error codes

Business errors return an error object with type, code, message, and param. Common errors:
HTTP statusError type / codeSolution
400invalid_request_error / missing_required_parameterProvide environment, for example {"type":"none"} or {"type":"openai_hosted"}
400invalid_request_error / specific code depends on the fieldProvide input for the applicable case; provide agent.model when there is no agent_id
400invalid_request_error / invalid_type, invalid_value, unknown_parameter, invalid_jsonRemove unknown fields, fix field types and enum values, and send valid JSON
400invalid_request_error / specific code depends on the fieldShorten metadata, vault_ids, or the string field as described
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404not_found_error / not_found_errorUse a resource ID that exists in the current workspace
502server_error / agents_api_upstream_unavailableRetry later. If it keeps failing, submit a ticket with the x-request-id from the response headers
503server_error / specific service error codeRetry later. If it keeps failing, submit a ticket with x-request-id