> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent versioning and the change-log audit trail

> What an agent version is — the immutable snapshot of an agent's prompt, model, tools, and knowledge wiring — how it moves from draft to promoted, what gates the promote path, and how the change log derives a queryable audit row per revision from the same snapshot ledger.

# Agent versioning and the change-log audit trail

Every change to a production agent is versioned. A version is the immutable
snapshot experiments, canaries, regression replays, and rollbacks bind to; the
change log turns that snapshot ledger into a queryable "who changed which
field, when" row per revision. Together they are the audit spine behind every
promote: what was tested, what was promoted, and what each promotion changed.

This page defines the vocabulary the rest of the agent-governance surface
uses. For the endpoint reference, see [Agent versions](/agents/agent-versions);
for the governance gates, see
[Guardrail policies and red-team gates](/concepts/guardrails-and-red-team-pipeline).

## 1. What a version is

A version is an immutable snapshot of the agent's governed configuration,
captured at a point in time:

* `system_prompt`
* `model`, `temperature`, `max_tokens`
* `tools` and `knowledge_base_ids`
* `safety_config` and `config`
* `max_cost_per_conversation_cents`

Each version row carries a monotonically increasing `version_number` (unique
per agent), an optional operator-set `label` (a bookmark such as "before the
Black Friday tweak"), an optional `branch` naming the experiment line it
belongs to, and a `parent_version_id` recording what it forked or was restored
from. Because the snapshot is immutable, a version id is a stable pointer: the
candidate you scored is exactly the candidate you promoted, and the rollback
target is exactly the configuration that ran last quarter.

The dashboard lists an agent's versions under **Agents → \[agent] → Versions**
(the same list, newest first, plus the distinct branch names). The API surface
is `GET /agents/:id/versions` for the list, `POST /agents/:id/versions` to
mint a checkpoint from the agent's current state, and
`GET /agents/:id/versions/:vid/diff` to compare two versions or a version
against the live config. Two aliases exist for prompt-oriented integrations:
`GET /agents/:id/prompt-history` (same list) and
`POST /agents/:id/prompt-rollback/:vid` (same action as promote).

A version is also minted automatically whenever an agent save touches one of
the governed fields above, so manual checkpoints and automatic checkpoints
land in the same monotonic ledger.

## 2. The change log

The version ledger is append-only and forward-only, which makes it the source
of truth for "who changed which governed field, and when". The change log is
the queryable form of that ledger: one entry per revision, derived
deterministically by diffing each snapshot against its chronological
predecessor — never a separate table that could drift.

`GET /agents/:id/changelog` returns entries newest-first. Each entry carries:

* `version_id` and `version_number` — which revision this row describes
* `changed_by` — the operator who made the change (empty for automatic
  checkpoints such as the create-time baseline)
* `changed_at` — when the revision was committed
* `branch` and `label` — the experiment line and operator bookmark, when set
* `changed_fields` — the governed fields whose value moved relative to the
  previous revision; for the very first revision, the fields configured at
  creation
* `is_initial` — true only on that first revision

Two query parameters make the audit questions cheap: `field` narrows to
revisions that touched one governed field (for example, every change to the
`safety_config`), and `cursor` keyset-paginates on `version_number`.

## 3. Version lifecycle

A version moves through four stages, and the last one is reversible:

1. **Draft.** Mint a checkpoint with `POST /agents/:id/versions` (or branch a
   sibling line with `POST /agents/:id/versions/:vid/branch`). A branch is a
   history-only line — the live agent is untouched until you promote it, so an
   experiment line and production never share a pointer by accident.
2. **Candidate.** Point offline testing at the snapshot: regression replays,
   batch simulation, persona simulation, red-team runs, or a diff against the
   live config. Every testing harness resolves a saved version id — there is
   no "test whatever the agent currently holds" path.
3. **Promoted.** `POST /agents/:id/versions/:vid/promote` copies the snapshot
   onto the live agent and advances the agent's version counter. Until this
   call runs, live traffic keeps serving the previous promoted version; an
   experiment or canary binds its contact assignments to the candidate version
   id so a later promote does not retroactively change what an assignment saw.
4. **Superseded.** The next promote supersedes the current live snapshot.
   Because promote is forward-only, a rollback promotes an *older* snapshot:
   it mints a fresh version that copies the older values and records a
   `parent_version_id` pointing at the restore source. The audit timeline
   stays linear — "restored from v3" is itself a versioned, gated, audited
   event.

## 4. Promotion gates

The promote path runs up to three checks before it flips production traffic,
and each block is itself an audit entry:

* **Eval-regression gate.** When the agent has a pinned eval suite configured
  (`GET/PUT /agents/:id/promotion-gate/settings`), promote replays the golden
  sets against the candidate version first. A regression — or a set that could
  not run — refuses the promote with `PROMOTION_GATE_FAILED` (422) and returns
  the gate report. The gate fails closed.
* **Red-team safety gate.** When the agent has the pre-deploy safety gate
  configured (`GET/PUT /agents/:id/red-team/gate-settings`), promote replays
  the built-in adversarial pack against the candidate before going live. A
  safety regression against the pinned baseline, or a floor breach, refuses
  the promote with `RED_TEAM_GATE_FAILED` (422). See
  [Guardrail policies and red-team gates](/concepts/guardrails-and-red-team-pipeline)
  for how the gate composes with the policy library and token budgets.
* **Separation of duties.** When the organization enables the promotion
  approval policy (org setting), the operator who authored a version cannot
  promote it — a second reviewer must. A self-promotion attempt is refused
  with `PROMOTION_APPROVAL_REQUIRED` (403), and both the refusal and the
  successful approval land in the audit entries.

Experiments reach the same gates: the experiment console's
`POST /agents/:id/experiments/:expId/promote-winner` promotes the winning
variant's version id through the same checked promote path — see
[Agent prompt A/B experiments](/guides/agent-experiments-ab-prompts).

## 5. Rollback and drift

A rollback is a promote of an older version. Pick a prior snapshot, promote
it, and the live agent reverts while the ledger gains a fresh row marking the
restore — which means the rollback itself clears the same gates any forward
promotion must clear.

To see what you would be reverting to, compare before you promote:
`GET /agents/:id/versions/:vid/diff` answers "what differs" with a field-level
before/after for every governed field. Pass `against=prev` (the default) for
the immediately older version, `against=live` to compare a candidate against
production right now, or `against=<version id>` for an arbitrary pair. The
response lists every governed field with a `changed` flag, so an empty diff
("these two snapshots are identical") is distinguishable from a missing
comparison.

When a rollback is gated — for example a prompt-regression evaluator rejects
the target version as out of bounds — the promote registers but never applies;
see
[Prompt-regression rejects an agent-version rollback](/troubleshooting/agent-prompt-regression-registered)
for the resolution path. For a structured gate block on a forward promote, see
[Promotion gate blocked a version](/troubleshooting/agent-promotion-gate-blocks).

## 6. Worked example

One chain: checkpoint the current config, start an experiment on a candidate
branch, promote the winner, then read the change log back. Replace
`$AGENT_ID` and use your API key against `https://api.orbit.devotel.io/api/v1`.

```bash theme={null}
# 1) Checkpoint the current live config as a labeled version.
curl -X POST "$BASE/agents/$AGENT_ID/versions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "pre-experiment baseline"}'
# → { "data": { "id": "<version_a>", "version_number": 7, ... } }

# 2) Branch a candidate line from that checkpoint.
curl -X POST "$BASE/agents/$AGENT_ID/versions/<version_a>/branch" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch": "spring-refund-prompt", "note": "refund wording experiment"}'
# → { "data": { "id": "<version_b>", ... } }

# 3) Wire an experiment over the two versions, then promote the winner
#    through the checked promote path (see the experiments guide).
curl -X POST "$BASE/agents/$AGENT_ID/versions/<version_b>/promote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true, "note": "experiment winner"}'
# → 200 { "data": { "promoted_from_version_number": 8, "new_version": {...} } }
#   or 422 PROMOTION_GATE_FAILED / RED_TEAM_GATE_FAILED when a gate blocks.

# 4) Read the audit row for what just changed.
curl "$BASE/agents/$AGENT_ID/changelog?field=system_prompt" \
  -H "Authorization: Bearer $API_KEY"
# → one entry per revision that moved the prompt: who, when, which fields.
```

The dashboard renders the same chain: the Versions page lists every
checkpoint, the diff viewer compares a candidate against live before you
promote, and the change log shows each promotion as a fresh row.

## 7. See also

* [Agent versions (endpoint reference)](/agents/agent-versions) — the
  version-aware endpoints: canary, regression replay, persona simulation,
  shadow comparison.
* [Guardrail policies and red-team gates](/concepts/guardrails-and-red-team-pipeline)
  — the governance spine the promote-time gates compose.
* [Pick a testing harness](/concepts/agent-testing-harness-picker) — dry-run,
  batch-simulation, voice-simulation, soak-test, red-team, persona-simulation.
* [Agent prompt A/B experiments](/guides/agent-experiments-ab-prompts) — the
  experiment model that binds live traffic to candidate versions.
* [Canary rollout & shadow dispatch](/concepts/canary-and-shadow-rollout-model)
  — staged exposure behind a quality gate.
* [Troubleshooting: promotion gate blocked a version](/troubleshooting/agent-promotion-gate-blocks)
  and
  [prompt-regression rejects an agent-version rollback](/troubleshooting/agent-prompt-regression-registered).