agent_framework_oci/specs/en/SPEC-013-Versioning-and-Compatibility-Model.md

SPEC-013 — Versioning and Compatibility Model

Agent Platform OCI

Version: 1.0.0

---

Reading guide

each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.

The document structure is:

1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.

---

1. Concept

Versionamento Defines como The platform evolui without quebrar projetos existing. compatibility Defines quais versions of framework, runtime, gateways, contracts, templates, prompts, tools and evaluator can operar juntas.

2. Problem addressed

without Model of versionamento:

• a change em GatewayRequest quebra canais;
• a change em MCP tool quebra Agents;
• a prompt alterado muda comportamento without rastreabilidade;
• evaluator muda score without History;
• templates ficam incompatíveis with runtime;
• Production Uses imagem latest without control.

3. Semantic Versioning

Formato:

MAJOR.MINOR.PATCH

Rules:

Parte	Significado
MAJOR	change incompatível.
MINOR	new Capacity compatível.
PATCH	Correction without change of Contract.

4. artifacts versionados

Artefato	Model
agent_framework	SemVer
agent_runtime	SemVer alinhado ao framework
agent_gateway	SemVer + Docker tag
channel_gateway	SemVer + Docker tag
ai_gateway	SemVer + Docker tag
mcp_gateway	SemVer + Docker tag
templates	Version of the plataforma
contracts	contract-name-vN
prompts	SemVer
datasets	SemVer
guardrails	SemVer por código
judges	SemVer por judge
mcp_tools	SemVer por tool
evaluator	SemVer
certification_suite	SemVer + ruleset version

5. Contract versioning

Examples:

gateway-request-v1
business-context-v1
tool-invocation-v1
llm-request-v1

allowed na mesma Version major:

• adicionar fields optional;
• adicionar metadata;
• adicionar enum documentado.

No allowed:

• remover field Required;
• mudar tipo;
• mudar significado;
• alterar regra obrigatória.

6. Compatibility Matrix

compatibility:
  - framework: "1.4.x"
    runtime: "1.4.x"
    agent_gateway: "1.4.x"
    supported: true
  - framework: "1.4.x"
    runtime: "2.0.x"
    supported: false

7. Policy of depreciação

Ciclo:

Active → Deprecated → Retired

Período recommended:

12 meses

8. Policy of migração

changes major exigem:

• migration guide;
• compatibility matrix;
• rollback strategy;
• certification;
• evaluator;
• release notes.

9. Estratégia of rollback

Rollback must considerar:

• imagem Docker;
• Version of the pacote;
• Version of the YAMLs;
• Version of the Contract;
• migration of banco;
• dataset;
• prompts.

10. Common errors

Error	Impact	Correction
use latest em Production	Deploy No reprodutível.	use tag explícita.
Mudar prompt without Version	without rastreabilidade.	Versionar prompt.
Adicionar field Required em Contract v1	Quebra clientes.	create v2.
Atualizar evaluator without baseline	Scores No comparáveis.	Registrar Version and metodologia.

11. Acceptance criteria

• all os Components têm Version.
• contracts têm Version independente.
• Matriz of compatibility publicada.
• Release notes publicadas.
• Migrações major possuem guide.
• Rollback definido.
• Prompts and datasets versionados.
• Evaluator and certification registram Version.