Skip to content

Chapter 7.2 — Versioning

🎯 Objective

Version everything that can affect behavior in production. In AI, that is more than code — and most "mysterious" incidents come from one of these items not being versioned.

🧠 Items to version

  • Models (weights + tokenizer + config).
  • Prompts (system + templates).
  • Tools (interface + behavior).
  • Output schemas.
  • MCP servers (version + declared capabilities).
  • A2A Agent Cards.
  • Datasets (training + eval + golden + adversarial).
  • Embeddings (model + dimension).
  • RAG indexes (embedding version + pipeline version).
  • Policy bundles.
  • Memory (schema + data version).

📐 Patterns

  • Semver for tools, MCP servers, schemas and policy bundles.
  • Immutable version + moving alias (@stable, @canary, @experimental) for models and prompts.
  • A version tag in each execution's metadata (tracing). Without it, "was this agent run with prompt v1 or v2?" is an unanswerable question.
  • Explicit compatibility between components: this agent works with tool v1.x and v2.x; with v3, it requires migration.

🧠 Interface vs behavior

An honest problem: two components can have the same interface (schema) and different behavior (e.g., a new search tool that prioritizes a different ranking). API semver does not capture this.

Mitigation:

  • Treat a behavior change as a breaking change whenever it affects the observable metric (recall, citation coverage, error rate). Version and communicate it as such.
  • Keep a comparative eval between versions before promotion.