First commit

2026-07-09 14:04:19 +00:00 · 2026-06-19 22:17:09 -03:00
commit 239203ee2a
533 changed files with 75195 additions and 0 deletions
--- a/specs/README.md
+++ b/specs/README.md
@@ -0,0 +1,27 @@
+# Agent Platform OCI — SDD Clean V3
+
+Pacote de SPECs técnicas em formato SDD.
+
+## Arquivos
+
+| Arquivo | Tema |
+|---|---|
+| SPEC-001-Architecture.md | Arquitetura da plataforma |
+| SPEC-002-Agent-Runtime.md | Runtime LangGraph |
+| SPEC-003-AI-Gateway.md | AI Gateway |
+| SPEC-004-MCP-Gateway.md | MCP Gateway |
+| SPEC-005-Guardrails.md | Guardrails |
+| SPEC-006-Evals.md | Evals e certificação |
+| SPEC-007-Observability.md | Observabilidade |
+| SPEC-008-Deployment.md | CI/CD e deployment |
+| SPEC-009-Channel-Gateway.md | Channel Gateway |
+| SPEC-010-Agent-Development.md | Desenvolvimento de agentes |
+
+## Padrão de escrita
+
+- Especificação direta.
+- Sem justificativas.
+- Sem histórico.
+- Sem defesa arquitetural.
+- Sem comentários políticos.
+- Com contratos, fluxos, configurações, eventos, métricas e critérios de aceite.
--- a/specs/SPEC-001-Architecture.md
+++ b/specs/SPEC-001-Architecture.md
@@ -0,0 +1,239 @@
+# SPEC-001 — Architecture
+
+## Escopo
+
+A Agent Platform OCI é composta por componentes reutilizáveis, aplicações deployáveis, contratos de integração, templates de agentes, camada de avaliação e artefatos de operação.
+
+## Componentes
+
+| Componente | Tipo | Responsabilidade |
+|---|---|---|
+| `libs/agent_framework` | Lib | Core reutilizável do framework. |
+| `runtimes/langgraph_runtime` | Runtime | Execução de agentes baseada em LangGraph. |
+| `apps/agent_gateway` | App | Entrada padronizada e roteamento de agentes/backends. |
+| `apps/channel_gateway` | App | Normalização de canais externos. |
+| `apps/ai_gateway` | App | Abstração, governança e roteamento de modelos. |
+| `apps/mcp_gateway` | App | Governança, catálogo e execução de tools MCP. |
+| `mcp/servers` | Apps | MCP servers de domínio. |
+| `evals/offline` | App/Lib | Avaliação offline/batch. |
+| `evals/certification` | Suite | Certificação técnica e funcional. |
+| `templates/backend` | Template | Scaffold para novos agentes. |
+| `specs` | Documentação | Contratos SDD versionados. |
+| `deploy` | Operação | Docker, Kubernetes e Helm. |
+
+## Estrutura de Repositório
+
+```text
+agent_platform_oci/
+├── libs/
+│   └── agent_framework/
+├── runtimes/
+│   └── langgraph_runtime/
+├── apps/
+│   ├── agent_gateway/
+│   ├── channel_gateway/
+│   ├── ai_gateway/
+│   └── mcp_gateway/
+├── mcp/
+│   └── servers/
+├── evals/
+│   ├── offline/
+│   └── certification/
+├── templates/
+│   ├── backend/
+│   └── backend_day_zero/
+├── specs/
+├── deploy/
+│   ├── docker/
+│   ├── k8s/
+│   └── helm/
+├── tests/
+└── docs/
+```
+
+## Arquitetura Lógica
+
+```mermaid
+flowchart LR
+    C[Canal] --> CG[Channel Gateway]
+    CG --> AG[Agent Gateway]
+    AG --> RT[Agent Runtime]
+    RT --> FW[Agent Framework Core]
+    RT --> AIG[AI Gateway]
+    RT --> MCPG[MCP Gateway]
+    MCPG --> MCPS[MCP Servers]
+    RT --> OBS[Observability]
+    RT --> MEM[Memory/Checkpoint]
+    OBS --> LF[Langfuse/OTEL]
+    LF --> EV[Evaluator]
+```
+
+## Arquitetura Física
+
+| Serviço | Porta Padrão | Deploy | Escala |
+|---|---:|---|---|
+| Agent Gateway | 9000 | Kubernetes Deployment | Horizontal |
+| Agent Backend / Runtime | 8000 | Kubernetes Deployment | Horizontal com storage externo |
+| Channel Gateway | 7000 | Kubernetes Deployment | Horizontal |
+| AI Gateway | 9100 | Kubernetes Deployment | Horizontal |
+| MCP Gateway | 9200 | Kubernetes Deployment | Horizontal |
+| MCP Servers | 8001+ | Kubernetes Deployment | Por domínio |
+| Evaluator API | 9300 | Deployment/CronJob | Por carga batch |
+| Frontend Demo | 5173 | Opcional | Não crítico |
+
+## Contratos Principais
+
+| Contrato | Produtor | Consumidor |
+|---|---|---|
+| GatewayRequest | Channel Gateway / Agent Gateway | Agent Runtime |
+| ChannelResponse | Agent Runtime | Channel Gateway / Cliente |
+| BusinessContext | Channel Gateway / Identity Resolver | Runtime / Agents / MCP |
+| LLMRequest | Agent Runtime | AI Gateway |
+| LLMResponse | AI Gateway | Agent Runtime |
+| ToolInvocation | Agent Runtime / MCP Gateway | MCP Server |
+| ToolResult | MCP Server / MCP Gateway | Agent Runtime |
+| GuardrailResult | Guardrail Engine | Runtime / Observability |
+| JudgeResult | Judge Engine / Evaluator | Runtime / Evaluator |
+| EvaluationRun | Evaluator | Persistence / Dashboards |
+
+## GatewayRequest
+
+```json
+{
+  "channel": "web",
+  "tenant_id": "default",
+  "agent_id": "telecom_contas",
+  "payload": {
+    "message": "Quero consultar minha fatura",
+    "session_id": "session-001",
+    "user_id": "user-001",
+    "message_id": "msg-001",
+    "business_context": {
+      "customer_key": "11999999999",
+      "contract_key": "3000131180",
+      "interaction_key": "301953872",
+      "session_key": "session-001"
+    },
+    "metadata": {
+      "request_id": "req-001"
+    }
+  }
+}
+```
+
+## ChannelResponse
+
+```json
+{
+  "channel": "web",
+  "session_id": "default:telecom_contas:session-001",
+  "text": "Resposta final do agente.",
+  "metadata": {
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "route": "billing_agent",
+    "intent": "billing_invoice_explanation"
+  }
+}
+```
+
+## Fluxo Principal
+
+```mermaid
+sequenceDiagram
+    participant Canal
+    participant ChannelGateway
+    participant AgentGateway
+    participant Runtime
+    participant AIGateway
+    participant MCPGateway
+    participant Store
+    Canal->>ChannelGateway: Payload bruto
+    ChannelGateway->>AgentGateway: GatewayRequest
+    AgentGateway->>Runtime: GatewayRequest normalizado
+    Runtime->>Store: Sessão, memória e checkpoint
+    Runtime->>Runtime: Guardrails de entrada
+    Runtime->>Runtime: Router/Supervisor
+    Runtime->>MCPGateway: ToolInvocation
+    MCPGateway-->>Runtime: ToolResult
+    Runtime->>AIGateway: LLMRequest
+    AIGateway-->>Runtime: LLMResponse
+    Runtime->>Runtime: Guardrails de saída e Judges
+    Runtime->>Store: Persistência
+    Runtime-->>AgentGateway: ChannelResponse
+    AgentGateway-->>ChannelGateway: ChannelResponse
+    ChannelGateway-->>Canal: Resposta do canal
+```
+
+## Configuração
+
+| Arquivo | Uso |
+|---|---|
+| `.env` | Provider, autenticação, flags e endpoints por ambiente. |
+| `agents.yaml` | Registro de agentes. |
+| `routing.yaml` | Intents, rotas, políticas e fallback. |
+| `guardrails.yaml` | Guardrails globais. |
+| `judges.yaml` | Judges globais. |
+| `llm_profiles.yaml` | Profiles de modelos por componente. |
+| `mcp_servers.yaml` | MCP servers disponíveis. |
+| `tools.yaml` | Catálogo de tools. |
+| `mcp_parameter_mapping.yaml` | Mapeamento BusinessContext → argumentos MCP. |
+| `identity.yaml` | Resolução de identidade de negócio. |
+| `observability.yaml` | Logs, métricas, traces e exporters. |
+| `evals.yaml` | Datasets, métricas e configuração do evaluator. |
+
+## Eventos
+
+| Evento | Origem | Descrição |
+|---|---|---|
+| `gateway.request.received` | Agent Gateway | Requisição recebida. |
+| `channel.normalized` | Channel Gateway | Payload convertido em GatewayRequest. |
+| `runtime.started` | Runtime | Execução iniciada. |
+| `guardrail.input.completed` | Guardrails | Guardrails de entrada concluídos. |
+| `route.selected` | Router/Supervisor | Rota definida. |
+| `mcp.tool.completed` | MCP Gateway | Tool executada. |
+| `llm.completed` | AI Gateway | Chamada LLM concluída. |
+| `judge.completed` | Judge Engine | Avaliação concluída. |
+| `runtime.completed` | Runtime | Execução finalizada. |
+
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|---|---|
+| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
+| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
+| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
+| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
+| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
+| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+
+
+## Critérios de Aceite
+
+- [ ] Estrutura de repositório separa libs, runtimes, apps, mcp, evals, templates, specs e deploy.
+- [ ] Cada app deployável possui contrato de entrada/saída documentado.
+- [ ] GatewayRequest e ChannelResponse estão versionados.
+- [ ] BusinessContext é usado como contrato canônico.
+- [ ] Runtime não recebe payload bruto de canal.
+- [ ] AI Gateway e MCP Gateway possuem fronteiras explícitas.
+- [ ] Evaluator é componente padronizado de avaliação.
+- [ ] Todos os serviços possuem health check.
+- [ ] Telemetria fim-a-fim correlaciona request_id, trace_id e session_id.
+- [ ] Configurações críticas possuem YAML dedicado.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
+| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
+| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
+| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
+| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
+| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
+| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
+| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
+| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
--- a/specs/SPEC-002-Agent-Runtime.md
+++ b/specs/SPEC-002-Agent-Runtime.md
@@ -0,0 +1,251 @@
+# SPEC-002 — Agent Runtime
+
+## Escopo
+
+O Agent Runtime executa o ciclo de vida conversacional do agente. A execução inclui normalização de contexto, estado LangGraph, memória, checkpoint, roteamento, supervisor, guardrails, MCP, RAG, LLM, judges, persistência e resposta final.
+
+## Componentes
+
+| Componente | Responsabilidade |
+|---|---|
+| Workflow Builder | Compila o grafo LangGraph. |
+| State Manager | Mantém o estado de execução. |
+| Session Manager | Resolve sessão e conversation_key. |
+| Memory Manager | Carrega e persiste histórico. |
+| Checkpoint Manager | Persiste estado LangGraph. |
+| Input Guardrail Node | Executa guardrails de entrada. |
+| Router Node | Decide rota/intent. |
+| Supervisor Node | Decide handoff ou próximo agente quando habilitado. |
+| Agent Node | Executa agente de domínio. |
+| MCP Client/Router | Executa tools por contrato. |
+| RAG Service | Recupera contexto documental. |
+| Output Supervisor | Revisa resposta antes de saída. |
+| Output Guardrail Node | Executa guardrails de saída. |
+| Judge Node | Avalia resposta. |
+| Persistence Node | Persiste mensagens, memória e checkpoint. |
+
+## State Model
+
+```python
+class AgentState(TypedDict, total=False):
+    user_text: str
+    sanitized_input: str
+    response_text: str
+    tenant_id: str
+    agent_id: str
+    channel: str
+    session_id: str
+    conversation_key: str
+    message_id: str
+    route: str
+    intent: str
+    context: dict
+    business_context: dict
+    tool_arguments: dict
+    mcp_tools: list[str]
+    mcp_results: list[dict]
+    rag_context: str
+    rag_metadata: dict
+    guardrails: list[dict]
+    judges: list[dict]
+    metadata: dict
+    errors: list[dict]
+```
+
+## Workflow
+
+```mermaid
+flowchart TD
+    A[start] --> B[input_guardrails]
+    B --> C[routing_decision]
+    C --> D[agent_execution]
+    D --> E[output_supervisor]
+    E --> F[output_guardrails]
+    F --> G[judge]
+    G --> H[persist]
+    H --> I[end]
+    C --> J[handoff]
+    J --> C
+```
+
+## Nós
+
+| Nó | Entrada | Saída |
+|---|---|---|
+| `input_guardrails` | `user_text`, `context` | `sanitized_input`, `guardrails` |
+| `routing_decision` | `sanitized_input`, `business_context` | `route`, `intent`, `mcp_tools` |
+| `agent_execution` | `state` completo | `response_text`, `mcp_results`, `rag_metadata` |
+| `output_supervisor` | `response_text` | `response_text` revisado |
+| `output_guardrails` | `response_text` | `response_text`, `guardrails` |
+| `judge` | `response_text`, evidências | `judges` |
+| `persist` | `state` completo | checkpoint, memória, mensagens |
+
+## Router
+
+```yaml
+routing:
+  mode: router
+  fallback_agent: billing_agent
+  enable_llm_router: false
+  intents:
+    billing_invoice_explanation:
+      route: billing_agent
+      keywords:
+        - fatura
+        - cobrança
+        - boleto
+      mcp_tools:
+        - consultar_fatura
+        - consultar_pagamentos
+```
+
+## Supervisor
+
+```yaml
+supervisor:
+  enabled: true
+  profile: supervisor
+  max_turns: 5
+  handoff_enabled: true
+  fallback_route: support_agent
+```
+
+## Memory
+
+| Provider | Uso |
+|---|---|
+| `memory` | Execução local e testes. |
+| `sqlite` | Desenvolvimento local persistente. |
+| `mongodb` | Checkpoint e histórico em ambiente distribuído. |
+| `autonomous` | Produção com Oracle Autonomous Database. |
+
+## Checkpoints
+
+Checkpoint contém:
+
+```json
+{
+  "conversation_key": "default:telecom_contas:session-001",
+  "checkpoint_id": "ckpt-001",
+  "state": {},
+  "pending_writes": [],
+  "created_at": "2026-06-19T12:00:00Z"
+}
+```
+
+Formato entregue ao LangGraph:
+
+```python
+pending_writes: list[tuple[str, str, object]]
+```
+
+## Business Context
+
+```yaml
+business_context:
+  customer_key: "11999999999"
+  contract_key: "3000131180"
+  interaction_key: "301953872"
+  account_key: null
+  resource_key: null
+  session_key: "session-001"
+  metadata:
+    source_channel: web
+```
+
+## Ordem de Prioridade dos Dados
+
+1. `tool_arguments`
+2. `business_context`
+3. `context`
+4. `session.metadata`
+5. `state`
+6. extração complementar do texto
+
+## MCP Integration
+
+```mermaid
+flowchart LR
+    AgentNode --> ToolList[mcp_tools]
+    ToolList --> Mapping[mcp_parameter_mapping.yaml]
+    Mapping --> MCP[MCP Gateway/Router]
+    MCP --> Result[mcp_results]
+```
+
+## RAG Integration
+
+```yaml
+rag:
+  enabled: true
+  namespace_strategy: agent_id
+  top_k: 5
+  profile_generation: rag_generation
+```
+
+## Eventos
+
+| Evento | Descrição |
+|---|---|
+| `runtime.started` | Execução iniciada. |
+| `runtime.session.loaded` | Sessão carregada. |
+| `runtime.memory.loaded` | Memória carregada. |
+| `runtime.checkpoint.loaded` | Checkpoint carregado. |
+| `runtime.route.selected` | Rota selecionada. |
+| `runtime.agent.started` | Agente iniciado. |
+| `runtime.agent.completed` | Agente concluído. |
+| `runtime.persist.completed` | Persistência concluída. |
+| `runtime.failed` | Falha controlada. |
+
+## Erros
+
+| Código | Condição | Tratamento |
+|---|---|---|
+| `RUNTIME_INVALID_REQUEST` | GatewayRequest inválido | 422 |
+| `RUNTIME_ROUTE_NOT_FOUND` | Nenhuma rota elegível | fallback ou resposta controlada |
+| `RUNTIME_CHECKPOINT_ERROR` | Falha em checkpoint | retry ou stateless conforme config |
+| `RUNTIME_MEMORY_ERROR` | Falha em memória | retry ou resposta controlada |
+| `RUNTIME_AGENT_ERROR` | Falha no agente | NOC + fallback |
+| `RUNTIME_TIMEOUT` | Timeout geral | resposta controlada |
+
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|---|---|
+| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
+| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
+| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
+| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
+| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
+| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+
+
+## Critérios de Aceite
+
+- [ ] Runtime recebe GatewayRequest validado.
+- [ ] State contém tenant_id, agent_id, session_id, conversation_key, route e intent.
+- [ ] Input guardrails executam antes do roteamento.
+- [ ] Router ou Supervisor seleciona rota.
+- [ ] Agent Node executa sem acessar payload bruto de canal.
+- [ ] MCP é acessado por contrato.
+- [ ] RAG é acessado por serviço reutilizável.
+- [ ] Output guardrails executam antes da resposta final.
+- [ ] Judges geram JudgeResult.
+- [ ] Memória e checkpoint são persistidos conforme provider.
+- [ ] Erros geram NOC e resposta controlada.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
+| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
+| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
+| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
+| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
+| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
+| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
+| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
+| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
--- a/specs/SPEC-003-AI-Gateway.md
+++ b/specs/SPEC-003-AI-Gateway.md
@@ -0,0 +1,218 @@
+# SPEC-003 — AI Gateway
+
+## Escopo
+
+O AI Gateway executa chamadas de inferência e embedding por contrato padronizado. Ele centraliza provider, modelo, profile, política, fallback, uso, custo, latência e telemetria.
+
+## Endpoints
+
+| Método | Endpoint | Descrição |
+|---|---|---|
+| `POST` | `/v1/chat/completions` | Geração de texto/chat. |
+| `POST` | `/v1/embeddings` | Geração de embeddings. |
+| `GET` | `/v1/models` | Lista modelos disponíveis. |
+| `GET` | `/v1/profiles` | Lista profiles configurados. |
+| `GET` | `/health` | Health check. |
+| `GET` | `/ready` | Readiness check. |
+
+## LLMRequest
+
+```json
+{
+  "tenant_id": "default",
+  "agent_id": "telecom_contas",
+  "profile": "judge",
+  "component": "judge",
+  "operation": "chat_completion",
+  "messages": [
+    {"role": "system", "content": "Você é um avaliador."},
+    {"role": "user", "content": "Avalie a resposta."}
+  ],
+  "parameters": {
+    "temperature": 0,
+    "max_tokens": 800
+  },
+  "metadata": {
+    "request_id": "req-001",
+    "trace_id": "trace-001",
+    "session_id": "default:telecom_contas:session-001"
+  }
+}
+```
+
+## LLMResponse
+
+```json
+{
+  "provider": "oci_openai",
+  "model": "openai.gpt-4.1",
+  "profile": "judge",
+  "content": "Resultado da geração.",
+  "usage": {
+    "input_tokens": 1200,
+    "output_tokens": 300,
+    "total_tokens": 1500
+  },
+  "latency_ms": 820,
+  "finish_reason": "stop",
+  "metadata": {
+    "fallback_used": false
+  }
+}
+```
+
+## Profiles
+
+```yaml
+profiles:
+  default:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0.2
+    max_tokens: 2048
+
+  supervisor:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 700
+
+  router:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 500
+
+  guardrail:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 600
+
+  judge:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 800
+
+  rag_generation:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0.1
+    max_tokens: 1800
+```
+
+## Providers
+
+| Provider | Autenticação | Uso |
+|---|---|---|
+| `mock` | Nenhuma | Testes locais. |
+| `oci_openai` | API Key / endpoint compatible | OCI GenAI OpenAI-Compatible. |
+| `oci_sdk` | OCI Auth Mode | SDK nativo OCI. |
+| `openai_compatible` | API Key | Endpoint compatível OpenAI. |
+
+## OCI Authentication
+
+| Variável | Valores |
+|---|---|
+| `LLM_PROVIDER` | `mock`, `oci_openai`, `oci_sdk`, `openai_compatible` |
+| `OCI_AUTH_MODE` | `config_file`, `instance_principal`, `resource_principal`, `workload_identity` |
+| `OCI_GENAI_API_KEY` | API key para provider compatível |
+
+## Fallback
+
+```yaml
+fallback:
+  enabled: true
+  policies:
+    default:
+      chain:
+        - profile: default
+        - profile: default_low_cost
+    judge:
+      enabled: false
+```
+
+## Rate Limit
+
+```yaml
+rate_limits:
+  default:
+    requests_per_minute: 600
+    tokens_per_minute: 1000000
+  agents:
+    telecom_contas:
+      requests_per_minute: 120
+```
+
+## Eventos
+
+| Evento | Descrição |
+|---|---|
+| `ai.request.received` | Requisição recebida. |
+| `ai.profile.resolved` | Profile resolvido. |
+| `ai.provider.selected` | Provider selecionado. |
+| `ai.completion.started` | Chamada iniciada. |
+| `ai.completion.completed` | Chamada concluída. |
+| `ai.fallback.used` | Fallback utilizado. |
+| `ai.request.failed` | Falha de inferência. |
+
+## Métricas
+
+| Métrica | Dimensões |
+|---|---|
+| `ai_requests_total` | provider, model, profile, tenant, agent, status |
+| `ai_latency_ms` | provider, model, profile |
+| `ai_tokens_total` | provider, model, input/output |
+| `ai_cost_estimated` | provider, model, tenant, agent |
+| `ai_fallback_total` | source_profile, fallback_profile |
+
+## Segurança
+
+- API keys não são gravadas em logs.
+- Prompts podem ser mascarados conforme política.
+- Providers são autorizados por tenant.
+- Workload Identity é usada em Kubernetes quando configurada.
+- Modelos bloqueados por política retornam erro controlado.
+
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|---|---|
+| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
+| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
+| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
+| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
+| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
+| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+
+
+## Critérios de Aceite
+
+- [ ] Endpoint de chat completion aceita LLMRequest.
+- [ ] Endpoint de embeddings aceita EmbeddingRequest.
+- [ ] Profiles são resolvidos por `llm_profiles.yaml`.
+- [ ] Provider/model/profile aparecem em logs e traces.
+- [ ] Fallback é explícito e rastreável.
+- [ ] Rate limit é aplicado por tenant/agente.
+- [ ] OCI Auth funciona por ambiente.
+- [ ] Modelo não autorizado é rejeitado.
+- [ ] Uso de tokens é registrado.
+- [ ] Erros retornam payload padronizado.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
+| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
+| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
+| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
+| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
+| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
+| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
+| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
+| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
--- a/specs/SPEC-004-MCP-Gateway.md
+++ b/specs/SPEC-004-MCP-Gateway.md
@@ -0,0 +1,227 @@
+# SPEC-004 — MCP Gateway
+
+## Escopo
+
+O MCP Gateway centraliza catálogo, autorização, roteamento, execução, cache, timeout, retry, observabilidade e resposta padronizada de tools MCP.
+
+## Endpoints
+
+| Método | Endpoint | Descrição |
+|---|---|---|
+| `GET` | `/health` | Health check. |
+| `GET` | `/ready` | Readiness check. |
+| `GET` | `/v1/tools` | Catálogo de tools. |
+| `GET` | `/v1/tools/{tool_name}` | Detalhe da tool. |
+| `POST` | `/v1/tools/{tool_name}/invoke` | Execução de tool. |
+| `GET` | `/v1/servers` | Lista MCP servers. |
+
+## ToolInvocation
+
+```json
+{
+  "tenant_id": "default",
+  "agent_id": "telecom_contas",
+  "tool_name": "consultar_fatura",
+  "arguments": {
+    "msisdn": "11999999999",
+    "invoice_id": "3000131180",
+    "session_id": "default:telecom_contas:session-001"
+  },
+  "business_context": {
+    "customer_key": "11999999999",
+    "contract_key": "3000131180",
+    "session_key": "session-001"
+  },
+  "metadata": {
+    "request_id": "req-001",
+    "trace_id": "trace-001"
+  }
+}
+```
+
+## ToolResult
+
+```json
+{
+  "tool_name": "consultar_fatura",
+  "ok": true,
+  "data": {
+    "invoice_id": "3000131180",
+    "valor_total": 249.90,
+    "vencimento": "2026-06-10",
+    "status": "ABERTA"
+  },
+  "cache": {
+    "hit": false,
+    "ttl_seconds": 300
+  },
+  "latency_ms": 140,
+  "metadata": {
+    "server": "telecom"
+  }
+}
+```
+
+## mcp_servers.yaml
+
+```yaml
+servers:
+  telecom:
+    transport: http
+    url: http://telecom-mcp:8001/mcp
+    enabled: true
+    timeout_seconds: 30
+
+  retail:
+    transport: http
+    url: http://retail-mcp:8002/mcp
+    enabled: true
+    timeout_seconds: 30
+```
+
+## tools.yaml
+
+```yaml
+tools:
+  consultar_fatura:
+    server: telecom
+    enabled: true
+    idempotent: true
+    cache_ttl_seconds: 300
+    allowed_agents:
+      - telecom_contas
+    required_business_keys:
+      - customer_key
+      - contract_key
+
+  solicitar_devolucao:
+    server: retail
+    enabled: true
+    idempotent: false
+    requires_confirmation: true
+    allowed_agents:
+      - retail_orders
+```
+
+## mcp_parameter_mapping.yaml
+
+```yaml
+tools:
+  consultar_fatura:
+    map:
+      customer_key: msisdn
+      contract_key: invoice_id
+      interaction_key: ura_call_id
+      session_key: session_id
+```
+
+## Autorização
+
+```yaml
+authorization:
+  default_policy: deny
+  agents:
+    telecom_contas:
+      allowed_tools:
+        - consultar_fatura
+        - consultar_pagamentos
+        - consultar_plano
+```
+
+## Cache
+
+| Regra | Valor |
+|---|---|
+| Chave | `tenant_id:agent_id:tool_name:hash(arguments)` |
+| Aplicação | Apenas tools idempotentes |
+| Bypass | `metadata.cache_bypass=true` |
+| TTL | `cache_ttl_seconds` |
+| Escrita | Não cachear operações mutáveis |
+
+## Retry e Timeout
+
+```yaml
+execution:
+  default_timeout_seconds: 30
+  retry:
+    enabled: true
+    max_attempts: 2
+    backoff_ms: 250
+  circuit_breaker:
+    enabled: true
+    failure_threshold: 5
+    recovery_seconds: 60
+```
+
+## Eventos
+
+| Evento | Descrição |
+|---|---|
+| `mcp.tool.requested` | Tool requisitada. |
+| `mcp.tool.authorized` | Autorização aprovada. |
+| `mcp.tool.denied` | Autorização negada. |
+| `mcp.tool.started` | Execução iniciada. |
+| `mcp.tool.completed` | Execução concluída. |
+| `mcp.tool.failed` | Execução falhou. |
+| `mcp.cache.hit` | Cache hit. |
+| `mcp.cache.miss` | Cache miss. |
+
+## Métricas
+
+| Métrica | Dimensões |
+|---|---|
+| `mcp_tool_calls_total` | tool, server, tenant, agent, status |
+| `mcp_tool_latency_ms` | tool, server |
+| `mcp_tool_errors_total` | tool, server, error_type |
+| `mcp_cache_hits_total` | tool |
+| `mcp_cache_misses_total` | tool |
+
+## Segurança
+
+- Tools são negadas por padrão.
+- Argumentos sensíveis são mascarados.
+- Tools mutáveis exigem confirmação quando configurado.
+- MCP servers não recebem payload bruto de canal.
+- Credenciais de backend são mantidas nos MCP servers ou secret store.
+
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|---|---|
+| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
+| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
+| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
+| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
+| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
+| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+
+
+## Critérios de Aceite
+
+- [ ] Catálogo de tools retorna tools habilitadas.
+- [ ] ToolInvocation é validado antes da execução.
+- [ ] Autorização por agente é aplicada.
+- [ ] Parâmetros são derivados do BusinessContext.
+- [ ] Cache só é aplicado a tools idempotentes.
+- [ ] Timeout/retry/circuit breaker são configuráveis.
+- [ ] Eventos e métricas são emitidos.
+- [ ] Falhas retornam ToolResult padronizado.
+- [ ] MCP servers são substituíveis por configuração.
+- [ ] Tools críticas possuem testes de contrato.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
+| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
+| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
+| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
+| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
+| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
+| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
+| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
+| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
--- a/specs/SPEC-005-Guardrails.md
+++ b/specs/SPEC-005-Guardrails.md
@@ -0,0 +1,194 @@
+# SPEC-005 — Guardrails
+
+## Escopo
+
+Guardrails são políticas executadas sobre entrada, saída, tool calls, RAG e respostas finais. A plataforma suporta guardrails globais, por agente, por canal e por fase.
+
+## Fases
+
+| Fase | Entrada | Saída |
+|---|---|---|
+| Input | `user_text`, `context` | `sanitized_input`, `GuardrailResult` |
+| Tool | `ToolInvocation` | tool permitida/bloqueada |
+| RAG | query/contexto recuperado | contexto aprovado/filtrado |
+| Output | `response_text` | resposta aprovada/sanitizada/bloqueada |
+| Review | resposta + evidências | decisão final |
+
+## GuardrailResult
+
+```json
+{
+  "code": "PINJ",
+  "phase": "input",
+  "status": "blocked",
+  "severity": "high",
+  "score": 0.98,
+  "message": "Entrada bloqueada por política.",
+  "details": {
+    "matched_policy": "prompt_injection"
+  }
+}
+```
+
+## Configuração Global
+
+```yaml
+input:
+  - code: MSK
+    enabled: true
+    mode: enforce
+  - code: VLOOP
+    enabled: true
+    mode: enforce
+  - code: PINJ
+    enabled: true
+    mode: enforce
+
+output:
+  - code: REVPREC
+    enabled: true
+    mode: enforce
+  - code: DLEX_OUT
+    enabled: true
+    mode: enforce
+  - code: PINJ
+    enabled: true
+    mode: observe
+```
+
+## Configuração por Agente
+
+```yaml
+agents:
+  telecom_contas:
+    input:
+      - code: BILLING_INPUT_POLICY
+        enabled: true
+        mode: observe
+    output:
+      - code: BILLING_COMPLIANCE
+        enabled: true
+        mode: enforce
+```
+
+## Modos
+
+| Modo | Comportamento |
+|---|---|
+| `enforce` | Aplica bloqueio, máscara ou alteração. |
+| `observe` | Registra sem bloquear. |
+| `fail_open` | Em erro técnico, prossegue e emite NOC. |
+| `fail_closed` | Em erro técnico, bloqueia. |
+
+## Tipos
+
+| Tipo | Implementação |
+|---|---|
+| Determinístico | Regex, listas, tamanho, estrutura, regras. |
+| LLM | Classificação semântica por profile. |
+| Híbrido | Determinístico + LLM em casos ambíguos. |
+
+## Profiles LLM
+
+```yaml
+profiles:
+  guardrail:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 600
+
+  grl:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 700
+```
+
+## Fluxo
+
+```mermaid
+flowchart TD
+    A[Input] --> B[Deterministic Guardrails]
+    B --> C{Blocked?}
+    C -- yes --> D[Safe Response]
+    C -- no --> E[LLM Guardrails]
+    E --> F{Approved?}
+    F -- no --> D
+    F -- yes --> G[Runtime]
+```
+
+## Eventos
+
+| Evento | Descrição |
+|---|---|
+| `guardrail.started` | Execução iniciada. |
+| `guardrail.completed` | Execução concluída. |
+| `guardrail.blocked` | Conteúdo bloqueado. |
+| `guardrail.masked` | Conteúdo mascarado. |
+| `guardrail.failed` | Falha técnica. |
+| `guardrail.observe` | Política observacional registrada. |
+
+## Códigos Base
+
+| Código | Fase | Uso |
+|---|---|---|
+| `MSK` | input/output | Mascaramento. |
+| `VLOOP` | input | Detecção de loop. |
+| `PINJ` | input/output | Prompt injection. |
+| `REVPREC` | output | Revisão de precisão. |
+| `DLEX_OUT` | output | Controle de dados e linguagem na saída. |
+| `RAGSEC` | rag/output | Segurança de contexto recuperado. |
+
+## Testes
+
+| Teste | Objetivo |
+|---|---|
+| Unitário | Validar guardrail isolado. |
+| Config | Validar YAML e schema. |
+| Integração | Validar execução no workflow. |
+| Observabilidade | Validar eventos e traces. |
+| Negativo | Validar bloqueio. |
+| Observe-only | Validar não bloqueio. |
+
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|---|---|
+| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
+| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
+| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
+| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
+| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
+| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+
+
+## Critérios de Aceite
+
+- [ ] Guardrails globais são carregados por YAML.
+- [ ] Guardrails por agente sobrescrevem ou complementam globais.
+- [ ] GuardrailResult é gerado para cada execução.
+- [ ] Modo enforce bloqueia quando aplicável.
+- [ ] Modo observe não bloqueia.
+- [ ] Falhas técnicas seguem política configurada.
+- [ ] Guardrails LLM usam profile dedicado.
+- [ ] Eventos e métricas são emitidos.
+- [ ] Testes cobrem casos positivos e negativos.
+- [ ] Output guardrails executam antes da resposta final.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
+| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
+| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
+| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
+| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
+| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
+| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
+| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
+| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
--- a/specs/SPEC-006-Evals.md
+++ b/specs/SPEC-006-Evals.md
@@ -0,0 +1,226 @@
+# SPEC-006 — Evals
+
+## Escopo
+
+A camada de Evals executa avaliação online, avaliação offline, regressão, certificação e publicação de métricas. Ela padroniza a validação de agentes, prompts, tools, respostas e guardrails.
+
+## Componentes
+
+| Componente | Responsabilidade |
+|---|---|
+| Online Judges | Avaliação durante a execução. |
+| Offline Evaluator | Avaliação batch de conversas. |
+| Dataset Runner | Execução de datasets versionados. |
+| Regression Runner | Comparação entre versões. |
+| Certification Suite | Validação técnica e funcional. |
+| Metrics Engine | Cálculo de métricas. |
+| Persistence | Persistência de runs e itens. |
+| Exporter | Exportação TXT.GZ/JSON/HTML. |
+| Publisher | Publicação de scores no Langfuse. |
+
+## Fluxo Offline
+
+```mermaid
+flowchart TD
+    A[Start EvaluationRun] --> B[Collect Conversations]
+    B --> C[Normalize Items]
+    C --> D[Run Judges]
+    D --> E[Calculate Metrics]
+    E --> F[Persist Results]
+    F --> G[Export Reports]
+    G --> H[Publish Scores]
+    H --> I[Complete Run]
+```
+
+## EvaluationRun
+
+```json
+{
+  "run_id": "eval-20260619-001",
+  "agent_id": "telecom_contas",
+  "source": "langfuse",
+  "period_start": "2026-06-18T00:00:00Z",
+  "period_end": "2026-06-19T00:00:00Z",
+  "status": "running",
+  "limit": 500,
+  "metadata": {
+    "profile": "judge",
+    "dataset": "production-sample"
+  }
+}
+```
+
+## EvaluationItem
+
+```json
+{
+  "conversation_id": "default:telecom_contas:session-001",
+  "trace_id": "trace-001",
+  "agent_id": "telecom_contas",
+  "input": "Quero consultar minha fatura",
+  "output": "Sua fatura está aberta...",
+  "evidence": {
+    "mcp_results": [],
+    "rag_context": ""
+  },
+  "scores": {
+    "quality": 0.86,
+    "groundedness": 0.78,
+    "safety": 1.0,
+    "resolution": 0.91
+  },
+  "findings": []
+}
+```
+
+## Métricas
+
+| Métrica | Descrição | Faixa |
+|---|---|---|
+| `quality` | Clareza, completude e utilidade. | 0–1 |
+| `groundedness` | Aderência a evidências MCP/RAG. | 0–1 |
+| `safety` | Conformidade de segurança. | 0–1 |
+| `resolution` | Capacidade de resolver a intenção. | 0–1 |
+| `tool_correctness` | Uso correto de tools. | 0–1 |
+| `policy_compliance` | Aderência a regras de domínio. | 0–1 |
+
+## Dataset
+
+```yaml
+dataset:
+  name: telecom_contas_billing
+  version: 1.0.0
+  items:
+    - id: billing-001
+      input: "Quero consultar minha fatura"
+      business_context:
+        customer_key: "11999999999"
+        contract_key: "3000131180"
+      expected:
+        route: billing_agent
+        tools:
+          - consultar_fatura
+        min_scores:
+          quality: 0.75
+          groundedness: 0.70
+          safety: 1.0
+```
+
+## Judges
+
+```yaml
+judges:
+  - name: response_quality
+    enabled: true
+    threshold: 0.7
+    profile: judge
+
+  - name: groundedness
+    enabled: true
+    threshold: 0.6
+    profile: judge
+
+  - name: safety
+    enabled: true
+    threshold: 1.0
+    profile: judge
+```
+
+## CLI
+
+```bash
+af-evaluator run \
+  --agent-id telecom_contas \
+  --source langfuse \
+  --period-start 2026-06-18T00:00:00Z \
+  --period-end 2026-06-19T00:00:00Z \
+  --limit 500
+```
+
+## API
+
+| Método | Endpoint | Descrição |
+|---|---|---|
+| `POST` | `/evaluation/runs` | Cria run. |
+| `GET` | `/evaluation/runs/{run_id}` | Consulta run. |
+| `GET` | `/evaluation/runs/{run_id}/items` | Lista itens. |
+| `POST` | `/evaluation/datasets/{name}/run` | Executa dataset. |
+| `GET` | `/health` | Health check. |
+
+## Persistência
+
+| Tabela | Conteúdo |
+|---|---|
+| `EVAL_RUNS` | Runs executadas. |
+| `EVAL_ITEMS` | Conversas avaliadas. |
+| `EVAL_SCORES` | Scores por métrica. |
+| `EVAL_FINDINGS` | Achados. |
+| `EVAL_EXPORTS` | Arquivos exportados. |
+
+## Certificação
+
+A Certification Suite valida:
+
+- endpoints de health;
+- GatewayRequest;
+- roteamento;
+- MCP tools;
+- guardrails;
+- judges;
+- memória;
+- checkpoint;
+- Langfuse/OTEL;
+- datasets mínimos;
+- evidências JSON/HTML.
+
+## Eventos
+
+| Evento | Descrição |
+|---|---|
+| `eval.run.started` | Run iniciada. |
+| `eval.item.completed` | Item avaliado. |
+| `eval.run.completed` | Run concluída. |
+| `eval.run.failed` | Run falhou. |
+| `eval.score.published` | Score publicado. |
+
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|---|---|
+| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
+| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
+| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
+| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
+| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
+| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+
+
+## Critérios de Aceite
+
+- [ ] Evaluator executa runs por período/agente.
+- [ ] Langfuse é fonte suportada.
+- [ ] Datasets são versionados.
+- [ ] LLM Judges usam profile `judge`.
+- [ ] Scores são persistidos.
+- [ ] TXT.GZ/JSON/HTML são exportáveis.
+- [ ] Scores podem ser publicados no Langfuse.
+- [ ] Certification Suite gera evidências.
+- [ ] Métricas mínimas são padronizadas.
+- [ ] Falhas permitem retomada por checkpoint de run.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
+| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
+| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
+| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
+| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
+| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
+| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
+| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
+| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
--- a/specs/SPEC-007-Observability.md
+++ b/specs/SPEC-007-Observability.md
@@ -0,0 +1,202 @@
+# SPEC-007 — Observability
+
+## Escopo
+
+Observabilidade cobre logs, métricas, traces, eventos IC/NOC/GRL, Langfuse, OpenTelemetry, dashboards, alertas e evidências operacionais.
+
+## Correlação
+
+Campos obrigatórios:
+
+```text
+request_id
+trace_id
+session_id
+conversation_key
+tenant_id
+agent_id
+channel
+message_id
+route
+intent
+```
+
+## Logs
+
+Formato:
+
+```json
+{
+  "timestamp": "2026-06-19T12:00:00Z",
+  "level": "INFO",
+  "service": "agent-runtime",
+  "event": "runtime.route.selected",
+  "tenant_id": "default",
+  "agent_id": "telecom_contas",
+  "session_id": "default:telecom_contas:session-001",
+  "trace_id": "trace-001",
+  "route": "billing_agent",
+  "intent": "billing_invoice_explanation"
+}
+```
+
+## Traces
+
+```mermaid
+flowchart TD
+    T[conversation trace] --> A[gateway.received]
+    T --> B[channel.normalized]
+    T --> C[runtime.started]
+    T --> D[guardrails.input]
+    T --> E[routing]
+    T --> F[agent.execution]
+    F --> G[mcp.tool]
+    F --> H[llm.generation]
+    T --> I[guardrails.output]
+    T --> J[judges]
+    T --> K[persist]
+```
+
+## Métricas
+
+| Métrica | Dimensões |
+|---|---|
+| `requests_total` | service, tenant, agent, channel, status |
+| `request_latency_ms` | service, route, intent |
+| `active_sessions` | tenant, agent |
+| `llm_tokens_total` | provider, model, profile |
+| `llm_cost_estimated` | provider, model, tenant, agent |
+| `mcp_tool_calls_total` | tool, server, status |
+| `mcp_tool_latency_ms` | tool, server |
+| `guardrail_blocks_total` | code, phase, agent |
+| `judge_scores` | metric, agent, route |
+| `errors_total` | service, component, error_type |
+
+## Langfuse
+
+Dados registrados:
+
+- trace de conversa;
+- spans técnicos;
+- generations LLM;
+- prompts e respostas quando permitido;
+- tokens;
+- custos;
+- latência;
+- scores;
+- metadados;
+- erros.
+
+## OpenTelemetry
+
+Configuração:
+
+```yaml
+otel:
+  enabled: true
+  service_name: agent-runtime
+  exporter: otlp
+  endpoint: http://otel-collector:4317
+```
+
+## IC/NOC/GRL
+
+| Família | Eventos |
+|---|---|
+| IC | `IC.GATEWAY_RECEIVED`, `IC.AGENT_STARTED`, `IC.AGENT_COMPLETED` |
+| NOC | `NOC.RUNTIME_FAILED`, `NOC.MCP_TIMEOUT`, `NOC.LLM_FAILED` |
+| GRL | `GRL.INPUT_BLOCKED`, `GRL.OUTPUT_BLOCKED`, `GRL.MASK_APPLIED` |
+
+## Dashboards
+
+| Dashboard | Conteúdo |
+|---|---|
+| Platform Overview | tráfego, erros, latência, sessões. |
+| Agent Runtime | rotas, intents, memória, checkpoints. |
+| LLM Usage | tokens, custo, latência, provider/model. |
+| MCP Operations | chamadas, erros, cache, latência. |
+| Guardrails | bloqueios, observe-only, códigos. |
+| Evals | scores, trends, regressões. |
+| Channels | tráfego por canal, erros, retries. |
+
+## Alertas
+
+| Alerta | Condição |
+|---|---|
+| `GatewayHighErrorRate` | Erros 5xx acima do limite. |
+| `RuntimeLatencyHigh` | p95 acima do SLO. |
+| `LLMProviderUnavailable` | falhas consecutivas de provider. |
+| `MCPToolTimeoutSpike` | aumento de timeouts. |
+| `GuardrailBlockSpike` | aumento anômalo de bloqueios. |
+| `EvaluatorRunFailed` | run batch falhou. |
+| `CheckpointFailure` | falha persistente em checkpoint. |
+
+## Mascaramento
+
+Campos mascarados:
+
+- tokens;
+- API keys;
+- senhas;
+- secrets;
+- CPF/CNPJ, quando aplicável;
+- telefone, quando configurado;
+- payload bruto de canal;
+- documentos sensíveis.
+
+## Evidências
+
+Relatórios de homologação incluem:
+
+- health checks;
+- logs de execução;
+- traces Langfuse;
+- métricas;
+- resultados de guardrails;
+- resultados de judges;
+- chamadas MCP;
+- chamadas LLM;
+- relatório do evaluator;
+- relatório da certification suite.
+
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|---|---|
+| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
+| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
+| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
+| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
+| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
+| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+
+
+## Critérios de Aceite
+
+- [ ] Todos os serviços emitem logs estruturados.
+- [ ] Trace correlaciona gateway, runtime, MCP, LLM, guardrails e judges.
+- [ ] Langfuse recebe traces quando habilitado.
+- [ ] OTEL exporta spans quando habilitado.
+- [ ] Métricas mínimas estão disponíveis.
+- [ ] Dashboards estão definidos.
+- [ ] Alertas estão definidos.
+- [ ] Segredos e PII são mascarados.
+- [ ] Evaluator consome dados observáveis.
+- [ ] Certification Suite gera evidências.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
+| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
+| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
+| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
+| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
+| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
+| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
+| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
+| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
--- a/specs/SPEC-008-Deployment.md
+++ b/specs/SPEC-008-Deployment.md
@@ -0,0 +1,233 @@
+# SPEC-008 — Deployment
+
+## Escopo
+
+Deployment cobre empacotamento, CI/CD, Kubernetes/OKE, Docker, secrets, autenticação OCI, health checks, rollback e operação dos componentes.
+
+## Componentes Deployáveis
+
+| Componente | Artefato |
+|---|---|
+| Agent Gateway | Docker image + Kubernetes Deployment |
+| Channel Gateway | Docker image + Kubernetes Deployment |
+| AI Gateway | Docker image + Kubernetes Deployment |
+| MCP Gateway | Docker image + Kubernetes Deployment |
+| Agent Backend | Docker image + Kubernetes Deployment |
+| MCP Server | Docker image + Kubernetes Deployment |
+| Evaluator API | Docker image + Kubernetes Deployment |
+| Evaluator Batch | Kubernetes CronJob |
+| Frontend Demo | Docker image opcional |
+
+## Pipeline
+
+```mermaid
+flowchart LR
+    A[Commit] --> B[Lint]
+    B --> C[Type Check]
+    C --> D[Unit Tests]
+    D --> E[Contract Tests]
+    E --> F[Security Scan]
+    F --> G[Build Wheel]
+    G --> H[Build Images]
+    H --> I[Publish]
+    I --> J[Deploy Dev]
+    J --> K[Smoke Tests]
+    K --> L[Certification]
+    L --> M[Deploy HML/Prod]
+```
+
+## Stages
+
+```yaml
+stages:
+  - validate
+  - lint
+  - type_check
+  - unit_test
+  - contract_test
+  - security_scan
+  - build_package
+  - build_image
+  - publish
+  - deploy_dev
+  - smoke_test
+  - certification
+  - deploy_hml
+  - deploy_prod
+```
+
+## Kubernetes Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: agent-runtime
+  labels:
+    app: agent-runtime
+    component: runtime
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: agent-runtime
+  template:
+    metadata:
+      labels:
+        app: agent-runtime
+    spec:
+      serviceAccountName: agent-runtime-sa
+      containers:
+        - name: agent-runtime
+          image: registry/agent-runtime:1.0.0
+          ports:
+            - containerPort: 8000
+          envFrom:
+            - configMapRef:
+                name: agent-runtime-config
+            - secretRef:
+                name: agent-runtime-secrets
+          readinessProbe:
+            httpGet:
+              path: /ready
+              port: 8000
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 8000
+```
+
+## Service
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: agent-runtime
+spec:
+  selector:
+    app: agent-runtime
+  ports:
+    - port: 8000
+      targetPort: 8000
+```
+
+## OCI Authentication
+
+| Ambiente | Modo |
+|---|---|
+| Local | `config_file` |
+| Local com endpoint OpenAI-Compatible | API key |
+| OCI Compute | `instance_principal` |
+| OKE | `workload_identity` ou `resource_principal` |
+| Testes | `mock` |
+
+## Variáveis
+
+```env
+LLM_PROVIDER=oci_sdk
+OCI_AUTH_MODE=workload_identity
+ENABLE_LANGFUSE=true
+ENABLE_OTEL=true
+SESSION_REPOSITORY_PROVIDER=autonomous
+MEMORY_REPOSITORY_PROVIDER=autonomous
+CHECKPOINT_REPOSITORY_PROVIDER=autonomous
+```
+
+## Secrets
+
+| Secret | Uso |
+|---|---|
+| `LANGFUSE_PUBLIC_KEY` | Langfuse |
+| `LANGFUSE_SECRET_KEY` | Langfuse |
+| `OCI_GENAI_API_KEY` | OCI OpenAI-Compatible |
+| `ADB_PASSWORD` | Autonomous Database |
+| `MCP_BACKEND_TOKEN` | Integrações MCP |
+| `OTEL_AUTH_TOKEN` | Exportador OTEL, se aplicável |
+
+## Health Checks
+
+| Endpoint | Uso |
+|---|---|
+| `/health` | Processo vivo. |
+| `/ready` | Pronto para tráfego. |
+| `/version` | Versão de build. |
+| `/debug/env` | Ambiente sem segredos, quando habilitado. |
+
+## Rollback
+
+Itens considerados:
+
+- tag da imagem;
+- versão do pacote Python;
+- versão dos schemas;
+- versão dos YAMLs;
+- migrations;
+- datasets de eval;
+- contracts;
+- dashboards.
+
+## Smoke Tests
+
+```bash
+curl -f http://agent-runtime:8000/health
+curl -f http://agent-gateway:9000/health
+curl -f http://mcp-gateway:9200/health
+curl -f http://ai-gateway:9100/health
+```
+
+## Certification Stage
+
+A pipeline executa:
+
+- health checks;
+- contrato GatewayRequest;
+- roteamento;
+- MCP invoke;
+- LLM mock/real conforme ambiente;
+- guardrails;
+- judges;
+- memória/checkpoint;
+- relatório JSON/HTML.
+
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|---|---|
+| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
+| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
+| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
+| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
+| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
+| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+
+
+## Critérios de Aceite
+
+- [ ] Cada app possui Dockerfile.
+- [ ] Cada app possui manifest Kubernetes.
+- [ ] CI executa lint, type check e testes.
+- [ ] Contract tests validam contratos principais.
+- [ ] Security scan executa antes do publish.
+- [ ] Secrets não são versionados.
+- [ ] Workload Identity está configurado em OKE.
+- [ ] Health/readiness/liveness estão ativos.
+- [ ] Smoke tests rodam após deploy.
+- [ ] Rollback está documentado.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
+| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
+| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
+| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
+| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
+| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
+| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
+| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
+| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
--- a/specs/SPEC-009-Channel-Gateway.md
+++ b/specs/SPEC-009-Channel-Gateway.md
@@ -0,0 +1,197 @@
+# SPEC-009 — Channel Gateway
+
+## Escopo
+
+O Channel Gateway normaliza payloads de canais externos para GatewayRequest e traduz ChannelResponse para o formato de resposta do canal.
+
+## Modos de Operação
+
+| Modo | Descrição |
+|---|---|
+| Embedded | Normalização no próprio backend para demos e cenários simples. |
+| External | Serviço dedicado para canais corporativos. |
+
+## GatewayRequest
+
+```json
+{
+  "channel": "whatsapp",
+  "tenant_id": "default",
+  "agent_id": "telecom_contas",
+  "payload": {
+    "message": "Segunda via de fatura",
+    "session_id": "5511999999999",
+    "user_id": "5511999999999",
+    "message_id": "wamid.123",
+    "business_context": {
+      "customer_key": "5511999999999",
+      "interaction_key": "wamid.123",
+      "session_key": "5511999999999"
+    },
+    "metadata": {
+      "source_channel": "whatsapp",
+      "source_message_type": "interactive"
+    }
+  }
+}
+```
+
+## ChannelResponse
+
+```json
+{
+  "channel": "whatsapp",
+  "session_id": "default:telecom_contas:5511999999999",
+  "text": "Encontrei sua fatura...",
+  "metadata": {
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "route": "billing_agent",
+    "intent": "billing_invoice_explanation"
+  }
+}
+```
+
+## Fluxo Externo
+
+```mermaid
+sequenceDiagram
+    participant Canal
+    participant CG as Channel Gateway
+    participant AG as Agent Gateway
+    participant RT as Agent Runtime
+    Canal->>CG: payload bruto
+    CG->>CG: autenticação, parse, dedupe
+    CG->>AG: GatewayRequest
+    AG->>RT: execução
+    RT-->>AG: ChannelResponse
+    AG-->>CG: ChannelResponse
+    CG-->>Canal: resposta do canal
+```
+
+## Responsabilidades
+
+| Responsabilidade | Detalhe |
+|---|---|
+| Auth | Validar assinatura, token ou origem. |
+| Parse | Interpretar payload bruto. |
+| Dedup | Evitar reprocessamento por message_id. |
+| Normalize | Criar GatewayRequest. |
+| Business Context | Mapear chaves canônicas. |
+| Forward | Chamar Agent Gateway. |
+| Translate | Converter ChannelResponse para canal. |
+| Observe | Emitir logs, métricas e traces. |
+
+## Idempotência
+
+Chave:
+
+```text
+tenant_id:channel:user_id:message_id
+```
+
+Comportamentos:
+
+| Situação | Ação |
+|---|---|
+| Primeira mensagem | Processar. |
+| Duplicada em andamento | Retornar 202 ou resposta controlada. |
+| Duplicada concluída | Retornar resposta anterior. |
+
+## Versionamento
+
+Header:
+
+```http
+X-Agent-Framework-Contract: gateway-request-v1
+```
+
+Campo alternativo:
+
+```json
+{
+  "payload": {
+    "metadata": {
+      "contract_version": "gateway-request-v1"
+    }
+  }
+}
+```
+
+## Segurança
+
+Validações:
+
+- assinatura do webhook;
+- origem permitida;
+- tamanho máximo;
+- tipo de evento permitido;
+- anexos permitidos;
+- sanitização de texto;
+- remoção de tokens;
+- máscara de dados sensíveis;
+- rate limit;
+- deduplicação.
+
+## Erros
+
+| Código HTTP | Uso |
+|---|---|
+| 400 | Payload inválido do canal. |
+| 401 | Autenticação ausente. |
+| 403 | Origem não autorizada. |
+| 422 | GatewayRequest inválido. |
+| 429 | Rate limit. |
+| 500 | Erro interno. |
+| 503 | Runtime indisponível. |
+
+## Anti-patterns
+
+- Agente lendo payload bruto.
+- Workflow tratando `channel == whatsapp`.
+- MCP recebendo payload bruto.
+- Tokens do canal em metadata.
+- Gateway externo executando regra de agente.
+- Frontend enviando campos fora do contrato.
+
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|---|---|
+| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
+| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
+| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
+| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
+| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
+| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+
+
+## Critérios de Aceite
+
+- [ ] Payload bruto é convertido para GatewayRequest.
+- [ ] GatewayRequest é validado.
+- [ ] message_id é usado para idempotência.
+- [ ] business_context contém chaves canônicas.
+- [ ] Resposta do runtime é traduzida para o canal.
+- [ ] Payload bruto não chega ao Agent Runtime.
+- [ ] Auth/rate limit/dedup estão implementados.
+- [ ] Erros são padronizados.
+- [ ] Contrato possui versão.
+- [ ] Logs/traces usam request_id e trace_id.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
+| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
+| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
+| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
+| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
+| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
+| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
+| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
+| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
--- a/specs/SPEC-010-Agent-Development.md
+++ b/specs/SPEC-010-Agent-Development.md
@@ -0,0 +1,299 @@
+# SPEC-010 — Agent Development
+
+## Escopo
+
+Esta SPEC define o padrão para criação de agentes usando templates, configuração YAML, BusinessContext, MCP, guardrails, judges, RAG, memória, observabilidade e evals.
+
+## Estrutura do Template
+
+```text
+templates/backend/
+├── app/
+│   ├── main.py
+│   ├── state.py
+│   ├── workflows/
+│   │   └── agent_graph.py
+│   ├── agents/
+│   │   ├── runtime.py
+│   │   └── domain_agent.py
+│   └── examples/
+├── config/
+│   ├── agents.yaml
+│   ├── routing.yaml
+│   ├── tools.yaml
+│   ├── mcp_servers.yaml
+│   ├── mcp_parameter_mapping.yaml
+│   ├── identity.yaml
+│   ├── guardrails.yaml
+│   ├── judges.yaml
+│   ├── prompt_policy.yaml
+│   └── agents/<agent_id>/
+├── Dockerfile
+├── requirements.txt
+└── .env.example
+```
+
+## Responsabilidades do Framework
+
+- LangGraph;
+- memória;
+- checkpoint;
+- sessão;
+- router;
+- supervisor;
+- guardrails;
+- judges;
+- telemetry;
+- MCP integration;
+- RAG genérico;
+- cache;
+- providers LLM;
+- event bus.
+
+## Responsabilidades do Agente
+
+- prompts de domínio;
+- regras de negócio;
+- schemas específicos;
+- decisão de uso de evidências;
+- tratamento de campos obrigatórios;
+- mensagens de domínio;
+- ICs de jornada;
+- datasets de eval específicos.
+
+## Registro do Agente
+
+```yaml
+agents:
+  financeiro_agent:
+    enabled: true
+    description: "Agente financeiro"
+    profile: financeiro_agent
+    rag_namespace: financeiro
+    allowed_tools:
+      - consultar_fatura
+      - consultar_pagamentos
+```
+
+## Roteamento
+
+```yaml
+intents:
+  financeiro_consulta_fatura:
+    route: financeiro_agent
+    keywords:
+      - fatura
+      - boleto
+      - cobrança
+    mcp_tools:
+      - consultar_fatura
+```
+
+## Tool Mapping
+
+```yaml
+tools:
+  consultar_fatura:
+    map:
+      customer_key: msisdn
+      contract_key: invoice_id
+      interaction_key: ura_call_id
+      session_key: session_id
+```
+
+## Classe de Agente
+
+```python
+class FinanceiroAgent(AgentRuntimeMixin):
+    name = "financeiro_agent"
+
+    def __init__(
+        self,
+        llm,
+        telemetry=None,
+        tool_router=None,
+        rag_service=None,
+        cache=None,
+        settings=None,
+        observer=None,
+        memory=None,
+        summary_memory=None,
+    ):
+        self.llm = llm
+        self.telemetry = telemetry
+        self.tool_router = tool_router
+        self.rag_service = rag_service
+        self.cache = cache
+        self.settings = settings
+        self.observer = observer
+        self.memory = memory
+        self.summary_memory = summary_memory
+
+    async def run(self, state):
+        await self._emit_ic("IC.FINANCEIRO_AGENT_STARTED", state, {})
+        tool_context = await self._collect_mcp_context(state)
+        rag_context, rag_metadata = await self._retrieve_rag_context(state)
+        response = await self._invoke_llm_cached(
+            state,
+            "FinanceiroAgent",
+            [
+                {"role": "system", "content": "Você é um agente financeiro."},
+                {"role": "user", "content": state.get("sanitized_input") or state.get("user_text", "")},
+            ],
+        )
+        await self._emit_ic("IC.FINANCEIRO_AGENT_COMPLETED", state, {})
+        return {
+            "response_text": response,
+            "mcp_results": tool_context,
+            "rag_metadata": rag_metadata,
+        }
+```
+
+## Ordem de Confiança dos Dados
+
+1. `tool_arguments`
+2. `business_context`
+3. `context`
+4. `session.metadata`
+5. `state`
+6. extração complementar do texto
+
+## Prompt Policy
+
+```yaml
+prompt_policy:
+  system_prompt_path: prompts/system.md
+  response_style: concise
+  require_evidence: true
+  allow_tool_usage: true
+```
+
+## Guardrails por Agente
+
+```yaml
+input:
+  - code: FIN_INPUT_POLICY
+    enabled: true
+    mode: observe
+
+output:
+  - code: FIN_OUTPUT_COMPLIANCE
+    enabled: true
+    mode: enforce
+```
+
+## Judges por Agente
+
+```yaml
+judges:
+  - name: response_quality
+    enabled: true
+    threshold: 0.75
+  - name: groundedness
+    enabled: true
+    threshold: 0.70
+```
+
+## Dataset de Eval
+
+```yaml
+dataset:
+  name: financeiro_agent_regression
+  version: 1.0.0
+  items:
+    - id: fin-001
+      input: "Quero consultar minha fatura"
+      business_context:
+        customer_key: "11999999999"
+        contract_key: "3000131180"
+      expected:
+        route: financeiro_agent
+        tools:
+          - consultar_fatura
+        min_scores:
+          quality: 0.75
+          groundedness: 0.70
+```
+
+## Testes
+
+| Teste | Escopo |
+|---|---|
+| Unitário | Classe do agente. |
+| Routing | Intent e rota. |
+| MCP Mapping | BusinessContext para argumentos. |
+| Guardrails | Entrada e saída. |
+| Judges | Scores mínimos. |
+| Runtime | Execução completa. |
+| Memory | Continuidade de conversa. |
+| Checkpoint | Resume/replay. |
+| Observability | Trace e eventos. |
+| Certification | Evidências finais. |
+
+## Definition of Done
+
+- agente registrado;
+- rota configurada;
+- tools declaradas;
+- mapping definido;
+- prompts versionados;
+- guardrails configurados;
+- judges configurados;
+- dataset criado;
+- testes executados;
+- traces gerados;
+- certification suite aprovada;
+- documentação do agente atualizada.
+
+## Anti-patterns
+
+- agente criando sessão;
+- agente abrindo SSE;
+- agente compilando LangGraph;
+- agente chamando sistema externo diretamente;
+- prompt hardcoded sem política;
+- lógica genérica duplicada no agente;
+- payload bruto de canal dentro do agente;
+- ausência de dataset de eval.
+
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|---|---|
+| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
+| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
+| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
+| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
+| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
+| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
+| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+
+
+## Critérios de Aceite
+
+- [ ] Novo agente é criado sem alterar core do framework.
+- [ ] Configuração ocorre por YAML e `.env`.
+- [ ] Agente usa BusinessContext.
+- [ ] Agente acessa MCP por router/gateway.
+- [ ] Agente não conhece payload bruto de canal.
+- [ ] Guardrails e judges são configurados.
+- [ ] Dataset de eval existe.
+- [ ] Testes mínimos executam.
+- [ ] Trace completo é gerado.
+- [ ] Definition of Done é atendida.
+
+
+## Glossário
+
+| Termo | Definição |
+|---|---|
+| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
+| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
+| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
+| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
+| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
+| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
+| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
+| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
+| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
--- a/specs/SPEC-011-Governance-Model.md
+++ b/specs/SPEC-011-Governance-Model.md
@@ -0,0 +1,347 @@
+# SPEC-011 — Governance Model
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+Governança é o conjunto de papéis, responsabilidades, controles, aprovações, evidências e processos que permite que a Agent Platform OCI seja usada por múltiplos times sem perder padronização, segurança, rastreabilidade e capacidade de evolução.
+
+A governança não substitui a engenharia. Ela define como a engenharia evolui de forma controlada.
+
+Em uma plataforma de agentes, governança cobre:
+
+- quem pode criar agentes;
+- quem pode alterar prompts;
+- quem pode liberar MCP tools;
+- quem aprova mudanças de guardrails;
+- quem aprova modelos;
+- quem aprova datasets;
+- quem promove para produção;
+- quais evidências são obrigatórias;
+- como auditar decisões da plataforma.
+
+# 2. Problema que resolve
+
+Sem governança, cada time tende a criar agentes de forma diferente.
+
+Problemas comuns:
+
+- prompts sem versionamento;
+- MCP tools sem owner;
+- datasets ausentes;
+- agentes sem avaliação;
+- produção sem certification;
+- mudanças de modelo sem rastreabilidade;
+- guardrails duplicados;
+- regras de negócio dentro do runtime;
+- uso diferente da plataforma por cada fornecedor;
+- dificuldade de manutenção.
+
+A governança cria um modelo único de adoção.
+
+# 3. Domínios de governança
+
+| Domínio | Escopo |
+| --- | --- |
+| Platform Governance | Framework, Runtime, Gateways, Evaluator, Certification Suite. |
+| Agent Governance | Agentes, prompts, regras de negócio, datasets e configs. |
+| Model Governance | LLM profiles, providers, fallback, custo e uso. |
+| MCP Governance | Tools, MCP servers, owners, SLAs, autorização e contratos. |
+| Data Governance | BusinessContext, RAG, datasets, memória e retenção. |
+| Security Governance | Identidade, autorização, secrets, auditoria e PII. |
+| Operational Governance | Deploy, monitoramento, alertas, SLOs e incidentes. |
+| Evaluation Governance | Judges, evaluator, certification e métricas. |
+
+
+# 4. Modelo de ownership
+
+## 4.1. Platform Team
+
+Responsável por:
+
+- Agent Framework;
+- Agent Runtime;
+- Agent Gateway;
+- Channel Gateway;
+- AI Gateway;
+- MCP Gateway;
+- Evaluator;
+- Certification Suite;
+- contratos canônicos;
+- documentação da plataforma;
+- templates oficiais.
+
+## 4.2. Domain Team
+
+Responsável por:
+
+- comportamento do agente;
+- prompts;
+- regras de negócio;
+- datasets;
+- configurações específicas;
+- validação funcional;
+- critérios de sucesso.
+
+## 4.3. Integration Team
+
+Responsável por:
+
+- MCP servers;
+- APIs externas;
+- SLAs de tools;
+- contratos de integração;
+- credenciais de backend;
+- disponibilidade de sistemas externos.
+
+## 4.4. SRE / DevOps
+
+Responsável por:
+
+- CI/CD;
+- deploy;
+- observabilidade;
+- alertas;
+- capacidade;
+- SLOs;
+- runbooks;
+- rollback.
+
+## 4.5. Security / Architecture
+
+Responsável por:
+
+- segurança;
+- arquitetura;
+- policies;
+- Workload Identity;
+- secrets;
+- revisão de risco;
+- aprovação de exceções.
+
+# 5. RACI
+
+| Atividade | Platform | Domain | Integration | SRE | Security |
+| --- | --- | --- | --- | --- | --- |
+| Framework change | R/A | C | I | C | C |
+| Runtime change | R/A | C | I | C | C |
+| New agent | C | R/A | C | I | I |
+| New MCP tool | C | C | R/A | I | C |
+| Prompt change | I | R/A | I | I | C |
+| Guardrail change | R | C | I | I | A |
+| Model profile change | R | C | I | I | C |
+| Production deploy | I | C | C | R/A | C |
+| Security review | I | C | C | C | R/A |
+| Certification | R/A | C | C | I | I |
+
+
+# 6. Governança de agentes
+
+Todo agente deve possuir:
+
+```yaml
+agent:
+  id: telecom_contas
+  owner: billing_team
+  technical_owner: ai_platform_team
+  business_objective: "Atendimento sobre faturas, pagamentos e cobranças"
+  status: active
+  version: 1.0.0
+```
+
+Artefatos obrigatórios:
+
+- `agents.yaml`;
+- `routing.yaml`;
+- `prompt_policy.yaml`;
+- `guardrails.yaml`;
+- `judges.yaml`;
+- `tools.yaml`;
+- `mcp_parameter_mapping.yaml`;
+- dataset de regressão;
+- testes;
+- evidências de evaluator;
+- evidências de certification.
+
+# 7. Governança de prompts
+
+Prompts devem ser versionados e rastreáveis.
+
+```yaml
+prompt:
+  name: billing_system_prompt
+  version: 1.3.0
+  owner: billing_team
+  reviewed_at: 2026-06-19
+  status: approved
+```
+
+Mudanças de prompt exigem:
+
+1. revisão do domain owner;
+2. execução de dataset;
+3. evaluator;
+4. comparação contra baseline;
+5. registro da versão.
+
+# 8. Governança de guardrails
+
+Guardrails globais pertencem à plataforma/segurança.
+
+Guardrails por agente pertencem ao domínio, mas precisam seguir o contrato da plataforma.
+
+```yaml
+guardrail:
+  code: REVPREC
+  version: 2.0.0
+  owner: platform_security
+  phase: output
+  mode: enforce
+```
+
+Mudanças em guardrails `enforce` exigem certification.
+
+# 9. Governança de judges
+
+Judges devem ter objetivo, métrica, threshold e owner.
+
+```yaml
+judge:
+  name: groundedness
+  version: 1.1.0
+  threshold: 0.70
+  owner: platform_quality
+```
+
+Mudanças de threshold exigem reexecução do evaluator.
+
+# 10. Governança de modelos
+
+Agentes não referenciam modelo diretamente.
+
+O modelo é resolvido por profile.
+
+```yaml
+profiles:
+  judge:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+```
+
+Mudanças de modelo exigem:
+
+- validação de custo;
+- evaluator;
+- validação de qualidade;
+- validação de latência;
+- atualização de release notes.
+
+# 11. Governança de MCP
+
+Cada tool deve ter owner, SLA, timeout e contrato.
+
+```yaml
+tool:
+  name: consultar_fatura
+  version: 1.0.0
+  owner: billing_platform
+  sla: p95_2s
+  timeout_seconds: 30
+  idempotent: true
+```
+
+Tools mutáveis exigem política de confirmação.
+
+# 12. Governança de datasets
+
+Datasets são ativos de qualidade.
+
+```yaml
+dataset:
+  name: telecom_contas_regression
+  version: 1.0.0
+  owner: billing_team
+```
+
+Datasets devem conter:
+
+- entrada;
+- BusinessContext;
+- rota esperada;
+- tools esperadas;
+- critérios mínimos;
+- casos negativos;
+- casos de segurança.
+
+# 13. Processo de aprovação
+
+```mermaid
+flowchart LR
+    Dev[Development] --> Tests[Tests]
+    Tests --> Eval[Evaluator]
+    Eval --> Cert[Certification]
+    Cert --> Sec[Security Review]
+    Sec --> Arch[Architecture Approval]
+    Arch --> HML[Homologation]
+    HML --> PROD[Production]
+```
+
+# 14. Evidências obrigatórias
+
+- relatório de testes;
+- relatório evaluator;
+- relatório certification;
+- trace Langfuse;
+- logs e métricas;
+- checklist de segurança;
+- release notes;
+- versão dos artefatos.
+
+# 15. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Prompt sem owner | Dificulta manutenção e aprovação. | Definir owner no metadata. |
+| Tool sem SLA | Operação sem expectativa de resposta. | Registrar SLA em tools.yaml. |
+| Dataset ausente | Sem regressão objetiva. | Criar dataset mínimo. |
+| Guardrail hardcoded | Governança fora do YAML. | Mover para config. |
+| Modelo definido no agente | Quebra governança de modelos. | Usar AI Gateway profiles. |
+
+
+# 16. Critérios de aceite
+
+- [ ] Cada agente possui owner funcional e técnico.
+- [ ] Prompts estão versionados.
+- [ ] Tools MCP possuem owner, SLA e versão.
+- [ ] Guardrails possuem owner e modo.
+- [ ] Judges possuem threshold e versão.
+- [ ] Datasets estão versionados.
+- [ ] Evaluator roda por agente.
+- [ ] Certification aprova antes de produção.
+- [ ] Release possui evidências.
+- [ ] Exceções são documentadas.
--- a/specs/SPEC-012-Canonical-Contracts.md
+++ b/specs/SPEC-012-Canonical-Contracts.md
@@ -0,0 +1,312 @@
+# SPEC-012 — Canonical Contracts
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+Contratos canônicos são estruturas padronizadas usadas para desacoplar canais, gateways, runtime, agentes, tools, LLMs, evaluator e observabilidade.
+
+A plataforma usa contratos para garantir que componentes independentes possam evoluir sem quebrar uns aos outros.
+
+# 2. Problema que resolve
+
+Sem contratos:
+
+- cada canal envia payload diferente;
+- agentes passam a conhecer WhatsApp, Voice, Teams ou CRM;
+- MCP tools recebem parâmetros inconsistentes;
+- LLM calls ficam acopladas ao provider;
+- evaluator não consegue comparar respostas;
+- observabilidade fica fragmentada.
+
+Com contratos:
+
+```text
+Canal → GatewayRequest → Runtime → BusinessContext → ToolInvocation → ToolResult
+```
+
+# 3. Catálogo de contratos
+
+| Contrato | Uso |
+| --- | --- |
+| GatewayRequest | Entrada canônica da plataforma. |
+| ChannelResponse | Resposta canônica ao canal. |
+| BusinessContext | Identidade canônica de negócio. |
+| AgentState | Estado interno do runtime. |
+| Session | Sessão técnica/conversacional. |
+| Checkpoint | Persistência de estado LangGraph. |
+| ToolInvocation | Chamada canônica de tool MCP. |
+| ToolResult | Resposta canônica de tool MCP. |
+| LLMRequest | Chamada canônica ao AI Gateway. |
+| LLMResponse | Resposta canônica do AI Gateway. |
+| EvaluationRun | Execução do evaluator. |
+| EvaluationResult | Resultado de avaliação. |
+| CertificationResult | Resultado de certificação. |
+| EventEnvelope | Envelope de eventos IC/NOC/GRL. |
+
+
+# 4. GatewayRequest
+
+## 4.1. Uso
+
+Usado por Channel Gateway e Agent Gateway para enviar mensagens ao Runtime.
+
+```json
+{
+  "channel": "web",
+  "tenant_id": "default",
+  "agent_id": "telecom_contas",
+  "payload": {
+    "message": "Quero consultar minha fatura",
+    "session_id": "session-001",
+    "user_id": "user-001",
+    "message_id": "msg-001",
+    "business_context": {
+      "customer_key": "11999999999",
+      "contract_key": "3000131180",
+      "interaction_key": "301953872",
+      "session_key": "session-001"
+    },
+    "metadata": {
+      "request_id": "req-001",
+      "contract_version": "gateway-request-v1"
+    }
+  }
+}
+```
+
+## 4.2. Campos obrigatórios
+
+- `channel`;
+- `payload.message`;
+- `payload.session_id`;
+- `payload.message_id`;
+- `tenant_id` quando multi-tenant;
+- `agent_id` quando não houver roteamento global.
+
+# 5. ChannelResponse
+
+```json
+{
+  "channel": "web",
+  "session_id": "default:telecom_contas:session-001",
+  "text": "Resposta final do agente.",
+  "metadata": {
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "route": "billing_agent",
+    "intent": "billing_invoice_explanation",
+    "guardrails": [],
+    "judges": []
+  }
+}
+```
+
+# 6. BusinessContext
+
+## 6.1. Uso
+
+BusinessContext transporta identidade de negócio sem acoplar a plataforma ao formato de cada canal.
+
+```yaml
+business_context:
+  customer_key: "11999999999"
+  contract_key: "3000131180"
+  interaction_key: "301953872"
+  account_key: null
+  resource_key: null
+  session_key: "session-001"
+  metadata:
+    source_channel: web
+```
+
+## 6.2. Mapeamento para MCP
+
+```yaml
+tools:
+  consultar_fatura:
+    map:
+      customer_key: msisdn
+      contract_key: invoice_id
+      interaction_key: ura_call_id
+      session_key: session_id
+```
+
+# 7. AgentState
+
+```python
+class AgentState(TypedDict, total=False):
+    user_text: str
+    sanitized_input: str
+    response_text: str
+    tenant_id: str
+    agent_id: str
+    channel: str
+    session_id: str
+    conversation_key: str
+    message_id: str
+    route: str
+    intent: str
+    business_context: dict
+    mcp_tools: list[str]
+    mcp_results: list[dict]
+    rag_context: str
+    guardrails: list[dict]
+    judges: list[dict]
+```
+
+# 8. ToolInvocation
+
+```json
+{
+  "tenant_id": "default",
+  "agent_id": "telecom_contas",
+  "tool_name": "consultar_fatura",
+  "arguments": {
+    "msisdn": "11999999999",
+    "invoice_id": "3000131180"
+  },
+  "business_context": {
+    "customer_key": "11999999999",
+    "contract_key": "3000131180"
+  },
+  "metadata": {
+    "request_id": "req-001",
+    "trace_id": "trace-001"
+  }
+}
+```
+
+# 9. ToolResult
+
+```json
+{
+  "tool_name": "consultar_fatura",
+  "ok": true,
+  "data": {
+    "invoice_id": "3000131180",
+    "valor_total": 249.90,
+    "status": "ABERTA"
+  },
+  "cache": {
+    "hit": false,
+    "ttl_seconds": 300
+  },
+  "latency_ms": 140
+}
+```
+
+# 10. LLMRequest
+
+```json
+{
+  "tenant_id": "default",
+  "agent_id": "telecom_contas",
+  "profile": "judge",
+  "operation": "judge.response_quality",
+  "messages": [
+    {"role": "system", "content": "Você é um avaliador."},
+    {"role": "user", "content": "Avalie a resposta."}
+  ],
+  "metadata": {
+    "request_id": "req-001",
+    "trace_id": "trace-001"
+  }
+}
+```
+
+# 11. LLMResponse
+
+```json
+{
+  "provider": "oci_openai",
+  "model": "openai.gpt-4.1",
+  "profile": "judge",
+  "content": "Resultado",
+  "usage": {
+    "input_tokens": 1200,
+    "output_tokens": 300,
+    "total_tokens": 1500
+  },
+  "latency_ms": 820
+}
+```
+
+# 12. EvaluationRun
+
+```json
+{
+  "run_id": "eval-001",
+  "agent_id": "telecom_contas",
+  "source": "langfuse",
+  "period_start": "2026-06-18T00:00:00Z",
+  "period_end": "2026-06-19T00:00:00Z",
+  "status": "running"
+}
+```
+
+# 13. EventEnvelope
+
+```json
+{
+  "event_type": "IC.AGENT_COMPLETED",
+  "timestamp": "2026-06-19T12:00:00Z",
+  "tenant_id": "default",
+  "agent_id": "telecom_contas",
+  "session_id": "session-001",
+  "trace_id": "trace-001",
+  "payload": {}
+}
+```
+
+# 14. Regras de evolução
+
+- campos novos devem ser opcionais;
+- campos obrigatórios não podem ser removidos dentro da mesma major;
+- mudança semântica exige nova versão;
+- contratos são versionados independentemente.
+
+# 15. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Payload bruto no Runtime | Acopla canais ao core. | Usar GatewayRequest. |
+| Tool recebendo BusinessContext bruto sem mapping | Quebra contrato da tool. | Usar mcp_parameter_mapping.yaml. |
+| LLM direto no agente | Quebra AI Gateway. | Usar LLMRequest/profile. |
+| Campos sem versão | Dificulta migração. | Declarar contract_version. |
+
+
+# 16. Critérios de aceite
+
+- [ ] GatewayRequest documentado e versionado.
+- [ ] ChannelResponse documentado e versionado.
+- [ ] BusinessContext usado por canais e MCP.
+- [ ] ToolInvocation e ToolResult padronizados.
+- [ ] LLMRequest e LLMResponse padronizados.
+- [ ] EvaluationRun e EvaluationResult padronizados.
+- [ ] EventEnvelope usado para IC/NOC/GRL.
+- [ ] Contratos possuem regras de evolução.
--- a/specs/SPEC-013-Versioning-and-Compatibility-Model.md
+++ b/specs/SPEC-013-Versioning-and-Compatibility-Model.md
@@ -0,0 +1,175 @@
+# SPEC-013 — Versioning and Compatibility Model
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+Versionamento define como a plataforma evolui sem quebrar projetos existentes. Compatibilidade define quais versões de framework, runtime, gateways, contracts, templates, prompts, tools e evaluator podem operar juntas.
+
+# 2. Problema que resolve
+
+Sem modelo de versionamento:
+
+- uma mudança em GatewayRequest quebra canais;
+- uma mudança em MCP tool quebra agentes;
+- um prompt alterado muda comportamento sem rastreabilidade;
+- evaluator muda score sem histórico;
+- templates ficam incompatíveis com runtime;
+- produção usa imagem `latest` sem controle.
+
+# 3. Semantic Versioning
+
+Formato:
+
+```text
+MAJOR.MINOR.PATCH
+```
+
+Regras:
+
+| Parte | Significado |
+| --- | --- |
+| MAJOR | Mudança incompatível. |
+| MINOR | Nova capacidade compatível. |
+| PATCH | Correção sem mudança de contrato. |
+
+
+# 4. Artefatos versionados
+
+| Artefato | Modelo |
+| --- | --- |
+| 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 | versão da 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
+
+Exemplos:
+
+```text
+gateway-request-v1
+business-context-v1
+tool-invocation-v1
+llm-request-v1
+```
+
+Permitido na mesma versão major:
+
+- adicionar campos opcionais;
+- adicionar metadata;
+- adicionar enum documentado.
+
+Não permitido:
+
+- remover campo obrigatório;
+- 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. Política de depreciação
+
+Ciclo:
+
+```text
+Active → Deprecated → Retired
+```
+
+Período recomendado:
+
+```text
+12 meses
+```
+
+# 8. Política de migração
+
+Mudanças major exigem:
+
+- migration guide;
+- compatibility matrix;
+- rollback strategy;
+- certification;
+- evaluator;
+- release notes.
+
+# 9. Estratégia de rollback
+
+Rollback deve considerar:
+
+- imagem Docker;
+- versão do pacote;
+- versão dos YAMLs;
+- versão do contrato;
+- migration de banco;
+- dataset;
+- prompts.
+
+# 10. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Usar latest em produção | Deploy não reprodutível. | Usar tag explícita. |
+| Mudar prompt sem versão | Sem rastreabilidade. | Versionar prompt. |
+| Adicionar campo obrigatório em contrato v1 | Quebra clientes. | Criar v2. |
+| Atualizar evaluator sem baseline | Scores não comparáveis. | Registrar versão e metodologia. |
+
+
+# 11. Critérios de aceite
+
+- [ ] Todos os componentes têm versão.
+- [ ] Contratos têm versão independente.
+- [ ] Matriz de compatibilidade publicada.
+- [ ] Release notes publicadas.
+- [ ] Migrações major possuem guide.
+- [ ] Rollback definido.
+- [ ] Prompts e datasets versionados.
+- [ ] Evaluator e certification registram versão.
--- a/specs/SPEC-014-Templates-and-Agent-Creation-Model.md
+++ b/specs/SPEC-014-Templates-and-Agent-Creation-Model.md
@@ -0,0 +1,248 @@
+# SPEC-014 — Templates and Agent Creation Model
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+Templates são scaffolds oficiais para criar agentes, MCP servers e backends compatíveis com a Agent Platform OCI.
+
+Eles aceleram o início de um projeto, mas não substituem o framework. O template contém a estrutura mínima de aplicação e os pontos de extensão esperados.
+
+# 2. Problema que resolve
+
+Sem template:
+
+- cada squad cria estrutura diferente;
+- imports e configs variam;
+- MCP mapping é esquecido;
+- datasets não são criados;
+- guardrails e judges ficam ausentes;
+- deploy não segue padrão;
+- onboarding demora.
+
+# 3. Templates oficiais
+
+| Template | Uso |
+| --- | --- |
+| backend | Criação de agentes com runtime. |
+| backend_day_zero | Bootstrap acelerado com exemplos. |
+| mcp_server | Criação de MCP server. |
+| channel_adapter | Adapter de canal quando aplicável. |
+
+
+# 4. Estrutura padrão de agente
+
+```text
+my_agent/
+├── app/
+│   ├── main.py
+│   ├── state.py
+│   ├── workflows/
+│   │   └── agent_graph.py
+│   └── agents/
+│       └── my_agent.py
+├── config/
+│   ├── agents.yaml
+│   ├── routing.yaml
+│   ├── tools.yaml
+│   ├── mcp_servers.yaml
+│   ├── mcp_parameter_mapping.yaml
+│   ├── guardrails.yaml
+│   ├── judges.yaml
+│   └── llm_profiles.yaml
+├── prompts/
+├── datasets/
+├── tests/
+├── Dockerfile
+└── README.md
+```
+
+# 5. O que fica no framework
+
+- LangGraph runtime;
+- sessão;
+- memória;
+- checkpoint;
+- guardrails genéricos;
+- judges genéricos;
+- MCP client/router;
+- RAG genérico;
+- telemetry;
+- providers;
+- event bus.
+
+# 6. O que fica no agente
+
+- prompts;
+- regras de negócio;
+- intents;
+- tools específicas;
+- datasets;
+- testes;
+- guardrails de domínio;
+- judges de domínio.
+
+# 7. Passo a passo para criar agente do zero
+
+## Passo 1 — Copiar template
+
+```bash
+cp -R templates/backend financeiro_agent
+cd financeiro_agent
+```
+
+## Passo 2 — Definir escopo
+
+```text
+Agente: financeiro_agent
+Objetivo: responder dúvidas sobre faturas, pagamentos e cobranças.
+Fora de escopo: vendas, cancelamento e suporte técnico.
+```
+
+## Passo 3 — Registrar agente
+
+```yaml
+agents:
+  financeiro_agent:
+    enabled: true
+    description: "Agente financeiro"
+    rag_namespace: financeiro
+    allowed_tools:
+      - consultar_fatura
+      - consultar_pagamentos
+```
+
+## Passo 4 — Configurar rotas
+
+```yaml
+intents:
+  financeiro_consulta_fatura:
+    route: financeiro_agent
+    keywords:
+      - fatura
+      - boleto
+      - cobrança
+    mcp_tools:
+      - consultar_fatura
+```
+
+## Passo 5 — Configurar tools
+
+```yaml
+tools:
+  consultar_fatura:
+    server: telecom
+    enabled: true
+    idempotent: true
+    cache_ttl_seconds: 300
+```
+
+## Passo 6 — Mapear BusinessContext
+
+```yaml
+tools:
+  consultar_fatura:
+    map:
+      customer_key: msisdn
+      contract_key: invoice_id
+      session_key: session_id
+```
+
+## Passo 7 — Criar prompt
+
+```text
+Você é um agente financeiro.
+Use MCP como fonte transacional.
+Use RAG para políticas e procedimentos.
+Não invente valores, datas ou status.
+```
+
+## Passo 8 — Implementar agente
+
+```python
+class FinanceiroAgent(AgentRuntimeMixin):
+    name = "financeiro_agent"
+
+    async def run(self, state):
+        mcp = await self._collect_mcp_context(state)
+        rag, rag_metadata = await self._retrieve_rag_context(state)
+        answer = await self._invoke_llm_cached(
+            state,
+            "FinanceiroAgent",
+            [
+                {"role": "system", "content": "Você é um agente financeiro."},
+                {"role": "user", "content": state.get("sanitized_input") or ""},
+            ],
+        )
+        return {"response_text": answer, "mcp_results": mcp, "rag_metadata": rag_metadata}
+```
+
+## Passo 9 — Criar dataset
+
+```yaml
+dataset:
+  name: financeiro_agent_regression
+  version: 1.0.0
+  items:
+    - id: fin-001
+      input: "Quero consultar minha fatura"
+      expected:
+        route: financeiro_agent
+        tools:
+          - consultar_fatura
+```
+
+## Passo 10 — Testar
+
+```bash
+pytest
+af-evaluator run --agent-id financeiro_agent
+af-certification run --agent-id financeiro_agent
+```
+
+# 8. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Alterar o core para regra de domínio | Dificulta reuso. | Criar agente/config. |
+| Esquecer dataset | Sem regressão. | Criar dataset mínimo. |
+| Tool sem mapping | Argumentos ausentes. | Configurar mcp_parameter_mapping.yaml. |
+| Prompt hardcoded | Sem governança. | Usar prompt_policy/prompts. |
+
+
+# 9. Critérios de aceite
+
+- [ ] Template usado como base.
+- [ ] Agente registrado.
+- [ ] Rotas configuradas.
+- [ ] Tools configuradas.
+- [ ] MCP mapping configurado.
+- [ ] Prompt criado.
+- [ ] Dataset criado.
+- [ ] Testes executados.
+- [ ] Evaluator executado.
+- [ ] Certification aprovada.
--- a/specs/SPEC-015-Adoption-and-Eligibility-Criteria.md
+++ b/specs/SPEC-015-Adoption-and-Eligibility-Criteria.md
@@ -0,0 +1,168 @@
+# SPEC-015 — Adoption and Eligibility Criteria
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+Critérios de adoção definem quando um projeto deve usar a Agent Platform OCI e quais requisitos mínimos precisa atender para entrar em desenvolvimento, homologação e produção.
+
+# 2. Problema que resolve
+
+Sem critérios claros:
+
+- qualquer caso simples vira agente;
+- projetos sem owner entram na plataforma;
+- canais entram sem contrato;
+- agentes entram sem dataset;
+- produção ocorre sem evaluator;
+- operação fica sem dashboard/alerta.
+
+# 3. Casos indicados
+
+| Caso | Exemplo |
+| --- | --- |
+| Agentes conversacionais | Atendimento, suporte, backoffice. |
+| Multiagentes | Handoff entre domínios. |
+| Agentes com tools | Consulta/ação em sistemas. |
+| Agentes com RAG | Uso de documentos e políticas. |
+| Ambientes regulados | Necessidade de governança e auditoria. |
+| Canais corporativos | Web, WhatsApp, Voice, URA, CRM. |
+
+
+# 4. Casos não indicados
+
+| Caso | Motivo |
+| --- | --- |
+| CRUD simples | API REST sem IA. |
+| ETL batch | Pipeline de dados. |
+| Job agendado simples | Sem interação. |
+| Serviço utilitário | Validação/formatação simples. |
+| Integração sem decisão | Proxy API sem raciocínio. |
+
+
+# 5. Critérios de entrada de negócio
+
+Antes de iniciar:
+
+- business owner;
+- technical owner;
+- objetivo;
+- escopo;
+- fora de escopo;
+- canais;
+- sistemas;
+- documentos;
+- critérios de sucesso;
+- riscos.
+
+# 6. Critérios de arquitetura
+
+Obrigatórios:
+
+- GatewayRequest;
+- ChannelResponse;
+- BusinessContext;
+- health/readiness;
+- logs;
+- traces;
+- dataset;
+- evaluator;
+- certification.
+
+# 7. Critérios de segurança
+
+Obrigatórios:
+
+- autenticação;
+- autorização;
+- secrets externos;
+- máscara de PII;
+- auditoria;
+- revisão de risco.
+
+# 8. Critérios de qualidade
+
+Obrigatórios:
+
+- testes unitários;
+- testes de integração;
+- dataset;
+- evaluator;
+- thresholds;
+- certification.
+
+# 9. Critérios de operação
+
+Obrigatórios:
+
+- métricas;
+- dashboards;
+- alertas;
+- runbook;
+- rollback;
+- SLO.
+
+# 10. Processo de exceção
+
+Exceções permitidas:
+
+- sem RAG;
+- sem MCP;
+- sem memória;
+- sem handoff;
+- sem canal externo.
+
+Toda exceção deve registrar:
+
+```yaml
+exception:
+  reason: "Agente não usa documentos"
+  approved_by: architecture
+  expires_at: 2026-12-31
+```
+
+# 11. Checklist de adoção
+
+- [ ] Business owner definido.
+- [ ] Technical owner definido.
+- [ ] Escopo definido.
+- [ ] Casos fora de escopo definidos.
+- [ ] GatewayRequest definido.
+- [ ] BusinessContext definido.
+- [ ] Segurança definida.
+- [ ] Dataset criado.
+- [ ] Evaluator configurado.
+- [ ] Certification planejada.
+- [ ] Observabilidade planejada.
+
+# 12. Critérios de aceite
+
+- [ ] Projeto elegível para plataforma.
+- [ ] Requisitos mínimos atendidos.
+- [ ] Exceções documentadas.
+- [ ] Plano de homologação definido.
+- [ ] Critérios de produção definidos.
--- a/specs/SPEC-016-Agent-Development-Lifecycle.md
+++ b/specs/SPEC-016-Agent-Development-Lifecycle.md
@@ -0,0 +1,227 @@
+# SPEC-016 — Agent Development Lifecycle
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+O ciclo de vida de desenvolvimento de agentes define as etapas desde a descoberta do caso de uso até a operação em produção.
+
+Ele organiza trabalho de produto, arquitetura, engenharia, segurança, avaliação e operação.
+
+# 2. Fluxo do ciclo de vida
+
+```mermaid
+flowchart LR
+    D[Discovery] --> S[Scope]
+    S --> AD[Agent Design]
+    AD --> PD[Prompt Design]
+    PD --> MD[MCP Design]
+    MD --> RD[RAG Design]
+    RD --> I[Implementation]
+    I --> T[Testing]
+    T --> E[Evaluation]
+    E --> C[Certification]
+    C --> H[Homologation]
+    H --> P[Production]
+```
+
+# 3. Etapa 1 — Discovery
+
+Objetivo:
+
+- entender problema;
+- identificar usuários;
+- mapear canais;
+- mapear sistemas;
+- mapear documentos;
+- mapear riscos.
+
+Saída:
+
+```yaml
+discovery:
+  business_problem: ""
+  users: []
+  channels: []
+  systems: []
+  documents: []
+  risks: []
+```
+
+# 4. Etapa 2 — Scope Definition
+
+Definir:
+
+- o que o agente faz;
+- o que não faz;
+- intenções;
+- ações permitidas;
+- limites;
+- critérios de sucesso.
+
+# 5. Etapa 3 — Agent Design
+
+Desenhar:
+
+- agent_id;
+- rotas;
+- intents;
+- BusinessContext;
+- tools;
+- RAG namespaces;
+- memória;
+- handoff.
+
+# 6. Etapa 4 — Prompt Design
+
+Criar:
+
+- system prompt;
+- prompt policy;
+- instruções de domínio;
+- exemplos;
+- restrições;
+- formato de resposta.
+
+# 7. Etapa 5 — MCP Design
+
+Definir:
+
+- tools;
+- parâmetros;
+- owner;
+- SLA;
+- timeout;
+- retry;
+- cache;
+- operação mutável ou idempotente.
+
+# 8. Etapa 6 — RAG Design
+
+Definir:
+
+- documentos;
+- namespace;
+- ingestão;
+- chunking;
+- embeddings;
+- atualização;
+- critérios de relevância.
+
+# 9. Etapa 7 — Implementation
+
+Implementar:
+
+- classe do agente;
+- configs;
+- prompts;
+- datasets;
+- tests;
+- observabilidade específica.
+
+# 10. Etapa 8 — Testing
+
+Testes mínimos:
+
+- unit;
+- integration;
+- contract;
+- MCP;
+- RAG;
+- guardrails;
+- judges;
+- runtime;
+- channel.
+
+# 11. Etapa 9 — Evaluation
+
+Executar:
+
+```bash
+af-evaluator run --agent-id <agent_id> --dataset <dataset>
+```
+
+Avaliar:
+
+- quality;
+- groundedness;
+- safety;
+- tool correctness;
+- route accuracy.
+
+# 12. Etapa 10 — Certification
+
+Executar:
+
+```bash
+af-certification run --agent-id <agent_id>
+```
+
+# 13. Etapa 11 — Homologation
+
+Validar com:
+
+- negócio;
+- arquitetura;
+- segurança;
+- operação;
+- integração.
+
+# 14. Etapa 12 — Production
+
+Requisitos:
+
+- deploy aprovado;
+- alertas ativos;
+- dashboards ativos;
+- rollback validado;
+- runbook disponível.
+
+# 15. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Começar pelo código | Escopo mal definido. | Iniciar por discovery/scope. |
+| Criar tool antes da intent | Tool sem contexto. | Definir fluxo primeiro. |
+| Dataset depois da produção | Sem regressão. | Criar dataset antes da homologação. |
+| Prompt sem critérios | Resposta inconsistente. | Definir prompt policy. |
+
+
+# 16. Critérios de aceite
+
+- [ ] Discovery concluído.
+- [ ] Escopo aprovado.
+- [ ] Agent design documentado.
+- [ ] Prompts criados.
+- [ ] MCP design aprovado.
+- [ ] RAG design aprovado quando aplicável.
+- [ ] Implementação concluída.
+- [ ] Testes executados.
+- [ ] Evaluator aprovado.
+- [ ] Certification aprovada.
+- [ ] Homologação concluída.
+- [ ] Produção monitorada.
--- a/specs/SPEC-017-Release-Management-and-CICD.md
+++ b/specs/SPEC-017-Release-Management-and-CICD.md
@@ -0,0 +1,144 @@
+# SPEC-017 — Release Management and CI/CD
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+Release management define como mudanças entram na plataforma, são testadas, empacotadas, publicadas, promovidas e auditadas.
+
+CI/CD automatiza validações e reduz risco operacional.
+
+# 2. Pipeline padrão
+
+```mermaid
+flowchart LR
+    C[Commit] --> L[Lint]
+    L --> TC[Type Check]
+    TC --> UT[Unit Tests]
+    UT --> IT[Integration Tests]
+    IT --> CT[Contract Tests]
+    CT --> SS[Security Scan]
+    SS --> B[Build]
+    B --> P[Publish]
+    P --> DD[Deploy Dev]
+    DD --> ST[Smoke Tests]
+    ST --> CERT[Certification]
+    CERT --> HML[Deploy HML]
+    HML --> PROD[Deploy Prod]
+```
+
+# 3. Stages
+
+| Stage | Função |
+| --- | --- |
+| validate | Validação inicial de estrutura. |
+| lint | Estilo e erros simples. |
+| type_check | Tipos e contratos Python. |
+| unit_test | Testes unitários. |
+| integration_test | Integrações locais. |
+| contract_test | Contratos JSON/YAML/API. |
+| security_scan | Dependências, secrets e imagens. |
+| build_package | Wheel/package. |
+| build_image | Imagem Docker. |
+| publish | Registry/artifacts. |
+| deploy_dev | Ambiente dev. |
+| smoke_test | Health e chamadas básicas. |
+| certification | Certification Suite. |
+| deploy_hml | Homologação. |
+| deploy_prod | Produção. |
+
+
+# 4. Artefatos de release
+
+- imagem Docker;
+- pacote Python;
+- release notes;
+- matriz de compatibilidade;
+- migration guide quando necessário;
+- evaluator report;
+- certification report;
+- SBOM quando aplicável;
+- evidência de scan;
+- changelog.
+
+# 5. Exemplo de pipeline
+
+```yaml
+stages:
+  - lint
+  - test
+  - contract
+  - security
+  - build
+  - publish
+  - deploy
+  - certification
+```
+
+# 6. Gates
+
+| Gate | Quando aplica |
+| --- | --- |
+| Architecture Gate | Mudanças estruturais, contratos, runtime, gateways. |
+| Security Gate | Segredos, identidade, dados sensíveis, MCP externo. |
+| Quality Gate | Testes, evaluator, certification. |
+| Operations Gate | Dashboards, alertas, runbook, rollback. |
+
+
+# 7. Estratégia de rollback
+
+Rollback deve restaurar:
+
+- imagem anterior;
+- configuração anterior;
+- contrato anterior;
+- prompt anterior;
+- dataset anterior quando necessário;
+- migration de banco quando aplicável.
+
+# 8. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Deploy sem certification | Risco funcional. | Rodar certification no pipeline. |
+| Sem release notes | Sem rastreabilidade. | Publicar release notes. |
+| Sem contract tests | Quebra integração. | Adicionar testes de contrato. |
+| Sem rollback | Risco operacional. | Definir estratégia de rollback. |
+
+
+# 9. Critérios de aceite
+
+- [ ] Pipeline executa lint, type check e testes.
+- [ ] Contract tests executam.
+- [ ] Security scan executa.
+- [ ] Imagem Docker gerada.
+- [ ] Artifacts publicados.
+- [ ] Smoke tests executados.
+- [ ] Certification executada.
+- [ ] Release notes publicadas.
+- [ ] Rollback definido.
+- [ ] Evidências arquivadas.
--- a/specs/SPEC-018-Security-and-Identity-Model.md
+++ b/specs/SPEC-018-Security-and-Identity-Model.md
@@ -0,0 +1,152 @@
+# SPEC-018 — Security and Identity Model
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+Security and Identity Model define como workloads autenticam, como componentes autorizam ações, como segredos são protegidos e como dados sensíveis são tratados.
+
+# 2. Modelos de autenticação
+
+| Modo | Uso |
+| --- | --- |
+| config_file | Desenvolvimento local com ~/.oci/config. |
+| instance_principal | Execução em OCI Compute. |
+| workload_identity | Execução em OKE/Kubernetes. |
+| resource_principal | Recursos OCI gerenciados. |
+| api_key | Endpoints compatíveis com OpenAI quando aplicável. |
+
+
+# 3. Workload Identity
+
+Fluxo:
+
+```mermaid
+flowchart LR
+    Pod[Pod Kubernetes] --> SA[ServiceAccount]
+    SA --> WI[Workload Identity]
+    WI --> IAM[OCI IAM Policy]
+    IAM --> Resource[OCI Resource]
+```
+
+# 4. Autorização
+
+Escopos:
+
+- agente pode chamar tool?
+- tenant pode usar provider?
+- canal pode chamar agent_id?
+- usuário pode executar ação?
+- tool mutável exige confirmação?
+
+# 5. Secrets
+
+Secrets não ficam no código.
+
+Fontes:
+
+- OCI Vault;
+- Kubernetes Secrets;
+- secret manager corporativo.
+
+Exemplos:
+
+```text
+LANGFUSE_SECRET_KEY
+OCI_GENAI_API_KEY
+ADB_PASSWORD
+MCP_BACKEND_TOKEN
+```
+
+# 6. Proteção de dados
+
+Aplicar:
+
+- máscara de PII;
+- minimização de metadata;
+- sanitização de payload;
+- não logar secrets;
+- retenção controlada;
+- classificação de dados.
+
+# 7. Segurança em MCP
+
+MCP tools devem ter:
+
+- autorização por agente;
+- allowlist;
+- timeout;
+- retry;
+- idempotência declarada;
+- confirmação para operações mutáveis.
+
+# 8. Segurança em canais
+
+Channel Gateway deve:
+
+- validar assinatura;
+- validar origem;
+- deduplicar;
+- rate limit;
+- remover tokens;
+- normalizar payload;
+- rejeitar anexos inválidos.
+
+# 9. Auditoria
+
+Registrar:
+
+- usuário/canal;
+- agent_id;
+- tenant_id;
+- tool chamada;
+- modelo usado;
+- decisão de guardrail;
+- judge score;
+- erro;
+- trace_id.
+
+# 10. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Secret em .env versionado | Vazamento. | Usar Vault/Secrets. |
+| Tool sem autorização | Acesso indevido. | Allowed agents por tool. |
+| Payload bruto em logs | Exposição de dados. | Mascarar/minimizar. |
+| Instance principal local | Timeout/autenticação inválida. | Usar config_file local. |
+
+
+# 11. Critérios de aceite
+
+- [ ] Modo de autenticação definido por ambiente.
+- [ ] Secrets externos ao código.
+- [ ] MCP tools autorizadas por agente.
+- [ ] Channel Gateway valida origem.
+- [ ] PII mascarada em logs.
+- [ ] Eventos auditáveis emitidos.
+- [ ] Workload Identity definido para OKE.
+- [ ] Security review executado antes de produção.
--- a/specs/SPEC-019-Evaluation-and-Certification-Framework.md
+++ b/specs/SPEC-019-Evaluation-and-Certification-Framework.md
@@ -0,0 +1,164 @@
+# SPEC-019 — Evaluation and Certification Framework
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+Evaluation mede qualidade e comportamento. Certification valida prontidão técnica e funcional.
+
+Evaluator responde:
+
+```text
+O agente respondeu bem?
+A resposta está fundamentada?
+A tool certa foi chamada?
+Houve regressão?
+```
+
+Certification responde:
+
+```text
+O agente está pronto para rodar?
+Endpoints funcionam?
+MCP funciona?
+Guardrails funcionam?
+Observabilidade funciona?
+```
+
+# 2. Arquitetura
+
+```mermaid
+flowchart LR
+    Runtime[Runtime] --> LF[Langfuse]
+    LF --> Eval[Offline Evaluator]
+    Dataset[Datasets] --> Eval
+    Eval --> Scores[Scores]
+    Eval --> Reports[Reports]
+    Cert[Certification Suite] --> Runtime
+    Cert --> Evidence[Evidences]
+```
+
+# 3. Métricas
+
+| Métrica | Descrição |
+| --- | --- |
+| quality | Clareza, completude e utilidade. |
+| groundedness | Aderência a evidências MCP/RAG. |
+| safety | Conformidade de segurança. |
+| resolution | Resolve a intenção. |
+| tool_correctness | Usa tools corretas. |
+| route_accuracy | Rota/intenção corretas. |
+| policy_compliance | Aderência à política de domínio. |
+
+
+# 4. Dataset
+
+```yaml
+dataset:
+  name: telecom_contas_regression
+  version: 1.0.0
+  items:
+    - id: billing-001
+      input: "Quero consultar minha fatura"
+      business_context:
+        customer_key: "11999999999"
+        contract_key: "3000131180"
+      expected:
+        route: billing_agent
+        tools:
+          - consultar_fatura
+        min_scores:
+          quality: 0.75
+          groundedness: 0.70
+```
+
+# 5. EvaluationRun
+
+```json
+{
+  "run_id": "eval-001",
+  "agent_id": "telecom_contas",
+  "source": "langfuse",
+  "period_start": "2026-06-18T00:00:00Z",
+  "period_end": "2026-06-19T00:00:00Z",
+  "status": "running"
+}
+```
+
+# 6. CLI
+
+```bash
+af-evaluator run   --agent-id telecom_contas   --dataset datasets/telecom_contas.yaml
+```
+
+# 7. Certification
+
+Valida:
+
+- health;
+- GatewayRequest;
+- routing;
+- identity;
+- MCP;
+- RAG;
+- guardrails;
+- judges;
+- memory;
+- checkpoint;
+- Langfuse;
+- OTEL.
+
+# 8. Evidências
+
+- JSON;
+- HTML;
+- TXT.GZ legado;
+- scores Langfuse;
+- logs;
+- traces;
+- screenshots quando aplicável.
+
+# 9. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Dataset só com casos felizes | Baixa cobertura. | Incluir negativos e bordas. |
+| Evaluator sem baseline | Sem comparação. | Registrar baseline. |
+| Certification sem MCP real/mock | Integração não validada. | Criar tool test. |
+| Judge sem threshold | Sem critério objetivo. | Definir threshold. |
+
+
+# 10. Critérios de aceite
+
+- [ ] Dataset versionado.
+- [ ] Evaluator executado.
+- [ ] Scores persistidos.
+- [ ] Certification executada.
+- [ ] Relatórios gerados.
+- [ ] Thresholds definidos.
+- [ ] Casos negativos incluídos.
+- [ ] Scores publicados quando aplicável.
--- a/specs/SPEC-020-Operational-Readiness-and-SRE-Model.md
+++ b/specs/SPEC-020-Operational-Readiness-and-SRE-Model.md
@@ -0,0 +1,166 @@
+# SPEC-020 — Operational Readiness and SRE Model
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+Operational Readiness define os requisitos mínimos para operar a Agent Platform OCI em produção com confiabilidade, observabilidade, capacidade de resposta a incidentes e recuperação.
+
+# 2. Componentes operados
+
+- Agent Gateway;
+- Channel Gateway;
+- Agent Runtime;
+- AI Gateway;
+- MCP Gateway;
+- MCP Servers;
+- Evaluator;
+- bancos/repositórios;
+- Langfuse/OTEL;
+- Redis/Mongo/ADB quando usados.
+
+# 3. Health e readiness
+
+Endpoints mínimos:
+
+```text
+GET /health
+GET /ready
+GET /version
+```
+
+# 4. SLOs
+
+| Componente | Latência | Disponibilidade |
+| --- | --- | --- |
+| Agent Gateway | p95 < 1s | 99.5% |
+| Agent Runtime | p95 < 5s | 99.0% |
+| AI Gateway | p95 < 10s | 99.0% |
+| MCP Gateway | p95 < 2s | 99.0% |
+| Evaluator | janela batch | execução diária |
+
+
+# 5. Métricas
+
+- requests_total;
+- request_latency_ms;
+- errors_total;
+- active_sessions;
+- llm_tokens_total;
+- llm_cost_estimated;
+- mcp_tool_calls_total;
+- guardrail_blocks_total;
+- judge_scores;
+- evaluator_scores.
+
+# 6. Dashboards
+
+Dashboards mínimos:
+
+- Platform Overview;
+- Runtime;
+- Gateway;
+- AI Gateway;
+- MCP Gateway;
+- Guardrails;
+- Evaluator;
+- Cost/Usage;
+- Incidents.
+
+# 7. Alertas
+
+| Alerta | Condição |
+| --- | --- |
+| HighErrorRate | 5xx acima do limite. |
+| LatencySLOBreach | p95 acima do SLO. |
+| LLMProviderDown | Falhas consecutivas no provider. |
+| MCPTimeoutSpike | Aumento de timeout MCP. |
+| GuardrailSpike | Aumento anômalo de bloqueios. |
+| EvaluatorFailed | Run falhou. |
+
+
+# 8. Runbooks
+
+Runbook deve conter:
+
+- sintoma;
+- impacto;
+- consultas;
+- dashboards;
+- logs;
+- ações;
+- rollback;
+- escalonamento.
+
+# 9. Incident management
+
+Fluxo:
+
+```mermaid
+flowchart LR
+    Detect[Detect] --> Triage[Triage]
+    Triage --> Mitigate[Mitigate]
+    Mitigate --> Recover[Recover]
+    Recover --> Postmortem[Postmortem]
+```
+
+# 10. Capacidade
+
+Avaliar:
+
+- QPS;
+- sessões simultâneas;
+- tokens/minuto;
+- chamadas MCP/minuto;
+- latência de provider;
+- uso de memória;
+- storage de checkpoints.
+
+# 11. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Sem readiness | Tráfego antes do app estar pronto. | Implementar /ready. |
+| Sem alertas MCP | Falha silenciosa. | Criar alertas por tool. |
+| Sem runbook | MTTR alto. | Criar runbooks por incidente. |
+| Sem custo LLM | Sem controle financeiro. | Registrar tokens/custos. |
+
+
+# 12. Production readiness checklist
+
+- [ ] Health checks ativos.
+- [ ] Readiness checks ativos.
+- [ ] Logs estruturados.
+- [ ] Métricas exportadas.
+- [ ] Traces exportados.
+- [ ] Dashboards criados.
+- [ ] Alertas configurados.
+- [ ] Runbooks disponíveis.
+- [ ] Rollback validado.
+- [ ] SLOs definidos.
+- [ ] Capacidade estimada.
+- [ ] Incident process definido.