# 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:

```bash
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):

```json
{
  "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:

```json
{
  "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. |