Reference

Preview changes

Shows exactly what a change set would do, without writing anything: a structured diff (path, operation, before, after), problems such as unknown ids, what else is needed (scope, confirmation) and the validation of the result.

REST	`POST /api/v1/agents/{agent_id}/configuration/preview`
MCP tool	`preview_agent_changes`
Classification	Read (changes nothing)
Scope	`agents:read`
Minimum role on the agent	editor
Confirmation	Not needed
Retry safety	Safe to retry with the same input
Success status	200

What it does

Side effects

None. It only reads.

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.

Example

REST

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

MCP (POST /mcp)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "preview_agent_changes",
    "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"
            }
          ]
        }
      }
    }
  }
}

Response

Returns an object with revision, changes, problems, removes, needs and validation. This is a real response, shortened to two items per list.

200 response

{
  "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
      }
    }
  ],
  "problems": [],
  "removes": 0,
  "needs": [],
  "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:read`.
404	`agent_not_found`	Unknown agent, or not reachable with this token.
400	`bad_request`	An input is invalid; `field` names it.
429	`rate_limited`	Wait `Retry-After` seconds.