Reference

Change configuration

Applies a change set to the live configuration.

REST	`PATCH /api/v1/agents/{agent_id}/configuration`
MCP tool	`update_agent_configuration`
Classification	Sensitive write
Scope	`agents:write`
Minimum role on the agent	editor
Confirmation	Required: `confirm: true`, after the person agrees
Retry safety	Send an `Idempotency-Key` header (REST) or `idempotency_key` argument (MCP) to retry safely
Success status	200

What it does

Applies a change set to the live configuration. Send expected_revision from your last read to avoid overwriting someone else (version_conflict otherwise). An automatic version is saved first so the change can be rolled back with restore_version. Removing items needs the agents:delete scope and confirm: true. To stage changes for review instead, use create_draft.

Side effects

Saves an automatic version first, then changes the configuration. If the agent is published, visitors see the change at once. Removing items needs the agents:delete scope.

Inputs

Name	Type	Required	In	Description
`agent_id`	string	yes	path	The agent id (agt_...), from list_agents.
`changes`	object	yes	body	Changes by section. identity and personality take the fields to change. links, offers, knowledge and places take add (new items), update (items with id plus the fields to change) and remove (ids). Get ids and current values from get_agent_configuration; get the full schema from get_configuration_schema.
`expected_revision`	integer	no	body	The revision you read. Strongly recommended.
`confirm`	true	no	body	Set to true after reviewing the effect with the person you work for. Required for destructive operations.

Example

REST

curl -X PATCH "https://covo.lanaai.io/api/v1/agents/agt_4edc89bb2964/configuration" \
  -H "Authorization: Bearer $COVO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"changes":{"personality":{"tone":"Warm, direct and practical."},"links":{"add":[{"title":"Book a discovery call","url":"https://cal.example/avery","category":"booking"}]}},"expected_revision":4,"confirm":true}'

MCP (POST /mcp)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_agent_configuration",
    "arguments": {
      "agent_id": "agt_4edc89bb2964",
      "changes": {
        "personality": {
          "tone": "Warm, direct and practical."
        },
        "links": {
          "add": [
            {
              "title": "Book a discovery call",
              "url": "https://cal.example/avery",
              "category": "booking"
            }
          ]
        }
      },
      "expected_revision": 4,
      "confirm": true
    }
  }
}

Response

Returns an object with applied, revision, previous_revision, changes, backup_version and validation. This is a real response, shortened to two items per list.

200 response

{
  "applied": true,
  "revision": 6,
  "previous_revision": 4,
  "changes": [
    {
      "path": "personality.tone",
      "operation": "replace",
      "before": "warm",
      "after": "Warm, direct and practical."
    },
    {
      "path": "links",
      "operation": "add",
      "value": {
        "title": "Book a discovery call",
        "url": "https://cal.example/avery",
        "description": "",
        "icon": "",
        "image_url": null,
        "category": "booking",
        "enabled": true,
        "priority": 0,
        "tags": [],
        "keywords": [],
        "visibility": "public",
        "expires_at": null
      }
    }
  ],
  "backup_version": 1,
  "validation": {
    "valid": true,
    "state": "ready",
    "errors": [],
    "warnings": [
      {
        "step": "knowledge",
        "field": null,
        "severity": "recommended",
        "message": "Add a few common questions. Short, specific answers work best."
      },
      {
        "step": "publish",
        "field": null,
        "severity": "recommended",
        "message": "Ask the preview a question before you publish."
      }
    ]
  }
}

Over MCP the same object comes back as the tool result, in structuredContent and as JSON text.

Errors

Status	Code	Meaning
401	`unauthorized`	No token, or it is unknown, revoked or expired. OAuth apps refresh or reconnect.
403	`account_suspended`	The account that owns the token is paused.
403	`insufficient_scope`	The token lacks `agents:write`.
404	`agent_not_found`	Unknown agent, or not reachable with this token.
400	`bad_request`	An input is invalid; `field` names it.
409	`confirmation_required`	Review the effect with the person you work for, then send `confirm: true`.
409	`version_conflict`	The agent changed since you read it. Read again and redo the change.
409, 422	`idempotency_in_progress`, `idempotency_key_reused`	See Idempotency on the REST page.
429	`rate_limited`	Wait `Retry-After` seconds.