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 bodymodelstring (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.
Properties effort string / null (optional)Reasoning effort: none, minimal, low, medium, high, xhigh, or max.summary string / null (optional)Reasoning summary: concise, detailed, or auto.object / null (optional)Text output settings, containing the following fields.
Properties
format type string (conditional)Output format type, fixed as text.string / null (optional)Output verbosity, low, medium, or high. Session execution currently accepts only medium.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.
Properties
function name string (required)Function namedescription string / null (required)Function description, can be nullparameters object (required)Function input JSON Schema; must declare type: object
mcp server_label string (required)MCP server labeltransport object (required)Transport configuration; see the branches below
Properties 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 argumentsarray<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
web_search type string (required)Tool type, fixed as web_searchobject / null (optional)Subagent configuration, containing the following fields.
Properties 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. | Request example |
Response fieldsidstringAgent 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.
Properties effort string / nullReasoning effort: none, minimal, low, medium, high, xhigh, maxsummary string / nullReasoning summary: concise, detailed, autoobject / nullText output configuration.
Properties format objectOutput format.
Properties type string / nullOutput format type, fixed as textstring / nullOutput verbosity, low, medium, highstring / nullSaved custom instructions.tools array / nullSaved tool configuration. Each branch returns only its own fields.
Properties 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 configurationobject / nullSubagent configuration.
Properties enabled booleanWhether subagent tools are enabledmax_concurrent_subagents integer / nullMaximum number of concurrent subagents; no default is applied | Response example |
Available models
model supports the following models:
| Brand | Model ID | Capabilities |
|---|---|---|
| Qwen | qwen4-max | Reasoning, visual understanding, text generation |
| Qwen | qwen3.8-max | Reasoning, visual understanding, text generation |
| Qwen | qwen3.7-max | Reasoning, text generation |
| Qwen | qwen3.7-plus | Reasoning, visual understanding, text generation |
| Qwen | qwen3.6-plus | Reasoning, visual understanding, text generation |
| DeepSeek | deepseek-v4-pro | Reasoning, text generation |
| Zhipu AI | glm-5.3 | Reasoning, text generation |
| Zhipu AI | glm-5.2 | Reasoning, text generation |
| Moonshot AI | kimi-k3 | Reasoning, visual understanding, text generation |
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 status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Provide model as described, fix field types and enums, satisfy tool cross-field constraints, and send valid JSON |
400 | invalid_request_error / string_above_max_length | Shorten instructions to 1,048,576 characters or fewer |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | invalid_request_error / model_not_found | Use a model ID that is available in the current workspace |
500 | server_error / server_error | Retry later. If it keeps failing, submit a ticket with x-request-id |