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

采用全量替换语义：请求体须包含 version以及完整的智能体配置，缺省的字段视为清空。成功后 version 自动递增。

前提

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

接口

POST /agents/{agent_id}

语义

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

请求体

字段	必填	类型	说明
`version`	是	int	当前版本号。若与服务端不一致返回 409 冲突
其余字段	同创建	—	`name`、`model`、`system`、`tools`、`mcp_servers`、`skills`、`description`、`metadata`。字段含义同创建 Agent，缺省视为清空

请求示例

Bash

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-max"},
    "system": "你是资深数据分析师，输出结论时附带置信度。",
    "tools": [],
    "mcp_servers": [],
    "skills": [],
    "metadata": {"team": "data"}
  }'

Python

current = client.agents.retrieve("agent_xxx")
agent = client.agents.update(
    "agent_xxx",
    version=current.version,
    name="data-analyst",
    model="qwen3-max",
    description="数据分析助手",
    system_prompt="你是资深数据分析师，输出结论时附带置信度。",
    tools=[],
    mcp_servers=[],
    skills=[],
    metadata={"team": "data"},
)

Java

Agent current = client.agents().retrieve("agent_xxx");
Agent updated = client.agents().update("agent_xxx", AgentUpdateParam.builder()
    .version(current.getVersion())
    .name("data-analyst")
    .model("qwen3-max")
    .description("数据分析助手")
    .instructions("你是资深数据分析师，输出结论时附带置信度。")
    .metadata(Map.of("team", "data"))
    .build());

响应说明

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

响应字段

字段	类型	说明
`id`	string	智能体 ID
`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	创建/最近更新时间
`workspace_id`	string	所属工作空间 ID
`request_id`	string	本次请求的唯一标识