first commit

README.md

@@ -1,179 +1,786 @@
-# CI/CD para Artefatos de Configuração no NeMo Guardrails
+# CI/CD para Agentes de IA com NeMo Guardrails como Package Python no Azure DevOps e Deploy em OCI OKE
 
-## Introdução
+## 1. Introdução
 
-Em projetos que utilizam **NeMo Guardrails**, os principais artefatos não são apenas código, mas sim **configurações declarativas** que controlam o comportamento do LLM.
+Este documento apresenta uma estratégia de CI/CD para projetos de **Agentes de IA** que consomem uma arquitetura compartilhada de **guardrails baseada em NeMo Guardrails**.
 
-Isso muda completamente a abordagem de CI/CD.
+A referência técnica e conceitual deste material é o projeto:
+
+> [Tutorial: NeMo Guardrails com Python, Proxy OpenAI-Compatible e Tracing
+](https://github.com/hoshikawa2/nemo_guardrails_configuration)
+
+A decisão arquitetural considerada neste documento é:
+
+> O projeto NeMo Guardrails **não será implantado como um serviço/server separado**.  
+> Ele será empacotado como uma **biblioteca Python versionada**, publicada por um pipeline próprio, e instalada pelos projetos de Agente de IA durante o build da imagem Docker.
+
+Essa decisão reduz a complexidade operacional, preserva a cadência de desenvolvimento dos times de agentes e mantém a governança dos artefatos de guardrails por meio de versionamento, testes e controle de publicação no pipeline do projeto NeMo.
 
 ---
 
-## Tipos de Artefatos no NeMo
+## 2. Visão geral da arquitetura
 
-### 1. Configurações principais
-- `config.yml` / `rails.yaml`
-- `guardrails.yaml`
-- `prompts/`
-- `flows.co`
-- `input.co`
-- `output.co`
+### 2.1 Fluxo funcional dos guardrails
 
-### 2. Código complementar
-- Actions Python (`actions.py`)
-- Integrações externas (APIs, tools)
-
----
-
-## Problema Principal
-
-Diferente de código tradicional:
-
-- Pequenas mudanças em `.co` ou `.yaml` podem quebrar o comportamento
-- Não há erro de compilação
-- Falhas são **semânticas**, não sintáticas
-
----
-
-## Pipeline CI/CD Recomendado
-
-### Etapa 1: Validação Sintática
-
-Validar YAML e estrutura:
-
-```bash
-yamllint .
+```text
+User Input
+  ↓
+Input Rails
+  ├─ Regex: PII Masking
+  ├─ LLM: Toxicidade
+  └─ LLM: Out-of-Scope
+  ↓
+LLM principal via NeMo Guardrails
+  ↓
+Output Rails
+  ├─ Compliance Anatel
+  ├─ Verbalização Prematura
+  └─ Groundedness
+  ↓
+Python Rules
+  ├─ Alçada de Ajuste
+  └─ Consistência Histórica
+  ↓
+Execução de API / Backend
+  ↓
+Supervisor VAS Avulso
+  ↓
+Curadoria / Métricas
+  ├─ TCR
+  ├─ Fallback
+  ├─ Tokens
+  ├─ Tamanho de mensagem
+  └─ Eficiência RAG
+  ↓
+Resposta final
 ```
 
-Validar carregamento:
+Esse fluxo representa a função do projeto NeMo dentro da arquitetura: ele atua como uma **camada de segurança, validação, controle de resposta, curadoria e métricas** para agentes de IA.
+
+---
+
+## 3. Decisão arquitetural: NeMo como package, não como serviço
+
+### 3.1 Modelo descartado: NeMo como serviço central
+
+Uma alternativa seria implantar o projeto NeMo como um serviço separado:
+
+```text
+Agente de IA
+  ↓ HTTP
+Serviço NeMo Guardrails
+  ↓
+LLM / Tools / Backend
+```
+
+Esse modelo centralizaria o runtime dos guardrails, mas traria custos e impactos:
+
+- necessidade de manter um serviço adicional;
+- aumento de latência;
+- criação de dependência runtime entre agente e serviço de guardrails;
+- maior complexidade de deploy;
+- possível gargalo de aprovação e governança;
+- risco de interromper a cadência dos times de desenvolvimento.
+
+### 3.2 Modelo adotado: NeMo como biblioteca versionada
+
+```text
+Pipeline NeMo
+  ↓
+gera package Python versionado
+  ↓
+publica em um feed privado
+  ↓
+Pipeline Agente
+  ↓
+pip install company-nemo-guardrails==x.y.z
+  ↓
+build da imagem final do agente
+  ↓
+deploy no OCI OKE
+```
+
+No runtime, o Pod terá **um único container**, contendo:
+
+```text
+Pod Kubernetes
+ └── Container do Agente
+       ├── código do agente de IA
+       ├── package NeMo Guardrails instalado
+       ├── configs de guardrails
+       ├── actions
+       ├── deterministic rails
+       └── llm rails
+```
+
+Portanto, o deploy no OKE é sempre da **imagem final do agente**, e não de uma imagem separada do NeMo.
+
+---
+
+## 4. Separação de responsabilidades
+
+### 4.1 Projeto NeMo Guardrails
+
+O projeto NeMo é responsável por:
+
+- manter os artefatos de guardrails;
+- implementar rails determinísticos;
+- implementar rails baseados em LLM;
+- registrar actions;
+- manter prompts;
+- manter catálogo de regras;
+- executar testes unitários e de regressão;
+- gerar package Python versionado;
+- publicar o package em um feed privado.
+
+### 4.2 Projeto Agente de IA
+
+Cada projeto de Agente de IA é responsável por:
+
+- implementar sua lógica conversacional;
+- implementar integrações com APIs, backend, ferramentas e RAG;
+- declarar a dependência do package NeMo;
+- executar testes de integração com os guardrails;
+- construir a imagem Docker final;
+- publicar a imagem no OCIR;
+- fazer deploy no OKE.
+
+### 4.3 Azure DevOps
+
+O Azure DevOps é responsável por orquestrar:
+
+- pipeline do NeMo;
+- pipeline dos agentes;
+- publicação do package;
+- build Docker;
+- push para OCIR;
+- deploy no OKE;
+- controle de variáveis e secrets;
+- permissões entre repositórios, feeds e pipelines.
+
+---
+
+## 5. Artefatos envolvidos no projeto NeMo
+
+O projeto `nemo_guardrails_configuration` contém artefatos que devem ser tratados como componentes de uma biblioteca compartilhada.
+
+Estrutura esperada:
+
+```text
+nemo_guardrails_tracing_project/
+├── config/
+│   ├── config.yml
+│   ├── config.py
+│   ├── guardrails.yaml
+│   ├── guardrails_catalog.json
+│   └── rails/
+│       ├── input.co
+│       └── output.co
+├── src/
+│   ├── app.py
+│   ├── app_nemo.py
+│   ├── actions.py
+│   ├── deterministic_rails.py
+│   ├── judges.py
+│   ├── llm_client.py
+│   ├── llm_rails.py
+│   ├── models.py
+│   ├── registry.py
+│   └── prompts/
+├── tests/
+│   └── test_guardrails.py
+├── scripts/
+│   └── run_tests.sh
+├── requirements.txt
+├── pyproject.toml
+├── .env.example
+└── README.md
+```
+
+### 5.1 `config/config.yml`
+
+Arquivo principal de configuração do NeMo Guardrails. Define modelos, engine, parâmetros, input rails, output rails e fluxos habilitados.
+
+Em ambientes corporativos, o `engine: openai` pode apontar para um proxy OpenAI-compatible, inclusive um proxy interno para OCI Generative AI.
+
+### 5.2 `config/rails/input.co`
+
+Define fluxos de entrada, como PII, toxicidade, prompt injection, out-of-scope, bloqueio de intenção e normalização de input.
+
+### 5.3 `config/rails/output.co`
+
+Define fluxos de saída, como resposta segura, groundedness, ausência de vazamento de dados, aderência ao tom, compliance e prevenção de verbalização prematura.
+
+### 5.4 `src/actions.py`
+
+Arquivo de registro das actions expostas ao NeMo. Ele conecta os fluxos `.co` com funções Python.
+
+### 5.5 `src/deterministic_rails.py`
+
+Contém rails determinísticos, como máscara de CPF, validação de alçada, validação de protocolo, consistência entre valores e regras de negócio com retorno previsível.
+
+### 5.6 `src/llm_rails.py`
+
+Contém rails que dependem de LLM ou judge, como toxicidade, out-of-scope, groundedness, qualidade de resposta, tom de voz e avaliação semântica.
+
+### 5.7 `src/judges.py`
+
+Contém avaliadores usados para medir qualidade ou segurança das respostas.
+
+### 5.8 `src/models.py`
+
+Contém classes de retorno padronizadas, por exemplo:
 
 ```python
-from nemoguardrails import LLMRails, RailsConfig
+class RailResult:
+    allowed: bool
+    reason: str
+    sanitized_text: str | None
+    code: str
+    mechanism: str
+    data: dict
+```
 
-config = RailsConfig.from_path("./config")
-rails = LLMRails(config)
+### 5.9 `src/registry.py`
+
+Contém o registry dos guardrails, mapeando código da regra, nome, tipo, mecanismo, severidade e comportamento esperado.
+
+### 5.10 `src/prompts/`
+
+Contém prompts usados por rails baseados em LLM. Esses prompts devem ser tratados como artefatos sensíveis.
+
+### 5.11 `tests/test_guardrails.py`
+
+Contém a suíte de testes do projeto NeMo. O pipeline apenas executa os testes versionados no repositório.
+
+### 5.12 `pyproject.toml`
+
+Arquivo necessário para transformar o projeto NeMo em package Python instalável.
+
+---
+
+## 6. Segurança e governança dos artefatos NeMo
+
+Como o projeto NeMo contém artefatos de segurança, ele deve ter governança própria.
+
+### 6.1 O time do agente não deve ter acesso aos steps internos do pipeline NeMo
+
+O time do agente deve consumir apenas o resultado aprovado:
+
+```text
+company-nemo-guardrails==1.2.0
+```
+
+Ele não precisa acessar YAML do pipeline NeMo, steps de teste, lógica de aprovação, scripts internos ou secrets do pipeline NeMo.
+
+### 6.2 Permissões recomendadas no Azure DevOps
+
+| Recurso | Time NeMo | Time Agente |
+|---|---:|---:|
+| Repo NeMo | Leitura/escrita | Sem acesso ou leitura restrita |
+| Pipeline NeMo | Administração | Sem acesso |
+| Feed do package | Publicação | Leitura |
+| Repo Agente | Sem acesso ou leitura | Leitura/escrita |
+| Pipeline Agente | Sem acesso ou leitura | Administração |
+| Service Connection OCI/OKE | Uso controlado | Uso conforme necessidade |
+
+### 6.3 Segurança por contrato
+
+O contrato entre NeMo e Agente é o package.
+
+```text
+Package Python versionado = contrato técnico e de segurança
 ```
 
 ---
 
-### Etapa 2: Testes de Guardrails (Unitários)
+## 7. Fluxo de CI/CD completo
 
-Criar cenários:
+### 7.1 Pipeline do NeMo
 
-```python
-tests = [
-    {"input": "xingar atendente", "expected_blocked": True},
-    {"input": "cancelar plano", "expected_blocked": False}
+```text
+Commit no repo NeMo
+  ↓
+Pipeline NeMo
+  ↓
+instala dependências
+  ↓
+executa testes
+  ↓
+gera package Python
+  ↓
+publica no Azure Artifacts
+```
+
+### 7.2 Pipeline do Agente
+
+```text
+Commit no repo Agente
+  ↓
+Pipeline Agente
+  ↓
+instala dependências
+  ↓
+instala package NeMo
+  ↓
+executa testes do agente
+  ↓
+build Docker
+  ↓
+push OCIR
+  ↓
+deploy OKE
+```
+
+### 7.3 Quem chama quem?
+
+Nenhum pipeline precisa chamar o outro diretamente. O acoplamento ocorre via package:
+
+```text
+Pipeline NeMo publica package
+Pipeline Agente instala package
+```
+
+---
+
+## 8. Criando o package Python do projeto NeMo
+
+### 8.1 Estrutura sugerida
+
+```text
+nemo_guardrails_configuration/
+├── company_nemo_guardrails/
+│   ├── __init__.py
+│   ├── config/
+│   │   ├── config.yml
+│   │   └── rails/
+│   │       ├── input.co
+│   │       └── output.co
+│   ├── actions.py
+│   ├── deterministic_rails.py
+│   ├── llm_rails.py
+│   ├── judges.py
+│   ├── models.py
+│   ├── registry.py
+│   └── prompts/
+├── tests/
+├── pyproject.toml
+└── README.md
+```
+
+### 8.2 Exemplo de `pyproject.toml`
+
+```toml
+[build-system]
+requires = ["setuptools>=68", "wheel", "build"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "company-nemo-guardrails"
+version = "1.0.0"
+description = "Biblioteca corporativa de guardrails baseada em NeMo Guardrails"
+requires-python = ">=3.11"
+dependencies = [
+  "nemoguardrails[openai]",
+  "pydantic>=2",
+  "httpx"
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+
+[tool.setuptools.package-data]
+company_nemo_guardrails = [
+  "config/*.yml",
+  "config/**/*.co",
+  "prompts/*.txt",
+  "prompts/*.md",
+  "*.json"
 ]
 ```
 
-Executar:
+### 8.3 Função utilitária para carregar config do package
 
 ```python
-for t in tests:
-    response = rails.generate(messages=[{"role": "user", "content": t["input"]}])
+from importlib.resources import files
+from nemoguardrails import RailsConfig, LLMRails
+
+def create_rails():
+    config_path = files("company_nemo_guardrails").joinpath("config")
+    config = RailsConfig.from_path(str(config_path))
+    return LLMRails(config)
+```
+
+Uso no agente:
+
+```python
+from company_nemo_guardrails import create_rails
+
+rails = create_rails()
 ```
 
 ---
 
-### Etapa 3: Testes de Regressão
+## 9. Pipeline Azure DevOps do NeMo para publicar package
 
-Garantir que mudanças não quebram comportamento anterior.
+```yaml
+trigger:
+- main
 
-- Snapshot de respostas
-- Comparação antes/depois
+pool:
+  vmImage: 'ubuntu-latest'
 
----
+variables:
+  PYTHON_VERSION: '3.11'
 
-### Etapa 4: Testes de Segurança (Guardrails)
+steps:
+- checkout: self
 
-Validar:
+- task: UsePythonVersion@0
+  inputs:
+    versionSpec: '$(PYTHON_VERSION)'
+  displayName: 'Use Python $(PYTHON_VERSION)'
 
-- Prompt injection
-- Toxicidade
-- Out-of-scope
+- script: |
+    python -m pip install --upgrade pip
+    pip install -r requirements.txt
+    pip install build twine pytest
+  displayName: 'Install dependencies'
 
----
+- script: |
+    export OPENAI_API_KEY="${OPENAI_API_KEY:-sk-fake}"
+    pytest -v --junitxml=test-results.xml
+  displayName: 'Run NeMo Guardrails tests'
 
-### Etapa 5: Testes de Fluxo Completo (E2E)
+- task: PublishTestResults@2
+  inputs:
+    testResultsFormat: 'JUnit'
+    testResultsFiles: 'test-results.xml'
+    failTaskOnFailedTests: true
+  condition: succeededOrFailed()
+  displayName: 'Publish test results'
 
-Simular jornada real:
+- script: |
+    python -m build
+    ls -la dist
+  displayName: 'Build Python package'
 
-- Input → Guardrails → LLM → Tools → Output
+- task: TwineAuthenticate@1
+  inputs:
+    artifactFeed: 'company-python-feed'
+  displayName: 'Authenticate Azure Artifacts feed'
 
----
-
-## Estratégia de Versionamento
-
-### Versionar separadamente:
-
-- Código
-- Configuração de guardrails
-
-Exemplo:
-
-```
-/app
-/config
-/tests
+- script: |
+    python -m twine upload       --repository company-python-feed       --config-file $(PYPIRC_PATH)       dist/*
+  displayName: 'Publish package to Azure Artifacts'
 ```
 
 ---
 
-## Deploy
+## 10. Projeto Agente consumindo o package NeMo
 
-### Opção 1: Embutido no container
+### 10.1 Estrutura do projeto Agente
 
-```Dockerfile
-COPY config/ /app/config/
+```text
+ai_agent_project/
+├── app/
+│   ├── main.py
+│   └── agent.py
+├── tests/
+│   ├── test_agent.py
+│   └── test_guardrails_integration.py
+├── k8s/
+│   ├── deployment.yaml
+│   └── service.yaml
+├── Dockerfile
+├── requirements.txt
+├── azure-pipelines.yml
+└── README.md
 ```
 
-### Opção 2: Config externo
+### 10.2 `requirements.txt` do Agente
 
-- S3 / OCI Object Storage
-- Volume mount
+```txt
+fastapi
+uvicorn[standard]
+company-nemo-guardrails==1.0.0
+```
+
+### 10.3 Uso no código do Agente
+
+```python
+from company_nemo_guardrails import create_rails
+
+rails = create_rails()
+
+def process_message(message: str):
+    response = rails.generate(
+        messages=[{"role": "user", "content": message}],
+        options={"log": {"activated_rails": True}}
+    )
+    return response.output_text
+```
 
 ---
 
-## Observabilidade no CI/CD
+## 11. Pipeline Azure DevOps do Agente
 
-Integrar com:
+```yaml
+trigger:
+- main
 
-- Logs estruturados
-- Tracing (OpenTelemetry)
-- Métricas de bloqueio
+pool:
+  vmImage: 'ubuntu-latest'
+
+variables:
+  PYTHON_VERSION: '3.11'
+  IMAGE_NAME: 'ai-agent'
+  IMAGE_TAG: '$(Build.SourceVersion)'
+  K8S_NAMESPACE: 'ai-agent'
+
+steps:
+- checkout: self
+
+- task: UsePythonVersion@0
+  inputs:
+    versionSpec: '$(PYTHON_VERSION)'
+  displayName: 'Use Python $(PYTHON_VERSION)'
+
+- task: PipAuthenticate@1
+  inputs:
+    artifactFeeds: 'company-python-feed'
+  displayName: 'Authenticate Python feed'
+
+- script: |
+    python -m pip install --upgrade pip
+    pip install -r requirements.txt
+  displayName: 'Install agent dependencies with NeMo package'
+
+- script: |
+    export OPENAI_API_KEY="${OPENAI_API_KEY:-sk-fake}"
+    pytest -v --junitxml=test-results.xml
+  displayName: 'Run agent tests'
+
+- task: PublishTestResults@2
+  inputs:
+    testResultsFormat: 'JUnit'
+    testResultsFiles: 'test-results.xml'
+    failTaskOnFailedTests: true
+  condition: succeededOrFailed()
+  displayName: 'Publish test results'
+
+- script: |
+    IMAGE_URI="$(OCIR_REGISTRY)/$(OCI_NAMESPACE)/$(OCIR_REPOSITORY):$(IMAGE_TAG)"
+    echo "##vso[task.setvariable variable=IMAGE_URI]$IMAGE_URI"
+    docker build -t "$IMAGE_URI" .
+  displayName: 'Build Docker image'
+
+- script: |
+    echo "$(OCIR_PASSWORD)" | docker login "$(OCIR_REGISTRY)"       -u "$(OCIR_USER)"       --password-stdin
+    docker push "$(IMAGE_URI)"
+  displayName: 'Push image to OCIR'
+
+- script: |
+    mkdir -p ~/.kube
+    echo "$(OKE_KUBECONFIG_B64)" | base64 -d > ~/.kube/config
+    chmod 600 ~/.kube/config
+
+    kubectl apply -f k8s/namespace.yaml
+    sed "s|REPLACE_IMAGE_URI|$(IMAGE_URI)|g" k8s/deployment.yaml | kubectl apply -f -
+    kubectl apply -f k8s/service.yaml
+
+    kubectl rollout status deployment/ai-agent -n $(K8S_NAMESPACE) --timeout=180s
+  displayName: 'Deploy to OCI OKE'
+```
 
 ---
 
-## Estratégia Avançada
+## 12. Dockerfile do Agente
 
-### Feature Flags de Guardrails
+```dockerfile
+FROM python:3.11-slim
 
-Permitir ativar/desativar regras sem deploy.
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY requirements.txt .
+
+RUN pip install --no-cache-dir --upgrade pip     && pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8080
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]
+```
 
 ---
 
-## Anti-patterns
+## 13. Variáveis e secrets no Azure DevOps
 
-Evitar:
+### 13.1 Variáveis do pipeline do Agente
 
-- Deploy direto sem testes
-- Misturar lógica de negócio com guardrails
-- Não versionar `.co`
+| Variável | Exemplo | Tipo |
+|---|---|---|
+| `OCIR_REGISTRY` | `gru.ocir.io` | normal |
+| `OCI_NAMESPACE` | `meunamespace` | normal |
+| `OCIR_REPOSITORY` | `agents/ai-agent` | normal |
+| `OCIR_USER` | `tenancy/user` | secret |
+| `OCIR_PASSWORD` | auth token OCI | secret |
+| `OKE_KUBECONFIG_B64` | kubeconfig em base64 | secret |
+| `OPENAI_API_KEY` | chave ou fake/proxy | secret |
+
+### 13.2 Variáveis do pipeline NeMo
+
+| Variável | Exemplo | Tipo |
+|---|---|---|
+| `OPENAI_API_KEY` | `sk-fake` | secret |
+| Feed credentials | gerenciado pelo Azure Artifacts | service/task |
 
 ---
 
-## Conclusão
+## 14. OCI Vault
 
-No NeMo Guardrails:
+### 14.1 Papel do OCI Vault
 
-> CI/CD não é só sobre código, é sobre comportamento do agente.
+O OCI Vault deve ser usado para proteger secrets em runtime:
 
-É essencial tratar configurações como **artefatos críticos de software**.
+- chaves de LLM;
+- credenciais de API;
+- tokens de backend;
+- senhas de integração.
 
-## Referências
+### 14.2 Estratégia simples
 
-- [Tutorial: NeMo Guardrails com Python, Proxy OpenAI-Compatible e Tracing](https://github.com/hoshikawa2/nemo_guardrails_configuration)
+```text
+Azure DevOps secret → Kubernetes Secret → Pod
+```
 
-## Acknowledgments
+### 14.3 Estratégia recomendada
 
-- **Author** - Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer)
+```text
+OCI Vault → External Secrets Operator / CSI Driver → Kubernetes Secret → Pod
+```
+
+Esse modelo evita manter secrets de runtime no Azure DevOps.
+
+---
+
+## 15. Segurança: impedindo acesso indevido ao pipeline NeMo
+
+### 15.1 Separação de repositórios
+
+```text
+Repo NeMo        → time plataforma/guardrails
+Repo Agente      → time aplicação/agente
+```
+
+### 15.2 Separação de pipelines
+
+```text
+Pipeline NeMo    → administrado pelo time NeMo
+Pipeline Agente  → administrado pelo time Agente
+```
+
+### 15.3 Compartilhamento apenas do package
+
+O time do agente recebe permissão de leitura no feed:
+
+```text
+company-python-feed
+```
+
+Ele não precisa acessar repo NeMo, pipeline NeMo, steps de teste, scripts internos ou secrets do NeMo.
+
+---
+
+## 16. Testes no modelo com package
+
+### 16.1 Testes do NeMo
+
+Executados no pipeline NeMo:
+
+- testes determinísticos;
+- testes de segurança;
+- testes de regressão;
+- testes de catálogo;
+- testes de actions;
+- testes de judge.
+
+### 16.2 Testes do Agente
+
+Executados no pipeline do agente:
+
+- testes do código do agente;
+- teste de carregamento do package NeMo;
+- teste de integração mínima;
+- teste E2E do fluxo conversacional;
+- teste de contrato de API.
+
+### 16.3 Exemplo
+
+```python
+def test_agent_uses_guardrails():
+    from company_nemo_guardrails import create_rails
+
+    rails = create_rails()
+    assert rails is not None
+```
+
+---
+
+## 17. Versionamento
+
+Recomenda-se versionamento semântico:
+
+```text
+MAJOR.MINOR.PATCH
+```
+
+Exemplos:
+
+```text
+1.0.0
+1.1.0
+1.1.1
+2.0.0
+```
+
+| Tipo de mudança | Versão |
+|---|---|
+| Correção sem mudança de comportamento esperado | PATCH |
+| Nova regra compatível | MINOR |
+| Mudança que pode bloquear novos casos | MINOR ou MAJOR |
+| Mudança incompatível | MAJOR |
+
+No agente:
+
+```txt
+company-nemo-guardrails==1.2.0
+```
+
+Ou aceitando patches:
+
+```txt
+company-nemo-guardrails~=1.2.0
+```
+
+---
+
+## 18. Conclusão
+
+A estratégia recomendada para este cenário é:
+
+```text
+NeMo Guardrails = package Python versionado
+Agente de IA = aplicação final
+Pipeline NeMo = publica package aprovado
+Pipeline Agente = instala package, gera imagem e faz deploy
+Runtime = um container com agente + guardrails
+```
+
+Esse modelo equilibra segurança, governança, velocidade, simplicidade operacional, reutilização entre múltiplos agentes e deploy único no OCI OKE.
+
+A governança deixa de depender de um serviço central em runtime e passa a acontecer no ciclo de CI/CD, por meio de testes, versionamento, publicação controlada e permissões no feed de packages.