> ## 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. # Update an agent > Update an Agent configuration with optimistic concurrency control. `POST /api/v1/cloud/agents/{agent_id}` Updates the configuration of the specified Agent. Uses optimistic concurrency control (OCC); the request body must include the current `version`. ## Headers | Header | Required | Description | | --------------- | -------- | ------------------ | | `Authorization` | Yes | `Bearer ` | | `Content-Type` | Yes | `application/json` | ## Path parameters | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ----------------------- | | `agent_id` | string | Yes | Agent unique identifier | ## Request body | Field | Type | Required | Description | | ------------- | ------------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `version` | integer | Yes | Current version (OCC). Must match the server-side version. | | `name` | string | No | Agent name, 1-256 characters | | `model` | string \| object | No | Model identifier. Pass a string or an [Agent model](/cloud-agents/api/agents/schemas#agent-model) object to configure `effort` or `context_window`. Use [List models](/cloud-agents/api/models/list) to discover available values | | `system` | string | No | System prompt, at most 100000 characters | | `description` | string | No | Agent description, at most 2048 characters | | `tools` | array of [Agent tool](/cloud-agents/api/agents/schemas#agent-tool) | No | Replaces the stored tool configuration list. Maximum 128 entries | | `mcp_servers` | array of [MCP server](/cloud-agents/api/agents/schemas#mcp-server) | No | Replaces the stored MCP server list. Maximum 20 entries. `mcp_toolset` entries in `tools` must reference names in this list | | `skills` | array of [Skill binding](/cloud-agents/api/agents/schemas#skill-binding) | No | Replaces the stored skill binding list. Maximum 20 entries | | `metadata` | object | No | Metadata patch. String values upsert keys; `null` values delete keys from stored metadata | ## Example request ```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": "You are an updated documentation testing assistant.", "description": "Used for API documentation testing", "version": 1 }' ``` ## Example response **HTTP 200 OK** ```json theme={null} { "type": "agent", "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "name": "doc-test-agent-updated", "description": "Used for API documentation testing", "model": "ultimate", "system": "You are an updated documentation testing assistant.", "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" } ``` ## Response fields | Field | Type | Description | | ------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `type` | string | Always `"agent"` | | `id` | string | Agent unique identifier with the `agent_` prefix | | `name` | string | Agent name | | `description` | string | Agent description | | `model` | string \| object | Model identifier. See [Agent model](/cloud-agents/api/agents/schemas#agent-model) | | `system` | string | System prompt | | `tools` | array of [Agent tool](/cloud-agents/api/agents/schemas#agent-tool) | Tool configuration list | | `mcp_servers` | array of [MCP server](/cloud-agents/api/agents/schemas#mcp-server) | MCP server configuration | | `skills` | array of [Skill binding](/cloud-agents/api/agents/schemas#skill-binding) | Skill bindings | | `metadata` | [Metadata object](/cloud-agents/api/conventions/schemas#metadata-object) | Custom metadata | | `multiagent` | [Multiagent](/cloud-agents/api/agents/schemas#multiagent) \| null | Agents configuration, `null` when not set | | `version` | integer | New version after the update | | `archived_at` | string\|null | Archive time (ISO 8601), `null` when not archived | | `created_at` | string | Creation time (ISO 8601) | | `updated_at` | string | Last update time (ISO 8601) | ## Optimistic concurrency control (OCC) Updates use the version number for optimistic locking: 1. The client first calls `GET` to obtain the current `version`. 2. The update sends that `version` in the request body. 3. The server checks whether the supplied `version` matches the current value. 4. On match, the update succeeds and `version` increments by 1. 5. On mismatch, the server returns `409 Conflict`. This prevents concurrent updates from overwriting each other. ## Errors | HTTP | Type | Trigger | | ---- | ----------------------- | ---------------------------------------------------------------------------- | | 400 | `invalid_request_error` | Malformed body or invalid field value | | 400 | `invalid_request_error` | `model.effort` is not one of `none`, `low`, `medium`, `high`, `xhigh`, `max` | | 400 | `invalid_request_error` | `model.context_window` is not a positive integer | | 400 | `invalid_request_error` | `model.speed` was supplied; use `model.effort` instead | | 400 | `invalid_request_error` | `tools` exceeds the maximum of 128 entries | | 400 | `invalid_request_error` | `mcp_servers` exceeds the maximum of 20 entries | | 400 | `invalid_request_error` | `skills` exceeds the maximum of 20 entries | | 401 | `authentication_error` | PAT invalid or expired | | 403 | `permission_error` | Not authorized to update this Agent | | 404 | `not_found_error` | Agent with the given ID does not exist | | 409 | `conflict_error` | `version` mismatch (concurrent modification) | See [Errors](/cloud-agents/api/conventions/errors) for the full error envelope. ### Error response example **Version conflict (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." } } ``` ## Notes * `version` is required; omitting it causes the update to fail. * `version` increments on each successful update. * Updates use merge semantics: optional fields not included in the request body retain their current values. Only explicitly provided fields are updated. * When `tools`, `mcp_servers`, or `skills` is provided, the supplied array replaces the stored array for that field. * When `metadata` is provided, string values are merged into the stored metadata object and `null` values delete existing keys. * View the change history with `GET /api/v1/cloud/agents/{agent_id}/versions`. ## Related Create a reusable, versioned agent configuration.