Skip to main content
Agents

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.
This update publishes a new Agent version, but existing Sessions continue using their pinned runtime snapshots. To apply the Agent version's model, prompt, tool, MCP server, or Skill-binding changes to an existing Session, call Update a session with the corresponding agent fields.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
x-qoder-betaWhen using Browser UseMust include browser-use-2026-07-14 when replacing tools with an array containing browser_toolset_20260714. See Browser Use (Beta)

Path parameters

ParameterTypeRequiredDescription
agent_idstringYesAgent unique identifier

Request body

FieldTypeRequiredDescription
versionintegerYesCurrent version (OCC). Must match the server-side version.
namestringNoAgent name, 1-256 characters
modelstring | objectNoModel identifier. Pass a string or an Agent model object to configure effort or context_window. Use List models to discover available values
systemstringNoSystem prompt, at most 100000 characters
descriptionstringNoAgent description, at most 2048 characters
toolsarray of Agent toolNoReplaces the stored tool configuration list. Maximum 128 entries
mcp_serversarray of MCP serverNoReplaces the stored MCP server list. Maximum 20 entries. mcp_toolset entries in tools must reference names in this list
skillsarray of Skill bindingNoReplaces the stored skill binding list. Maximum 20 entries
metadataobjectNoMetadata patch. String values upsert keys; null values delete keys from stored metadata
multiagentMultiagent | nullNoReplaces the orchestration configuration. Omit to keep it unchanged or pass null to clear it. Ordinary Agent or self entries require agent_toolset_20260401 in tools; an Advisor-only roster does not. See Multiagent orchestration
When updating a child Agent reference, omitting version pins it to that Agent’s latest version at save time, even if the previous value was "latest". See child Agent version rules.

Example request

curl -X POST "https://api.qoder.com/api/v1/cloud/agents/agent_019eXXXX..." \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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 
{
  "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

FieldTypeDescription
typestringAlways "agent"
idstringAgent unique identifier with the agent_ prefix
namestringAgent name
descriptionstringAgent description
modelstring | objectModel identifier. See Agent model
systemstringSystem prompt
toolsarray of Agent toolTool configuration list
mcp_serversarray of MCP serverMCP server configuration
skillsarray of Skill bindingSkill bindings
metadataMetadata objectCustom metadata
multiagentMultiagent | nullMultiagent orchestration configuration, null when not set
versionintegerNew version after the update
archived_atstring|nullArchive time (ISO 8601), null when not archived
created_atstringCreation time (ISO 8601)
updated_atstringLast 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

HTTPTypeTrigger
400invalid_request_errorMalformed body or invalid field value
400invalid_request_errormodel.effort is not one of none, low, medium, high, xhigh, max
400invalid_request_errormodel.context_window is not a positive integer
400invalid_request_errormodel.speed was supplied; use model.effort instead
400invalid_request_errortools exceeds the maximum of 128 entries
400invalid_request_errormcp_servers exceeds the maximum of 20 entries
400invalid_request_errorskills exceeds the maximum of 20 entries
400invalid_request_errorInvalid multiagent configuration (including an invalid Advisor entry), or a roster with ordinary Agent / self entries lacks agent_toolset_20260401 in tools
400invalid_request_errorbrowser_toolset_20260714 is used without the Browser Use Beta header
401authentication_errorPAT or SAT invalid or expired
403permission_errorNot authorized to update this Agent
404not_found_errorAgent with the given ID does not exist
409conflict_errorversion mismatch (concurrent modification)
503feature_not_availableBrowser Use is temporarily unavailable
See Errors for the full error envelope.

Error response example

Version conflict (409): 
{
  "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.

Agent setup

Create a reusable, versioned agent configuration.
First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference
Update an agent - Qoder