Agent - Agent Studio

版本机制

智能体使用 version 整数字段跟踪配置历史，行为如下：

更新接口采用全量替换语义，成功后 version 自动 +1，请求体需带当前值用作乐观锁，不一致返回 409。
会话创建时锁定当时 version，已有会话不受后续更新影响；查询历史版本通过 GET /agents/{agent_id}?version=N。
归档为软操作，archived_at 被填入归档时间；归档后不可用于新建会话，已有会话不受影响。

创建 Agent

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`
`skills`	否	array<object>	挂载的技能列表，每项含 `type`（`official` \| `customer`）、`skill_id` 与 `version`（必须锁定到具体版本号）
`metadata`	否	object	业务自定义键值，不影响模型行为

请求示例

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"}
  }'

响应示例

{
  "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	本次请求的唯一标识，排查问题时附带

获取 Agent

GET /agents/{agent_id} 默认返回最新版本；带 ?version=N 查询历史版本。

列出 Agent

GET /agents 分页列出工作空间下的智能体，默认不含已归档。传 include_archived=true 包含已归档。

更新 Agent

POST /agents/{agent_id} 全量替换；请求体需带 version 作乐观锁，成功后递增。

归档 Agent

POST /agents/{agent_id}/archive 软归档；不可用于新建会话，已有会话不受影响。

列出 Agent 版本

GET /agents/{agent_id}/versions 分页返回该智能体的全部历史版本。

​版本机制

​创建 Agent

​请求体

​请求示例

​响应示例

​响应字段

​获取 Agent

​列出 Agent

​更新 Agent

​归档 Agent

​列出 Agent 版本