176 lines
3.5 KiB
Markdown
176 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```text
|
|
Active → Deprecated → Retired
|
|
```
|
|
|
|
Período recommended:
|
|
|
|
```text
|
|
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.
|