Skip to main content
Build Agent

Define an Agent

An agent defines its model, system prompt, tools, and extended capabilities; each save automatically generates a new version.

Configuration Fields

On the Agents page, click Create Agent, or click an existing agent to enter its detail page, where you can configure the following fields:
FieldRequiredEditableDescription
NameYesYesUnique identifier within the workspace, e.g., "Data Analysis Assistant"
DescriptionNoYesBrief description of the agent’s purpose, shown in lists and dropdowns
ModelYesYesSelect from dropdown, e.g., qwen3-max. Changing the model creates a new version
System PromptNoYesDefines the agent’s role, behavior, and constraints. Changes trigger a new version
ToolsNoYesSeven built-in tools—select as needed. See Agent Tool Configuration for details
MCP ServerNoYesMount an enabled MCP service (official or custom); all tools under it are enabled by default and can be selectively disabled
SkillsNoYesMount uploaded skill packages and lock their versions
Multi-AgentNoYesConfigure a coordinator formation to orchestrate multiple member agents. See Multi-Agent Collaboration for details
MetadataNoYesCustom key-value pairs (corresponding to the API’s metadata field). Does not affect model behavior; useful for tagging environment identifiers, version numbers, or other business metadata
When creating an agent via API, you must specify the name and model; system prompt and tool set are optional. For full parameter and response field details, see the Create Agent API. 
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 who uses 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}
        ]
      }
    ]
  }'
An agent’s capabilities are jointly determined by the following components. For detailed configuration, refer to their respective documentation pages:
  • Agent Tool Configuration: Seven out-of-the-box tools covering command execution, file operations, and network access.
  • Agent MCP: Integrate external tool services via the MCP protocol.
  • Agent Skills: Mount pre-packaged tool combinations that encapsulate end-to-end task workflows.
  • Multi-Agent Collaboration: Orchestrate multiple member agents through a coordinator formation.

Versioning

Each time you save an agent, its version number automatically increments. Sessions lock to the agent version active at creation time—subsequent edits do not affect existing sessions. When updating via API, full-replacement semantics apply: the request body must include the current version for optimistic concurrency control; omitted fields are treated as cleared.

Archiving and Deletion

Agents support archiving but not deletion. After clicking Archive on the agent detail page, the agent is hidden from default lists and cannot be used for new sessions—existing sessions remain unaffected. Archived agents remain accessible via API using include_archived=true. For API-based archiving, see the Archive Agent API. 
curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/agents/agent_xxx/archive" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Next Steps

Overview
Build Agent
Environment
Sessions
Context
Event Subscriptions
Billing
Changelog