Update Agent
Uses full replacement semantics: the request body must include version along with the complete agent configuration. Omitted fields are treated as cleared. On success, version is auto-incremented.
Prerequisites
Endpoint and authentication configured. For details, see Overview and authentication.
Endpoint
POST /agents/{agent_id}
Semantics
Uses full replacement: the request body must include version (current version number, used for optimistic locking) along with the complete name, model, system, tools, and other fields. Omitted fields are treated as cleared. If version does not match the server-side value, a 409 Conflict is returned. On success, the version in the response is auto-incremented; sessions bound to a previous version are not affected.
Request body
| Field | Required | Type | Description |
|---|---|---|---|
version | Yes | int | Current version number, used for optimistic locking. Returns 409 Conflict if it does not match the server-side value |
name | Yes | string | Agent name; omitted fields are treated as cleared |
model | Yes | object | Model configuration, structure {"id": "qwen3-max"}, required sub-field id |
description | No | string | Agent purpose description; omitted fields are treated as cleared |
system | No | string | System prompt; omitted fields are treated as cleared |
tools | No | array<object> | Toolkit list, same as create; omitted fields are treated as cleared. builtin_toolkit at most one, mcp_toolkit can be multiple |
mcp_servers | No | array<object> | MCP Server reference list, same as create; omitted fields are treated as cleared |
skills | No | array<object> | Mounted skill list, same as create; omitted fields are treated as cleared |
multiagent | No | object | Multi-agent collaboration configuration, same as create; omitted fields are treated as cleared |
metadata | No | object | Custom business key-value pairs; omitted fields are treated as cleared |
For field structures, see the Request body section of Create Agent.
Request example
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": [],
"multiagent": {
"type": "coordinator",
"agents": [
{"type": "self"},
{"type": "agent", "id": "agent_researcher", "version": 3}
]
},
"metadata": {"team": "data"}
}'
current = client.agents.retrieve("agent_xxx")
agent = client.agents.update(
"agent_xxx",
version=current.version,
name="data-analyst",
model="qwen3.8-max",
description="数据分析助手",
system_prompt="你是资深数据分析师，输出结论时附带置信度。",
tools=[],
mcp_servers=[],
skills=[],
metadata={"team": "data"},
)
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());
Response
The response is the updated Agent object, with the same structure as the Create Agent response. The version is auto-incremented. Fields:
Response fields
| Field | Type | Description |
|---|---|---|
id | string | Agent ID |
type | string | Always agent |
version | int | New version number (auto-incremented); sessions bound to a previous version are not affected |
name / description / system | string | New values after replacement from the request body |
model / tools / mcp_servers / skills / multiagent / metadata | object / array | New values after replacement from the request body; omitted fields are empty |
archived_at | string | null | Archive timestamp; null if not archived |
created_at / updated_at | string | Creation / last update time |
workspace_id | string | Workspace ID |
request_id | string | Unique identifier for this request |