Agent Config Versioning

Every time an agent config is created or updated via the API, a snapshot is automatically written to agent_config_versions. Versions are numbered sequentially starting at 1. You can list all versions, inspect any historical config, label versions for easy reference, and roll back to any previous version.

How snapshots work

Versioning is automatic — you don't need to opt in. Every POST /agents (create) and PUT /agents/:id (update) call writes a version snapshot as a fire-and-forget side effect. A snapshot failure does not block the create or update operation.

Field	Description
`version`	Auto-incrementing integer, unique per agent
`config`	Full JSONB snapshot of the agent config at that point in time
`label`	Optional human-readable tag (e.g. `production`, `pre-migration`)
`created_by`	UID of the user who triggered the change
`created_at`	Timestamp of the snapshot

API

Endpoint	Description
`GET /agents/:id/versions`	List all version summaries (newest first)
`GET /agents/:id/versions/:v`	Get the full config snapshot at version `v`
`PUT /agents/:id/versions/:v/label`	Set or clear the label on a version
`POST /agents/:id/rollback/:v`	Roll the live agent config back to version `v` (creates a new version snapshot)

Listing versions

bash

# List all versions of an agent config
curl "http://localhost:3000/agents/researcher/versions" \
  -H "Authorization: Bearer $TOKEN"

# Response:
# {
#   "versions": [
#     { "version": 3, "label": "production", "createdAt": "...", "createdBy": "uid_alice" },
#     { "version": 2, "label": null,          "createdAt": "...", "createdBy": "uid_alice" },
#     { "version": 1, "label": "initial",     "createdAt": "...", "createdBy": "uid_alice" }
#   ]
# }

Labeling a version

Labels are optional freeform strings. Use them to mark stable releases, pre-migration states, or experiment checkpoints:

bash

# Tag version 3 as "production" for easy reference
curl -X PUT "http://localhost:3000/agents/researcher/versions/3/label" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "label": "production" }'

Inspecting a historical config

bash

# Inspect what the config looked like at version 1
curl "http://localhost:3000/agents/researcher/versions/1" \
  -H "Authorization: Bearer $TOKEN"

Rolling back

Rolling back applies the historical config as the new live config and writes a new version snapshot. The version history is never deleted — rollback adds to it rather than truncating.

bash

# Roll back researcher to version 2
curl -X POST "http://localhost:3000/agents/researcher/rollback/2" \
  -H "Authorization: Bearer $TOKEN"

# Response: { "message": "Rolled back to version 2", "agent": { ... } }

ℹRolling back to version 2 creates version 4 (a copy of version 2). The history always moves forward — you can always roll back a rollback.

Common use cases

Safe model upgrades — label the current config as pre-upgrade, switch the model, and roll back if quality regresses.
System prompt A/B testing — snapshot before changing the system prompt, compare results, roll back if needed.
Audit trail — every change is attributed to a created_by UID with a timestamp, satisfying change-control requirements.