更新 Agent

更新指定 Agent 的配置，使用乐观并发控制（OCC）。

POST /api/v1/cloud/agents/{agent_id}

更新指定 Agent 的配置。使用乐观并发控制（OCC），需要在请求体中提供当前 version 值。

​

请求头

头部	必选	说明
Authorization	是	Bearer <PAT>
Content-Type	是	application/json
x-qoder-beta	使用 Browser Use 时	整体替换 tools 时，如果新数组中配置了 browser_toolset_20260714，请求头 x-qoder-beta 必须包含 browser-use-2026-07-14。详见 Browser Use（Beta）

​

路径参数

参数	类型	必选	说明
agent_id	string	是	Agent 唯一标识

​

请求体

字段	类型	必选	说明
version	integer	是	当前版本号（OCC 校验），必须与服务端当前版本一致
name	string	否	Agent 名称，长度 1-256 字符
model	string | object	否	模型标识。可传 string 或 Agent model 对象以同时配置 effort 或 context_window。可通过 列出模型 查询可用值
system	string	否	系统提示词，最长 100000 字符
description	string	否	Agent 描述，最长 2048 字符
tools	Agent tool 数组	否	替换已保存的工具配置列表，最多 128 个
mcp_servers	MCP server 数组	否	替换已保存的 MCP server 列表，最多 20 个。tools 中的 mcp_toolset 必须引用此列表里的名称
skills	Skill binding 数组	否	替换已保存的 Skill 绑定列表，最多 20 个
metadata	object	否	Metadata 补丁。字符串值用于新增或更新 key；null 值用于删除已保存 metadata 中的 key

​

示例请求

curl -X POST "https://api.qoder.com/api/v1/cloud/agents/agent_019eXXXX..." \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent-updated",
    "model": "ultimate",
    "system": "你是更新后的文档测试助手",
    "description": "用于 API 文档测试",
    "version": 1
  }'

​

示例响应

HTTP 200 OK

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent-updated",
  "description": "用于 API 文档测试",
  "model": "ultimate",
  "system": "你是更新后的文档测试助手",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "metadata": {},
  "multiagent": null,
  "version": 2,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:27:07.967138Z"
}

​

响应字段

字段	类型	说明
type	string	固定值 "agent"
id	string	Agent 唯一标识，前缀为 agent_
name	string	Agent 名称
description	string	Agent 描述
model	string | object	模型标识，详见 Agent model
system	string	系统提示词
tools	Agent tool 数组	工具配置列表
mcp_servers	MCP server 数组	MCP 服务器配置
skills	Skill binding 数组	Skill 绑定列表
metadata	Metadata 对象	自定义元数据
multiagent	Multiagent | null	Agents 配置，未设置时为 null
version	integer	更新后的新版本号
archived_at	string|null	归档时间（ISO 8601），未归档时为 null
created_at	string	创建时间（ISO 8601）
updated_at	string	最后更新时间（ISO 8601）

​

乐观并发控制（OCC）

更新操作使用版本号进行乐观锁校验：

1. 客户端先通过 GET 获取 Agent 当前的 version 值
2. 更新时将该 version 放入请求体
3. 服务端校验 version 是否与当前值一致
4. 一致则更新成功，version 自动 +1
5. 不一致则返回 409 Conflict

这确保了多个客户端并发修改同一 Agent 时不会互相覆盖。

​

错误码

HTTP	type	触发条件
400	invalid_request_error	请求体格式错误或字段值不合法
400	invalid_request_error	model.effort 不在 none、low、medium、high、xhigh、max 之内
400	invalid_request_error	model.context_window 不是正整数
400	invalid_request_error	传入了 model.speed，请改用 model.effort
400	invalid_request_error	tools 数量超过 128 个上限
400	invalid_request_error	mcp_servers 数量超过 20 个上限
400	invalid_request_error	skills 数量超过 20 个上限
400	invalid_request_error	使用 browser_toolset_20260714 但未携带 Browser Use Beta 请求头
401	authentication_error	PAT 无效或过期
403	permission_error	无权限更新此 Agent
404	not_found_error	指定 ID 的 Agent 不存在
409	conflict_error	version 不匹配，存在并发冲突
503	feature_not_available	Browser Use 暂时不可用

版本冲突（409）错误响应示例：

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 99, got 1."
  }
}

​

注意事项

• version 字段是必须的，不传会导致更新失败
• 每次成功更新后 version 自动递增
• 更新为部分更新（merge）语义：请求体中未传入的可选字段将保持原值不变，仅显式传入的字段会被更新
• 显式传入 tools、mcp_servers 或 skills 时，该字段的数组会整体替换为请求中的数组
• 显式传入 metadata 时，字符串值会合并到已保存 metadata 对象中，null 值会删除已存在的 key
• 可通过 列出 Agent 版本 查看历史版本

​

相关

定义 Agent

创建可复用、可版本化的 Agent 配置。