> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # 更新 Agent > 更新指定 Agent 的配置，使用乐观并发控制（OCC）。 `POST /api/v1/cloud/agents/{agent_id}` 更新指定 Agent 的配置。使用乐观并发控制（OCC），需要在请求体中提供当前 `version` 值。 ## 请求头 | 头部 | 必选 | 说明 | | --------------- | -- | ------------------ | | `Authorization` | 是 | `Bearer ` | | `Content-Type` | 是 | `application/json` | ## 路径参数 | 参数 | 类型 | 必选 | 说明 | | ---------- | ------ | -- | ---------- | | `agent_id` | string | 是 | Agent 唯一标识 | ## 请求体 | 字段 | 类型 | 必选 | 说明 | | ------------- | --------------------------------------------------------------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `version` | integer | 是 | 当前版本号（OCC 校验），必须与服务端当前版本一致 | | `name` | string | 否 | Agent 名称，长度 1-256 字符 | | `model` | string \| object | 否 | 模型标识。可传 string 或 [Agent model](/zh/cloud-agents/api/agents/schemas#agent-model) 对象以同时配置 `effort` 或 `context_window`。可通过 [列出模型](/zh/cloud-agents/api/models/list) 查询可用值 | | `system` | string | 否 | 系统提示词，最长 100000 字符 | | `description` | string | 否 | Agent 描述，最长 2048 字符 | | `tools` | [Agent tool](/zh/cloud-agents/api/agents/schemas#agent-tool) 数组 | 否 | 替换已保存的工具配置列表，最多 128 个 | | `mcp_servers` | [MCP server](/zh/cloud-agents/api/agents/schemas#mcp-server) 数组 | 否 | 替换已保存的 MCP server 列表，最多 20 个。`tools` 中的 `mcp_toolset` 必须引用此列表里的名称 | | `skills` | [Skill binding](/zh/cloud-agents/api/agents/schemas#skill-binding) 数组 | 否 | 替换已保存的 Skill 绑定列表，最多 20 个 | | `metadata` | object | 否 | Metadata 补丁。字符串值用于新增或更新 key；`null` 值用于删除已保存 metadata 中的 key | ## 示例请求 ```bash theme={null} 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** ```json theme={null} { "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](/zh/cloud-agents/api/agents/schemas#agent-model) | | `system` | string | 系统提示词 | | `tools` | [Agent tool](/zh/cloud-agents/api/agents/schemas#agent-tool) 数组 | 工具配置列表 | | `mcp_servers` | [MCP server](/zh/cloud-agents/api/agents/schemas#mcp-server) 数组 | MCP 服务器配置 | | `skills` | [Skill binding](/zh/cloud-agents/api/agents/schemas#skill-binding) 数组 | Skill 绑定列表 | | `metadata` | [Metadata 对象](/zh/cloud-agents/api/conventions/schemas#metadata-对象) | 自定义元数据 | | `multiagent` | [Multiagent](/zh/cloud-agents/api/agents/schemas#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 个上限 | | 401 | `authentication_error` | PAT 无效或过期 | | 403 | `permission_error` | 无权限更新此 Agent | | 404 | `not_found_error` | 指定 ID 的 Agent 不存在 | | 409 | `conflict_error` | `version` 不匹配，存在并发冲突 | 版本冲突（409）错误响应示例： ```json theme={null} { "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 版本](/zh/cloud-agents/api/agents/list-versions) 查看历史版本 ## 相关 创建可复用、可版本化的 Agent 配置。