创建智能体 API：POST /agents-大模型服务平台百炼(Model Studio)-阿里云帮助中心

前提

已完成 Endpoint 与鉴权配置，详见API 总览与认证。

接口

POST /agents

请求体

字段	必填	类型	说明
`name`	是	string	智能体名称，用于在控制台与列表中辨识
`description`	否	string	智能体用途说明
`model`	是	object	模型配置，结构 `{"id": "qwen3-max"}`
`system`	否	string	系统提示词，定义角色与行为约束
`tools`	否	array<object>	工具包列表，按类型分组。每项含 `type`（`builtin_toolkit` \| `mcp_toolkit`）、`default_config`、`configs`，MCP 类还需 `mcp_server_name`。`builtin_toolkit` 至多一项，`mcp_toolkit` 可多项
`mcp_servers`	否	array<object>	MCP Server 引用列表，每项含 `type`（`official` \| `customer`）与 `name`。`name` 可在百炼控制台 MCP 管理菜单的服务卡片上查看服务ID（自定义服务在创建时指定）
`skills`	否	array<object>	挂载的技能列表，每项含 `type`（`official` \| `customer`）、`skill_id` 与 `version`（必须锁定到具体版本号）。`skill_id` 在百炼控制台 Skill管理菜单的技能详情页查看
`metadata`	否	object	业务自定义键值，不影响模型行为

请求示例

Bash

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-max"},
    "system": "你是数据分析专家，使用 pandas 处理 CSV 文件。",
    "tools": [
      {
        "type": "builtin_toolkit",
        "default_config": {"enabled": true},
        "configs": [
          {"name": "bash", "enabled": true},
          {"name": "read", "enabled": true},
          {"name": "write", "enabled": true}
        ]
      }
    ],
    "mcp_servers": [],
    "skills": [
      {"type": "customer", "skill_id": "skill_xxx", "version": "1.0"}
    ],
    "metadata": {"team": "data"}
  }'

Python

agent = client.agents.create(
    name="data-analyst",
    model="qwen3-max",
    description="数据分析助手",
    system_prompt="你是数据分析专家，使用 pandas 处理 CSV 文件。",
    tools=[
        {"type": "builtin_toolkit",
         "default_config": {"enabled": True},
         "configs": [
             {"name": "bash", "enabled": True},
             {"name": "read", "enabled": True},
             {"name": "write", "enabled": True},
         ]}
    ],
    mcp_servers=[],
    skills=[{"type": "customer", "skill_id": "skill_xxx", "version": "1.0"}],
    metadata={"team": "data"},
)
print(agent.id)       # "agent_xxx"
print(agent.version)  # 1

Java

Agent agent = client.agents().create(AgentCreateParam.builder()
    .name("data-analyst")
    .model("qwen3-max")
    .description("数据分析助手")
    .instructions("你是数据分析专家，使用 pandas 处理 CSV 文件。")
    .metadata(Map.of("team", "data"))
    .build());
System.out.println(agent.getId());       // "agent_xxx"
System.out.println(agent.getVersion());  // 1

响应示例

{
  "id": "agent_xxx",
  "type": "agent",
  "version": 1,
  "name": "data-analyst",
  "description": "数据分析助手",
  "model": {"id": "qwen3-max"},
  "system": "你是数据分析专家，使用 pandas 处理 CSV 文件。",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "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"
}

响应字段

字段	类型	说明
`id`	string	智能体 ID，格式 `agent_<ULID>`
`type`	string	固定为 `agent`
`version`	int	当前版本号，每次更新自动递增；会话创建时锁定该值
`name` / `description` / `system`	string	同请求体
`model` / `tools` / `mcp_servers` / `skills` / `metadata`	object / array	同请求体
`archived_at`	string \| null	归档时间，未归档时为 `null`
`created_at` / `updated_at`	string	创建/最近更新时间，ISO 8601
`workspace_id`	string	所属工作空间 ID
`request_id`	string	本次请求的唯一标识，排查问题时附带