fix: Spec Agent Runtime

2026-11-05 19:04:13 +00:00 · 2026-10-30 10:39:34 -03:00
parent ddd9d9a0d4
commit f035580c21
22 changed files with 4614 additions and 20 deletions
--- a/README.md
+++ b/README.md
@@ -49,89 +49,91 @@ If something is not working or if you want to understand the features of the Age
 [English technical specifications (SPEC-001–SPEC-020)](specs/en/README.md)
 ## SPECs / SDDs of the Agent Platform OCI
 The Agent Platform OCI documentation is organized into numbered SPECs/SDDs, each covering an architectural, operational, or governance area of the platform. The objective is to standardize the construction, evolution, operation, and certification of enterprise agents based on the Agent Framework OCI.
 >**/agent_platform_oci/specs**
-### [SPEC-001 — Architecture](specs/SPEC-001-Architecture.md)
+### [SPEC-001 — Architecture](specs/en/SPEC-001-Architecture.md)
 Defines the overall platform architecture, its main components, repository structure, logical and physical architecture, core contracts, primary flow, non-functional requirements, and acceptance criteria.
-### [SPEC-002 — Agent Runtime](specs/SPEC-002-Agent-Runtime.md)
+### [SPEC-002 — Agent Runtime](specs/en/SPEC-002-Agent-Runtime.md)
 Describes the conversational execution runtime for agents, including LangGraph, state management, memory, checkpoints, routing, supervisor, BusinessContext, MCP integration, RAG, events, and error handling.
-### [SPEC-003 — Agent Gateway](specs/SPEC-003-Agent-Gateway.md)
+### [SPEC-003 — Agent Gateway](specs/en/SPEC-003-Agent-Gateway.md)
 Specifies the gateway responsible for centralizing LLM and embedding calls, including request/response contracts, profiles, providers, OCI authentication, fallback, rate limiting, metrics, security, and observability.
-### [SPEC-004 — MCP Gateway](specs/SPEC-004-MCP-Gateway.md)
+### [SPEC-004 — MCP Gateway](specs/en/SPEC-004-MCP-Gateway.md)
 Defines the MCP integration model, including the tool catalog, routing, execution, authorization, caching, retries, timeouts, parameter mapping, events, metrics, and standardized tool responses.
-### [SPEC-005 — Guardrails](specs/SPEC-005-Guardrails.md)
+### [SPEC-005 — Guardrails](specs/en/SPEC-005-Guardrails.md)
 Describes the platform guardrail model, covering input, output, tool, RAG, and final response policies. It also defines phases, execution modes, guardrail types, LLM profiles, base codes, events, tests, and acceptance criteria.
-### [SPEC-006 — Evals](specs/SPEC-006-Evals.md)
+### [SPEC-006 — Evals](specs/en/SPEC-006-Evals.md)
 Defines the platform evaluation layer, including online evaluation, offline evaluation, regression testing, certification, datasets, judges, metrics, CLI, API, result persistence, and evidence publication.
-### [SPEC-007 — Observability](specs/SPEC-007-Observability.md)
+### [SPEC-007 — Observability](specs/en/SPEC-007-Observability.md)
 Specifies the observability model, including logs, traces, metrics, Langfuse, OpenTelemetry, IC/NOC/GRL events, dashboards, alerts, data masking, and operational evidence generation.
-### [SPEC-008 — Deployment](specs/SPEC-008-Deployment.md)
+### [SPEC-008 — Deployment](specs/en/SPEC-008-Deployment.md)
 Describes the platform packaging and deployment process, including deployable components, CI/CD pipelines, Kubernetes/OKE, Docker, secrets, OCI authentication, health checks, rollback, smoke tests, and certification stages.
-### [SPEC-009 — Channel Gateway](specs/SPEC-009-Channel-Gateway.md)
+### [SPEC-009 — Channel Gateway](specs/en/SPEC-009-Channel-Gateway.md)
 Defines the channel gateway responsible for normalizing external payloads into the platform's canonical contract and translating responses for each channel. Covers operating modes, idempotency, versioning, security, errors, and anti-patterns.
-### [SPEC-010 — Agent Development](specs/SPEC-010-Agent-Development.md)
+### [SPEC-010 — Agent Development](specs/en/SPEC-010-Agent-Development.md)
 Describes the standard for agent development using templates, YAML configuration, BusinessContext, MCP, guardrails, judges, RAG, memory, observability, and evaluations. It also differentiates framework and agent responsibilities.
-### [SPEC-011 — Governance Model](specs/SPEC-011-Governance-Model.md)
+### [SPEC-011 — Governance Model](specs/en/SPEC-011-Governance-Model.md)
 Defines the platform governance model, including ownership, roles and responsibilities, RACI, agent governance, prompts, guardrails, judges, models, MCP, datasets, approval processes, and mandatory evidence.
-### [SPEC-012 — Canonical Contracts](specs/SPEC-012-Canonical-Contracts.md)
+### [SPEC-012 — Canonical Contracts](specs/en/SPEC-012-Canonical-Contracts.md)
 Documents the platform's canonical contracts, including GatewayRequest, ChannelResponse, BusinessContext, AgentState, ToolInvocation, ToolResult, LLMRequest, LLMResponse, EvaluationRun, and EventEnvelope. It also defines contract evolution rules.
-### [SPEC-013 — Versioning and Compatibility Model](specs/SPEC-013-Versioning-and-Compatibility-Model.md)
+### [SPEC-013 — Versioning and Compatibility Model](specs/en/SPEC-013-Versioning-and-Compatibility-Model.md)
 Defines the platform versioning and compatibility model, including Semantic Versioning, versioned artifacts, contract versioning, compatibility matrices, deprecation policies, migration, and rollback.
-### [SPEC-014 — Templates and Agent Creation Model](specs/SPEC-014-Templates-and-Agent-Creation-Model.md)
+### [SPEC-014 — Templates and Agent Creation Model](specs/en/SPEC-014-Templates-and-Agent-Creation-Model.md)
 Describes the official templates and the agent creation model from scratch. Explains what belongs to the framework, what belongs to the agent, the standard structure, and the step-by-step process for copying templates, defining scope, registering agents, configuring routes, tools, BusinessContext, prompts, datasets, and tests.
-### [SPEC-015 — Adoption and Eligibility Criteria](specs/SPEC-015-Adoption-and-Eligibility-Criteria.md)
+### [SPEC-015 — Adoption and Eligibility Criteria](specs/en/SPEC-015-Adoption-and-Eligibility-Criteria.md)
 Defines clear platform adoption criteria, including recommended and non-recommended use cases, business entry criteria, architecture, security, quality, operations, exception processes, and adoption checklists.
-### [SPEC-016 — Agent Development Lifecycle](specs/SPEC-016-Agent-Development-Lifecycle.md)
+### [SPEC-016 — Agent Development Lifecycle](specs/en/SPEC-016-Agent-Development-Lifecycle.md)
 Describes the complete agent development lifecycle, from discovery and scope definition through design, prompting, MCP, RAG, implementation, testing, evaluation, certification, validation, and production.
-### [SPEC-017 — Release Management and CI/CD](specs/SPEC-017-Release-Management-and-CICD.md)
+### [SPEC-017 — Release Management and CI/CD](specs/en/SPEC-017-Release-Management-and-CICD.md)
 Defines the release and CI/CD model, including standard pipelines, stages, release artifacts, quality gates, rollback strategies, common errors, and acceptance criteria.
-### [SPEC-018 — Security and Identity Model](specs/SPEC-018-Security-and-Identity-Model.md)
+### [SPEC-018 — Security and Identity Model](specs/en/SPEC-018-Security-and-Identity-Model.md)
 Specifies the platform security and identity model, covering authentication, Workload Identity, authorization, secrets, data protection, MCP security, channel security, auditing, and acceptance criteria.
-### [SPEC-019 — Evaluation and Certification Framework](specs/SPEC-019-Evaluation-and-Certification-Framework.md)
+### [SPEC-019 — Evaluation and Certification Framework](specs/en/SPEC-019-Evaluation-and-Certification-Framework.md)
 Details the evaluation and certification framework, including evaluation architecture, metrics, datasets, EvaluationRun, CLI, certification processes, mandatory evidence, and acceptance criteria.
-### [SPEC-020 — Operational Readiness and SRE Model](specs/SPEC-020-Operational-Readiness-and-SRE-Model.md)
+### [SPEC-020 — Operational Readiness and SRE Model](specs/en/SPEC-020-Operational-Readiness-and-SRE-Model.md)
 Defines the platform operational readiness and SRE model, including managed components, health checks, readiness, SLOs, metrics, dashboards, alerts, runbooks, incident management, capacity planning, and production checklists.
--- a/specs/en/README.md
+++ b/specs/en/README.md
@@ -0,0 +1,28 @@
 # Agent Platform OCI — Technical Specifications (English)
 The English-language specifications are listed below. File names and technical identifiers are aligned with the original documents.
 | Specification | Title |
 |---|---|
 | [SPEC-001-Architecture.md](SPEC-001-Architecture.md) | SPEC-001 — Architecture |
 | [SPEC-002-Agent-Runtime.md](SPEC-002-Agent-Runtime.md) | SPEC-002 — Agent Runtime |
 | [SPEC-003-Agent-Gateway.md](SPEC-003-Agent-Gateway.md) | SPEC-003 — Agent Gateway |
 | [SPEC-004-MCP-Gateway.md](SPEC-004-MCP-Gateway.md) | SPEC-004 — MCP Gateway |
 | [SPEC-005-Guardrails.md](SPEC-005-Guardrails.md) | SPEC-005 — Guardrails |
 | [SPEC-006-Evals.md](SPEC-006-Evals.md) | SPEC-006 — Evals |
 | [SPEC-007-Observability.md](SPEC-007-Observability.md) | SPEC-007 — Observability |
 | [SPEC-008-Deployment.md](SPEC-008-Deployment.md) | SPEC-008 — Deployment |
 | [SPEC-009-Channel-Gateway.md](SPEC-009-Channel-Gateway.md) | SPEC-009 — Channel Gateway |
 | [SPEC-010-Agent-Development.md](SPEC-010-Agent-Development.md) | SPEC-010 — Agent Development |
 | [SPEC-011-Governance-Model.md](SPEC-011-Governance-Model.md) | SPEC-011 — Governance Model |
 | [SPEC-012-Canonical-Contracts.md](SPEC-012-Canonical-Contracts.md) | SPEC-012 — Canonical Contracts |
 | [SPEC-013-Versioning-and-Compatibility-Model.md](SPEC-013-Versioning-and-Compatibility-Model.md) | SPEC-013 — Versioning and Compatibility Model |
 | [SPEC-014-Templates-and-Agent-Creation-Model.md](SPEC-014-Templates-and-Agent-Creation-Model.md) | SPEC-014 — Templates and Agent Creation Model |
 | [SPEC-015-Adoption-and-Eligibility-Criteria.md](SPEC-015-Adoption-and-Eligibility-Criteria.md) | SPEC-015 — Adoption and Eligibility Criteria |
 | [SPEC-016-Agent-Development-Lifecycle.md](SPEC-016-Agent-Development-Lifecycle.md) | SPEC-016 — Agent Development Lifecycle |
 | [SPEC-017-Release-Management-and-CICD.md](SPEC-017-Release-Management-and-CICD.md) | SPEC-017 — Release Management and CI/CD |
 | [SPEC-018-Security-and-Identity-Model.md](SPEC-018-Security-and-Identity-Model.md) | SPEC-018 — Security and Identity Model |
 | [SPEC-019-Evaluation-and-Certification-Framework.md](SPEC-019-Evaluation-and-Certification-Framework.md) | SPEC-019 — Evaluation and Certification Framework |
 | [SPEC-020-Operational-Readiness-and-SRE-Model.md](SPEC-020-Operational-Readiness-and-SRE-Model.md) | SPEC-020 — Operational Readiness and SRE Model |
 [Portuguese specifications](../README.md) · [Developer guide](../../README.md)
--- a/specs/en/SPEC-001-Architecture.md
+++ b/specs/en/SPEC-001-Architecture.md
@@ -0,0 +1,239 @@
 # SPEC-001 — Architecture
 ## Scope
 The Agent Platform OCI consists of reusable components, deployable applications, integration contracts, agent templates, an evaluation layer, and operational artifacts.
 ## Components
 | Componente | Tipo | Responsibility |
 |---|---|---|
 | `libs/agent_framework` | Lib | Core reutilizável of the framework. |
 | `runtimes/langgraph_runtime` | Runtime | Execution of Agents based on LangGraph. |
 | `apps/agent_gateway` | App | Input padronizada and Routing of Agents/backends. |
 | `apps/channel_gateway` | App | Normalização of canais external. |
 | `apps/ai_gateway` | App | Abstração, Governance and Routing of modelos. |
 | `apps/mcp_gateway` | App | Governance, Catalog and Execution of tools MCP. |
 | `mcp/servers` | Apps | MCP servers of Domain. |
 | `evals/offline` | App/Lib | Evaluation offline/batch. |
 | `evals/certification` | Suite | Certification técnica and funcional. |
 | `templates/agent_template_backend` | Template | Scaffold for new Agents. |
 | `specs` | documentation | contracts SDD versionados. |
 | `deploy` | Operations | Docker, Kubernetes and Helm. |
 ## Repository structure
 ```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/
 ```
 ## Logical architecture
 ```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]
 ```
 ## Physical architecture
 | service | Porta Standard | Deploy | Escala |
 |---|---:|---|---|
 | Agent Gateway | 9000 | Kubernetes Deployment | Horizontal |
 | Agent Backend / Runtime | 8000 | Kubernetes Deployment | Horizontal with external storage |
 | Channel Gateway | 7000 | Kubernetes Deployment | Horizontal |
 | AI Gateway | 9100 | Kubernetes Deployment | Horizontal |
 | MCP Gateway | 8300 | Kubernetes Deployment | Horizontal |
 | MCP Servers | 8001+ | Kubernetes Deployment | Per domain |
 | Evaluator API | 9300 | Deployment/CronJob | By batch workload |
 | Frontend Demo | 5173 | Optional | Noncritical |
 ## Main contracts
 | Contract | producer | consumer |
 |---|---|---|
 | GatewayRequest | Channel Gateway / Agent Gateway | Agent Runtime |
 | ChannelResponse | Agent Runtime | Channel Gateway / Cliente |
 | BusinessContext | Channel Gateway / Identity resolve | 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"
  }
 }
 ```
 ## Flow main
 ```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
 ```
 ## Configuration
 | file | Uso |
 |---|---|
 | `.env` | Provider, Authentication, flags and endpoints por ambiente. |
 | `agents.yaml` | Registration of Agents. |
 | `routing.yaml` | Intents, rotas, Policies and fallback. |
 | `guardrails.yaml` | Guardrails global. |
 | `judges.yaml` | Judges global. |
 | `llm_profiles.yaml` | Profiles of modelos por componente. |
 | `mcp_servers.yaml` | MCP servers disponíveis. |
 | `tools.yaml` | Catalog of tools. |
 | `mcp_parameter_mapping.yaml` | Mapeamento BusinessContext → argumentos MCP. |
 | `identity.yaml` | Resolução of Identity of negócio. |
 | `observability.yaml` | Logs, Metrics, traces and exporters. |
 | `evals.yaml` | Datasets, Metrics and Configuration of the evaluator. |
 ## Events
 | Evento | Origem | Description |
 |---|---|---|
 | `gateway.request.received` | Agent Gateway | Request recebida. |
 | `channel.normalized` | Channel Gateway | Payload convertido em GatewayRequest. |
 | `runtime.started` | Runtime | Execution iniciada. |
 | `guardrail.input.completed` | Guardrails | Guardrails of Input concluídos. |
 | `route.selected` | Router/Supervisor | Rota definida. |
 | `mcp.tool.completed` | MCP Gateway | Tool executada. |
 | `llm.completed` | AI Gateway | Call LLM concluída. |
 | `judge.completed` | Judge Engine | Evaluation concluída. |
 | `runtime.completed` | Runtime | Execution finalizada. |
 ## Requirements No Funcionais
 | Categoria | Requirement |
 |---|---|
 | Availability | Components deployáveis expõem `/health` and `/ready`. |
 | Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
 | Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
 | Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
 | Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
 | Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
 | Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |
 ## Acceptance criteria
 - [ ] Repository structure separa libs, runtimes, apps, mcp, evals, templates, specs and deploy.
 - [ ] each app deployável possui Contract of Input/Output documentado.
 - [ ] GatewayRequest and ChannelResponse are versionados.
 - [ ] BusinessContext is Used como Contract canônico.
 - [ ] Runtime No recebe payload bruto of canal.
 - [ ] AI Gateway and MCP Gateway possuem fronteiras explícitas.
 - [ ] Evaluator is componente padronizado of Evaluation.
 - [ ] all os services possuem health check.
 - [ ] Telemetria fim-a-fim correlaciona request_id, trace_id and session_id.
 - [ ] Configuration críticas possuem YAML dedicado.
 ## Glossário
 | Termo | Definição |
 |---|---|
 | Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
 | Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
 | Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
 | Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
 | Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
 | AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
 | MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
 | Evaluator | layer of Evaluation online/offline, regressão and Certification. |
 | Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |
--- a/specs/en/SPEC-002-Agent-Runtime.md
+++ b/specs/en/SPEC-002-Agent-Runtime.md
@@ -0,0 +1,333 @@
 # SPEC-002 — Agent Runtime
 ## 1. Overview
 The Agent Runtime coordinates conversational execution for agents on the OCI platform. It combines LangGraph graphs, per-conversation state, intent routing, domain agents, guardrails, judges, long-term memory, and persistence. The reusable framework library provides services and contracts consumed by agent backends; the reference `agent_template_backend` assembles these services into an executable workflow.
 ## 2. Implementation structure
 | Component | Location | Responsibility |
 |---|---|---|
 | Shared runtime | `libs/agent_framework/src/agent_framework/runtime/` | Reusable agent-execution capabilities. |
 | Reference workflow | `templates/agent_template_backend/app/workflows/agent_graph.py` | Graph construction and workflow-node implementations. |
 | Workflow state | `templates/agent_template_backend/app/state.py` | Typed definition of data exchanged between nodes. |
 | Agent configuration | `templates/agent_template_backend/config/agents.yaml` | Agent registry and policy/configuration file paths. |
 | Routing configuration | `templates/agent_template_backend/config/routing.yaml` | Router mode, fallback, threshold, and intent catalog. |
 | Tool configuration | `templates/agent_template_backend/config/tools.yaml` | Tool definitions used by agents. |
 ## 3. Execution state
 The workflow uses the `AgentState` definition shown below. Its `TypedDict(total=False)` declaration allows nodes to add the fields relevant to each execution stage without requiring every field to be present in each state instance.
 ```python
 from typing import Any, TypedDict
 class AgentState(TypedDict, total=False):
    tenant_id: str
    agent_id: str
    session_id: str
    conversation_key: str
    workflow_id: str
    agent_profile: dict[str, Any]
    user_text: str
    sanitized_input: str
    route: str
    intent: str
    route_decision: dict[str, Any]
    answer: str
    final_answer: str
    history: list[dict[str, Any]]
    context: dict[str, Any]
    guardrail_decisions: list[dict[str, Any]]
    judge_results: list[dict[str, Any]]
    next_state: str
    domain: str
    mcp_tools: list[str]
    mcp_results: list[dict[str, Any]]
    rag_results: list[dict[str, Any]]
    available_mcp_tools: list[str]
    selected_tool_call: dict[str, Any]
    pending_tool_call: dict[str, Any]
    active_transaction: dict[str, Any]
    last_transaction: dict[str, Any]
    transaction_status: str
    transaction_pre_validation: dict[str, Any]
    transaction_evidence: list[dict[str, Any]]
    last_transaction_evidence: dict[str, Any]
    relevant_transaction_evidence: list[dict[str, Any]]
    confirmation_required: bool
    confirmation_received: bool
    tool_policy_result: dict[str, Any]
    missing_parameters: list[str]
    supervisor_plan: dict[str, Any]
    supervisor_results: list[dict[str, Any]]
    agent_responses: list[dict[str, Any]]
    pending_topics: list[dict[str, Any]]
    handled_topics: list[dict[str, Any]]
    operation_results: dict[str, dict[str, Any]]
    multi_intent_plan: dict[str, Any]
    active_agent: str
    route_bypassed: bool
    continuity_signal: dict[str, Any]
    session_control: str
    session_ended: bool
    human_handoff_requested: bool
    blocked: bool
    supervisor_action: str
    supervisor_guidance: str
    supervisor_attempt: int
    supervisor_handover_reason: str
    output_supervisor_results: list[dict[str, Any]]
    output_guardrails_already_applied: bool
    long_term_memories: list[dict[str, Any]]
    long_term_memory_context: str
    long_term_memory_write_result: dict[str, Any]
    long_term_memory_subject_key: str
    long_term_memory_load_error: str
 ```
 ## 4. Execution flow
 The workflow is compiled using `FrameworkStateGraph(AgentState)` with a checkpointer created by `create_langgraph_checkpointer(self.settings)`.
 ```mermaid
 flowchart TD
  START([START]) --> input_guardrails
  input_guardrails -->|continue| load_long_term_memory
  input_guardrails -->|blocked| output_guardrails
  load_long_term_memory --> routing_decision
  routing_decision --> billing_agent
  routing_decision --> product_agent
  routing_decision --> orders_agent
  routing_decision --> support_agent
  routing_decision --> handoff
  routing_decision --> human_handoff
  routing_decision --> end_session
  routing_decision --> supervisor_agent
  billing_agent --> output_supervisor
  product_agent --> output_supervisor
  orders_agent --> output_supervisor
  support_agent --> output_supervisor
  handoff --> output_supervisor
  human_handoff --> output_supervisor
  end_session --> output_supervisor
  supervisor_agent --> output_supervisor
  output_supervisor --> output_guardrails
  output_guardrails -->|continue| judge
  output_guardrails -->|blocked| persist
  judge --> supervisor_review
  supervisor_review --> persist_long_term_memory
  persist_long_term_memory --> persist
  persist --> END([END])
 ```
 Routing after `input_guardrails` depends on `state['blocked']`. Following `routing_decision`, the value of `state['route']` selects one of the registered nodes, defaulting to `billing_agent` when the key is absent. Routing after `output_guardrails` also checks `state['blocked']`.
 ## 5. Workflow nodes
 | Node | Responsibility |
 |---|---|
 | `input_guardrails` | Evaluates and processes input before routing. |
 | `load_long_term_memory` | Loads long-term memory context. |
 | `routing_decision` | Determines the conversation's execution destination. |
 | `billing_agent` | Runs the billing agent. |
 | `product_agent` | Runs the product and services agent. |
 | `orders_agent` | Runs the orders agent. |
 | `support_agent` | Runs the support agent. |
 | `handoff` | Handles the transfer path defined by the workflow. |
 | `human_handoff` | Handles requests for transfer to a human representative. |
 | `end_session` | Handles session termination. |
 | `supervisor_agent` | Runs the supervisor-related path. |
 | `output_supervisor` | Processes response supervision. |
 | `output_guardrails` | Applies output policies. |
 | `judge` | Evaluates the response. |
 | `supervisor_review` | Processes review after the judge. |
 | `persist_long_term_memory` | Performs the long-term memory write stage. |
 | `persist` | Performs the final workflow persistence stage. |
 Nodes are wrapped by the `_node` method, which executes them within `self.langgraph_telemetry.node(name, state)`.
 ## 6. Routing
 The `config/routing.yaml` file defines the main options under the `router` key:
 ```yaml
 # Configurable enterprise routing with MCP-aware intents.
 router:
  # mode can also be set through the ROUTING_MODE environment variable.
  # Values: router | supervisor
  mode: router
  fallback_agent: billing_agent
  confidence_threshold: 0.65
  allow_handoff: true
 ```
 The configuration also contains `state_policies`, which keep certain confirmation or parameter-collection stages bound to the corresponding agent, and an `intents` catalog with attributes such as `name`, `domain`, `agent`, `priority`, `mcp_tools`, `keywords`, and `examples`.
 The agent catalog in `config/agents.yaml` declares `telecom_contas` and `retail_orders`. Each entry points to prompt, routing, guardrail, judge, MCP server, and tool policy/configuration files, as well as domain metadata.
 ## 7. Agent and tool execution
 Domain nodes dispatch requests to the billing, product, order, and support agent instances. MCP tools are exposed to agents through tool configuration and tool-routing components. Tool results can be carried in `mcp_results`; selected tool names are stored in `mcp_tools`.
 State also supports `selected_tool_call`, `pending_tool_call`, `tool_policy_result`, `missing_parameters`, and transaction-evidence fields. These allow preparation, validation, confirmation, and execution stages to share information across the conversation.
 ## 8. Transaction state
 `AgentState` holds the current transaction in `active_transaction` and the latest completed transaction in `last_transaction`. The fields `transaction_status`, `transaction_pre_validation`, `transaction_evidence`, `last_transaction_evidence`, `relevant_transaction_evidence`, `confirmation_required`, and `confirmation_received` carry the information required for transactional processing.
 Routing configuration defines state policies for `WAITING_BILLING_CONFIRMATION`, `WAITING_PRODUCT_CONFIRMATION`, `WAITING_ORDER_CONFIRMATION`, `WAITING_SUPPORT_CONFIRMATION`, `COLLECTING_BILLING_PARAMETERS`, `COLLECTING_PRODUCT_PARAMETERS`, `COLLECTING_ORDER_PARAMETERS`, and `COLLECTING_SUPPORT_PARAMETERS`.
 The transactional-flow reference guide is [`docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
 ## 9. Memory and checkpoints
 The workflow includes two explicit long-term memory stages: `load_long_term_memory`, before routing, and `persist_long_term_memory`, before final persistence. The fields `long_term_memories`, `long_term_memory_context`, `long_term_memory_write_result`, `long_term_memory_subject_key`, and `long_term_memory_load_error` form this capability's state interface.
 Graph construction passes the result of `create_langgraph_checkpointer(self.settings)` to `compile`. Checkpoint storage and retrieval are handled by the configured checkpointer, retaining state continuity across interactions according to the selected backend.
 ## 10. Guardrails, supervision, and judges
 Input passes through `input_guardrails` before memory loading and routing. When input is blocked, execution goes directly to `output_guardrails`.
 Agent responses pass through `output_supervisor` and `output_guardrails`. An unblocked response proceeds to `judge` and `supervisor_review`; a blocked response goes to `persist`. Results are carried in `guardrail_decisions`, `output_supervisor_results`, `judge_results`, `supervisor_action`, `supervisor_guidance`, and related state fields.
 ## 11. Observability
 The workflow wraps each node in `langgraph_telemetry.node` instrumentation, associating execution with the node identity and conversation state. Framework telemetry and observability mechanisms provide traceability for decisions and execution stages.
 ## 12. Error handling and recovery by component
 ### 12.1. Failure propagation principles
 The runtime distinguishes failures handled within a stage, negative policy/tool results, and exceptions that prevent graph execution. Each component's contract determines whether processing continues, a response is modified, or the exception is returned to the caller. The `blocked` field represents a policy decision in state; it does not generically denote a Python exception.
 | Area | Representation | Execution impact |
 |---|---|---|
 | Guardrails | Decisions with `allowed`, `code`, and `reason`; supervision decisions with `action` | May stop routing, replace or sanitize the response, or allow processing to continue. |
 | MCP | Tool results with `ok`, `error`, `tool_name`, and source-specific execution details | The agent uses the result to control how the operation proceeds. |
 | Long-term memory | `long_term_memory_load_error` and `long_term_memory_write_result` fields | Read or write exceptions caught in the node do not terminate graph execution. |
 | RAG | Retrieval result or technical-error object | A failure may be incorporated into the agent's execution context. |
 | Checkpoints | Repository exceptions, integrity validation, and version recovery | Recovery may select an earlier valid checkpoint or start from a clean state; exhausted storage retries propagate an exception. |
 | Workflow | Exceptions raised by nodes or `graph.ainvoke` | Execution is marked as failed in telemetry and the exception is re-raised. |
 ### 12.2. Input, sessions, and input guardrails
 The `input_guardrails` node first checks `session_ended`. If the session has already ended, it sets `blocked=True`, `session_control="END_SESSION"`, `session_ended=True`, and `next_state="SESSION_ENDED"`, composes the message configured in `SESSION_ALREADY_ENDED_MESSAGE`, and records `session.message.rejected_after_end`. This prevents the message from reaching the router or domain agents.
 For active sessions, the pipeline evaluates guardrails and stores decisions in `guardrail_decisions`. If any decision has `allowed=False`, the node generates a safe response, sets `route="blocked"` and `intent="input_guardrail_blocked"`, clears the turn's MCP tool and result lists, and follows the output branch. `_input_guardrail_user_message` has specific messages for `COER`, `INPUT_SIZE`, `DLEX_IN`, `PINJ`, `TOX`, and `CMP`, plus a default response for other codes. Detailed reasons remain in decisions and telemetry; the runtime controls the user-facing message.
 Evaluation records `guardrails.input.completed`, individual decisions in guardrail telemetry, and GRL events through the observer. When input is blocked, the pre-routing memory node, router, and agent tools do not execute. The branch proceeds to `output_guardrails` and, according to graph conditions, ends in `persist`.
 **Implementation reference:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`input_guardrails`, `_input_guardrail_user_message`, `_after_input_guardrails`).
 ### 12.3. Routing, classification, and continuity
 Routing configuration is loaded through `routing/config_loader.py`; a missing file raises `FileNotFoundError`. `EnterpriseRouter` locally handles errors from classification calls and model-output parsing. In the semantic classifier for expected inputs, a failed `llm.ainvoke` call is logged with `logger.warning`, and the function returns `(None, None)`. Subsequent routing paths can therefore operate without treating the failure as a valid classification.
 The flow uses `fallback_agent` and `confidence_threshold` settings, as well as state policies in `routing.yaml`. Selecting a fallback is a routing decision, not intrinsically an error code. The `route_decision`, `continuity_signal`, `pending_topics`, and `multi_intent_plan` structures preserve information for resumption and routing of related turns.
 Failure recovery depends on the method actually invoked: not every internal routing error is handled by the same `except` clause. Exceptions escaping the node reach the workflow failure handler in `ainvoke`.
 **Implementation references:** `libs/agent_framework/src/agent_framework/routing/config_loader.py`, `routing/enterprise_router.py`, `routing/continuity.py`; `templates/agent_template_backend/app/workflows/agent_graph.py` (`routing_decision`, `ainvoke`).
 ### 12.4. Agent execution, arguments, and MCP tools
 Tool preparation is handled by the reusable runtime in `runtime/agent_runtime.py`. `_prepare_mcp_call` invokes the MCP router and returns a structured preparation error when `prepare_call` provides one. If the tool router is unavailable, the runtime produces a negative result with `ok=False`, `tool_name`, and the description `MCP Tool Router indisponível`.
 During parameter mapping, regular-expression errors (`re.error`, `IndexError`, `ValueError`) are caught and logged as `mcp.parameter.regex_extract_failed`. For LLM-based extraction, missing model/message data and inference exceptions are recorded as `mcp.parameter.llm_extract_failed`. Argument processing and call results remain subject to tool validation and agent policies; absence of an exception alone does not establish success.
 MCP results may expose `ok=False` and `error`, including validation and execution failures. The implementation emits `NOC.MCP_TOOL_FAILED` along one path that aggregates negative tool results. Transaction handling, confirmations, evidence, and partial results operate on execution data including `active_transaction`, `transaction_pre_validation`, `transaction_evidence`, and `operation_results`, depending on operation type.
 **Implementation reference:** `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py` (`_prepare_mcp_call`, parameter handling, tool execution, and result aggregation).
 ### 12.5. RAG and knowledge retrieval
 The runtime wraps knowledge-retrieval failures in a technical result containing `technical_error=True`, `technical_error_in_rag=True`, `status="error"`, and a description in `error`. This allows the agent to distinguish retrieval failure from a completed search yielding no useful evidence.
 The RAG service also validates preconditions: `RagService.generate_answer` raises `RuntimeError` when used without an LLM, and `kbdb_service.py` checks configuration/signatures and disallows ingestion/publication when the KBDB provider is configured exclusively for serving. During ingestion, a missing directory may raise `FileNotFoundError`, while `chunk_overlap >= chunk_size` raises `ValueError`. These initialization and administration errors must not be confused with an empty retrieval result during a conversation.
 **Implementation references:** `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py` (technical RAG error handling); `rag/rag_service.py`, `rag/kbdb_service.py`, `rag/ingest.py`.
 ### 12.6. Long-term memory
 The `load_long_term_memory` node catches exceptions from `long_term_memory_manager.load(state)`. If loading fails, it publishes `long_term_memory.load.failed`, returns `long_term_memories=[]` and `long_term_memory_context=""`, and stores the exception text in `long_term_memory_load_error`. The conversation continues without retrieved long-term memory context for that turn.
 The `persist_long_term_memory` node catches exceptions from `long_term_memory_manager.persist_turn(state)`. A successful write publishes `long_term_memory.persist.completed` and stores its return value in `long_term_memory_write_result`; a failure publishes `long_term_memory.persist.failed` and returns `{"saved": 0, "error": str(exc)}` in the same field. Thus, a long-term memory persistence failure is isolated within the node and does not automatically terminate the graph with an exception.
 These fields concern the workflow's long-term memory and are separate from LangGraph checkpoint persistence.
 **Implementation reference:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`load_long_term_memory`, `persist_long_term_memory`).
 ### 12.7. Checkpoints, retries, and integrity
 The graph is compiled with the checkpointer created by `create_langgraph_checkpointer(self.settings)` and uses `conversation_key` or `session_id` as `thread_id` in `ainvoke`. The repository layer in `checkpoints/checkpoint_repository.py` retries operations protected by `_with_retry`: after an exception, it computes a bounded exponential delay with jitter, records `checkpoint.<operation>.retry`, and retries up to `retry_policy.max_attempts`. Once attempts are exhausted, it re-raises the last exception.
 On recovery, `recover_latest` scans recent records, discards those failing `is_valid_checkpoint`, and skips checkpoints with `CheckpointIntegrityError`, recording `checkpoint.recovery.skip_corrupt`. If no valid checkpoint remains after integrity failures, recovery returns `None` so execution can begin without restored state. Compaction after a write is isolated: a failure records `checkpoint.compaction.failed` and does not undo the completed write.
 Integrity recovery cannot guarantee retention of history if no valid checkpoint can be recovered. Storage-communication errors that exceed the retry policy follow the exception path of the calling component.
 **Implementation references:** `libs/agent_framework/src/agent_framework/checkpoints/checkpoint_repository.py`, `checkpoints/langgraph_saver.py`; `templates/agent_template_backend/app/workflows/agent_graph.py` (`ainvoke`).
 ### 12.8. Output supervision and output guardrails
 `output_supervisor` evaluates the response and interprets `RailAction`. For `ALLOW`, `SANITIZE`, and `OBSERVE`, it uses `decision.candidate`; for `HANDOVER`, it supplies a message referring the user to a specialist; for other actions, it uses `decision.fallback_message`. The action, guidance, and results are stored in `supervisor_action`, `supervisor_guidance`, and `output_supervisor_results`.
 The node sets `output_guardrails_already_applied=True`. When `output_guardrails` sees this flag, it returns the prepared response without running the pipeline again. Otherwise, it runs `guardrails.run_output`, records decisions, blocks, and GRL completion, then returns `final_answer`.
 The parallel rail executor (`guardrails/parallel_executor.py`) converts unexpected task failures to `RailResult`: it selects `RailAction.BLOCK` when `fail_closed` is enabled and `RailAction.OBSERVE` otherwise. This is executor policy, not a claim that all guardrails fail closed. The executor also handles cancellation and early termination when a terminal action is produced.
 **Implementation references:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`output_supervisor`, `output_guardrails`); `libs/agent_framework/src/agent_framework/guardrails/parallel_executor.py`.
 ### 12.9. Judges and supervisor review
 The `judge` node builds evaluation context from MCP results, RAG results, and relevant transaction evidence, executes evaluation, and stores outcomes in `judge_results`. The subsequent review invokes `self.supervisor.review` and records `supervisor.review.completed`. A judge's failing score or recommendation belongs to evaluation and review; it is not, by definition, an infrastructure exception.
 The judge layer validates configuration and structured responses. The calibrated judge client raises `ValueError` for unsupported tasks or invalid structured output. LLM construction and loading of judge configuration can also raise `RuntimeError` or `ValueError` under the conditions checked in `judges/judge.py`. Exceptions not caught within the node propagate to `ainvoke`.
 **Implementation references:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`judge`, `supervisor_review`); `libs/agent_framework/src/agent_framework/judges/judge.py`, `judges/calibrated/llm_client.py`.
 ### 12.10. Final persistence and workflow-level failure
 The `persist` node emits completion observability, including the IC event `AGENT_COMPLETED`. The public graph entry point is `ainvoke`, which configures the thread, starts workflow telemetry, and emits the start events `NOC.001` and `AGENT_STARTED` before calling `self.graph.ainvoke`.
 If `graph.ainvoke` completes, the workflow is marked completed and its final state is returned. If an exception escapes the graph, the `except Exception` handler in `ainvoke` calls `workflow_telemetry.failed("agent_workflow", exc)`, emits `NOC.005` with `error` and `exception_type`, and re-raises the same exception. This path does not automatically convert the error into a successful conversational response.
 Failures handled inside nodes, such as long-term memory failures, do not trigger the global `except`. Unhandled errors in routing, agent execution, checkpoint storage, or other stages may reach this boundary and cause a workflow-level failure.
 **Implementation reference:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`persist`, `ainvoke`).
 ### 12.11. Operational events and tracing
 `_node` wraps every node execution in `self.langgraph_telemetry.node(name, state)`. Additional mechanisms use workflow spans, semantic events, and the observer for GRL, IC, and NOC. Concrete records in the flow include `session.message.rejected_after_end`, `guardrails.input.completed`, `guardrails.output.completed`, `output_supervisor.completed`, `supervisor.review.completed`, `long_term_memory.load.failed`, `long_term_memory.persist.failed`, `long_term_memory.persist.completed`, and `workflow_telemetry.failed` on workflow-level failure.
 Operational errors should be correlated using `conversation_key` or `session_id`, together with `tenant_id` and `agent_id` when available. A memory or tool failure event does not necessarily indicate overall workflow failure; this depends on whether the component returned a state/result or propagated an exception.
 **Implementation references:** `templates/agent_template_backend/app/workflows/agent_graph.py`; `libs/agent_framework/src/agent_framework/observability/`.
 ## 13. Integration interfaces
 | Interface | Runtime integration |
 |---|---|
 | LangGraph | State-graph construction, compilation, and execution. |
 | Domain agents | Specialized billing, product, order, and support nodes. |
 | MCP | Tool selection, parameter mapping, and execution by agents. |
 | RAG | Knowledge retrieval incorporated into agent execution. |
 | Guardrails | Input and output evaluation. |
 | Judges | Evaluation after response generation. |
 | Memory | Long-term information loading and writing. |
 | Checkpointer | Graph-state persistence. |
 | Observability | Per-node telemetry and execution tracing. |
 ## 14. Implementation references
 - `libs/agent_framework/src/agent_framework/runtime/`
 - `templates/agent_template_backend/app/state.py`
 - `templates/agent_template_backend/app/workflows/agent_graph.py`
 - `templates/agent_template_backend/config/agents.yaml`
 - `templates/agent_template_backend/config/routing.yaml`
 - `templates/agent_template_backend/config/tools.yaml`
 - [`SPEC-004 — MCP Gateway`](SPEC-004-MCP-Gateway.md)
 - [`SPEC-005 — Guardrails`](SPEC-005-Guardrails.md)
 - [`SPEC-007 — Observability`](SPEC-007-Observability.md)
 - [`SPEC-012 — Canonical Contracts`](SPEC-012-Canonical-Contracts.md)
--- a/specs/en/SPEC-003-Agent-Gateway.md
+++ b/specs/en/SPEC-003-Agent-Gateway.md
@@ -0,0 +1,273 @@
 # SPEC-003 — Agent Gateway
 ## Scope
 The Agent Gateway is the platform's single entry point for channels and external consumers.
 It receives messages, manages global sessions, resolves the responsible backend or agent, performs routing and cross-agent/backend handoffs, and forwards SSE events.
 The Agent Gateway does not run LLM inference or embeddings. Those capabilities belong to the Runtime and Agent Framework.
 ---
 ## Responsibilities
 ### Single platform entry point
 ```text
 Web
 WhatsApp
 Voice
 Teams
 Slack
      |
      v
 Agent Gateway
      |
      +--> Agent Backend A
      |
      +--> Agent Backend B
      |
      +--> Agent Backend C
 ```
 ### Session management
 Responsible for:
 - Creation of Sessions
 - Recovery of Sessions
 - Update of Context global
 - Persistence of metadata of Session
 - correlation of requests
 Example:
 ```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 must processar a Message.
 Example:
 ```yaml
 backends:
  telecom_contas:
    url: http://backend-contas:8000
  telecom_ofertas:
    url: http://backend-ofertas:8000
 ```
 Possible criteria:
 - Backend Standard
 - Rules YAML
 - intent detected
 - Context of the Session
 - Router LLM (Optional)
 ---
 ## Handoff
 Allows transferência between Agents or backends.
 Example:
 ```text
 Contas
   |
   +--> Ofertas
   |
   +--> Retenção
 ```
 A handoff must preserve:
 - session_id
 - conversation_key
 - business context
 - History of the conversation
 - metadata of correlation
 ---
 ## SSE Proxy
 responsible for forward Events of streaming for clientes.
 ### Endpoints
 | Method | Endpoint |
 |----------|----------|
 | POST | /gateway/message |
 | POST | /gateway/message/sse |
 | GET | /gateway/events/{session_id} |
 Supported SSE events:
 - connected
 - workflow.started
 - message.responded
 - workflow.completed
 - flow.end
 - error
 ---
 ## Backend Discovery
 Can operate with Catalog static or discovery dynamic.
 ### Catalog static
 ```yaml
 backends:
  telecom_contas:
    url: http://contas:8000
  telecom_ofertas:
    url: http://ofertas:8000
 ```
 ### discovery dynamic
 ```yaml
 service_discovery:
  enabled: true
 ```
 Capabilities:
 - Registration automatic
 - Health check periodic
 - Update of Catalog
 - synchronization of metadata
 ---
 ## Health and Operations
 ### Endpoints
 | Method | Endpoint |
 |----------|----------|
 | GET | /health |
 | GET | /ready |
 | GET | /backends |
 | GET | /debug/sessions |
 ---
 ## Contract 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"
  }
 }
 ```
 ---
 ## Contract 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"
  }
 }
 ```
 ---
 ## Events
 | Evento | Description |
 |----------|----------|
 | agent.gateway.request.received | Request recebida |
 | agent.gateway.session.created | Session criada |
 | agent.gateway.backend.selected | Backend selected |
 | agent.gateway.handoff.started | Handoff iniciado |
 | agent.gateway.handoff.completed | Handoff concluído |
 | agent.gateway.sse.connected | Cliente SSE conectado |
 | agent.gateway.request.failed | Failure of processing |
 ---
 ## Metrics
 | metric | 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 |
 ---
 ## Security
 - Authentication obrigatória when configured.
 - Propagação of Identity between gateways.
 - Máscara of Data sensíveis em logs.
 - correlation por request_id, trace_id and session_id.
 - control of acesso por tenant.
 ---
 ## Requirements No Funcionais
 | Categoria | Requirement |
 |----------|----------|
 | Availability | Expor /health and /ready |
 | Escalabilidade | Stateless with escala horizontal |
 | Observability | Logs, Metrics and traces |
 | Auditabilidade | all as Decisions of Routing rastreáveis |
 | Security | Segredos external and mascaramento |
 | Portabilidade | Local, Docker and Kubernetes |
 | Configuration | YAML and variáveis of ambiente |
 ---
 ## Acceptance criteria
 - [ ] Recebe Messages of múltiplos canais.
 - [ ] Seleciona backend corretamente.
 - [ ] maintains Session global.
 - [ ] Encaminha SSE.
 - [ ] Executa handoff.
 - [ ] Preserva Business Context.
 - [ ] Suporta múltiplos backends.
 - [ ] Allows discovery dynamic.
 - [ ] Expõe Health and readiness.
 - [ ] Gera Metrics and telemetria.
--- a/specs/en/SPEC-004-MCP-Gateway.md
+++ b/specs/en/SPEC-004-MCP-Gateway.md
@@ -0,0 +1,231 @@
 # SPEC-004 — MCP Gateway
 ## Scope
 O MCP Gateway centraliza Catalog, Authorization, Routing, Execution, cache, timeout, retry, Observability and Response padronizada of tools MCP.
 ## Endpoints
 | Method | Endpoint | Description |
 |---|---|---|
 | `GET` | `/health` | Health check. |
 | `GET` | `/ready` | Readiness check. |
 | `GET` | `/v1/tools` | Catalog of tools. |
 | `GET` | `/v1/tools/{tool_name}` | Detalhe of the tool. |
 | `POST` | `/v1/tools/{tool_name}/invoke` | Execution of 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
 ```
 ## Authorization
 ```yaml
 authorization:
  default_policy: deny
  agents:
    telecom_contas:
      allowed_tools:
        - consultar_fatura
        - consultar_pagamentos
        - consultar_plano
 ```
 ## Cache
 | Regra | value |
 |---|---|
 | Chave | `tenant_id:agent_id:tool_name:hash(arguments)` |
 | Aplicação | only tools idempotentes |
 | Bypass | `metadata.cache_bypass=true` |
 | TTL | `cache_ttl_seconds` |
 | Escrita | No cachear operações mutáveis |
 ## Retry and 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
 ```
 ## Events
 | Evento | Description |
 |---|---|
 | `mcp.tool.requested` | Tool requisitada. |
 | `mcp.tool.authorized` | Authorization aprovada. |
 | `mcp.tool.denied` | Authorization negada. |
 | `mcp.tool.started` | Execution iniciada. |
 | `mcp.tool.completed` | Execution concluída. |
 | `mcp.tool.failed` | Execution failed. |
 | `mcp.cache.hit` | Cache hit. |
 | `mcp.cache.miss` | Cache miss. |
 ## Metrics
 | metric | 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 |
 ## Security
 - Tools are negadas por Standard.
 - Argumentos sensíveis are mascarados.
 - Tools mutáveis exigem confirmação when configured.
 - MCP servers No recebem payload bruto of canal.
 - Credenciais of backend are mantidas nos MCP servers or secret store.
 ## Requirements No Funcionais
 | Categoria | Requirement |
 |---|---|
 | Availability | Components deployáveis expõem `/health` and `/ready`. |
 | Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
 | Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
 | Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
 | Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
 | Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
 | Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |
 ## Acceptance criteria
 - [ ] Catalog of tools retorna tools habilitadas.
 - [ ] ToolInvocation is validado before of the Execution.
 - [ ] Authorization por Agent is aplicada.
 - [ ] Parâmetros are derivados of the BusinessContext.
 - [ ] Cache só is applied a tools idempotentes.
 - [ ] Timeout/retry/circuit breaker are configuráveis.
 - [ ] Events and Metrics are emitidos.
 - [ ] Failures retornam ToolResult padronizado.
 - [ ] MCP servers are substituíveis por Configuration.
 - [ ] Tools críticas possuem Tests of Contract.
 ## Glossário
 | Termo | Definição |
 |---|---|
 | Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
 | Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
 | Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
 | Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
 | Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
 | AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
 | MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
 | Evaluator | layer of Evaluation online/offline, regressão and Certification. |
 | Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |
 ## Policy mínima of Operations
 before forward a tool, The runtime must apply a Policy Optional of the backend em `config/tool_policies.yaml`. Os tipos canônicos are `read_only` and `transactional`; esta última can exigir confirmação booleana explícita and fields required. A ausência of the file No is Error and preserva os fields legados of `tools.yaml`. A Policy conversational No substitui Authentication, Authorization, idempotência nem atomicidade no MCP Server.
--- a/specs/en/SPEC-005-Guardrails.md
+++ b/specs/en/SPEC-005-Guardrails.md
@@ -0,0 +1,194 @@
 # SPEC-005 — Guardrails
 ## Scope
 Guardrails are Policies executadas sobre Input, Output, tool calls, RAG and responses finais. The platform suporta guardrails global, por Agent, por canal and por fase.
 ## Fases
 | Fase | Input | Output |
 |---|---|---|
 | Input | `user_text`, `context` | `sanitized_input`, `GuardrailResult` |
 | Tool | `ToolInvocation` | tool allowed/bloqueada |
 | RAG | query/Context recuperado | Context aprovado/filtrado |
 | Output | `response_text` | Response aprovada/sanitizada/bloqueada |
 | Review | Response + evidências | Decision 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"
  }
 }
 ```
 ## Configuration 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
 ```
 ## Configuration por Agent
 ```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` | applies Block, máscara or alteração. |
 | `observe` | Registra without bloquear. |
 | `fail_open` | Em Error técnico, prossegue and emite NOC. |
 | `fail_closed` | Em Error técnico, bloqueia. |
 ## Tipos
 | Tipo | Implementation |
 |---|---|
 | Determinístico | Regex, listas, tamanho, structure, Rules. |
 | 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
 ```
 ## Flow
 ```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]
 ```
 ## Events
 | Evento | Description |
 |---|---|
 | `guardrail.started` | Execution iniciada. |
 | `guardrail.completed` | Execution concluída. |
 | `guardrail.blocked` | Conteúdo bloqueado. |
 | `guardrail.masked` | Conteúdo mascarado. |
 | `guardrail.failed` | Failure técnica. |
 | `guardrail.observe` | Policy observacional registrada. |
 ## Códigos Base
 | Código | Fase | Uso |
 |---|---|---|
 | `MSK` | input/output | Mascaramento. |
 | `VLOOP` | input | Detecção of loop. |
 | `PINJ` | input/output | Prompt injection. |
 | `REVPREC` | output | Review of precisão. |
 | `DLEX_OUT` | output | control of Data and linguagem na Output. |
 | `RAGSEC` | rag/output | Security of Context recuperado. |
 ## Tests
 | Test | objective |
 |---|---|
 | Unitário | validate guardrail isolado. |
 | Config | validate YAML and schema. |
 | integration | validate Execution no workflow. |
 | Observability | validate Events and traces. |
 | Negativo | validate Block. |
 | Observe-only | validate No Block. |
 ## Requirements No Funcionais
 | Categoria | Requirement |
 |---|---|
 | Availability | Components deployáveis expõem `/health` and `/ready`. |
 | Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
 | Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
 | Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
 | Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
 | Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
 | Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |
 ## Acceptance criteria
 - [ ] Guardrails global are carregados por YAML.
 - [ ] Guardrails por Agent sobrescrevem or complementam global.
 - [ ] GuardrailResult is gerado for each Execution.
 - [ ] Modo enforce bloqueia when aplicável.
 - [ ] Modo observe No bloqueia.
 - [ ] Failures técnicas seguem Policy configured.
 - [ ] Guardrails LLM usam profile dedicado.
 - [ ] Events and Metrics are emitidos.
 - [ ] Tests cobrem casos positivos and negativos.
 - [ ] Output guardrails executam before of the Response final.
 ## Glossário
 | Termo | Definição |
 |---|---|
 | Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
 | Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
 | Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
 | Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
 | Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
 | AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
 | MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
 | Evaluator | layer of Evaluation online/offline, regressão and Certification. |
 | Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |
--- a/specs/en/SPEC-006-Evals.md
+++ b/specs/en/SPEC-006-Evals.md
@@ -0,0 +1,226 @@
 # SPEC-006 — Evals
 ## Scope
 The layer of Evals executa Evaluation online, Evaluation offline, regressão, Certification and publicação of Metrics. Ela padroniza Validation of Agents, prompts, tools, responses and guardrails.
 ## Components
 | Componente | Responsibility |
 |---|---|
 | Online Judges | Evaluation during a Execution. |
 | Offline Evaluator | Evaluation batch of conversas. |
 | Dataset Runner | Execution of datasets versionados. |
 | Regression Runner | Comparação between versions. |
 | Certification Suite | Validation técnica and funcional. |
 | Metrics Engine | Cálculo of Metrics. |
 | Persistence | Persistence of runs and itens. |
 | Exporter | Exportação TXT.GZ/JSON/HTML. |
 | Publisher | Publicação of scores no Langfuse. |
 ## Flow 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": []
 }
 ```
 ## Metrics
 | metric | Description | Faixa |
 |---|---|---|
 | `quality` | Clareza, completude and utilidade. | 0–1 |
 | `groundedness` | Aderência evidências MCP/RAG. | 0–1 |
 | `safety` | compliance of Security. | 0–1 |
 | `resolution` | Capacity of resolve a intent. | 0–1 |
 | `tool_correctness` | Uso correct of tools. | 0–1 |
 | `policy_compliance` | Aderência Rules of Domain. | 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
 | Method | Endpoint | Description |
 |---|---|---|
 | `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. |
 ## Persistence
 | table | Conteúdo |
 |---|---|
 | `EVAL_RUNS` | Runs executadas. |
 | `EVAL_ITEMS` | Conversas avaliadas. |
 | `EVAL_SCORES` | Scores por metric. |
 | `EVAL_FINDINGS` | Achados. |
 | `EVAL_EXPORTS` | files exportados. |
 ## Certification
 A Certification Suite valida:
 - endpoints of health;
 - GatewayRequest;
 - Routing;
 - MCP tools;
 - guardrails;
 - judges;
 - Memory;
 - checkpoint;
 - Langfuse/OTEL;
 - datasets minimum;
 - evidências JSON/HTML.
 ## Events
 | Evento | Description |
 |---|---|
 | `eval.run.started` | Run iniciada. |
 | `eval.item.completed` | Item avaliado. |
 | `eval.run.completed` | Run concluída. |
 | `eval.run.failed` | Run failed. |
 | `eval.score.published` | Score publicado. |
 ## Requirements No Funcionais
 | Categoria | Requirement |
 |---|---|
 | Availability | Components deployáveis expõem `/health` and `/ready`. |
 | Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
 | Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
 | Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
 | Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
 | Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
 | Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |
 ## Acceptance criteria
 - [ ] Evaluator executa runs por período/Agent.
 - [ ] Langfuse is source suportada.
 - [ ] Datasets are versionados.
 - [ ] LLM Judges usam profile `judge`.
 - [ ] Scores are persistidos.
 - [ ] TXT.GZ/JSON/HTML are exportáveis.
 - [ ] Scores Can be publicados no Langfuse.
 - [ ] Certification Suite gera evidências.
 - [ ] Metrics mínimas are padronizadas.
 - [ ] Failures permitem retomada por checkpoint of run.
 ## Glossário
 | Termo | Definição |
 |---|---|
 | Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
 | Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
 | Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
 | Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
 | Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
 | AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
 | MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
 | Evaluator | layer of Evaluation online/offline, regressão and Certification. |
 | Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |
--- a/specs/en/SPEC-007-Observability.md
+++ b/specs/en/SPEC-007-Observability.md
@@ -0,0 +1,202 @@
 # SPEC-007 — Observability
 ## Scope
 Observability cobre logs, Metrics, traces, Events IC/NOC/GRL, Langfuse, OpenTelemetry, dashboards, Alerts and evidências operational.
 ## correlation
 fields required:
 ```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]
 ```
 ## Metrics
 | metric | 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
 Data registrados:
 - trace of conversation;
 - spans técnicos;
 - generations LLM;
 - prompts and responses when allowed;
 - tokens;
 - Costs;
 - Latency;
 - scores;
 - metadata;
 - erros.
 ## OpenTelemetry
 Configuration:
 ```yaml
 otel:
  enabled: true
  service_name: agent-runtime
  exporter: otlp
  endpoint: http://otel-collector:4317
 ```
 ## IC/NOC/GRL
 | Família | Events |
 |---|---|
 | 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 | traffic, erros, Latency, Sessions. |
 | Agent Runtime | rotas, intents, Memory, checkpoints. |
 | LLM Usage | tokens, Cost, Latency, provider/model. |
 | MCP Operations | Calls, erros, cache, Latency. |
 | Guardrails | Blocks, observe-only, códigos. |
 | Evals | scores, trends, regressões. |
 | Channels | traffic por canal, erros, retries. |
 ## Alerts
 | Alert | Condition |
 |---|---|
 | `GatewayHighErrorRate` | Erros 5xx above of the Limit. |
 | `RuntimeLatencyHigh` | p95 above of the SLO. |
 | `LLMProviderUnavailable` | Failures consecutive of provider. |
 | `MCPToolTimeoutSpike` | increase of timeouts. |
 | `GuardrailBlockSpike` | increase abnormal of Blocks. |
 | `EvaluatorRunFailed` | run batch failed. |
 | `CheckpointFailure` | Failure persistente em checkpoint. |
 ## Mascaramento
 fields mascarados:
 - tokens;
 - API keys;
 - senhas;
 - secrets;
 - CPF/CNPJ, when aplicável;
 - telefone, when configured;
 - payload bruto of canal;
 - documentos sensíveis.
 ## Evidências
 Relatórios of homologação Include:
 - health checks;
 - logs of Execution;
 - traces Langfuse;
 - Metrics;
 - results of guardrails;
 - results of judges;
 - Calls MCP;
 - Calls LLM;
 - relatório of the evaluator;
 - relatório of the certification suite.
 ## Requirements No Funcionais
 | Categoria | Requirement |
 |---|---|
 | Availability | Components deployáveis expõem `/health` and `/ready`. |
 | Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
 | Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
 | Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
 | Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
 | Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
 | Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |
 ## Acceptance criteria
 - [ ] all os services emitem Structured logs.
 - [ ] Trace correlaciona gateway, runtime, MCP, LLM, guardrails and judges.
 - [ ] Langfuse recebe traces when enabled.
 - [ ] OTEL exporta spans when enabled.
 - [ ] Metrics mínimas are disponíveis.
 - [ ] Dashboards are definidos.
 - [ ] Alerts are definidos.
 - [ ] Segredos and PII are mascarados.
 - [ ] Evaluator consome Data observáveis.
 - [ ] Certification Suite gera evidências.
 ## Glossário
 | Termo | Definição |
 |---|---|
 | Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
 | Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
 | Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
 | Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
 | Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
 | AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
 | MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
 | Evaluator | layer of Evaluation online/offline, regressão and Certification. |
 | Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |
--- a/specs/en/SPEC-008-Deployment.md
+++ b/specs/en/SPEC-008-Deployment.md
@@ -0,0 +1,233 @@
 # SPEC-008 — Deployment
 ## Scope
 Deployment cobre empacotamento, CI/CD, Kubernetes/OKE, Docker, secrets, Authentication OCI, health checks, rollback and Operations of the Components.
 ## Components 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 Optional |
 ## 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 with endpoint OpenAI-Compatible | API key |
 | OCI Compute | `instance_principal` |
 | OKE | `workload_identity` or `resource_principal` |
 | Tests | `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, if aplicável |
 ## Health Checks
 | Endpoint | Uso |
 |---|---|
 | `/health` | Process vivo. |
 | `/ready` | ready for traffic. |
 | `/version` | Version of build. |
 | `/debug/env` | Ambiente without segredos, when enabled. |
 ## Rollback
 Itens considerados:
 - tag of the imagem;
 - Version of the pacote Python;
 - Version of the schemas;
 - Version of the YAMLs;
 - migrations;
 - datasets of 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;
 - Contract GatewayRequest;
 - Routing;
 - MCP invoke;
 - LLM mock/real conforme ambiente;
 - guardrails;
 - judges;
 - Memory/checkpoint;
 - relatório JSON/HTML.
 ## Requirements No Funcionais
 | Categoria | Requirement |
 |---|---|
 | Availability | Components deployáveis expõem `/health` and `/ready`. |
 | Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
 | Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
 | Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
 | Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
 | Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
 | Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |
 ## Acceptance criteria
 - [ ] each app possui Dockerfile.
 - [ ] each app possui manifest Kubernetes.
 - [ ] CI executa lint, type check and Tests.
 - [ ] Contract tests validam Main contracts.
 - [ ] Security scan executa before of the publish.
 - [ ] Secrets No are versionados.
 - [ ] Workload Identity is configured em OKE.
 - [ ] Health/readiness/liveness are ativos.
 - [ ] Smoke tests rodam após deploy.
 - [ ] Rollback is documentado.
 ## Glossário
 | Termo | Definição |
 |---|---|
 | Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
 | Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
 | Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
 | Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
 | Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
 | AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
 | MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
 | Evaluator | layer of Evaluation online/offline, regressão and Certification. |
 | Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |
--- a/specs/en/SPEC-009-Channel-Gateway.md
+++ b/specs/en/SPEC-009-Channel-Gateway.md
@@ -0,0 +1,197 @@
 # SPEC-009 — Channel Gateway
 ## Scope
 O Channel Gateway normaliza payloads of canais external for GatewayRequest and traduz ChannelResponse for the formato of Response of the canal.
 ## Modos of Operations
 | Modo | Description |
 |---|---|
 | Embedded | Normalização no próprio backend for demos and cenários simples. |
 | External | service dedicado for 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"
  }
 }
 ```
 ## Flow External
 ```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
 ```
 ## Responsibilities
 | Responsibility | Detalhe |
 |---|---|
 | Auth | validate assinatura, token or origem. |
 | Parse | Interpretar payload bruto. |
 | Dedup | Evitar reprocessamento por message_id. |
 | Normalize | create GatewayRequest. |
 | Business Context | Mapear chaves canônicas. |
 | Forward | Chamar Agent Gateway. |
 | Translate | Converter ChannelResponse for canal. |
 | Observe | emit logs, Metrics and traces. |
 ## Idempotência
 Chave:
 ```text
 tenant_id:channel:user_id:message_id
 ```
 Comportamentos:
 | Situação | Ação |
 |---|---|
 | Primeira Message | Processar. |
 | Duplicada em andamento | return 202 or Response controlada. |
 | Duplicada concluída | return Response previous. |
 ## Versionamento
 Header:
 ```http
 X-Agent-Framework-Contract: gateway-request-v1
 ```
 field alternativo:
 ```json
 {
  "payload": {
    "metadata": {
      "contract_version": "gateway-request-v1"
    }
  }
 }
 ```
 ## Security
 Validations:
 - assinatura of the webhook;
 - origem allowed;
 - tamanho máximo;
 - tipo of evento allowed;
 - anexos permitidos;
 - sanitização of texto;
 - remoção of tokens;
 - máscara of Data sensíveis;
 - rate limit;
 - deduplicação.
 ## Erros
 | Código HTTP | Uso |
 |---|---|
 | 400 | Payload invalid of the canal. |
 | 401 | Authentication ausente. |
 | 403 | Origem No autorizada. |
 | 422 | GatewayRequest invalid. |
 | 429 | Rate limit. |
 | 500 | Error Internal. |
 | 503 | Runtime unavailable. |
 ## Anti-patterns
 - Agent lendo payload bruto.
 - Workflow tratando `channel == whatsapp`.
 - MCP recebendo payload bruto.
 - Tokens of the canal em metadata.
 - Gateway External executando regra of Agent.
 - Frontend enviando fields outside of the Contract.
 ## Requirements No Funcionais
 | Categoria | Requirement |
 |---|---|
 | Availability | Components deployáveis expõem `/health` and `/ready`. |
 | Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
 | Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
 | Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
 | Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
 | Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
 | Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |
 ## Acceptance criteria
 - [ ] Payload bruto is convertido for GatewayRequest.
 - [ ] GatewayRequest is validado.
 - [ ] message_id Is used to idempotência.
 - [ ] business_context contains chaves canônicas.
 - [ ] Response of the runtime is traduzida for the canal.
 - [ ] Payload bruto No chega ao Agent Runtime.
 - [ ] Auth/rate limit/dedup are implementados.
 - [ ] Erros are padronizados.
 - [ ] Contract possui Version.
 - [ ] Logs/traces usam request_id and trace_id.
 ## Glossário
 | Termo | Definição |
 |---|---|
 | Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
 | Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
 | Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
 | Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
 | Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
 | AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
 | MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
 | Evaluator | layer of Evaluation online/offline, regressão and Certification. |
 | Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |
--- a/specs/en/SPEC-010-Agent-Development.md
+++ b/specs/en/SPEC-010-Agent-Development.md
@@ -0,0 +1,333 @@
 # SPEC-010 — Agent Development
 ## Scope
 Esta SPEC Defines o Standard for Creation of Agents usando templates, Configuration YAML, BusinessContext, MCP, guardrails, judges, RAG, Memory, Observability and evals.
 ## structure of the 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
 ```
 ## Responsibilities of the Framework
 - LangGraph;
 - Memory;
 - checkpoint;
 - Session;
 - router;
 - supervisor;
 - guardrails;
 - judges;
 - telemetry;
 - MCP integration;
 - RAG genérico;
 - cache;
 - providers LLM;
 - event bus.
 ## Responsibilities of the Agent
 - prompts of Domain;
 - Rules of negócio;
 - schemas específicos;
 - Decision of uso of evidências;
 - handling of fields required;
 - Messages of Domain;
 - ICs of jornada;
 - datasets of eval específicos.
 ## Registration of the Agent
 ```yaml
 agents:
  financeiro_agent:
    enabled: true
    description: "Agente financeiro"
    profile: financeiro_agent
    rag_namespace: financeiro
    allowed_tools:
      - consultar_fatura
      - consultar_pagamentos
 ```
 ## Routing
 ```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 of Agent
 ```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 of Confiança of the Data
 1. `tool_arguments`
 2. `business_context`
 3. `context`
 4. `session.metadata`
 5. `state`
 6. extração complementar of the texto
 ## Prompt Policy
 ```yaml
 prompt_policy:
  system_prompt_path: prompts/system.md
  response_style: concise
  require_evidence: true
  allow_tool_usage: true
 ```
 ## Guardrails por Agent
 ```yaml
 input:
  - code: FIN_INPUT_POLICY
    enabled: true
    mode: observe
 output:
  - code: FIN_OUTPUT_COMPLIANCE
    enabled: true
    mode: enforce
 ```
 ## Judges por Agent
 ```yaml
 judges:
  - name: response_quality
    enabled: true
    threshold: 0.75
  - name: groundedness
    enabled: true
    threshold: 0.70
 ```
 ## Dataset of 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
 ```
 ## Contract Required for Agents transacionais
 Ao create a Agent that Uses tools transacionais of the framework, o desenvolvedor No must create a motor paralelo of coleta/confirmação. must reutilizar `AgentRuntime` and garantir that o `AgentState` of the host mantenha o latch durável:
 ```python
 active_transaction: dict[str, Any]
 last_transaction: dict[str, Any]
 ```
 during a transação ativa, parâmetros já coletados are preservados and new values are mesclados incrementalmente. Em `COLLECTING_PARAMETERS`, a Response that satisfaz a Parameter pendente tem precedência sobre keywords genéricas. changes of intent explícitas and inequívocas continuam permitidas.
 before publicar a new template/host, execute os cenários multi-turno descritos no [`Transaction State Developer Guide`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
 ## Contract MCP Multi-item
 for a intent that opere sobre múltiplos itens homogêneos, o Agent **No must implement fan-out/loop of Calls MCP por conta própria**. must reutilizar The runtime and declarar o Contract natural of the tool. A Input Can be escalar or coleção; `type: array/list` No is Requirement for suporte multi-item.
 Rules:
 1. canonicalização of itens pertence ao MCP/pre-validation and can use `transaction_decision.resolved_arguments`;
 2. confirmação transacional must representar o conjunto efetivo of itens;
 3. a tool primária Must return `results[]` with dois or mais itens containing `success` or `ok` booleano por item;
 4. for workflow-backed tools, a source preferencial is `workflow.output[tool_name].results`;
 5. The runtime normaliza o agregado for `SUCCESS`, `PARTIAL_SUCCESS` or `FAILED`;
 6. Failure em stage auxiliar posterior No can apagar evidência terminal of itens concluídos;
 7. a `eligible=false` global em pre-validation encerra toda transação; for processing parcial, mantenha `eligible=true` when houver ao menos a item acionável and deixe a tool primária materializar o result por item.
 Referência of Implementation: [`MCP Multi-item — Guia do Desenvolvedor`](../docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE.md).
 ## Tests
 | Test | Scope |
 |---|---|
 | Unitário | Classe of the Agent. |
 | Routing | Intent and rota. |
 | MCP Mapping | BusinessContext for argumentos. |
 | Guardrails | Input and Output. |
 | Judges | Scores minimum. |
 | Runtime | Execution completa. |
 | Memory | continuity of conversation. |
 | Checkpoint | Resume/replay. |
 | Observability | Trace and Events. |
 | Certification | Evidências finais. |
 ## Definition of Done
 - Agent registrado;
 - rota configured;
 - tools declaradas;
 - mapping definido;
 - prompts versionados;
 - guardrails configurados;
 - judges configurados;
 - dataset criado;
 - Tests executados;
 - traces gerados;
 - certification suite aprovada;
 - documentation of the Agent atualizada.
 ## Anti-patterns
 - Agent criando Session;
 - Agent abrindo SSE;
 - Agent compilando LangGraph;
 - Agent chamando system External diretamente;
 - prompt hardcoded without Policy;
 - lógica genérica duplicada no Agent;
 - payload bruto of canal inside of the Agent;
 - ausência of dataset of eval.
 ## Requirements No Funcionais
 | Categoria | Requirement |
 |---|---|
 | Availability | Components deployáveis expõem `/health` and `/ready`. |
 | Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
 | Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
 | Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
 | Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
 | Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
 | Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |
 ## Acceptance criteria
 - [ ] new Agent is criado without alterar core of the framework.
 - [ ] if houver transações multi-turno, `AgentState` declara `active_transaction` and `last_transaction`.
 - [ ] Configuration ocorre por YAML and `.env`.
 - [ ] Agent Uses BusinessContext.
 - [ ] Agent acessa MCP por router/gateway.
 - [ ] Casos multi-item usam o Contract natural of the Operations (escalar or coleção) + result por item, without loop MCP of negócio inside of the Agent.
 - [ ] Agent No conhece payload bruto of canal.
 - [ ] Guardrails and judges are configurados.
 - [ ] Dataset of eval existe.
 - [ ] Tests minimum executam.
 - [ ] Trace completo is gerado.
 - [ ] Definition of Done is atendida.
 ## Glossário
 | Termo | Definição |
 |---|---|
 | Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
 | Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
 | Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
 | Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
 | Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
 | AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
 | MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
 | Evaluator | layer of Evaluation online/offline, regressão and Certification. |
 | Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |
--- a/specs/en/SPEC-011-Governance-Model.md
+++ b/specs/en/SPEC-011-Governance-Model.md
@@ -0,0 +1,347 @@
 # SPEC-011 — Governance Model
 ## Agent Platform OCI
 Version: 1.0.0
 ---
 ## Reading guide
 each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
 The document structure is:
 1. Concept.
 2. Problem addressed.
 3. When to use.
 4. When not to use.
 5. Architecture.
 6. Implementation.
 7. Examples.
 8. Common errors.
 9. Acceptance criteria.
 ---
 # 1. Concept
 Governance is o conjunto of papéis, Responsibilities, controles, aprovações, evidências and processos that Allows that a Agent Platform OCI seja usada por múltiplos times without perder Standardization, Security, rastreabilidade and Capacity of evolução.
 A Governance No substitui a engenharia. Ela Defines como a engenharia evolui of forma controlada.
 Em a plataforma of Agents, Governance cobre:
 - quem can create Agents;
 - quem can alterar prompts;
 - quem can liberar MCP tools;
 - quem aprova changes of guardrails;
 - quem aprova modelos;
 - quem aprova datasets;
 - quem promove for Production;
 - quais evidências are obrigatórias;
 - como auditar Decisions of the plataforma.
 # 2. Problem addressed
 without Governance, each time tende a create Agents of forma diferente.
 Problemas comuns:
 - prompts without versionamento;
 - MCP tools without owner;
 - datasets ausentes;
 - Agents without Evaluation;
 - Production without certification;
 - changes of Model without rastreabilidade;
 - guardrails duplicados;
 - Rules of negócio inside of the runtime;
 - uso diferente of the plataforma por each fornecedor;
 - dificuldade of maintenance.
 A Governance cria Model único of adoção.
 # 3. Domínios of Governance
 | Domain | Scope |
 | --- | --- |
 | Platform Governance | Framework, Runtime, Gateways, Evaluator, Certification Suite. |
 | Agent Governance | Agents, prompts, Rules of negócio, datasets and configs. |
 | Model Governance | LLM profiles, providers, fallback, Cost and uso. |
 | MCP Governance | Tools, MCP servers, owners, SLAs, Authorization and contracts. |
 | Data Governance | BusinessContext, RAG, datasets, Memory and retenção. |
 | Security Governance | Identity, Authorization, secrets, auditoria and PII. |
 | Operational Governance | Deploy, monitoramento, Alerts, SLOs and incidents. |
 | Evaluation Governance | Judges, evaluator, certification and Metrics. |
 # 4. Model of ownership
 ## 4.1. Platform Team
 Responsible for:
 - Agent Framework;
 - Agent Runtime;
 - Agent Gateway;
 - Channel Gateway;
 - AI Gateway;
 - MCP Gateway;
 - Evaluator;
 - Certification Suite;
 - contracts canônicos;
 - documentation of the plataforma;
 - templates oficiais.
 ## 4.2. Domain Team
 Responsible for:
 - comportamento of the Agent;
 - prompts;
 - Rules of negócio;
 - datasets;
 - Configuration específicas;
 - Validation funcional;
 - criteria of success.
 ## 4.3. Integration Team
 Responsible for:
 - MCP servers;
 - APIs external;
 - SLAs of tools;
 - contracts of integration;
 - credenciais of backend;
 - Availability of sistemas external.
 ## 4.4. SRE / DevOps
 Responsible for:
 - CI/CD;
 - deploy;
 - Observability;
 - Alerts;
 - Capacity;
 - SLOs;
 - runbooks;
 - rollback.
 ## 4.5. Security / Architecture
 Responsible for:
 - Security;
 - Architecture;
 - policies;
 - Workload Identity;
 - secrets;
 - Review of Risk;
 - approval of Exceptions.
 # 5. RACI
 | activity | 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. Governance of Agents
 Todo Agent must 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
 ```
 artifacts required:
 - `agents.yaml`;
 - `routing.yaml`;
 - `prompt_policy.yaml`;
 - `guardrails.yaml`;
 - `judges.yaml`;
 - `tools.yaml`;
 - `mcp_parameter_mapping.yaml`;
 - dataset of regressão;
 - Tests;
 - evidências of evaluator;
 - evidências of certification.
 # 7. Governance of prompts
 Prompts must be versionados and rastreáveis.
 ```yaml
 prompt:
  name: billing_system_prompt
  version: 1.3.0
  owner: billing_team
  reviewed_at: 2026-06-19
  status: approved
 ```
 changes of prompt exigem:
 1. Review of the domain owner;
 2. Execution of dataset;
 3. evaluator;
 4. comparação contra baseline;
 5. Registration of the Version.
 # 8. Governance of guardrails
 Guardrails global belong à plataforma/Security.
 Guardrails por Agent belong ao Domain, mas precisam seguir o Contract of the plataforma.
 ```yaml
 guardrail:
  code: REVPREC
  version: 2.0.0
  owner: platform_security
  phase: output
  mode: enforce
 ```
 changes em guardrails `enforce` exigem certification.
 # 9. Governance of judges
 Judges must ter objective, metric, threshold and owner.
 ```yaml
 judge:
  name: groundedness
  version: 1.1.0
  threshold: 0.70
  owner: platform_quality
 ```
 changes of threshold exigem reexecução of the evaluator.
 # 10. Governance of modelos
 Agents No referenciam Model diretamente.
 O Model is resolvido por profile.
 ```yaml
 profiles:
  judge:
    provider: oci_openai
    model: openai.gpt-4.1
    temperature: 0
 ```
 changes of Model exigem:
 - Validation of Cost;
 - evaluator;
 - Validation of quality;
 - Validation of Latency;
 - Update of release notes.
 # 11. Governance of MCP
 each tool must ter owner, SLA, timeout and Contract.
 ```yaml
 tool:
  name: consultar_fatura
  version: 1.0.0
  owner: billing_platform
  sla: p95_2s
  timeout_seconds: 30
  idempotent: true
 ```
 Tools mutáveis exigem Policy of confirmação.
 # 12. Governance of datasets
 Datasets are ativos of quality.
 ```yaml
 dataset:
  name: telecom_contas_regression
  version: 1.0.0
  owner: billing_team
 ```
 Datasets must contain:
 - Input;
 - BusinessContext;
 - rota expected;
 - tools esperadas;
 - criteria minimum;
 - casos negativos;
 - casos of Security.
 # 13. Process of approval
 ```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 of Tests;
 - relatório evaluator;
 - relatório certification;
 - trace Langfuse;
 - logs and Metrics;
 - checklist of Security;
 - release notes;
 - Version of artifacts.
 # 15. Common errors
 | Error | Impact | Correction |
 | --- | --- | --- |
 | Prompt without owner | Dificulta maintenance and approval. | Definir owner no metadata. |
 | Tool without SLA | Operations without expectativa of Response. | Registrar SLA em tools.yaml. |
 | Dataset ausente | without regressão objetiva. | create dataset minimum. |
 | Guardrail hardcoded | Governance outside of the YAML. | Mover for config. |
 | Model definido no Agent | Quebra Governance of modelos. | use AI Gateway profiles. |
 # 16. Acceptance criteria
 - [ ] each Agent possui owner funcional and técnico.
 - [ ] Prompts are versionados.
 - [ ] Tools MCP possuem owner, SLA and Version.
 - [ ] Guardrails possuem owner and modo.
 - [ ] Judges possuem threshold and Version.
 - [ ] Datasets are versionados.
 - [ ] Evaluator roda por Agent.
 - [ ] Certification aprova before Production.
 - [ ] Release possui evidências.
 - [ ] Exceptions are documentadas.
--- a/specs/en/SPEC-012-Canonical-Contracts.md
+++ b/specs/en/SPEC-012-Canonical-Contracts.md
@@ -0,0 +1,312 @@
 # SPEC-012 — Canonical Contracts
 ## Agent Platform OCI
 Version: 1.0.0
 ---
 ## Reading guide
 each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
 The document structure is:
 1. Concept.
 2. Problem addressed.
 3. When to use.
 4. When not to use.
 5. Architecture.
 6. Implementation.
 7. Examples.
 8. Common errors.
 9. Acceptance criteria.
 ---
 # 1. Concept
 contracts canônicos are structures padronizadas usadas for desacoplar canais, gateways, runtime, Agents, tools, LLMs, evaluator and Observability.
 The platform Uses contracts to ensure that Components independentes possam evoluir without quebrar uns aos outros.
 # 2. Problem addressed
 without contracts:
 - each canal envia payload diferente;
 - Agents passam a conhecer WhatsApp, Voice, Teams or CRM;
 - MCP tools recebem parâmetros inconsistentes;
 - LLM calls ficam acopladas ao provider;
 - evaluator No consegue comparar responses;
 - Observability fica fragmentada.
 with contracts:
 ```text
 Canal → GatewayRequest → Runtime → BusinessContext → ToolInvocation → ToolResult
 ```
 # 3. Catalog of contracts
 | Contract | Uso |
 | --- | --- |
 | GatewayRequest | Input canônica of the plataforma. |
 | ChannelResponse | Response canônica ao canal. |
 | BusinessContext | Identity canônica of negócio. |
 | AgentState | State Internal of the runtime. |
 | Session | Session técnica/conversational. |
 | Checkpoint | Persistence of State LangGraph. |
 | ToolInvocation | Call canônica of tool MCP. |
 | ToolResult | Response canônica of tool MCP. |
 | LLMRequest | Call canônica ao AI Gateway. |
 | LLMResponse | Response canônica of the AI Gateway. |
 | EvaluationRun | Execution of the evaluator. |
 | EvaluationResult | result of Evaluation. |
 | CertificationResult | result of Certification. |
 | EventEnvelope | Envelope of Events IC/NOC/GRL. |
 # 4. GatewayRequest
 ## 4.1. Uso
 Used por Channel Gateway and Agent Gateway for enviar Messages 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. fields required
 - `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 Identity of negócio without acoplar The platform ao formato of each 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 for 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. Rules of evolução
 - fields new must be optional;
 - fields required No Can be removidos inside of the mesma major;
 - change semântica exige new Version;
 - contracts are versionados independentemente.
 # 15. Common errors
 | Error | Impact | Correction |
 | --- | --- | --- |
 | Payload bruto in the runtime | Acopla canais ao core. | use GatewayRequest. |
 | Tool recebendo BusinessContext bruto without mapping | Quebra Contract of the tool. | use mcp_parameter_mapping.yaml. |
 | LLM direto no Agent | Quebra AI Gateway. | use LLMRequest/profile. |
 | fields without Version | Dificulta migração. | Declarar contract_version. |
 # 16. Acceptance criteria
 - [ ] GatewayRequest documentado and versionado.
 - [ ] ChannelResponse documentado and versionado.
 - [ ] BusinessContext Used por canais and MCP.
 - [ ] ToolInvocation and ToolResult padronizados.
 - [ ] LLMRequest and LLMResponse padronizados.
 - [ ] EvaluationRun and EvaluationResult padronizados.
 - [ ] EventEnvelope Used for IC/NOC/GRL.
 - [ ] contracts possuem Rules of evolução.
--- a/specs/en/SPEC-013-Versioning-and-Compatibility-Model.md
+++ b/specs/en/SPEC-013-Versioning-and-Compatibility-Model.md
@@ -0,0 +1,175 @@
 # SPEC-013 — Versioning and Compatibility Model
 ## Agent Platform OCI
 Version: 1.0.0
 ---
 ## Reading guide
 each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
 The document structure is:
 1. Concept.
 2. Problem addressed.
 3. When to use.
 4. When not to use.
 5. Architecture.
 6. Implementation.
 7. Examples.
 8. Common errors.
 9. Acceptance criteria.
 ---
 # 1. Concept
 Versionamento Defines como The platform evolui without quebrar projetos existing. compatibility Defines quais versions of framework, runtime, gateways, contracts, templates, prompts, tools and evaluator can operar juntas.
 # 2. Problem addressed
 without Model of versionamento:
 - a change em GatewayRequest quebra canais;
 - a change em MCP tool quebra Agents;
 - a prompt alterado muda comportamento without rastreabilidade;
 - evaluator muda score without History;
 - templates ficam incompatíveis with runtime;
 - Production Uses imagem `latest` without control.
 # 3. Semantic Versioning
 Formato:
 ```text
 MAJOR.MINOR.PATCH
 ```
 Rules:
 | Parte | Significado |
 | --- | --- |
 | MAJOR | change incompatível. |
 | MINOR | new Capacity compatível. |
 | PATCH | Correction without change of Contract. |
 # 4. artifacts versionados
 | Artefato | Model |
 | --- | --- |
 | agent_framework | SemVer |
 | agent_runtime | SemVer alinhado ao framework |
 | agent_gateway | SemVer + Docker tag |
 | channel_gateway | SemVer + Docker tag |
 | ai_gateway | SemVer + Docker tag |
 | mcp_gateway | SemVer + Docker tag |
 | templates | Version of the plataforma |
 | contracts | contract-name-vN |
 | prompts | SemVer |
 | datasets | SemVer |
 | guardrails | SemVer por código |
 | judges | SemVer por judge |
 | mcp_tools | SemVer por tool |
 | evaluator | SemVer |
 | certification_suite | SemVer + ruleset version |
 # 5. Contract versioning
 Examples:
 ```text
 gateway-request-v1
 business-context-v1
 tool-invocation-v1
 llm-request-v1
 ```
 allowed na mesma Version major:
 - adicionar fields optional;
 - adicionar metadata;
 - adicionar enum documentado.
 No allowed:
 - remover field Required;
 - mudar tipo;
 - mudar significado;
 - alterar regra obrigatória.
 # 6. Compatibility Matrix
 ```yaml
 compatibility:
  - framework: "1.4.x"
    runtime: "1.4.x"
    agent_gateway: "1.4.x"
    supported: true
  - framework: "1.4.x"
    runtime: "2.0.x"
    supported: false
 ```
 # 7. Policy of depreciação
 Ciclo:
 ```text
 Active → Deprecated → Retired
 ```
 Período recommended:
 ```text
 12 meses
 ```
 # 8. Policy of migração
 changes major exigem:
 - migration guide;
 - compatibility matrix;
 - rollback strategy;
 - certification;
 - evaluator;
 - release notes.
 # 9. Estratégia of rollback
 Rollback must considerar:
 - imagem Docker;
 - Version of the pacote;
 - Version of the YAMLs;
 - Version of the Contract;
 - migration of banco;
 - dataset;
 - prompts.
 # 10. Common errors
 | Error | Impact | Correction |
 | --- | --- | --- |
 | use latest em Production | Deploy No reprodutível. | use tag explícita. |
 | Mudar prompt without Version | without rastreabilidade. | Versionar prompt. |
 | Adicionar field Required em Contract v1 | Quebra clientes. | create v2. |
 | Atualizar evaluator without baseline | Scores No comparáveis. | Registrar Version and metodologia. |
 # 11. Acceptance criteria
 - [ ] all os Components têm Version.
 - [ ] contracts têm Version independente.
 - [ ] Matriz of compatibility publicada.
 - [ ] Release notes publicadas.
 - [ ] Migrações major possuem guide.
 - [ ] Rollback definido.
 - [ ] Prompts and datasets versionados.
 - [ ] Evaluator and certification registram Version.
--- a/specs/en/SPEC-014-Templates-and-Agent-Creation-Model.md
+++ b/specs/en/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
 ---
 ## Reading guide
 each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
 The document structure is:
 1. Concept.
 2. Problem addressed.
 3. When to use.
 4. When not to use.
 5. Architecture.
 6. Implementation.
 7. Examples.
 8. Common errors.
 9. Acceptance criteria.
 ---
 # 1. Concept
 Templates are scaffolds oficiais for create Agents, MCP servers and backends compatíveis with a Agent Platform OCI.
 Eles aceleram o início of a projeto, mas No substituem o framework. O template contains a structure mínima of aplicação and os pontos of extensão esperados.
 # 2. Problem addressed
 without template:
 - each squad cria structure diferente;
 - imports and configs variam;
 - MCP mapping is esquecido;
 - datasets No are criados;
 - guardrails and judges ficam ausentes;
 - deploy No segue Standard;
 - onboarding demora.
 # 3. Templates oficiais
 | Template | Uso |
 | --- | --- |
 | backend | Creation of Agents with runtime. |
 | agent_template_backend_day_zero | Bootstrap acelerado with Examples. |
 | mcp_server | Creation of MCP server. |
 | channel_adapter | Adapter of canal when aplicável. |
 # 4. structure Standard of Agent
 ```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 that fica in the framework
 - LangGraph runtime;
 - Session;
 - Memory;
 - checkpoint;
 - guardrails genéricos;
 - judges genéricos;
 - MCP client/router;
 - RAG genérico;
 - telemetry;
 - providers;
 - event bus.
 # 6. O that fica no Agent
 - prompts;
 - Rules of negócio;
 - intents;
 - tools específicas;
 - datasets;
 - Tests;
 - guardrails of Domain;
 - judges of Domain.
 # 7. step a step for create Agent of the zero
 ## step 1 — Copiar template
 ```bash
 cp -R templates/agent_template_backend financeiro_agent
 cd financeiro_agent
 ```
 ## step 2 — Definir Scope
 ```text
 Agente: financeiro_agent
 Objetivo: responder dúvidas sobre faturas, pagamentos e cobranças.
 Fora de escopo: vendas, cancelamento e suporte técnico.
 ```
 ## step 3 — Registrar Agent
 ```yaml
 agents:
  financeiro_agent:
    enabled: true
    description: "Agente financeiro"
    rag_namespace: financeiro
    allowed_tools:
      - consultar_fatura
      - consultar_pagamentos
 ```
 ## step 4 — Configurar rotas
 ```yaml
 intents:
  financeiro_consulta_fatura:
    route: financeiro_agent
    keywords:
      - fatura
      - boleto
      - cobrança
    mcp_tools:
      - consultar_fatura
 ```
 ## step 5 — Configurar tools
 ```yaml
 tools:
  consultar_fatura:
    server: telecom
    enabled: true
    idempotent: true
    cache_ttl_seconds: 300
 ```
 ## step 6 — Mapear BusinessContext
 ```yaml
 tools:
  consultar_fatura:
    map:
      customer_key: msisdn
      contract_key: invoice_id
      session_key: session_id
 ```
 ## step 7 — create 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.
 ```
 ## step 8 — implement Agent
 ```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}
 ```
 ## step 9 — create 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
 ```
 ## step 10 — Testar
 ```bash
 pytest
 af-evaluator run --agent-id financeiro_agent
 af-certification run --agent-id financeiro_agent
 ```
 # 8. Common errors
 | Error | Impact | Correction |
 | --- | --- | --- |
 | Alterar o core for regra of Domain | Dificulta reuso. | create Agent/config. |
 | Esquecer dataset | without regressão. | create dataset minimum. |
 | Tool without mapping | Argumentos ausentes. | Configurar mcp_parameter_mapping.yaml. |
 | Prompt hardcoded | without Governance. | use prompt_policy/prompts. |
 # 9. Acceptance criteria
 - [ ] Template Used como base.
 - [ ] Agent registrado.
 - [ ] Rotas configuradas.
 - [ ] Tools configuradas.
 - [ ] MCP mapping configured.
 - [ ] Prompt criado.
 - [ ] Dataset criado.
 - [ ] Tests executados.
 - [ ] Evaluator executado.
 - [ ] Certification aprovada.
--- a/specs/en/SPEC-015-Adoption-and-Eligibility-Criteria.md
+++ b/specs/en/SPEC-015-Adoption-and-Eligibility-Criteria.md
@@ -0,0 +1,168 @@
 # SPEC-015 — Adoption and Eligibility Criteria
 ## Agent Platform OCI
 Version: 1.0.0
 ---
 ## Reading guide
 each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
 The document structure is:
 1. Concept.
 2. Problem addressed.
 3. When to use.
 4. When not to use.
 5. Architecture.
 6. Implementation.
 7. Examples.
 8. Common errors.
 9. Acceptance criteria.
 ---
 # 1. Concept
 criteria of adoção definem when a projeto must use a Agent Platform OCI and quais Requirements minimum precisa atender for entrar em Development, homologação and Production.
 # 2. Problem addressed
 without criteria claros:
 - qualquer caso simples vira Agent;
 - projetos without owner entram on the platform;
 - canais entram without Contract;
 - Agents entram without dataset;
 - Production ocorre without evaluator;
 - Operations fica without dashboard/Alert.
 # 3. Casos indicados
 | Caso | Example |
 | --- | --- |
 | Agents conversational | Atendimento, suporte, backoffice. |
 | Multiagentes | Handoff between domínios. |
 | Agents with tools | Consulta/ação em sistemas. |
 | Agents with RAG | Uso of documentos and Policies. |
 | Ambientes regulados | Necessidade of Governance and auditoria. |
 | Canais corporativos | Web, WhatsApp, Voice, URA, CRM. |
 # 4. Casos No indicados
 | Caso | Motivo |
 | --- | --- |
 | CRUD simples | API REST without IA. |
 | ETL batch | Pipeline of Data. |
 | Job agendado simples | without interação. |
 | service utilitário | Validation/formatação simples. |
 | integration without Decision | Proxy API without raciocínio. |
 # 5. criteria of Input of negócio
 before iniciar:
 - business owner;
 - technical owner;
 - objective;
 - Scope;
 - outside of Scope;
 - canais;
 - sistemas;
 - documentos;
 - criteria of success;
 - Risks.
 # 6. criteria of Architecture
 required:
 - GatewayRequest;
 - ChannelResponse;
 - BusinessContext;
 - health/readiness;
 - logs;
 - traces;
 - dataset;
 - evaluator;
 - certification.
 # 7. criteria of Security
 required:
 - Authentication;
 - Authorization;
 - secrets external;
 - máscara of PII;
 - auditoria;
 - Review of Risk.
 # 8. criteria of quality
 required:
 - Tests unitários;
 - Tests of integration;
 - dataset;
 - evaluator;
 - thresholds;
 - certification.
 # 9. criteria of Operations
 required:
 - Metrics;
 - dashboards;
 - Alerts;
 - runbook;
 - rollback;
 - SLO.
 # 10. Process of exceção
 Exceptions permitidas:
 - without RAG;
 - without MCP;
 - without Memory;
 - without handoff;
 - without canal External.
 Toda exceção Must record:
 ```yaml
 exception:
  reason: "Agente não usa documentos"
  approved_by: architecture
  expires_at: 2026-12-31
 ```
 # 11. Checklist of adoção
 - [ ] Business owner definido.
 - [ ] Technical owner definido.
 - [ ] Scope definido.
 - [ ] Casos outside of Scope definidos.
 - [ ] GatewayRequest definido.
 - [ ] BusinessContext definido.
 - [ ] Security definida.
 - [ ] Dataset criado.
 - [ ] Evaluator configured.
 - [ ] Certification planejada.
 - [ ] Observability planejada.
 # 12. Acceptance criteria
 - [ ] Projeto elegível for plataforma.
 - [ ] Requirements minimum atendidos.
 - [ ] Exceptions documentadas.
 - [ ] Plano of homologação definido.
 - [ ] criteria of Production definidos.
--- a/specs/en/SPEC-016-Agent-Development-Lifecycle.md
+++ b/specs/en/SPEC-016-Agent-Development-Lifecycle.md
@@ -0,0 +1,227 @@
 # SPEC-016 — Agent Development Lifecycle
 ## Agent Platform OCI
 Version: 1.0.0
 ---
 ## Reading guide
 each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
 The document structure is:
 1. Concept.
 2. Problem addressed.
 3. When to use.
 4. When not to use.
 5. Architecture.
 6. Implementation.
 7. Examples.
 8. Common errors.
 9. Acceptance criteria.
 ---
 # 1. Concept
 O ciclo of vida of Development of Agents Defines as stages desde a discovery of the caso of uso até a Operations em Production.
 Ele organiza trabalho of produto, Architecture, engenharia, Security, Evaluation and Operations.
 # 2. Flow of the ciclo of 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. stage 1 — Discovery
 objective:
 - entender problema;
 - identificar users;
 - mapear canais;
 - mapear sistemas;
 - mapear documentos;
 - mapear Risks.
 Output:
 ```yaml
 discovery:
  business_problem: ""
  users: []
  channels: []
  systems: []
  documents: []
  risks: []
 ```
 # 4. stage 2 — Scope Definition
 Definir:
 - o that o Agent does;
 - o that No does;
 - intenções;
 - actions permitidas;
 - Limits;
 - criteria of success.
 # 5. stage 3 — Agent Design
 Desenhar:
 - agent_id;
 - rotas;
 - intents;
 - BusinessContext;
 - tools;
 - RAG namespaces;
 - Memory;
 - handoff.
 # 6. stage 4 — Prompt Design
 create:
 - system prompt;
 - prompt policy;
 - instruções of Domain;
 - Examples;
 - restrições;
 - formato of Response.
 # 7. stage 5 — MCP Design
 Definir:
 - tools;
 - parâmetros;
 - owner;
 - SLA;
 - timeout;
 - retry;
 - cache;
 - Operations mutável or idempotente.
 # 8. stage 6 — RAG Design
 Definir:
 - documentos;
 - namespace;
 - ingestão;
 - chunking;
 - embeddings;
 - Update;
 - criteria of relevância.
 # 9. stage 7 — Implementation
 implement:
 - classe of the Agent;
 - configs;
 - prompts;
 - datasets;
 - tests;
 - Observability específica.
 # 10. stage 8 — Testing
 Tests minimum:
 - unit;
 - integration;
 - contract;
 - MCP;
 - RAG;
 - guardrails;
 - judges;
 - runtime;
 - channel.
 # 11. stage 9 — Evaluation
 Executar:
 ```bash
 af-evaluator run --agent-id <agent_id> --dataset <dataset>
 ```
 Assess:
 - quality;
 - groundedness;
 - safety;
 - tool correctness;
 - route accuracy.
 # 12. stage 10 — Certification
 Executar:
 ```bash
 af-certification run --agent-id <agent_id>
 ```
 # 13. stage 11 — Homologation
 validate with:
 - negócio;
 - Architecture;
 - Security;
 - Operations;
 - integration.
 # 14. stage 12 — Production
 Requirements:
 - deploy aprovado;
 - Alerts ativos;
 - dashboards ativos;
 - rollback validado;
 - runbook disponível.
 # 15. Common errors
 | Error | Impact | Correction |
 | --- | --- | --- |
 | Começar by the código | Scope mal definido. | Iniciar por discovery/scope. |
 | create tool before of the intent | Tool without Context. | Definir Flow primeiro. |
 | Dataset after of the Production | without regressão. | create dataset before of the homologação. |
 | Prompt without criteria | Response inconsistente. | Definir prompt policy. |
 # 16. Acceptance criteria
 - [ ] Discovery concluído.
 - [ ] Scope aprovado.
 - [ ] Agent design documentado.
 - [ ] Prompts criados.
 - [ ] MCP design aprovado.
 - [ ] RAG design aprovado when aplicável.
 - [ ] Implementation concluída.
 - [ ] Tests executados.
 - [ ] Evaluator aprovado.
 - [ ] Certification aprovada.
 - [ ] Homologação concluída.
 - [ ] Production monitorada.
--- a/specs/en/SPEC-017-Release-Management-and-CICD.md
+++ b/specs/en/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
 ---
 ## Reading guide
 each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
 The document structure is:
 1. Concept.
 2. Problem addressed.
 3. When to use.
 4. When not to use.
 5. Architecture.
 6. Implementation.
 7. Examples.
 8. Common errors.
 9. Acceptance criteria.
 ---
 # 1. Concept
 Release management Defines como changes entram on the platform, are testadas, empacotadas, publicadas, promovidas and auditadas.
 CI/CD automatiza Validations and reduz Risk operacional.
 # 2. Pipeline Standard
 ```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 | Validation inicial of structure. |
 | lint | Estilo and erros simples. |
 | type_check | Tipos and contracts Python. |
 | unit_test | Tests unitários. |
 | integration_test | Integrações locais. |
 | contract_test | contracts JSON/YAML/API. |
 | security_scan | Dependências, secrets and imagens. |
 | build_package | Wheel/package. |
 | build_image | Imagem Docker. |
 | publish | Registry/artifacts. |
 | deploy_dev | Ambiente dev. |
 | smoke_test | Health and Calls básicas. |
 | certification | Certification Suite. |
 | deploy_hml | Homologação. |
 | deploy_prod | Production. |
 # 4. artifacts of release
 - imagem Docker;
 - pacote Python;
 - release notes;
 - matriz of compatibility;
 - migration guide when necessário;
 - evaluator report;
 - certification report;
 - SBOM when aplicável;
 - evidência of scan;
 - changelog.
 # 5. Example of pipeline
 ```yaml
 stages:
  - lint
  - test
  - contract
  - security
  - build
  - publish
  - deploy
  - certification
 ```
 # 6. Gates
 | Gate | when applies |
 | --- | --- |
 | Architecture Gate | changes estruturais, contracts, runtime, gateways. |
 | Security Gate | Segredos, Identity, Data sensíveis, MCP External. |
 | Quality Gate | Tests, evaluator, certification. |
 | Operations Gate | Dashboards, Alerts, runbook, rollback. |
 # 7. Estratégia of rollback
 Rollback must restaurar:
 - imagem previous;
 - Configuration previous;
 - Contract previous;
 - prompt previous;
 - dataset previous when necessário;
 - migration of banco when aplicável.
 # 8. Common errors
 | Error | Impact | Correction |
 | --- | --- | --- |
 | Deploy without certification | Risk funcional. | Rodar certification no pipeline. |
 | without release notes | without rastreabilidade. | Publicar release notes. |
 | without contract tests | Quebra integration. | Adicionar Tests of Contract. |
 | without rollback | Risk operacional. | Definir estratégia of rollback. |
 # 9. Acceptance criteria
 - [ ] Pipeline executa lint, type check and Tests.
 - [ ] Contract tests executam.
 - [ ] Security scan executa.
 - [ ] Imagem Docker gerada.
 - [ ] Artifacts publicados.
 - [ ] Smoke tests executados.
 - [ ] Certification executada.
 - [ ] Release notes publicadas.
 - [ ] Rollback definido.
 - [ ] Evidências arquivadas.
--- a/specs/en/SPEC-018-Security-and-Identity-Model.md
+++ b/specs/en/SPEC-018-Security-and-Identity-Model.md
@@ -0,0 +1,152 @@
 # SPEC-018 — Security and Identity Model
 ## Agent Platform OCI
 Version: 1.0.0
 ---
 ## Reading guide
 each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
 The document structure is:
 1. Concept.
 2. Problem addressed.
 3. When to use.
 4. When not to use.
 5. Architecture.
 6. Implementation.
 7. Examples.
 8. Common errors.
 9. Acceptance criteria.
 ---
 # 1. Concept
 Security and Identity Model Defines como workloads autenticam, como Components autorizam actions, como segredos are protegidos and como Data sensíveis are tratados.
 # 2. Modelos of Authentication
 | Modo | Uso |
 | --- | --- |
 | config_file | Development local with ~/.oci/config. |
 | instance_principal | Execution em OCI Compute. |
 | workload_identity | Execution em OKE/Kubernetes. |
 | resource_principal | Recursos OCI gerenciados. |
 | api_key | Endpoints compatíveis with OpenAI when aplicável. |
 # 3. Workload Identity
 Flow:
 ```mermaid
 flowchart LR
    Pod[Pod Kubernetes] --> SA[ServiceAccount]
    SA --> WI[Workload Identity]
    WI --> IAM[OCI IAM Policy]
    IAM --> Resource[OCI Resource]
 ```
 # 4. Authorization
 Escopos:
 - Agent can chamar tool?
 - tenant can use provider?
 - canal can chamar agent_id?
 - User can executar ação?
 - tool mutável exige confirmação?
 # 5. Secrets
 Secrets No ficam no código.
 sources:
 - OCI Vault;
 - Kubernetes Secrets;
 - secret manager corporativo.
 Examples:
 ```text
 LANGFUSE_SECRET_KEY
 OCI_GENAI_API_KEY
 ADB_PASSWORD
 MCP_BACKEND_TOKEN
 ```
 # 6. Proteção of Data
 apply:
 - máscara of PII;
 - minimização of metadata;
 - sanitização of payload;
 - No logar secrets;
 - retenção controlada;
 - classificação of Data.
 # 7. Security em MCP
 MCP tools must ter:
 - Authorization por Agent;
 - allowlist;
 - timeout;
 - retry;
 - idempotência declarada;
 - confirmação for operações mutáveis.
 # 8. Security em canais
 Channel Gateway must:
 - validate assinatura;
 - validate origem;
 - deduplicar;
 - rate limit;
 - remover tokens;
 - normalizar payload;
 - rejeitar anexos inválidos.
 # 9. Auditoria
 Registrar:
 - User/canal;
 - agent_id;
 - tenant_id;
 - tool Call;
 - Model Used;
 - Decision of guardrail;
 - judge score;
 - Error;
 - trace_id.
 # 10. Common errors
 | Error | Impact | Correction |
 | --- | --- | --- |
 | Secret em .env versionado | Vazamento. | use Vault/Secrets. |
 | Tool without Authorization | Acesso indevido. | Allowed agents por tool. |
 | Payload bruto em logs | Exposição of Data. | Mascarar/minimizar. |
 | Instance main local | Timeout/Authentication invalid. | use config_file local. |
 # 11. Acceptance criteria
 - [ ] Modo of Authentication definido por ambiente.
 - [ ] Secrets external ao código.
 - [ ] MCP tools autorizadas por Agent.
 - [ ] Channel Gateway valida origem.
 - [ ] PII mascarada em logs.
 - [ ] Events auditáveis emitidos.
 - [ ] Workload Identity definido for OKE.
 - [ ] Security review executado before Production.
--- a/specs/en/SPEC-019-Evaluation-and-Certification-Framework.md
+++ b/specs/en/SPEC-019-Evaluation-and-Certification-Framework.md
@@ -0,0 +1,164 @@
 # SPEC-019 — Evaluation and Certification Framework
 ## Agent Platform OCI
 Version: 1.0.0
 ---
 ## Reading guide
 each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
 The document structure is:
 1. Concept.
 2. Problem addressed.
 3. When to use.
 4. When not to use.
 5. Architecture.
 6. Implementation.
 7. Examples.
 8. Common errors.
 9. Acceptance criteria.
 ---
 # 1. Concept
 Evaluation mede quality and comportamento. Certification valida prontidão técnica and 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. Architecture
 ```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. Metrics
 | metric | Description |
 | --- | --- |
 | quality | Clareza, completude and utilidade. |
 | groundedness | Aderência evidências MCP/RAG. |
 | safety | compliance of Security. |
 | resolution | Resolve a intent. |
 | tool_correctness | Uses tools corretas. |
 | route_accuracy | Rota/intent corretas. |
 | policy_compliance | Aderência à Policy of Domain. |
 # 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 when aplicável.
 # 9. Common errors
 | Error | Impact | Correction |
 | --- | --- | --- |
 | Dataset só with casos felizes | Baixa coverage. | include negativos and bordas. |
 | Evaluator without baseline | without comparação. | Registrar baseline. |
 | Certification without MCP real/mock | integration No validada. | create tool test. |
 | Judge without threshold | without criterion objective. | Definir threshold. |
 # 10. Acceptance criteria
 - [ ] Dataset versionado.
 - [ ] Evaluator executado.
 - [ ] Scores persistidos.
 - [ ] Certification executada.
 - [ ] Relatórios gerados.
 - [ ] Thresholds definidos.
 - [ ] Casos negativos incluídos.
 - [ ] Scores publicados when aplicável.
--- a/specs/en/SPEC-020-Operational-Readiness-and-SRE-Model.md
+++ b/specs/en/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
 ---
 ## Reading guide
 each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
 The document structure is:
 1. Concept.
 2. Problem addressed.
 3. When to use.
 4. When not to use.
 5. Architecture.
 6. Implementation.
 7. Examples.
 8. Common errors.
 9. Acceptance criteria.
 ---
 # 1. Concept
 Operational readiness defines the minimum requirements to run the Agent Platform OCI in production with reliability, observability, incident response capabilities, and recovery.
 # 2. Managed components
 - Agent Gateway;
 - Channel Gateway;
 - Agent Runtime;
 - AI Gateway;
 - MCP Gateway;
 - MCP Servers;
 - Evaluator;
 - bancos/repositórios;
 - Langfuse/OTEL;
 - Redis/Mongo/ADB when usados.
 # 3. Health and readiness
 Minimum endpoints:
 ```text
 GET /health
 GET /ready
 GET /version
 ```
 # 4. SLOs
 | Componente | Latency | Availability |
 | --- | --- | --- |
 | 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 | Execution diária |
 # 5. Metrics
 - 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
 Minimum dashboards:
 - Platform Overview;
 - Runtime;
 - Gateway;
 - AI Gateway;
 - MCP Gateway;
 - Guardrails;
 - Evaluator;
 - Cost/Usage;
 - Incidents.
 # 7. Alerts
 | Alert | Condition |
 | --- | --- |
 | HighErrorRate | 5xx above of the Limit. |
 | LatencySLOBreach | p95 above of the SLO. |
 | LLMProviderDown | Failures consecutive no provider. |
 | MCPTimeoutSpike | increase of timeout MCP. |
 | GuardrailSpike | increase abnormal of Blocks. |
 | EvaluatorFailed | Run failed. |
 # 8. Runbooks
 A runbook must contain:
 - symptom;
 - Impact;
 - queries;
 - dashboards;
 - logs;
 - actions;
 - rollback;
 - escalation.
 # 9. Incident management
 Flow:
 ```mermaid
 flowchart LR
    Detect[Detect] --> Triage[Triage]
    Triage --> Mitigate[Mitigate]
    Mitigate --> Recover[Recover]
    Recover --> Postmortem[Postmortem]
 ```
 # 10. Capacity
 Assess:
 - QPS;
 - Sessions concurrent;
 - tokens/minuto;
 - Calls MCP/minuto;
 - Latency of provider;
 - uso of Memory;
 - storage of checkpoints.
 # 11. Common errors
 | Error | Impact | Correction |
 | --- | --- | --- |
 | without readiness | traffic before of app estar ready. | implement /ready. |
 | without Alerts MCP | Failure silenciosa. | create Alerts por tool. |
 | without runbook | MTTR high. | create runbooks por incidente. |
 | without Cost LLM | without control financial. | Registrar tokens/Costs. |
 # 12. Production readiness checklist
 - [ ] Health checks ativos.
 - [ ] Readiness checks ativos.
 - [ ] Structured logs.
 - [ ] Metrics exportadas.
 - [ ] Exported traces.
 - [ ] Dashboards created.
 - [ ] Configured alerts.
 - [ ] Runbooks disponíveis.
 - [ ] Rollback validado.
 - [ ] Defined SLOs.
 - [ ] Estimated capacity.
 - [ ] Incident process definido.