Skip to content

Version an AI system's behavior

An AI system's behavior doesn't live in one file. It's the sum of a model, the prompts that drive it, the tools it can call, its memory and retrieval config, and its guardrails — and any one of those can change without a single line of application code moving. Behavioral versioning captures that whole surface as a snapshot you can diff and roll back independently of code.

Built and default-on — optional and additive

tovio behavioral is part of the optional, additive semantic layer, which is built and on by default — the commands below work today. It builds on the agent provenance TOVIO already records, and it never blocks a core operation.

The problem it solves

You ship a code change that touches nothing about your agent's logic — but you also swapped the model version and tweaked the system prompt. A week later behavior drifts. A text diff of your repo shows the code change and misses the two that actually mattered. Behavioral versioning gives those changes a first-class home:

  • A snapshot records the full behavioral surface at a point in time.
  • A diff shows exactly which parts of the surface moved between two commits — and rates the risk.
  • A rollback restores a known-good behavioral surface without touching your code.

What a snapshot captures

A behavioral snapshot is a content-addressed object — the same kind of object as a commit — recording the surface that determines how the system behaves:

Field What it pins
model_id_hash The model identifier you pass (e.g. anthropic:claude-opus-4-8), by content hash
prompt_template_hash The prompt template surface, by content hash
tool_manifest_hash The set of tools the agent may call, and their schemas
memory_config_hash The memory configuration
retrieval_config_hash The retrieval configuration
policy_version The guardrail/policy version label, recorded verbatim
commit The implementing commit, so behavior and code stay tied

Because it's hashes, not copies, a snapshot is small, tamper-evident, and syncs like any other object. Every descriptor is optional — an omitted one hashes the empty string — so a partial snapshot is well-defined and reproducible.

When a provider publishes no version hash

TOVIO hashes whatever model identifier you give it. Pass the most specific identifier the provider exposes — a pinned version or a version-hash suffix rather than a friendly alias — and the snapshot is exactly as precise as that identifier.

Take a snapshot

Each descriptor is either a literal string or a path — if the value names a readable file, its contents are hashed; otherwise the string itself is. The snapshot links to HEAD:

$ tovio behavioral snapshot \
    --model-id anthropic:claude-opus-4-8 \
    --prompts prompts/system.md \
    --tools tools/manifest.json \
    --memory config/memory.toml \
    --policy-version v4
✓ Recorded behavioral snapshot blake3:9c02f1e4a6…
  linked to commit blake3:7b3da9c051… (code unchanged)

The snapshot is now a versioned object in your history: HEAD is re-sealed with a behavioral_snapshot pointer, and its tree, parents, message, and change ID are untouched. Re-sealing does mint a new commit address and advance the lane to it, so push a repository you share before or after — the code is identical either way, but the tip moved. You can take one before a risky change and another after, or on a schedule — each is a point you can diff against or return to. tovio behavioral list shows every snapshot across reachable history, newest first.

Diff two snapshots

This is where the value lands. A behavioral diff compares the surfaces linked to two commits, names the fields that moved, and carries a risk assessment — not every change is equal, and the diff says which ones to look at twice:

$ tovio behavioral diff 3f9c1a2b 7b3da9c0
Behavioral fields changed: model, tools
Risk: high — model or policy changed; re-run safety and acceptance evaluations before rollout

The risk level is deterministic: a model or policy change is high (it can move the whole decision boundary); a tools, memory, or retrieval change is medium (available actions or context changed); a prompt-only change is low; nothing changed is none. A commit with no snapshot on either side is reported as unrecorded and rated high rather than silently optimistic. Read the note as guidance, not alarm — but a model swap or a change to which tools an agent can call is the kind of thing worth a fresh eval run.

Machine-readable diff

The diff honors the standard --json contract — decoration-free, stable, the surface CI gates and agents read:

$ tovio behavioral diff 3f9c1a2b 7b3da9c0 --json

{
  "a": "blake3:3f9c1a2b7d4e6f0182a35c9b7e04d1f6a83c25be9701df4368ac52e1b0947dca",
  "b": "blake3:7b3da9c051f28e6b40cd93a7182f5e0cb64d31af09e7256bd8143fc60ba9e572",
  "a_recorded": true,
  "b_recorded": true,
  "changed": ["model", "tools"],
  "risk": {
    "level": "high",
    "note": "model or policy changed; re-run safety and acceptance evaluations before rollout"
  }
}

The machine contract carries no warmth

--json carries the structured risk field and nothing decorative — no glyphs, no color — so a CI gate parses exactly the same bytes every time.

Roll back behavior without touching code

If new behavior misbehaves, restore the surface recorded on a known-good commit. The rollback records a new snapshot equal to that commit's — model, prompts, tools, memory, retrieval, policy version — and links it to HEAD, leaving your code exactly where it is:

$ tovio behavioral rollback 3f9c1a2b
✓ Rolled the behavioral surface back to blake3:3f9c1a2b7d…
  recorded snapshot blake3:51ab8e2df0… linked to commit blake3:c04d17f9b2… (code unchanged)

A target commit that carries no snapshot is refused with TVO-SEM-006 rather than guessed at. Like every mutation in TOVIO, a snapshot or rollback goes on the local op-log, so tovio undo puts the lane back where it was. You can move between behavioral versions as freely as you move between lanes, with nothing lost either way.

Pin behavior to the commit that needs it

Because a snapshot links to its implementing commit, you can answer "what behavior was live when we shipped this change?" months later — and roll back to exactly that surface if a regression traces to it.

How this fits the agent control plane

Behavioral versioning builds directly on the provenance TOVIO already records for every agent operation — model hash, task, and authorizing identity. Snapshots give that provenance a versioned, diffable home, so the question shifts from "what did this agent do?" to "what was this agent, exactly, and how has it changed?" For the day-to-day of running agents, see the agents guide.

Where to go next

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure