An agent defines the model, system prompt, tools, and extended capabilities. Each save automatically creates a new version.
Configuration fields
On the Agents page, click Create Agent, or click an existing agent to open its detail page. You can configure the following fields:
Field | Required | Mutable | Description |
Name | Yes | Yes | Unique identifier within the workspace, for example "data-analysis-assistant" |
Description | No | Yes | Brief description of the agent's purpose, displayed in lists and dropdowns |
Model | Yes | Yes | Select from the dropdown, for example |
System prompt | No | Yes | Defines the agent's role, behavior, and constraints. Changes create a new version |
Tools | No | Yes | 7 built-in tools that you can enable as needed. For details, see Agent Tool Configuration |
MCP servers | No | Yes | Attach activated MCP services (official or custom). All tools under a service are enabled by default and can be disabled individually |
Skills | No | Yes | Attach uploaded skill packages with a pinned version |
Metadata | No | Yes | Custom key-value pairs (corresponding to the |
When creating an agent via the API, you must specify the name and model. The system prompt and tool set are optional. For full request parameters and response fields, see Create Agent.
curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/agents" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "data-analyst",
"model": {"id": "qwen3-max"},
"system": "You are a data analysis expert. Use pandas to process CSV files.",
"tools": [
{
"type": "builtin_toolkit",
"default_config": {"enabled": true},
"configs": [
{"name": "bash", "enabled": true},
{"name": "read", "enabled": true},
{"name": "write", "enabled": true}
]
}
]
}'agent = client.agents.create(
name="data-analyst",
model="qwen3-max",
system_prompt="You are a data analysis expert. Use pandas to process CSV files.",
tools=[
{"type": "builtin_toolkit",
"default_config": {"enabled": True},
"configs": [
{"name": "bash", "enabled": True},
{"name": "read", "enabled": True},
{"name": "write", "enabled": True},
]}
],
)
print(agent.id) # "agent_xxx"
print(agent.version) # 1Agent agent = client.agents().create(AgentCreateParam.builder()
.name("data-analyst")
.model("qwen3-max")
.instructions("You are a data analysis expert. Use pandas to process CSV files.")
.build());
System.out.println(agent.getId()); // "agent_xxx"
System.out.println(agent.getVersion()); // 1Related configurations
Versioning
Each time you save an agent, the version auto-increments. A session is pinned to the version at the time of creation; subsequent edits do not affect existing sessions. API updates use full-replacement semantics — the request body must include the current version for optimistic lock validation, and omitted fields are treated as cleared.
Archiving and deletion
Agents support archiving only, not deletion. After clicking Archive on the agent detail page, the agent no longer appears in the list by default, cannot be used to create new sessions, and existing sessions are not affected. Archived agents can still be queried via the API (include_archived=true).
To archive an agent via the API, see Archive Agent.
curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/agents/agent_xxx/archive" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"client.agents.archive("agent_xxx")client.agents().archive("agent_xxx");