更新 Agent-Qoder CN 系列(Lingma)-阿里云帮助中心

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

请求头

头部	必选	说明
`Authorization`	是	`Bearer`
`Content-Type`	是	`application/json`

路径参数

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

请求体

字段	类型	必选	说明
`version`	integer	是	当前版本号（OCC 校验），必须与服务端当前版本一致
`name`	string	否	Agent 名称，长度 1-256 字符
`model`	string/object	否	模型标识
`instructions`	string	否	系统提示词
`description`	string	否	Agent 描述
`tools`	array	否	工具配置列表
`mcp_servers`	array	否	MCP 服务器配置列表
`skills`	array	否	Skill 绑定列表，格式 `[{"type":"custom","skill_id":""}]`，最多 20 个
`metadata`	object	否	自定义元数据键值对
`default_environment`	string	否	默认运行环境

示例请求

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

示例响应

HTTP 200 OK

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

乐观并发控制（OCC）

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

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

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

错误码

HTTP	type	触发条件
400	`invalid_request_error`	请求体格式错误或字段值不合法
400	`invalid_request_error`	`skills` 数量超过 20 个上限
401	`authentication_error`	PAT 无效或过期
403	`permission_error`	无权限更新此 Agent
404	`not_found_error`	指定 ID 的 Agent 不存在
409	`conflict_error`	`version` 不匹配，存在并发冲突

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

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 99, got 1."
  }
}

注意事项

version 字段是必须的，不传会导致更新失败
每次成功更新后 version 自动递增
更新为部分更新（merge）语义：请求体中未传入的可选字段将保持原值不变，仅显式传入的字段会被更新
可通过列出 Agent 版本查看历史版本