:Update an agent

Request headers

Header	Required	Description
Authorization	Yes	Bearer <PAT>
Content-Type	Yes	application/json

Path parameters

Parameter	Type	Required	Description
agent_id	string	Yes	Unique agent identifier.

Request body

Field	Type	Required	Description
version	integer	Yes	Current version number for OCC. Must match the server-side value.
name	string	No	Agent name, 1-256 characters.
model	string|object	No	Model identifier.
instructions	string	No	System prompt.
description	string	No	Agent description.
tools	array	No	Tool configuration list.
mcp_servers	array	No	MCP server configuration list.
skills	array	No	Skill bindings, in the form [{"type":"custom","skill_id":"[skill_id]"}]. Up to 20 entries.
metadata	object	No	Custom metadata key-value pairs.
default_environment	string	No	Default runtime environment.

Example request

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": "You are the updated documentation test assistant.",
    "description": "Used for API documentation testing.",
    "version": 1
  }'

Example response

HTTP 200 OK

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent-updated",
  "description": "Used for API documentation testing.",
  "model": "ultimate",
  "system": "You are the updated documentation test assistant.",
  "instructions": "You are the updated documentation test assistant.",
  "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"
}

Optimistic concurrency control (OCC)

Update requests use the version number for optimistic locking:

1. The client first calls GET to obtain the agent's current version.

2. The client sends the update with that version in the request body.

3. The server verifies that version matches the current server-side value.

4. If they match, the update succeeds and version is incremented by 1.

5. If they do not match, the server returns 409 Conflict.

This prevents concurrent clients from overwriting each other's changes to the same agent.

Errors

HTTP	Type	Trigger
400	invalid_request_error	Request body or field value is invalid.
400	invalid_request_error	skills exceeds the maximum of 20 entries.
401	authentication_error	PAT is invalid or has expired.
403	permission_error	Caller is not authorized to update this agent.
404	not_found_error	No agent exists with the given ID.
409	conflict_error	version does not match: concurrent modification.

Version conflict (409) response example:

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

For the full error envelope, see Errors.

Notes

• version is required; omitting it causes the update to fail.

• version is incremented on every successful update.

• Updates use partial-update (merge) semantics: optional fields not present in the request body keep their previous values, and only explicitly provided fields are updated.

• Use List Agent versions to view historical versions.