Projeto do Agent Contas ORACLE

2026-08-19 09:35:50 -03:00
commit 950a2bcd33
1366 changed files with 177217 additions and 0 deletions
--- a/agent_framework_oci/specs/Disclaimer
+++ b/agent_framework_oci/specs/Disclaimer
@@ -0,0 +1,40 @@
+### Recomendações de segurança, autenticação e autorização
+
+Os componentes e templates deste framework podem ser adaptados a diferentes arquiteturas e requisitos de segurança. Para ambientes produtivos, recomenda-se que a solução seja avaliada de acordo com as políticas corporativas, os requisitos regulatórios aplicáveis e as melhores práticas de segurança da Oracle Cloud Infrastructure.
+
+Como orientação geral, recomenda-se considerar autenticação e autorização em todas as interfaces acessíveis por usuários, canais, sistemas externos ou outros serviços. Na OCI, uma opção é utilizar o OCI API Gateway, ou uma camada equivalente, em conjunto com OAuth 2.0/OpenID Connect, validação de tokens e políticas de autorização por rota, scope, papel e tenant.
+
+Métodos como HTTP Basic e API keys podem ser adequados para determinados cenários de integração, especialmente ambientes controlados ou sistemas legados. Nesses casos, recomenda-se utilizá-los sobre TLS, manter as credenciais em um serviço seguro de gerenciamento de segredos e adotar mecanismos de expiração e rotação.
+
+A avaliação de segurança deve considerar, conforme os componentes utilizados pela solução:
+
+- Agent Gateway, Channel Gateway e MCP Gateway;
+- backends de agentes e comunicação entre gateways e backends;
+- aplicações frontend e APIs consumidas pelo navegador;
+- callbacks e webhooks provenientes de canais externos;
+- conexões SSE, WebSocket ou outros mecanismos de streaming;
+- histórico, memória, checkpoints e dados de sessão;
+- endpoints administrativos, de debug, documentação, health e métricas;
+- integrações com LLMs, bancos de dados, caches, mensageria e plataformas de observabilidade.
+
+Recomenda-se tratar identificadores recebidos em payloads ou headers — como `tenant_id`, `agent_id`, `user_id`, `customer_id` e `session_id` — como informações de contexto, e não como evidência suficiente da identidade do solicitante. Quando aplicável, esses identificadores podem ser derivados de claims validadas ou relacionados à identidade autenticada antes da execução da operação.
+
+Além da autenticação, recomenda-se avaliar a autorização sobre cada recurso acessado. Essa verificação pode considerar se o usuário ou serviço autenticado possui permissão para acessar o tenant, agente, sessão, histórico, checkpoint, backend ou ferramenta MCP solicitado.
+
+Para comunicação entre serviços, podem ser consideradas identidades específicas por workload e mecanismos como OAuth 2.0 client credentials, OCI IAM, OKE Workload Identity, Instance Principals, Resource Principals ou mTLS. A escolha deve considerar a plataforma de execução e o modelo de confiança definido para a solução.
+
+Para callbacks e webhooks, recomenda-se avaliar os mecanismos disponibilizados pelo provedor do canal, como assinatura digital ou HMAC, JWT, timestamp, identificador de mensagem, proteção contra replay e idempotência.
+
+Em relação aos endpoints operacionais, é recomendável avaliar separadamente:
+
+- endpoints de liveness, com resposta mínima sobre o estado do processo;
+- endpoints de readiness, preferencialmente acessíveis apenas pela infraestrutura;
+- endpoints de métricas, destinados aos coletores autorizados;
+- endpoints de debug e teste, normalmente restritos a ambientes não produtivos;
+- documentação OpenAPI, que pode ser desabilitada ou protegida em produção.
+
+Também é recomendável utilizar TLS nas comunicações, restringir a exposição de serviços por meio de redes privadas, sub-redes, NSGs e allowlists, e considerar rate limiting, auditoria, rastreabilidade e monitoramento de acessos negados.
+
+Segredos, tokens, senhas, certificados e chaves podem ser mantidos no OCI Secret Management ou em solução corporativa equivalente, evitando seu armazenamento em código-fonte ou arquivos de configuração versionados. Recomenda-se estabelecer políticas de acesso de menor privilégio, expiração e rotação compatíveis com a criticidade de cada credencial.
+
+Estas recomendações representam uma referência inicial de melhores práticas. A definição final dos mecanismos de autenticação, autorização, proteção de rede e gestão de segredos permanece sob responsabilidade da equipe responsável pela arquitetura e pelo deployment, considerando o contexto, os riscos e os requisitos específicos de cada implementação.
--- a/agent_framework_oci/specs/Disclaimer_Auth_and_Security_EN.md
+++ b/agent_framework_oci/specs/Disclaimer_Auth_and_Security_EN.md
@@ -0,0 +1,40 @@
+### Security, Authentication, and Authorization Recommendations
+
+The components and templates in this framework can be adapted to different architectures and security requirements. For production environments, it is recommended that the solution be assessed in accordance with corporate policies, applicable regulatory requirements, and Oracle Cloud Infrastructure security best practices.
+
+As general guidance, authentication and authorization should be considered for all interfaces accessible by users, channels, external systems, or other services. In OCI, one option is to use OCI API Gateway, or an equivalent layer, together with OAuth 2.0/OpenID Connect, token validation, and authorization policies based on route, scope, role, and tenant.
+
+Methods such as HTTP Basic authentication and API keys may be suitable for certain integration scenarios, particularly in controlled environments or with legacy systems. In such cases, it is recommended that they be used over TLS, that credentials be stored in a secure secrets management service, and that expiration and rotation mechanisms be adopted.
+
+The security assessment should consider, according to the components used by the solution:
+
+- Agent Gateway, Channel Gateway, and MCP Gateway;
+- agent backends and communication between gateways and backends;
+- frontend applications and APIs consumed by the browser;
+- callbacks and webhooks originating from external channels;
+- SSE, WebSocket, or other streaming connections;
+- history, memory, checkpoints, and session data;
+- administrative, debug, documentation, health, and metrics endpoints;
+- integrations with LLMs, databases, caches, messaging systems, and observability platforms.
+
+Identifiers received in payloads or headers—such as `tenant_id`, `agent_id`, `user_id`, `customer_id`, and `session_id`—should be treated as contextual information rather than sufficient proof of the requester's identity. When applicable, these identifiers may be derived from validated claims or associated with the authenticated identity before the operation is executed.
+
+In addition to authentication, authorization should be evaluated for each accessed resource. This verification may consider whether the authenticated user or service has permission to access the requested tenant, agent, session, history, checkpoint, backend, or MCP tool.
+
+For service-to-service communication, dedicated workload identities and mechanisms such as OAuth 2.0 client credentials, OCI IAM, OKE Workload Identity, Instance Principals, Resource Principals, or mTLS may be considered. The choice should take into account the execution platform and the trust model defined for the solution.
+
+For callbacks and webhooks, the mechanisms provided by the channel provider should be evaluated, such as digital signatures or HMAC, JWT, timestamps, message identifiers, replay protection, and idempotency.
+
+Operational endpoints should also be evaluated separately:
+
+- liveness endpoints, with a minimal response regarding the process status;
+- readiness endpoints, preferably accessible only by the infrastructure;
+- metrics endpoints, intended for authorized collectors;
+- debug and test endpoints, typically restricted to non-production environments;
+- OpenAPI documentation, which may be disabled or protected in production.
+
+It is also recommended to use TLS for communications, restrict service exposure through private networks, subnets, NSGs, and allowlists, and consider rate limiting, auditing, traceability, and monitoring of denied access attempts.
+
+Secrets, tokens, passwords, certificates, and keys may be stored in OCI Secret Management or an equivalent corporate solution, avoiding storage in source code or version-controlled configuration files. Least-privilege access policies, expiration, and rotation practices appropriate to the criticality of each credential should be established.
+
+These recommendations provide an initial reference for best practices. The final definition of authentication, authorization, network protection, and secrets management mechanisms remains the responsibility of the team accountable for the architecture and deployment, taking into consideration the context, risks, and specific requirements of each implementation.
--- a/agent_framework_oci/specs/README.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-001-Architecture.md
+++ b/agent_framework_oci/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/agent_template_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/
+│   ├── agent_template_backend/
+│   └── agent_template_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 | 8300 | 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/agent_framework_oci/specs/SPEC-002-Agent-Runtime.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-003-Agent-Gateway.md
+++ b/agent_framework_oci/specs/SPEC-003-Agent-Gateway.md
@@ -0,0 +1,273 @@
+# SPEC-003 — Agent Gateway
+
+## Escopo
+
+O Agent Gateway é o ponto único de entrada da plataforma para canais e consumidores externos.
+
+Sua responsabilidade é receber mensagens, gerenciar sessões globais, resolver o backend/agente responsável, executar roteamento, realizar handoff entre agentes/backends e encaminhar eventos SSE.
+
+O Agent Gateway não executa inferência LLM nem embeddings. Essas capacidades pertencem ao Runtime e ao Agent Framework.
+
+---
+
+## Responsabilidades
+
+### Entrada Única da Plataforma
+
+```text
+Web
+WhatsApp
+Voice
+Teams
+Slack
+      |
+      v
+Agent Gateway
+      |
+      +--> Agent Backend A
+      |
+      +--> Agent Backend B
+      |
+      +--> Agent Backend C
+```
+
+### Gerenciamento de Sessões
+
+Responsável por:
+
+- Criação de sessões
+- Recuperação de sessões
+- Atualização de contexto global
+- Persistência de metadados de sessão
+- Correlação de requisições
+
+Exemplo:
+
+```json
+{
+  "session_id": "default:telecom_contas:123",
+  "tenant_id": "default",
+  "active_backend": "telecom_contas",
+  "active_agent": "telecom_contas",
+  "turn_count": 12,
+  "metadata": {}
+}
+```
+
+---
+
+## Backend Routing
+
+Resolve qual backend deve processar a mensagem.
+
+Exemplo:
+
+```yaml
+backends:
+  telecom_contas:
+    url: http://backend-contas:8000
+
+  telecom_ofertas:
+    url: http://backend-ofertas:8000
+```
+
+Critérios possíveis:
+
+- Backend padrão
+- Regras YAML
+- Intenção detectada
+- Contexto da sessão
+- Router LLM (opcional)
+
+---
+
+## Handoff
+
+Permite transferência entre agentes ou backends.
+
+Exemplo:
+
+```text
+Contas
+   |
+   +--> Ofertas
+   |
+   +--> Retenção
+```
+
+O handoff deve preservar:
+
+- session_id
+- conversation_key
+- business context
+- histórico da conversa
+- metadados de correlação
+
+---
+
+## SSE Proxy
+
+Responsável por encaminhar eventos de streaming para clientes.
+
+### Endpoints
+
+| Método | Endpoint |
+|----------|----------|
+| POST | /gateway/message |
+| POST | /gateway/message/sse |
+| GET | /gateway/events/{session_id} |
+
+Eventos SSE suportados:
+
+- connected
+- workflow.started
+- message.responded
+- workflow.completed
+- flow.end
+- error
+
+---
+
+## Backend Discovery
+
+Pode operar com catálogo estático ou descoberta dinâmica.
+
+### Catálogo Estático
+
+```yaml
+backends:
+  telecom_contas:
+    url: http://contas:8000
+
+  telecom_ofertas:
+    url: http://ofertas:8000
+```
+
+### Descoberta Dinâmica
+
+```yaml
+service_discovery:
+  enabled: true
+```
+
+Capacidades:
+
+- Registro automático
+- Health check periódico
+- Atualização de catálogo
+- Sincronização de metadados
+
+---
+
+## Health e Operação
+
+### Endpoints
+
+| Método | Endpoint |
+|----------|----------|
+| GET | /health |
+| GET | /ready |
+| GET | /backends |
+| GET | /debug/sessions |
+
+---
+
+## Contrato GatewayRequest
+
+```json
+{
+  "tenant_id": "default",
+  "agent_id": "telecom_contas",
+  "session_id": "default:telecom_contas:123",
+  "message": "Quero consultar minha fatura",
+  "business_context": {
+    "customer_key": "11999999999"
+  },
+  "metadata": {
+    "request_id": "req-001",
+    "trace_id": "trace-001"
+  }
+}
+```
+
+---
+
+## Contrato GatewayResponse
+
+```json
+{
+  "session_id": "default:telecom_contas:123",
+  "backend": "telecom_contas",
+  "agent": "telecom_contas",
+  "message": "Sua fatura está disponível.",
+  "metadata": {
+    "request_id": "req-001"
+  }
+}
+```
+
+---
+
+## Eventos
+
+| Evento | Descrição |
+|----------|----------|
+| agent.gateway.request.received | Requisição recebida |
+| agent.gateway.session.created | Sessão criada |
+| agent.gateway.backend.selected | Backend selecionado |
+| agent.gateway.handoff.started | Handoff iniciado |
+| agent.gateway.handoff.completed | Handoff concluído |
+| agent.gateway.sse.connected | Cliente SSE conectado |
+| agent.gateway.request.failed | Falha de processamento |
+
+---
+
+## Métricas
+
+| Métrica | Dimensões |
+|----------|----------|
+| gateway_requests_total | tenant, backend, agent, status |
+| gateway_sessions_active | tenant |
+| gateway_backend_selection_total | backend |
+| gateway_handoff_total | origem, destino |
+| gateway_latency_ms | backend |
+| gateway_sse_connections | backend |
+
+---
+
+## Segurança
+
+- Autenticação obrigatória quando configurada.
+- Propagação de identidade entre gateways.
+- Máscara de dados sensíveis em logs.
+- Correlação por request_id, trace_id e session_id.
+- Controle de acesso por tenant.
+
+---
+
+## Requisitos Não Funcionais
+
+| Categoria | Requisito |
+|----------|----------|
+| Disponibilidade | Expor /health e /ready |
+| Escalabilidade | Stateless com escala horizontal |
+| Observabilidade | Logs, métricas e traces |
+| Auditabilidade | Todas as decisões de roteamento rastreáveis |
+| Segurança | Segredos externos e mascaramento |
+| Portabilidade | Local, Docker e Kubernetes |
+| Configuração | YAML e variáveis de ambiente |
+
+---
+
+## Critérios de Aceite
+
+- [ ] Recebe mensagens de múltiplos canais.
+- [ ] Seleciona backend corretamente.
+- [ ] Mantém sessão global.
+- [ ] Encaminha SSE.
+- [ ] Executa handoff.
+- [ ] Preserva Business Context.
+- [ ] Suporta múltiplos backends.
+- [ ] Permite descoberta dinâmica.
+- [ ] Expõe health e readiness.
+- [ ] Gera métricas e telemetria.
--- a/agent_framework_oci/specs/SPEC-004-MCP-Gateway.md
+++ b/agent_framework_oci/specs/SPEC-004-MCP-Gateway.md
@@ -0,0 +1,231 @@
+# 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. |
+
+## Política mínima de operação
+
+Antes de encaminhar uma tool, o runtime deve aplicar a política opcional do backend em `config/tool_policies.yaml`. Os tipos canônicos são `read_only` e `transactional`; esta última pode exigir confirmação booleana explícita e campos obrigatórios. A ausência do arquivo não é erro e preserva os campos legados de `tools.yaml`. A política conversacional não substitui autenticação, autorização, idempotência nem atomicidade no MCP Server.
--- a/agent_framework_oci/specs/SPEC-005-Guardrails.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-006-Evals.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-007-Observability.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-008-Deployment.md
+++ b/agent_framework_oci/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:8300/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/agent_framework_oci/specs/SPEC-009-Channel-Gateway.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-010-Agent-Development.md
+++ b/agent_framework_oci/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/agent_template_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/agent_framework_oci/specs/SPEC-011-Governance-Model.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-012-Canonical-Contracts.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-013-Versioning-and-Compatibility-Model.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-014-Templates-and-Agent-Creation-Model.md
+++ b/agent_framework_oci/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. |
+| agent_template_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/agent_template_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/agent_framework_oci/specs/SPEC-015-Adoption-and-Eligibility-Criteria.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-016-Agent-Development-Lifecycle.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-017-Release-Management-and-CICD.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-018-Security-and-Identity-Model.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-019-Evaluation-and-Certification-Framework.md
+++ b/agent_framework_oci/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/agent_framework_oci/specs/SPEC-020-Operational-Readiness-and-SRE-Model.md
+++ b/agent_framework_oci/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.