Create Agent

Prerequisites

Endpoint and authentication configured. For details, see Overview and authentication.

Endpoint

POST /agents

Request body

Field	Required	Type	Description
`name`	Yes	string	Agent name, used for identification in the console and list views
`description`	No	string	Description of the agent's purpose
`model`	Yes	object	Model configuration. Required sub-field `id` (model ID, e.g. qwen3.7-max); optional sub-fields `enable_thinking` (bool, whether to enable thinking mode), `max_tokens` (int32, maximum generation length), `temperature` (double, sampling temperature that controls randomness), and `thinking_budget` (int32, thinking budget length)
`system`	No	string	System prompt that defines the role and behavioral constraints
`tools`	No	array<object>	Toolkit list, grouped by type. Each item contains `type` (`builtin_toolkit` \| `mcp_toolkit`), `default_config` (includes `enabled` and `permission_policy`), and `configs` (per-tool config that overrides `default_config`). MCP types also require `mcp_server_name`. At most one `builtin_toolkit` is allowed; multiple `mcp_toolkit` items are allowed
`mcp_servers`	No	array<object>	MCP Server reference list. Each item contains `type` (`official` \| `customer`) and `name`. The `name` can be found as the service ID on the service card in the MCP Management menu of the Bailian console (custom services are named at creation time)
`skills`	No	array<object>	Mounted skill list. Each item contains `type` (`official` \| `customer`), `skill_id`, and `version` (must be locked to a concrete version number). The `skill_id` can be viewed on the skill detail page in the Skill Management menu of the Bailian console
`multiagent`	No	object	Multi-agent collaboration configuration. Omitting or leaving empty indicates a single agent. Once configured, the agent acts as a coordinator that orchestrates fleet members. Contains `type` (currently only `coordinator`) and `agents` (1-20 fleet entries; pass an empty array to clear the fleet). Each entry contains `type` (`agent` (references another Agent) / `self` (the coordinator itself, at most one in the fleet)), `id` (required when `type=agent`, max 64 chars; forbidden when `type=self`), and `version` (optional when `type=agent`, defaults to latest; forbidden when `type=self`)
`metadata`	No	object	Custom business key-value pairs; does not affect model behavior

permission_policy.type takes values always_allow (execute directly) / always_ask (pause and wait for manual confirmation before each call). Tool approval is only supported on the main agent, not sub-agents. The approval policy for MCP tools is configured in the default_config / configs of the tools[].type=mcp_toolkit item, not in mcp_servers[].

Request example

curl -X POST "$AGENTSTUDIO_URL/agents" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-analyst",
    "description": "数据分析助手",
    "model": {"id": "qwen3.7-max"},
    "system": "你是数据分析专家，使用 pandas 处理 CSV 文件。",
    "tools": [
      {
        "type": "builtin_toolkit",
        "default_config": {
          "enabled": true,
          "permission_policy": {"type": "always_allow"}
        },
        "configs": [
          {"name": "bash", "enabled": true, "permission_policy": {"type": "always_ask"}},
          {"name": "read", "enabled": true},
          {"name": "write", "enabled": true}
        ]
      }
    ],
    "mcp_servers": [],
    "skills": [
      {"type": "customer", "skill_id": "skill_xxx", "version": "1.0"}
    ],
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "self"},
        {"type": "agent", "id": "agent_researcher", "version": 3}
      ]
    },
    "metadata": {"team": "data"}
  }'

Response example

{
  "id": "agent_xxx",
  "type": "agent",
  "version": 1,
  "name": "data-analyst",
  "description": "数据分析助手",
  "model": {"id": "qwen3.7-max"},
  "system": "你是数据分析专家，使用 pandas 处理 CSV 文件。",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "multiagent": {
    "type": "coordinator",
    "agents": [
      {"type": "self"},
      {"type": "agent", "id": "agent_researcher", "version": 3}
    ]
  },
  "metadata": {"team": "data"},
  "created_at": "2026-05-28T16:23:11.456+08:00",
  "updated_at": "2026-05-28T16:23:11.456+08:00",
  "archived_at": null,
  "workspace_id": "ws_xxx",
  "request_id": "req_xxx"
}

Response fields

Field	Type	Description
`id`	string	Agent ID, format: `agent_<ULID>`
`type`	string	Always `agent`
`version`	int	Current version number, auto-incremented on each update; locked when a session is created
`name` / `description` / `system`	string	Same as request body
`model` / `tools` / `mcp_servers` / `skills` / `multiagent` / `metadata`	object / array	Same as request body
`archived_at`	string \| null	Archive timestamp; `null` if not archived
`created_at` / `updated_at`	string	Creation / last update time, ISO 8601
`workspace_id`	string	Workspace ID
`request_id`	string	Unique identifier for this request; include when troubleshooting

​Prerequisites

​Endpoint

​Request body

​Request example

​Response example