> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/operations/versioning.md).

# Versioning & compatibility

> **Context** — An agent deployment has four independently versioned layers. This page defines them, explains how compatibility between them is published, and gives the upgrade procedure.

## The four version axes

| Axis                  | Example                   | Who controls it                      | Changes when                                            |
| --------------------- | ------------------------- | ------------------------------------ | ------------------------------------------------------- |
| **Runtime**           | `0.7.x`                   | The platform                         | The platform upgrades the agent runtime                 |
| **Manifest schema**   | `5.0.0`                   | Implicit — determined by the runtime | The manifest format itself evolves                      |
| **Manifest revision** | `version: "12"`           | You — manifest top-level `version`   | You change the agent's configuration                    |
| **Content versions**  | `book-a-car` `version: 9` | You — each `context.*` reference pin | You publish new routine/policy/prompt/glossary versions |

Key properties:

* **You own the bottom two axes; the platform owns the runtime.** You pin content versions and stamp a manifest revision; the platform runs and upgrades the runtime, and the runtime determines which manifest schema applies.
* **Content pins are exact.** Publishing version 10 of a routine changes nothing until a manifest pinning `version: 10` is deployed. This makes content rollout deliberate and rollback trivial (redeploy the previous manifest).
* **The manifest `version` label is yours** — a free-form revision marker surfaced in logs and traces so you can correlate behaviour with config releases.

## The compatibility matrix

Each runtime version validates manifests against one manifest-schema version — the manifest and content document shapes **differ across schema versions**, so an example written for one schema may be invalid under another. All examples in this documentation set follow **manifest schema 6.1.1** (the schema of the runtime version these docs were generated for). The published **compatibility matrix** maps runtime to schema:

```json
{
  "0.6.4": "4.0.0",
  "0.6.3": "4.0.0",
  "0.5.1": "3.0.0",
  "0.4.2": "2.1.0"
}
```

It is published at a stable location alongside the schemas (ask your platform operator for the bucket; the canonical object is `compatibility-matrix.json` at the bucket root) and rendered in the schema reference docs. When the platform moves your agent to a new runtime version, check whether the schema version changes — same schema version means your manifest is valid as-is.

## Machine-readable artifacts

Per published version, these artifacts exist for tooling and AI agents:

| Artifact                        | Contents                                                                                                                                                   | Location pattern                                |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| Manifest & content JSON Schemas | `agent-manifest`, `agent-config`, `routines`, `policies`, `glossaries`, `macros`, `variables` — Draft 2020-12, including cross-field rules                 | `<schemas bucket>/<schema-version>/<name>.json` |
| Agent API artifacts             | OpenAPI spec for the agent's HTTP surface, JSON Schemas for conversation events and autonomous callbacks, `llms-full.md` (this documentation, single file) | `<schemas bucket>/agent/<runtime-version>/`     |
| Compatibility matrix            | runtime → schema-version map                                                                                                                               | `<schemas bucket>/compatibility-matrix.json`    |

Validate manifests in CI with any JSON Schema library against the matching schema version — the same validation the platform applies on upload.

## Upgrade procedures

### Content release (most frequent)

1. Publish new content versions to the platform catalog.
2. Bump the pins in the manifest; bump the manifest `version` label.
3. Deploy the manifest. The platform validates it, warms the evaluation cache for the changed items (see [Startup evaluation](/agents/concepts/startup-evaluation.md#caching-cold-vs-warm-boots)), and rolls the agent.
4. Verify via traces — the per-turn config snapshot shows the new versions live.

**Rollback:** redeploy the previous manifest. Content versions are immutable in the catalog, so rollback is exact.

### Runtime upgrade

The platform performs runtime upgrades; your job is to keep your manifest compatible across the schema boundary:

1. Read the matrix: does the new runtime require a new manifest-schema version?
   * **Same schema** → nothing to do; your manifest is valid as-is.
   * **New schema** → validate your manifest against the new JSON Schema and adjust any changed fields, so it's ready when the upgrade lands.
2. If your platform offers a staging environment, deploy your manifest there against the new runtime first — it applies cleanly or fails loudly with every violation listed.
3. With Postgres session storage, in-flight conversations survive the platform's rollout.

**Rollback:** runtime rollback is platform-side; from your side, the matching manifest revision is what pairs with each runtime.

### Documentation versioning

These docs are regenerated and published per runtime release; the `llms-full.md` artifact in the per-version bucket path is the exact corpus for the version you run. Reference pages marked `generated: true` are produced from the runtime's source of truth and cannot drift from it.

## Pinning discipline (recommendations)

* Pin exact content versions in the manifest and stamp a manifest revision — never float references.
* Keep your content changes and a platform runtime upgrade on separate deploys where you can, so behaviour changes attribute cleanly to one axis.
* Keep manifests in version control even though the platform stores them; the diff history of pins is your behaviour-change ledger, and traces carry the manifest `version` label to join against it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.interactive.ai/agents/operations/versioning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.