Capítulo 7.2 — Versionamento

🎯 Objetivo

Versionar tudo o que pode afetar comportamento em produção. Em IA, isso é mais do que código - e a maior parte dos incidentes "misteriosos" vem de algum desses itens não versionado.

🧠 Itens a versionar

• Modelos (pesos + tokenizer + config).
• Prompts (system + templates).
• Tools (interface + comportamento).
• Schemas de saída.
• MCP servers (versão + capabilities declaradas).
• A2A Agent Cards.
• Datasets (treino + eval + golden + adversarial).
• Embeddings (modelo + dimensão).
• Índices RAG (versão de embedding + versão de pipeline).
• Policy bundles.
• Memória (schema + data version).

📐 Padrões

• Semver para tools, MCP servers, schemas e policy bundles.
• Versão imutável + alias móvel (@stable, @canary, @experimental) para modelos e prompts.
• Tag de versão na metadata de cada execução (tracing). Sem isso, "esse agente já foi rodado com prompt v1 ou v2?" é pergunta sem resposta.
• Compatibilidade explícita entre componentes: este agente funciona com tool v1.x e v2.x; com v3, requer migração.

🧠 Interface vs comportamento

Um problema honesto: dois componentes podem ter mesma interface (schema) e comportamento diferente (ex.: tool nova de busca que prioriza outro ranking). Semver da API não captura isso.

Mitigação:

• Tratar mudança de comportamento como breaking change sempre que afetar a métrica observável (recall, citation coverage, rate de erro). Versione e comunique como tal.
• Manter eval comparativo entre versões antes da promoção.

---