Agent versioning and rollback for Claude, ChatGPT, Grok

**Intro** If you maintain production AI agents built on Claude, ChatGPT, or Grok, uncontrolled model updates can break tooling, degrade response quality, or cause downtime. This guide shows a reproducible way to version prompts, snapshot full agent state, and roll back reliably.

How to implement agent versioning and rollback for Claude, ChatGPT, and Grok

Agent versioning is the practice of treating every change to prompts, tool definitions, and runtime state as an immutable snapshot. A rollback consists of loading a previous snapshot, re‑creating the SDK client with the recorded model identifier, and feeding the stored conversation history back to the API. The process works for Anthropic’s Claude, OpenAI’s ChatGPT, and xAI’s Grok without special vendor‑specific hacks.

Prerequisites

• Python ≥ 3.9
• `anthropic` 0.7+, `openai` 1.10+, `xai` 0.2+ (`pip install anthropic openai xai`)
• `sqlite3` (standard library)
• `git` installed and a repository that stores `prompts/`, `config/`, and `tools/` directories
• Optional GUI libraries: `tkinter` (bundled) or `PyQt6` (`pip install pyqt6`)

Core architecture & concepts

Prompt version control with Git

All prompt files (`system_prompt.txt`, `user_prompt.txt`) and tool definitions live in a Git‑tracked folder. A new commit represents a **prompt version**. The commit hash is stored alongside runtime metadata so the exact prompt can be reproduced.

Metadata store (SQLite)

A lightweight SQLite database (`agent_versions.db`) tracks each snapshot:

column	type	description
`id`	INTEGER	primary key
`git_hash`	TEXT	Git commit hash for prompts and tools
`model_name`	TEXT	exact model identifier (e.g., `claude-3-opus-20240229`)
`snapshot_path`	TEXT	file system path to the serialized state
`created_at`	TEXT	ISO‑8601 timestamp
`notes`	TEXT	optional human‑readable description

State snapshot (JSON + pickle)

Conversation turns and tool execution logs are first serialized to JSON for readability. Heavy Python objects (e.g., custom tool classes) are stored with `pickle` in a companion file. The two files together form a **full agent state** that can be re‑loaded even after a process restart.

# agent_state.py
import json, pickle, pathlib
from dataclasses import asdict, dataclass
from typing import List, Any

@dataclass
class Turn:
    role: str          # "user" or "assistant"
    content: str
    tools_used: List[str]

@dataclass
class AgentState:
    turns: List[Turn]
    tool_objects: List[Any]   # pickled custom tool instances

def dump_state(state: AgentState, base_path: pathlib.Path) -> None:
    # JSON for conversation, pickle for tool objects
    json_path = base_path / "conversation.json"
    pickle_path = base_path / "tools.pkl"
    json_path.write_text(json.dumps([asdict(t) for t in state.turns], indent=2))
    with pickle_path.open("wb") as f:
        pickle.dump(state.tool_objects, f)

def load_state(base_path: pathlib.Path) -> AgentState:
    json_path = base_path / "conversation.json"
    pickle_path = base_path / "tools.pkl"
    turns = [Turn(**t) for t in json.loads(json_path.read_text())]
    with pickle_path.open("rb") as f:
        tool_objects = pickle.load(f)
    return AgentState(turns=turns, tool_objects=tool_objects)

Recovery flow diagram

flowchart LR
    A[New code change] --> B[git commit prompts & tools]
    B --> C[Create SQLite entry]
    C --> D[Take state snapshot (JSON+pickle)]
    D --> E[Store snapshot path]
    E --> F[Deploy new agent]
    F --> G[Detect regression?]
    G -->|yes| H[Select prior version from DB]
    H --> I[Load snapshot & re‑init SDK]
    I --> J[Agent runs with historic state]

Step‑by‑step implementation

1. Initialize the SQLite catalog

# init_db.py
import sqlite3, pathlib

DB_PATH = pathlib.Path("agent_versions.db")

def init():
    conn = sqlite3.connect(DB_PATH)
    cur = conn.cursor()
    cur.execute(
        """
        CREATE TABLE IF NOT EXISTS versions (
            id INTEGER PRIMARY KEY,
            git_hash TEXT NOT NULL,
            model_name TEXT NOT NULL,
            snapshot_path TEXT NOT NULL,
            created_at TEXT NOT NULL,
            notes TEXT
        )
        """
    )
    conn.commit()
    conn.close()

if __name__ == "__main__":
    init()

Running `python init_db.py` creates the catalog.

2. Capture a new version after a change

# capture_version.py
import subprocess, datetime, sqlite3, pathlib
from agent_state import AgentState, dump_state

DB_PATH = pathlib.Path("agent_versions.db")
SNAP_ROOT = pathlib.Path("snapshots")
SNAP_ROOT.mkdir(exist_ok=True)

def current_git_hash() -> str:
    return subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()

def register_version(model_name: str, state: AgentState, notes: str = ""):
    git_hash = current_git_hash()
    timestamp = datetime.datetime.utcnow().isoformat()
    snap_dir = SNAP_ROOT / f"{timestamp}_{git_hash[:7]}"
    snap_dir.mkdir()
    dump_state(state, snap_dir)

    conn = sqlite3.connect(DB_PATH)
    cur = conn.cursor()
    cur.execute(
        """
        INSERT INTO versions (git_hash, model_name, snapshot_path, created_at, notes)
        VALUES (?,?,?,?,?)
        """,
        (git_hash, model_name, str(snap_dir), timestamp, notes),
    )
    conn.commit()
    conn.close()
    print(f"Version recorded: {git_hash}")

# Example usage
if __name__ == "__main__":
    dummy_state = AgentState(turns=[], tool_objects=[])
    register_version("claude-3-opus-20240229", dummy_state, "initial rollout")

The script records the exact Git commit, model identifier, and a directory containing the serialized state.

3. SDK‑specific agent factory

# agent_factory.py
import pathlib
from anthropic import Anthropic
from openai import OpenAI
from xai import XAI
from agent_state import load_state

def create_claude_client(model_name: str) -> Anthropic:
    return Anthropic(api_key="YOUR_ANTHROPIC_KEY")

def create_chatgpt_client(model_name: str) -> OpenAI:
    return OpenAI(api_key="YOUR_OPENAI_KEY")

def create_grok_client(model_name: str) -> XAI:
    return XAI(api_key="YOUR_XAI_KEY")

def restore_agent(version_id: int):
    import sqlite3
    DB_PATH = pathlib.Path("agent_versions.db")
    conn = sqlite3.connect(DB_PATH)
    cur = conn.cursor()
    cur.execute("SELECT model_name, snapshot_path FROM versions WHERE id=?", (version_id,))
    row = cur.fetchone()
    conn.close()
    if not row:
        raise ValueError(f"No version with id={version_id}")

    model_name, snap_path = row
    state = load_state(pathlib.Path(snap_path))

    if model_name.startswith("claude"):
        client = create_claude_client(model_name)
    elif model_name.startswith("gpt-"):
        client = create_chatgpt_client(model_name)
    elif model_name.startswith("grok"):
        client = create_grok_client(model_name)
    else:
        raise RuntimeError(f"Unsupported model prefix in {model_name}")

    return client, state

Calling `restore_agent(3)` loads the third stored snapshot, re‑creates the appropriate SDK client, and returns the saved conversation history.

4. Simple rollback dashboard (Tkinter)

# rollback_gui.py
import tkinter as tk, sqlite3, pathlib
from agent_factory import restore_agent

DB_PATH = pathlib.Path("agent_versions.db")

def fetch_versions():
    conn = sqlite3.connect(DB_PATH)
    cur = conn.cursor()
    cur.execute("SELECT id, model_name, created_at, notes FROM versions ORDER BY id DESC")
    rows = cur.fetchall()
    conn.close()
    return rows

def on_revert():
    sel = listbox.curselection()
    if not sel:
        status["text"] = "Select a version first"
        return
    vid = int(listbox.get(sel[0]).split("|")[0].strip())
    try:
        client, state = restore_agent(vid)
        status["text"] = f"Reverted to version {vid} using {client.__class__.__name__}"
    except Exception as e:
        status["text"] = f"Rollback failed: {e}"

root = tk.Tk()
root.title("AI Agent Rollback")

listbox = tk.Listbox(root, width=80)
for row in fetch_versions():
    vid, model, ts, notes = row
    listbox.insert(tk.END, f"{vid} | {model} | {ts} | {notes}")
listbox.pack(padx=10, pady=5)

btn = tk.Button(root, text="Revert to selected version", command=on_revert)
btn.pack(pady=5)

status = tk.Label(root, text="", fg="red")
status.pack(pady=5)

root.mainloop()

The GUI lists all recorded snapshots, shows notes, and on button press calls `restore_agent`. Non‑technical ops staff can trigger rollbacks without touching the command line.

*(If you prefer a web UI, replace Tkinter with Streamlit – see the internal link “building a tkinter interface”.)*

5. Claude‑specific handling of tool schema changes

Claude’s `Computer` tool schema evolved between `claude-3-sonnet-20240229` and `claude-3-opus-20240229`. When restoring a snapshot that references the older schema, the API will reject the tool definition. To mitigate:

1. Store the **tool schema version** together with the snapshot (column `tool_schema` in SQLite).
2. At restore time, check the target model’s supported schema via the Anthropic `/v1/models` endpoint.
3. If the snapshot’s schema is newer than the model supports, either (a) downgrade the stored schema (remove unsupported fields) or (b) abort and suggest a fallback model.

def compatible_tool_schema(model_name: str, schema_version: int) -> bool:
    client = create_claude_client(model_name)
    info = client.models.retrieve(model_name)
    supported = info.get("tool_schema_version", 1)
    return schema_version <= supported

6. ChatGPT rollback strategy

OpenAI allows switching between `gpt-4-1106-preview` and `gpt-3.5-turbo-0125` instantly. However, function‑calling definitions are attached to the model request payload. Store the **function schema JSON** alongside the snapshot. When rolling back, pass that JSON verbatim:

def chatgpt_completion(client: OpenAI, state, function_schema):
    messages = [{"role": t.role, "content": t.content} for t in state.turns]
    response = client.chat.completions.create(
        model="gpt-3.5-turbo-0125",
        messages=messages,
        tools=function_schema,
        tool_choice="auto",
    )
    return response

If the function schema uses a field removed in the target model (e.g., `type: “function”` vs. `type: “function_call”`), adjust or abort.

7. Grok state management via xAI API

Grok’s API does not expose a `tools` field, but you can embed custom tool calls in the `messages` array. Capture the exact message list in the JSON snapshot. When restoring, simply resend the stored list; the model will replay the same tool invocations.

def grok_completion(client: XAI, state):
    msgs = [{"role": t.role, "content": t.content} for t in state.turns]
    return client.chat.completions.create(model="grok-2", messages=msgs)

Because Grok’s model name can be retired, always record the full version string (e.g., `grok-2-20241015`). If the API reports the version as unavailable, fall back to the next‑closest tag or discuss migration.

8. Testing rollback before production

1. **Sandbox clone**: Duplicate the SQLite DB and the `snapshots/` folder into a temporary directory. Run the GUI or CLI against this copy.
2. **Inject a bad update**: Change a system prompt, commit, and register a new version. Then deliberately break the tool schema (remove a required field).
3. **Execute rollback**: Verify that the GUI reports incompatibility and that the fallback logic restores the prior good version.
4. **Validate integrity**: After restoration, compare `len(state.turns)` and a hash of the pickle file against the recorded values to ensure no corruption.

Trade‑offs & when not to use this

Aspect	Lightweight SQLite + JSON	Full state dump with pickle
Storage overhead	Small (metadata only)	Larger (binary tool objects)
Simplicity	Easy to query, low maintenance	Requires version‑compatible class code
True rollback fidelity	Limited to prompts & config	Includes in‑memory variables, tool state
Performance on restore	Fast (just DB lookup)	Slightly slower (deserialize pickle)

**When not to use** If your agent is stateless (no tool objects, no long conversation) you can skip the pickle step and rely solely on Git + SQLite. For massive conversation histories that exceed the target model’s context window, consider truncating older turns before snapshotting; otherwise restore will fail with a context overflow error.

Common errors and fixes

Error: `sqlite3.IntegrityError: UNIQUE constraint failed: versions.id`

**Cause**: Manual insertion without auto‑increment. **Fix**: Omit the `id` column in the `INSERT` statement; let SQLite assign it.

cur.execute(
    "INSERT INTO versions (git_hash, model_name, snapshot_path, created_at, notes) VALUES (?,?,?,?,?)",
    (git_hash, model_name, str(snap_dir), timestamp, notes),
)

Error: `pickle.UnpicklingError: invalid load key, ‘\x00’.`

**Cause**: The pickle file was corrupted (partial write or moved). **Fix**: Write the pickle atomically by first saving to a temp file then renaming.

tmp_path = pickle_path.with_suffix(".tmp")
with tmp_path.open("wb") as f:
    pickle.dump(state.tool_objects, f)
tmp_path.replace(pickle_path)

Error: `anthropic.exceptions.APIError: Tool schema version mismatch`

**Cause**: Restoring a snapshot that uses a newer tool schema than the selected Claude model supports. **Fix**: Use the `compatible_tool_schema` helper to validate before calling the API. If incompatible, either downgrade the schema fields or choose a newer model that supports them.

Error: `openai.BadRequestError: This model’s context length is 8192 tokens, but 10500 tokens were provided.`

**Cause**: Restored conversation exceeds the target model’s context window. **Fix**: Trim the oldest turns until the token count fits. The OpenAI Python library provides `tiktoken` for token counting.

import tiktoken
enc = tiktoken.encoding_for_model("gpt-3.5-turbo-0125")
def trim_to_window(state, max_tokens=8000):
    while enc.encode("\n".join(t.content for t in state.turns)) > max_tokens:
        state.turns.pop(0)
    return state

Frequently asked questions