Define an Agent

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:

Field	Required	Editable	Description
Name	Yes	Yes	Unique identifier within the workspace, e.g., "Data Analysis Assistant"
Description	No	Yes	Brief description of the agent's purpose, shown in lists and dropdowns
Model	Yes	Yes	Select from dropdown; see Available models for the currently supported models. Changing the model creates a new version
System Prompt	No	Yes	Defines the agent's role, behavior, and constraints. Changes trigger a new version
Tools	No	Yes	Nine built-in tools—select as needed. See Agent Tool Configuration for details
MCP Server	No	Yes	Mount an enabled MCP service (official or custom); all tools under it are enabled by default and can be selectively disabled
Skills	No	Yes	Mount uploaded skill packages and lock their versions
Multi-Agent	No	Yes	Configure a coordinator formation to orchestrate multiple member agents. See Multi-Agent Collaboration for details
Metadata	No	Yes	Custom 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.

You can also manage agents as Infrastructure-as-Code with the Bailian CLI: bl managed-agent init generates a config template, bl managed-agent plan previews changes, and bl managed-agent apply creates everything in one step. See Use the CLI.

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.8-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}
        ]
      }
    ]
  }'

Available models

model.id supports smart modes, where the platform routes by tier:

Mode ID	Description
`auto`	Automatically routes to the appropriate tier based on task complexity
`performance`	Performance tier: high-quality models balancing speed and quality
`balanced`	Balanced tier: advanced reasoning with high-quality output
`economy`	Economy tier: standard reasoning at high cost-effectiveness

The following models are also supported:

Brand	Model ID	Capabilities
Qwen	qwen3.8-max	Reasoning, visual understanding, text generation
Qwen	qwen3.8-flash	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
Qwen	qwen3.6-flash	Reasoning, visual understanding, text generation
DeepSeek	deepseek-v4-pro	Reasoning, text generation
DeepSeek	deepseek-v4-flash-0731	Reasoning, text generation
Zhipu AI	glm-5.2	Reasoning, text generation
Zhipu AI	glm-5.1	Reasoning, text generation
Moonshot AI	kimi-k3	Reasoning, visual understanding, text generation

Models with visual understanding can process images and videos delivered in sessions. See Send Event.

The model list is continuously updated. The dropdown list shown when creating an agent in the console is authoritative.

An agent's capabilities are jointly determined by the following components. For detailed configuration, refer to their respective documentation pages:

Agent Tool Configuration: Nine 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

Start a Session: Initiate a session using your configured agent.
Cloud Hosting Environment: Prepare a sandbox environment for tool execution.

​Configuration Fields

​Available models

​Related Configurations

​Versioning

​Archiving and Deletion

​Next Steps

Configuration Fields

Available models

Related Configurations

Versioning

Archiving and Deletion

Next Steps