Versioning & compatibility

The four version axes of an agent deployment, the compatibility matrix, the upgrade procedure, and where machine-readable schemas and docs are published.

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.5 (the schema of the runtime version these docs were generated for). The published compatibility matrix maps runtime to schema:

{
  "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 and JSON Schemas for conversation events and autonomous callbacks	docs/agent/json/<runtime-version>/ in the runtime repository
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), 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 per runtime release. 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.