Skip to main content

​
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; for the governance gates, see Guardrail policies and red-team gates.

​
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 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.

​
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 for the resolution path. For a structured gate block on a forward promote, see Promotion gate blocked a version.

​
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.
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