更新 Agent

前提

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

接口

POST /agents/{agent_id}

语义

采用全量替换：请求体须包含 version（当前版本号，用于乐观锁）以及完整的 name、model、system、tools 等字段，缺省的字段视为清空。成功后响应中 version 自动递增；已绑定旧版本的会话不受影响。

请求体

字段	必填	类型	说明
`version`	是	int	当前版本号，用于乐观锁。若与服务端不一致返回 409 冲突
`name`	是	string	智能体名称，缺省视为清空
`model`	是	object	模型配置，结构 `{"id": "qwen3.7-max"}`，必填子字段 `id`
`description`	否	string	智能体用途说明，缺省视为清空
`system`	否	string	系统提示词，缺省视为清空
`tools`	否	array<object>	工具包列表，含义同创建，缺省视为清空。`builtin_toolkit` 至多一项，`mcp_toolkit` 可多项
`mcp_servers`	否	array<object>	MCP Server 引用列表，含义同创建，缺省视为清空
`skills`	否	array<object>	挂载的技能列表，含义同创建，缺省视为清空
`multiagent`	否	object	多智能体协作配置，含义同创建，缺省视为清空
`metadata`	否	object	业务自定义键值，缺省视为清空

各字段结构详见创建 Agent的请求体一节。

请求示例

curl -X POST "$AGENTSTUDIO_URL/agents/agent_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "name": "data-analyst",
    "description": "数据分析助手",
    "model": {"id": "qwen3.7-max"},
    "system": "你是资深数据分析师，输出结论时附带置信度。",
    "tools": [],
    "mcp_servers": [],
    "skills": [],
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "self"},
        {"type": "agent", "id": "agent_researcher", "version": 3}
      ]
    },
    "metadata": {"team": "data"}
  }'

响应说明

响应为更新后的 Agent 对象，结构同创建 Agent响应，version 自动递增。字段如下：

响应字段

字段	类型	说明
`id`	string	智能体 ID
`type`	string	固定为 `agent`
`version`	int	新版本号（自动递增）；已绑定旧版本的会话不受影响
`name` / `description` / `system`	string	请求体覆盖后的新值
`model` / `tools` / `mcp_servers` / `skills` / `multiagent` / `metadata`	object / array	请求体覆盖后的新值，缺省字段为空
`archived_at`	string / null	归档时间，未归档时为 `null`
`created_at` / `updated_at`	string	创建 / 最近更新时间
`workspace_id`	string	所属工作空间 ID
`request_id`	string	本次请求的唯一标识

​前提

​接口

​语义

​请求体

​请求示例

​响应说明

​响应字段

前提

接口

语义

请求体

请求示例

响应说明

响应字段