Skip to main content

Create agent

Create a reusable agent configuration that stores the model, instructions, tools, and multi-agent settings.

Endpoint

POST /agents Returns 201 and the complete agent object. Creation only saves the configuration. It does not start a session, model, or MCP server. Submitting the same request body again creates a new resource.

Request body

model string (required)Model ID. It must match a model available in the current workspace; otherwise the API returns 404 model_not_found. For available models, see Available models.name string / null (optional)Display name, up to 128 characters.instructions string / null (optional)Custom instructions appended to the agent's default instructions, up to 1,048,576 characters.metadata object / null (optional)Metadata, string key-value pairs. Recommended limits are 16 items, key up to 64 characters, and value up to 512 characters. All values must be strings.reasoning object / null (optional)Reasoning settings, containing the following fields.
effort string / null (optional)Reasoning effort: none, minimal, low, medium, high, xhigh, or max.summary string / null (optional)Reasoning summary: concise, detailed, or auto.
text object / null (optional)Text output settings, containing the following fields.
type string (conditional)Output format type, fixed as text.
verbosity string / null (optional)Output verbosity, low, medium, or high. Session execution currently accepts only medium.
tools array / null (optional)Tool configuration. Each tool must provide a type. The current supported types are function, mcp, and web_search. Creation only saves the configuration; it does not mean the tool can execute.
name string (required)Function namedescription string / null (required)Function description, can be nullparameters object (required)Function input JSON Schema; must declare type: object
server_label string (required)MCP server labeltransport object (required)Transport configuration; see the branches below
type string (required)Transport type, http or stdioserver_url string / null (conditional)MCP server URLheaders object<string,string> / null (optional)Additional HTTP headers; do not put secrets herecommand string (conditional)Command to start the servercwd string (conditional)Working directory; must be an absolute path whose segments are not . or ..args array<string> / null (optional)Command arguments
allowed_tools array<string> / null (optional)Allowed tool names; null means no filterrequired boolean (optional)Whether MCP initialization must succeedconnection_origin string / null (optional)Connection origin, service or environment, defaults to service
type string (required)Tool type, fixed as web_search
multi_agent object / null (optional)Subagent configuration, containing the following fields.
enabled boolean (required)Whether subagent tools are enabled; required when the parent object is present.max_concurrent_subagents integer / null (optional)Concurrent subagent limit. Execution currently supports 1..32, default 6.
Unknown top-level fields do not produce an error and may be filtered out and recorded; do not assume a field is applied just because the request succeeds.

Request example

curl -sS -X POST "$BASE_URL/agents" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "name": "support-agent",
    "instructions": "Answer briefly and include steps when necessary.",
    "metadata": {"team": "support"}
  }'

Response fields

id stringAgent ID. Treat it as an opaque string.object stringAgent object type, fixed as agent.created_at integerCreation time as a Unix timestamp in seconds.updated_at integerLast modification time as a Unix timestamp in seconds, not a version number.name string / nullDisplay name.metadata object / nullMetadata, saved string key-value pairs.model stringSaved model ID.reasoning object / nullReasoning configuration. Either subfield can be null.
effort string / nullReasoning effort: none, minimal, low, medium, high, xhigh, maxsummary string / nullReasoning summary: concise, detailed, auto
text object / nullText output configuration.
format objectOutput format.
type string / nullOutput format type, fixed as text
verbosity string / nullOutput verbosity, low, medium, high
instructions string / nullSaved custom instructions.tools array / nullSaved tool configuration. Each branch returns only its own fields.
function objectFunction tool configuration; returns name, description, and parametersmcp objectMCP tool configuration; returns server_label, transport, allowed_tools, required, and connection_origin; transport is http or stdioweb_search objectWeb search tool configuration; returns type and the saved configuration
multi_agent object / nullSubagent configuration.
enabled booleanWhether subagent tools are enabledmax_concurrent_subagents integer / nullMaximum number of concurrent subagents; no default is applied

Response example

{
  "id": "agent_xxx",
  "object": "agent",
  "created_at": 1794117521,
  "updated_at": 1794117521,
  "name": "support-agent",
  "metadata": {"team": "support"},
  "model": "qwen3.8-max",
  "reasoning": null,
  "text": null,
  "instructions": "Answer briefly and include steps when necessary.",
  "tools": null,
  "multi_agent": null
}

Available models

model supports the following models:
BrandModel IDCapabilities
Qwenqwen4-maxReasoning, visual understanding, text generation
Qwenqwen3.8-maxReasoning, visual understanding, text generation
Qwenqwen3.7-maxReasoning, text generation
Qwenqwen3.7-plusReasoning, visual understanding, text generation
Qwenqwen3.6-plusReasoning, visual understanding, text generation
DeepSeekdeepseek-v4-proReasoning, text generation
Zhipu AIglm-5.3Reasoning, text generation
Zhipu AIglm-5.2Reasoning, text generation
Moonshot AIkimi-k3Reasoning, visual understanding, text generation
Models with visual understanding can process images passed when creating a session. See Create session.
The model list is continuously updated. The dropdown list shown when creating an agent in the console is authoritative.

Error codes

Business errors return an error object with type, code, message, and param. Common errors:
HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorProvide model as described, fix field types and enums, satisfy tool cross-field constraints, and send valid JSON
400invalid_request_error / string_above_max_lengthShorten instructions to 1,048,576 characters or fewer
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404invalid_request_error / model_not_foundUse a model ID that is available in the current workspace
500server_error / server_errorRetry later. If it keeps failing, submit a ticket with x-request-id
Authentication, workspace routing, and rate-limit errors can be returned directly by the gateway with a different structure.