diff --git a/Implementando_Basic_Auth.md b/Implementando_Basic_Auth.md
new file mode 100644
index 0000000..d6ff282
--- /dev/null
+++ b/Implementando_Basic_Auth.md
@@ -0,0 +1,987 @@
+# Implementando Basic Auth
+
+Para validar **todo o circuito com Basic Auth**, você precisa configurar três relações distintas:
+
+```text
+Cliente de teste
+   └─ Basic Auth A ─► Agent Gateway :8010
+                         └─ Basic Auth B ─► Agent Backend :8000
+                                                └─ Basic Auth C ─► MCP Gateway :8300
+```
+
+Há um detalhe importante: no pacote atual, a autenticação Basic já funciona para chamadas **de entrada**, mas os clientes internos ainda não enviam Basic Auth:
+
+* `Agent Gateway → Agent Backend` não envia credencial;
+* `Agent Backend → MCP Gateway` envia apenas Bearer Token.
+
+Portanto, para testar o circuito inteiro com Basic Auth, faça os dois pequenos ajustes de código descritos abaixo.
+
+---
+
+# 1. Preparar o ambiente
+
+Considere que o ZIP foi extraído em:
+
+```bash
+cd agent_framework_oci_authentication_v2_1
+```
+
+Crie um único ambiente virtual para facilitar o teste:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+No Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+Instale o framework e as dependências dos três componentes:
+
+```bash
+pip install -U pip
+
+pip install -e ./libs/agent_framework
+
+pip install \
+  -r ./Tuning-Performance/Authentication/agent_template_backend_authentication/requirements.txt \
+  -r ./apps/agent_gateway/requirements.txt \
+  -r ./apps/mcp_gateway/requirements.txt
+```
+
+Confirme a importação:
+
+```bash
+python -c "from agent_framework.security import install_authentication; print('framework ok')"
+```
+
+---
+
+# 2. Criar três pares de Client ID e Secret
+
+Use credenciais diferentes para cada trecho. Para teste local:
+
+| Fluxo                   | Client ID            | Secret de teste             |
+| ----------------------- | -------------------- | --------------------------- |
+| Cliente → Agent Gateway | `tia-test`           | `TiaGateway-Test-2026!`     |
+| Agent Gateway → Backend | `agent-gateway-test` | `GatewayBackend-Test-2026!` |
+| Backend → MCP Gateway   | `agent-backend-test` | `BackendMcp-Test-2026!`     |
+
+Esses valores são apenas para ambiente local. Não os reutilize em produção.
+
+## Gerar os hashes
+
+O script está em:
+
+```text
+Tuning-Performance/Authentication/
+  agent_template_backend_authentication/
+    scripts/generate_secret_hash.py
+```
+
+Execute:
+
+```bash
+python Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py \
+  --secret 'TiaGateway-Test-2026!'
+```
+
+Depois:
+
+```bash
+python Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py \
+  --secret 'GatewayBackend-Test-2026!'
+```
+
+E:
+
+```bash
+python Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py \
+  --secret 'BackendMcp-Test-2026!'
+```
+
+Você receberá três valores semelhantes a:
+
+```text
+pbkdf2_sha256:310000:<salt>:<digest>
+```
+
+Guarde-os temporariamente:
+
+```bash
+HASH_CLIENT_GATEWAY='pbkdf2_sha256:310000:...'
+HASH_GATEWAY_BACKEND='pbkdf2_sha256:310000:...'
+HASH_BACKEND_MCP='pbkdf2_sha256:310000:...'
+```
+
+O hash muda a cada execução porque o salt é aleatório. Isso é esperado.
+
+---
+
+# 3. Configurar o Agent Gateway
+
+Entre no diretório:
+
+```bash
+cd apps/agent_gateway
+```
+
+Copie o exemplo:
+
+```bash
+cp .env.example .env
+```
+
+Adicione ao final do `.env`:
+
+```env
+# Entrada: cliente/TIA -> Agent Gateway
+AGENT_GATEWAY_AUTH_ENABLED=true
+AGENT_GATEWAY_AUTH_MODE=basic
+AGENT_GATEWAY_AUTH_BASIC_CLIENT_ID=tia-test
+AGENT_GATEWAY_AUTH_BASIC_SECRET_HASH=COLE_AQUI_HASH_CLIENT_GATEWAY
+AGENT_GATEWAY_AUTH_BASIC_REALM=agent-gateway
+
+AGENT_GATEWAY_AUTH_PUBLIC_PATHS=/health,/docs,/openapi.json,/redoc
+AGENT_GATEWAY_AUTH_PUBLIC_PREFIXES=
+
+# Saída: Agent Gateway -> Agent Backend
+BACKEND_AUTH_MODE=basic
+BACKEND_AUTH_CLIENT_ID=agent-gateway-test
+BACKEND_AUTH_SECRET=GatewayBackend-Test-2026!
+```
+
+Não coloque aspas no `.env`:
+
+```env
+BACKEND_AUTH_SECRET=GatewayBackend-Test-2026!
+```
+
+O arquivo de backends já aponta o backend Contas para:
+
+```yaml
+contas:
+  url: http://localhost:8000
+```
+
+Arquivo:
+
+```text
+apps/agent_gateway/config/backends.yaml
+```
+
+Para este teste, mantenha apenas o backend `contas` ou force o backend no payload. Caso contrário, pedidos sobre ofertas e suporte podem ser roteados para portas em que nenhum backend está rodando.
+
+---
+
+# 4. Fazer o Agent Gateway enviar Basic Auth ao backend
+
+Abra:
+
+```text
+libs/agent_framework/src/agent_framework/global_supervisor/client.py
+```
+
+Substitua a classe `BackendClient` por uma versão que aceite autenticação Basic.
+
+No início do arquivo, adicione:
+
+```python
+import os
+```
+
+Altere o construtor:
+
+```python
+class BackendClient:
+    def __init__(
+        self,
+        timeout_seconds: float = 120.0,
+        basic_client_id: str | None = None,
+        basic_secret: str | None = None,
+    ):
+        self.timeout_seconds = timeout_seconds
+        self.basic_client_id = basic_client_id
+        self.basic_secret = basic_secret
+
+    def _auth(self) -> httpx.BasicAuth | None:
+        if self.basic_client_id and self.basic_secret:
+            return httpx.BasicAuth(
+                username=self.basic_client_id,
+                password=self.basic_secret,
+            )
+        return None
+```
+
+No método `call_message`, troque:
+
+```python
+resp = await client.post(url, json=payload)
+```
+
+por:
+
+```python
+resp = await client.post(
+    url,
+    json=payload,
+    auth=self._auth(),
+)
+```
+
+No método `health`, você pode manter `/health` público. Caso queira enviar autenticação também, use:
+
+```python
+resp = await client.get(url, auth=self._auth())
+```
+
+Agora abra:
+
+```text
+apps/agent_gateway/app/main.py
+```
+
+Adicione:
+
+```python
+import os
+```
+
+Troque:
+
+```python
+backend_client = BackendClient(
+    timeout_seconds=settings.BACKEND_TIMEOUT_SECONDS
+)
+```
+
+por:
+
+```python
+backend_client = BackendClient(
+    timeout_seconds=settings.BACKEND_TIMEOUT_SECONDS,
+    basic_client_id=os.getenv("BACKEND_AUTH_CLIENT_ID"),
+    basic_secret=os.getenv("BACKEND_AUTH_SECRET"),
+)
+```
+
+Isso implementa:
+
+```text
+Agent Gateway → Agent Backend
+Authorization: Basic base64(agent-gateway-test:GatewayBackend-Test-2026!)
+```
+
+---
+
+# 5. Configurar o Agent Backend autenticado
+
+Entre no diretório:
+
+```bash
+cd Tuning-Performance/Authentication/agent_template_backend_authentication
+```
+
+Copie o exemplo:
+
+```bash
+cp .env.example .env
+```
+
+Ajuste a seção de autenticação:
+
+```env
+# Entrada: Agent Gateway -> Agent Backend
+AGENT_AUTH_ENABLED=true
+AGENT_AUTH_MODE=basic
+AGENT_AUTH_BASIC_CLIENT_ID=agent-gateway-test
+AGENT_AUTH_BASIC_SECRET_HASH=COLE_AQUI_HASH_GATEWAY_BACKEND
+AGENT_AUTH_BASIC_REALM=agent-contas
+
+AGENT_AUTH_PUBLIC_PATHS=/health,/docs,/openapi.json,/redoc
+AGENT_AUTH_PUBLIC_PREFIXES=
+```
+
+Para usar o MCP Gateway:
+
+```env
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+
+# Saída: Agent Backend -> MCP Gateway
+MCP_GATEWAY_AUTH_MODE=basic
+MCP_GATEWAY_BASIC_CLIENT_ID=agent-backend-test
+MCP_GATEWAY_BASIC_SECRET=BackendMcp-Test-2026!
+```
+
+Para evitar dependências externas durante o primeiro teste, configure também:
+
+```env
+LLM_PROVIDER=mock
+ENABLE_LANGFUSE=false
+ENABLE_ANALYTICS=false
+
+SESSION_REPOSITORY_PROVIDER=memory
+MEMORY_REPOSITORY_PROVIDER=memory
+CHECKPOINT_REPOSITORY_PROVIDER=memory
+CACHE_PROVIDER=memory
+USAGE_REPOSITORY_PROVIDER=memory
+```
+
+Os nomes exatos de alguns providers podem depender do arquivo de configuração atual do framework. Caso o `.env.example` já contenha valores locais ou mock, preserve-os.
+
+---
+
+# 6. Fazer o Backend enviar Basic Auth ao MCP Gateway
+
+Abra:
+
+```text
+libs/agent_framework/src/agent_framework/gateways/mcp_gateway_client.py
+```
+
+Substitua a implementação por:
+
+```python
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+import httpx
+
+
+class MCPGatewayClient:
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        timeout_seconds: int = 60,
+        auth_mode: str | None = None,
+        basic_client_id: str | None = None,
+        basic_secret: str | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout_seconds = timeout_seconds
+        self.auth_mode = (auth_mode or "").strip().lower()
+        self.basic_client_id = basic_client_id
+        self.basic_secret = basic_secret
+
+    def _headers(self) -> dict[str, str]:
+        if (
+            self.auth_mode == "basic"
+            and self.basic_client_id
+            and self.basic_secret
+        ):
+            raw = f"{self.basic_client_id}:{self.basic_secret}".encode("utf-8")
+            encoded = base64.b64encode(raw).decode("ascii")
+            return {"Authorization": f"Basic {encoded}"}
+
+        if self.token:
+            return {"Authorization": f"Bearer {self.token}"}
+
+        return {}
+
+    async def list_tools(self) -> dict[str, Any]:
+        async with httpx.AsyncClient(
+            timeout=self.timeout_seconds
+        ) as client:
+            response = await client.get(
+                f"{self.base_url}/v1/tools",
+                headers=self._headers(),
+            )
+            response.raise_for_status()
+            return response.json()
+
+    async def invoke_tool(
+        self,
+        *,
+        tenant_id: str,
+        agent_id: str,
+        channel: str | None,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+        business_context: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "tenant_id": tenant_id,
+            "agent_id": agent_id,
+            "channel": channel,
+            "tool_name": tool_name,
+            "arguments": arguments or {},
+            "business_context": business_context or {},
+            "metadata": metadata or {},
+        }
+
+        async with httpx.AsyncClient(
+            timeout=self.timeout_seconds
+        ) as client:
+            response = await client.post(
+                f"{self.base_url}/v1/tools/{tool_name}/invoke",
+                json=payload,
+                headers=self._headers(),
+            )
+            response.raise_for_status()
+            return response.json()
+```
+
+Agora abra:
+
+```text
+libs/agent_framework/src/agent_framework/mcp/tool_router.py
+```
+
+Localize:
+
+```python
+MCPGatewayClient(
+    base_url=getattr(
+        settings,
+        "MCP_GATEWAY_URL",
+        "http://localhost:8300",
+    ),
+    token=getattr(settings, "MCP_GATEWAY_TOKEN", None),
+    timeout_seconds=getattr(
+        settings,
+        "MCP_GATEWAY_TIMEOUT_SECONDS",
+        settings.MCP_TOOL_TIMEOUT_SECONDS,
+    ),
+)
+```
+
+Altere para:
+
+```python
+MCPGatewayClient(
+    base_url=getattr(
+        settings,
+        "MCP_GATEWAY_URL",
+        "http://localhost:8300",
+    ),
+    token=getattr(settings, "MCP_GATEWAY_TOKEN", None),
+    timeout_seconds=getattr(
+        settings,
+        "MCP_GATEWAY_TIMEOUT_SECONDS",
+        settings.MCP_TOOL_TIMEOUT_SECONDS,
+    ),
+    auth_mode=getattr(
+        settings,
+        "MCP_GATEWAY_AUTH_MODE",
+        None,
+    ),
+    basic_client_id=getattr(
+        settings,
+        "MCP_GATEWAY_BASIC_CLIENT_ID",
+        None,
+    ),
+    basic_secret=getattr(
+        settings,
+        "MCP_GATEWAY_BASIC_SECRET",
+        None,
+    ),
+)
+```
+
+Adicione estes campos em:
+
+```text
+libs/agent_framework/src/agent_framework/config/settings.py
+```
+
+Próximo das configurações existentes de MCP Gateway:
+
+```python
+MCP_GATEWAY_AUTH_MODE: str | None = None
+MCP_GATEWAY_BASIC_CLIENT_ID: str | None = None
+MCP_GATEWAY_BASIC_SECRET: str | None = None
+```
+
+Há também uma factory local em:
+
+```text
+Tuning-Performance/Authentication/
+  agent_template_backend_authentication/
+    app/mcp_gateway_client_factory.py
+```
+
+Ajuste para:
+
+```python
+from __future__ import annotations
+
+import os
+
+from agent_framework.gateways import MCPGatewayClient
+
+
+def build_mcp_gateway_client() -> MCPGatewayClient | None:
+    if os.getenv("MCP_GATEWAY_ENABLED", "true").lower() != "true":
+        return None
+
+    return MCPGatewayClient(
+        base_url=os.getenv(
+            "MCP_GATEWAY_URL",
+            "http://localhost:8300",
+        ),
+        token=os.getenv("MCP_GATEWAY_TOKEN") or None,
+        timeout_seconds=int(
+            os.getenv("MCP_GATEWAY_TIMEOUT_SECONDS", "60")
+        ),
+        auth_mode=os.getenv("MCP_GATEWAY_AUTH_MODE"),
+        basic_client_id=os.getenv(
+            "MCP_GATEWAY_BASIC_CLIENT_ID"
+        ),
+        basic_secret=os.getenv(
+            "MCP_GATEWAY_BASIC_SECRET"
+        ),
+    )
+```
+
+---
+
+# 7. Configurar o MCP Gateway
+
+Entre no diretório:
+
+```bash
+cd apps/mcp_gateway
+```
+
+Crie `.env`:
+
+```bash
+cp .env.example .env
+```
+
+Adicione:
+
+```env
+# Entrada: Agent Backend -> MCP Gateway
+MCP_GATEWAY_AUTH_ENABLED=true
+MCP_GATEWAY_AUTH_MODE=basic
+MCP_GATEWAY_AUTH_BASIC_CLIENT_ID=agent-backend-test
+MCP_GATEWAY_AUTH_BASIC_SECRET_HASH=COLE_AQUI_HASH_BACKEND_MCP
+MCP_GATEWAY_AUTH_BASIC_REALM=mcp-gateway
+
+MCP_GATEWAY_AUTH_PUBLIC_PATHS=/health,/ready,/docs,/openapi.json,/redoc
+MCP_GATEWAY_AUTH_PUBLIC_PREFIXES=
+
+MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+```
+
+## Desabilitar o mecanismo Bearer legado
+
+O MCP Gateway ainda possui um segundo mecanismo antigo, configurado dentro de:
+
+```text
+apps/mcp_gateway/config/mcp_gateway.yaml
+```
+
+Localize a seção:
+
+```yaml
+auth:
+  enabled: true
+```
+
+Altere para:
+
+```yaml
+auth:
+  enabled: false
+```
+
+Isso é necessário porque o novo middleware já faz a autenticação Basic. Caso o `auth_check()` legado continue habilitado, a requisição passará pelo Basic e depois será rejeitada por não possuir Bearer Token.
+
+---
+
+# 8. Subir os componentes
+
+Use quatro terminais.
+
+## Terminal 1 — MCP Servers
+
+O MCP Gateway precisa ter pelo menos um servidor MCP disponível para demonstrar uma chamada real.
+
+Na raiz do projeto:
+
+```bash
+source .venv/bin/activate
+```
+
+Suba o servidor telecom:
+
+```bash
+uvicorn mcp.servers.telecom_mcp_server.main:app \
+  --host 0.0.0.0 \
+  --port 8100 \
+  --reload
+```
+
+Em outro terminal, caso queira também o retail:
+
+```bash
+uvicorn mcp.servers.retail_mcp_server.main:app \
+  --host 0.0.0.0 \
+  --port 8200 \
+  --reload
+```
+
+Confira as URLs configuradas em:
+
+```text
+apps/mcp_gateway/config/mcp_gateway.yaml
+```
+
+Para execução local, devem apontar para:
+
+```yaml
+url: http://localhost:8100
+```
+
+e:
+
+```yaml
+url: http://localhost:8200
+```
+
+---
+
+## Terminal 2 — MCP Gateway
+
+```bash
+cd apps/mcp_gateway
+source ../../.venv/bin/activate
+```
+
+Suba usando `--env-file`. Isso é importante porque o middleware lê variáveis com `os.getenv()`:
+
+```bash
+uvicorn app.main:app \
+  --host 0.0.0.0 \
+  --port 8300 \
+  --reload \
+  --env-file .env
+```
+
+Teste a saúde pública:
+
+```bash
+curl http://localhost:8300/health
+```
+
+Teste um endpoint protegido sem credencial:
+
+```bash
+curl -i http://localhost:8300/v1/tools
+```
+
+Esperado:
+
+```text
+HTTP/1.1 401 Unauthorized
+```
+
+Teste com Basic Auth:
+
+```bash
+curl -i \
+  -u 'agent-backend-test:BackendMcp-Test-2026!' \
+  http://localhost:8300/v1/tools
+```
+
+Esperado:
+
+```text
+HTTP/1.1 200 OK
+```
+
+---
+
+## Terminal 3 — Agent Backend
+
+```bash
+cd Tuning-Performance/Authentication/agent_template_backend_authentication
+source ../../../.venv/bin/activate
+```
+
+Suba:
+
+```bash
+uvicorn app.main:app \
+  --host 0.0.0.0 \
+  --port 8000 \
+  --reload \
+  --env-file .env
+```
+
+Teste saúde:
+
+```bash
+curl http://localhost:8000/health
+```
+
+Teste endpoint protegido sem credencial:
+
+```bash
+curl -i http://localhost:8000/agents
+```
+
+Esperado:
+
+```text
+HTTP/1.1 401 Unauthorized
+```
+
+Teste com a credencial usada pelo Agent Gateway:
+
+```bash
+curl -i \
+  -u 'agent-gateway-test:GatewayBackend-Test-2026!' \
+  http://localhost:8000/agents
+```
+
+Esperado:
+
+```text
+HTTP/1.1 200 OK
+```
+
+Teste mensagem diretamente:
+
+```bash
+curl -X POST http://localhost:8000/gateway/message \
+  -u 'agent-gateway-test:GatewayBackend-Test-2026!' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channel": "web",
+    "agent_id": "telecom_contas",
+    "tenant_id": "default",
+    "payload": {
+      "text": "Quero consultar minha fatura",
+      "session_id": "teste-backend-001",
+      "user_id": "user-001",
+      "customer_id": "12345",
+      "message_id": "msg-001"
+    }
+  }'
+```
+
+---
+
+## Terminal 4 — Agent Gateway
+
+```bash
+cd apps/agent_gateway
+source ../../.venv/bin/activate
+```
+
+Suba:
+
+```bash
+uvicorn app.main:app \
+  --host 0.0.0.0 \
+  --port 8010 \
+  --reload \
+  --env-file .env
+```
+
+Teste saúde:
+
+```bash
+curl http://localhost:8010/health
+```
+
+Teste endpoint protegido sem credencial:
+
+```bash
+curl -i http://localhost:8010/backends
+```
+
+Esperado:
+
+```text
+HTTP/1.1 401 Unauthorized
+```
+
+Teste com a credencial externa:
+
+```bash
+curl -i \
+  -u 'tia-test:TiaGateway-Test-2026!' \
+  http://localhost:8010/backends
+```
+
+Esperado:
+
+```text
+HTTP/1.1 200 OK
+```
+
+---
+
+# 9. Validar o circuito completo
+
+Force o backend `contas` para evitar que o roteador selecione um backend não iniciado:
+
+```bash
+curl -X POST http://localhost:8010/gateway/message \
+  -u 'tia-test:TiaGateway-Test-2026!' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channel": "web",
+    "backend_id": "contas",
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "session_id": "circuito-basic-001",
+    "payload": {
+      "text": "Quero consultar minha fatura",
+      "session_id": "circuito-basic-001",
+      "user_id": "user-001",
+      "customer_id": "12345",
+      "message_id": "msg-circuito-001"
+    }
+  }'
+```
+
+O circuito esperado é:
+
+```text
+curl
+  │ Basic tia-test
+  ▼
+Agent Gateway :8010
+  │ Basic agent-gateway-test
+  ▼
+Agent Backend :8000
+  │ Basic agent-backend-test
+  ▼
+MCP Gateway :8300
+  ▼
+MCP Server :8100 ou :8200
+```
+
+---
+
+# 10. Como comprovar cada autenticação
+
+Faça testes negativos em cada trecho.
+
+## Secret externo incorreto
+
+```bash
+curl -i \
+  -u 'tia-test:senha-errada' \
+  http://localhost:8010/backends
+```
+
+Resultado esperado:
+
+```text
+401 Unauthorized
+```
+
+## Secret do gateway para backend incorreto
+
+Altere temporariamente no `apps/agent_gateway/.env`:
+
+```env
+BACKEND_AUTH_SECRET=senha-errada
+```
+
+Reinicie o Agent Gateway e envie uma mensagem.
+
+O gateway deverá retornar erro de backend, normalmente:
+
+```text
+502 Bad Gateway
+```
+
+O erro interno será originado por um:
+
+```text
+401 Unauthorized
+```
+
+do Agent Backend.
+
+## Secret do backend para MCP incorreto
+
+Altere temporariamente:
+
+```env
+MCP_GATEWAY_BASIC_SECRET=senha-errada
+```
+
+Reinicie o backend e execute uma frase que acione uma ferramenta MCP.
+
+O backend deverá registrar falha na chamada ao MCP Gateway com:
+
+```text
+401 Unauthorized
+```
+
+---
+
+# 11. Verificação rápida de portas
+
+No Linux ou WSL:
+
+```bash
+ss -lntp | grep -E ':8000|:8010|:8100|:8200|:8300'
+```
+
+No Windows PowerShell:
+
+```powershell
+Get-NetTCPConnection -State Listen |
+  Where-Object LocalPort -in 8000,8010,8100,8200,8300 |
+  Sort-Object LocalPort
+```
+
+Você deverá ver:
+
+```text
+8000  Agent Backend
+8010  Agent Gateway
+8100  Telecom MCP Server
+8200  Retail MCP Server
+8300  MCP Gateway
+```
+
+## Observação importante
+
+O segredo original precisa existir no componente cliente:
+
+```text
+TIA ou curl:
+  TiaGateway-Test-2026!
+
+Agent Gateway:
+  GatewayBackend-Test-2026!
+
+Agent Backend:
+  BackendMcp-Test-2026!
+```
+
+Os componentes servidores armazenam apenas os hashes:
+
+```text
+Agent Gateway:
+  hash de TiaGateway-Test-2026!
+
+Agent Backend:
+  hash de GatewayBackend-Test-2026!
+
+MCP Gateway:
+  hash de BackendMcp-Test-2026!
+```
+
+Em produção, os segredos originais e hashes devem vir de Vault ou Kubernetes Secret, não de arquivos `.env`.
diff --git a/Tuning-Performance/Authentication/DISCLAIMER.md b/Tuning-Performance/Authentication/DISCLAIMER.md
new file mode 100644
index 0000000..2c815c5
--- /dev/null
+++ b/Tuning-Performance/Authentication/DISCLAIMER.md
@@ -0,0 +1,24 @@
+# Disclaimer — template de autenticação
+
+Este conteúdo é um **template de referência técnica** criado para demonstrar como integrar mecanismos genéricos de autenticação ao Agent Framework OCI, ao Agent Gateway, ao MCP Gateway e a aplicações FastAPI independentes.
+
+O código, os arquivos YAML, as variáveis de ambiente, os providers, as políticas por rota e os exemplos de deployment **não constituem uma implementação final ou automaticamente adequada para produção**. Cada projeto deve lapidar e adaptar a solução conforme sua arquitetura, seus fluxos de confiança e suas exigências de segurança.
+
+Antes de usar em homologação ou produção, é responsabilidade da equipe do projeto avaliar e implementar, conforme aplicável:
+
+- integração com o provedor corporativo de identidade;
+- definição de autenticação e autorização por sistema, rota, método, tenant, role e scope;
+- armazenamento, distribuição e rotação de credenciais e chaves;
+- TLS ou mTLS e proteção das comunicações internas e externas;
+- bloqueio de acessos que contornem gateways ou proxies de confiança;
+- validação de issuer, audience, algoritmo, expiração e revogação de tokens;
+- proteção contra replay, brute force, credential stuffing e abuso de endpoints;
+- rate limiting, timeout, circuit breaker e controles de disponibilidade;
+- mascaramento de dados sensíveis em logs, traces e mensagens de erro;
+- auditoria, observabilidade, alertas e resposta a incidentes;
+- requisitos legais, regulatórios e políticas corporativas;
+- threat modeling, security review, testes de integração, testes de carga e testes de segurança.
+
+Os exemplos de Basic Authentication, API Key, Bearer estático, JWT, OAuth2 Introspection e Trusted Proxy devem ser entendidos como pontos de extensão. A seleção e a configuração finais dependem do cliente, da infraestrutura e do modelo de risco.
+
+A promoção para produção deve ocorrer somente após aprovação formal das equipes responsáveis por arquitetura, segurança, infraestrutura e operação.
diff --git a/Tuning-Performance/Authentication/IMPLEMENTACAO.md b/Tuning-Performance/Authentication/IMPLEMENTACAO.md
new file mode 100644
index 0000000..f40f46d
--- /dev/null
+++ b/Tuning-Performance/Authentication/IMPLEMENTACAO.md
@@ -0,0 +1,29 @@
+# Implementação técnica
+
+> [!IMPORTANT]
+> **Template de referência — requer adequação antes do uso produtivo.**
+> Esta implementação demonstra pontos de extensão, providers, middleware e exemplos de configuração para autenticação. Ela não deve ser considerada uma solução pronta para produção nem substitui o desenho de segurança do projeto. Antes da implantação, a equipe responsável deve revisar, testar e adaptar o código às políticas corporativas, ao modelo de identidade, à topologia de rede, à gestão e rotação de segredos, aos requisitos regulatórios, à observabilidade, à alta disponibilidade e ao processo de resposta a incidentes do ambiente do cliente. Recomenda-se executar security review, threat modeling, testes de integração e testes de segurança antes da homologação e da produção.
+## Biblioteca
+
+`libs/agent_framework/src/agent_framework/security` contém:
+
+- contratos e resultados de autenticação;
+- Basic, API Key, Bearer estático, JWT, OAuth2 Introspection e Trusted Proxy;
+- provider `none` para rotas públicas;
+- provider `deny` para default seguro;
+- middleware de provider único;
+- middleware de políticas por rota;
+- factory por ambiente ou mapping;
+- instalador reutilizável para qualquer app FastAPI.
+
+## Integrações
+
+- `apps/agent_gateway/app/main.py`: `AGENT_GATEWAY_AUTH_*`
+- `apps/mcp_gateway/app/main.py`: `MCP_GATEWAY_AUTH_*`
+- `Tuning-Performance/Authentication/agent_template_backend_authentication/app/main.py`: `AGENT_AUTH_*`
+
+Nenhuma integração é obrigatória. A instalação ocorre somente quando `*_AUTH_ENABLED=true`, quando um modo diferente de `none` é configurado ou quando existe `*_AUTH_POLICIES_FILE`.
+
+## Compatibilidade
+
+`AuthenticationMiddleware` e `create_authentication_provider()` foram mantidos para compatibilidade. O caminho recomendado para novos projetos é `install_authentication()`.
diff --git a/Tuning-Performance/Authentication/README.md b/Tuning-Performance/Authentication/README.md
new file mode 100644
index 0000000..72fdda0
--- /dev/null
+++ b/Tuning-Performance/Authentication/README.md
@@ -0,0 +1,19 @@
+# Authentication
+
+> [!IMPORTANT]
+> **Template de referência — requer adequação antes do uso produtivo.**
+> Esta implementação demonstra pontos de extensão, providers, middleware e exemplos de configuração para autenticação. Ela não deve ser considerada uma solução pronta para produção nem substitui o desenho de segurança do projeto. Antes da implantação, a equipe responsável deve revisar, testar e adaptar o código às políticas corporativas, ao modelo de identidade, à topologia de rede, à gestão e rotação de segredos, aos requisitos regulatórios, à observabilidade, à alta disponibilidade e ao processo de resposta a incidentes do ambiente do cliente. Recomenda-se executar security review, threat modeling, testes de integração e testes de segurança antes da homologação e da produção.
+Implementação de referência para autenticação transversal no Agent Framework OCI.
+
+Inclui:
+
+- providers genéricos em `libs/agent_framework/security`;
+- instalação opcional por `install_authentication()`;
+- políticas por rota, método, roles e scopes;
+- integração opcional em `apps/agent_gateway`;
+- integração opcional em `apps/mcp_gateway`;
+- backend independente autenticado em `agent_template_backend_authentication`;
+- exemplos YAML sem secrets embutidos;
+- manual completo no diretório `docs` do agente.
+
+A implementação não pressupõe o uso de gateways. Cada fronteira HTTP pode ativar autenticação com um prefixo de ambiente isolado.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/.env.example b/Tuning-Performance/Authentication/agent_template_backend_authentication/.env.example
new file mode 100644
index 0000000..310a33c
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/.env.example
@@ -0,0 +1,39 @@
+# Select: none | basic | api_key | bearer_static | jwt | oauth2_introspection | trusted_proxy
+AGENT_AUTH_MODE=basic
+
+# Public endpoints. Avoid exposing /debug in production.
+AGENT_AUTH_PUBLIC_PATHS=/health,/docs,/openapi.json,/redoc
+AGENT_AUTH_PUBLIC_PREFIXES=
+
+# HTTP Basic - TIA -> Agent example
+AGENT_AUTH_BASIC_CLIENT_ID=tia-contas
+# Supported formats: plain:value | sha256:hex | pbkdf2_sha256:iterations:salt:digest
+AGENT_AUTH_BASIC_SECRET_HASH=pbkdf2_sha256:310000:replace-salt:replace-digest
+AGENT_AUTH_BASIC_REALM=agent-contas
+
+# API Key
+# AGENT_AUTH_API_KEY_HEADER=x-api-key
+# AGENT_AUTH_API_KEY_HASH=sha256:replace-hex
+# AGENT_AUTH_API_KEY_PRINCIPAL=tia
+
+# Static Bearer token
+# AGENT_AUTH_BEARER_TOKEN_HASH=sha256:replace-hex
+# AGENT_AUTH_BEARER_PRINCIPAL=tia
+
+# JWT / OIDC access token validation. For production, prefer asymmetric algorithms.
+# AGENT_AUTH_JWT_KEY=-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----
+# AGENT_AUTH_JWT_ALGORITHMS=RS256
+# AGENT_AUTH_JWT_AUDIENCE=agent-contas
+# AGENT_AUTH_JWT_ISSUER=https://identity.example.com/
+
+# OAuth2 opaque-token introspection
+# AGENT_AUTH_OAUTH2_INTROSPECTION_URL=https://identity.example.com/oauth2/introspect
+# AGENT_AUTH_OAUTH2_CLIENT_ID=agent-contas
+# AGENT_AUTH_OAUTH2_CLIENT_SECRET=replace-from-vault
+# AGENT_AUTH_OAUTH2_TIMEOUT_SECONDS=5
+
+# Authentication delegated to API Gateway / service mesh.
+# Only trust these headers when direct access to the pod is blocked.
+# AGENT_AUTH_PROXY_SUBJECT_HEADER=x-authenticated-subject
+# AGENT_AUTH_PROXY_SHARED_SECRET_HEADER=x-internal-auth
+# AGENT_AUTH_PROXY_SHARED_SECRET_HASH=sha256:replace-hex
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/Dockerfile b/Tuning-Performance/Authentication/agent_template_backend_authentication/Dockerfile
new file mode 100644
index 0000000..273fe01
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/Dockerfile
@@ -0,0 +1,6 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY agent_framework /agent_framework
+COPY agent_template_backend /app
+RUN pip install --no-cache-dir -e /agent_framework -r requirements.txt
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/README.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/README.md
new file mode 100644
index 0000000..6198130
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/README.md
@@ -0,0 +1,4222 @@
+# Tutorial — Implementação de um Agente usando `agent_template_backend`
+
+> [!IMPORTANT]
+> **Template de referência — requer adequação antes do uso produtivo.**
+> Esta implementação demonstra pontos de extensão, providers, middleware e exemplos de configuração para autenticação. Ela não deve ser considerada uma solução pronta para produção nem substitui o desenho de segurança do projeto. Antes da implantação, a equipe responsável deve revisar, testar e adaptar o código às políticas corporativas, ao modelo de identidade, à topologia de rede, à gestão e rotação de segredos, aos requisitos regulatórios, à observabilidade, à alta disponibilidade e ao processo de resposta a incidentes do ambiente do cliente. Recomenda-se executar security review, threat modeling, testes de integração e testes de segurança antes da homologação e da produção.
+Este tutorial ensina como implementar um novo agente a partir do `agent_template_backend`, usando o framework como motor corporativo de execução.
+
+A ideia central é simples:
+
+```text
+Framework = motor reutilizável
+Agente = regra de negócio específica
+MCP Server = fronteira padronizada com sistemas externos
+Config YAML = comportamento alterável sem recompilar código
+IC/NOC/GRL = rastreabilidade de negócio, operação e governança
+```
+
+![img_1.png](img_1.png)
+
+O objetivo é que cada novo agente implemente apenas sua lógica de domínio — prompts, regras de negócio, ferramentas, schemas e nós específicos — sem recriar motores que já pertencem ao framework.
+
+---
+
+## 1. Visão geral da arquitetura
+
+O template separa o que é genérico do que é específico.
+
+```text
+agent_template_backend/
+├── app/
+│   ├── main.py                    # API FastAPI, gateway, sessão, SSE e entrada do workflow
+│   ├── state.py                   # Contrato de estado compartilhado do LangGraph
+│   ├── workflows/
+│   │   └── agent_graph.py          # Workflow corporativo com router, guardrails, agentes, judges e persistência
+│   ├── agents/
+│   │   ├── runtime.py              # Recursos comuns para agentes: MCP, RAG, cache, IC, LLM
+│   │   ├── billing_agent.py        # Exemplo de agente de faturas
+│   │   ├── product_agent.py        # Exemplo de agente de produtos
+│   │   ├── orders_agent.py         # Exemplo de agente de pedidos
+│   │   └── support_agent.py        # Exemplo de agente de suporte
+│   └── examples/                  # Exemplos de IC, NOC, GRL, MCP e observer
+├── config/
+│   ├── agents.yaml                # Registro dos agentes disponíveis
+│   ├── routing.yaml               # Intents, keywords, fallback e decisão de rota
+│   ├── tools.yaml                 # Catálogo das ferramentas disponíveis para o backend
+│   ├── mcp_servers.yaml           # Endpoints MCP locais
+│   ├── mcp_servers.docker.yaml    # Endpoints MCP em Docker Compose
+│   ├── mcp_parameter_mapping.yaml # Mapeamento entre chaves canônicas e parâmetros das tools
+│   ├── identity.yaml              # Resolução de identidade de negócio
+│   ├── guardrails.yaml            # Guardrails globais
+│   ├── judges.yaml                # Judges globais
+│   ├── prompt_policy.yaml         # Política global de prompt
+│   └── agents/<agent_id>/         # Configurações isoladas por agente
+├── data/
+│   └── agent_framework.db         # Banco local de exemplo, quando aplicável
+├── Dockerfile
+├── requirements.txt
+└── .env                           # Configuração local
+```
+
+### 1.1. O que pertence ao framework
+
+O framework deve concentrar os motores reutilizáveis:
+
+- LangGraph e montagem do workflow.
+- Checkpoint.
+- Memória.
+- Session repository.
+- Channel gateway.
+- Enterprise Router.
+- Supervisor.
+- Guardrails.
+- Output Supervisor.
+- Judges.
+- Telemetria Langfuse/OpenTelemetry.
+- Analytics IC/NOC/GRL.
+- MCP Tool Router.
+- Cache.
+- RAG genérico.
+
+### 1.2. O que pertence ao agente
+
+O agente deve concentrar apenas customizações de domínio:
+
+- Prompts específicos.
+- Regras de negócio.
+- Schemas próprios.
+- Tools específicas.
+- Clients de sistemas externos, preferencialmente encapsulados atrás de MCP.
+- Mapeamento de parâmetros.
+- Nós especializados, se houver.
+- ICs de negócio da jornada.
+
+Quando uma regra só faz sentido para um domínio, ela pertence ao agente. Quando uma capacidade deve ser usada por vários agentes, ela pertence ao framework.
+
+---
+
+## 2. Fluxo de execução do template
+
+O fluxo principal começa em `app/main.py`, no endpoint `/gateway/message`.
+
+```text
+Canal / Frontend / API
+  ↓
+POST /gateway/message
+  ↓
+ChannelGateway.normalize()
+  ↓
+IdentityResolver
+  ↓
+SessionRepository
+  ↓
+MemoryRepository
+  ↓
+AgentWorkflow.ainvoke()
+  ↓
+LangGraph
+  ↓
+Input Guardrails
+  ↓
+Enterprise Router ou Supervisor
+  ↓
+Agente especializado
+  ↓
+MCP Tool Router / RAG / Cache / LLM
+  ↓
+Output Supervisor
+  ↓
+Output Guardrails
+  ↓
+Judges
+  ↓
+Supervisor Review
+  ↓
+Persistência / Checkpoint / Memória
+  ↓
+Resposta
+```
+
+O `AgentWorkflow`, em `app/workflows/agent_graph.py`, normalmente já contém nós corporativos como:
+
+```text
+input_guardrails
+routing_decision
+billing_agent
+product_agent
+orders_agent
+support_agent
+handoff
+supervisor_agent
+output_supervisor
+output_guardrails
+judge
+supervisor_review
+persist
+```
+
+Para criar um novo agente, normalmente você altera:
+
+```text
+app/agents/<novo_agente>.py
+app/workflows/agent_graph.py
+app/state.py, se precisar de campos novos
+config/agents.yaml
+config/routing.yaml
+config/tools.yaml
+config/mcp_servers.yaml
+config/mcp_parameter_mapping.yaml
+config/identity.yaml
+config/agents/<agent_id>/prompt_policy.yaml
+config/agents/<agent_id>/guardrails.yaml
+config/agents/<agent_id>/judges.yaml
+.env
+```
+
+---
+
+## 3. Pré-requisitos
+
+### 3.1. Requisitos locais
+
+- Python 3.12 ou 3.13.
+- `pip` ou `uv`.
+- Projeto `agent_framework` disponível no mesmo workspace, caso o template use instalação local.
+- Servidores MCP, se o agente usar tools.
+- Redis, Oracle Autonomous Database, MongoDB e Langfuse são opcionais conforme configuração.
+
+Estrutura recomendada:
+
+```text
+workspace/
+├── agent_framework/
+└── agent_template_backend/
+```
+
+### 3.2. Instalação local
+
+Dentro do diretório `agent_template_backend`:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Se o `agent_framework` estiver em desenvolvimento local:
+
+```bash
+pip install -e ../agent_framework
+```
+
+Em Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+pip install -e ..\agent_framework
+```
+
+---
+
+## 4. Configuração do `.env`
+
+O `.env` define quais motores serão ativados. Ele não é apenas um arquivo de propriedades: ele muda o comportamento do agente em tempo de execução.
+
+Exemplo seguro para desenvolvimento local:
+
+```env
+APP_NAME=ai-agent-template
+APP_ENV=local
+LOG_LEVEL=INFO
+API_HOST=0.0.0.0
+API_PORT=8000
+CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
+
+LLM_PROVIDER=mock
+LLM_TEMPERATURE=0.2
+LLM_MAX_TOKENS=2048
+LLM_TIMEOUT_SECONDS=120
+
+SESSION_REPOSITORY_PROVIDER=memory
+MEMORY_REPOSITORY_PROVIDER=memory
+CHECKPOINT_REPOSITORY_PROVIDER=memory
+USAGE_REPOSITORY_PROVIDER=memory
+
+ENABLE_REDIS_CACHE=false
+REDIS_URL=redis://localhost:6379/0
+CACHE_TTL_SECONDS=300
+
+VECTOR_STORE_PROVIDER=memory
+GRAPH_STORE_PROVIDER=memory
+RAG_TOP_K=5
+EMBEDDING_PROVIDER=mock
+
+ENABLE_LANGFUSE=false
+LANGFUSE_HOST=http://localhost:3005
+ENABLE_OTEL=false
+OTEL_SERVICE_NAME=ai-agent-template
+
+ENABLE_ANALYTICS=false
+ANALYTICS_PROVIDERS=noop
+ENABLE_OCI_STREAMING=false
+OCI_STREAM_ENDPOINT=
+OCI_STREAM_OCID=
+OCI_STREAM_PARTITION_KEY=agent-events
+
+ENABLE_INPUT_GUARDRAILS=true
+ENABLE_OUTPUT_GUARDRAILS=true
+ENABLE_OUTPUT_SUPERVISOR=true
+ENABLE_JUDGES=true
+ENABLE_SUPERVISOR=true
+ENABLE_PARALLEL_GUARDRAILS=true
+GUARDRAILS_FAIL_FAST=true
+OUTPUT_SUPERVISOR_MAX_RETRIES=3
+GUARDRAILS_CONFIG_PATH=./config/guardrails.yaml
+JUDGES_CONFIG_PATH=./config/judges.yaml
+PROMPT_POLICY_PATH=./config/prompt_policy.yaml
+
+ROUTING_CONFIG_PATH=./config/routing.yaml
+ROUTING_MODE=router
+ENABLE_LLM_ROUTER=false
+
+ENABLE_MCP_TOOLS=true
+MCP_SERVERS_CONFIG_PATH=./config/mcp_servers.yaml
+TOOLS_CONFIG_PATH=./config/tools.yaml
+MCP_PARAMETER_MAPPING_PATH=./config/mcp_parameter_mapping.yaml
+MCP_TOOL_TIMEOUT_SECONDS=30
+
+IDENTITY_CONFIG_PATH=./config/identity.yaml
+```
+
+### 4.1. Como raciocinar sobre o `.env`
+
+Antes de testar um novo agente, responda:
+
+```text
+O LLM será mock ou real?
+A memória será local ou banco?
+O checkpoint precisa sobreviver a restart?
+As tools MCP serão chamadas de verdade ou simuladas?
+O roteamento será por regra/intent ou supervisor?
+Guardrails, judges e supervisor devem bloquear, revisar ou só observar?
+Langfuse/OTEL/Streaming serão usados neste ambiente?
+```
+
+Para um primeiro teste, use `LLM_PROVIDER=mock`, persistência em `memory` e MCP mock/local. Depois evolua para LLM real, banco, Langfuse e serviços reais.
+
+Para usar Oracle Autonomous Database, ajuste:
+
+```env
+SESSION_REPOSITORY_PROVIDER=autonomous
+MEMORY_REPOSITORY_PROVIDER=autonomous
+CHECKPOINT_REPOSITORY_PROVIDER=autonomous
+USAGE_REPOSITORY_PROVIDER=autonomous
+
+ADB_USER=<usuario>
+ADB_PASSWORD=<senha>
+ADB_DSN=<dsn>
+ADB_WALLET_LOCATION=<caminho-wallet>
+ADB_WALLET_PASSWORD=<senha-wallet>
+ADB_TABLE_PREFIX=AGENTFW
+```
+
+Para usar Langfuse:
+
+```env
+ENABLE_LANGFUSE=true
+LANGFUSE_PUBLIC_KEY=<public-key>
+LANGFUSE_SECRET_KEY=<secret-key>
+LANGFUSE_HOST=http://localhost:3005
+```
+
+
+---
+
+## 5. Criando um novo agente
+
+Neste exemplo, vamos criar um agente chamado `financeiro_agent` para atendimento financeiro genérico.
+
+### 5.1. Antes do código: o que é um agente neste framework?
+
+Um agente é uma classe de domínio que recebe o `state` do LangGraph, interpreta a intenção escolhida pelo roteador ou supervisor, coleta evidências, chama tools/RAG/LLM quando necessário e retorna uma decisão para o workflow continuar.
+
+Ele não deve decidir sozinho tudo que o framework já decide. Por exemplo:
+
+```text
+O agente não cria sessão.
+O agente não abre SSE.
+O agente não compila LangGraph.
+O agente não cria checkpoint.
+O agente não executa guardrails globais.
+O agente não chama sistema externo diretamente quando existe MCP Tool Router.
+```
+
+O agente deve responder perguntas como:
+
+```text
+Qual problema de negócio estou resolvendo?
+Quais dados preciso para responder com segurança?
+Quais tools podem fornecer esses dados?
+Quais regras de domínio impedem ou autorizam uma ação?
+Qual resposta deve ser devolvida ao usuário?
+Quais eventos IC preciso emitir para auditoria da jornada?
+```
+
+### 5.2. Responsabilidades do arquivo `app/agents/financeiro_agent.py`
+
+Esse arquivo deve conter a lógica específica do agente financeiro. Ele deve:
+
+1. Receber o `state`.
+2. Separar `context`, `session`, `business_context` e `tool_arguments`.
+3. Emitir IC de início usando `AgentRuntimeMixin`.
+4. Coletar contexto de tools MCP, se houver, usando o MCP Tool Router do framework.
+5. Coletar contexto RAG, se houver, usando o RAG genérico do framework.
+6. Montar um prompt de domínio.
+7. Chamar o LLM pelo runtime comum, com cache e telemetria.
+8. Montar uma resposta padronizada.
+9. Emitir IC de conclusão.
+10. Retornar dados para o workflow.
+
+
+### 5.2.1. Entendendo `state`, `context`, `session`, `business_context` e `tool_arguments`
+
+Antes de copiar o código do agente, o desenvolvedor precisa entender **de onde vêm os dados**. Em um agente corporativo, o erro mais comum é pegar qualquer campo diretamente do `state` sem saber se aquele dado veio do canal, do gateway, do identity resolver, do roteador ou do usuário.
+
+O `state` é o envelope completo da execução do LangGraph. Dentro dele normalmente existe um `context`, que é o contexto normalizado pelo framework.
+
+Dentro de `context`, se o projeto usa **Agent Gateway / Global Supervisor**, é comum existir também um bloco `session`:
+
+```python
+ctx = state.get("context") or {}
+session = ctx.get("session") or {}
+```
+
+O papel de cada bloco é diferente:
+
+```text
+state
+  Estado completo do workflow atual. Carrega texto, intent, route, resposta parcial,
+  resultados MCP, dados de guardrail, checkpoint e outros campos técnicos.
+
+context
+  Contexto normalizado da mensagem atual. Normalmente vem do Channel Gateway,
+  Identity Resolver e Agent Gateway.
+
+session
+  Dados da sessão e do canal. Ajuda a saber quem está conversando, por qual canal,
+  em qual tenant, qual sessão global está ativa e qual backend/agente está atendendo.
+
+business_context
+  Dados de negócio já normalizados. Exemplo: customer_key, contract_key,
+  interaction_key, session_key, protocol_id, invoice_id, order_id.
+
+tool_arguments
+  Parâmetros explícitos já preparados para tools/MCP. Quando existe, deve ter
+  prioridade sobre inferências feitas pelo agente.
+```
+
+A ordem de confiança recomendada é:
+
+```text
+1. tool_arguments explícitos
+2. business_context resolvido pelo framework
+3. context normalizado
+4. session e session.metadata, quando vierem do Agent Gateway
+5. state direto
+6. texto original do usuário, apenas para extração complementar
+```
+
+Essa ordem evita dois problemas:
+
+```text
+Problema 1: ignorar dados já resolvidos pelo Gateway/Identity Resolver.
+Problema 2: sobrescrever um parâmetro canônico com um valor bruto e menos confiável.
+```
+
+Exemplo prático: se o `business_context.customer_key` já foi resolvido pelo framework, o agente não deve preferir um `user_id` genérico da sessão apenas porque ele existe. O `user_id` identifica o usuário no canal; o `customer_key` identifica o cliente no negócio.
+
+Mesmo que um agente simples não use `session` diretamente, existe uma diferença entre **sessão técnica** e **contexto de negócio**.
+
+### 5.2.2. Entendendo a classe `AgentRuntimeMixin` de `runtime.py`
+
+Antes de escrever um agente novo, o desenvolvedor precisa entender por que quase todos os exemplos herdam de:
+
+```python
+from app.agents.runtime import AgentRuntimeMixin
+```
+
+O `AgentRuntimeMixin` é uma camada de conveniência operacional para o agente. Ele não é o agente, não é o workflow e não contém regra de negócio. Ele existe para evitar que cada agente tenha que reimplementar, de forma diferente, as mesmas capacidades técnicas.
+
+Em termos simples:
+
+```text
+AgentRuntimeMixin = caixa de ferramentas padronizada do agente
+FinanceiroAgent  = regra de negócio que usa essa caixa de ferramentas
+AgentWorkflow    = motor LangGraph que chama o agente
+Framework        = infraestrutura corporativa completa
+```
+
+Sem o `AgentRuntimeMixin`, cada desenvolvedor tenderia a escrever código próprio para:
+
+```text
+emitir IC/NOC/GRL
+chamar MCP Tool Router
+chamar RAG
+montar cache de LLM
+chamar LLM
+montar chave de cache
+tratar ausência de observer, cache, RAG ou tools
+```
+
+Isso geraria agentes inconsistentes. Um agente emitiria IC de um jeito, outro chamaria MCP diretamente, outro ignoraria cache, outro quebraria quando o observer estivesse desabilitado. O mixin evita esse problema.
+
+#### 5.2.2.1. O que o `AgentRuntimeMixin` oferece
+
+No template, o `AgentRuntimeMixin` concentra métodos utilitários como:
+
+| Método | Para que serve | Quando o agente usa |
+|---|---|---|
+| `_emit_ic()` | Emite evento de negócio/auditoria | início, fim, decisão de negócio, contexto coletado |
+| `_emit_noc()` | Emite evento operacional | erro técnico, timeout, fallback, indisponibilidade |
+| `_emit_grl()` | Emite evento de governança customizado | regra de domínio bloqueou ou sanitizou algo |
+| `_retrieve_rag_context()` | Consulta o RAG genérico do framework | agente precisa de contexto documental |
+| `_collect_mcp_context()` | Chama as tools MCP declaradas no `state.mcp_tools` | agente precisa consultar sistemas externos |
+| `_cache_get()` | Lê cache genérico | uso avançado, normalmente indireto |
+| `_cache_set()` | Grava cache genérico | uso avançado, normalmente indireto |
+| `_llm_cache_key()` | Monta chave estável de cache do LLM | normalmente usado internamente |
+| `_invoke_llm_cached()` | Chama o LLM com cache e telemetria | agente precisa gerar resposta com LLM |
+
+O desenvolvedor deve pensar assim:
+
+```text
+Eu escrevo a regra de negócio no run().
+Quando precisar de infraestrutura, chamo um helper do AgentRuntimeMixin.
+```
+
+#### 5.2.2.2. O que o `AgentRuntimeMixin` não deve fazer
+
+O mixin não deve conter regra de negócio específica, por exemplo:
+
+```text
+calcular contestação de fatura
+consultar protocolo ANATEL diretamente
+abrir SR Siebel diretamente
+classificar cancelamento TIM
+calcular valor de boleto financeiro
+validar produto de varejo específico
+```
+
+Essas regras pertencem ao agente ou ao MCP Server do domínio.
+
+A fronteira correta é:
+
+```text
+AgentRuntimeMixin
+  sabe chamar MCP, RAG, cache, LLM e observer
+
+Agente específico
+  sabe quais evidências precisa, quais regras aplicar e como responder
+
+MCP Server
+  sabe falar com sistema real, mock, banco, REST, SOAP ou serviço legado
+```
+
+#### 5.2.2.3. Como o mixin recebe seus recursos
+
+O `AgentRuntimeMixin` não cria `llm`, `tool_router`, `rag_service`, `cache` ou `observer`. Ele espera que o workflow injete esses objetos no construtor do agente.
+
+Por isso, no agente aparece este padrão:
+
+```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):
+        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
+```
+
+Isso significa:
+
+```text
+llm          = motor de geração configurado pelo framework
+telemetry    = spans/eventos técnicos
+tool_router  = roteador MCP padronizado
+rag_service  = busca documental/grafo/vetor
+cache        = cache Redis/memory/etc.
+settings     = configurações carregadas do .env/YAML
+observer     = emissor IC/NOC/GRL
+```
+
+O agente recebe esses objetos prontos. Ele não deve criar uma nova instância por conta própria dentro do `run()`.
+
+#### 5.2.2.4. Como `_emit_ic()`, `_emit_noc()` e `_emit_grl()` ajudam
+
+Um agente precisa ser auditável, mas não deveria quebrar se a observabilidade estiver desligada.
+
+Por isso, os métodos de emissão do mixin são **fail-open**: se não houver `observer`, ou se ocorrer erro ao emitir evento, a jornada de negócio continua.
+
+Exemplo de IC:
+
+```python
+await self._emit_ic(
+    "IC.FINANCEIRO_AGENT_STARTED",
+    state,
+    {"business_component": "financeiro"},
+    component="agent.financeiro.start",
+)
+```
+
+O desenvolvedor não precisa montar manualmente todos os metadados básicos. O mixin já tenta incluir informações como:
+
+```text
+session_id
+conversation_key
+tenant_id
+agent_id
+route
+intent
+message_id
+channel_id
+```
+
+A regra prática é:
+
+```text
+Use _emit_ic() para marco de negócio.
+Use _emit_noc() para problema operacional.
+Use _emit_grl() para governança específica do domínio.
+```
+
+#### 5.2.2.5. Como `_collect_mcp_context()` funciona
+
+O método `_collect_mcp_context(state)` lê a lista de tools já escolhidas pelo roteador:
+
+```python
+ tools = state.get("mcp_tools") or []
+```
+
+Depois chama o `tool_router` do framework para cada tool. O agente não precisa saber se a tool usa HTTP, Docker, mock ou serviço real.
+
+Fluxo conceitual:
+
+```text
+routing.yaml escolhe intent
+  ↓
+intent define mcp_tools
+  ↓
+state.mcp_tools recebe a lista de tools
+  ↓
+AgentRuntimeMixin._collect_mcp_context()
+  ↓
+MCP Tool Router
+  ↓
+MCP Server
+  ↓
+resultado normalizado volta ao agente
+```
+
+Exemplo no agente:
+
+```python
+tool_context = await self._collect_mcp_context(state)
+```
+
+O desenvolvedor deve usar esse método quando basta chamar as tools definidas pela intent.
+
+Se o agente precisar escolher argumentos especiais por tool, pular tools perigosas, exigir confirmação ou montar parâmetros adicionais, ele pode implementar um método próprio no agente e chamar o router de forma mais controlada, como no exemplo do `BackofficeAgent`.
+
+#### 5.2.2.6. Como `_retrieve_rag_context()` funciona
+
+O método `_retrieve_rag_context(state)` consulta o RAG genérico configurado no framework.
+
+Ele usa como texto base:
+
+```text
+state.sanitized_input ou state.user_text
+```
+
+E tenta definir um namespace de busca a partir de:
+
+```text
+agent_profile.rag_namespace
+agent_id
+route
+default
+```
+
+Também pode usar informações do `business_context`, como `customer_key` ou `contract_key`, para enriquecer busca em grafo ou contexto relacionado.
+
+Exemplo:
+
+```python
+rag_context, rag_metadata = await self._retrieve_rag_context(state)
+```
+
+O agente usa `rag_context` no prompt e pode retornar `rag_metadata` para auditoria/debug.
+
+Regra prática:
+
+```text
+Use RAG quando a resposta depende de documento, política, base de conhecimento ou conteúdo não codificado.
+Não use RAG para substituir uma consulta operacional que deve ser feita por tool MCP.
+```
+
+#### 5.2.2.7. Como `_invoke_llm_cached()` funciona
+
+O método `_invoke_llm_cached()` chama o LLM passando mensagens no formato chat:
+
+```python
+answer = await self._invoke_llm_cached(state, "FinanceiroAgent", messages)
+```
+
+Antes de chamar o LLM, ele monta uma chave de cache considerando elementos como:
+
+```text
+nome do agente
+tenant_id
+agent_id
+intent
+customer_key
+contract_key
+interaction_key
+texto do usuário
+conteúdo do prompt
+```
+
+Se já existir resposta no cache, o método retorna o valor cacheado. Se não existir, chama o LLM, grava no cache e retorna a resposta.
+
+Isso evita que cada agente implemente cache de forma diferente.
+
+O desenvolvedor deve entender que o cache é útil para prompts determinísticos ou consultas repetidas, mas deve ser usado com cuidado em ações sensíveis. O agente não deve confirmar operação externa apenas porque uma resposta de LLM veio de cache. Confirmações operacionais devem depender de retorno real da tool.
+
+#### 5.2.2.8. Quando usar `_collect_mcp_context()` e quando criar lógica própria
+
+Use `_collect_mcp_context()` quando:
+
+```text
+a intent já definiu as tools corretas
+os parâmetros canônicos já estão no business_context
+a execução pode chamar todas as tools da lista
+nenhuma tool representa ação sensível
+```
+
+Crie lógica própria no agente quando:
+
+```text
+uma tool só pode ser chamada após confirmação explícita
+uma tool exige argumentos adicionais derivados da mensagem
+uma tool deve ser pulada se faltar campo obrigatório
+uma tool de registro/alteração não pode rodar automaticamente
+uma sequência de tools depende do resultado anterior
+```
+
+Exemplo de regra segura:
+
+```python
+if tool.startswith("registrar_") and not action_text:
+    return {"ok": False, "skipped": True, "reason": "ação sem confirmação explícita"}
+```
+
+Isso é regra de domínio e deve ficar no agente, não no mixin.
+
+#### 5.2.2.9. Como o dev deve ler o `run()` de um agente que herda o mixin
+
+Ao abrir um agente, o desenvolvedor deve procurar esta estrutura mental:
+
+```text
+1. O agente emite IC de início?
+2. Ele lê context/session/business_context de forma organizada?
+3. Ele valida dados obrigatórios do domínio?
+4. Ele chama MCP usando o mixin ou lógica própria controlada?
+5. Ele chama RAG quando precisa de conhecimento documental?
+6. Ele monta prompt com evidências, e não com chute?
+7. Ele chama LLM via _invoke_llm_cached()?
+8. Ele emite IC/NOC/GRL relevantes?
+9. Ele retorna answer, next_state, mcp_results e metadados úteis?
+```
+
+Se o agente faz isso, ele está usando o framework corretamente.
+
+#### 5.2.2.10. Exemplo mínimo de uso correto do mixin
+
+```python
+async def run(self, state):
+    await self._emit_ic("IC.FINANCEIRO_STARTED", state, component="agent.financeiro.start")
+
+    ctx = state.get("context") or {}
+    business_context = ctx.get("business_context") or state.get("business_context") or {}
+
+    if not business_context.get("customer_key"):
+        return {
+            "answer": "Informe o identificador do cliente para continuar.",
+            "next_state": "WAITING_CUSTOMER_KEY",
+            "mcp_results": [],
+        }
+
+    mcp_results = await self._collect_mcp_context(state)
+    rag_context, rag_metadata = await self._retrieve_rag_context(state)
+
+    messages = [
+        {"role": "system", "content": "Você é um agente financeiro corporativo."},
+        {"role": "user", "content": f"Evidências MCP: {mcp_results}\nContexto RAG: {rag_context}"},
+    ]
+
+    answer = await self._invoke_llm_cached(state, "FinanceiroAgent", messages)
+
+    await self._emit_ic("IC.FINANCEIRO_COMPLETED", state, {"mcp_count": len(mcp_results)}, component="agent.financeiro.completed")
+
+    return {
+        "answer": answer,
+        "next_state": "FINANCEIRO_ACTIVE",
+        "mcp_results": mcp_results,
+        "rag_metadata": rag_metadata,
+    }
+```
+
+Esse exemplo mostra a intenção do mixin: o desenvolvedor escreve o raciocínio do agente, mas delega infraestrutura para métodos padronizados.
+
+#### 5.2.2.11. Erros comuns ao usar o `AgentRuntimeMixin`
+
+```text
+Herdar de AgentRuntimeMixin, mas chamar REST diretamente dentro do agente.
+Criar outro cache manual em vez de usar _invoke_llm_cached().
+Emitir eventos diretamente em formatos diferentes do observer.
+Colocar regra de domínio dentro do runtime.py.
+Usar _collect_mcp_context() para tool de ação sem confirmação.
+Ignorar business_context e pegar parâmetros soltos do payload.
+Tratar session_id global e backend_session_id como se fossem a mesma coisa.
+Sobrescrever métodos internos do mixin sem necessidade.
+```
+
+A regra mais importante é:
+
+```text
+O mixin padroniza capacidades técnicas.
+O agente decide como aplicar essas capacidades ao domínio.
+```
+
+
+### 5.2.3. Entendendo `messages`: arquitetura conversacional do agente
+
+Depois de entender `state`, `context`, `session`, `business_context`, `tool_arguments` e `AgentRuntimeMixin`, falta entender uma peça central: `messages`.
+
+Em um agente, `messages` não é apenas uma lista de textos. Ele é o **contrato conversacional** que será enviado ao LLM naquela chamada. É nesse contrato que o agente organiza instruções, pergunta do usuário, evidências, contexto RAG, resultados MCP, memória resumida e formato esperado da resposta.
+
+Um exemplo mínimo é:
+
+```python
+messages = [
+    {
+        "role": "system",
+        "content": "Você é um agente financeiro. Não invente dados.",
+    },
+    {
+        "role": "user",
+        "content": "Quero consultar meu pagamento.",
+    },
+]
+```
+
+Esse formato é comum em frameworks e provedores modernos de IA conversacional. Ele aparece, com pequenas variações, em OpenAI Chat Completions/Responses API, OCI Generative AI OpenAI-compatible, LangChain `ChatModel`, LangGraph, Semantic Kernel, LlamaIndex e em arquiteturas com tool calling e MCP.
+
+A ideia é simples:
+
+```text
+O agente monta uma conversa canônica.
+O AgentRuntimeMixin chama o provider LLM padronizado.
+O provider adapta essa conversa para o backend real.
+```
+
+Isso permite que o agente continue escrevendo `messages` de forma previsível, mesmo que por baixo o projeto use OCI Generative AI, OpenAI-compatible endpoint, LangChain, Llama local, mock ou outro provider.
+
+#### 5.2.3.1. Papéis principais de uma mensagem
+
+Cada item de `messages` possui pelo menos um `role` e um `content`.
+
+| Role | Para que serve |
+|---|---|
+| `system` | Define identidade, limites, políticas, regras e comportamento do agente. |
+| `user` | Representa a solicitação atual do usuário ou uma instrução contextualizada pelo framework. |
+| `assistant` | Representa respostas anteriores do modelo, quando o histórico é incluído explicitamente. |
+| `tool` | Representa resultado de ferramenta em fluxos com tool calling estruturado. |
+| `developer` | Em alguns provedores, representa instruções intermediárias do desenvolvedor ou da aplicação. |
+
+No template, o padrão mais simples usa principalmente:
+
+```text
+system → quem é o agente, o que ele pode fazer e o que ele não pode fazer
+user   → mensagem atual + evidências + contexto de negócio + MCP + RAG
+```
+
+Esse padrão é intencionalmente simples para manter compatibilidade com vários runtimes.
+
+#### 5.2.3.2. O que deve ir no `system`
+
+O `system` deve conter regras estáveis e de maior prioridade. Ele responde:
+
+```text
+Quem é este agente?
+Qual domínio ele atende?
+Quais limites ele deve respeitar?
+O que ele nunca deve inventar?
+Quando ele deve pedir mais dados?
+Quando ele deve recusar uma ação?
+Qual tom e formato de resposta deve usar?
+```
+
+Exemplo:
+
+```python
+system_content = apply_agent_profile_prompt(
+    state,
+    """
+    Você é um agente financeiro corporativo.
+    Use somente dados fornecidos por MCP, RAG ou business_context.
+    Não confirme pagamento, baixa, acordo ou contestação sem evidência de tool.
+    Se faltar identificador obrigatório, peça apenas esse dado.
+    Responda de forma curta, operacional e auditável.
+    """.strip(),
+)
+```
+
+Regras críticas devem ficar no `system`, não escondidas no meio do `user`.
+
+#### 5.2.3.3. O que deve ir no `user`
+
+O `user` deve trazer o pedido atual e o contexto necessário para responder. No agente corporativo, ele normalmente contém:
+
+```text
+mensagem atual do usuário
+intent escolhida pelo roteador
+route/agente ativo
+business_context normalizado
+resultados MCP
+contexto RAG
+metadados relevantes de sessão
+instrução de formato para a resposta
+```
+
+Exemplo:
+
+```python
+messages = [
+    {
+        "role": "system",
+        "content": system_content,
+    },
+    {
+        "role": "user",
+        "content": (
+            "Mensagem do usuário:\n"
+            f"{user_text}\n\n"
+            "Intent e rota escolhidas pelo framework:\n"
+            f"intent={state.get('intent')} route={state.get('route')}\n\n"
+            "Contexto de negócio normalizado:\n"
+            f"customer_key={business_context.get('customer_key')}\n"
+            f"contract_key={business_context.get('contract_key')}\n"
+            f"interaction_key={business_context.get('interaction_key')}\n\n"
+            "Resultados MCP:\n"
+            f"{tool_context}\n\n"
+            "Contexto RAG:\n"
+            f"{rag_context or '[sem contexto RAG]'}\n\n"
+            "Instrução de resposta:\n"
+            "Responda somente com base nas evidências acima. "
+            "Se uma evidência obrigatória estiver ausente, diga que não foi encontrada."
+        ),
+    },
+]
+```
+
+Observe que o exemplo não joga o `state` inteiro no prompt. Ele seleciona os campos relevantes.
+
+#### 5.2.3.4. Relação entre `messages`, memória e histórico
+
+`messages` não é a memória persistente do agente.
+
+```text
+Memória persistente
+  Fica no repositório/memória do framework.
+  Pode sobreviver a várias interações.
+  Pode ser resumida, compactada ou consultada.
+
+messages
+  É o payload enviado ao LLM em uma chamada específica.
+  Pode incluir um resumo de memória.
+  Pode incluir parte do histórico.
+  Não deve virar um dump completo da conversa.
+```
+
+Se o framework já carregou histórico ou resumo de conversa, o agente deve usar apenas o trecho necessário. Duplicar histórico manualmente aumenta custo, latência e risco de inconsistência.
+
+#### 5.2.3.5. Relação entre `messages`, MCP e RAG
+
+MCP e RAG produzem evidências. O LLM usa essas evidências para redigir a resposta.
+
+```text
+MCP Tool Router
+  consulta sistemas, mocks, serviços ou ações externas
+  retorna dados estruturados
+
+RAG
+  busca contexto documental
+  retorna trechos relevantes e metadados
+
+messages
+  organizam essas evidências em uma conversa para o LLM
+```
+
+Um bom agente deixa claro para o LLM o que é evidência e o que é instrução.
+
+Evite misturar tudo em um texto sem estrutura. Prefira blocos:
+
+```text
+Instruções:
+- Não invente dados.
+
+Mensagem do usuário:
+...
+
+Evidências MCP:
+...
+
+Contexto RAG:
+...
+
+Formato esperado:
+...
+```
+
+Essa organização melhora a rastreabilidade e reduz alucinação.
+
+#### 5.2.3.6. Compatibilidade com frameworks de mercado
+
+O padrão de `messages` é compatível com a maior parte do ecossistema de IA conversacional, mas existem diferenças entre provedores.
+
+| Framework/provedor | Compatibilidade conceitual | Atenção |
+|---|---|---|
+| OpenAI Chat/Responses | Alta | Roles, tool calls e formatos multimodais podem variar por API. |
+| OCI Generative AI OpenAI-compatible | Alta | Normalmente aceita formato semelhante ao OpenAI-compatible. |
+| LangChain `ChatModel` | Alta | Pode converter dicts para `SystemMessage`, `HumanMessage`, `AIMessage`. |
+| LangGraph | Alta | O state pode carregar `messages` ou o agente pode montar messages por chamada. |
+| Semantic Kernel | Alta | Usa conceitos equivalentes de chat history e roles. |
+| LlamaIndex | Alta | Pode adaptar para chat engine ou completion engine. |
+| Anthropic Messages API | Média/Alta | Pode exigir adaptações de system prompt e roles. |
+| Modelos locais | Variável | Alguns esperam chat template específico. |
+
+Por isso, o agente não deve chamar diretamente SDKs específicos. Ele monta `messages` e delega a chamada para:
+
+```python
+answer = await self._invoke_llm_cached(state, "FinanceiroAgent", messages)
+```
+
+Assim, a adaptação para o provider fica centralizada no runtime/framework.
+
+#### 5.2.3.7. Pitfalls comuns ao montar `messages`
+
+**Pitfall 1 — Enviar o `state` inteiro ao LLM**
+
+Ruim:
+
+```python
+{"role": "user", "content": f"State completo: {state}"}
+```
+
+Melhor:
+
+```python
+{"role": "user", "content": f"customer_key={business_context.get('customer_key')}"}
+```
+
+O `state` pode conter dados técnicos, campos sensíveis, histórico, checkpoint e informações desnecessárias.
+
+**Pitfall 2 — Mandar objetos enormes sem curadoria**
+
+Ruim:
+
+```python
+f"Resultados completos: {mcp_results}"
+```
+
+Melhor:
+
+```python
+resumo_tools = [
+    {
+        "tool": r.get("tool_name") or r.get("tool"),
+        "ok": r.get("ok"),
+        "status": r.get("status"),
+        "evidence": r.get("evidence") or r.get("summary"),
+    }
+    for r in mcp_results
+]
+```
+
+Depois envie apenas o resumo necessário.
+
+**Pitfall 3 — Passar dados sensíveis sem necessidade**
+
+Ruim:
+
+```python
+f"CPF completo: {cpf}"
+```
+
+Melhor:
+
+```python
+f"Cliente identificado: {'sim' if customer_key else 'não'}"
+```
+
+Quando precisar enviar identificador, prefira chave canônica, hash ou valor mascarado, conforme política do projeto.
+
+**Pitfall 4 — Deixar o LLM inventar quando a tool falhou**
+
+Ruim:
+
+```text
+Responda sobre o pagamento do cliente.
+```
+
+Melhor:
+
+```text
+A tool consultar_pagamentos_financeiro retornou erro ou ausência de dados.
+Não confirme pagamento. Informe que a evidência não foi encontrada.
+```
+
+**Pitfall 5 — Confundir instrução com evidência**
+
+Ruim:
+
+```text
+O cliente pagou e você deve responder que está tudo certo.
+```
+
+Melhor:
+
+```text
+Evidência MCP:
+- consultar_pagamentos_financeiro: status=COMPENSADO
+
+Instrução:
+- Explique o status de forma objetiva.
+```
+
+**Pitfall 6 — Colocar regra crítica só no `user`**
+
+Regra de comportamento permanente deve ir no `system`. O `user` deve carregar o pedido e o contexto daquela interação.
+
+**Pitfall 7 — Duplicar histórico**
+
+Se o framework já incluiu resumo de memória, não reenvie toda a conversa manualmente.
+
+**Pitfall 8 — Não pedir formato de resposta**
+
+Em contexto corporativo, peça resposta curta, operacional, rastreável e baseada em evidência.
+
+#### 5.2.3.8. Modelo recomendado de `messages` para agentes corporativos
+
+Use este padrão como referência:
+
+```python
+system_content = apply_agent_profile_prompt(
+    state,
+    """
+    Você é um agente corporativo especializado no domínio financeiro.
+    Use somente evidências vindas de business_context, MCP e RAG.
+    Não invente protocolo, cliente, contrato, status, pagamento ou ação operacional.
+    Se faltar dado obrigatório, peça apenas esse dado.
+    Responda de forma curta, operacional e auditável.
+    """.strip(),
+)
+
+messages = [
+    {
+        "role": "system",
+        "content": system_content,
+    },
+    {
+        "role": "user",
+        "content": (
+            "Mensagem do usuário:\n"
+            f"{user_text}\n\n"
+            "Contexto de sessão resumido:\n"
+            f"channel={session.get('channel')} tenant_id={session.get('tenant_id')}\n"
+            f"global_session_id={session.get('global_session_id')}\n\n"
+            "Contexto de negócio:\n"
+            f"customer_key={business_context.get('customer_key')}\n"
+            f"contract_key={business_context.get('contract_key')}\n"
+            f"interaction_key={business_context.get('interaction_key')}\n\n"
+            "Intent e rota:\n"
+            f"intent={state.get('intent')} route={state.get('route')}\n\n"
+            "Evidências MCP:\n"
+            f"{mcp_evidence}\n\n"
+            "Contexto RAG:\n"
+            f"{rag_context or '[sem contexto RAG]'}\n\n"
+            "Formato esperado:\n"
+            "1. Resposta direta ao usuário.\n"
+            "2. Não cite detalhes internos de arquitetura.\n"
+            "3. Se faltou evidência, diga claramente o que faltou."
+        ),
+    },
+]
+```
+
+Esse padrão ajuda o desenvolvedor a separar:
+
+```text
+Regras permanentes        → system
+Pedido e contexto atual   → user
+Evidências de tools       → bloco MCP
+Conhecimento documental   → bloco RAG
+Sessão/canal              → contexto resumido
+Formato de saída          → instrução final
+```
+
+#### 5.2.3.9. Como revisar `messages` durante desenvolvimento
+
+Durante o desenvolvimento, antes de culpar o LLM, revise o payload enviado para ele.
+
+Perguntas úteis:
+
+```text
+O system prompt contém as regras mais importantes?
+O user prompt contém a pergunta real do usuário?
+O business_context certo foi incluído?
+Os resultados MCP aparecem como evidência, e não como instrução inventada?
+O RAG trouxe contexto útil ou só ruído?
+Há dados sensíveis desnecessários?
+O prompt está grande demais?
+O formato de resposta esperado está claro?
+```
+
+Uma boa prática é emitir um IC de debug em ambiente não produtivo ou logar uma versão sanitizada do prompt, nunca o prompt bruto com dados sensíveis.
+
+
+### 5.2.4. Recursos avançados agora padronizados pelo framework
+
+Nos primeiros exemplos deste tutorial, o agente usa diretamente métodos simples como `_collect_mcp_context()` e `_invoke_llm_cached()`. Isso é suficiente para agentes simples. Porém, em agentes reais migrados para o framework, como um Backoffice/ANATEL, aparecem necessidades adicionais:
+
+```text
+normalizar tools por intent;
+ler context/session/business_context/tool_arguments sempre da mesma forma;
+montar argumentos MCP com aliases;
+bloquear tools de ação quando falta payload obrigatório;
+executar tools uma a uma com eventos de observabilidade;
+montar messages sem despejar o state inteiro no prompt;
+gerar fallback controlado quando o LLM falha.
+```
+
+Essas necessidades não são exclusivas do Backoffice. Por isso, a partir desta versão, elas passam a ser tratadas como **capacidades reutilizáveis do framework**, e não como código que cada agente deve copiar.
+
+#### 5.2.4.1. `RuntimeContext`: leitura canônica do state
+
+O framework passa a oferecer um objeto conceitual chamado `RuntimeContext`, obtido pelo agente com:
+
+```python
+runtime = self.get_runtime_context(state)
+```
+
+Esse objeto organiza:
+
+```text
+runtime.state              → state completo do LangGraph
+runtime.context            → context normalizado
+runtime.session            → dados de sessão/canal vindos do Gateway
+runtime.session_metadata   → metadata da sessão
+runtime.business_context   → identidade de negócio canônica
+runtime.tool_arguments     → parâmetros explícitos para tools
+runtime.sanitized_input    → texto sanitizado pelos guardrails
+runtime.original_text      → texto original, quando necessário para extração controlada
+```
+
+O desenvolvedor não precisa ficar repetindo:
+
+```python
+ctx = state.get("context") or {}
+session = ctx.get("session") or {}
+business_context = ctx.get("business_context") or state.get("business_context") or {}
+```
+
+Ele pode usar:
+
+```python
+runtime = self.get_runtime_context(state)
+customer_key = runtime.pick("customer_key", "cpf", "cnpj", "msisdn")
+```
+
+A ordem de confiança continua padronizada:
+
+```text
+1. tool_arguments
+2. business_context
+3. context
+4. session
+5. session.metadata
+6. state
+```
+
+#### 5.2.4.2. `normalize_tools_by_intent()`: fallback de tools sem tirar poder do router
+
+Em um agente ideal, o `EnterpriseRouter` escolhe a intent e injeta `mcp_tools` no `state`. Mas, em testes, chamadas diretas ou migrações, o agente pode ser executado sem essa injeção.
+
+Para isso, o framework oferece:
+
+```python
+normalized_state = self.normalize_tools_by_intent(
+    state,
+    default_tools_by_intent=DEFAULT_TOOLS_BY_INTENT,
+    default_intent="financeiro_pagamentos",
+    route=self.name,
+)
+```
+
+A regra é:
+
+```text
+Se state['mcp_tools'] veio do router, use essas tools.
+Se não veio, use o fallback declarado pelo agente.
+Remova duplicidades.
+Preserve ordem estável.
+Defina intent, route e active_agent quando estiverem ausentes.
+```
+
+Isso evita que cada agente implemente seu próprio `_normalize_state_tools()`.
+
+#### 5.2.4.3. `build_tool_arguments()`: argumentos MCP canônicos
+
+O agente pode montar argumentos MCP sem conhecer todos os detalhes do mapper:
+
+```python
+args = self.build_tool_arguments(
+    state,
+    tool_name="consultar_titulo_financeiro",
+    intent=state.get("intent"),
+    aliases={
+        "customer_key": ["customer_id", "cpf", "cnpj"],
+        "contract_key": ["contract_id", "invoice_id"],
+    },
+)
+```
+
+Esse método monta argumentos como:
+
+```text
+query
+operator_instructions
+customer_key
+contract_key
+interaction_key
+session_key
+parâmetros explícitos de tool_arguments
+aliases configurados pelo domínio
+```
+
+Depois disso, o `MCPToolRouter` ainda aplica o `mcp_parameter_mapping.yaml`. Ou seja:
+
+```text
+build_tool_arguments() monta o contrato canônico.
+mcp_parameter_mapping.yaml traduz para o nome esperado por cada MCP Server.
+```
+
+#### 5.2.4.4. Política de execução de tools sensíveis
+
+Nem toda tool é apenas consulta. Algumas tools executam ações, como registrar parecer, abrir solicitação, cancelar serviço ou criar protocolo.
+
+Essas tools devem ser declaradas com política em `config/tools.yaml`:
+
+```yaml
+tools:
+  registrar_acao_backoffice:
+    description: Registra ação operacional no backoffice.
+    mcp_server: backoffice
+    enabled: true
+    tool_type: action
+    requires: [protocol_id, action_text, operator_session]
+    confirmation_required: false
+    args_schema:
+      protocol_id: string
+      action_text: string
+      operator_session: string
+```
+
+Com isso, o framework consegue bloquear a chamada antes de chegar ao MCP quando falta campo obrigatório:
+
+```text
+Tool registrar_acao_backoffice escolhida.
+Framework monta argumentos.
+Framework verifica requires.
+Se action_text estiver ausente, retorna skipped=true.
+Agente emite IC/NOC de domínio, se necessário.
+```
+
+Isso evita que cada agente escreva manualmente:
+
+```python
+if tool.startswith("registrar_") and not arguments.get("action_text"):
+    ...
+```
+
+#### 5.2.4.5. `execute_tools_for_intent()`: execução padronizada das tools
+
+O agente pode executar tools selecionadas pela intent com:
+
+```python
+mcp_results = await self.execute_tools_for_intent(
+    state,
+    tools=state.get("mcp_tools") or [],
+    aliases=TOOL_ALIASES,
+)
+```
+
+Esse método cuida de:
+
+```text
+montar argumentos;
+aplicar política de execução;
+chamar _call_mcp_tool();
+normalizar resultado;
+emitir IC.MCP_TOOL_CALLED;
+emitir IC.TOOL_CALLED;
+emitir NOC.MCP_TOOL_FAILED quando houver falha;
+retornar skipped=true quando uma política bloquear a execução.
+```
+
+O agente ainda pode emitir ICs específicos de negócio depois disso. Exemplo: `AGA.010` para Speech Analytics, `AGA.011` para Cliente/IMDB, `AGA.020` para TAIS/templates.
+
+#### 5.2.4.6. `build_messages()`: messages padronizado
+
+Para evitar que cada agente monte prompts de forma diferente, o framework oferece:
+
+```python
+messages = self.build_messages(
+    state,
+    system_prompt=system_prompt,
+    mcp_results=mcp_results,
+    rag_context=rag_context,
+    rag_metadata=rag_metadata,
+)
+```
+
+Esse builder separa:
+
+```text
+system prompt;
+mensagem do usuário;
+intent e route;
+business_context;
+resultados MCP;
+contexto RAG;
+metadados RAG;
+seções extras.
+```
+
+O objetivo é reduzir estes erros:
+
+```text
+enviar state inteiro para o LLM;
+misturar regra permanente com evidência;
+incluir dados sensíveis sem necessidade;
+esquecer de informar que uma tool falhou;
+duplicar histórico que o framework já carrega.
+```
+
+#### 5.2.4.7. Quando customizar e quando usar o framework
+
+Use o framework para:
+
+```text
+ler contexto;
+normalizar tools;
+montar argumentos MCP;
+aplicar política de execução;
+chamar MCP;
+montar messages;
+chamar LLM com cache;
+emitir eventos técnicos genéricos.
+```
+
+Use o agente para:
+
+```text
+definir regras de negócio;
+definir aliases específicos do domínio;
+definir prompts do domínio;
+definir ICs específicos da jornada;
+definir estados conversacionais como WAITING_*;
+tratar compatibilidade de migração;
+decidir fallback textual específico do domínio.
+```
+
+Essa separação permite que um agente real tenha customizações fortes sem virar um motor paralelo ao framework.
+
+
+### 5.3. Criar o arquivo do agente
+
+Crie:
+
+```text
+app/agents/financeiro_agent.py
+```
+
+Código-base comentado:
+
+```python
+from app.agents.prompting import apply_agent_profile_prompt
+from app.agents.runtime import AgentRuntimeMixin
+
+
+class FinanceiroAgent(AgentRuntimeMixin):
+    # Este nome precisa bater com o nome usado no workflow e nas configurações.
+    name = "financeiro_agent"
+
+    def __init__(self, llm, telemetry=None, tool_router=None, rag_service=None, cache=None, settings=None, observer=None):
+        # Estes objetos são injetados pelo workflow/framework.
+        # O agente usa, mas não cria esses motores.
+        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
+
+    async def run(self, state):
+        # 1. Marca o início da jornada de negócio deste agente.
+        await self._emit_ic(
+            "IC.FINANCEIRO_AGENT_STARTED",
+            state,
+            {"business_component": "financeiro"},
+            component="agent.financeiro.start",
+        )
+
+        # 2. Separa os blocos do contrato do framework.
+        # O agente lê esses blocos, mas quem cria/normaliza é o framework.
+        ctx = state.get("context") or {}
+        session = ctx.get("session") or {}
+        session_metadata = session.get("metadata") or {}
+        business_context = ctx.get("business_context") or state.get("business_context") or {}
+        tool_arguments = ctx.get("tool_arguments") or state.get("tool_arguments") or {}
+
+        # 3. Interpreta a mensagem atual usando o texto já sanitizado pelos guardrails,
+        # mas preserva o texto original apenas quando precisar extrair identificadores.
+        user_text = state.get("sanitized_input") or state.get("user_text") or ""
+        original_text = (
+            ctx.get("message")
+            or ctx.get("text")
+            or ctx.get("query")
+            or session.get("last_user_message")
+            or state.get("user_text")
+            or user_text
+        )
+
+        # 4. Chama tools MCP selecionadas pelo roteamento, quando configuradas.
+        # O agente não precisa saber se a tool usa REST, SOAP, DB ou mock.
+        tool_context = await self._collect_tool_context(state)
+
+        if tool_context:
+            await self._emit_ic(
+                "IC.FINANCEIRO_MCP_CONTEXT_COLLECTED",
+                state,
+                {"tool_result_count": len(tool_context)},
+                component="agent.financeiro.mcp",
+            )
+
+        # 5. Recupera contexto documental, se o RAG estiver habilitado.
+        rag_context, rag_metadata = await self._retrieve_rag_context(state)
+
+        # 6. Monta a mensagem para o LLM.
+        # O system prompt define comportamento e limites do agente.
+        # O user prompt leva dados, evidências e contexto.
+        messages = [
+            {
+                "role": "system",
+                "content": apply_agent_profile_prompt(
+                    state,
+                    "Você é um agente financeiro. Responda com clareza, usando dados das ferramentas quando disponíveis. Não confirme ações financeiras sem evidência e confirmação explícita."
+                ),
+            },
+            {
+                "role": "user",
+                "content": (
+                    f"Mensagem: {state.get('sanitized_input') or state['user_text']}\n"
+                    f"Sessão: {session}\n"
+                    f"Intent: {state.get('intent')}\n"
+                    f"Dados MCP: {tool_context}\n"
+                    f"Contexto RAG: {rag_context}"
+                ),
+            },
+        ]
+
+        # 7. Chama o LLM usando o runtime comum, com cache e telemetria.
+        answer = await self._invoke_llm_cached(state, "FinanceiroAgent", messages)
+
+        # 8. Retorna no contrato esperado pelo workflow.
+        result = {
+            "answer": f"[FinanceiroAgent] {answer}",
+            "next_state": "FINANCEIRO_ACTIVE",
+            "mcp_results": tool_context,
+            "rag": rag_metadata,
+        }
+
+        # 9. Marca o fim da jornada de negócio.
+        await self._emit_ic(
+            "IC.FINANCEIRO_AGENT_COMPLETED",
+            state,
+            {
+                "answer_chars": len(result.get("answer") or ""),
+                "has_mcp_results": bool(tool_context),
+                "rag_enabled": bool(rag_metadata.get("enabled")),
+            },
+            component="agent.financeiro.completed",
+        )
+
+        return result
+
+    async def _collect_tool_context(self, state):
+        # Este método delega para o MCP Tool Router do framework.
+        # As tools chamadas dependem da intent definida em routing.yaml.
+        return await self._collect_mcp_context(state)
+```
+
+### 5.3.1. Como adaptar esse exemplo para um agente real
+
+No exemplo acima, `session`, `business_context` e `tool_arguments` aparecem no prompt para fins didáticos. Em produção, o desenvolvedor deve evitar jogar objetos enormes diretamente no prompt. O ideal é selecionar apenas os campos necessários.
+
+Exemplo de raciocínio para um agente financeiro:
+
+```text
+session.channel       → útil para ajustar linguagem ou entender origem da conversa.
+session.tenant_id     → útil para isolamento multi-tenant.
+business_context.customer_key → útil para consultar cliente/título/pagamento.
+business_context.contract_key → útil para consultar contrato, fatura ou pedido.
+business_context.interaction_key → útil para rastrear protocolo/chamado/interação.
+tool_arguments        → útil quando o Gateway ou Identity Resolver já preparou parâmetros exatos.
+```
+
+Uma função utilitária comum dentro do agente é um `pick()` com ordem de precedência explícita:
+
+```python
+def pick(name: str, *, tool_arguments, business_context, ctx, session, session_metadata, state):
+    if name in tool_arguments:
+        return tool_arguments.get(name)
+    if isinstance(business_context, dict) and name in business_context:
+        return business_context.get(name)
+    if name in ctx:
+        return ctx.get(name)
+    if name in session:
+        return session.get(name)
+    if name in session_metadata:
+        return session_metadata.get(name)
+    return state.get(name)
+```
+
+Essa função deixa claro que o agente não está “adivinhando” de onde vem o dado. Ele está seguindo uma política de confiança.
+
+### 5.3.2. Onde entra o Agent Gateway nesse código?
+
+Quando existe Agent Gateway / Global Supervisor, ele pode enriquecer a mensagem antes de enviá-la ao backend do agente. Exemplos de dados que podem chegar em `context.session`:
+
+```json
+{
+  "session": {
+    "global_session_id": "s1",
+    "backend_session_id": "default:financeiro_agent:s1",
+    "active_backend": "financeiro",
+    "channel": "web",
+    "tenant_id": "default",
+    "metadata": {
+      "selected_backend": "financeiro",
+      "last_reason": "Backend escolhido por regras: matches=['pagamento']"
+    }
+  }
+}
+```
+
+O agente não deve usar esse bloco para tomar decisão de negócio final. Ele deve usá-lo para contexto técnico, rastreabilidade e continuidade da conversa. A decisão de negócio deve continuar baseada em `business_context`, tools MCP, RAG e regras de domínio.
+
+### 5.4. Como saber se o agente está bem implementado?
+
+Um agente está bem implementado quando:
+
+```text
+Ele conhece regras de negócio, mas não conhece detalhes de infraestrutura.
+Ele usa o runtime comum para LLM, RAG, cache, MCP e IC.
+Ele retorna um contrato simples para o workflow.
+Ele não duplica guardrail, checkpoint, sessão, memória ou telemetria.
+Ele consegue ser testado isoladamente com state simulado.
+```
+
+---
+
+## 6. Registrando o agente no workflow
+
+### 6.1. Antes do código: o que é o workflow?
+
+O workflow é o caminho controlado pelo LangGraph. Ele define a ordem de execução:
+
+```text
+entrada → guardrails → roteamento → agente → revisão → persistência → resposta
+```
+
+Criar a classe do agente não basta. O LangGraph só executa nós que foram registrados no grafo.
+
+O registro no workflow responde três perguntas:
+
+```text
+Qual classe implementa o agente?
+Qual nome de nó representa esse agente no grafo?
+Para onde o fluxo segue depois que o agente responde?
+```
+
+### 6.2. Importar o agente
+
+Edite:
+
+```text
+app/workflows/agent_graph.py
+```
+
+Adicione:
+
+```python
+from app.agents.financeiro_agent import FinanceiroAgent
+```
+
+### 6.3. Instanciar o agente
+
+No `__init__` da classe `AgentWorkflow`, depois da criação de `agent_kwargs`:
+
+```python
+self.financeiro = FinanceiroAgent(llm, **agent_kwargs)
+```
+
+Essa linha injeta no agente os mesmos motores compartilhados pelos demais agentes: LLM, telemetry, MCP Tool Router, RAG, cache, settings e observer.
+
+### 6.4. Criar o nó do LangGraph
+
+Em `_build_graph()`:
+
+```python
+builder.add_node("financeiro_agent", self._node("financeiro_agent", self.financeiro_agent))
+```
+
+O primeiro `financeiro_agent` é o nome do nó no grafo. O segundo `self.financeiro_agent` é o método wrapper que será chamado quando o fluxo chegar nesse nó.
+
+### 6.5. Adicionar rota condicional
+
+No dicionário de `builder.add_conditional_edges("routing_decision", ...)`, inclua:
+
+```python
+"financeiro_agent": "financeiro_agent",
+```
+
+Exemplo:
+
+```python
+builder.add_conditional_edges(
+    "routing_decision",
+    lambda s: s.get("route", "billing_agent"),
+    {
+        "billing_agent": "billing_agent",
+        "product_agent": "product_agent",
+        "orders_agent": "orders_agent",
+        "support_agent": "support_agent",
+        "financeiro_agent": "financeiro_agent",
+        "handoff": "handoff",
+        "supervisor_agent": "supervisor_agent",
+    },
+)
+```
+
+Essa tabela conecta a decisão do roteador com o nó real do grafo.
+
+### 6.6. Conectar o nó ao Output Supervisor
+
+```python
+builder.add_edge("financeiro_agent", "output_supervisor")
+```
+
+Essa linha é importante porque a resposta do agente não deve ir direto ao usuário. Ela passa antes por output supervisor, output guardrails, judges, supervisor review e persistência.
+
+### 6.7. Criar o método wrapper
+
+Na classe `AgentWorkflow`:
+
+```python
+async def financeiro_agent(self, state):
+    async with self.langgraph_telemetry.node("financeiro_agent", state):
+        async with self.telemetry.span(
+            "workflow.agent.financeiro",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input={"intent": state.get("intent")},
+        ):
+            return await self.financeiro.run(state)
+```
+
+O wrapper adiciona telemetria ao redor do agente. A lógica de negócio continua dentro de `FinanceiroAgent.run()`.
+
+### 6.8. Adicionar ao modo supervisor
+
+No método `supervisor_agent()`, ajuste o mapa de handlers:
+
+```python
+handlers = {
+    "billing_agent": self.billing.run,
+    "product_agent": self.product.run,
+    "orders_agent": self.orders.run,
+    "support_agent": self.support.run,
+    "financeiro_agent": self.financeiro.run,
+}
+```
+
+Isso permite que o supervisor chame o novo agente quando `ROUTING_MODE=supervisor` ou quando houver handoff supervisionado.
+
+### 6.9. Erros comuns neste capítulo
+
+```text
+Criar a classe do agente, mas esquecer add_node.
+Adicionar add_node, mas esquecer add_conditional_edges.
+Adicionar rota, mas esquecer add_edge para output_supervisor.
+Usar nome diferente em routing.yaml, workflow e classe.
+Chamar self.financeiro.run direto sem wrapper de telemetria.
+```
+
+---
+
+## 7. Ajustando o estado do agente
+
+### 7.1. Antes do código: o que é o state?
+
+O `state` é o objeto que trafega entre os nós do LangGraph. Ele funciona como a memória de curto prazo da execução atual.
+
+Ele não é o banco de dados, não é a memória conversacional completa e não deve virar um repositório gigante de informações.
+
+Use o `state` para dados que precisam circular entre nós, por exemplo:
+
+```text
+texto do usuário
+intent escolhida
+rota escolhida
+resposta parcial
+resultado de uma tool
+próximo estado da conversa
+flags de decisão
+```
+
+Não use o `state` para:
+
+```text
+histórico longo de conversa
+arquivos grandes
+respostas completas de sistemas externos sem necessidade
+conteúdo bruto de documentos
+logs extensos
+```
+
+### 7.2. Quando alterar `app/state.py`
+
+Edite:
+
+```text
+app/state.py
+```
+
+Somente adicione novos campos se o agente precisar compartilhar informações específicas com outros nós.
+
+Exemplo:
+
+```python
+class AgentState(TypedDict, total=False):
+    # campos existentes...
+    financial_context: dict[str, Any]
+    financial_decision: dict[str, Any]
+```
+
+### 7.3. Critério de decisão
+
+Antes de criar um campo novo, pergunte:
+
+```text
+Outro nó precisa ler este dado?
+Este dado precisa sobreviver ao próximo passo do workflow?
+Este dado é pequeno e estruturado?
+Este dado ajuda na auditoria ou na decisão?
+```
+
+Se a resposta for não, deixe o dado local ao agente ou grave em repositório apropriado.
+
+---
+
+## 8. Registrando o agente em `config/agents.yaml`
+
+### 8.1. Antes do YAML: para que serve `agents.yaml`?
+
+O `agents.yaml` é o cadastro oficial dos agentes disponíveis. Ele não executa o agente sozinho, mas informa ao framework quais agentes existem, quais configurações isoladas eles usam e quais metadados descrevem o domínio.
+
+Ele responde:
+
+```text
+Qual é o agent_id?
+Qual nome amigável aparece em listagens e debug?
+Onde estão prompt, guardrails e judges específicos?
+Qual domínio esse agente atende?
+Quais metadados ajudam roteamento, auditoria e operação?
+```
+
+### 8.2. Exemplo de registro
+
+Edite:
+
+```text
+config/agents.yaml
+```
+
+Adicione:
+
+```yaml
+agents:
+  - agent_id: financeiro_agent
+    name: Financeiro Agent
+    description: Agente para dúvidas financeiras, pagamentos, saldos, acordos e segunda via.
+    prompt_policy_path: ./config/agents/financeiro_agent/prompt_policy.yaml
+    routing_config_path: ./config/routing.yaml
+    guardrails_config_path: ./config/agents/financeiro_agent/guardrails.yaml
+    judges_config_path: ./config/agents/financeiro_agent/judges.yaml
+    mcp_servers_config_path: ./config/mcp_servers.yaml
+    tools_config_path: ./config/tools.yaml
+    metadata:
+      domain: financeiro
+      system_prefix: |
+        Você está executando o financeiro_agent.
+        Use somente políticas, memória, checkpoints, guardrails e judges deste agent_id.
+        Não misture histórico ou decisões de outros agentes.
+```
+
+### 8.3. Cuidados
+
+O `agent_id` precisa ser consistente com:
+
+```text
+nome do nó no workflow
+nome usado em routing.yaml
+session_id canônico
+pasta config/agents/<agent_id>/
+metadados de observabilidade
+```
+
+Evite renomear `agent_id` depois que o agente já estiver em produção, porque isso pode quebrar histórico, memória, checkpoint e métricas.
+
+---
+
+## 9. Criando configurações isoladas do agente
+
+### 9.1. Antes do YAML: por que isolar configuração por agente?
+
+Cada agente pode ter política de prompt, guardrails e judges próprios. Um agente financeiro pode exigir confirmação explícita antes de uma ação. Um agente de suporte pode permitir respostas mais abertas. Um agente jurídico pode exigir evidência documental.
+
+Por isso, evite colocar tudo no arquivo global. Use configuração global para regras corporativas e configuração local para regras do domínio.
+
+Crie:
+
+```text
+config/agents/financeiro_agent/
+```
+
+### 9.2. `prompt_policy.yaml`
+
+Esse arquivo define a postura base do agente.
+
+```yaml
+id: financeiro_agent_prompt_policy
+version: 1
+description: Prompt base isolado do agente financeiro.
+system_prefix: |
+  Você é um agente corporativo especializado em atendimento financeiro.
+  Seja claro, objetivo, auditável e não invente dados.
+  Quando precisar executar uma ação, use ferramentas configuradas.
+  Quando faltar informação obrigatória, peça apenas o dado necessário.
+```
+
+Use este arquivo para regras persistentes de comportamento, não para regras temporárias de teste.
+
+### 9.3. `guardrails.yaml`
+
+Esse arquivo complementa os guardrails globais.
+
+```yaml
+input:
+  - code: MSK
+    enabled: true
+  - code: VLOOP
+    enabled: true
+  - code: PINJ
+    enabled: true
+output:
+  - code: REVPREC
+    enabled: true
+  - code: CMP
+    enabled: true
+```
+
+Use guardrail quando a resposta precisa ser bloqueada, sanitizada ou revisada por regra.
+
+### 9.4. `judges.yaml`
+
+Judges avaliam qualidade, aderência, groundedness e outros critérios após a resposta ser produzida.
+
+```yaml
+judges:
+  - name: response_quality
+    enabled: true
+    threshold: 0.7
+  - name: groundedness
+    enabled: true
+    threshold: 0.6
+```
+
+Use judge para avaliar resposta. Use guardrail para bloquear ou proteger. Use prompt para orientar comportamento.
+
+---
+
+## 10. Configurando roteamento em `config/routing.yaml`
+
+### 10.1. Antes do YAML: o que é roteamento?
+
+Roteamento é a decisão de qual agente deve tratar a mensagem.
+
+Em um sistema multiagente, o usuário não deveria precisar saber qual agente chamar. Ele escreve uma mensagem, e o framework decide a rota.
+
+O roteador normalmente considera:
+
+```text
+texto do usuário
+estado atual da conversa
+keywords
+examples
+prioridade
+agent_id solicitado
+políticas de estado
+LLM router, se habilitado
+```
+
+### 10.2. Quando criar uma intent nova?
+
+Crie uma intent quando existir uma categoria clara de solicitação que deve ir para um agente específico.
+
+Exemplo de intent financeira:
+
+```yaml
+intents:
+  - name: financeiro_pagamentos
+    domain: financeiro
+    agent: financeiro_agent
+    description: Dúvidas sobre pagamento, saldo, fatura, boleto, acordo, contestação e segunda via.
+    priority: 15
+    mcp_tools:
+      - consultar_titulo_financeiro
+      - consultar_pagamentos_financeiro
+    keywords:
+      - pagamento
+      - boleto
+      - saldo
+      - acordo
+      - financeiro
+      - segunda via
+      - vencimento
+      - cobrança
+      - contestação
+    examples:
+      - Quero consultar meu pagamento.
+      - Preciso da segunda via do boleto.
+      - Meu pagamento ainda não foi baixado.
+```
+
+### 10.3. O que significa `mcp_tools` na intent?
+
+`mcp_tools` indica quais tools devem ser disponibilizadas/coletadas quando essa intent for escolhida. Assim, o agente não precisa decidir manualmente cada chamada em todos os casos simples.
+
+O fluxo fica:
+
+```text
+routing.yaml escolhe intent
+intent aponta agent
+intent declara mcp_tools
+AgentRuntimeMixin coleta contexto MCP
+agente usa os dados na resposta
+```
+
+### 10.4. Políticas de estado
+
+Se a conversa já estiver em um estado específico, a próxima mensagem pode precisar voltar ao mesmo agente, mesmo que o texto seja curto.
+
+Exemplo:
+
+```yaml
+state_policies:
+  - state: WAITING_FINANCEIRO_CONFIRMATION
+    agent: financeiro_agent
+    description: Mantém confirmações curtas no fluxo financeiro.
+```
+
+Isso evita que uma resposta como “sim” seja roteada para o agente errado.
+
+### 10.5. Router versus supervisor
+
+No modo router:
+
+```env
+ROUTING_MODE=router
+```
+
+O framework escolhe uma rota de forma mais direta, normalmente por regras, keywords, examples e score.
+
+No modo supervisor:
+
+```env
+ROUTING_MODE=supervisor
+```
+
+Um supervisor pode decidir a sequência de agentes, handoff ou combinação de respostas.
+
+Use router quando o domínio for bem mapeado. Use supervisor quando a conversa exigir decomposição, múltiplos agentes ou decisão mais flexível.
+
+---
+
+## 11. Configurando tools em `config/tools.yaml`
+
+### 11.1. Antes do YAML: o que é uma tool?
+
+Uma tool é uma capacidade externa que o agente pode usar para obter dados ou executar uma ação.
+
+Exemplos:
+
+```text
+consultar fatura
+consultar pagamento
+abrir protocolo
+buscar pedido
+cancelar serviço
+consultar base de conhecimento
+```
+
+A tool não é necessariamente o sistema real. Ela é o contrato que o backend conhece. O sistema real fica atrás do MCP Server.
+
+### 11.2. Declarando tools
+
+Edite:
+
+```text
+config/tools.yaml
+```
+
+Adicione:
+
+```yaml
+tools:
+  consultar_titulo_financeiro:
+    description: Consulta um título financeiro por cliente e contrato.
+    mcp_server: financeiro
+    enabled: true
+    args_schema:
+      customer_id: string
+      contract_id: string
+
+  consultar_pagamentos_financeiro:
+    description: Consulta pagamentos financeiros por cliente.
+    mcp_server: financeiro
+    enabled: true
+    args_schema:
+      customer_id: string
+```
+
+### 11.3. Como pensar sobre uma tool
+
+Antes de declarar uma tool, defina:
+
+```text
+Qual pergunta de negócio ela responde?
+Ela só consulta ou executa uma ação?
+Quais parâmetros são obrigatórios?
+Quais parâmetros vêm da identidade canônica?
+Qual MCP Server implementa a tool?
+Qual timeout e fallback são aceitáveis?
+O resultado tem dados sensíveis que precisam ser mascarados?
+```
+
+O backend não deve chamar diretamente HTTP/SOAP/DB de sistemas de negócio quando essa chamada puder ser padronizada via MCP Tool Router.
+
+---
+
+## 12. Configurando servidores MCP
+
+### 12.1. Antes do YAML: o que é o MCP Server?
+
+O MCP Server é o adaptador entre o mundo do agente e os sistemas reais. Ele permite que o backend converse com ferramentas de forma padronizada, sem conhecer detalhes de REST, SOAP, banco, filas ou mocks.
+
+O desenho é:
+
+```text
+Agente
+  ↓
+MCP Tool Router do framework
+  ↓
+MCP Server do domínio
+  ↓
+Sistema real, mock, banco, REST, SOAP ou serviço interno
+```
+
+### 12.2. Configuração local
+
+Edite:
+
+```text
+config/mcp_servers.yaml
+```
+
+Exemplo:
+
+```yaml
+servers:
+  financeiro:
+    transport: http
+    endpoint: http://localhost:8300/mcp
+    enabled: true
+    description: MCP Server Financeiro local.
+```
+
+### 12.3. Configuração em Docker Compose
+
+Edite:
+
+```text
+config/mcp_servers.docker.yaml
+```
+
+Exemplo:
+
+```yaml
+servers:
+  financeiro:
+    transport: http
+    endpoint: http://financeiro-mcp:8300/mcp
+    enabled: true
+    description: MCP Server Financeiro em Docker.
+```
+
+### 12.4. Como evitar erro comum de endpoint
+
+Localmente, `localhost` funciona porque backend e MCP rodam na mesma máquina.
+
+Dentro do Docker Compose, `localhost` dentro do container do backend aponta para o próprio container do backend, não para o container do MCP. Por isso, em Docker, use o nome do serviço:
+
+```text
+http://financeiro-mcp:8300/mcp
+```
+
+---
+
+## 13. Configurando mapeamento de parâmetros MCP
+
+### 13.1. Antes do YAML: por que existe mapeamento?
+
+O framework trabalha com chaves canônicas para não depender dos nomes específicos de cada sistema.
+
+Exemplo:
+
+```text
+customer_key = cliente canônico no framework
+contract_key = contrato/fatura/pedido/título canônico
+interaction_key = interação externa
+session_key = sessão técnica
+```
+
+Mas cada tool pode esperar nomes diferentes:
+
+```text
+customer_id
+cpf
+msisdn
+clientCode
+contract_id
+invoice_id
+order_id
+```
+
+O `mcp_parameter_mapping.yaml` faz essa tradução sem obrigar o agente a conhecer os nomes internos de cada MCP.
+
+### 13.2. Exemplo
+
+Edite:
+
+```text
+config/mcp_parameter_mapping.yaml
+```
+
+```yaml
+mcp_parameter_mapping:
+  defaults:
+    use_mock: true
+  tools:
+    consultar_titulo_financeiro:
+      map:
+        customer_key: customer_id
+        contract_key: contract_id
+        interaction_key: interaction_id
+        session_key: session_id
+    consultar_pagamentos_financeiro:
+      map:
+        customer_key: customer_id
+        session_key: session_id
+```
+
+Interpretação:
+
+```text
+customer_key  -> chave canônica no framework
+customer_id   -> parâmetro esperado pela tool MCP
+```
+
+### 13.3. Como validar o mapeamento
+
+Se a tool recebe parâmetro errado, investigue nesta ordem:
+
+```text
+payload enviado ao /gateway/message
+config/identity.yaml
+business_context resolvido
+config/mcp_parameter_mapping.yaml
+args_schema da tool
+assinatura real no MCP Server
+```
+
+---
+
+## 14. Configurando identidade de negócio
+
+### 14.1. Antes do YAML: o que é identidade de negócio?
+
+Identidade de negócio é a normalização das chaves que representam o cliente, contrato, pedido, protocolo, sessão ou interação.
+
+Sem essa camada, cada canal envia um nome diferente e cada tool espera outro nome. O resultado é erro de parâmetro, tool sem dado obrigatório ou consulta ao cliente errado.
+
+O `identity.yaml` responde:
+
+```text
+De onde posso extrair customer_key?
+De onde posso extrair contract_key?
+De onde posso extrair interaction_key?
+De onde posso extrair session_key?
+Quais chaves são obrigatórias?
+```
+
+### 14.2. Exemplo
+
+Edite:
+
+```text
+config/identity.yaml
+```
+
+```yaml
+identity:
+  version: "2"
+  required:
+    - session_key
+  keys:
+    customer_key:
+      description: Cliente canônico.
+      sources:
+        - business_context.customer_key
+        - context.business_context.customer_key
+        - context.session.metadata.customer_key
+        - customer_key
+        - customer_id
+        - cpf
+        - cnpj
+        - user_id
+    contract_key:
+      description: Contrato, pedido, fatura ou título principal.
+      sources:
+        - business_context.contract_key
+        - context.business_context.contract_key
+        - context.session.metadata.contract_key
+        - contract_key
+        - contract_id
+        - invoice_id
+        - order_id
+    interaction_key:
+      description: Chave externa da interação.
+      sources:
+        - business_context.interaction_key
+        - context.business_context.interaction_key
+        - context.session.metadata.interaction_key
+        - interaction_key
+        - call_id
+        - message_id
+        - protocol_id
+    session_key:
+      description: Sessão técnica estável.
+      sources:
+        - business_context.session_key
+        - context.business_context.session_key
+        - context.session.backend_session_id
+        - context.session.global_session_id
+        - context.session.metadata.session_key
+        - session_key
+        - conversation_key
+        - session_id
+```
+
+### 14.3. Como pensar sobre identidade
+
+Use o mínimo necessário. Não torne tudo obrigatório. Para uma pergunta genérica, talvez só `session_key` seja suficiente. Para consultar um título financeiro, talvez `customer_key` e `contract_key` sejam obrigatórios.
+
+A identidade resolvida aparece em `business_context` dentro do `state` e é usada pelo `MCP Tool Router`.
+
+### 14.4. Relação entre SessionContext e BusinessContext
+
+Quando o Agent Gateway está presente, ele pode criar ou transportar dados de sessão. Esses dados são importantes, mas não substituem a identidade de negócio.
+
+```text
+SessionContext responde:
+  Quem está falando?
+  Por qual canal?
+  Qual sessão global está ativa?
+  Qual backend está atendendo?
+  Qual foi a razão da última decisão de rota?
+
+BusinessContext responde:
+  Qual cliente deve ser consultado?
+  Qual contrato/fatura/pedido está em discussão?
+  Qual protocolo/chamado/interação identifica o caso?
+  Qual chave deve ser enviada para a tool MCP?
+```
+
+Regra prática:
+
+```text
+Use session para continuidade, rastreabilidade e canal.
+Use business_context para consultar sistemas, chamar MCP e tomar decisão de negócio.
+Use tool_arguments quando parâmetros já vierem explicitamente preparados.
+```
+
+Exemplo de erro comum:
+
+```text
+Usar session.user_id como customer_key sem validar identity.yaml.
+```
+
+O correto é deixar o `IdentityResolver` transformar `user_id`, `cpf`, `msisdn`, `customer_id` ou outro identificador em uma chave canônica como `customer_key`.
+
+---
+
+## 15. Implementando ou conectando um MCP Server
+
+### 15.1. Antes do código: qual é o papel do MCP Server?
+
+O MCP Server é onde fica a integração com sistemas externos ou mocks de domínio. Ele permite que o agente use uma tool sem conhecer implementação técnica.
+
+O backend sabe chamar:
+
+```text
+consultar_titulo_financeiro(customer_id, contract_id)
+```
+
+Mas não sabe, nem deveria saber, se essa consulta usa:
+
+```text
+REST
+SOAP
+banco Oracle
+arquivo mock
+serviço legado
+fila
+sistema interno
+```
+
+### 15.2. Contrato conceitual das tools
+
+Exemplo conceitual:
+
+```python
+async def consultar_titulo_financeiro(customer_id: str, contract_id: str, session_id: str | None = None):
+    return {
+        "customer_id": customer_id,
+        "contract_id": contract_id,
+        "status": "ABERTO",
+        "valor": 129.90,
+        "vencimento": "2026-06-20",
+    }
+
+
+async def consultar_pagamentos_financeiro(customer_id: str, session_id: str | None = None):
+    return {
+        "customer_id": customer_id,
+        "pagamentos": [
+            {"data": "2026-06-01", "valor": 129.90, "status": "COMPENSADO"}
+        ],
+    }
+```
+
+### 15.3. Critério para mock versus real
+
+Use mock quando:
+
+```text
+o sistema real não está disponível
+você está testando roteamento e contrato
+você quer validar frontend/backend sem depender de VPN
+você quer montar testes automatizados determinísticos
+```
+
+Use integração real quando:
+
+```text
+o contrato já foi validado
+os parâmetros estão corretos
+o timeout e fallback foram definidos
+há observabilidade para sucesso e falha
+há dados seguros para teste
+```
+
+Para desenvolvimento, você pode usar `use_mock: true` no `mcp_parameter_mapping.yaml` ou implementar um MCP Server local com respostas simuladas.
+
+---
+
+## 16. IC, NOC e GRL no novo agente
+
+### 16.1. Antes dos eventos: por que eles existem?
+
+IC, NOC e GRL não são logs comuns. Eles existem para rastrear a execução de forma corporativa.
+
+```text
+IC  = evento de negócio ou jornada do agente
+NOC = evento operacional, erro, indisponibilidade, timeout ou degradação
+GRL = evento de governança, guardrail, bloqueio, revisão ou sanitização
+```
+
+Use `logger.info()` para diagnóstico simples. Use IC/NOC/GRL quando o evento precisa aparecer em auditoria, observabilidade ou análise operacional.
+
+### 16.2. IC — eventos de negócio
+
+Use ICs dentro do agente para registrar passos relevantes da jornada.
+
+Exemplo:
+
+```python
+await self._emit_ic(
+    "IC.FINANCEIRO_AGENT_STARTED",
+    state,
+    {"business_component": "financeiro"},
+    component="agent.financeiro.start",
+)
+```
+
+Sugestão mínima por agente:
+
+```text
+IC.<AGENTE>_AGENT_STARTED
+IC.<AGENTE>_MCP_CONTEXT_COLLECTED
+IC.<AGENTE>_RAG_CONTEXT_RETRIEVED
+IC.<AGENTE>_AGENT_COMPLETED
+IC.<AGENTE>_BUSINESS_DECISION
+IC.<AGENTE>_ACTION_REQUESTED
+IC.<AGENTE>_ACTION_COMPLETED
+```
+
+### 16.3. NOC — eventos operacionais
+
+NOC deve ser usado para saúde técnica, indisponibilidade, erro, timeout, fallback e degradação.
+
+Exemplo:
+
+```python
+await self.observer.emit_noc(
+    "NOC.FINANCEIRO_TOOL_TIMEOUT",
+    {
+        "session_id": state.get("conversation_key") or state.get("session_id"),
+        "tenant_id": state.get("tenant_id"),
+        "agent_id": state.get("agent_id"),
+        "tool": "consultar_titulo_financeiro",
+    },
+    component="agent.financeiro.tool",
+)
+```
+
+### 16.4. GRL — guardrails
+
+A maior parte dos GRLs já é emitida pelo workflow em:
+
+```text
+input_guardrails
+output_supervisor
+output_guardrails
+```
+
+Só implemente GRL dentro do agente quando houver uma validação de domínio específica que não caiba nos guardrails globais.
+
+### 16.5. Quando não criar evento novo
+
+Não crie IC/NOC/GRL para cada linha de código. Crie eventos para decisões importantes:
+
+```text
+entrada validada
+contexto MCP coletado
+decisão de negócio tomada
+ação externa solicitada
+ação externa concluída
+fallback técnico acionado
+resposta bloqueada ou revisada
+workflow concluído
+```
+
+---
+
+## 17. Build e execução local
+
+### 17.1. Antes dos comandos: o que significa subir o backend?
+
+Subir o backend significa iniciar a API que recebe mensagens, normaliza canal, resolve identidade, abre sessão, executa o workflow e devolve resposta.
+
+Ele pode subir mesmo sem MCP real, desde que a configuração esteja em mock ou que as tools não sejam obrigatórias para o teste.
+
+### 17.2. Rodar backend local
+
+Dentro de `agent_template_backend`:
+
+```bash
+source .venv/bin/activate
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+### 17.3. Validações imediatas
+
+Verifique saúde:
+
+```bash
+curl http://localhost:8000/health
+```
+
+Listar agentes:
+
+```bash
+curl http://localhost:8000/agents
+```
+
+Listar tools MCP conhecidas:
+
+```bash
+curl http://localhost:8000/debug/mcp/tools
+```
+
+### 17.4. Como interpretar o resultado
+
+```text
+/health ok         → API subiu.
+/agents lista      → agents.yaml foi carregado.
+/debug/mcp/tools   → tools.yaml e mcp_servers.yaml foram carregados.
+```
+
+Se `/health` funciona mas `/agents` não lista o agente, o problema provavelmente está em `config/agents.yaml`. Se `/debug/mcp/tools` não mostra a tool, o problema provavelmente está em `tools.yaml` ou `mcp_servers.yaml`.
+
+---
+
+## 18. Subindo MCP Servers
+
+### 18.1. Antes dos comandos: quando preciso subir MCP?
+
+Você precisa subir MCP quando a intent escolhida usa `mcp_tools` e o agente depende dessas tools para responder.
+
+Não precisa subir MCP para testar apenas:
+
+```text
+health check
+registro de agentes
+roteamento básico
+mock LLM sem tools
+fluxo conversacional simples sem consulta externa
+```
+
+### 18.2. Subir MCP Server local
+
+Se os MCP Servers forem processos Python separados, suba cada um em uma porta distinta.
+
+Exemplo:
+
+```bash
+cd ../mcp_servers/financeiro_mcp_server
+source .venv/bin/activate
+uvicorn main:app --host 0.0.0.0 --port 8300 --reload
+```
+
+Depois confirme que o endpoint configurado em `config/mcp_servers.yaml` está correto:
+
+```yaml
+servers:
+  financeiro:
+    endpoint: http://localhost:8300/mcp
+```
+
+### 18.3. Testar tool pelo backend
+
+Teste pelo backend, não diretamente pelo MCP. Assim você valida o caminho completo:
+
+```text
+backend → MCP Tool Router → MCP Server → resposta
+```
+
+```bash
+curl -X POST http://localhost:8000/debug/mcp/call/consultar_titulo_financeiro \
+  -H "Content-Type: application/json" \
+  -d '{
+    "business_context": {
+      "customer_key": "12345",
+      "contract_key": "ABC-999",
+      "session_key": "sessao-teste"
+    },
+    "original_context": {
+      "session_id": "sessao-teste"
+    }
+  }'
+```
+
+### 18.4. Como interpretar erros MCP
+
+```text
+Tool não encontrada         → tools.yaml ou nome da tool errado.
+Servidor não encontrado     → mcp_servers.yaml não tem o mcp_server indicado pela tool.
+Connection refused          → MCP Server não está rodando ou porta errada.
+Parâmetro obrigatório ausente → identity.yaml ou mcp_parameter_mapping.yaml incorreto.
+Timeout                     → MCP lento, endpoint errado, VPN, DNS ou sistema real indisponível.
+```
+
+---
+
+## 19. Build com Docker
+
+O Dockerfile do template espera copiar `agent_framework` e `agent_template_backend`. Portanto, rode o build a partir do diretório pai que contém ambos.
+
+Estrutura esperada:
+
+```text
+workspace/
+├── agent_framework/
+└── agent_template_backend/
+```
+
+Build:
+
+```bash
+cd workspace
+docker build -t agent-template-backend:local -f agent_template_backend/Dockerfile .
+```
+
+Run:
+
+```bash
+docker run --rm -p 8000:8000 \
+  --env-file agent_template_backend/.env \
+  agent-template-backend:local
+```
+
+Health check:
+
+```bash
+curl http://localhost:8000/health
+```
+
+---
+
+## 20. Docker Compose sugerido
+
+Crie um `docker-compose.yaml` no diretório pai, se quiser subir backend, Redis, Langfuse e MCP Servers juntos.
+
+Exemplo simplificado:
+
+```yaml
+services:
+  backend:
+    build:
+      context: .
+      dockerfile: agent_template_backend/Dockerfile
+    env_file:
+      - agent_template_backend/.env
+    ports:
+      - "8000:8000"
+    depends_on:
+      - redis
+      - financeiro-mcp
+
+  redis:
+    image: redis:7
+    ports:
+      - "6379:6379"
+
+  financeiro-mcp:
+    build:
+      context: ./mcp_servers/financeiro_mcp_server
+    ports:
+      - "8300:8300"
+```
+
+Quando estiver em Docker, use `config/mcp_servers.docker.yaml` e ajuste o `.env`:
+
+```env
+MCP_SERVERS_CONFIG_PATH=./config/mcp_servers.docker.yaml
+```
+
+---
+
+## 21. Testando o agente pelo Gateway
+
+### 21.1. Teste simples
+
+```bash
+curl -X POST http://localhost:8000/gateway/message \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "web",
+    "agent_id": "financeiro_agent",
+    "tenant_id": "default",
+    "payload": {
+      "text": "Quero consultar meu pagamento",
+      "session_id": "teste-financeiro-001",
+      "user_id": "user-001",
+      "customer_id": "12345",
+      "contract_id": "ABC-999",
+      "message_id": "msg-001"
+    }
+  }'
+```
+
+A resposta deve conter metadados como:
+
+```json
+{
+  "channel": "web",
+  "session_id": "default:financeiro_agent:teste-financeiro-001",
+  "text": "...",
+  "metadata": {
+    "route": "financeiro_agent",
+    "intent": "financeiro_pagamentos",
+    "mcp_results": [],
+    "business_context": {
+      "customer_key": "12345",
+      "contract_key": "ABC-999"
+    }
+  }
+}
+```
+
+### 21.2. Teste de roteamento sem fixar `agent_id`
+
+```bash
+curl -X POST http://localhost:8000/gateway/message \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "web",
+    "tenant_id": "default",
+    "payload": {
+      "text": "Meu pagamento ainda não foi baixado",
+      "session_id": "teste-router-001",
+      "user_id": "user-001",
+      "customer_id": "12345",
+      "contract_id": "ABC-999"
+    }
+  }'
+```
+
+### 21.3. Teste de SSE
+
+Enviar mensagem com SSE:
+
+```bash
+curl -X POST http://localhost:8000/gateway/message/sse \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "web",
+    "agent_id": "financeiro_agent",
+    "tenant_id": "default",
+    "payload": {
+      "text": "Preciso da segunda via do boleto",
+      "session_id": "teste-sse-001",
+      "user_id": "user-001",
+      "customer_id": "12345",
+      "contract_id": "ABC-999"
+    }
+  }'
+```
+
+Abrir stream:
+
+```bash
+curl -N http://localhost:8000/gateway/events/default:financeiro_agent:teste-sse-001
+```
+
+Eventos esperados:
+
+```text
+connected
+flow.start
+session.upserted
+message.received
+workflow.started
+workflow.completed
+message.responded
+flow.end
+```
+
+---
+
+## 22. Testando debug endpoints
+
+### 22.1. Roteamento
+
+```bash
+curl -X POST http://localhost:8000/debug/route \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Quero consultar meu pagamento",
+    "context": {
+      "agent_id": "financeiro_agent",
+      "tenant_id": "default"
+    }
+  }'
+```
+
+### 22.2. Identidade
+
+```bash
+curl -X POST http://localhost:8000/debug/identity \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_id": "teste-id-001",
+    "customer_id": "12345",
+    "contract_id": "ABC-999",
+    "message_id": "msg-001"
+  }'
+```
+
+### 22.3. Mensagens da sessão
+
+```bash
+curl http://localhost:8000/sessions/default:financeiro_agent:teste-financeiro-001/messages
+```
+
+### 22.4. Checkpoint
+
+```bash
+curl http://localhost:8000/sessions/default:financeiro_agent:teste-financeiro-001/checkpoint
+```
+
+### 22.5. Uso/custo
+
+```bash
+curl http://localhost:8000/debug/usage
+```
+
+---
+
+## 23. Checklist de validação funcional
+
+Use este checklist antes de considerar o agente pronto.
+
+### 23.1. Configuração
+
+- [ ] `.env` sem credenciais reais versionadas.
+- [ ] `LLM_PROVIDER` correto.
+- [ ] `ROUTING_MODE` definido: `router` ou `supervisor`.
+- [ ] `ENABLE_MCP_TOOLS` ajustado conforme necessidade.
+- [ ] `MCP_SERVERS_CONFIG_PATH` aponta para o YAML correto.
+- [ ] `IDENTITY_CONFIG_PATH` aponta para `config/identity.yaml`.
+- [ ] Persistência local ou Autonomous configurada.
+
+### 23.2. Agente
+
+- [ ] Arquivo criado em `app/agents/<agent>.py`.
+- [ ] Classe implementa `async def run(self, state)`.
+- [ ] Agente herda `AgentRuntimeMixin`.
+- [ ] Agente usa `get_runtime_context()` ou padrão equivalente para ler `state/context/session/business_context`.
+- [ ] Agente usa `normalize_tools_by_intent()` quando precisa de fallback de tools por intent.
+- [ ] Agente usa `build_tool_arguments()` ou `execute_tools_for_intent()` quando precisa de aliases/política de tools.
+- [ ] Tools de ação em `tools.yaml` possuem `tool_type`, `requires` e, quando necessário, `confirmation_required`.
+- [ ] Dev entende que `AgentRuntimeMixin` é infraestrutura compartilhada, não regra de negócio.
+- [ ] Agente usa `_emit_ic()`, `_emit_noc()` ou `_emit_grl()` em vez de emitir observabilidade em formato próprio.
+- [ ] Agente usa `_collect_mcp_context()` para consultas simples às tools declaradas em `routing.yaml`.
+- [ ] Agente usa `_retrieve_rag_context()` quando precisa de contexto documental.
+- [ ] Agente usa `_invoke_llm_cached()` para chamada LLM com cache e telemetria.
+- [ ] Dev entende que `messages` é o contrato conversacional enviado ao LLM, não a memória persistente.
+- [ ] `messages` separa regras permanentes no `system` e pedido/evidências no `user`.
+- [ ] `messages` inclui apenas campos necessários de `session`, `business_context`, MCP e RAG.
+- [ ] Agente não envia `state` completo, objetos enormes ou dados sensíveis desnecessários ao LLM.
+- [ ] Agente deixa claro no prompt quando MCP/RAG falharam, para evitar resposta inventada.
+- [ ] Agente não chama REST, banco, SOAP ou serviço externo diretamente quando isso deveria estar atrás de MCP.
+- [ ] Agente separa `context`, `session`, `business_context` e `tool_arguments` antes de tomar decisões.
+- [ ] Agente usa `business_context` para decisões de negócio e `session` para continuidade/rastreabilidade.
+- [ ] Prompts específicos aplicam `apply_agent_profile_prompt()`.
+- [ ] Tools são chamadas via `_collect_mcp_context()`.
+- [ ] RAG é chamado via `_retrieve_rag_context()`, se aplicável.
+- [ ] LLM é chamado via `_invoke_llm_cached()`.
+- [ ] Retorno contém `answer`, `next_state`, `mcp_results` e, se aplicável, `rag`.
+
+### 23.3. Workflow
+
+- [ ] Agente importado em `agent_graph.py`.
+- [ ] Agente instanciado no `__init__`.
+- [ ] Nó adicionado no `StateGraph`.
+- [ ] Rota adicionada em `add_conditional_edges`.
+- [ ] Edge criada para `output_supervisor`.
+- [ ] Handler adicionado no modo supervisor, se necessário.
+
+### 23.4. Roteamento
+
+- [ ] Intent adicionada em `config/routing.yaml`.
+- [ ] Keywords suficientes.
+- [ ] Examples coerentes.
+- [ ] `agent` da intent bate com o nome do nó do workflow.
+- [ ] `mcp_tools` da intent existem em `config/tools.yaml`.
+
+### 23.5. MCP
+
+- [ ] Tool declarada em `config/tools.yaml`.
+- [ ] MCP Server declarado em `config/mcp_servers.yaml`.
+- [ ] Mapeamento declarado em `config/mcp_parameter_mapping.yaml`.
+- [ ] Tool testada via `/debug/mcp/call/{tool_name}`.
+- [ ] Timeout e fallback definidos.
+
+### 23.6. Observabilidade
+
+- [ ] ICs de início e fim emitidos.
+- [ ] ICs de coleta MCP/RAG emitidos quando aplicável.
+- [ ] NOCs emitidos em erros técnicos relevantes.
+- [ ] GRLs globais aparecem em input/output.
+- [ ] Langfuse ou outro provider recebe traces, se habilitado.
+
+### 23.7. Testes
+
+- [ ] `/health` retorna `status=ok`.
+- [ ] `/agents` lista o agente novo.
+- [ ] `/debug/route` escolhe o agente correto.
+- [ ] `/debug/identity` resolve as chaves esperadas.
+- [ ] `/gateway/message` retorna resposta correta.
+- [ ] `/gateway/message/sse` publica eventos.
+- [ ] `/sessions/{session_id}/messages` mostra histórico.
+- [ ] `/sessions/{session_id}/checkpoint` mostra checkpoint.
+
+---
+
+## 24. Boas práticas de customização
+
+### Faça
+
+- Coloque regra de negócio no agente, não no framework.
+- Use MCP para acesso a sistemas externos.
+- Use `RuntimeContext`, `build_tool_arguments()` e `execute_tools_for_intent()` antes de criar helpers locais duplicados no agente.
+- Use `identity.yaml` para normalizar chaves de negócio.
+- Use `mcp_parameter_mapping.yaml` para adaptar nomes de parâmetros.
+- Use IC para eventos de negócio.
+- Use NOC para falhas técnicas.
+- Use GRL para decisões de segurança/validação.
+- Monte `messages` com separação clara entre instrução, pedido, evidência MCP, contexto RAG e formato de saída.
+- Mantenha prompts por agente em `config/agents/<agent_id>/prompt_policy.yaml`.
+- Mantenha guardrails e judges isolados quando o agente tiver regras próprias.
+
+### Evite
+
+- Criar outro workflow fora de `AgentWorkflow` sem necessidade.
+- Chamar REST/DB direto dentro do agente quando a chamada deveria ser tool MCP.
+- Criar checkpointer próprio.
+- Criar memória paralela fora do framework.
+- Emitir telemetria em formato incompatível com `AgentObserver`.
+- Colocar regra específica de um agente dentro do framework.
+- Misturar histórico de agentes diferentes na mesma sessão.
+- Enviar o `state` inteiro ou dumps grandes de tools/RAG diretamente dentro de `messages`.
+- Colocar regras críticas apenas no `user` prompt quando deveriam estar no `system`.
+
+---
+
+## 25. Troubleshooting
+
+### 25.1. `/gateway/message` retorna rota errada
+
+Verifique:
+
+```bash
+curl -X POST http://localhost:8000/debug/route \
+  -H "Content-Type: application/json" \
+  -d '{"text":"sua frase de teste","context":{"agent_id":"financeiro_agent"}}'
+```
+
+Depois revise:
+
+```text
+config/routing.yaml
+keywords
+examples
+priority
+ROUTING_MODE
+ENABLE_LLM_ROUTER
+```
+
+### 25.2. Tool MCP não é chamada
+
+Verifique:
+
+```text
+A intent em routing.yaml possui mcp_tools.
+A tool existe em tools.yaml.
+O MCP Server está em mcp_servers.yaml.
+ENABLE_MCP_TOOLS=true.
+O mapeamento existe em mcp_parameter_mapping.yaml.
+A identidade tem as chaves necessárias.
+```
+
+### 25.3. Tool recebe parâmetro errado
+
+Revise:
+
+```text
+config/identity.yaml
+config/mcp_parameter_mapping.yaml
+payload enviado ao /gateway/message
+```
+
+Use:
+
+```bash
+curl -X POST http://localhost:8000/debug/identity \
+  -H "Content-Type: application/json" \
+  -d '{"session_id":"s1","customer_id":"123","contract_id":"C1"}'
+```
+
+### 25.4. SSE dá MIME type incorreto
+
+O endpoint correto é:
+
+```text
+GET /gateway/events/{session_id}
+```
+
+O `session_id` precisa ser a chave canônica completa retornada pelo gateway:
+
+```text
+tenant_id:agent_id:session_id_original
+```
+
+Exemplo:
+
+```text
+default:financeiro_agent:teste-sse-001
+```
+
+### 25.5. Langfuse não mostra traces
+
+Verifique:
+
+```env
+ENABLE_LANGFUSE=true
+LANGFUSE_PUBLIC_KEY=<public-key>
+LANGFUSE_SECRET_KEY=<secret-key>
+LANGFUSE_HOST=http://localhost:3005
+```
+
+E confira:
+
+```bash
+curl http://localhost:8000/health
+curl http://localhost:8000/debug/env
+```
+
+### 25.6. Banco Autonomous não conecta
+
+Para desenvolvimento, simplifique primeiro:
+
+```env
+SESSION_REPOSITORY_PROVIDER=memory
+MEMORY_REPOSITORY_PROVIDER=memory
+CHECKPOINT_REPOSITORY_PROVIDER=memory
+USAGE_REPOSITORY_PROVIDER=memory
+```
+
+Depois volte para `autonomous` quando wallet, DSN e variáveis estiverem corretos.
+
+---
+
+
+### 25.7. LLM responde inventando ou ignorando evidências
+
+Quando o LLM inventa dados, confirma uma ação inexistente ou ignora uma tool, nem sempre o problema está no modelo. Muitas vezes o problema está em como `messages` foi montado.
+
+Verifique:
+
+```text
+O system prompt proíbe claramente inventar dados?
+O user prompt separa evidências MCP de instruções?
+A falha da tool foi informada explicitamente ao LLM?
+O agente enviou um dump confuso de mcp_results em vez de um resumo útil?
+O RAG trouxe documentos relevantes ou ruído?
+O prompt pediu formato de resposta claro?
+Há histórico duplicado confundindo a resposta?
+```
+
+Exemplo de correção:
+
+```text
+Ruim:
+  Responda sobre o pagamento do cliente usando os dados abaixo: [...]
+
+Melhor:
+  A tool consultar_pagamentos_financeiro retornou ok=false.
+  Não confirme pagamento.
+  Informe que a evidência de pagamento não foi encontrada.
+```
+
+Em ambiente de desenvolvimento, registre uma versão sanitizada de `messages` para revisar o que realmente chegou ao LLM. Nunca registre prompts brutos com CPF, token, credencial, dados sensíveis ou payloads grandes de sistemas externos.
+
+## 26. Modelo mínimo de entrega de um novo agente
+
+Ao finalizar uma implementação, a entrega mínima deve conter:
+
+```text
+app/agents/<agent_name>.py
+config/agents.yaml
+config/routing.yaml
+config/tools.yaml
+config/mcp_servers.yaml
+config/mcp_parameter_mapping.yaml
+config/identity.yaml
+config/agents/<agent_id>/prompt_policy.yaml
+config/agents/<agent_id>/guardrails.yaml
+config/agents/<agent_id>/judges.yaml
+app/workflows/agent_graph.py
+app/state.py, se necessário
+.env.example ou documentação de variáveis
+README.md com testes curl
+```
+
+---
+
+## 27. Exemplo de teste completo
+
+```bash
+# 1. Health
+curl http://localhost:8000/health
+
+# 2. Agentes
+curl http://localhost:8000/agents
+
+# 3. Tools MCP
+curl http://localhost:8000/debug/mcp/tools
+
+# 4. Roteamento
+curl -X POST http://localhost:8000/debug/route \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Quero consultar meu pagamento",
+    "context": {"agent_id": "financeiro_agent", "tenant_id": "default"}
+  }'
+
+# 5. Identidade
+curl -X POST http://localhost:8000/debug/identity \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_id": "teste-final-001",
+    "customer_id": "12345",
+    "contract_id": "ABC-999"
+  }'
+
+# 6. Mensagem real
+curl -X POST http://localhost:8000/gateway/message \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "web",
+    "agent_id": "financeiro_agent",
+    "tenant_id": "default",
+    "payload": {
+      "text": "Quero consultar meu pagamento",
+      "session_id": "teste-final-001",
+      "user_id": "user-001",
+      "customer_id": "12345",
+      "contract_id": "ABC-999",
+      "message_id": "msg-final-001"
+    }
+  }'
+
+# 7. Histórico
+curl http://localhost:8000/sessions/default:financeiro_agent:teste-final-001/messages
+
+# 8. Checkpoint
+curl http://localhost:8000/sessions/default:financeiro_agent:teste-final-001/checkpoint
+```
+
+---
+
+## 28. Agent Gateway / Global Supervisor
+
+Este capítulo é uma tratativa à parte. Em uma arquitetura com vários agentes, não basta saber construir um backend de agente isolado. Em algum momento o frontend recebe uma mensagem do usuário e precisa decidir **qual backend de agente deve tratar aquela conversa**.
+
+Essa decisão não deve ficar espalhada no frontend, nem duplicada dentro de cada agente. Para isso existe o **Agent Gateway**, também chamado aqui de **Global Supervisor**.
+
+### 28.1. Antes do código: qual problema o Agent Gateway resolve?
+
+Imagine que a empresa tenha três backends independentes:
+
+```text
+Backend Contas
+  resolve fatura, pagamento, consumo, segunda via, contestação
+
+Backend Ofertas
+  resolve planos, contratação, upgrade, retenção, desconto
+
+Backend Suporte
+  resolve internet lenta, sinal, rede, modem, falha técnica
+```
+
+Sem um gateway global, o frontend teria que saber regras como:
+
+```text
+Se a mensagem tem "fatura", chamar Contas.
+Se a mensagem tem "plano", chamar Ofertas.
+Se a mensagem tem "internet lenta", chamar Suporte.
+```
+
+Isso parece simples no começo, mas vira problema quando:
+
+- surgem muitos agentes;
+- uma conversa começa em Contas e depois muda para Ofertas;
+- uma mensagem é ambígua, como “quero cancelar”;
+- cada canal, Web, WhatsApp e Voz, começa a implementar sua própria regra;
+- o desenvolvedor precisa manter roteamento, sessão e handoff em vários lugares.
+
+O **Agent Gateway** centraliza essa decisão.
+
+Ele recebe a mensagem normalizada do canal, descobre o backend correto e encaminha a requisição para o backend escolhido.
+
+```text
+Usuário
+  ↓
+Frontend / Canal
+  ↓
+Agent Gateway / Global Supervisor
+  ↓
+Backend Contas | Backend Ofertas | Backend Suporte | Outros backends
+```
+
+O Gateway **não substitui o agente**. Ele não deve conter regra de negócio de fatura, oferta ou suporte. Ele apenas decide **quem deve receber a mensagem**.
+
+### 28.2. Diferença entre Supervisor do agente e Global Supervisor
+
+Dentro de um backend de agente, você pode ter um supervisor local. Esse supervisor decide entre caminhos internos do próprio agente.
+
+Exemplo dentro do agente de Contas:
+
+```text
+Mensagem: "Minha fatura veio alta"
+
+Supervisor local do Backend Contas decide:
+  - explicar fatura
+  - consultar pagamentos
+  - abrir contestação
+  - chamar humano
+```
+
+O **Global Supervisor** decide em um nível acima:
+
+```text
+Mensagem: "Minha internet está lenta"
+
+Global Supervisor decide:
+  - isso não é Contas
+  - isso deve ir para Suporte
+```
+
+A separação correta é:
+
+```text
+Global Supervisor / Agent Gateway
+  decide o backend
+
+Supervisor local do backend
+  decide o fluxo interno do agente
+
+Agente especializado
+  executa a lógica de negócio
+```
+
+Essa separação evita que o framework ou o gateway fiquem contaminados com detalhes específicos de um domínio.
+
+### 28.3. O que pertence ao Agent Gateway
+
+O Gateway deve cuidar de responsabilidades transversais entre backends:
+
+```text
+agent_gateway/
+  app/main.py
+    expõe /gateway/message, /gateway/events/{session_id}, /debug/route,
+    /backends, /backends/health e /health
+
+  app/settings.py
+    lê variáveis de ambiente do gateway global
+
+  config/backends.yaml
+    declara quais backends existem, suas URLs, domínios, keywords e prioridade
+
+  .env.example
+    documenta o modo de roteamento, TTL de sessão, timeout e provider LLM
+```
+
+O Gateway pode usar motores do framework para:
+
+- roteamento global;
+- sessão global;
+- client HTTP para backends;
+- supervisor LLM;
+- observabilidade;
+- publicação de eventos;
+- proxy SSE.
+
+No arquivo `agent_gateway/app/main.py`, o gateway usa componentes do framework como:
+
+```python
+from agent_framework.global_supervisor import (
+    BackendClient,
+    BackendRegistry,
+    GlobalRouteRequest,
+    GlobalSupervisorRouter,
+    InMemoryGlobalSessionStore,
+)
+```
+
+Isso significa que o gateway não está criando um mecanismo paralelo de roteamento. Ele está usando uma camada própria do framework para governar múltiplos backends.
+
+### 28.4. O que não pertence ao Agent Gateway
+
+O Gateway não deve implementar regras específicas como:
+
+```text
+consultar_fatura
+consultar_pagamentos
+abrir_contestacao
+consultar_imdb
+buscar_speech_analytics
+abrir_sr_siebel
+calcular_pro_rata
+resolver_ean
+```
+
+Essas funcionalidades pertencem aos backends especializados ou aos MCP servers.
+
+Uma regra prática:
+
+```text
+Se a lógica depende do negócio de um agente específico, ela não deve ficar no Gateway.
+Se a lógica decide qual backend deve tratar a conversa, ela pode ficar no Gateway.
+```
+
+### 28.5. Estrutura do projeto `agent_gateway`
+
+A estrutura mínima observada no projeto é:
+
+```text
+agent_gateway/
+  app/
+    main.py
+    settings.py
+  config/
+    backends.yaml
+  docs/
+    ARQUITETURA_GLOBAL_SUPERVISOR.md
+  .env.example
+  Dockerfile
+  README.md
+  requirements.txt
+```
+
+Cada arquivo tem uma responsabilidade clara:
+
+| Arquivo | Responsabilidade |
+|---|---|
+| `app/main.py` | expõe endpoints HTTP, chama o router global, encaminha mensagens aos backends e faz proxy SSE |
+| `app/settings.py` | centraliza variáveis do gateway global |
+| `config/backends.yaml` | cadastra backends disponíveis e regras de roteamento por domínio/keyword |
+| `.env.example` | documenta como ligar/desligar modos de roteamento e providers |
+| `Dockerfile` | empacota o gateway como serviço separado |
+| `docs/ARQUITETURA_GLOBAL_SUPERVISOR.md` | explica a arquitetura conceitual |
+
+### 28.6. Como o desenvolvedor deve pensar antes de configurar o Gateway
+
+Antes de editar `config/backends.yaml`, o desenvolvedor deve responder quatro perguntas:
+
+```text
+1. Quais backends de agente existem?
+2. Qual é o domínio de responsabilidade de cada backend?
+3. Quais palavras ou exemplos indicam cada domínio?
+4. O que deve acontecer quando a mensagem for ambígua?
+```
+
+Exemplo:
+
+```text
+Mensagem: "Quero cancelar"
+```
+
+Essa mensagem pode significar:
+
+```text
+Cancelar serviço avulso    → talvez Contas ou Ofertas
+Cancelar plano inteiro     → talvez Ofertas ou Retenção
+Cancelar por problema rede → talvez Suporte
+```
+
+Nesse caso, o router por keyword pode não ser suficiente. O modo `hybrid` pode manter o backend ativo se a conversa já tiver contexto, ou chamar o supervisor LLM se houver conflito.
+
+### 28.7. Configurando os backends em `config/backends.yaml`
+
+O arquivo principal de configuração do Gateway é:
+
+```text
+agent_gateway/config/backends.yaml
+```
+
+Exemplo:
+
+```yaml
+default_backend: contas
+
+backends:
+  contas:
+    url: http://localhost:8001
+    description: Backend responsável por faturas, contas, pagamentos, consumo, segunda via e contestação.
+    domains: [contas, fatura, pagamento, consumo, contestacao]
+    keywords: [fatura, conta, boleto, pagamento, consumo, segunda via, contestar, contestação, valor, cobrança]
+    examples:
+      - Quero consultar minha fatura
+      - Minha conta veio alta
+      - Preciso da segunda via do boleto
+    priority: 10
+    default_agent_id: telecom_contas
+
+  ofertas:
+    url: http://localhost:8002
+    description: Backend responsável por ofertas, planos, upgrades, retenção e contratação.
+    domains: [ofertas, planos, retenção, contratação]
+    keywords: [oferta, plano, contratar, upgrade, desconto, promoção, pacote, retenção, cancelar serviço]
+    examples:
+      - Quero trocar meu plano
+      - Tem alguma oferta para mim?
+      - Quero cancelar um serviço
+    priority: 20
+    default_agent_id: telecom_ofertas
+
+  suporte:
+    url: http://localhost:8003
+    description: Backend responsável por suporte técnico, falhas, rede, internet e atendimento operacional.
+    domains: [suporte, técnico, rede, internet]
+    keywords: [internet, sinal, rede, suporte, técnico, problema, falha, sem conexão, modem]
+    examples:
+      - Minha internet está lenta
+      - Estou sem sinal
+      - Preciso de suporte técnico
+    priority: 30
+    default_agent_id: telecom_suporte
+```
+
+O desenvolvedor não deve preencher esse YAML como uma lista aleatória de palavras. Ele deve pensar em **famílias de intenção**.
+
+Exemplo correto:
+
+```text
+Família: contas
+  assuntos: fatura, pagamento, consumo, segunda via, contestação
+```
+
+Exemplo ruim:
+
+```text
+Família: qualquer coisa que tenha "valor"
+```
+
+A palavra “valor” pode aparecer em fatura, oferta, desconto, contestação ou cobrança. Palavras genéricas devem ser usadas com cuidado.
+
+### 28.8. Escolhendo o modo de roteamento global
+
+O `.env` do gateway possui a variável:
+
+```env
+GLOBAL_ROUTING_MODE=hybrid
+```
+
+Os modos possíveis são:
+
+| Modo | Como decide | Quando usar |
+|---|---|---|
+| `router` | usa regras, keywords, domínios e prioridade | desenvolvimento local, testes determinísticos, ambientes com baixa ambiguidade |
+| `supervisor` | usa LLM para escolher backend | domínios muito parecidos ou mensagens muito abertas |
+| `hybrid` | mantém backend ativo, usa regra e chama LLM em conflito | recomendado para produção inicial |
+
+A decisão prática é:
+
+```text
+Se você quer previsibilidade total, use router.
+Se você quer interpretação semântica forte, use supervisor.
+Se você quer equilíbrio entre contexto, regra e LLM, use hybrid.
+```
+
+Para a maioria dos projetos corporativos, comece com:
+
+```env
+GLOBAL_ROUTING_MODE=hybrid
+GLOBAL_KEEP_ACTIVE_BACKEND=true
+GLOBAL_USE_SUPERVISOR_ON_CONFLICT=true
+GLOBAL_MIN_ROUTER_CONFIDENCE=0.55
+```
+
+### 28.9. Entendendo sessão global e sessão do backend
+
+O Gateway mantém uma sessão global, por exemplo:
+
+```text
+global_session_id = s1
+```
+
+O backend pode manter outra sessão interna, por exemplo:
+
+```text
+backend_session_id = default:telecom_contas:s1
+```
+
+O código do Gateway ajusta a resposta para manter os dois identificadores no `metadata`:
+
+```json
+{
+  "session_id": "s1",
+  "metadata": {
+    "global_session_id": "s1",
+    "backend_session_id": "default:telecom_contas:s1",
+    "selected_backend": "contas"
+  }
+}
+```
+
+Essa separação é importante porque o usuário conversa com uma sessão global, mas cada backend pode precisar de sua própria chave interna para memória, checkpoint e histórico.
+
+### 28.9.1. Como o Gateway deve entregar sessão ao backend
+
+Para que o agente consiga entender de onde veio a conversa, o Gateway deve encaminhar a sessão dentro de `context.session` ou em uma estrutura equivalente normalizada pelo framework.
+
+Exemplo de payload conceitual que chega ao backend:
+
+```json
+{
+  "channel": "web",
+  "tenant_id": "default",
+  "agent_id": "financeiro_agent",
+  "payload": {
+    "text": "Quero consultar meu pagamento",
+    "session_id": "s1",
+    "customer_id": "12345"
+  },
+  "context": {
+    "session": {
+      "global_session_id": "s1",
+      "backend_session_id": "default:financeiro_agent:s1",
+      "active_backend": "financeiro",
+      "channel": "web",
+      "tenant_id": "default",
+      "metadata": {
+        "selected_backend": "financeiro",
+        "route_confidence": 0.82
+      }
+    },
+    "business_context": {
+      "customer_key": "12345",
+      "session_key": "default:financeiro_agent:s1"
+    }
+  }
+}
+```
+
+O desenvolvedor do agente deve entender que `context.session` não é “mais um lugar para buscar qualquer parâmetro”. Ele é o contrato de continuidade da conversa. Para chamadas MCP, prefira sempre `business_context` e `tool_arguments`.
+
+### 28.10. Subindo o Agent Gateway localmente
+
+Entre no diretório do gateway:
+
+```bash
+cd agent_gateway
+```
+
+Copie o arquivo de ambiente:
+
+```bash
+cp .env.example .env
+```
+
+Configure o `PYTHONPATH` para enxergar o framework:
+
+```bash
+export PYTHONPATH=../agent_framework/src:.
+```
+
+Suba o serviço:
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8010 --reload
+```
+
+Valide o health:
+
+```bash
+curl http://localhost:8010/health
+```
+
+Resposta esperada:
+
+```json
+{
+  "status": "ok",
+  "app": "agent-gateway-global-supervisor",
+  "routing_mode": "hybrid",
+  "backends": ["contas", "ofertas", "suporte"],
+  "llm_provider": "mock"
+}
+```
+
+Se esse endpoint não responder, o problema ainda está no gateway, não nos backends.
+
+### 28.11. Subindo os backends de agente
+
+O Gateway só roteia corretamente se os backends configurados em `backends.yaml` estiverem de pé.
+
+Exemplo local:
+
+```text
+Gateway        http://localhost:8010
+Contas         http://localhost:8001
+Ofertas        http://localhost:8002
+Suporte        http://localhost:8003
+Frontend       http://localhost:5173
+```
+
+Cada backend precisa expor, no mínimo:
+
+```text
+GET  /health
+POST /gateway/message
+GET  /gateway/events/{session_id}
+```
+
+O endpoint `/backends/health` do Gateway verifica a saúde dos backends:
+
+```bash
+curl http://localhost:8010/backends/health
+```
+
+Use esse teste antes de culpar o roteamento. Se o backend está fora do ar, o Gateway pode até escolher corretamente, mas falhará no encaminhamento.
+
+### 28.12. Testando apenas a decisão de rota
+
+Antes de enviar uma mensagem real para o backend, teste a decisão:
+
+```bash
+curl -X POST http://localhost:8010/debug/route \
+  -H 'content-type: application/json' \
+  -d '{
+    "channel": "web",
+    "payload": {
+      "text": "Minha fatura veio alta",
+      "session_id": "s1"
+    }
+  }'
+```
+
+Resultado esperado:
+
+```json
+{
+  "backend_id": "contas",
+  "confidence": 0.8,
+  "reason": "Backend escolhido por regras: matches=['fatura']"
+}
+```
+
+O desenvolvedor deve interpretar o resultado assim:
+
+```text
+backend_id   → para qual backend o gateway mandaria a mensagem
+confidence   → quão forte foi a decisão
+reason       → por que a decisão foi tomada
+```
+
+Se o backend escolhido estiver errado, ajuste `domains`, `keywords`, `examples`, `priority` ou o modo de roteamento.
+
+### 28.13. Enviando mensagem real pelo Gateway
+
+Depois que a decisão de rota estiver correta, envie a mensagem real:
+
+```bash
+curl -X POST http://localhost:8010/gateway/message \
+  -H 'content-type: application/json' \
+  -d '{
+    "channel": "web",
+    "payload": {
+      "text": "Minha fatura veio alta",
+      "session_id": "s1",
+      "msisdn": "11999999999"
+    }
+  }'
+```
+
+O Gateway fará:
+
+```text
+1. Receber a mensagem.
+2. Emitir IC.GLOBAL_GATEWAY_RECEIVED.
+3. Criar uma GlobalRouteRequest.
+4. Chamar GlobalSupervisorRouter.
+5. Escolher o backend.
+6. Emitir IC.GLOBAL_BACKEND_SELECTED.
+7. Encaminhar para o /gateway/message do backend.
+8. Guardar o active_backend da sessão.
+9. Acrescentar metadados de rota na resposta.
+10. Emitir IC.GLOBAL_GATEWAY_COMPLETED.
+```
+
+### 28.14. Handoff entre backends
+
+O handoff acontece quando um backend percebe que a conversa deve mudar de domínio.
+
+Exemplo:
+
+```text
+Usuário começou em Contas:
+  "Minha fatura veio alta"
+
+Depois perguntou:
+  "Tem algum plano melhor para reduzir esse valor?"
+```
+
+O backend de Contas pode responder com metadata pedindo troca:
+
+```json
+{
+  "metadata": {
+    "handover_backend": "ofertas"
+  }
+}
+```
+
+O Gateway detecta esse campo e chama automaticamente o novo backend.
+
+O desenvolvedor precisa entender que handoff não é erro. É uma transição controlada entre domínios.
+
+### 28.15. Proxy SSE pelo Gateway
+
+O Gateway também possui endpoint:
+
+```text
+GET /gateway/events/{session_id}
+```
+
+Esse endpoint faz proxy do SSE do backend ativo.
+
+Fluxo:
+
+```text
+Frontend abre EventSource no Gateway
+  ↓
+Gateway espera existir sessão global
+  ↓
+Gateway descobre active_backend
+  ↓
+Gateway monta URL SSE do backend
+  ↓
+Gateway repassa os eventos text/event-stream para o frontend
+```
+
+Teste:
+
+```bash
+curl -N http://localhost:8010/gateway/events/s1
+```
+
+Eventos esperados no início:
+
+```text
+event: connected
+data: {"session_id":"s1","component":"agent_gateway"}
+
+```
+
+Depois que uma mensagem for enviada para `/gateway/message`, o Gateway deve emitir algo como:
+
+```text
+event: backend.selected
+data: {"session_id":"s1","backend_id":"contas","backend_session_id":"s1"}
+```
+
+Se aparecer erro de MIME type, o backend ativo provavelmente não está retornando `text/event-stream` em `/gateway/events/{session_id}`.
+
+### 28.16. IC e NOC do Agent Gateway
+
+O Gateway deve emitir eventos próprios, diferentes dos eventos internos dos agentes.
+
+Eventos encontrados no projeto:
+
+| Evento | Significado |
+|---|---|
+| `IC.GLOBAL_GATEWAY_RECEIVED` | Gateway recebeu mensagem do canal |
+| `IC.GLOBAL_BACKEND_SELECTED` | Gateway escolheu um backend |
+| `IC.GLOBAL_BACKEND_HANDOVER` | Houve troca de backend durante a conversa |
+| `IC.GLOBAL_GATEWAY_COMPLETED` | Gateway concluiu o encaminhamento |
+| `NOC.005` | falha operacional no Gateway ou na chamada ao backend |
+| `NOC.006` | conclusão HTTP observada pelo middleware |
+
+Esses eventos não substituem os IC/NOC/GRL do backend. Eles complementam a visão ponta a ponta.
+
+Em uma rastreabilidade completa, você deve conseguir enxergar:
+
+```text
+IC.GLOBAL_GATEWAY_RECEIVED
+IC.GLOBAL_BACKEND_SELECTED
+IC.BACKEND_WORKFLOW_STARTED
+IC.TOOL_CALLED
+GRL.INPUT_STARTED
+GRL.OUTPUT_COMPLETED
+IC.BACKEND_WORKFLOW_COMPLETED
+IC.GLOBAL_GATEWAY_COMPLETED
+```
+
+### 28.17. Como integrar o frontend ao Agent Gateway
+
+O frontend não deve chamar diretamente cada backend de agente.
+
+Em vez disso, ele deve apontar para:
+
+```text
+POST http://localhost:8010/gateway/message
+GET  http://localhost:8010/gateway/events/{session_id}
+```
+
+O frontend continua enviando uma mensagem normalizada:
+
+```json
+{
+  "channel": "web",
+  "payload": {
+    "text": "Minha fatura veio alta",
+    "session_id": "s1"
+  }
+}
+```
+
+O frontend não precisa saber se a mensagem foi para Contas, Ofertas ou Suporte. Essa informação pode aparecer em `metadata.selected_backend`, mas não deve virar regra de negócio no frontend.
+
+### 28.18. Build do Gateway com Docker
+
+O Dockerfile do Gateway usa:
+
+```dockerfile
+FROM python:3.12-slim
+WORKDIR /app
+COPY agent_framework /agent_framework
+COPY agent_gateway /app
+RUN pip install --no-cache-dir -e /agent_framework -r requirements.txt
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8010"]
+```
+
+Isso pressupõe que, no contexto de build, existam os diretórios:
+
+```text
+agent_framework/
+agent_gateway/
+```
+
+Build:
+
+```bash
+docker build -t agent-gateway:local -f agent_gateway/Dockerfile .
+```
+
+Run:
+
+```bash
+docker run --rm -p 8010:8010 \
+  --env-file agent_gateway/.env \
+  agent-gateway:local
+```
+
+### 28.19. Checklist de implementação do Agent Gateway
+
+Antes de considerar o Gateway pronto, valide:
+
+```text
+[ ] /health responde.
+[ ] /backends lista todos os backends esperados.
+[ ] /backends/health consegue chamar cada backend.
+[ ] /debug/route escolhe o backend correto para mensagens óbvias.
+[ ] /debug/route explica o motivo da decisão.
+[ ] /gateway/message encaminha para o backend escolhido.
+[ ] response.metadata.selected_backend aparece na resposta.
+[ ] response.metadata.global_route_decision aparece na resposta.
+[ ] /debug/sessions mostra active_backend após primeira mensagem.
+[ ] /gateway/events/{session_id} retorna text/event-stream.
+[ ] handoff_backend funciona quando um backend solicita troca.
+[ ] IC.GLOBAL_* aparece na observabilidade.
+[ ] NOC.005 aparece em falhas reais de backend.
+```
+
+### 28.20. Erros comuns no Agent Gateway
+
+#### Erro 1: Gateway escolhe backend errado
+
+Causas comuns:
+
+```text
+keywords genéricas demais
+priority mal definida
+examples insuficientes
+GLOBAL_MIN_ROUTER_CONFIDENCE muito baixo
+modo router usado para domínio ambíguo
+```
+
+Correção:
+
+```text
+1. Teste /debug/route.
+2. Leia o campo reason.
+3. Ajuste domains, keywords e examples.
+4. Se continuar ambíguo, use hybrid ou supervisor.
+```
+
+#### Erro 2: Gateway escolhe certo, mas retorna 502
+
+Isso normalmente significa que o backend escolhido está fora do ar ou não expõe `/gateway/message`.
+
+Teste:
+
+```bash
+curl http://localhost:8001/health
+curl -X POST http://localhost:8001/gateway/message \
+  -H 'content-type: application/json' \
+  -d '{"channel":"web","payload":{"text":"teste","session_id":"s1"}}'
+```
+
+#### Erro 3: SSE retorna `application/json` em vez de `text/event-stream`
+
+O backend ativo precisa expor SSE corretamente.
+
+Teste direto no backend:
+
+```bash
+curl -i -N http://localhost:8001/gateway/events/s1
+```
+
+O header esperado é:
+
+```text
+content-type: text/event-stream
+```
+
+#### Erro 4: Sessão global existe, mas o backend ativo não aparece
+
+Verifique:
+
+```bash
+curl http://localhost:8010/debug/sessions
+```
+
+Depois envie uma mensagem por `/gateway/message`. O `active_backend` só é definido depois que o Gateway roteia uma mensagem com sucesso.
+
+### 28.21. Como explicar essa arquitetura para um novo desenvolvedor
+
+Uma forma simples de ensinar é:
+
+```text
+O backend de agente sabe resolver um tipo de problema.
+O Gateway sabe escolher qual backend deve resolver o problema.
+O framework fornece os motores reutilizáveis para ambos.
+```
+
+Portanto, ao implementar um novo agente, o desenvolvedor deve fazer duas integrações:
+
+```text
+1. Criar o backend especializado usando agent_template_backend.
+2. Registrar esse backend no agent_gateway/config/backends.yaml.
+```
+
+Ele não deve alterar o frontend para cada novo agente. Também não deve colocar regra de negócio do novo agente dentro do Gateway.
+
+
+---
+
+## 29. Conclusão
+
+O `agent_template_backend` fornece a espinha dorsal corporativa para novos agentes. A implementação de um agente novo deve se limitar ao domínio: prompts, regras, tools, clients, schemas e decisões específicas.
+
+O padrão correto é:
+
+```text
+Framework = motor reutilizável
+Agente = customização de negócio
+MCP = fronteira padronizada com sistemas externos
+Config YAML = comportamento alterável sem mexer no motor
+IC/NOC/GRL = rastreabilidade corporativa
+```
+
+Um desenvolvedor não deve apenas copiar arquivos. Ele deve entender que cada alteração representa uma decisão arquitetural:
+
+```text
+Criar agente       → define a lógica de domínio.
+Registrar workflow → torna o agente executável pelo LangGraph.
+Ajustar state      → compartilha dados entre nós.
+Configurar agents  → declara o agente para o framework.
+Configurar routing → ensina o framework quando chamar o agente.
+Configurar tools   → declara capacidades externas.
+Configurar MCP     → conecta tools a sistemas ou mocks.
+Configurar identity→ normaliza chaves de negócio.
+Emitir IC/NOC/GRL  → torna a execução auditável.
+Testar gateway     → valida o fluxo real fim a fim.
+```
+
+Seguindo esse modelo, novos agentes podem ser criados com padronização, escalabilidade, rastreabilidade e manutenção mais simples.
+
+
+## 30. Entrega final com Agent Gateway
+
+Ao final da implementação, a entrega recomendada deve conter quatro projetos ou diretórios claramente separados:
+
+```text
+agent_framework/
+  biblioteca reutilizável com motores de workflow, routing, guardrails,
+  judges, supervisor, memória, checkpoint, observabilidade e MCP tool router
+
+agent_template_backend/
+  backend especializado de um agente, com domínio, prompts, tools,
+  state, workflow e configurações próprias
+
+agent_gateway/
+  global supervisor que roteia conversas entre vários backends de agentes
+
+agent_frontend/
+  interface Web, WhatsApp ou Voz que conversa com o Agent Gateway
+```
+
+A relação correta é:
+
+```text
+Frontend
+  chama Agent Gateway
+
+Agent Gateway
+  escolhe o backend
+
+Backend do agente
+  executa o workflow especializado
+
+MCP Server
+  executa ou simula ferramentas de negócio
+
+Framework
+  fornece os motores reutilizáveis para gateway e backends
+```
+
+### 30.1. Sequência final de subida local
+
+Uma sequência local completa pode ser:
+
+```bash
+# 1. Subir MCP do agente, se existir
+cd mcp_servers/meu_agente_mcp
+uvicorn app.main:app --host 0.0.0.0 --port 9001 --reload
+
+# 2. Subir backend do agente Contas
+cd agent_template_backend
+cp .env.example .env
+uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
+
+# 3. Subir Agent Gateway
+cd agent_gateway
+cp .env.example .env
+export PYTHONPATH=../agent_framework/src:.
+uvicorn app.main:app --host 0.0.0.0 --port 8010 --reload
+
+# 4. Subir frontend
+cd agent_frontend
+npm install
+npm run dev
+```
+
+### 30.2. Sequência final de testes
+
+```bash
+# Gateway vivo
+curl http://localhost:8010/health
+
+# Backends registrados
+curl http://localhost:8010/backends
+
+# Saúde dos backends
+curl http://localhost:8010/backends/health
+
+# Decisão de rota
+curl -X POST http://localhost:8010/debug/route \
+  -H 'content-type: application/json' \
+  -d '{"channel":"web","payload":{"text":"Minha fatura veio alta","session_id":"s1"}}'
+
+# Mensagem real ponta a ponta
+curl -X POST http://localhost:8010/gateway/message \
+  -H 'content-type: application/json' \
+  -d '{"channel":"web","payload":{"text":"Minha fatura veio alta","session_id":"s1","msisdn":"11999999999"}}'
+
+# Sessões globais
+curl http://localhost:8010/debug/sessions
+
+# SSE pelo Gateway
+curl -N http://localhost:8010/gateway/events/s1
+```
+
+### 30.3. Critério de aceite arquitetural
+
+A implementação está arquiteturalmente correta quando:
+
+```text
+[ ] o frontend não conhece URLs individuais dos backends de agentes;
+[ ] o Gateway não contém regra de negócio específica de fatura, oferta ou suporte;
+[ ] cada backend continua independente;
+[ ] cada backend usa os motores do framework;
+[ ] o Gateway usa o GlobalSupervisorRouter do framework;
+[ ] o roteamento global é observável;
+[ ] cada troca de backend gera metadados e evento de handoff;
+[ ] os MCP servers continuam plugáveis por backend/agente;
+[ ] a sessão global e a sessão do backend são preservadas no metadata;
+[ ] o desenvolvedor consegue testar rota antes de testar execução real.
+```
+
+Com esse desenho, adicionar um novo agente não exige reescrever o frontend nem copiar lógica entre backends. O desenvolvedor cria o backend especializado, registra no Agent Gateway e deixa o framework cuidar dos motores transversais.
+
+## Política read-only/transacional
+
+Este template inclui o arquivo opcional `config/tool_policies.yaml`. Use `operation_type: read_only` para consultas e `operation_type: transactional` com `require_confirmation: true` para ações que só podem executar após confirmação booleana explícita. Se o arquivo for removido ou não existir em um template antigo, os campos legados de `config/tools.yaml` continuam válidos.
+
+## Workflows transacionais determinísticos
+
+Além da execução direta de MCP tools, uma operação transacional pode usar um workflow LangGraph determinístico após `clarification` e confirmação explícita. Configure `execution.mode: workflow` em `config/tool_policies.yaml`, mantenha as definições versionadas em `workflows/` e implemente as actions do domínio no projeto do agente. O runtime genérico está em `agent_framework.workflows`.
+
+Consulte `libs/agent_framework/docs/TRANSACTIONAL_WORKFLOWS_PT.md` e o exemplo `workflows/devolucao_pedido.v1.yaml`.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/README_ENTERPRISE_TEMPLATE.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/README_ENTERPRISE_TEMPLATE.md
new file mode 100644
index 0000000..cae516e
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/README_ENTERPRISE_TEMPLATE.md
@@ -0,0 +1,54 @@
+# Agent Template Backend Enterprise
+
+Este folder é uma cópia completa do `agent_template_backend`, sem cortes de
+arquitetura. Ele mantém workflow, router, output supervisor, guardrails,
+analytics, observer, MCP, memória, checkpoints e configurações.
+
+A diferença é que a lógica de negócio dos agentes de exemplo foi removida da
+execução e preservada comentada nos próprios arquivos:
+
+- `app/agents/billing_agent.py`
+- `app/agents/product_agent.py`
+- `app/agents/orders_agent.py`
+- `app/agents/support_agent.py`
+
+## O que o desenvolvedor deve alterar
+
+1. Escolher ou criar um agente em `app/agents/`.
+2. Implementar o método `run()`.
+3. Ajustar prompts e tools, se necessário.
+4. Emitir ICs de negócio relevantes para a jornada.
+5. Manter NOC/GRL nos pontos operacionais e de guardrails.
+
+## O que já está integrado
+
+- `AgentObserver`
+- `observer.emit_ic()`
+- `observer.emit_noc()`
+- `observer.emit_grl()`
+- `AnalyticsPublisher`
+- OCI Streaming
+- GCP Pub/Sub
+- OutputSupervisor
+- GuardrailPipeline com suporte a execução paralela/fail-fast no framework
+- MCP Tool Router
+- LangGraph
+- Memory
+- Checkpoint
+- Langfuse / OpenTelemetry
+
+## Exemplos adicionados
+
+Veja `app/examples/`:
+
+- `ic_examples.py`
+- `noc_examples.py`
+- `grl_examples.py`
+- `mcp_examples.py`
+- `observer_examples.py`
+
+## Convenção rápida
+
+- IC = evento de negócio / curadoria / informacional.
+- NOC = evento operacional / saúde técnica.
+- GRL = evento de guardrail / segurança / validação.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__init__.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/__init__.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/__init__.cpython-313.pyc
new file mode 100644
index 0000000..f80d227
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/__init__.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/main.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/main.cpython-313.pyc
new file mode 100644
index 0000000..ad5975b
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/main.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/mcp_gateway_client_factory.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/mcp_gateway_client_factory.cpython-313.pyc
new file mode 100644
index 0000000..7cbdba3
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/mcp_gateway_client_factory.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/state.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/state.cpython-313.pyc
new file mode 100644
index 0000000..851ddfa
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/__pycache__/state.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/README.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/README.md
new file mode 100644
index 0000000..2917425
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/README.md
@@ -0,0 +1,15 @@
+# Agentes do Template Backend Enterprise
+
+Os arquivos desta pasta preservam a estrutura real esperada pelo workflow, mas
+não executam lógica de negócio pronta.
+
+Cada agente mostra:
+
+- como emitir IC;
+- como emitir NOC;
+- como emitir GRL;
+- como coletar MCP via `_collect_tool_context()`;
+- como recuperar RAG via `_retrieve_rag_context()`;
+- onde chamar LLM/cache.
+
+A implementação original do exemplo está comentada no fim de cada arquivo.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/billing_agent.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/billing_agent.cpython-313.pyc
new file mode 100644
index 0000000..78a71e5
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/billing_agent.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/orders_agent.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/orders_agent.cpython-313.pyc
new file mode 100644
index 0000000..1e1d603
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/orders_agent.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/product_agent.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/product_agent.cpython-313.pyc
new file mode 100644
index 0000000..9173e5a
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/product_agent.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/prompting.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/prompting.cpython-313.pyc
new file mode 100644
index 0000000..3c4c277
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/prompting.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/runtime.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/runtime.cpython-313.pyc
new file mode 100644
index 0000000..c79c9ec
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/runtime.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/support_agent.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/support_agent.cpython-313.pyc
new file mode 100644
index 0000000..05f7a75
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/__pycache__/support_agent.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/billing_agent.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/billing_agent.py
new file mode 100644
index 0000000..aa60099
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/billing_agent.py
@@ -0,0 +1,129 @@
+from app.agents.prompting import apply_agent_profile_prompt
+from app.agents.runtime import AgentRuntimeMixin
+
+
+class BillingAgent(AgentRuntimeMixin):
+    name = "billingAgent"
+
+    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.BILLING_AGENT_STARTED",
+            state,
+            {"business_component": "faturas"},
+            component="agent.billing.start",
+        )
+
+        tool_context = await self._collect_tool_context(state)
+        if tool_context:
+            await self._emit_ic(
+                "IC.BILLING_MCP_CONTEXT_COLLECTED",
+                state,
+                {"tool_result_count": len(tool_context)},
+                component="agent.billing.mcp",
+            )
+
+        state["mcp_results"] = tool_context
+        clarification_message = self.transaction_clarification_message(state)
+        if clarification_message:
+            return {
+                "answer": f"[{self.__class__.__name__}] {clarification_message}",
+                "next_state": state.get("next_state") or "COLLECTING_PARAMETERS",
+                "mcp_results": tool_context,
+                **self.transaction_state_patch(state),
+            }
+
+        confirmation_message = self.transaction_confirmation_message(state)
+        if confirmation_message:
+            result = {
+                "answer": f"[{self.__class__.__name__}] {confirmation_message}",
+                "next_state": state.get("next_state"),
+                "mcp_results": tool_context,
+                **self.transaction_state_patch(state),
+            }
+            return result
+
+        direct_answer = self.build_direct_mcp_answer(state, tool_context, agent_label="BillingAgent")
+        if direct_answer:
+            return {
+                "answer": direct_answer,
+                "next_state": state.get("next_state") or "ACTIVE",
+                "mcp_results": tool_context,
+                "rag": {"enabled": False, "skipped": True, "reason": "direct_mcp_answer"},
+                **self.transaction_state_patch(state),
+            }
+
+        rag_context, rag_metadata = await self._retrieve_rag_context(state)
+        if rag_metadata.get("enabled"):
+            await self._emit_ic(
+                "IC.BILLING_RAG_CONTEXT_RETRIEVED",
+                state,
+                {
+                    "document_count": rag_metadata.get("document_count"),
+                    "graph_neighbors": rag_metadata.get("graph_neighbors"),
+                    "latency_ms": rag_metadata.get("latency_ms"),
+                },
+                component="agent.billing.rag",
+            )
+
+        # Prepara ConversationSummaryMemory antes de montar o prompt.
+        # O build_messages() do framework injeta resumo + últimas mensagens quando habilitado.
+        await self.prepare_memory_context(state)
+
+        messages = self.build_messages(
+            state,
+            system_prompt=apply_agent_profile_prompt(
+                state,
+                "Você é um agente especialista em faturas. Responda com clareza, objetividade e sem sugerir ações não solicitadas. Use dados MCP quando disponíveis.",
+            ),
+            mcp_results=tool_context,
+            rag_context=rag_context,
+            rag_metadata=rag_metadata,
+        )
+
+        answer = await self._invoke_llm_cached(state, "BillingAgent", messages)
+        result = {
+            "answer": f"[BillingAgent] {answer}",
+            "next_state": "BILLING_ACTIVE",
+            "mcp_results": tool_context,
+            "rag": rag_metadata,
+            "memory_context_metadata": state.get("memory_context_metadata"),
+            **self.transaction_state_patch(state),
+        }
+
+        await self._emit_ic(
+            "IC.BILLING_AGENT_COMPLETED",
+            state,
+            {
+                "answer_chars": len(result.get("answer") or ""),
+                "has_mcp_results": bool(tool_context),
+                "rag_enabled": bool(rag_metadata.get("enabled")),
+                "memory_context": state.get("memory_context_metadata"),
+            },
+            component="agent.billing.completed",
+        )
+        return result
+
+    async def _collect_tool_context(self, state):
+        return await self._collect_mcp_context(state)
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/orders_agent.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/orders_agent.py
new file mode 100644
index 0000000..f557bed
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/orders_agent.py
@@ -0,0 +1,129 @@
+from app.agents.prompting import apply_agent_profile_prompt
+from app.agents.runtime import AgentRuntimeMixin
+
+
+class OrdersAgent(AgentRuntimeMixin):
+    name = "orders_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.ORDERS_AGENT_STARTED",
+            state,
+            {"business_component": "pedidos"},
+            component="agent.orders.start",
+        )
+
+        tool_context = await self._collect_tool_context(state)
+        if tool_context:
+            await self._emit_ic(
+                "IC.ORDERS_MCP_CONTEXT_COLLECTED",
+                state,
+                {"tool_result_count": len(tool_context)},
+                component="agent.orders.mcp",
+            )
+
+        state["mcp_results"] = tool_context
+        clarification_message = self.transaction_clarification_message(state)
+        if clarification_message:
+            return {
+                "answer": f"[{self.__class__.__name__}] {clarification_message}",
+                "next_state": state.get("next_state") or "COLLECTING_PARAMETERS",
+                "mcp_results": tool_context,
+                **self.transaction_state_patch(state),
+            }
+
+        confirmation_message = self.transaction_confirmation_message(state)
+        if confirmation_message:
+            result = {
+                "answer": f"[{self.__class__.__name__}] {confirmation_message}",
+                "next_state": state.get("next_state"),
+                "mcp_results": tool_context,
+                **self.transaction_state_patch(state),
+            }
+            return result
+
+        direct_answer = self.build_direct_mcp_answer(state, tool_context, agent_label="OrdersAgent")
+        if direct_answer:
+            return {
+                "answer": direct_answer,
+                "next_state": state.get("next_state") or "ACTIVE",
+                "mcp_results": tool_context,
+                "rag": {"enabled": False, "skipped": True, "reason": "direct_mcp_answer"},
+                **self.transaction_state_patch(state),
+            }
+
+        rag_context, rag_metadata = await self._retrieve_rag_context(state)
+        if rag_metadata.get("enabled"):
+            await self._emit_ic(
+                "IC.ORDERS_RAG_CONTEXT_RETRIEVED",
+                state,
+                {
+                    "document_count": rag_metadata.get("document_count"),
+                    "graph_neighbors": rag_metadata.get("graph_neighbors"),
+                    "latency_ms": rag_metadata.get("latency_ms"),
+                },
+                component="agent.orders.rag",
+            )
+
+        # Prepara ConversationSummaryMemory antes de montar o prompt.
+        # O build_messages() do framework injeta resumo + últimas mensagens quando habilitado.
+        await self.prepare_memory_context(state)
+
+        messages = self.build_messages(
+            state,
+            system_prompt=apply_agent_profile_prompt(
+                state,
+                "Você é um agente de pedidos de varejo. Use dados de tools quando disponíveis.",
+            ),
+            mcp_results=tool_context,
+            rag_context=rag_context,
+            rag_metadata=rag_metadata,
+        )
+
+        answer = await self._invoke_llm_cached(state, "OrdersAgent", messages)
+        result = {
+            "answer": f"[OrdersAgent] {answer}",
+            "next_state": "ORDER_ACTIVE",
+            "mcp_results": tool_context,
+            "rag": rag_metadata,
+            "memory_context_metadata": state.get("memory_context_metadata"),
+            **self.transaction_state_patch(state),
+        }
+
+        await self._emit_ic(
+            "IC.ORDERS_AGENT_COMPLETED",
+            state,
+            {
+                "answer_chars": len(result.get("answer") or ""),
+                "has_mcp_results": bool(tool_context),
+                "rag_enabled": bool(rag_metadata.get("enabled")),
+                "memory_context": state.get("memory_context_metadata"),
+            },
+            component="agent.orders.completed",
+        )
+        return result
+
+    async def _collect_tool_context(self, state):
+        return await self._collect_mcp_context(state)
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/product_agent.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/product_agent.py
new file mode 100644
index 0000000..34433f5
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/product_agent.py
@@ -0,0 +1,129 @@
+from app.agents.prompting import apply_agent_profile_prompt
+from app.agents.runtime import AgentRuntimeMixin
+
+
+class ProductAgent(AgentRuntimeMixin):
+    name = "productAgent"
+
+    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.PRODUCT_AGENT_STARTED",
+            state,
+            {"business_component": "produtos"},
+            component="agent.product.start",
+        )
+
+        tool_context = await self._collect_tool_context(state)
+        if tool_context:
+            await self._emit_ic(
+                "IC.PRODUCT_MCP_CONTEXT_COLLECTED",
+                state,
+                {"tool_result_count": len(tool_context)},
+                component="agent.product.mcp",
+            )
+
+        state["mcp_results"] = tool_context
+        clarification_message = self.transaction_clarification_message(state)
+        if clarification_message:
+            return {
+                "answer": f"[{self.__class__.__name__}] {clarification_message}",
+                "next_state": state.get("next_state") or "COLLECTING_PARAMETERS",
+                "mcp_results": tool_context,
+                **self.transaction_state_patch(state),
+            }
+
+        confirmation_message = self.transaction_confirmation_message(state)
+        if confirmation_message:
+            result = {
+                "answer": f"[{self.__class__.__name__}] {confirmation_message}",
+                "next_state": state.get("next_state"),
+                "mcp_results": tool_context,
+                **self.transaction_state_patch(state),
+            }
+            return result
+
+        direct_answer = self.build_direct_mcp_answer(state, tool_context, agent_label="ProductAgent")
+        if direct_answer:
+            return {
+                "answer": direct_answer,
+                "next_state": state.get("next_state") or "ACTIVE",
+                "mcp_results": tool_context,
+                "rag": {"enabled": False, "skipped": True, "reason": "direct_mcp_answer"},
+                **self.transaction_state_patch(state),
+            }
+
+        rag_context, rag_metadata = await self._retrieve_rag_context(state)
+        if rag_metadata.get("enabled"):
+            await self._emit_ic(
+                "IC.PRODUCT_RAG_CONTEXT_RETRIEVED",
+                state,
+                {
+                    "document_count": rag_metadata.get("document_count"),
+                    "graph_neighbors": rag_metadata.get("graph_neighbors"),
+                    "latency_ms": rag_metadata.get("latency_ms"),
+                },
+                component="agent.product.rag",
+            )
+
+        # Prepara ConversationSummaryMemory antes de montar o prompt.
+        # O build_messages() do framework injeta resumo + últimas mensagens quando habilitado.
+        await self.prepare_memory_context(state)
+
+        messages = self.build_messages(
+            state,
+            system_prompt=apply_agent_profile_prompt(
+                state,
+                "Você é um agente especialista em produtos, planos e serviços. Explique sem fazer oferta proativa e sem executar ações sem confirmação. Use dados MCP quando disponíveis.",
+            ),
+            mcp_results=tool_context,
+            rag_context=rag_context,
+            rag_metadata=rag_metadata,
+        )
+
+        answer = await self._invoke_llm_cached(state, "ProductAgent", messages)
+        result = {
+            "answer": f"[ProductAgent] {answer}",
+            "next_state": "PRODUCT_ACTIVE",
+            "mcp_results": tool_context,
+            "rag": rag_metadata,
+            "memory_context_metadata": state.get("memory_context_metadata"),
+            **self.transaction_state_patch(state),
+        }
+
+        await self._emit_ic(
+            "IC.PRODUCT_AGENT_COMPLETED",
+            state,
+            {
+                "answer_chars": len(result.get("answer") or ""),
+                "has_mcp_results": bool(tool_context),
+                "rag_enabled": bool(rag_metadata.get("enabled")),
+                "memory_context": state.get("memory_context_metadata"),
+            },
+            component="agent.product.completed",
+        )
+        return result
+
+    async def _collect_tool_context(self, state):
+        return await self._collect_mcp_context(state)
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/prompting.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/prompting.py
new file mode 100644
index 0000000..255422b
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/prompting.py
@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+
+def apply_agent_profile_prompt(state: dict, default_prompt: str) -> str:
+    """Adiciona o prefixo de prompt configurado para o agent_template selecionado.
+
+    Cada agent_id pode definir metadata.system_prefix em config/agents.yaml. Isso
+    mantém prompts isolados sem duplicar o código dos agentes especializados.
+    """
+    profile = state.get("agent_profile") or (state.get("context") or {}).get("agent_profile") or {}
+    metadata = profile.get("metadata") or {}
+    prefix = (metadata.get("system_prefix") or "").strip()
+    if not prefix:
+        return default_prompt
+    return f"{prefix}\n\n{default_prompt}"
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/runtime.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/runtime.py
new file mode 100644
index 0000000..e6429c4
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/runtime.py
@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+# Compatibilidade local do template/backend.
+# A implementação oficial agora fica no framework para evitar duplicação entre agentes.
+from agent_framework.runtime import AgentRuntimeMixin, MessageBuilder, RuntimeContext
+
+__all__ = ["AgentRuntimeMixin", "MessageBuilder", "RuntimeContext"]
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/support_agent.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/support_agent.py
new file mode 100644
index 0000000..b4f0244
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/agents/support_agent.py
@@ -0,0 +1,129 @@
+from app.agents.prompting import apply_agent_profile_prompt
+from app.agents.runtime import AgentRuntimeMixin
+
+
+class SupportAgent(AgentRuntimeMixin):
+    name = "support_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.SUPPORT_AGENT_STARTED",
+            state,
+            {"business_component": "suporte"},
+            component="agent.support.start",
+        )
+
+        tool_context = await self._collect_tool_context(state)
+        if tool_context:
+            await self._emit_ic(
+                "IC.SUPPORT_MCP_CONTEXT_COLLECTED",
+                state,
+                {"tool_result_count": len(tool_context)},
+                component="agent.support.mcp",
+            )
+
+        state["mcp_results"] = tool_context
+        clarification_message = self.transaction_clarification_message(state)
+        if clarification_message:
+            return {
+                "answer": f"[{self.__class__.__name__}] {clarification_message}",
+                "next_state": state.get("next_state") or "COLLECTING_PARAMETERS",
+                "mcp_results": tool_context,
+                **self.transaction_state_patch(state),
+            }
+
+        confirmation_message = self.transaction_confirmation_message(state)
+        if confirmation_message:
+            result = {
+                "answer": f"[{self.__class__.__name__}] {confirmation_message}",
+                "next_state": state.get("next_state"),
+                "mcp_results": tool_context,
+                **self.transaction_state_patch(state),
+            }
+            return result
+
+        direct_answer = self.build_direct_mcp_answer(state, tool_context, agent_label="SupportAgent")
+        if direct_answer:
+            return {
+                "answer": direct_answer,
+                "next_state": state.get("next_state") or "ACTIVE",
+                "mcp_results": tool_context,
+                "rag": {"enabled": False, "skipped": True, "reason": "direct_mcp_answer"},
+                **self.transaction_state_patch(state),
+            }
+
+        rag_context, rag_metadata = await self._retrieve_rag_context(state)
+        if rag_metadata.get("enabled"):
+            await self._emit_ic(
+                "IC.SUPPORT_RAG_CONTEXT_RETRIEVED",
+                state,
+                {
+                    "document_count": rag_metadata.get("document_count"),
+                    "graph_neighbors": rag_metadata.get("graph_neighbors"),
+                    "latency_ms": rag_metadata.get("latency_ms"),
+                },
+                component="agent.support.rag",
+            )
+
+        # Prepara ConversationSummaryMemory antes de montar o prompt.
+        # O build_messages() do framework injeta resumo + últimas mensagens quando habilitado.
+        await self.prepare_memory_context(state)
+
+        messages = self.build_messages(
+            state,
+            system_prompt=apply_agent_profile_prompt(
+                state,
+                "Você é um agente de suporte de varejo para troca, devolução e garantia.",
+            ),
+            mcp_results=tool_context,
+            rag_context=rag_context,
+            rag_metadata=rag_metadata,
+        )
+
+        answer = await self._invoke_llm_cached(state, "SupportAgent", messages)
+        result = {
+            "answer": f"[SupportAgent] {answer}",
+            "next_state": "SUPPORT_ACTIVE",
+            "mcp_results": tool_context,
+            "rag": rag_metadata,
+            "memory_context_metadata": state.get("memory_context_metadata"),
+            **self.transaction_state_patch(state),
+        }
+
+        await self._emit_ic(
+            "IC.SUPPORT_AGENT_COMPLETED",
+            state,
+            {
+                "answer_chars": len(result.get("answer") or ""),
+                "has_mcp_results": bool(tool_context),
+                "rag_enabled": bool(rag_metadata.get("enabled")),
+                "memory_context": state.get("memory_context_metadata"),
+            },
+            component="agent.support.completed",
+        )
+        return result
+
+    async def _collect_tool_context(self, state):
+        return await self._collect_mcp_context(state)
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__init__.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__init__.py
new file mode 100644
index 0000000..3f95e96
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__init__.py
@@ -0,0 +1 @@
+"""Exemplos de uso do template backend enterprise."""
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/__init__.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/__init__.cpython-313.pyc
new file mode 100644
index 0000000..59de564
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/__init__.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/grl_examples.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/grl_examples.cpython-313.pyc
new file mode 100644
index 0000000..1bbb960
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/grl_examples.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/ic_examples.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/ic_examples.cpython-313.pyc
new file mode 100644
index 0000000..72b0aca
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/ic_examples.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/mcp_examples.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/mcp_examples.cpython-313.pyc
new file mode 100644
index 0000000..a763cc5
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/mcp_examples.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/noc_examples.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/noc_examples.cpython-313.pyc
new file mode 100644
index 0000000..e39ccb5
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/noc_examples.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/observer_examples.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/observer_examples.cpython-313.pyc
new file mode 100644
index 0000000..4bdbd36
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/__pycache__/observer_examples.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/grl_examples.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/grl_examples.py
new file mode 100644
index 0000000..8dadac8
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/grl_examples.py
@@ -0,0 +1,37 @@
+"""Exemplos de GRL.
+
+GRL representa eventos de guardrails. Em regra, GRL.001..GRL.009 são emitidos
+pelo pipeline de guardrails e pelo OutputSupervisor do framework. Use emissão
+manual apenas para validações customizadas do agente.
+"""
+
+from typing import Any
+
+
+async def exemplo_guardrail_observado(observer: Any, state: dict[str, Any], rail_code: str, reason: str) -> None:
+    await observer.emit_grl(
+        "OBSERVE",
+        {
+            "session_id": state.get("conversation_key") or state.get("session_id"),
+            "tenant_id": state.get("tenant_id"),
+            "agent_id": state.get("agent_id"),
+            "rail_code": rail_code,
+            "reason": reason,
+        },
+        component="examples.grl",
+    )
+
+
+async def exemplo_guardrail_block(observer: Any, state: dict[str, Any], rail_code: str, reason: str) -> None:
+    await observer.emit_grl(
+        "004",
+        {
+            "session_id": state.get("conversation_key") or state.get("session_id"),
+            "tenant_id": state.get("tenant_id"),
+            "agent_id": state.get("agent_id"),
+            "rail_code": rail_code,
+            "reason": reason,
+            "action": "block",
+        },
+        component="examples.grl",
+    )
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/ic_examples.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/ic_examples.py
new file mode 100644
index 0000000..f6daa57
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/ic_examples.py
@@ -0,0 +1,34 @@
+"""Exemplos de IC - Item de Controle.
+
+ICs representam eventos de negócio. Eles alimentam Informacional, Curadoria,
+analytics, BigQuery ou qualquer publisher configurado no framework.
+"""
+
+from typing import Any
+
+
+async def exemplo_fatura_consultada(observer: Any, state: dict[str, Any], invoice_id: str) -> None:
+    await observer.emit_ic(
+        "IC.FATURA_CONSULTADA",
+        {
+            "session_id": state.get("conversation_key") or state.get("session_id"),
+            "tenant_id": state.get("tenant_id"),
+            "agent_id": state.get("agent_id"),
+            "invoice_id": invoice_id,
+        },
+        component="examples.ic",
+    )
+
+
+async def exemplo_acao_concluida(observer: Any, state: dict[str, Any], action_name: str, ok: bool) -> None:
+    await observer.emit_ic(
+        "IC.ACAO_CONCLUIDA",
+        {
+            "session_id": state.get("conversation_key") or state.get("session_id"),
+            "tenant_id": state.get("tenant_id"),
+            "agent_id": state.get("agent_id"),
+            "action_name": action_name,
+            "ok": ok,
+        },
+        component="examples.ic",
+    )
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/mcp_examples.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/mcp_examples.py
new file mode 100644
index 0000000..613f10c
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/mcp_examples.py
@@ -0,0 +1,43 @@
+"""Exemplos de MCP + IC.
+
+O AgentRuntimeMixin já possui _collect_mcp_context(), mas este arquivo mostra o
+padrão para chamadas explícitas ao tool_router quando necessário.
+"""
+
+from typing import Any
+
+
+async def exemplo_chamada_mcp(tool_router: Any, observer: Any, state: dict[str, Any], tool_name: str, payload: dict[str, Any]) -> Any:
+    session_id = state.get("conversation_key") or state.get("session_id")
+
+    await observer.emit_ic(
+        "IC.MCP_TOOL_CALLED",
+        {
+            "session_id": session_id,
+            "tenant_id": state.get("tenant_id"),
+            "agent_id": state.get("agent_id"),
+            "tool_name": tool_name,
+        },
+        component="examples.mcp",
+    )
+
+    result = await tool_router.call(
+        tool_name,
+        payload,
+        business_context=(state.get("context") or {}).get("business_context") or {},
+        original_context=state.get("context") or {},
+    )
+
+    await observer.emit_ic(
+        "IC.TOOL_CALLED",
+        {
+            "session_id": session_id,
+            "tenant_id": state.get("tenant_id"),
+            "agent_id": state.get("agent_id"),
+            "tool_name": tool_name,
+            "ok": getattr(result, "ok", None),
+        },
+        component="examples.mcp",
+    )
+
+    return result
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/noc_examples.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/noc_examples.py
new file mode 100644
index 0000000..2b38a15
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/noc_examples.py
@@ -0,0 +1,37 @@
+"""Exemplos de NOC.
+
+NOC representa telemetria operacional. O workflow do template já emite NOC.001,
+NOC.005 e NOC.006. Estes exemplos mostram eventos adicionais que a squad pode
+emitir em pontos críticos.
+"""
+
+from typing import Any
+
+
+async def exemplo_api_invalida(observer: Any, state: dict[str, Any], api_url: str, status_code: int, latency_ms: int) -> None:
+    await observer.emit_noc(
+        "002",
+        {
+            "session_id": state.get("conversation_key") or state.get("session_id"),
+            "tenant_id": state.get("tenant_id"),
+            "agent_id": state.get("agent_id"),
+            "apiUrl": api_url,
+            "statusCode": status_code,
+            "latencyMs": latency_ms,
+        },
+        component="examples.noc",
+    )
+
+
+async def exemplo_latencia_banco(observer: Any, state: dict[str, Any], resource_name: str, latency_ms: int) -> None:
+    await observer.emit_noc(
+        "003",
+        {
+            "session_id": state.get("conversation_key") or state.get("session_id"),
+            "tenant_id": state.get("tenant_id"),
+            "agent_id": state.get("agent_id"),
+            "resourceName": resource_name,
+            "latencyMs": latency_ms,
+        },
+        component="examples.noc",
+    )
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/observer_examples.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/observer_examples.py
new file mode 100644
index 0000000..926b553
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/examples/observer_examples.py
@@ -0,0 +1,28 @@
+"""Resumo prático do Observer corporativo.
+
+Use este arquivo como cola rápida para IC, NOC e GRL.
+"""
+
+from typing import Any
+
+
+async def emitir_eventos_basicos(observer: Any, state: dict[str, Any]) -> None:
+    session_id = state.get("conversation_key") or state.get("session_id")
+
+    await observer.emit_ic(
+        "IC.EXEMPLO_NEGOCIO",
+        {"session_id": session_id, "agent_id": state.get("agent_id")},
+        component="examples.observer",
+    )
+
+    await observer.emit_noc(
+        "EXEMPLO_OPERACIONAL",
+        {"session_id": session_id, "agent_id": state.get("agent_id")},
+        component="examples.observer",
+    )
+
+    await observer.emit_grl(
+        "OBSERVE",
+        {"session_id": session_id, "agent_id": state.get("agent_id"), "rail_code": "CUSTOM"},
+        component="examples.observer",
+    )
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/main.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/main.py
new file mode 100644
index 0000000..c1d3354
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/main.py
@@ -0,0 +1,558 @@
+from __future__ import annotations
+
+import logging
+import os
+from uuid import uuid4
+import time
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+from agent_framework.channels.base import ChannelResponse
+from agent_framework.channels.gateway import ChannelGateway
+from agent_framework.config.agent_registry import AgentProfileRegistry
+from agent_framework.config.settings import settings
+from agent_framework.analytics.factory import create_analytics_publisher
+from agent_framework.observer import configure as configure_global_observer
+from agent_framework.llm.providers import create_llm
+from agent_framework.memory.message_history import create_memory
+from agent_framework.memory.summary_memory import create_conversation_summary_memory
+from agent_framework.mcp.tool_router import create_mcp_tool_router
+from agent_framework.models.identity import AgentIdentity
+from agent_framework.identity import IdentityResolver, BusinessContext
+from agent_framework.models.session import ChatMessage, SessionContext
+from agent_framework.observability.telemetry import Telemetry
+from agent_framework.observability.context import set_observability_context, clear_observability_context
+from agent_framework.repositories.session_repository import create_session_repository
+from agent_framework.checkpoints.checkpoint_repository import create_checkpoint_repository
+from agent_framework.cache.cache import create_cache
+from agent_framework.billing.usage_repository import create_usage_repository
+from agent_framework.sse.events import SSEHub
+from agent_framework.security import install_authentication
+from app.workflows.agent_graph import AgentWorkflow
+from app.observability.telemetry_observer import TelemetryBackedAgentObserver
+
+logging.basicConfig(level=settings.LOG_LEVEL)
+logger = logging.getLogger("agent_template_backend")
+
+app = FastAPI(title="Agent Template Backend FIRST-ready")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[o.strip() for o in settings.CORS_ORIGINS.split(",")],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Authentication is project-configured. The framework only provides generic providers.
+auth_enabled = install_authentication(app, prefix="AGENT_AUTH")
+
+telemetry = Telemetry(settings)
+usage_repository = create_usage_repository(settings)
+llm = create_llm(settings, telemetry=telemetry, usage_repository=usage_repository)
+memory = create_memory(settings)
+summary_memory = create_conversation_summary_memory(settings, message_history=memory, llm=llm, telemetry=telemetry)
+sessions = create_session_repository(settings)
+checkpoints = create_checkpoint_repository(settings)
+cache = create_cache(settings, telemetry=telemetry)
+gateway = ChannelGateway(input_mode=settings.FRAMEWORK_CHANNEL_INPUT_MODE)
+analytics = create_analytics_publisher(settings)
+observer = TelemetryBackedAgentObserver(telemetry=telemetry)
+configure_global_observer({
+    "enabled": getattr(settings, "ENABLE_ANALYTICS", False),
+    "providers": getattr(settings, "ANALYTICS_PROVIDERS", "oci_streaming"),
+    "topic_path": getattr(settings, "GCP_PUBSUB_TOPIC_PATH", None) or getattr(settings, "AGENT_PUBSUB_TOPIC", None),
+})
+tool_router = create_mcp_tool_router(settings, telemetry=telemetry)
+identity_resolver = IdentityResolver.from_yaml(settings.IDENTITY_CONFIG_PATH)
+agent_profiles = AgentProfileRegistry(settings)
+sse_hub = SSEHub(settings, telemetry=telemetry)
+workflow = AgentWorkflow(llm, memory, telemetry, analytics, settings, observer=observer, tool_router=tool_router, summary_memory=summary_memory)
+
+logger.info("LLM provider carregado: %s", llm.__class__.__name__)
+logger.info("Langfuse habilitado: %s host=%s", telemetry.is_enabled(), settings.LANGFUSE_HOST)
+logger.info("Analytics habilitado: %s providers=%s", getattr(settings, "ENABLE_ANALYTICS", False), getattr(settings, "ANALYTICS_PROVIDERS", ""))
+logger.info("Agentes disponíveis: %s", [p.agent_id for p in agent_profiles.list_profiles()])
+logger.info("Framework channel input mode: %s", gateway.input_mode)
+logger.info("Authentication enabled=%s mode=%s policies=%s", auth_enabled, os.getenv("AGENT_AUTH_MODE", "none"), os.getenv("AGENT_AUTH_POLICIES_FILE"))
+
+@app.middleware("http")
+async def observability_context_middleware(request: Request, call_next):
+    clear_observability_context()
+    request_id = request.headers.get("x-request-id") or str(uuid4())
+    set_observability_context(
+        request_id=request_id,
+        channel=request.headers.get("x-channel") or "http",
+        ura_call_id=request.headers.get("x-ura-call-id"),
+    )
+    started = time.time()
+    try:
+        response = await call_next(request)
+        response.headers["x-request-id"] = request_id
+        await telemetry.event("http.request.completed", {
+            "method": request.method,
+            "path": request.url.path,
+            "status_code": response.status_code,
+            "duration_ms": int((time.time() - started) * 1000),
+        }, kind="http")
+        return response
+    except Exception as exc:
+        await telemetry.event("http.request.failed", {
+            "method": request.method,
+            "path": request.url.path,
+            "error": str(exc),
+            "duration_ms": int((time.time() - started) * 1000),
+        }, kind="http")
+        raise
+    finally:
+        clear_observability_context()
+
+
+class GatewayRequest(BaseModel):
+    channel: str = "web"
+    payload: dict
+    agent_id: str | None = None
+    tenant_id: str | None = None
+
+
+def _metadata_value(payload: dict, key: str):
+    metadata = payload.get("metadata")
+    if isinstance(metadata, dict):
+        return metadata.get(key)
+    return None
+
+
+def _extract_workflow_id(payload: dict) -> str | None:
+    return (
+        payload.get("workflow_id")
+        or payload.get("workflowId")
+        or _metadata_value(payload, "workflow_id")
+        or _metadata_value(payload, "workflowId")
+    )
+
+
+def _format_root_span_name(template: str | None, values: dict) -> str:
+    template = template or "agent.gateway_message"
+    try:
+        return template.format(**{k: v or "unknown" for k, v in values.items()})
+    except Exception:
+        logger.warning("LANGFUSE_ROOT_SPAN_NAME inválido: %s", template)
+        return "agent.gateway_message"
+
+
+def _resolve_identity(req: GatewayRequest, msg) -> tuple[AgentIdentity, dict, BusinessContext, list[str]]:
+    payload = req.payload or {}
+    context = dict(msg.context or {})
+    tenant_id = req.tenant_id or payload.get("tenant_id") or context.get("tenant_id") or "default"
+    agent_id = req.agent_id or payload.get("agent_id") or context.get("agent_id") or agent_profiles.default_agent_id
+    profile = agent_profiles.get(agent_id)
+
+    # 1) Identidade técnica do framework: isola tenant/agente/sessão.
+    context.update({"tenant_id": tenant_id, "agent_id": profile.agent_id, "agent_profile": profile.__dict__})
+    identity = AgentIdentity.from_context(context, session_id=msg.session_id)
+
+    # 2) Identidade de negócio: chaves canônicas vindas do front/canal.
+    #    Estas chaves são estáveis na sessão e seguem até agentes e MCP Router.
+    previous_business_context = context.get("business_context") or context.get("identity") or {}
+    business_context = identity_resolver.resolve(
+        {**payload, **context},
+        session_id=identity.conversation_key(),
+        previous=previous_business_context,
+    )
+    missing_identity_keys = identity_resolver.validate(business_context)
+    context.update({
+        "business_context": business_context.model_dump(),
+        "business_keys": business_context.to_context_dict(),
+        "identity_missing": missing_identity_keys,
+        "conversation_key": identity.conversation_key(),
+        "original_session_id": msg.session_id,
+    })
+    return identity, context, business_context, missing_identity_keys
+
+
+async def _process_gateway_message(req: GatewayRequest, emit_sse: bool = False) -> dict:
+    try:
+        msg = await gateway.normalize(req.channel, req.payload)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    payload = req.payload or {}
+    identity, normalized_context, business_context, missing_identity_keys = _resolve_identity(req, msg)
+    agent_session_id = identity.conversation_key()
+    message_id = payload.get("message_id") or str(uuid4())
+    workflow_id = _extract_workflow_id(payload)
+    set_observability_context(
+        session_id=agent_session_id,
+        user_id=msg.user_id,
+        tenant_id=identity.tenant_id,
+        agent_id=identity.agent_id,
+        channel=msg.channel,
+        message_id=message_id,
+        workflow_id=workflow_id,
+        ura_call_id=payload.get("ura_call_id") or normalized_context.get("ura_call_id") or business_context.interaction_key,
+    )
+
+    stream = sse_hub.stream_for(agent_session_id)
+    async with stream.lock:
+        await sse_hub.emit(agent_session_id, "flow.start", {"session_id": agent_session_id, "message_id": message_id, "agent_id": identity.agent_id}) if emit_sse else None
+
+        session = await sessions.get(agent_session_id)
+        if not session:
+            context_fields = {
+                k: v
+                for k, v in normalized_context.items()
+                if k in SessionContext.model_fields
+                and k not in {"tenant_id", "agent_id", "session_id", "user_id", "channel", "channel_id"}
+            }
+            session = SessionContext(
+                tenant_id=identity.tenant_id,
+                agent_id=identity.agent_id,
+                session_id=agent_session_id,
+                user_id=msg.user_id,
+                channel=msg.channel,
+                channel_id=msg.channel_id,
+                **context_fields,
+            )
+
+        session.tenant_id = identity.tenant_id
+        session.agent_id = identity.agent_id
+        session.channel = msg.channel
+        session.channel_id = msg.channel_id or session.channel_id
+        await sessions.upsert(session)
+        session.metadata = {
+            **(session.metadata or {}),
+            "business_context": business_context.model_dump(),
+            "identity_missing": missing_identity_keys,
+            "original_context": normalized_context,
+        }
+        await sse_hub.emit(agent_session_id, "session.upserted", {"session_id": agent_session_id, "business_context": business_context.model_dump()}) if emit_sse else None
+
+        await memory.append(
+            agent_session_id,
+            ChatMessage(
+                role="user",
+                content=msg.text,
+                metadata={
+                    **normalized_context,
+                    "agent_id": identity.agent_id,
+                    "tenant_id": identity.tenant_id,
+                    "message_id": message_id,
+                    "business_context": business_context.model_dump(),
+                    "identity_missing": missing_identity_keys,
+                },
+            ),
+        )
+        await sse_hub.emit(agent_session_id, "message.received", {"session_id": agent_session_id, "role": "user"}) if emit_sse else None
+        history = [m.model_dump(mode="json") for m in await memory.list(agent_session_id)]
+
+        cms_input = {
+            "channel": req.channel,
+            "tenant_id": req.tenant_id,
+            "agent_id": req.agent_id,
+            "payload": payload,
+        }
+        trace_context = {
+            "text": msg.text,
+            "channel": msg.channel,
+            "channel_id": msg.channel_id,
+            "tenant_id": identity.tenant_id,
+            "agent_id": identity.agent_id,
+            "conversation_key": agent_session_id,
+            "workflow_id": workflow_id,
+            "message_id": message_id,
+            "business_context": business_context.model_dump(),
+            "identity_missing": missing_identity_keys,
+        }
+        root_span_name = _format_root_span_name(
+            getattr(settings, "LANGFUSE_ROOT_SPAN_NAME", "agent.gateway_message"),
+            {
+                "workflow_id": workflow_id,
+                "channel": msg.channel,
+                "agent_id": identity.agent_id,
+                "tenant_id": identity.tenant_id,
+            },
+        )
+        root_tags = ["agent-template", msg.channel, f"agent:{identity.agent_id}", f"tenant:{identity.tenant_id}"]
+        if workflow_id:
+            root_tags.append(f"workflow:{workflow_id}")
+
+        async with telemetry.span(
+            root_span_name,
+            session_id=agent_session_id,
+            user_id=session.user_id,
+            channel=msg.channel,
+            workflow_id=workflow_id,
+            input=cms_input,
+            tags=root_tags,
+            _root_span=True,
+        ) as root_span:
+            await telemetry.event("gateway.message.received", trace_context)
+            await sse_hub.emit(agent_session_id, "workflow.started", trace_context) if emit_sse else None
+            result = await workflow.ainvoke(
+                {
+                    "tenant_id": identity.tenant_id,
+                    "agent_id": identity.agent_id,
+                    "session_id": agent_session_id,
+                    "conversation_key": agent_session_id,
+                    "workflow_id": workflow_id,
+                    "agent_profile": normalized_context["agent_profile"],
+                    # Chave estável de LTM. Nunca use session_id como identidade de longo prazo.
+                    "long_term_memory_subject_key": business_context.customer_key or session.user_id,
+                    "customer_key": business_context.customer_key,
+                    "user_id": session.user_id,
+                    "business_context": business_context.model_dump(),
+                    "user_text": msg.text,
+                    "history": history,
+                    "context": {
+                        **normalized_context,
+                        "session": session.model_dump(mode="json"),
+                        "original_session_id": msg.session_id,
+                        "session_id": agent_session_id,
+                        "conversation_key": agent_session_id,
+                        "workflow_id": workflow_id,
+                        "user_id": session.user_id,
+                        "channel": msg.channel,
+                        "message_id": message_id,
+                        "business_context": business_context.model_dump(),
+                        "business_keys": business_context.to_context_dict(),
+                        "identity_missing": missing_identity_keys,
+                    },
+                }
+            )
+
+            await checkpoints.put(agent_session_id, {"state": result, "message_id": message_id})
+            await sse_hub.emit(agent_session_id, "workflow.completed", {"session_id": agent_session_id, "route": result.get("route"), "intent": result.get("intent")}) if emit_sse else None
+
+            answer = result.get("final_answer") or result.get("answer") or ""
+            await memory.append(
+                agent_session_id,
+                ChatMessage(
+                    role="assistant",
+                    content=answer,
+                    metadata={
+                        "tenant_id": identity.tenant_id,
+                        "agent_id": identity.agent_id,
+                        "message_id": f"assistant-{message_id}",
+                        "route": result.get("route"),
+                        "intent": result.get("intent"),
+                        "route_decision": result.get("route_decision"),
+                        "judges": result.get("judge_results"),
+                    },
+                ),
+            )
+
+            await telemetry.event(
+                "gateway.message.responded",
+                {
+                    "session_id": agent_session_id,
+                    "tenant_id": identity.tenant_id,
+                    "agent_id": identity.agent_id,
+                    "route": result.get("route"),
+                    "intent": result.get("intent"),
+                    "answer_chars": len(answer),
+                },
+            )
+
+            response = ChannelResponse(
+                channel=msg.channel,
+                session_id=agent_session_id,
+                text=answer,
+                metadata={
+                    "channel_id": msg.channel_id,
+                    "tenant_id": identity.tenant_id,
+                    "agent_id": identity.agent_id,
+                    "original_session_id": msg.session_id,
+                    "conversation_key": agent_session_id,
+                    "workflow_id": workflow_id,
+                    "message_id": message_id,
+                    "route": result.get("route"),
+                    "intent": result.get("intent"),
+                    "route_decision": result.get("route_decision"),
+                    "domain": result.get("domain"),
+                    "mcp_tools": result.get("mcp_tools"),
+                    "mcp_results": result.get("mcp_results"),
+                    "business_context": business_context.model_dump(),
+                    "identity_missing": missing_identity_keys,
+                    "judges": result.get("judge_results"),
+                    "guardrails": result.get("guardrail_decisions"),
+                    "long_term_memory": {
+                        "subject_key": business_context.customer_key or session.user_id,
+                        "loaded": result.get("long_term_memories", []),
+                        "context": result.get("long_term_memory_context", ""),
+                        "load_error": result.get("long_term_memory_load_error"),
+                        "write_result": result.get("long_term_memory_write_result", {}),
+                    },
+                },
+            )
+            rendered = await gateway.render(response)
+            root_span.set_output(rendered)
+            await sse_hub.emit(agent_session_id, "message.responded", rendered) if emit_sse else None
+            await sse_hub.emit(agent_session_id, "flow.end", {"session_id": agent_session_id, "message_id": message_id}) if emit_sse else None
+            return rendered
+
+
+@app.get("/health")
+async def health():
+    return {
+        "status": "ok",
+        "llm_provider": settings.LLM_PROVIDER,
+        "llm_class": llm.__class__.__name__,
+        "langfuse_enabled": telemetry.is_enabled(),
+        "agents": [p.agent_id for p in agent_profiles.list_profiles()],
+        "default_agent_id": agent_profiles.default_agent_id,
+        "routing_mode": settings.ROUTING_MODE,
+        "sse_enabled": settings.ENABLE_SSE,
+        "session_repository": settings.SESSION_REPOSITORY_PROVIDER,
+        "memory_repository": settings.MEMORY_REPOSITORY_PROVIDER,
+        "long_term_memory": {
+            "enabled": getattr(settings, "ENABLE_LONG_TERM_MEMORY", False),
+            "provider": getattr(settings, "LONG_TERM_MEMORY_PROVIDER", None),
+            "sqlite_path": getattr(settings, "LONG_TERM_MEMORY_SQLITE_PATH", None),
+            "table": getattr(settings, "LONG_TERM_MEMORY_TABLE", None),
+            "auto_extract": getattr(settings, "LONG_TERM_MEMORY_AUTO_EXTRACT", None),
+            "inject_context": getattr(settings, "LONG_TERM_MEMORY_INJECT_CONTEXT", None),
+        },
+        "checkpoint_repository": settings.CHECKPOINT_REPOSITORY_PROVIDER,
+        "usage_repository": settings.USAGE_REPOSITORY_PROVIDER,
+        "identity_config_path": settings.IDENTITY_CONFIG_PATH,
+        "mcp_parameter_mapping_path": settings.MCP_PARAMETER_MAPPING_PATH,
+        "framework_channel_input_mode": settings.FRAMEWORK_CHANNEL_INPUT_MODE,
+        "legacy_channel_gateway_mode": settings.CHANNEL_GATEWAY_MODE,
+    }
+
+
+@app.get("/agents")
+async def list_agents():
+    return {"default_agent_id": agent_profiles.default_agent_id, "agents": [p.__dict__ for p in agent_profiles.list_profiles()]}
+
+
+@app.get("/debug/env")
+async def debug_env():
+    return {
+        "APP_ENV": settings.APP_ENV,
+        "LLM_PROVIDER": settings.LLM_PROVIDER,
+        "ENABLE_LANGFUSE": settings.ENABLE_LANGFUSE,
+        "LANGFUSE_HOST": settings.LANGFUSE_HOST,
+        "TELEMETRY_ENABLED": telemetry.is_enabled(),
+        "SQLITE_DB_PATH": settings.SQLITE_DB_PATH,
+        "SESSION_REPOSITORY_PROVIDER": settings.SESSION_REPOSITORY_PROVIDER,
+        "MEMORY_REPOSITORY_PROVIDER": settings.MEMORY_REPOSITORY_PROVIDER,
+        "CHECKPOINT_REPOSITORY_PROVIDER": settings.CHECKPOINT_REPOSITORY_PROVIDER,
+        "AGENTS_CONFIG_PATH": settings.AGENTS_CONFIG_PATH,
+        "ROUTING_CONFIG_PATH": settings.ROUTING_CONFIG_PATH,
+        "ROUTING_MODE": settings.ROUTING_MODE,
+        "FRAMEWORK_CHANNEL_INPUT_MODE": settings.FRAMEWORK_CHANNEL_INPUT_MODE,
+        "CHANNEL_GATEWAY_MODE": settings.CHANNEL_GATEWAY_MODE,
+    }
+
+
+@app.get("/test-llm")
+async def test_llm():
+    async with telemetry.span("debug.test_llm", input={"message": "Diga apenas OK"}):
+        answer = await llm.ainvoke([
+            {"role": "system", "content": "Responda de forma curta."},
+            {"role": "user", "content": "Diga apenas OK"},
+        ])
+    telemetry.flush()
+    return {"provider": llm.__class__.__name__, "answer": answer}
+
+
+@app.post("/debug/route")
+async def debug_route(req: GatewayRequest):
+    msg = await gateway.normalize(req.channel, req.payload)
+    identity, context, business_context, missing_identity_keys = _resolve_identity(req, msg)
+    state = {
+        "tenant_id": identity.tenant_id,
+        "agent_id": identity.agent_id,
+        "session_id": msg.session_id or "debug-session",
+        "conversation_key": identity.conversation_key(),
+        "agent_profile": context["agent_profile"],
+        "user_text": msg.text,
+        "sanitized_input": msg.text,
+        "history": [],
+        "context": {**context, "session": context.get("session", {}), "channel": msg.channel, "business_context": business_context.model_dump()},
+    }
+    if settings.ROUTING_MODE == "supervisor":
+        plan = await workflow.supervisor.route_plan(state)
+        return {"mode": "supervisor", "route": "supervisor_agent", "agents": plan.agents, "intent": plan.intent, "confidence": plan.confidence, "reason": plan.reason, "metadata": plan.metadata}
+    decision = await workflow.router.route(state)
+    data = decision.model_dump(mode="json")
+    data["mode"] = "router"
+    return data
+
+
+
+
+@app.post("/debug/identity")
+async def debug_identity(req: GatewayRequest):
+    msg = await gateway.normalize(req.channel, req.payload)
+    identity, context, business_context, missing_identity_keys = _resolve_identity(req, msg)
+    return {
+        "technical_identity": {
+            "tenant_id": identity.tenant_id,
+            "agent_id": identity.agent_id,
+            "conversation_key": identity.conversation_key(),
+            "original_session_id": msg.session_id,
+        },
+        "business_context": business_context.model_dump(),
+        "identity_missing": missing_identity_keys,
+        "context_keys": sorted(context.keys()),
+    }
+
+@app.get("/debug/usage")
+async def debug_usage(tenant_id: str | None = None, session_id: str | None = None):
+    return await usage_repository.summarize(tenant_id=tenant_id, session_id=session_id)
+
+
+@app.get("/debug/mcp/tools")
+async def debug_mcp_tools():
+    return {"enabled": tool_router.enabled, "tools": tool_router.describe_tools()}
+
+
+@app.post("/debug/mcp/call/{tool_name}")
+async def debug_mcp_call(tool_name: str, arguments: dict | None = None):
+    arguments = arguments or {}
+    ctx = arguments.get("business_context") or arguments.get("identity") or {}
+    result = await tool_router.call(
+        tool_name,
+        arguments,
+        business_context=ctx,
+        original_context=arguments,
+    )
+    return result.model_dump(mode="json")
+
+
+@app.post("/gateway/message")
+async def gateway_message(req: GatewayRequest):
+    return await _process_gateway_message(req, emit_sse=False)
+
+
+@app.post("/gateway/message/sse")
+async def gateway_message_sse(req: GatewayRequest):
+    return await _process_gateway_message(req, emit_sse=True)
+
+
+@app.get("/gateway/events/{session_id}")
+async def gateway_events(session_id: str, request: Request):
+    last = request.headers.get("last-event-id") or request.query_params.get("last_event_id") or "0"
+    return StreamingResponse(
+        sse_hub.subscribe(session_id, int(last)),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no"},
+    )
+
+
+@app.get("/sessions/{session_id}/messages")
+async def get_session_messages(session_id: str, limit: int = 50):
+    return {"session_id": session_id, "messages": [m.model_dump(mode="json") for m in await memory.list(session_id, limit)]}
+
+
+@app.get("/sessions/{session_id}/checkpoint")
+async def get_session_checkpoint(session_id: str):
+    return {"session_id": session_id, "checkpoint": await checkpoints.get_latest(session_id)}
+
+
+@app.on_event("shutdown")
+async def shutdown():
+    telemetry.shutdown()
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/mcp_gateway_client_factory.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/mcp_gateway_client_factory.py
new file mode 100644
index 0000000..5a32d15
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/mcp_gateway_client_factory.py
@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import os
+
+from agent_framework.gateways import MCPGatewayClient
+
+
+def build_mcp_gateway_client() -> MCPGatewayClient | None:
+    if os.getenv("MCP_GATEWAY_ENABLED", "true").lower() != "true":
+        return None
+
+    return MCPGatewayClient(
+        base_url=os.getenv("MCP_GATEWAY_URL", "http://localhost:8300"),
+        token=os.getenv("MCP_GATEWAY_TOKEN") or None,
+        timeout_seconds=int(os.getenv("MCP_GATEWAY_TIMEOUT_SECONDS", "60")),
+    )
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/__init__.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/__pycache__/__init__.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/__pycache__/__init__.cpython-313.pyc
new file mode 100644
index 0000000..b6a83d0
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/__pycache__/__init__.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/__pycache__/telemetry_observer.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/__pycache__/telemetry_observer.cpython-313.pyc
new file mode 100644
index 0000000..b917a57
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/__pycache__/telemetry_observer.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/telemetry_observer.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/telemetry_observer.py
new file mode 100644
index 0000000..92f07a1
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/observability/telemetry_observer.py
@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+"""Observer adapter that emits IC/NOC/GRL through framework Telemetry only.
+
+This avoids a second Langfuse root trace created by AgentObserver ->
+AnalyticsPublisher while preserving the events inside the active request span.
+"""
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def _normalize_ic_code(code: str) -> str:
+    code = str(code or "UNKNOWN").strip()
+    return code if code.startswith(("IC.", "AGA.", "NOC.", "GRL.")) else f"IC.{code}"
+
+
+def _normalize_noc_code(code: str) -> str:
+    code = str(code or "UNKNOWN").strip()
+    return code if code.startswith("NOC.") else f"NOC.{code}"
+
+
+def _normalize_grl_code(code: str) -> str:
+    code = str(code or "UNKNOWN").strip()
+    return code if code.startswith("GRL.") else f"GRL.{code}"
+
+
+def _kind_for(event_type: str) -> str:
+    if event_type.startswith(("IC.", "AGA.")):
+        return "ic"
+    if event_type.startswith("NOC."):
+        return "noc"
+    if event_type.startswith("GRL."):
+        return "grl"
+    return "event"
+
+
+class TelemetryBackedAgentObserver:
+    """Drop-in subset of AgentObserver backed by Telemetry.event.
+
+    Do not publish through AnalyticsPublisher here. Analytics publishing may be
+    configured with a Langfuse provider, and that path creates an extra root
+    trace for business events such as IC.AGENT_COMPLETED/NOC.006. Telemetry.event
+    uses the active span/trace context, so these events appear inside the single
+    request trace.
+    """
+
+    def __init__(self, telemetry: Any, *, source: str = "agent_framework") -> None:
+        self.telemetry = telemetry
+        self.source = source
+
+    async def emit(
+        self,
+        event_type: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        metadata: dict[str, Any] | None = None,
+        source: str | None = None,
+    ) -> dict[str, Any]:
+        body = dict(payload or {})
+        meta = dict(metadata or {})
+        body.setdefault("tag", event_type)
+        event = {
+            "eventType": event_type,
+            "source": source or self.source,
+            "eventDate": datetime.now(timezone.utc).isoformat(),
+            "body": body,
+            "metadata": meta,
+        }
+        try:
+            await self.telemetry.event(event_type, event, kind=_kind_for(event_type))
+        except TypeError:
+            # Compatibility with older Telemetry.event signatures.
+            await self.telemetry.event(event_type, event)
+        return event
+
+    async def emit_ic(self, code: str, payload: dict[str, Any] | None = None, **metadata: Any) -> dict[str, Any]:
+        return await self.emit(_normalize_ic_code(code), payload, metadata={**metadata, "ic": True})
+
+    async def emit_noc(self, code: str, payload: dict[str, Any] | None = None, **metadata: Any) -> dict[str, Any]:
+        return await self.emit(_normalize_noc_code(code), payload, metadata={**metadata, "noc": True})
+
+    async def emit_grl(self, code: str, payload: dict[str, Any] | None = None, **metadata: Any) -> dict[str, Any]:
+        return await self.emit(_normalize_grl_code(code), payload, metadata={**metadata, "grl": True})
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/state.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/state.py
new file mode 100644
index 0000000..cc19c03
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/state.py
@@ -0,0 +1,53 @@
+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]]
+    available_mcp_tools: list[str]
+    selected_tool_call: dict[str, Any]
+    pending_tool_call: dict[str, Any]
+    transaction_status: str
+    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]]
+    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
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/__init__.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/__init__.py
new file mode 100644
index 0000000..6be8ce7
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/__init__.py
@@ -0,0 +1 @@
+from . import devolucao  # noqa: F401
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/__pycache__/__init__.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/__pycache__/__init__.cpython-313.pyc
new file mode 100644
index 0000000..672ec8a
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/__pycache__/__init__.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/__pycache__/devolucao.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/__pycache__/devolucao.cpython-313.pyc
new file mode 100644
index 0000000..ba3e1b1
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/__pycache__/devolucao.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/devolucao.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/devolucao.py
new file mode 100644
index 0000000..6111cf1
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflow_actions/devolucao.py
@@ -0,0 +1,13 @@
+"""Actions de domínio permanecem no agente; o runtime está no framework."""
+from agent_framework.workflows import workflow_action
+
+
+@workflow_action("validar_pedido")
+async def validar_pedido(params: dict, state: dict) -> dict:
+    return {"valid": bool(params.get("order_id"))}
+
+
+@workflow_action("registrar_devolucao")
+async def registrar_devolucao(params: dict, state: dict) -> dict:
+    # Substitua pela chamada real ao serviço/MCP e use chave idempotente.
+    return {"protocol": f"DEV-{params['order_id']}", "status": "REQUESTED"}
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflows/__pycache__/agent_graph.cpython-313.pyc b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflows/__pycache__/agent_graph.cpython-313.pyc
new file mode 100644
index 0000000..dbe6f09
Binary files /dev/null and b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflows/__pycache__/agent_graph.cpython-313.pyc differ
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflows/agent_graph.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflows/agent_graph.py
new file mode 100644
index 0000000..b8ed7bc
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/app/workflows/agent_graph.py
@@ -0,0 +1,887 @@
+from agent_framework.checkpoints.langgraph_saver import create_langgraph_checkpointer
+from langgraph.graph import END, START, StateGraph
+
+from agent_framework.guardrails.pipeline import GuardrailPipeline
+from agent_framework.guardrails.output_supervisor import OutputSupervisor
+from agent_framework.guardrails.rail_action import RailAction
+from agent_framework.guardrails.rail_result import RailResult
+from agent_framework.judges.judge import JudgePipeline
+from agent_framework.routing.enterprise_router import EnterpriseRouter
+from agent_framework.supervisor.supervisor import Supervisor
+from agent_framework.observability.workflow_events import WorkflowTelemetry
+from agent_framework.observability.guardrail_events import GuardrailTelemetry
+from agent_framework.observability.judge_events import JudgeTelemetry
+from agent_framework.observability.langgraph_telemetry import LangGraphDeepTelemetry
+from agent_framework.observability.observer import AgentObserver
+from app.agents.billing_agent import BillingAgent
+from app.agents.product_agent import ProductAgent
+from app.agents.orders_agent import OrdersAgent
+from app.agents.support_agent import SupportAgent
+from app.state import AgentState
+from agent_framework.rag.rag_service import RagService
+from agent_framework.rag.embedding_provider import create_embedding_provider
+from agent_framework.cache.cache import create_cache
+from agent_framework.memory.long_term_memory import create_long_term_memory_manager
+
+
+class LegacyOutputGuardrailRail:
+    """Adapter: reutiliza GuardrailPipeline.run_output dentro do OutputSupervisor novo.
+
+    O framework antigo retornava decisões allowed=True/False. O OutputSupervisor
+    corporativo trabalha com RailAction (allow/sanitize/retry/block/handover).
+    Este adapter evita reescrever todos os rails agora e mantém compatibilidade.
+    """
+
+    code = "LEGACY_OUTPUT_GUARDRAILS"
+
+    def __init__(self, pipeline: GuardrailPipeline):
+        self.pipeline = pipeline
+
+    async def evaluate(self, candidate: str, context: dict):
+        final, decisions = await self.pipeline.run_output(candidate, context)
+        serialized = [d.model_dump() for d in decisions]
+
+        blocked = [d for d in decisions if not getattr(d, "allowed", True)]
+        if blocked:
+            first = blocked[0]
+            code = (getattr(first, "code", "") or "").upper()
+            action = RailAction.RETRY if code in {"REVPREC", "CMP", "SCO", "GND"} else RailAction.BLOCK
+            return RailResult(
+                code=code or self.code,
+                action=action,
+                reason=getattr(first, "reason", "Resposta bloqueada por guardrail de saída"),
+                guidance=getattr(first, "reason", "Regerar resposta seguindo as políticas de saída."),
+                sanitized_text=final,
+                metadata={"legacy_decisions": serialized},
+            )
+
+        if final != candidate:
+            return RailResult(
+                code=self.code,
+                action=RailAction.SANITIZE,
+                reason="Resposta sanitizada por guardrail de saída legado.",
+                sanitized_text=final,
+                metadata={"legacy_decisions": serialized},
+            )
+
+        return RailResult(
+            code=self.code,
+            action=RailAction.ALLOW,
+            reason="Resposta aprovada pelos guardrails de saída legados.",
+            sanitized_text=final,
+            metadata={"legacy_decisions": serialized},
+        )
+
+
+class AgentWorkflow:
+    """Workflow principal com dois modos de roteamento.
+
+    Modos suportados por configuração:
+      ROUTING_MODE=router
+        input_guardrails -> routing_decision/EnterpriseRouter -> 1 agente -> output_guardrails
+
+      ROUTING_MODE=supervisor
+        input_guardrails -> routing_decision/Supervisor -> supervisor_agent -> N agentes -> consolidação
+
+    Em ambos os modos, memória/checkpoint/session usam tenant_id:agent_id:session_id.
+    """
+
+    def __init__(self, llm, memory, telemetry, analytics, settings, observer: AgentObserver | None = None, tool_router=None, summary_memory=None):
+        self.llm = llm
+        self.memory = memory
+        self.telemetry = telemetry
+        self.analytics = analytics
+        self.observer = observer or AgentObserver(analytics=analytics)
+        self.settings = settings
+        self.tool_router = tool_router
+        self.summary_memory = summary_memory
+        self.long_term_memory_manager = create_long_term_memory_manager(settings, telemetry=telemetry)
+        self.guardrails = GuardrailPipeline(
+            observer=self.observer,
+            enable_parallel=bool(getattr(settings, "ENABLE_PARALLEL_GUARDRAILS", True)),
+            fail_fast=bool(getattr(settings, "GUARDRAILS_FAIL_FAST", True)),
+        )
+        self.output_supervisor_engine = OutputSupervisor(
+            rails=[LegacyOutputGuardrailRail(self.guardrails)],
+            observer=self.observer,
+            max_retries=int(getattr(settings, "OUTPUT_SUPERVISOR_MAX_RETRIES", 3)),
+            enable_parallel=bool(getattr(settings, "ENABLE_PARALLEL_GUARDRAILS", True)),
+            fail_fast=bool(getattr(settings, "GUARDRAILS_FAIL_FAST", True)),
+        )
+        self.judges = JudgePipeline()
+        self.supervisor = Supervisor()
+        self.workflow_telemetry = WorkflowTelemetry(telemetry)
+        self.guardrail_telemetry = GuardrailTelemetry(telemetry)
+        self.judge_telemetry = JudgeTelemetry(telemetry)
+        self.langgraph_telemetry = LangGraphDeepTelemetry(telemetry)
+        self.cache = create_cache(settings)
+        self.embedding_provider = create_embedding_provider(settings)
+        self.rag_service = RagService(settings, embedding_provider=self.embedding_provider, telemetry=telemetry)
+        self.router = EnterpriseRouter(settings, llm=llm, telemetry=telemetry)
+        agent_kwargs = {"telemetry": telemetry, "tool_router": getattr(self, "tool_router", None), "rag_service": self.rag_service, "cache": self.cache, "settings": settings, "observer": self.observer, "memory": memory, "summary_memory": summary_memory}
+        self.billing = BillingAgent(llm, **agent_kwargs)
+        self.product = ProductAgent(llm, **agent_kwargs)
+        self.orders = OrdersAgent(llm, **agent_kwargs)
+        self.support = SupportAgent(llm, **agent_kwargs)
+
+        # The existing agent constructors intentionally keep their stable API.
+        # Long-term memory is injected as a runtime capability after creation.
+        for agent in (self.billing, self.product, self.orders, self.support):
+            agent.long_term_memory_manager = self.long_term_memory_manager
+        self.graph = self._build_graph()
+
+    def _node(self, name, fn):
+        async def _wrapped(state):
+            async with self.langgraph_telemetry.node(name, state):
+                return await fn(state)
+        return _wrapped
+
+    def _build_graph(self):
+        builder = StateGraph(AgentState)
+        builder.add_node("input_guardrails", self._node("input_guardrails", self.input_guardrails))
+        builder.add_node("load_long_term_memory", self._node("load_long_term_memory", self.load_long_term_memory))
+        builder.add_node("routing_decision", self._node("routing_decision", self.routing_decision))
+        builder.add_node("billing_agent", self._node("billing_agent", self.billing_agent))
+        builder.add_node("product_agent", self._node("product_agent", self.product_agent))
+        builder.add_node("orders_agent", self._node("orders_agent", self.orders_agent))
+        builder.add_node("support_agent", self._node("support_agent", self.support_agent))
+        builder.add_node("handoff", self._node("handoff", self.handoff))
+        builder.add_node("human_handoff", self._node("human_handoff", self.human_handoff))
+        builder.add_node("end_session", self._node("end_session", self.end_session))
+        builder.add_node("supervisor_agent", self._node("supervisor_agent", self.supervisor_agent))
+        builder.add_node("output_supervisor", self._node("output_supervisor", self.output_supervisor))
+        builder.add_node("output_guardrails", self._node("output_guardrails", self.output_guardrails))
+        builder.add_node("judge", self._node("judge", self.judge))
+        builder.add_node("supervisor_review", self._node("supervisor_review", self.supervisor_review))
+        builder.add_node("persist_long_term_memory", self._node("persist_long_term_memory", self.persist_long_term_memory))
+        builder.add_node("persist", self._node("persist", self.persist))
+
+        builder.add_edge(START, "input_guardrails")
+        builder.add_conditional_edges(
+            "input_guardrails",
+            self._after_input_guardrails,
+            {"blocked": "persist", "continue": "load_long_term_memory"},
+        )
+        builder.add_edge("load_long_term_memory", "routing_decision")
+        builder.add_conditional_edges(
+            "routing_decision",
+            lambda s: s.get("route", "billing_agent"),
+            {
+                "billing_agent": "billing_agent",
+                "product_agent": "product_agent",
+                "orders_agent": "orders_agent",
+                "support_agent": "support_agent",
+                "handoff": "handoff",
+                "human_handoff": "human_handoff",
+                "end_session": "end_session",
+                "supervisor_agent": "supervisor_agent",
+            },
+        )
+        builder.add_edge("billing_agent", "output_supervisor")
+        builder.add_edge("product_agent", "output_supervisor")
+        builder.add_edge("orders_agent", "output_supervisor")
+        builder.add_edge("support_agent", "output_supervisor")
+        builder.add_edge("handoff", "output_supervisor")
+        builder.add_edge("human_handoff", "output_supervisor")
+        builder.add_edge("end_session", "output_supervisor")
+        builder.add_edge("supervisor_agent", "output_supervisor")
+        builder.add_edge("output_supervisor", "output_guardrails")
+        builder.add_edge("output_guardrails", "judge")
+        builder.add_edge("judge", "supervisor_review")
+        builder.add_edge("supervisor_review", "persist_long_term_memory")
+        builder.add_edge("persist_long_term_memory", "persist")
+        builder.add_edge("persist", END)
+
+        return builder.compile(checkpointer=create_langgraph_checkpointer(self.settings))
+
+    def _after_input_guardrails(self, state):
+        return "blocked" if state.get("blocked") else "continue"
+
+    async def input_guardrails(self, state):
+        if state.get("session_ended") is True:
+            answer = str(getattr(
+                self.settings,
+                "SESSION_ALREADY_ENDED_MESSAGE",
+                "Este atendimento já foi encerrado. Inicie uma nova sessão para continuar.",
+            ))
+            await self.telemetry.event(
+                "session.message.rejected_after_end",
+                {"session_id": state.get("conversation_key") or state.get("session_id")},
+            )
+            return {
+                "answer": answer,
+                "final_answer": answer,
+                "blocked": True,
+                "session_control": "END_SESSION",
+                "session_ended": True,
+                "next_state": "SESSION_ENDED",
+            }
+        async with self.telemetry.span(
+            "workflow.input_guardrails",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input=state.get("user_text"),
+        ):
+            history_texts = [m.get("content", "") for m in state.get("history", [])]
+            await self.observer.emit_grl(
+                "001",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "phase": "input",
+                },
+                component="workflow.input_guardrails.start",
+            )
+            sanitized, decisions = await self.guardrails.run_input(
+                state["user_text"],
+                {
+                    **(state.get("context") or {}),
+                    "history_texts": history_texts,
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "agent_profile": state.get("agent_profile") or {},
+                },
+            )
+            for _decision in decisions:
+                await self.guardrail_telemetry.evaluated("input", _decision)
+                await self.observer.emit_grl(
+                    "002" if _decision.allowed else "004",
+                    {
+                        "session_id": state.get("conversation_key") or state.get("session_id"),
+                        "tenant_id": state.get("tenant_id"),
+                        "agent_id": state.get("agent_id"),
+                        "phase": "input",
+                        "rail_code": getattr(_decision, "code", None),
+                        "allowed": bool(_decision.allowed),
+                        "reason": getattr(_decision, "reason", None),
+                    },
+                    component="workflow.input_guardrails.decision",
+                )
+                if not _decision.allowed:
+                    await self.guardrail_telemetry.blocked("input", _decision)
+            await self.telemetry.event(
+                "guardrails.input.completed",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "decisions": [d.model_dump() for d in decisions],
+                },
+            )
+            await self.observer.emit_grl(
+                "009",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "phase": "input",
+                    "blocked": any(not d.allowed for d in decisions),
+                    "decision_count": len(decisions),
+                },
+                component="workflow.input_guardrails.final",
+            )
+            if any(not d.allowed for d in decisions):
+                return {
+                    "sanitized_input": sanitized,
+                    "answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "final_answer": "Não consegui seguir com essa mensagem por regra de segurança.",
+                    "guardrail_decisions": [d.model_dump() for d in decisions],
+                    "route": "blocked",
+                    "blocked": True,
+                }
+            return {
+                "sanitized_input": sanitized,
+                "guardrail_decisions": [d.model_dump() for d in decisions],
+                "blocked": False,
+            }
+
+    async def routing_decision(self, state):
+        mode = getattr(self.settings, "ROUTING_MODE", "router")
+        async with self.telemetry.span(
+            "workflow.routing_decision",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input={
+                "mode": mode,
+                "text": state.get("sanitized_input") or state.get("user_text"),
+                "previous_state": state.get("next_state"),
+            },
+        ):
+            if mode == "supervisor":
+                plan = await self.supervisor.route_plan(state)
+                await self.langgraph_telemetry.edge("routing_decision", "supervisor_agent", state, {"method": "supervisor", "intent": plan.intent, "confidence": plan.confidence})
+                return {
+                    "route": "supervisor_agent",
+                    "intent": plan.intent,
+                    "supervisor_plan": {
+                        "agents": plan.agents,
+                        "intent": plan.intent,
+                        "confidence": plan.confidence,
+                        "reason": plan.reason,
+                        "metadata": plan.metadata,
+                    },
+                    "route_decision": {
+                        "route": "supervisor_agent",
+                        "agent": "supervisor",
+                        "intent": plan.intent,
+                        "confidence": plan.confidence,
+                        "reason": plan.reason,
+                        "method": "supervisor",
+                        "metadata": plan.metadata,
+                    },
+                }
+
+            decision = await self.router.route(state)
+            await self.langgraph_telemetry.edge("routing_decision", decision.route, state, {"method": getattr(decision, "method", None), "intent": decision.intent, "confidence": decision.confidence})
+            await self.observer.emit_ic(
+                "ROUTE_SELECTED",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "route": decision.route,
+                    "intent": decision.intent,
+                    "confidence": decision.confidence,
+                    "method": getattr(decision, "method", None),
+                },
+                component="workflow.routing_decision",
+            )
+            return {
+                "route": decision.route,
+                "intent": decision.intent,
+                "route_decision": decision.model_dump(mode="json"),
+                "domain": decision.domain,
+                "mcp_tools": decision.mcp_tools,
+                "next_state": decision.next_state,
+                "active_agent": decision.agent,
+                "route_bypassed": decision.method == "continuity",
+                "session_control": (decision.metadata or {}).get("session_control", ""),
+                "human_handoff_requested": (decision.metadata or {}).get("session_control") == "HUMAN_HANDOFF",
+                "session_ended": (decision.metadata or {}).get("session_control") == "END_SESSION",
+                "continuity_signal": {
+                    "decision": (decision.metadata or {}).get("continuity_decision"),
+                    "confidence": decision.confidence if decision.method == "continuity" else None,
+                    "reason": decision.reason if decision.method == "continuity" else None,
+                    "profile": (decision.metadata or {}).get("continuity_profile"),
+                } if decision.method == "continuity" else {},
+            }
+
+    async def billing_agent(self, state):
+        async with self.telemetry.span(
+            "workflow.agent.billing",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input={"intent": state.get("intent")},
+        ):
+            return await self.billing.run(state)
+
+    async def product_agent(self, state):
+        async with self.telemetry.span(
+            "workflow.agent.product",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input={"intent": state.get("intent")},
+        ):
+            return await self.product.run(state)
+
+    async def orders_agent(self, state):
+        async with self.telemetry.span(
+            "workflow.agent.orders",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input={"intent": state.get("intent")},
+        ):
+            return await self.orders.run(state)
+
+    async def support_agent(self, state):
+        async with self.telemetry.span(
+            "workflow.agent.support",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input={"intent": state.get("intent")},
+        ):
+            return await self.support.run(state)
+
+    async def supervisor_agent(self, state):
+        """Executa um ou mais agentes no modo supervisor e consolida a resposta.
+
+        Este nó mantém o desenho de supervisor sem obrigar o restante do workflow
+        a conhecer quantos agentes foram acionados. Cada execução especializada
+        recebe o mesmo estado, mas com route/active_agent atualizados.
+        """
+        plan = state.get("supervisor_plan") or {}
+        agents = plan.get("agents") or ["billing_agent"]
+        handlers = {
+            "billing_agent": self.billing.run,
+            "product_agent": self.product.run,
+            "orders_agent": self.orders.run,
+            "support_agent": self.support.run,
+        }
+        partials = []
+        mcp_results = []
+        async with self.telemetry.span(
+            "workflow.supervisor_agent",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input={"agents": agents, "intent": state.get("intent")},
+        ):
+            for agent_name in agents:
+                handler = handlers.get(agent_name)
+                if handler is None:
+                    continue
+                child_state = {**state, "route": agent_name, "active_agent": agent_name}
+                result = await handler(child_state)
+                partials.append({"agent": agent_name, "answer": result.get("answer", "")})
+                mcp_results.extend(result.get("mcp_results") or [])
+
+        if len(partials) == 1:
+            answer = partials[0]["answer"]
+        else:
+            joined = "\n\n".join(f"{p['agent']}: {p['answer']}" for p in partials)
+            answer = (
+                "[Supervisor] Consolidação de múltiplos agentes acionados.\n"
+                f"{joined}"
+            )
+        return {
+            "answer": answer,
+            "supervisor_results": partials,
+            "mcp_results": mcp_results,
+            "next_state": "SUPERVISOR_ACTIVE",
+        }
+
+    async def handoff(self, state):
+        async with self.telemetry.span("workflow.handoff", session_id=state.get("session_id")):
+            target = (state.get("route_decision") or {}).get("metadata", {}).get("target_agent")
+            answer = (
+                "Vou redirecionar sua solicitação para o especialista correto. "
+                f"Destino sugerido: {target or 'agente especializado'}."
+            )
+            return {"answer": answer}
+
+    async def human_handoff(self, state):
+        session_id = state.get("conversation_key") or state.get("session_id")
+        async with self.telemetry.span("workflow.human_handoff", session_id=session_id):
+            answer = str(getattr(self.settings, "HUMAN_HANDOFF_MESSAGE", "Vou encaminhar seu atendimento para uma pessoa."))
+            await self.telemetry.event(
+                "session.human_handoff.requested",
+                {
+                    "session_id": session_id,
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "reason": (state.get("route_decision") or {}).get("reason"),
+                },
+            )
+            return {
+                "answer": answer,
+                "session_control": "HUMAN_HANDOFF",
+                "human_handoff_requested": True,
+                "session_ended": False,
+                "next_state": "HUMAN_HANDOFF_REQUESTED",
+            }
+
+    async def end_session(self, state):
+        session_id = state.get("conversation_key") or state.get("session_id")
+        async with self.telemetry.span("workflow.end_session", session_id=session_id):
+            answer = str(getattr(self.settings, "END_SESSION_MESSAGE", "Atendimento encerrado. Obrigado pelo contato."))
+            await self.telemetry.event(
+                "session.end.requested",
+                {
+                    "session_id": session_id,
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "reason": (state.get("route_decision") or {}).get("reason"),
+                },
+            )
+            return {
+                "answer": answer,
+                "session_control": "END_SESSION",
+                "session_ended": True,
+                "human_handoff_requested": False,
+                "next_state": "SESSION_ENDED",
+            }
+
+    async def output_supervisor(self, state):
+        """Valida a resposta candidata com o OutputSupervisor corporativo.
+
+        Este nó não substitui o roteador/supervisor multiagente. Ele roda após o
+        agente gerar `answer` e antes dos judges/persistência, produzindo campos
+        supervisor_* no state e eventos GRL.001..GRL.009 via AgentObserver.
+        """
+        if not bool(getattr(self.settings, "ENABLE_OUTPUT_SUPERVISOR", True)):
+            return {
+                "output_guardrails_already_applied": False,
+                "supervisor_action": "disabled",
+                "supervisor_attempt": int(state.get("supervisor_attempt", 0)),
+            }
+
+        candidate = state.get("answer") or ""
+        context = {
+            **(state.get("context") or {}),
+            "tenant_id": state.get("tenant_id"),
+            "agent_id": state.get("agent_id"),
+            "session_id": state.get("conversation_key") or state.get("session_id"),
+            "route": state.get("route"),
+            "intent": state.get("intent"),
+            "supervisor_attempt": int(state.get("supervisor_attempt", 0)),
+        }
+        async with self.telemetry.span(
+            "workflow.output_supervisor",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input=candidate,
+        ):
+            decision = await self.output_supervisor_engine.evaluate(candidate, context)
+            action = decision.action.value
+            await self.telemetry.event(
+                "output_supervisor.completed",
+                {
+                    "session_id": context["session_id"],
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "action": action,
+                    "approved": decision.approved,
+                    "guidance": decision.guidance,
+                },
+            )
+
+            await self.observer.emit_ic(
+                "IC.OUTPUT_SUPERVISOR_COMPLETED",
+                {
+                    "session_id": context["session_id"],
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "route": state.get("route"),
+                    "intent": state.get("intent"),
+                    "action": action,
+                    "approved": decision.approved,
+                    "result_count": len(decision.results),
+                },
+                component="workflow.output_supervisor",
+            )
+
+            if decision.action in {RailAction.ALLOW, RailAction.SANITIZE, RailAction.OBSERVE}:
+                final_answer = decision.candidate
+            elif decision.action == RailAction.HANDOVER:
+                final_answer = "Vou encaminhar seu atendimento para continuidade com um especialista."
+            else:
+                final_answer = decision.fallback_message
+
+            return {
+                "answer": final_answer,
+                "final_answer": final_answer,
+                "supervisor_action": action,
+                "supervisor_guidance": decision.guidance,
+                "supervisor_attempt": int(state.get("supervisor_attempt", 0)) + (1 if decision.action == RailAction.RETRY else 0),
+                "supervisor_handover_reason": decision.handover_reason,
+                "output_supervisor_results": [
+                    {
+                        "code": r.code,
+                        "action": r.action.value,
+                        "reason": r.reason,
+                        "guidance": r.guidance,
+                        "metadata": r.metadata,
+                    }
+                    for r in decision.results
+                ],
+                "output_guardrails_already_applied": True,
+                "guardrail_decisions": state.get("guardrail_decisions", [])
+                + [item for r in decision.results for item in (r.metadata or {}).get("legacy_decisions", [])],
+            }
+
+    async def output_guardrails(self, state):
+        if state.get("output_guardrails_already_applied"):
+            return {"final_answer": state.get("final_answer") or state.get("answer") or ""}
+
+        async with self.telemetry.span(
+            "workflow.output_guardrails",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input=state.get("answer"),
+        ):
+            await self.observer.emit_grl(
+                "001",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "phase": "output",
+                    "route": state.get("route"),
+                    "intent": state.get("intent"),
+                },
+                component="workflow.output_guardrails.start",
+            )
+            final, decisions = await self.guardrails.run_output(
+                state["answer"], state.get("context", {})
+            )
+            for _decision in decisions:
+                await self.guardrail_telemetry.evaluated("output", _decision)
+                await self.observer.emit_grl(
+                    "002" if _decision.allowed else "004",
+                    {
+                        "session_id": state.get("conversation_key") or state.get("session_id"),
+                        "tenant_id": state.get("tenant_id"),
+                        "agent_id": state.get("agent_id"),
+                        "phase": "output",
+                        "rail_code": getattr(_decision, "code", None),
+                        "allowed": bool(_decision.allowed),
+                        "reason": getattr(_decision, "reason", None),
+                    },
+                    component="workflow.output_guardrails.decision",
+                )
+                if not _decision.allowed:
+                    await self.guardrail_telemetry.blocked("output", _decision)
+            await self.telemetry.event(
+                "guardrails.output.completed",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "decisions": [d.model_dump() for d in decisions],
+                },
+            )
+            await self.observer.emit_grl(
+                "009",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "phase": "output",
+                    "blocked": any(not d.allowed for d in decisions),
+                    "decision_count": len(decisions),
+                },
+                component="workflow.output_guardrails.final",
+            )
+            return {
+                "final_answer": final,
+                "guardrail_decisions": state.get("guardrail_decisions", [])
+                + [d.model_dump() for d in decisions],
+            }
+
+    async def judge(self, state):
+        async with self.telemetry.span(
+            "workflow.judge",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input={"question": state.get("user_text"), "answer": state.get("final_answer")},
+        ):
+            judge_context = dict(state.get("context", {}) or {})
+            judge_context["mcp_results"] = state.get("mcp_results", [])
+            judge_context["evidence"] = state.get("mcp_results", []) or judge_context.get("evidence")
+            judge_context["route"] = state.get("route")
+            judge_context["intent"] = state.get("intent")
+            # Judge sampling must see the finalized transaction state. These
+            # fields are populated by the agent/tool runtime before this node.
+            for key in (
+                "transaction_status",
+                "confirmation_required",
+                "confirmation_received",
+                "tool_policy_result",
+                "selected_tool_call",
+                "pending_tool_call",
+            ):
+                judge_context[key] = state.get(key)
+            judge_context["transactional_tools"] = [
+                result.get("tool_name")
+                for result in state.get("mcp_results", [])
+                if isinstance(result, dict)
+                and (
+                    (result.get("metadata") or {}).get("operation_type") == "transactional"
+                    or result.get("awaiting_confirmation")
+                    or result.get("transaction_status")
+                )
+            ]
+            results = await self.judges.evaluate_all(
+                state["user_text"], state["final_answer"], judge_context
+            )
+            for _result in results:
+                await self.judge_telemetry.evaluated(_result)
+            await self.telemetry.event(
+                "judges.completed",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "results": [r.model_dump() for r in results],
+                },
+            )
+            return {"judge_results": [r.model_dump() for r in results]}
+
+    async def supervisor_review(self, state):
+        async with self.telemetry.span(
+            "workflow.supervisor_review",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input=state.get("final_answer"),
+        ):
+            ok, answer = await self.supervisor.review(
+                state["final_answer"], state.get("context", {})
+            )
+            await self.telemetry.event(
+                "supervisor.review.completed",
+                {"session_id": state.get("session_id"), "approved": ok},
+            )
+            return {"final_answer": answer if ok else answer}
+
+    async def load_long_term_memory(self, state):
+        """Carrega LTM antes do roteamento e mantém o resultado no estado.
+
+        A carga explícita evita depender apenas do agente selecionado para realizar
+        a recuperação e facilita o diagnóstico de identidade/namespace.
+        """
+        try:
+            memories = await self.long_term_memory_manager.load(state)
+            serialized = []
+            context_lines = []
+            for item in memories or []:
+                if hasattr(item, "model_dump"):
+                    data = item.model_dump(mode="json")
+                elif hasattr(item, "__dict__"):
+                    data = dict(item.__dict__)
+                elif isinstance(item, dict):
+                    data = dict(item)
+                else:
+                    data = {"value": str(item)}
+                serialized.append(data)
+                key = data.get("key") or data.get("memory_key") or data.get("category") or "memory"
+                value = data.get("value") or data.get("memory_value")
+                if value not in (None, ""):
+                    context_lines.append(f"- {key}: {value}")
+
+            return {
+                "long_term_memories": serialized,
+                "long_term_memory_context": "\n".join(context_lines),
+            }
+        except Exception as exc:
+            await self.telemetry.event(
+                "long_term_memory.load.failed",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "subject_key": state.get("long_term_memory_subject_key"),
+                    "error": str(exc),
+                },
+            )
+            return {
+                "long_term_memories": [],
+                "long_term_memory_context": "",
+                "long_term_memory_load_error": str(exc),
+            }
+
+    async def persist_long_term_memory(self, state):
+        try:
+            result = await self.long_term_memory_manager.persist_turn(state)
+            await self.telemetry.event(
+                "long_term_memory.persist.completed",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "subject_key": state.get("long_term_memory_subject_key"),
+                    "result": result,
+                },
+            )
+            return {"long_term_memory_write_result": result}
+        except Exception as exc:
+            await self.telemetry.event(
+                "long_term_memory.persist.failed",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "subject_key": state.get("long_term_memory_subject_key"),
+                    "error": str(exc),
+                },
+            )
+            return {"long_term_memory_write_result": {"saved": 0, "error": str(exc)}}
+
+    async def persist(self, state):
+        async with self.telemetry.span(
+            "workflow.persist",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            input={"route": state.get("route"), "intent": state.get("intent")},
+        ):
+            await self.observer.emit_ic(
+                "AGENT_COMPLETED",
+                {
+                    "session_id": state.get("conversation_key") or state["session_id"],
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "route": state.get("route"),
+                    "intent": state.get("intent"),
+                    "route_decision": state.get("route_decision"),
+                    "judges": state.get("judge_results", []),
+                    "mcp_tools": state.get("mcp_tools", []),
+                    "mcp_results": state.get("mcp_results", []),
+                },
+            )
+
+            await self.observer.emit_noc(
+                "006",
+                {
+                    "session_id": state.get("conversation_key") or state["session_id"],
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "route": state.get("route"),
+                    "intent": state.get("intent"),
+                    "answer_chars": len(state.get("final_answer") or ""),
+                },
+                component="workflow.persist",
+            )
+
+            await self.telemetry.event(
+                "agent.completed",
+                {
+                    "session_id": state.get("conversation_key") or state["session_id"],
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "route": state.get("route"),
+                    "intent": state.get("intent"),
+                    "answer_chars": len(state.get("final_answer") or ""),
+                },
+            )
+            return state
+
+    async def ainvoke(self, state):
+        thread_id = state.get("conversation_key") or state["session_id"]
+        config = {"configurable": {"thread_id": thread_id}}
+        async with self.telemetry.span(
+            "workflow.langgraph.ainvoke",
+            session_id=state.get("conversation_key") or state.get("session_id"),
+            user_id=state.get("context", {}).get("user_id"),
+            input={"user_text": state.get("user_text")},
+            tags=["langgraph", "agent-workflow", f"routing-mode:{getattr(self.settings, 'ROUTING_MODE', 'router')}",],
+        ):
+            await self.workflow_telemetry.started("agent_workflow", state)
+            await self.observer.emit_noc(
+                "001",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "channel_id": (state.get("context") or {}).get("channel"),
+                    "message_id": (state.get("context") or {}).get("message_id"),
+                    "ura_call_id": (state.get("context") or {}).get("ura_call_id"),
+                },
+                component="workflow.ainvoke",
+            )
+            await self.observer.emit_ic(
+                "AGENT_STARTED",
+                {
+                    "session_id": state.get("conversation_key") or state.get("session_id"),
+                    "tenant_id": state.get("tenant_id"),
+                    "agent_id": state.get("agent_id"),
+                    "channel_id": (state.get("context") or {}).get("channel"),
+                    "message_id": (state.get("context") or {}).get("message_id"),
+                    "user_text_chars": len(state.get("user_text") or ""),
+                },
+                component="workflow.ainvoke",
+            )
+            try:
+                result = await self.graph.ainvoke(state, config=config)
+                await self.workflow_telemetry.completed("agent_workflow", result)
+                return result
+            except Exception as exc:
+                await self.workflow_telemetry.failed("agent_workflow", exc)
+                await self.observer.emit_noc(
+                    "005",
+                    {
+                        "session_id": state.get("conversation_key") or state.get("session_id"),
+                        "tenant_id": state.get("tenant_id"),
+                        "agent_id": state.get("agent_id"),
+                        "error": str(exc),
+                        "exception_type": exc.__class__.__name__,
+                    },
+                    component="workflow.ainvoke",
+                )
+                raise
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents.yaml
new file mode 100644
index 0000000..7d245a5
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents.yaml
@@ -0,0 +1,33 @@
+default_agent_id: telecom_contas
+agents:
+  - agent_id: telecom_contas
+    name: Agente Telecom Contas
+    description: Template de atendimento para faturas, produtos e suporte de telecom.
+    prompt_policy_path: ./config/agents/telecom_contas/prompt_policy.yaml
+    routing_config_path: ./config/routing.yaml
+    guardrails_config_path: ./config/agents/telecom_contas/guardrails.yaml
+    judges_config_path: ./config/agents/telecom_contas/judges.yaml
+    mcp_servers_config_path: ./config/mcp_servers.yaml
+    tools_config_path: ./config/tools.yaml
+    metadata:
+      domain: telecom
+      system_prefix: |
+        Você está executando o agent_template telecom_contas.
+        Use somente políticas, memória, checkpoints, guardrails e judges deste agent_id.
+        Não misture histórico ou decisões de outros agentes.
+
+  - agent_id: retail_orders
+    name: Agente Retail Pedidos
+    description: Template de varejo para pedidos, produtos, troca/devolução e garantia.
+    prompt_policy_path: ./config/agents/retail_orders/prompt_policy.yaml
+    routing_config_path: ./config/routing.yaml
+    guardrails_config_path: ./config/agents/retail_orders/guardrails.yaml
+    judges_config_path: ./config/agents/retail_orders/judges.yaml
+    mcp_servers_config_path: ./config/mcp_servers.yaml
+    tools_config_path: ./config/tools.yaml
+    metadata:
+      domain: retail
+      system_prefix: |
+        Você está executando o agent_template retail_orders.
+        Use somente políticas, memória, checkpoints, guardrails e judges deste agent_id.
+        Não misture histórico ou decisões de outros agentes.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/retail_orders/guardrails.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/retail_orders/guardrails.yaml
new file mode 100644
index 0000000..9fe094a
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/retail_orders/guardrails.yaml
@@ -0,0 +1,8 @@
+input:
+  - code: MSK
+    enabled: true
+  - code: VLOOP
+    enabled: true
+output:
+  - code: REVPREC
+    enabled: true
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/retail_orders/judges.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/retail_orders/judges.yaml
new file mode 100644
index 0000000..62fc7c7
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/retail_orders/judges.yaml
@@ -0,0 +1,7 @@
+judges:
+  - name: response_quality
+    enabled: true
+    threshold: 0.7
+  - name: groundedness
+    enabled: true
+    threshold: 0.6
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/retail_orders/prompt_policy.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/retail_orders/prompt_policy.yaml
new file mode 100644
index 0000000..f872a2b
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/retail_orders/prompt_policy.yaml
@@ -0,0 +1,6 @@
+id: retail_orders_prompt_policy
+version: 1
+description: Prompt base isolado do agente de varejo/pedidos.
+system_prefix: |
+  Você é um agente corporativo de varejo especializado em pedidos, entrega, troca, devolução e garantia.
+  Seja claro, objetivo e não use regras de negócio de telecom neste agente.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/telecom_contas/guardrails.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/telecom_contas/guardrails.yaml
new file mode 100644
index 0000000..9fe094a
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/telecom_contas/guardrails.yaml
@@ -0,0 +1,8 @@
+input:
+  - code: MSK
+    enabled: true
+  - code: VLOOP
+    enabled: true
+output:
+  - code: REVPREC
+    enabled: true
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/telecom_contas/judges.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/telecom_contas/judges.yaml
new file mode 100644
index 0000000..d488063
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/telecom_contas/judges.yaml
@@ -0,0 +1,20 @@
+enabled: true
+fail_closed: true
+profile: judge
+
+judges:
+  - name: response_quality
+    enabled: true
+    threshold: 0.7
+
+  - name: groundedness
+    enabled: true
+    threshold: 0.6
+
+  - name: sentiment
+    enabled: true
+    fail_on_negative: false
+
+  - name: tone
+    enabled: true
+    fail_closed: true
\ No newline at end of file
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/telecom_contas/prompt_policy.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/telecom_contas/prompt_policy.yaml
new file mode 100644
index 0000000..42732c4
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/agents/telecom_contas/prompt_policy.yaml
@@ -0,0 +1,6 @@
+id: telecom_contas_prompt_policy
+version: 1
+description: Prompt base isolado do agente de telecom/contas.
+system_prefix: |
+  Você é um agente corporativo de atendimento telecom especializado em faturas, produtos, VAS e suporte.
+  Seja claro, objetivo e não prometa execução operacional sem ferramenta ou confirmação válida.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/authentication.example.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/authentication.example.yaml
new file mode 100644
index 0000000..881e3c0
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/authentication.example.yaml
@@ -0,0 +1,39 @@
+# Nunca coloque secrets diretamente neste arquivo. Use sempre *_env.
+providers:
+  public:
+    mode: none
+
+  deny:
+    mode: deny
+
+  tia_basic:
+    mode: basic
+    client_id_env: TIA_AGENT_CLIENT_ID
+    secret_hash_env: TIA_AGENT_SECRET_HASH
+    realm: agent-contas
+
+  platform_jwt:
+    mode: jwt
+    key_env: PLATFORM_JWT_PUBLIC_KEY
+    algorithms: [RS256]
+    audience: agent-platform
+    issuer: https://identity.example.com/
+
+policies:
+  - name: health-public
+    provider: public
+    paths: [/health, /ready, /live]
+
+  - name: tia-agent-api
+    provider: tia_basic
+    paths: [/gateway/message, /gateway/message/sse, /gateway/events/*]
+    methods: [GET, POST]
+
+  - name: admin-api
+    provider: platform_jwt
+    paths: [/debug/*, /admin/*]
+    required_roles: [platform-admin]
+    required_scopes: [agent.admin]
+
+# Quando nenhuma política casar, rejeita. O default omitido também é deny.
+default_provider: deny
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/guardrails.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/guardrails.yaml
new file mode 100644
index 0000000..44887eb
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/guardrails.yaml
@@ -0,0 +1,12 @@
+input:
+  - code: MSK
+    enabled: true
+  - code: VLOOP
+    enabled: true
+output:
+  - code: REVPREC
+    enabled: true
+  - code: PINJ
+    enabled: true
+  - code: DLEX_OUT
+    enabled: true
\ No newline at end of file
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/identity.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/identity.yaml
new file mode 100644
index 0000000..5f20147
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/identity.yaml
@@ -0,0 +1,55 @@
+identity:
+  version: "2"
+  required:
+    - session_key
+  keys:
+    customer_key:
+      description: Cliente/assinante/consumidor canônico.
+      sources:
+        - business_context.customer_key
+        - customer_key
+        - msisdn
+        - customer_id
+        - user_id
+        - ani
+        - from
+    contract_key:
+      description: Contrato, conta, fatura, pedido ou asset principal.
+      sources:
+        - business_context.contract_key
+        - contract_key
+        - invoice_id
+        - current_invoice_number
+        - order_id
+        - pedido_id
+        - asset_id
+    interaction_key:
+      description: Chave externa da interação/call/chat vinda do canal.
+      sources:
+        - business_context.interaction_key
+        - interaction_key
+        - ura_call_id
+        - call_id
+        - message_id
+    account_key:
+      description: Conta de cobrança/conta comercial.
+      sources:
+        - business_context.account_key
+        - account_key
+        - account_id
+        - billing_account_id
+    resource_key:
+      description: Recurso/linha/produto/asset específico.
+      sources:
+        - business_context.resource_key
+        - resource_key
+        - asset_id
+        - product_id
+        - sku
+    session_key:
+      description: Sessão técnica estável já escopada por tenant e agente.
+      sources:
+        - business_context.session_key
+        - session_key
+        - conversation_key
+        - session_id
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/judges.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/judges.yaml
new file mode 100644
index 0000000..c091619
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/judges.yaml
@@ -0,0 +1,18 @@
+enabled: true
+fail_closed: true
+profile: judge
+judges:
+- name: response_quality
+  enabled: true
+  threshold: 0.7
+- name: groundedness
+  enabled: true
+  threshold: 0.6
+- name: sentiment
+  enabled: true
+  fail_on_negative: false
+- name: tone
+  enabled: true
+  fail_closed: true
+sample_rate: 0.25
+always_run_for_transactional: true
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/mcp_parameter_mapping.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/mcp_parameter_mapping.yaml
new file mode 100644
index 0000000..5b29ccf
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/mcp_parameter_mapping.yaml
@@ -0,0 +1,92 @@
+mcp_parameter_mapping:
+  defaults:
+    use_mock: true
+  tools:
+    consultar_fatura:
+      map:
+        customer_key: msisdn
+        contract_key: invoice_id
+        interaction_key: ura_call_id
+        session_key: session_id
+      extract:
+        mes_referencia:
+          from: message
+          type: int
+          strategy: month_name_pt
+          description: 'Extrair mês citado na mensagem. janeiro=1, fevereiro=2, março=3,
+            abril=4, maio=5, junho=6, julho=7, agosto=8, setembro=9, outubro=10, novembro=11,
+            dezembro=12.
+
+            '
+    consultar_pagamentos:
+      map:
+        customer_key: msisdn
+        interaction_key: ura_call_id
+        session_key: session_id
+    consultar_plano:
+      map:
+        customer_key: msisdn
+        resource_key: asset_id
+        contract_key: asset_id
+        session_key: session_id
+    listar_servicos:
+      map:
+        customer_key: msisdn
+        session_key: session_id
+    consultar_pedido:
+      map:
+        customer_key: customer_id
+        session_key: session_id
+      extract:
+        order_id:
+          from: message
+          type: string
+          strategy: hybrid
+          description: Extraia somente o identificador do pedido informado explicitamente
+            pelo usuário. Retorne null quando não houver identificador de pedido na
+            mensagem.
+          pattern: (?i)\\b(?:pedido|order)\\s*[:#-]?\\s*([A-Z0-9-]+)\\b
+          group: 1
+    consultar_entrega:
+      map:
+        session_key: session_id
+      extract:
+        order_id:
+          from: message
+          type: string
+          strategy: hybrid
+          description: Extraia somente o identificador do pedido informado explicitamente
+            pelo usuário. Retorne null quando não houver identificador de pedido na
+            mensagem.
+          pattern: (?i)\\b(?:pedido|order)\\s*[:#-]?\\s*([A-Z0-9-]+)\\b
+          group: 1
+    solicitar_troca:
+      map:
+        session_key: session_id
+      defaults:
+        reason: Solicitação aberta pelo atendimento conversacional.
+      extract:
+        order_id:
+          from: message
+          type: string
+          strategy: hybrid
+          description: Extraia somente o identificador do pedido informado explicitamente
+            pelo usuário. Retorne null quando não houver identificador de pedido na
+            mensagem.
+          pattern: (?i)\\b(?:pedido|order)\\s*[:#-]?\\s*([A-Z0-9-]+)\\b
+          group: 1
+    solicitar_devolucao:
+      map:
+        session_key: session_id
+      defaults:
+        reason: Solicitação aberta pelo atendimento conversacional.
+      extract:
+        order_id:
+          from: message
+          type: string
+          strategy: hybrid
+          description: Extraia somente o identificador do pedido informado explicitamente
+            pelo usuário. Retorne null quando não houver identificador de pedido na
+            mensagem.
+          pattern: (?i)\\b(?:pedido|order)\\s*[:#-]?\\s*([A-Z0-9-]+)\\b
+          group: 1
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/mcp_servers.docker.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/mcp_servers.docker.yaml
new file mode 100644
index 0000000..8101130
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/mcp_servers.docker.yaml
@@ -0,0 +1,12 @@
+servers:
+  telecom:
+    transport: http
+    endpoint: http://telecom-mcp:8100/mcp
+    enabled: true
+    description: MCP Server Telecom via docker-compose.
+
+  retail:
+    transport: http
+    endpoint: http://retail-mcp:8200/mcp
+    enabled: true
+    description: MCP Server Retail via docker-compose.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/mcp_servers.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/mcp_servers.yaml
new file mode 100644
index 0000000..fe638a2
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/mcp_servers.yaml
@@ -0,0 +1,30 @@
+# MCP servers registry.
+# transport=http keeps the legacy framework mock contract:
+#   GET  <endpoint>/tools/list
+#   POST <endpoint>/tools/call
+# transport=fastmcp uses official MCP Streamable HTTP, typically endpoint http://host:port/mcp
+# transport=sse uses official MCP SSE, typically endpoint http://host:port/sse
+servers:
+  #  telecom:
+  #    enabled: true
+  #    transport: fastmcp
+  #    endpoint: http://localhost:8001/mcp
+  #    description: Telecom FastMCP server using official MCP protocol
+  #
+  #  retail:
+  #    enabled: true
+  #    transport: fastmcp
+  #    endpoint: http://localhost:8002/mcp
+  #    description: Retail FastMCP server using official MCP protocol
+
+  telecom:
+    enabled: true
+    transport: http
+    endpoint: http://localhost:8100/mcp
+    description: Telecom legacy HTTP mock MCP server
+
+  retail:
+    enabled: true
+    transport: http
+    endpoint: http://localhost:8200/mcp
+    description: Retail legacy HTTP mock MCP server
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/prompt_policy.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/prompt_policy.yaml
new file mode 100644
index 0000000..af4398f
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/prompt_policy.yaml
@@ -0,0 +1,19 @@
+tone:
+  style: "claro, objetivo, empático"
+  forbidden_phrases:
+    - "procure atendimento humano"
+vocabulary:
+  preferred:
+    fatura: "fatura"
+    contestacao: "contestação"
+intents:
+  billing_agent:
+    - fatura
+    - boleto
+    - cobrança
+    - segunda via
+  product_agent:
+    - plano
+    - produto
+    - oferta
+    - serviço
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/routing.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/routing.yaml
new file mode 100644
index 0000000..2dbe95e
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/routing.yaml
@@ -0,0 +1,128 @@
+# Roteamento enterprise configurável com MCP-aware intents.
+router:
+  # mode também pode ser definido por variável de ambiente ROUTING_MODE.
+  # Valores: router | supervisor
+  mode: router
+  fallback_agent: billing_agent
+  confidence_threshold: 0.65
+  allow_handoff: true
+
+state_policies:
+  - state: WAITING_BILLING_CONFIRMATION
+    agent: billing_agent
+    description: Mantém mensagens curtas como "sim" ou "não" no fluxo de fatura.
+  - state: WAITING_PRODUCT_CONFIRMATION
+    agent: product_agent
+    description: Mantém confirmações no fluxo de produtos/serviços.
+  - state: WAITING_ORDER_CONFIRMATION
+    agent: orders_agent
+    description: Mantém confirmações no fluxo de pedidos.
+  - state: WAITING_SUPPORT_CONFIRMATION
+    agent: support_agent
+    description: Mantém confirmações no fluxo de suporte retail.
+  - state: COLLECTING_BILLING_PARAMETERS
+    agent: billing_agent
+    description: Mantém a coleta de parâmetros no fluxo de faturamento.
+  - state: COLLECTING_PRODUCT_PARAMETERS
+    agent: product_agent
+    description: Mantém a coleta de parâmetros no fluxo de produtos e serviços.
+  - state: COLLECTING_ORDER_PARAMETERS
+    agent: orders_agent
+    description: Mantém a coleta de parâmetros no fluxo de pedidos.
+  - state: COLLECTING_SUPPORT_PARAMETERS
+    agent: support_agent
+    description: Mantém a coleta de parâmetros no fluxo transacional de suporte retail.
+
+intents:
+  - name: billing_invoice_explanation
+    domain: telecom
+    agent: billing_agent
+    description: Dúvidas sobre fatura, cobrança, vencimento, segunda via, contestação e valores.
+    priority: 10
+    mcp_tools:
+      - consultar_fatura
+      - consultar_pagamentos
+    keywords:
+      - fatura
+      - conta
+      - cobrança
+      - boleto
+      - vencimento
+      - segunda via
+      - contestar
+      - valor alto
+      - invoice
+    examples:
+      - Minha fatura veio alta.
+      - Quero entender uma cobrança.
+      - Preciso da segunda via da conta.
+
+  - name: product_services_information
+    domain: telecom
+    agent: product_agent
+    description: Dúvidas sobre plano, pacote, produto, serviço, VAS, internet, roaming e benefícios.
+    priority: 20
+    mcp_tools:
+      - consultar_plano
+      - listar_servicos
+    keywords:
+      - plano
+      - serviço
+      - pacote
+      - internet
+      - roaming
+      - vas
+      - benefício
+      - assinatura
+    examples:
+      - Quais serviços estão ativos no meu plano?
+      - Quero saber sobre meu pacote de internet.
+      - Tenho roaming internacional?
+
+  - name: retail_order_tracking
+    domain: retail
+    agent: orders_agent
+    description: Consulta de pedido, entrega, rastreamento, atraso e status de compra.
+    priority: 30
+    mcp_tools:
+      - consultar_pedido
+      - consultar_entrega
+    keywords:
+      - pedido
+      - entrega
+      - rastreio
+      - rastreamento
+      - encomenda
+      - compra
+      - atraso
+      - correios
+    examples:
+      - Meu pedido não chegou.
+      - Quero rastrear minha entrega.
+      - Qual é o status da minha compra?
+
+  - name: retail_support_exchange_return
+    domain: retail
+    agent: support_agent
+    description: Suporte, troca, devolução, garantia e problema com produto.
+    priority: 25
+    mcp_tools:
+      - consultar_pedido
+      - solicitar_troca
+      - solicitar_devolucao
+    keywords:
+      - solicitar devolução
+      - devolver pedido
+      - solicitar troca
+      - troca
+      - devolução
+      - devolver
+      - garantia
+      - defeito
+      - produto quebrado
+      - suporte
+      - arrependimento
+    examples:
+      - Quero trocar um produto.
+      - Meu produto veio com defeito.
+      - Como faço uma devolução?
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/tool_policies.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/tool_policies.yaml
new file mode 100644
index 0000000..3c4fd05
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/tool_policies.yaml
@@ -0,0 +1,26 @@
+version: 1
+
+# Arquivo opcional da aplicação. A ausência mantém o comportamento dos
+# templates anteriores e as políticas legadas declaradas em tools.yaml.
+defaults:
+  operation_type: read_only
+  require_confirmation: false
+
+tool_policies:
+  solicitar_troca:
+    operation_type: transactional
+    require_confirmation: true
+
+  solicitar_devolucao:
+    operation_type: transactional
+    require_confirmation: true
+    requires: [order_id, reason]
+    execution:
+      mode: workflow
+      workflow: devolucao_pedido
+      version: active
+
+# Exemplo para uma operação real que só pode executar após confirmação:
+#  cancelar_servico:
+#    operation_type: transactional
+#    require_confirmation: true
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/config/tools.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/tools.yaml
new file mode 100644
index 0000000..d85fae1
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/config/tools.yaml
@@ -0,0 +1,101 @@
+tools:
+  consultar_fatura:
+    description: Consulta dados resumidos de fatura por msisdn/invoice_id.
+    mcp_server: telecom
+    enabled: true
+    args_schema:
+      msisdn: string
+      invoice_id: string
+    selection_keywords:
+    - fatura
+    - conta
+    - boleto
+  consultar_pagamentos:
+    description: Consulta histórico de pagamentos do cliente.
+    mcp_server: telecom
+    enabled: true
+    args_schema:
+      msisdn: string
+    selection_keywords:
+    - pagamento
+    - pagamentos
+  consultar_plano:
+    description: Consulta plano ativo e atributos comerciais.
+    mcp_server: telecom
+    enabled: true
+    args_schema:
+      msisdn: string
+      asset_id: string
+    selection_keywords:
+    - plano
+  listar_servicos:
+    description: Lista serviços ativos e adicionais VAS.
+    mcp_server: telecom
+    enabled: true
+    args_schema:
+      msisdn: string
+    selection_keywords:
+    - serviços
+    - servicos
+    - vas
+  consultar_pedido:
+    description: Consulta pedido de varejo por order_id/customer_id.
+    mcp_server: retail
+    enabled: true
+    args_schema:
+      order_id: string
+      customer_id: string
+    selection_keywords:
+    - consultar pedido
+    - status do pedido
+    - pedido
+  consultar_entrega:
+    description: Consulta entrega e rastreamento do pedido.
+    mcp_server: retail
+    enabled: true
+    args_schema:
+      order_id: string
+    selection_keywords:
+    - entrega
+    - rastreio
+    - rastreamento
+    - transportadora
+    - previsão
+  solicitar_troca:
+    description: Simula abertura de solicitação de troca.
+    mcp_server: retail
+    enabled: true
+    tool_type: action
+    requires:
+    - order_id
+    - reason
+    confirmation_required: true
+    args_schema:
+      order_id: string
+      reason: string
+    selection_keywords:
+    - solicitar troca
+    - trocar
+    - troca
+    - defeito
+    - quebrado
+  solicitar_devolucao:
+    description: Simula abertura de solicitação de devolução.
+    mcp_server: retail
+    enabled: true
+    tool_type: action
+    requires:
+    - order_id
+    - reason
+    confirmation_required: true
+    args_schema:
+      order_id: string
+      reason: string
+    selection_keywords:
+    - solicitar devolução
+    - solicitar devolucao
+    - devolver pedido
+    - devolver
+    - devolução
+    - devolucao
+    - arrependimento
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/ATUALIZACAO_TEMPLATE_ANALYTICS_OUTPUT_SUPERVISOR.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/ATUALIZACAO_TEMPLATE_ANALYTICS_OUTPUT_SUPERVISOR.md
new file mode 100644
index 0000000..d81efdf
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/ATUALIZACAO_TEMPLATE_ANALYTICS_OUTPUT_SUPERVISOR.md
@@ -0,0 +1,95 @@
+# Atualização do Template Backend — Analytics, Observer, NOC/GRL e OutputSupervisor
+
+Esta versão do `agent_template_backend` foi atualizada para consumir as novidades transportadas para o `agent_framework`.
+
+## 1. Analytics e Pub/Sub
+
+O backend não chama mais diretamente apenas o publisher antigo de eventos. Agora ele cria um `AnalyticsPublisher`:
+
+```python
+from agent_framework.analytics.factory import create_analytics_publisher
+from agent_framework.observability.observer import AgentObserver
+
+analytics = create_analytics_publisher(settings)
+observer = AgentObserver(analytics=analytics)
+```
+
+Com isso, o mesmo backend pode publicar em:
+
+- OCI Streaming
+- GCP Pub/Sub
+- CompositePublisher, quando `ANALYTICS_PROVIDERS=oci_streaming,pubsub`
+- Noop, quando analytics estiver desligado
+
+## 2. Configuração mínima
+
+```env
+ENABLE_ANALYTICS=true
+ANALYTICS_PROVIDERS=pubsub
+GCP_PUBSUB_TOPIC_PATH=projects/<project-id>/topics/<topic-name>
+GOOGLE_APPLICATION_CREDENTIALS=/secrets/gcp-service-account.json
+```
+
+Para publicar simultaneamente em OCI Streaming e GCP Pub/Sub:
+
+```env
+ENABLE_ANALYTICS=true
+ANALYTICS_PROVIDERS=oci_streaming,pubsub
+ENABLE_OCI_STREAMING=true
+OCI_STREAM_ENDPOINT=<endpoint>
+OCI_STREAM_OCID=<stream-ocid>
+GCP_PUBSUB_TOPIC_PATH=projects/<project-id>/topics/<topic-name>
+```
+
+## 3. Observer corporativo
+
+O workflow recebeu emissão automática dos principais eventos corporativos:
+
+- `NOC.001`: início do workflow
+- `NOC.005`: exceção fatal no workflow
+- `NOC.006`: fim do workflow antes da resposta final
+- `IC.AGENT_COMPLETED`: evento informacional de conclusão
+- `GRL.001` a `GRL.009`: emitidos pelo `OutputSupervisor`
+
+## 4. OutputSupervisor
+
+Foi inserido um novo nó LangGraph:
+
+```text
+agent -> output_supervisor -> output_guardrails -> judge -> supervisor_review -> persist
+```
+
+O `OutputSupervisor` não substitui o supervisor de roteamento. Ele valida a saída candidata do agente usando o contrato corporativo:
+
+- `allow`
+- `sanitize`
+- `retry`
+- `block`
+- `handover`
+- `observe`
+
+Para compatibilidade com os guardrails já existentes, o template inclui o adapter `LegacyOutputGuardrailRail`, que converte decisões antigas `allowed=True/False` para `RailAction`.
+
+## 5. Campos adicionados ao AgentState
+
+```python
+supervisor_action: str
+supervisor_guidance: str
+supervisor_attempt: int
+supervisor_handover_reason: str
+output_supervisor_results: list[dict]
+output_guardrails_already_applied: bool
+```
+
+## 6. Arquivos alterados
+
+- `agent_template_backend/app/main.py`
+- `agent_template_backend/app/workflows/agent_graph.py`
+- `agent_template_backend/app/state.py`
+- `agent_template_backend/.env`
+- `agent_template_backend/requirements.txt`
+- `agent_framework/src/agent_framework/config/settings.py`
+
+## 7. Observação importante
+
+O `OutputSupervisor` roda os guardrails de saída por meio do adapter legado e marca `output_guardrails_already_applied=True`. Assim o nó `output_guardrails` permanece no grafo para compatibilidade, mas evita reexecutar a mesma validação quando o supervisor já aplicou os rails.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/COMO_USAR_IC_NOC_GRL_NO_TEMPLATE.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/COMO_USAR_IC_NOC_GRL_NO_TEMPLATE.md
new file mode 100644
index 0000000..83975af
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/COMO_USAR_IC_NOC_GRL_NO_TEMPLATE.md
@@ -0,0 +1,45 @@
+# Como usar IC, NOC e GRL no Template Backend
+
+## IC — Item de Controle
+
+Use IC para registrar eventos de negócio relevantes.
+
+```python
+await observer.emit_ic(
+    "IC.FATURA_CONSULTADA",
+    {"session_id": session_id, "invoice_id": invoice_id},
+    component="billing_agent",
+)
+```
+
+## NOC — Evento operacional
+
+Use NOC para saúde técnica, latência, erros e checkpoints operacionais.
+
+```python
+await observer.emit_noc(
+    "003",
+    {"session_id": session_id, "resourceName": "ADB", "latencyMs": 120},
+    component="repository",
+)
+```
+
+## GRL — Evento de guardrail
+
+Normalmente o framework emite GRL automaticamente. Use manualmente apenas para
+rails customizados dentro do agente.
+
+```python
+await observer.emit_grl(
+    "OBSERVE",
+    {"session_id": session_id, "rail_code": "CUSTOM_POLICY"},
+    component="custom_rail",
+)
+```
+
+## Onde já existe no template
+
+- `app/workflows/agent_graph.py` emite IC/NOC no ciclo do workflow.
+- `app/agents/runtime.py` emite IC para MCP/tools.
+- `app/agents/*_agent.py` contém exemplos dentro do método `run()`.
+- `app/examples/` contém exemplos isolados.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/CONVERSATION_SUMMARY_MEMORY_BACKEND.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/CONVERSATION_SUMMARY_MEMORY_BACKEND.md
new file mode 100644
index 0000000..3f981ac
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/CONVERSATION_SUMMARY_MEMORY_BACKEND.md
@@ -0,0 +1,48 @@
+# Backends atualizados para ConversationSummaryMemory
+
+Esta versão dos backends foi compatibilizada com a versão do framework que adiciona `ConversationSummaryMemory`.
+
+## O que mudou
+
+- `app/main.py` agora inicializa `create_conversation_summary_memory(...)` junto com `create_memory(...)`.
+- `AgentWorkflow` recebe `summary_memory` e repassa para os agentes.
+- Os agentes não montam mais prompts manuais para o LLM; agora usam `build_messages()` do framework.
+- Antes da chamada ao LLM, os agentes executam `await self.prepare_memory_context(state)`.
+- Quando habilitado por `.env`, o prompt passa a receber:
+  - resumo acumulado da conversa;
+  - últimas mensagens completas;
+  - mensagem atual;
+  - BusinessContext;
+  - MCP results;
+  - RAG context e metadata.
+
+## Configuração
+
+```env
+ENABLE_CONVERSATION_SUMMARY_MEMORY=true
+MEMORY_CONTEXT_STRATEGY=summary
+MEMORY_HISTORY_LIMIT=80
+MEMORY_RECENT_MESSAGES_LIMIT=8
+MEMORY_SUMMARY_TRIGGER_MESSAGES=20
+MEMORY_MAX_SUMMARY_CHARS=6000
+MEMORY_SUMMARY_USE_LLM=true
+MEMORY_INJECT_RECENT_MESSAGES=true
+MEMORY_INJECT_SUMMARY=true
+```
+
+## Backends alterados
+
+- `backoffice_convertido_framework`
+- `agent_template_backend`
+- `agent_template_backend_day_zero`
+
+## Observação importante
+
+Estes backends esperam que o pacote `agent_framework` instalado/conectado seja a versão com os módulos:
+
+- `agent_framework.memory.summary_memory`
+- `agent_framework.memory.summary_store`
+- `AgentRuntimeMixin.prepare_memory_context()`
+- `AgentRuntimeMixin.build_messages()` com injeção de memória
+
+Use junto com o ZIP `agent_framework_conversation_summary_memory.zip`.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/EXEMPLOS_ROUTE_HANDOFF_TRANSACOES.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/EXEMPLOS_ROUTE_HANDOFF_TRANSACOES.md
new file mode 100644
index 0000000..5c41732
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/EXEMPLOS_ROUTE_HANDOFF_TRANSACOES.md
@@ -0,0 +1,14 @@
+# Exemplos implementados no template
+
+Este projeto entrega as capacidades transversais habilitadas como referência:
+
+- route stickiness semântica com o perfil `route_continuity`;
+- decisões `CONTINUE`, `ROUTE`, `HUMAN_HANDOFF` e `END_SESSION`;
+- nós globais `human_handoff` e `end_session`;
+- persistência de `active_agent`, `route_bypassed`, `continuity_signal` e controle de sessão;
+- rejeição de novas mensagens depois de `session_ended=true`;
+- políticas MCP `read_only` e `transactional` no backend;
+- exemplo `solicitar_devolucao` com `require_confirmation: true`.
+
+Para confirmar a transação, envie `confirmed: true` ou `confirmation: true` como booleano. Handoff e encerramento não chamam agentes de domínio nem MCP.
+
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/FRAMEWORK_CHANNEL_INPUT_MODE.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/FRAMEWORK_CHANNEL_INPUT_MODE.md
new file mode 100644
index 0000000..c7bd3b2
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/FRAMEWORK_CHANNEL_INPUT_MODE.md
@@ -0,0 +1,84 @@
+# FRAMEWORK_CHANNEL_INPUT_MODE
+
+This backend setting controls what kind of channel input the Agent Framework backend accepts.
+
+It replaces the ambiguous use of `CHANNEL_GATEWAY_MODE` inside the backend.
+
+## Values
+
+```env
+FRAMEWORK_CHANNEL_INPUT_MODE=embedded
+```
+
+The backend may use internal channel adapters to interpret simple/native channel payloads. This is useful for demos, labs, local frontend, curl tests, and simple environments.
+
+```env
+FRAMEWORK_CHANNEL_INPUT_MODE=external
+```
+
+The backend accepts only a normalized `GatewayRequest` produced by an external Channel Gateway. It does not parse native WhatsApp, Voice, Teams, or other channel payloads.
+
+## Recommended enterprise setup
+
+In the external channel gateway service:
+
+```env
+CHANNEL_GATEWAY_RUNTIME_MODE=adapter
+```
+
+In this backend:
+
+```env
+FRAMEWORK_CHANNEL_INPUT_MODE=external
+```
+
+Flow:
+
+```text
+External channel / browser / customer adapter
+  ↓
+channel_gateway:7000
+  CHANNEL_GATEWAY_RUNTIME_MODE=adapter
+  ↓ GatewayRequest
+agent_template_backend:8000
+  FRAMEWORK_CHANNEL_INPUT_MODE=external
+  ↓
+LangGraph / Agents / MCP / Guardrails
+```
+
+## Valid direct request to backend in external mode
+
+```bash
+curl -s -X POST "http://localhost:8000/gateway/message" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "web",
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "payload": {
+      "message": "Quero consultar minha fatura",
+      "session_id": "backend-external-ok-001"
+    }
+  }' | jq
+```
+
+## Invalid direct request to backend in external mode
+
+```bash
+curl -i -s -X POST "http://localhost:8000/gateway/message" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Quero consultar minha fatura",
+    "session_id": "raw-payload-error-001"
+  }'
+```
+
+Expected result: HTTP 422.
+
+## Legacy compatibility
+
+`CHANNEL_GATEWAY_MODE` is still present as a legacy alias for older environments, but new deployments should use:
+
+```env
+FRAMEWORK_CHANNEL_INPUT_MODE=embedded|external
+```
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/GUARDRAILS_PARALLELOS_OBSERVER_IC.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/GUARDRAILS_PARALLELOS_OBSERVER_IC.md
new file mode 100644
index 0000000..849fda1
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/GUARDRAILS_PARALLELOS_OBSERVER_IC.md
@@ -0,0 +1,127 @@
+# Guardrails paralelos fail-fast e Observer IC
+
+## O que foi implementado
+
+### 1. ParallelRailExecutor
+
+Arquivo principal:
+
+```text
+agent_framework/src/agent_framework/guardrails/parallel_executor.py
+```
+
+Também foi criado um alias de compatibilidade:
+
+```text
+agent_framework/src/agent_framework/guardrails/executor.py
+```
+
+Esse alias evita erro quando algum código antigo importar:
+
+```python
+from agent_framework.guardrails.executor import ParallelRailExecutor
+```
+
+### 2. Execução paralela no GuardrailPipeline
+
+Arquivo alterado:
+
+```text
+agent_framework/src/agent_framework/guardrails/pipeline.py
+```
+
+O pipeline continua retornando o contrato antigo:
+
+```python
+(texto_final, list[RailDecision])
+```
+
+mas internamente pode executar rails em paralelo com fail-fast.
+
+### 3. Execução paralela no OutputSupervisor
+
+Arquivo alterado:
+
+```text
+agent_framework/src/agent_framework/guardrails/output_supervisor.py
+```
+
+O `OutputSupervisor` agora usa `ParallelRailExecutor` quando habilitado.
+
+### 4. Configuração
+
+Novas configurações:
+
+```env
+ENABLE_PARALLEL_GUARDRAILS=true
+GUARDRAILS_FAIL_FAST=true
+```
+
+Também foram adicionadas em:
+
+```text
+agent_framework/src/agent_framework/config/settings.py
+.env
+.env.example
+agent_template_backend/.env
+agent_template_backend_day_zero/.env
+```
+
+### 5. Observer IC
+
+O `AgentObserver` já tinha `emit_ic()`.
+
+Foi complementada a API global compatível com FIRST/TIM:
+
+```python
+from agent_framework.observer import ic, aic, noc, anoc, grl, agrl
+```
+
+Exemplos:
+
+```python
+ic("AGENT_COMPLETED", data={"session_id": "..."})
+await aic("MCP_TOOL_CALLED", data={"tool_name": "consultar_fatura"})
+```
+
+### 6. ICs automáticos no template backend
+
+O backend emite agora:
+
+```text
+IC.AGENT_STARTED
+IC.ROUTE_SELECTED
+IC.MCP_TOOL_CALLED
+IC.TOOL_CALLED
+IC.AGENT_COMPLETED
+```
+
+Além dos eventos já existentes:
+
+```text
+NOC.001
+NOC.005
+NOC.006
+GRL.001 ... GRL.009
+```
+
+## Validações executadas
+
+Foram executadas validações locais com `PYTHONPATH=agent_framework/src`:
+
+```bash
+python3 -m compileall -q agent_framework/src/agent_framework agent_template_backend/app agent_template_backend_day_zero/app
+```
+
+Smoke tests executados:
+
+```text
+1. Import de ParallelRailExecutor via agent_framework.guardrails
+2. Import de ParallelRailExecutor via agent_framework.guardrails.executor
+3. Execução fail-fast: FastBlock cancela SlowAllow
+4. GuardrailPipeline paralelo retorna RailDecision legado
+5. OutputSupervisor paralelo retorna RailAction.BLOCK
+6. API global observer.ic/noc/grl/aic/anoc/agrl
+```
+
+Observação: o import completo do `agent_template_backend.app.workflows.agent_graph` depende de `langgraph`, que não está instalado no sandbox de validação. O arquivo foi validado por `compileall`, e a dependência já consta em `agent_template_backend/requirements.txt`.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/IMPLEMENTACAO_IC_NOC_GRL_SEM_REMOVER_LOGICA.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/IMPLEMENTACAO_IC_NOC_GRL_SEM_REMOVER_LOGICA.md
new file mode 100644
index 0000000..edcd2c7
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/IMPLEMENTACAO_IC_NOC_GRL_SEM_REMOVER_LOGICA.md
@@ -0,0 +1,42 @@
+# Implementação IC/NOC/GRL preservando lógica existente
+
+Esta versão mantém a lógica original dos agentes do `agent_template_backend` e adiciona observabilidade corporativa.
+
+## IC adicionados nos agentes
+
+Cada agente agora emite eventos de negócio sem alterar a resposta final:
+
+- `IC.BILLING_AGENT_STARTED` / `IC.BILLING_AGENT_COMPLETED`
+- `IC.ORDERS_AGENT_STARTED` / `IC.ORDERS_AGENT_COMPLETED`
+- `IC.PRODUCT_AGENT_STARTED` / `IC.PRODUCT_AGENT_COMPLETED`
+- `IC.SUPPORT_AGENT_STARTED` / `IC.SUPPORT_AGENT_COMPLETED`
+- `IC.<AGENT>_MCP_CONTEXT_COLLECTED` quando houver dados MCP
+- `IC.<AGENT>_RAG_CONTEXT_RETRIEVED` quando RAG estiver habilitado
+
+O mixin `AgentRuntimeMixin` também emite:
+
+- `IC.MCP_TOOL_CALLED` antes da chamada MCP
+- `IC.TOOL_CALLED` após a chamada MCP
+
+## NOC
+
+O workflow já emite eventos operacionais principais:
+
+- `NOC.001` no início da execução
+- `NOC.005` em exceção fatal
+- `NOC.006` na persistência/finalização
+
+## GRL
+
+O backend agora também exemplifica emissão GRL no workflow:
+
+- `GRL.001` início do pipeline de guardrails
+- `GRL.002` decisão allow
+- `GRL.004` decisão block
+- `GRL.009` decisão final agregada
+
+Quando `OutputSupervisor` está habilitado, ele continua sendo o principal mecanismo corporativo de supervisão de saída.
+
+## Garantia
+
+A lógica original dos agentes não foi substituída por stubs. As chamadas LLM, MCP, RAG, cache e os retornos originais foram preservados.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/LANGFUSE_SINGLE_TRACE_OBSERVER_FIX.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/LANGFUSE_SINGLE_TRACE_OBSERVER_FIX.md
new file mode 100644
index 0000000..bc2638b
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/LANGFUSE_SINGLE_TRACE_OBSERVER_FIX.md
@@ -0,0 +1,5 @@
+# Langfuse single trace observer fix
+
+This backend now uses `TelemetryBackedAgentObserver` instead of publishing IC/NOC/GRL through `AgentObserver(analytics=...)`.
+
+Why: when analytics includes the Langfuse provider, observer events such as `IC.AGENT_COMPLETED` and `NOC.006` may create a second root trace with little detail. Emitting those events through `Telemetry.event(...)` keeps them inside the active request/workflow trace.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/MANUAL_AUTENTICACAO.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/MANUAL_AUTENTICACAO.md
new file mode 100644
index 0000000..b0e1395
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/MANUAL_AUTENTICACAO.md
@@ -0,0 +1,253 @@
+# Manual geral de autenticação do Agent Framework OCI
+
+> [!IMPORTANT]
+> **Template de referência — requer adequação antes do uso produtivo.**
+> Esta implementação demonstra pontos de extensão, providers, middleware e exemplos de configuração para autenticação. Ela não deve ser considerada uma solução pronta para produção nem substitui o desenho de segurança do projeto. Antes da implantação, a equipe responsável deve revisar, testar e adaptar o código às políticas corporativas, ao modelo de identidade, à topologia de rede, à gestão e rotação de segredos, aos requisitos regulatórios, à observabilidade, à alta disponibilidade e ao processo de resposta a incidentes do ambiente do cliente. Recomenda-se executar security review, threat modeling, testes de integração e testes de segurança antes da homologação e da produção.
+## 1. Princípio arquitetural
+
+A autenticação é uma capacidade transversal, opcional e reutilizável. Ela não depende da presença do `agent_gateway` ou do `mcp_gateway` e pode ser instalada em qualquer aplicação FastAPI que exponha uma fronteira protegida.
+
+```text
+agent_framework.security
+  ├── backend independente de agente
+  ├── agent_gateway
+  ├── mcp_gateway
+  ├── channel_gateway
+  ├── MCP Server
+  └── aplicação customizada
+```
+
+O framework fornece providers, middleware, instalação por configuração e políticas por rota. Cada projeto ou deployment decide onde ativar e qual mecanismo usar.
+
+## 2. Onde autenticar
+
+| Arquitetura | Ponto principal de autenticação |
+|---|---|
+| TIA → Agente Contas diretamente | backend do Agente Contas |
+| TIA → Agent Gateway → Agente | Agent Gateway; backend deve ficar inacessível externamente ou usar autenticação interna |
+| Agente → MCP Gateway → MCP Servers | MCP Gateway, com autorização adicional por agente e ferramenta |
+| Agente → MCP Server diretamente | MCP Server |
+
+Autenticar no gateway só libera o backend de autenticação externa quando o acesso direto ao backend é bloqueado por rede, `ClusterIP`, NetworkPolicy, security group, service mesh ou mTLS.
+
+## 3. Instalação no código
+
+Use a mesma função em qualquer app FastAPI, mudando apenas o prefixo:
+
+```python
+from fastapi import FastAPI
+from agent_framework.security import install_authentication
+
+app = FastAPI()
+install_authentication(app, prefix="AGENT_AUTH")
+```
+
+Integrações fornecidas neste pacote:
+
+```python
+# Backend independente/template de autenticação
+install_authentication(app, prefix="AGENT_AUTH")
+
+# apps/agent_gateway
+install_authentication(app, prefix="AGENT_GATEWAY_AUTH")
+
+# apps/mcp_gateway
+install_authentication(app, prefix="MCP_GATEWAY_AUTH")
+```
+
+A autenticação permanece opcional. Sem ativação, o comportamento original da aplicação é preservado.
+
+## 4. Providers disponíveis
+
+| Modo | Uso típico |
+|---|---|
+| `none` | rota pública ou desenvolvimento local |
+| `deny` | rejeição explícita/default seguro em políticas |
+| `basic` | integração system-to-system controlada, como TIA → Contas |
+| `api_key` | integração simples entre serviços |
+| `bearer_static` | token estático com rotação |
+| `jwt` | access token JWT emitido por OAuth2/OIDC |
+| `oauth2_introspection` | token opaco validado no authorization server |
+| `trusted_proxy` | identidade validada por API Gateway, ingress ou service mesh |
+
+mTLS deve ser terminado no ingress, API Gateway ou service mesh. A identidade resultante pode ser encaminhada com `trusted_proxy`, desde que o acesso direto e os headers internos sejam protegidos.
+
+## 5. Configuração simples com um provider por aplicação
+
+### Agente independente com Basic
+
+```bash
+AGENT_AUTH_ENABLED=true
+AGENT_AUTH_MODE=basic
+AGENT_AUTH_BASIC_CLIENT_ID=tia-contas
+AGENT_AUTH_BASIC_SECRET_HASH=pbkdf2_sha256:310000:<salt>:<digest>
+AGENT_AUTH_BASIC_REALM=agent-contas
+AGENT_AUTH_PUBLIC_PATHS=/health
+```
+
+### Agent Gateway com JWT
+
+```bash
+AGENT_GATEWAY_AUTH_ENABLED=true
+AGENT_GATEWAY_AUTH_MODE=jwt
+AGENT_GATEWAY_AUTH_JWT_KEY=<public-key-pem>
+AGENT_GATEWAY_AUTH_JWT_ALGORITHMS=RS256
+AGENT_GATEWAY_AUTH_JWT_AUDIENCE=agent-gateway
+AGENT_GATEWAY_AUTH_JWT_ISSUER=https://identity.example.com/
+AGENT_GATEWAY_AUTH_PUBLIC_PATHS=/health,/ready,/live
+```
+
+### MCP Gateway com token de serviço
+
+```bash
+MCP_GATEWAY_AUTH_ENABLED=true
+MCP_GATEWAY_AUTH_MODE=bearer_static
+MCP_GATEWAY_AUTH_BEARER_TOKEN_HASH=sha256:<digest>
+MCP_GATEWAY_AUTH_BEARER_PRINCIPAL=agent-platform
+MCP_GATEWAY_AUTH_PUBLIC_PATHS=/health
+```
+
+## 6. Políticas por rota
+
+Use um arquivo YAML quando uma aplicação precisar de providers ou requisitos diferentes por endpoint:
+
+```bash
+AGENT_AUTH_ENABLED=true
+AGENT_AUTH_POLICIES_FILE=config/authentication.yaml
+```
+
+Para gateways, use respectivamente:
+
+```bash
+AGENT_GATEWAY_AUTH_POLICIES_FILE=config/authentication.yaml
+MCP_GATEWAY_AUTH_POLICIES_FILE=config/authentication.yaml
+```
+
+Exemplo:
+
+```yaml
+providers:
+  public:
+    mode: none
+
+  deny:
+    mode: deny
+
+  tia_basic:
+    mode: basic
+    client_id_env: TIA_AGENT_CLIENT_ID
+    secret_hash_env: TIA_AGENT_SECRET_HASH
+    realm: agent-contas
+
+  platform_jwt:
+    mode: jwt
+    key_env: PLATFORM_JWT_PUBLIC_KEY
+    algorithms: [RS256]
+    audience: agent-platform
+    issuer: https://identity.example.com/
+
+policies:
+  - name: health-public
+    provider: public
+    paths: [/health, /ready, /live]
+
+  - name: tia-messages
+    provider: tia_basic
+    paths: [/gateway/message, /gateway/message/sse, /gateway/events/*]
+
+  - name: administration
+    provider: platform_jwt
+    paths: [/debug/*, /admin/*]
+    required_roles: [platform-admin]
+    required_scopes: [agent.admin]
+
+default_provider: deny
+```
+
+As políticas são avaliadas na ordem declarada; a primeira correspondência vence. Os paths usam padrões glob, como `/gateway/events/*`. Quando `default_provider` é omitido, o comportamento é `deny`.
+
+Secrets nunca devem ser gravados no YAML. Use campos como `secret_hash_env`, `key_env` e `client_secret_env`.
+
+Arquivos de exemplo:
+
+- `Tuning-Performance/Authentication/authentication_policies.example.yaml`
+- `apps/agent_gateway/config/authentication.example.yaml`
+- `apps/mcp_gateway/config/authentication.example.yaml`
+- `agent_template_backend_authentication/config/authentication.example.yaml`
+
+## 7. Roles e scopes
+
+Após autenticar, o middleware extrai roles de `roles`, `role` ou `groups`, e scopes de `scope`, `scp` ou `scopes`. Requisitos ausentes retornam `403 Forbidden`.
+
+```yaml
+required_roles: [platform-admin]
+required_scopes: [agent.admin]
+```
+
+Basic, API Key e tokens estáticos identificam o consumidor, mas não produzem roles/scopes por padrão. Para autorização granular, use JWT/OAuth2, um provider customizado ou uma camada de autorização específica.
+
+No MCP Gateway, autenticação não substitui a autorização por `agent_id`, tenant, ferramenta e tipo de operação.
+
+## 8. Azure DevOps, Azure Key Vault e Kubernetes
+
+O pipeline recupera secrets do Azure Key Vault e os injeta no deployment. O framework não chama Azure DevOps nem Key Vault diretamente.
+
+```yaml
+env:
+  - name: AGENT_AUTH_ENABLED
+    value: "true"
+  - name: AGENT_AUTH_MODE
+    value: basic
+  - name: AGENT_AUTH_BASIC_CLIENT_ID
+    valueFrom:
+      secretKeyRef:
+        name: contas-auth
+        key: client-id
+  - name: AGENT_AUTH_BASIC_SECRET_HASH
+    valueFrom:
+      secretKeyRef:
+        name: contas-auth
+        key: secret-hash
+```
+
+No cenário TIA → Contas, o TIA mantém o secret original e o agente pode armazenar somente o hash de validação.
+
+## 9. Provider customizado
+
+Um provider específico implementa somente:
+
+```python
+class AuthenticationProvider(Protocol):
+    async def authenticate(self, request: Request) -> AuthenticationResult: ...
+```
+
+Nomes e regras particulares de TIA, GStreamer, TIM, Azure ou outro cliente devem ficar no projeto do cliente. A biblioteca deve permanecer genérica.
+
+## 10. Testes rápidos
+
+Sem credencial:
+
+```bash
+curl -i http://localhost:8000/gateway/message
+```
+
+Basic:
+
+```bash
+curl -i -u 'tia-contas:secret-original' \
+  -H 'Content-Type: application/json' \
+  -d '{"channel":"web","payload":{"text":"Olá","session_id":"auth-test","user_id":"tia"}}' \
+  http://localhost:8000/gateway/message
+```
+
+## 11. Requisitos mínimos
+
+- TLS obrigatório fora de localhost.
+- Nunca registrar `Authorization`, API keys, secrets ou tokens.
+- Restringir acesso direto aos backends quando a autenticação estiver centralizada no gateway.
+- Usar comparação em tempo constante para credenciais estáticas.
+- Usar PBKDF2 para secrets humanos e rotação periódica.
+- Proteger `/debug`, sessões, métricas e documentação.
+- Não confiar em headers de identidade vindos diretamente da internet.
+- Separar autenticação, autorização e confirmação transacional.
+- Aplicar rate limiting, limites de payload e auditoria no ingress/gateway.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/TESTE_LONG_TERM_MEMORY.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/TESTE_LONG_TERM_MEMORY.md
new file mode 100644
index 0000000..cfe5969
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/TESTE_LONG_TERM_MEMORY.md
@@ -0,0 +1,82 @@
+# Teste e diagnóstico de Long-Term Memory
+
+## O que foi corrigido
+
+1. A LTM agora é carregada explicitamente antes do roteamento.
+2. O estado recebe uma chave estável em `long_term_memory_subject_key`, baseada em `business_context.customer_key` e, como fallback, `user_id`.
+3. O resultado de carga e persistência aparece em `metadata.long_term_memory` da resposta.
+4. `/health` informa a configuração efetiva de LTM carregada pelo processo.
+5. Falhas de leitura e gravação geram eventos `long_term_memory.load.failed` e `long_term_memory.persist.failed`.
+
+## Teste
+
+Primeira sessão:
+
+```bash
+curl -s http://localhost:8000/gateway/message \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channel":"web",
+    "payload":{
+      "text":"Meu nome preferido é Cris e minha linguagem preferida é Python.",
+      "session_id":"ltm-session-001",
+      "user_id":"ltm-user-001",
+      "customer_id":"ltm-customer-001"
+    }
+  }'
+```
+
+Verifique na resposta:
+
+```json
+"long_term_memory": {
+  "subject_key": "ltm-customer-001",
+  "write_result": {
+    "saved": 2
+  }
+}
+```
+
+Nova sessão, mesma identidade:
+
+```bash
+curl -s http://localhost:8000/gateway/message \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channel":"web",
+    "payload":{
+      "text":"Qual é meu nome preferido e qual linguagem eu prefiro?",
+      "session_id":"ltm-session-002",
+      "user_id":"ltm-user-001",
+      "customer_id":"ltm-customer-001"
+    }
+  }'
+```
+
+Na segunda resposta, confira:
+
+- `metadata.long_term_memory.subject_key` igual à primeira chamada;
+- `metadata.long_term_memory.loaded` com registros;
+- `metadata.long_term_memory.context` preenchido;
+- ausência de `load_error`.
+
+## Diagnóstico rápido
+
+```bash
+curl -s http://localhost:8000/health
+```
+
+A seção `long_term_memory` deve mostrar:
+
+```json
+{
+  "enabled": true,
+  "provider": "sqlite",
+  "sqlite_path": "./data/agent_framework.db",
+  "table": "agentfw_long_term_memory",
+  "auto_extract": true,
+  "inject_context": true
+}
+```
+
+Execute o backend com o diretório do projeto como diretório de trabalho. Como o caminho SQLite é relativo, iniciar a aplicação em outro diretório pode criar ou consultar outro arquivo `./data/agent_framework.db`.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/VALIDACAO_BACKEND_IC_NOC_GRL.md b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/VALIDACAO_BACKEND_IC_NOC_GRL.md
new file mode 100644
index 0000000..a9e4458
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/VALIDACAO_BACKEND_IC_NOC_GRL.md
@@ -0,0 +1,62 @@
+# Validação da versão com IC/NOC/GRL
+
+Validações executadas nesta geração:
+
+1. `python -m compileall -q agent_template_backend/app`
+   - Resultado: OK.
+
+2. Smoke test dos agentes com LLM fake e Observer fake:
+   - `BillingAgent`: preservou resposta gerada pelo LLM e emitiu IC de início/fim.
+   - `OrdersAgent`: preservou resposta gerada pelo LLM e emitiu IC de início/fim.
+   - `ProductAgent`: preservou resposta gerada pelo LLM e emitiu IC de início/fim.
+   - `SupportAgent`: preservou resposta gerada pelo LLM e emitiu IC de início/fim.
+
+3. Verificação de regressão:
+   - Nenhum agente retorna `Template Enterprise ativo`.
+   - A lógica LLM/MCP/RAG/cache existente foi preservada.
+
+## Eventos adicionados
+
+### IC
+
+Nos agentes:
+
+- `IC.BILLING_AGENT_STARTED`
+- `IC.BILLING_MCP_CONTEXT_COLLECTED`
+- `IC.BILLING_RAG_CONTEXT_RETRIEVED`
+- `IC.BILLING_AGENT_COMPLETED`
+- `IC.ORDERS_AGENT_STARTED`
+- `IC.ORDERS_MCP_CONTEXT_COLLECTED`
+- `IC.ORDERS_RAG_CONTEXT_RETRIEVED`
+- `IC.ORDERS_AGENT_COMPLETED`
+- `IC.PRODUCT_AGENT_STARTED`
+- `IC.PRODUCT_MCP_CONTEXT_COLLECTED`
+- `IC.PRODUCT_RAG_CONTEXT_RETRIEVED`
+- `IC.PRODUCT_AGENT_COMPLETED`
+- `IC.SUPPORT_AGENT_STARTED`
+- `IC.SUPPORT_MCP_CONTEXT_COLLECTED`
+- `IC.SUPPORT_RAG_CONTEXT_RETRIEVED`
+- `IC.SUPPORT_AGENT_COMPLETED`
+
+No runtime MCP:
+
+- `IC.MCP_TOOL_CALLED`
+- `IC.TOOL_CALLED`
+
+### NOC
+
+Já integrados no workflow:
+
+- `NOC.001` início da execução
+- `NOC.005` erro fatal
+- `NOC.006` finalização/persistência
+
+### GRL
+
+No workflow de guardrails:
+
+- `GRL.001` início da avaliação
+- `GRL.002` allow
+- `GRL.004` block
+- `GRL.009` decisão final
+
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/VALIDACAO_TEMPLATE_ENTERPRISE.txt b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/VALIDACAO_TEMPLATE_ENTERPRISE.txt
new file mode 100644
index 0000000..fac4bf4
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/docs/VALIDACAO_TEMPLATE_ENTERPRISE.txt
@@ -0,0 +1,3 @@
+compileall app: OK
+Arquivos de exemplos IC/NOC/GRL adicionados.
+Agentes preservam implementação original comentada.
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/llm_profiles.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/llm_profiles.yaml
new file mode 100644
index 0000000..908b382
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/llm_profiles.yaml
@@ -0,0 +1,80 @@
+profiles:
+  default:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0.2
+    max_tokens: 2048
+  supervisor:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 700
+  route_continuity:
+    provider: oci_openai
+    model: openai.gpt-4.1-mini
+    temperature: 0
+    max_tokens: 80
+    timeout_seconds: 5
+  router:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 500
+  guardrail:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 600
+  grl:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 700
+  judge:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 800
+  rag_rewriter:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 300
+  rag_compressor:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 1200
+  rag_generation:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0.1
+    max_tokens: 1800
+  summary_memory:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0.1
+    max_tokens: 1200
+  noc:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0
+    max_tokens: 700
+  billing_agent:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0.2
+  product_agent:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0.2
+  backoffice_agent:
+    provider: oci_openai
+    model: openai.gpt-4.1
+    temperature: 0.2
+  mcp_parameter_extraction:
+    provider: oci_openai
+    model: openai.gpt-4.1-mini
+    temperature: 0
+    max_tokens: 80
+    timeout_seconds: 5
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/requirements.txt b/Tuning-Performance/Authentication/agent_template_backend_authentication/requirements.txt
new file mode 100644
index 0000000..ba0f396
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/requirements.txt
@@ -0,0 +1,25 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+pydantic>=2.8.0
+pydantic-settings>=2.4.0
+python-dotenv>=1.0.1
+langgraph>=0.2.60
+langchain-core>=0.3.0
+openai>=1.60.0
+oci>=2.130.0
+oracledb>=2.4.0
+pymongo>=4.8.0
+redis>=5.0.0
+PyYAML>=6.0.2
+
+langfuse>=3.0.0
+httpx>=0.27.0
+opentelemetry-api>=1.27.0
+opentelemetry-sdk>=1.27.0
+opentelemetry-exporter-otlp-proto-http>=1.27.0
+
+pytest>=8.0.0
+pytest-asyncio>=0.23.0
+google-cloud-pubsub>=2.28.0
+
+PyJWT[crypto]>=2.9.0
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py
new file mode 100644
index 0000000..bc0a005
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py
@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import argparse
+import base64
+import getpass
+import hashlib
+import secrets
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate a PBKDF2-SHA256 value for AGENT_AUTH_*_HASH variables.")
+    parser.add_argument("--secret", help="Avoid on shared shells; omitted means secure prompt.")
+    parser.add_argument("--iterations", type=int, default=310_000)
+    args = parser.parse_args()
+    secret = args.secret or getpass.getpass("Secret: ")
+    salt = secrets.token_urlsafe(18)
+    digest = hashlib.pbkdf2_hmac("sha256", secret.encode(), salt.encode(), args.iterations)
+    encoded = base64.urlsafe_b64encode(digest).decode().rstrip("=")
+    print(f"pbkdf2_sha256:{args.iterations}:{salt}:{encoded}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/test_long_term_memory.py b/Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/test_long_term_memory.py
new file mode 100644
index 0000000..52e2a8d
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/test_long_term_memory.py
@@ -0,0 +1,29 @@
+import asyncio
+import tempfile
+from types import SimpleNamespace
+from agent_framework.memory.long_term_memory import create_long_term_memory_manager
+
+async def main():
+    with tempfile.TemporaryDirectory() as d:
+        settings = SimpleNamespace(
+            ENABLE_LONG_TERM_MEMORY=True,
+            LONG_TERM_MEMORY_PROVIDER='sqlite',
+            LONG_TERM_MEMORY_SQLITE_PATH=f'{d}/memory.db',
+            LONG_TERM_MEMORY_TABLE='agentfw_long_term_memory',
+            LONG_TERM_MEMORY_MAX_CONTEXT_ITEMS=20,
+            LONG_TERM_MEMORY_MIN_CONFIDENCE=0.70,
+            LONG_TERM_MEMORY_AUTO_EXTRACT=True,
+        )
+        manager = create_long_term_memory_manager(settings)
+        first = {'tenant_id':'default','agent_id':'memory_test','session_id':'a','user_text':'Me chame de Cris. Minha linguagem preferida é Python. Meu projeto atual se chama Atlas.','context':{'business_context':{'customer_key':'MEM-001'}}}
+        assert (await manager.persist_turn(first))['saved'] >= 3
+        second = {'tenant_id':'default','agent_id':'memory_test','session_id':'b','context':{'business_context':{'customer_key':'MEM-001'}}}
+        values = {item.key:item.value for item in await manager.load(second)}
+        assert values['preferred_name'].lower() == 'cris'
+        assert values['preferred_language'].lower() == 'python'
+        assert values['current_project'].lower() == 'atlas'
+        isolated = {'tenant_id':'default','agent_id':'memory_test','session_id':'c','context':{'business_context':{'customer_key':'MEM-002'}}}
+        assert await manager.load(isolated) == []
+        print('OK: persistência, recuperação entre sessões e isolamento validados')
+
+asyncio.run(main())
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/workflows/devolucao_pedido.active.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/workflows/devolucao_pedido.active.yaml
new file mode 100644
index 0000000..b825518
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/workflows/devolucao_pedido.active.yaml
@@ -0,0 +1 @@
+version: 1
diff --git a/Tuning-Performance/Authentication/agent_template_backend_authentication/workflows/devolucao_pedido.v1.yaml b/Tuning-Performance/Authentication/agent_template_backend_authentication/workflows/devolucao_pedido.v1.yaml
new file mode 100644
index 0000000..d2ff1aa
--- /dev/null
+++ b/Tuning-Performance/Authentication/agent_template_backend_authentication/workflows/devolucao_pedido.v1.yaml
@@ -0,0 +1,27 @@
+name: devolucao_pedido
+version: 1
+start: validar_pedido
+nodes:
+  - id: validar_pedido
+    action: validar_pedido
+    input:
+      order_id: $.input.order_id
+  - id: registrar_devolucao
+    action: registrar_devolucao
+    retry: 1
+    input:
+      order_id: $.input.order_id
+      reason: $.input.reason
+edges:
+  - from: validar_pedido
+    to: registrar_devolucao
+    when:
+      path: $.nodes.validar_pedido.valid
+      equals: true
+  - from: validar_pedido
+    to: END
+    when:
+      path: $.nodes.validar_pedido.valid
+      equals: false
+  - from: registrar_devolucao
+    to: END
diff --git a/Tuning-Performance/Authentication/authentication_policies.example.yaml b/Tuning-Performance/Authentication/authentication_policies.example.yaml
new file mode 100644
index 0000000..881e3c0
--- /dev/null
+++ b/Tuning-Performance/Authentication/authentication_policies.example.yaml
@@ -0,0 +1,39 @@
+# Nunca coloque secrets diretamente neste arquivo. Use sempre *_env.
+providers:
+  public:
+    mode: none
+
+  deny:
+    mode: deny
+
+  tia_basic:
+    mode: basic
+    client_id_env: TIA_AGENT_CLIENT_ID
+    secret_hash_env: TIA_AGENT_SECRET_HASH
+    realm: agent-contas
+
+  platform_jwt:
+    mode: jwt
+    key_env: PLATFORM_JWT_PUBLIC_KEY
+    algorithms: [RS256]
+    audience: agent-platform
+    issuer: https://identity.example.com/
+
+policies:
+  - name: health-public
+    provider: public
+    paths: [/health, /ready, /live]
+
+  - name: tia-agent-api
+    provider: tia_basic
+    paths: [/gateway/message, /gateway/message/sse, /gateway/events/*]
+    methods: [GET, POST]
+
+  - name: admin-api
+    provider: platform_jwt
+    paths: [/debug/*, /admin/*]
+    required_roles: [platform-admin]
+    required_scopes: [agent.admin]
+
+# Quando nenhuma política casar, rejeita. O default omitido também é deny.
+default_provider: deny
diff --git a/apps/agent_gateway/app/__pycache__/governance_middleware.cpython-313.pyc b/apps/agent_gateway/app/__pycache__/governance_middleware.cpython-313.pyc
new file mode 100644
index 0000000..9ef1c4f
Binary files /dev/null and b/apps/agent_gateway/app/__pycache__/governance_middleware.cpython-313.pyc differ
diff --git a/apps/agent_gateway/app/__pycache__/main.cpython-313.pyc b/apps/agent_gateway/app/__pycache__/main.cpython-313.pyc
new file mode 100644
index 0000000..fffdb5d
Binary files /dev/null and b/apps/agent_gateway/app/__pycache__/main.cpython-313.pyc differ
diff --git a/apps/agent_gateway/app/__pycache__/settings.cpython-313.pyc b/apps/agent_gateway/app/__pycache__/settings.cpython-313.pyc
new file mode 100644
index 0000000..0331ed7
Binary files /dev/null and b/apps/agent_gateway/app/__pycache__/settings.cpython-313.pyc differ
diff --git a/apps/agent_gateway/app/config/__pycache__/governance_loader.cpython-313.pyc b/apps/agent_gateway/app/config/__pycache__/governance_loader.cpython-313.pyc
new file mode 100644
index 0000000..49664df
Binary files /dev/null and b/apps/agent_gateway/app/config/__pycache__/governance_loader.cpython-313.pyc differ
diff --git a/apps/agent_gateway/app/governance/__pycache__/__init__.cpython-313.pyc b/apps/agent_gateway/app/governance/__pycache__/__init__.cpython-313.pyc
new file mode 100644
index 0000000..9facf87
Binary files /dev/null and b/apps/agent_gateway/app/governance/__pycache__/__init__.cpython-313.pyc differ
diff --git a/apps/agent_gateway/app/governance/__pycache__/audit.cpython-313.pyc b/apps/agent_gateway/app/governance/__pycache__/audit.cpython-313.pyc
new file mode 100644
index 0000000..1da29c6
Binary files /dev/null and b/apps/agent_gateway/app/governance/__pycache__/audit.cpython-313.pyc differ
diff --git a/apps/agent_gateway/app/governance/__pycache__/evaluation_hooks.cpython-313.pyc b/apps/agent_gateway/app/governance/__pycache__/evaluation_hooks.cpython-313.pyc
new file mode 100644
index 0000000..473f2bc
Binary files /dev/null and b/apps/agent_gateway/app/governance/__pycache__/evaluation_hooks.cpython-313.pyc differ
diff --git a/apps/agent_gateway/app/governance/__pycache__/model_policies.cpython-313.pyc b/apps/agent_gateway/app/governance/__pycache__/model_policies.cpython-313.pyc
new file mode 100644
index 0000000..1141210
Binary files /dev/null and b/apps/agent_gateway/app/governance/__pycache__/model_policies.cpython-313.pyc differ
diff --git a/apps/agent_gateway/app/governance/__pycache__/rate_limit.cpython-313.pyc b/apps/agent_gateway/app/governance/__pycache__/rate_limit.cpython-313.pyc
new file mode 100644
index 0000000..507ee7d
Binary files /dev/null and b/apps/agent_gateway/app/governance/__pycache__/rate_limit.cpython-313.pyc differ
diff --git a/apps/agent_gateway/app/governance/__pycache__/usage.cpython-313.pyc b/apps/agent_gateway/app/governance/__pycache__/usage.cpython-313.pyc
new file mode 100644
index 0000000..b102d11
Binary files /dev/null and b/apps/agent_gateway/app/governance/__pycache__/usage.cpython-313.pyc differ
diff --git a/apps/agent_gateway/app/main.py b/apps/agent_gateway/app/main.py
index a734d3d..06c5cd8 100644
--- a/apps/agent_gateway/app/main.py
+++ b/apps/agent_gateway/app/main.py
@@ -18,6 +18,7 @@ from agent_framework.global_supervisor import (
 )
 from agent_framework.llm.providers import create_llm
 from agent_framework.observability.observer import AgentObserver
+from agent_framework.security import install_authentication
 
 from app.settings import settings
 
@@ -25,6 +26,7 @@ logging.basicConfig(level=settings.LOG_LEVEL)
 logger = logging.getLogger("agent_gateway")
 
 app = FastAPI(title="Agent Gateway - Global Supervisor")
+install_authentication(app, prefix="AGENT_GATEWAY_AUTH")
 app.add_middleware(
     CORSMiddleware,
     allow_origins=[o.strip() for o in settings.CORS_ORIGINS.split(",")],
diff --git a/apps/agent_gateway/app/routes/__pycache__/governed_proxy_example.cpython-313.pyc b/apps/agent_gateway/app/routes/__pycache__/governed_proxy_example.cpython-313.pyc
new file mode 100644
index 0000000..e4d8952
Binary files /dev/null and b/apps/agent_gateway/app/routes/__pycache__/governed_proxy_example.cpython-313.pyc differ
diff --git a/apps/agent_gateway/config/authentication.example.yaml b/apps/agent_gateway/config/authentication.example.yaml
new file mode 100644
index 0000000..881e3c0
--- /dev/null
+++ b/apps/agent_gateway/config/authentication.example.yaml
@@ -0,0 +1,39 @@
+# Nunca coloque secrets diretamente neste arquivo. Use sempre *_env.
+providers:
+  public:
+    mode: none
+
+  deny:
+    mode: deny
+
+  tia_basic:
+    mode: basic
+    client_id_env: TIA_AGENT_CLIENT_ID
+    secret_hash_env: TIA_AGENT_SECRET_HASH
+    realm: agent-contas
+
+  platform_jwt:
+    mode: jwt
+    key_env: PLATFORM_JWT_PUBLIC_KEY
+    algorithms: [RS256]
+    audience: agent-platform
+    issuer: https://identity.example.com/
+
+policies:
+  - name: health-public
+    provider: public
+    paths: [/health, /ready, /live]
+
+  - name: tia-agent-api
+    provider: tia_basic
+    paths: [/gateway/message, /gateway/message/sse, /gateway/events/*]
+    methods: [GET, POST]
+
+  - name: admin-api
+    provider: platform_jwt
+    paths: [/debug/*, /admin/*]
+    required_roles: [platform-admin]
+    required_scopes: [agent.admin]
+
+# Quando nenhuma política casar, rejeita. O default omitido também é deny.
+default_provider: deny
diff --git a/apps/mcp_gateway/app/__pycache__/__init__.cpython-313.pyc b/apps/mcp_gateway/app/__pycache__/__init__.cpython-313.pyc
new file mode 100644
index 0000000..0e96f67
Binary files /dev/null and b/apps/mcp_gateway/app/__pycache__/__init__.cpython-313.pyc differ
diff --git a/apps/mcp_gateway/app/__pycache__/main.cpython-313.pyc b/apps/mcp_gateway/app/__pycache__/main.cpython-313.pyc
new file mode 100644
index 0000000..83107d4
Binary files /dev/null and b/apps/mcp_gateway/app/__pycache__/main.cpython-313.pyc differ
diff --git a/apps/mcp_gateway/app/main.py b/apps/mcp_gateway/app/main.py
index c4ace57..d087c1d 100644
--- a/apps/mcp_gateway/app/main.py
+++ b/apps/mcp_gateway/app/main.py
@@ -11,6 +11,7 @@ from typing import Any
 import httpx
 import yaml
 from fastapi import FastAPI, Header, HTTPException
+from agent_framework.security import install_authentication
 from pydantic import BaseModel, Field
 
 
@@ -64,6 +65,7 @@ discovered_tools: dict[str, dict[str, Any]] = {}
 discovery_state: dict[str, Any] = {"last_sync": None, "errors": [], "tools": []}
 cache: dict[str, tuple[float, Any]] = {}
 app = FastAPI(title="Agent Platform OCI - MCP Gateway", version="1.1.0")
+install_authentication(app, prefix="MCP_GATEWAY_AUTH")
 
 
 def audit(name: str, payload: dict[str, Any]) -> None:
diff --git a/apps/mcp_gateway/config/authentication.example.yaml b/apps/mcp_gateway/config/authentication.example.yaml
new file mode 100644
index 0000000..881e3c0
--- /dev/null
+++ b/apps/mcp_gateway/config/authentication.example.yaml
@@ -0,0 +1,39 @@
+# Nunca coloque secrets diretamente neste arquivo. Use sempre *_env.
+providers:
+  public:
+    mode: none
+
+  deny:
+    mode: deny
+
+  tia_basic:
+    mode: basic
+    client_id_env: TIA_AGENT_CLIENT_ID
+    secret_hash_env: TIA_AGENT_SECRET_HASH
+    realm: agent-contas
+
+  platform_jwt:
+    mode: jwt
+    key_env: PLATFORM_JWT_PUBLIC_KEY
+    algorithms: [RS256]
+    audience: agent-platform
+    issuer: https://identity.example.com/
+
+policies:
+  - name: health-public
+    provider: public
+    paths: [/health, /ready, /live]
+
+  - name: tia-agent-api
+    provider: tia_basic
+    paths: [/gateway/message, /gateway/message/sse, /gateway/events/*]
+    methods: [GET, POST]
+
+  - name: admin-api
+    provider: platform_jwt
+    paths: [/debug/*, /admin/*]
+    required_roles: [platform-admin]
+    required_scopes: [agent.admin]
+
+# Quando nenhuma política casar, rejeita. O default omitido também é deny.
+default_provider: deny
diff --git a/libs/agent_framework/pyproject.toml b/libs/agent_framework/pyproject.toml
index 60e4936..c653a16 100644
--- a/libs/agent_framework/pyproject.toml
+++ b/libs/agent_framework/pyproject.toml
@@ -23,7 +23,8 @@ dependencies = [
   "aiohttp>=3.9.0",
   "motor>=3.6.0",
   "google-cloud-pubsub>=2.28.0",
-  "mcp>=1.9.0"
+  "mcp>=1.9.0",
+  "PyJWT[crypto]>=2.9.0"
 ]
 
 [tool.setuptools.packages.find]
diff --git a/libs/agent_framework/src/agent_framework/__pycache__/__init__.cpython-313.pyc b/libs/agent_framework/src/agent_framework/__pycache__/__init__.cpython-313.pyc
index 3cb376f..35a5280 100644
Binary files a/libs/agent_framework/src/agent_framework/__pycache__/__init__.cpython-313.pyc and b/libs/agent_framework/src/agent_framework/__pycache__/__init__.cpython-313.pyc differ
diff --git a/libs/agent_framework/src/agent_framework/config/__pycache__/__init__.cpython-313.pyc b/libs/agent_framework/src/agent_framework/config/__pycache__/__init__.cpython-313.pyc
index af2746d..06f2a47 100644
Binary files a/libs/agent_framework/src/agent_framework/config/__pycache__/__init__.cpython-313.pyc and b/libs/agent_framework/src/agent_framework/config/__pycache__/__init__.cpython-313.pyc differ
diff --git a/libs/agent_framework/src/agent_framework/config/__pycache__/settings.cpython-313.pyc b/libs/agent_framework/src/agent_framework/config/__pycache__/settings.cpython-313.pyc
index 9275594..6986b73 100644
Binary files a/libs/agent_framework/src/agent_framework/config/__pycache__/settings.cpython-313.pyc and b/libs/agent_framework/src/agent_framework/config/__pycache__/settings.cpython-313.pyc differ
diff --git a/libs/agent_framework/src/agent_framework/security/__init__.py b/libs/agent_framework/src/agent_framework/security/__init__.py
new file mode 100644
index 0000000..04c47ef
--- /dev/null
+++ b/libs/agent_framework/src/agent_framework/security/__init__.py
@@ -0,0 +1,40 @@
+from .authentication import (
+    ApiKeyAuthenticationProvider,
+    AuthenticatedPrincipal,
+    AuthenticationProvider,
+    AuthenticationResult,
+    BasicAuthenticationProvider,
+    DenyAuthenticationProvider,
+    JwtAuthenticationProvider,
+    NoAuthenticationProvider,
+    OAuth2IntrospectionAuthenticationProvider,
+    StaticBearerAuthenticationProvider,
+    TrustedProxyAuthenticationProvider,
+    verify_secret,
+)
+from .factory import create_authentication_provider, create_provider_from_config, env_provider_config
+from .installer import install_authentication, load_authentication_policies
+from .middleware import AuthenticationMiddleware, AuthenticationPolicy, PolicyAuthenticationMiddleware
+
+__all__ = [
+    "ApiKeyAuthenticationProvider",
+    "AuthenticatedPrincipal",
+    "AuthenticationProvider",
+    "AuthenticationResult",
+    "AuthenticationMiddleware",
+    "AuthenticationPolicy",
+    "BasicAuthenticationProvider",
+    "DenyAuthenticationProvider",
+    "JwtAuthenticationProvider",
+    "NoAuthenticationProvider",
+    "OAuth2IntrospectionAuthenticationProvider",
+    "PolicyAuthenticationMiddleware",
+    "StaticBearerAuthenticationProvider",
+    "TrustedProxyAuthenticationProvider",
+    "create_authentication_provider",
+    "create_provider_from_config",
+    "env_provider_config",
+    "install_authentication",
+    "load_authentication_policies",
+    "verify_secret",
+]
diff --git a/libs/agent_framework/src/agent_framework/security/__pycache__/__init__.cpython-313.pyc b/libs/agent_framework/src/agent_framework/security/__pycache__/__init__.cpython-313.pyc
new file mode 100644
index 0000000..d5ac65c
Binary files /dev/null and b/libs/agent_framework/src/agent_framework/security/__pycache__/__init__.cpython-313.pyc differ
diff --git a/libs/agent_framework/src/agent_framework/security/__pycache__/authentication.cpython-313.pyc b/libs/agent_framework/src/agent_framework/security/__pycache__/authentication.cpython-313.pyc
new file mode 100644
index 0000000..ab536da
Binary files /dev/null and b/libs/agent_framework/src/agent_framework/security/__pycache__/authentication.cpython-313.pyc differ
diff --git a/libs/agent_framework/src/agent_framework/security/__pycache__/factory.cpython-313.pyc b/libs/agent_framework/src/agent_framework/security/__pycache__/factory.cpython-313.pyc
new file mode 100644
index 0000000..1c721f3
Binary files /dev/null and b/libs/agent_framework/src/agent_framework/security/__pycache__/factory.cpython-313.pyc differ
diff --git a/libs/agent_framework/src/agent_framework/security/__pycache__/installer.cpython-313.pyc b/libs/agent_framework/src/agent_framework/security/__pycache__/installer.cpython-313.pyc
new file mode 100644
index 0000000..2e80012
Binary files /dev/null and b/libs/agent_framework/src/agent_framework/security/__pycache__/installer.cpython-313.pyc differ
diff --git a/libs/agent_framework/src/agent_framework/security/__pycache__/middleware.cpython-313.pyc b/libs/agent_framework/src/agent_framework/security/__pycache__/middleware.cpython-313.pyc
new file mode 100644
index 0000000..57c4c9c
Binary files /dev/null and b/libs/agent_framework/src/agent_framework/security/__pycache__/middleware.cpython-313.pyc differ
diff --git a/libs/agent_framework/src/agent_framework/security/authentication.py b/libs/agent_framework/src/agent_framework/security/authentication.py
new file mode 100644
index 0000000..17d2ba8
--- /dev/null
+++ b/libs/agent_framework/src/agent_framework/security/authentication.py
@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Protocol, Sequence
+
+import httpx
+from fastapi import Request
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class AuthenticatedPrincipal:
+    subject: str
+    scheme: str
+    claims: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class AuthenticationResult:
+    authenticated: bool
+    principal: AuthenticatedPrincipal | None = None
+    error: str | None = None
+    challenge: str | None = None
+
+
+class AuthenticationProvider(Protocol):
+    async def authenticate(self, request: Request) -> AuthenticationResult: ...
+
+
+def _constant_time_equals(left: str, right: str) -> bool:
+    return hmac.compare_digest(left.encode("utf-8"), right.encode("utf-8"))
+
+
+def _pbkdf2_hash(secret: str, salt: str, iterations: int = 310_000) -> str:
+    digest = hashlib.pbkdf2_hmac("sha256", secret.encode(), salt.encode(), iterations)
+    return base64.urlsafe_b64encode(digest).decode().rstrip("=")
+
+
+def verify_secret(secret: str, stored_value: str) -> bool:
+    """Accepts plain:<value>, sha256:<hex>, or pbkdf2_sha256:<iterations>:<salt>:<digest>."""
+    if stored_value.startswith("plain:"):
+        return _constant_time_equals(secret, stored_value.removeprefix("plain:"))
+    if stored_value.startswith("sha256:"):
+        candidate = hashlib.sha256(secret.encode()).hexdigest()
+        return _constant_time_equals(candidate, stored_value.removeprefix("sha256:"))
+    if stored_value.startswith("pbkdf2_sha256:"):
+        try:
+            _, iterations, salt, expected = stored_value.split(":", 3)
+            return _constant_time_equals(_pbkdf2_hash(secret, salt, int(iterations)), expected)
+        except (ValueError, TypeError):
+            return False
+    return _constant_time_equals(secret, stored_value)
+
+
+class NoAuthenticationProvider:
+    async def authenticate(self, request: Request) -> AuthenticationResult:
+        return AuthenticationResult(True, AuthenticatedPrincipal("anonymous", "none"))
+
+
+class DenyAuthenticationProvider:
+    async def authenticate(self, request: Request) -> AuthenticationResult:
+        return AuthenticationResult(False, error="authentication_policy_not_configured")
+
+
+class BasicAuthenticationProvider:
+    def __init__(self, client_id: str, secret_hash: str, realm: str = "agent-api"):
+        self.client_id = client_id
+        self.secret_hash = secret_hash
+        self.realm = realm
+
+    async def authenticate(self, request: Request) -> AuthenticationResult:
+        header = request.headers.get("authorization", "")
+        if not header.lower().startswith("basic "):
+            return AuthenticationResult(False, error="missing_basic_credentials", challenge=f'Basic realm="{self.realm}"')
+        try:
+            decoded = base64.b64decode(header.split(" ", 1)[1], validate=True).decode("utf-8")
+            supplied_id, supplied_secret = decoded.split(":", 1)
+        except (ValueError, UnicodeDecodeError):
+            return AuthenticationResult(False, error="invalid_basic_credentials", challenge=f'Basic realm="{self.realm}"')
+        valid = _constant_time_equals(supplied_id, self.client_id) and verify_secret(supplied_secret, self.secret_hash)
+        if not valid:
+            return AuthenticationResult(False, error="invalid_basic_credentials", challenge=f'Basic realm="{self.realm}"')
+        return AuthenticationResult(True, AuthenticatedPrincipal(supplied_id, "basic"))
+
+
+class ApiKeyAuthenticationProvider:
+    def __init__(self, expected_hash: str, header_name: str = "x-api-key", principal: str = "api-client"):
+        self.expected_hash = expected_hash
+        self.header_name = header_name.lower()
+        self.principal = principal
+
+    async def authenticate(self, request: Request) -> AuthenticationResult:
+        supplied = request.headers.get(self.header_name)
+        if not supplied or not verify_secret(supplied, self.expected_hash):
+            return AuthenticationResult(False, error="invalid_api_key")
+        return AuthenticationResult(True, AuthenticatedPrincipal(self.principal, "api_key"))
+
+
+class StaticBearerAuthenticationProvider:
+    def __init__(self, token_hash: str, principal: str = "bearer-client"):
+        self.token_hash = token_hash
+        self.principal = principal
+
+    async def authenticate(self, request: Request) -> AuthenticationResult:
+        header = request.headers.get("authorization", "")
+        if not header.lower().startswith("bearer "):
+            return AuthenticationResult(False, error="missing_bearer_token", challenge="Bearer")
+        token = header.split(" ", 1)[1]
+        if not verify_secret(token, self.token_hash):
+            return AuthenticationResult(False, error="invalid_bearer_token", challenge="Bearer")
+        return AuthenticationResult(True, AuthenticatedPrincipal(self.principal, "bearer"))
+
+
+class JwtAuthenticationProvider:
+    def __init__(self, key: str, algorithms: Sequence[str], audience: str | None = None, issuer: str | None = None):
+        try:
+            import jwt  # type: ignore
+        except ImportError as exc:
+            raise RuntimeError("JWT authentication requires PyJWT[crypto]") from exc
+        self.jwt = jwt
+        self.key = key
+        self.algorithms = list(algorithms)
+        self.audience = audience
+        self.issuer = issuer
+
+    async def authenticate(self, request: Request) -> AuthenticationResult:
+        header = request.headers.get("authorization", "")
+        if not header.lower().startswith("bearer "):
+            return AuthenticationResult(False, error="missing_bearer_token", challenge="Bearer")
+        token = header.split(" ", 1)[1]
+        try:
+            claims = self.jwt.decode(token, self.key, algorithms=self.algorithms, audience=self.audience, issuer=self.issuer)
+        except Exception as exc:
+            logger.info("JWT rejected: %s", exc.__class__.__name__)
+            return AuthenticationResult(False, error="invalid_jwt", challenge="Bearer")
+        subject = str(claims.get("sub") or claims.get("client_id") or "jwt-client")
+        return AuthenticationResult(True, AuthenticatedPrincipal(subject, "jwt", claims))
+
+
+class OAuth2IntrospectionAuthenticationProvider:
+    def __init__(self, introspection_url: str, client_id: str, client_secret: str, timeout_seconds: float = 5.0):
+        self.introspection_url = introspection_url
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.timeout_seconds = timeout_seconds
+
+    async def authenticate(self, request: Request) -> AuthenticationResult:
+        header = request.headers.get("authorization", "")
+        if not header.lower().startswith("bearer "):
+            return AuthenticationResult(False, error="missing_bearer_token", challenge="Bearer")
+        token = header.split(" ", 1)[1]
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+                response = await client.post(
+                    self.introspection_url,
+                    data={"token": token},
+                    auth=(self.client_id, self.client_secret),
+                    headers={"accept": "application/json"},
+                )
+                response.raise_for_status()
+                claims = response.json()
+        except (httpx.HTTPError, ValueError):
+            return AuthenticationResult(False, error="introspection_unavailable", challenge="Bearer")
+        if not claims.get("active") or (claims.get("exp") and int(claims["exp"]) <= int(time.time())):
+            return AuthenticationResult(False, error="inactive_token", challenge="Bearer")
+        subject = str(claims.get("sub") or claims.get("client_id") or claims.get("username") or "oauth-client")
+        return AuthenticationResult(True, AuthenticatedPrincipal(subject, "oauth2_introspection", claims))
+
+
+class TrustedProxyAuthenticationProvider:
+    def __init__(self, subject_header: str = "x-authenticated-subject", shared_secret_header: str | None = None, shared_secret_hash: str | None = None):
+        self.subject_header = subject_header.lower()
+        self.shared_secret_header = shared_secret_header.lower() if shared_secret_header else None
+        self.shared_secret_hash = shared_secret_hash
+
+    async def authenticate(self, request: Request) -> AuthenticationResult:
+        subject = request.headers.get(self.subject_header)
+        if not subject:
+            return AuthenticationResult(False, error="missing_trusted_subject")
+        if self.shared_secret_header and self.shared_secret_hash:
+            supplied = request.headers.get(self.shared_secret_header)
+            if not supplied or not verify_secret(supplied, self.shared_secret_hash):
+                return AuthenticationResult(False, error="invalid_proxy_signature")
+        return AuthenticationResult(True, AuthenticatedPrincipal(subject, "trusted_proxy"))
diff --git a/libs/agent_framework/src/agent_framework/security/factory.py b/libs/agent_framework/src/agent_framework/security/factory.py
new file mode 100644
index 0000000..391a233
--- /dev/null
+++ b/libs/agent_framework/src/agent_framework/security/factory.py
@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import Any
+
+from .authentication import (
+    ApiKeyAuthenticationProvider,
+    BasicAuthenticationProvider,
+    DenyAuthenticationProvider,
+    JwtAuthenticationProvider,
+    NoAuthenticationProvider,
+    OAuth2IntrospectionAuthenticationProvider,
+    StaticBearerAuthenticationProvider,
+    TrustedProxyAuthenticationProvider,
+)
+
+
+def _required_env(name: str) -> str:
+    value = os.getenv(name)
+    if value is None or not value.strip():
+        raise ValueError(f"Required authentication environment variable is missing: {name}")
+    return value
+
+
+def _resolve(config: Mapping[str, Any], key: str, *, required: bool = False, default: Any = None) -> Any:
+    env_key = config.get(f"{key}_env")
+    if env_key:
+        value = os.getenv(str(env_key))
+        if required and (value is None or not value.strip()):
+            raise ValueError(f"Required authentication environment variable is missing: {env_key}")
+        return value if value is not None else default
+    value = config.get(key, default)
+    if required and (value is None or (isinstance(value, str) and not value.strip())):
+        raise ValueError(f"Required authentication configuration is missing: {key}")
+    return value
+
+
+def create_provider_from_config(config: Mapping[str, Any]):
+    """Create a provider from a secret-safe mapping.
+
+    Secret values may be supplied indirectly with ``<field>_env`` keys so YAML
+    never needs to contain credentials.
+    """
+    mode = str(config.get("mode", "none")).strip().lower()
+    if mode in {"none", "disabled"}:
+        return NoAuthenticationProvider()
+    if mode in {"deny", "reject"}:
+        return DenyAuthenticationProvider()
+    if mode == "basic":
+        return BasicAuthenticationProvider(
+            str(_resolve(config, "client_id", required=True)),
+            str(_resolve(config, "secret_hash", required=True)),
+            str(_resolve(config, "realm", default="agent-api")),
+        )
+    if mode == "api_key":
+        return ApiKeyAuthenticationProvider(
+            str(_resolve(config, "api_key_hash", required=True)),
+            str(_resolve(config, "header", default="x-api-key")),
+            str(_resolve(config, "principal", default="api-client")),
+        )
+    if mode == "bearer_static":
+        return StaticBearerAuthenticationProvider(
+            str(_resolve(config, "token_hash", required=True)),
+            str(_resolve(config, "principal", default="bearer-client")),
+        )
+    if mode == "jwt":
+        algorithms = _resolve(config, "algorithms", default=["RS256"])
+        if isinstance(algorithms, str):
+            algorithms = [item.strip() for item in algorithms.split(",") if item.strip()]
+        return JwtAuthenticationProvider(
+            str(_resolve(config, "key", required=True)),
+            algorithms,
+            _resolve(config, "audience"),
+            _resolve(config, "issuer"),
+        )
+    if mode == "oauth2_introspection":
+        return OAuth2IntrospectionAuthenticationProvider(
+            str(_resolve(config, "introspection_url", required=True)),
+            str(_resolve(config, "client_id", required=True)),
+            str(_resolve(config, "client_secret", required=True)),
+            float(_resolve(config, "timeout_seconds", default=5)),
+        )
+    if mode == "trusted_proxy":
+        return TrustedProxyAuthenticationProvider(
+            str(_resolve(config, "subject_header", default="x-authenticated-subject")),
+            _resolve(config, "shared_secret_header"),
+            _resolve(config, "shared_secret_hash"),
+        )
+    raise ValueError(f"Unsupported authentication mode: {mode}")
+
+
+def env_provider_config(prefix: str = "AGENT_AUTH") -> dict[str, Any]:
+    mode = os.getenv(f"{prefix}_MODE", "none").strip().lower()
+    config: dict[str, Any] = {"mode": mode}
+    if mode == "basic":
+        config.update(client_id=_required_env(f"{prefix}_BASIC_CLIENT_ID"), secret_hash=_required_env(f"{prefix}_BASIC_SECRET_HASH"), realm=os.getenv(f"{prefix}_BASIC_REALM", "agent-api"))
+    elif mode == "api_key":
+        config.update(api_key_hash=_required_env(f"{prefix}_API_KEY_HASH"), header=os.getenv(f"{prefix}_API_KEY_HEADER", "x-api-key"), principal=os.getenv(f"{prefix}_API_KEY_PRINCIPAL", "api-client"))
+    elif mode == "bearer_static":
+        config.update(token_hash=_required_env(f"{prefix}_BEARER_TOKEN_HASH"), principal=os.getenv(f"{prefix}_BEARER_PRINCIPAL", "bearer-client"))
+    elif mode == "jwt":
+        config.update(key=_required_env(f"{prefix}_JWT_KEY"), algorithms=os.getenv(f"{prefix}_JWT_ALGORITHMS", "RS256"), audience=os.getenv(f"{prefix}_JWT_AUDIENCE") or None, issuer=os.getenv(f"{prefix}_JWT_ISSUER") or None)
+    elif mode == "oauth2_introspection":
+        config.update(introspection_url=_required_env(f"{prefix}_OAUTH2_INTROSPECTION_URL"), client_id=_required_env(f"{prefix}_OAUTH2_CLIENT_ID"), client_secret=_required_env(f"{prefix}_OAUTH2_CLIENT_SECRET"), timeout_seconds=float(os.getenv(f"{prefix}_OAUTH2_TIMEOUT_SECONDS", "5")))
+    elif mode == "trusted_proxy":
+        config.update(subject_header=os.getenv(f"{prefix}_PROXY_SUBJECT_HEADER", "x-authenticated-subject"), shared_secret_header=os.getenv(f"{prefix}_PROXY_SHARED_SECRET_HEADER") or None, shared_secret_hash=os.getenv(f"{prefix}_PROXY_SHARED_SECRET_HASH") or None)
+    return config
+
+
+def create_authentication_provider(prefix: str = "AGENT_AUTH"):
+    return create_provider_from_config(env_provider_config(prefix))
diff --git a/libs/agent_framework/src/agent_framework/security/installer.py b/libs/agent_framework/src/agent_framework/security/installer.py
new file mode 100644
index 0000000..dec02c1
--- /dev/null
+++ b/libs/agent_framework/src/agent_framework/security/installer.py
@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+from fastapi import FastAPI
+
+from .authentication import DenyAuthenticationProvider
+from .factory import create_authentication_provider, create_provider_from_config
+from .middleware import AuthenticationMiddleware, AuthenticationPolicy, PolicyAuthenticationMiddleware
+
+
+def _csv(value: str | None, default: str = "") -> list[str]:
+    return [item.strip() for item in (value if value is not None else default).split(",") if item.strip()]
+
+
+def _bool(value: str | None, default: bool = False) -> bool:
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def load_authentication_policies(path: str | Path) -> tuple[list[AuthenticationPolicy], Any]:
+    raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
+    providers = {
+        name: create_provider_from_config(config or {})
+        for name, config in (raw.get("providers") or {}).items()
+    }
+    policies: list[AuthenticationPolicy] = []
+    for index, item in enumerate(raw.get("policies") or []):
+        provider_name = item.get("provider")
+        if provider_name not in providers:
+            raise ValueError(f"Unknown authentication provider in policy: {provider_name}")
+        policies.append(AuthenticationPolicy(
+            name=str(item.get("name") or f"policy-{index + 1}"),
+            provider=providers[provider_name],
+            paths=tuple(item.get("paths") or ["*"]),
+            methods=frozenset(str(method).upper() for method in (item.get("methods") or [])),
+            required_roles=frozenset(str(role) for role in (item.get("required_roles") or [])),
+            required_scopes=frozenset(str(scope) for scope in (item.get("required_scopes") or [])),
+        ))
+    default_name = raw.get("default_provider")
+    default_provider = providers.get(default_name) if default_name else DenyAuthenticationProvider()
+    return policies, default_provider
+
+
+def install_authentication(app: FastAPI, prefix: str = "AGENT_AUTH") -> bool:
+    """Install optional authentication using an isolated environment prefix.
+
+    Returns True when middleware was installed. Authentication remains disabled
+    unless ``<PREFIX>_ENABLED=true`` or a non-``none`` mode/policy file is set.
+    """
+    policy_file = os.getenv(f"{prefix}_POLICIES_FILE")
+    mode = os.getenv(f"{prefix}_MODE", "none").strip().lower()
+    enabled = _bool(os.getenv(f"{prefix}_ENABLED"), default=bool(policy_file or mode not in {"none", "disabled"}))
+    if not enabled:
+        return False
+
+    if policy_file:
+        policies, default_provider = load_authentication_policies(policy_file)
+        app.add_middleware(PolicyAuthenticationMiddleware, policies=policies, default_provider=default_provider)
+        return True
+
+    provider = create_authentication_provider(prefix)
+    public_paths = _csv(os.getenv(f"{prefix}_PUBLIC_PATHS"), "/health,/ready,/live,/docs,/openapi.json,/redoc")
+    public_prefixes = _csv(os.getenv(f"{prefix}_PUBLIC_PREFIXES"))
+    app.add_middleware(AuthenticationMiddleware, provider=provider, public_paths=public_paths, public_prefixes=public_prefixes)
+    return True
diff --git a/libs/agent_framework/src/agent_framework/security/middleware.py b/libs/agent_framework/src/agent_framework/security/middleware.py
new file mode 100644
index 0000000..470692c
--- /dev/null
+++ b/libs/agent_framework/src/agent_framework/security/middleware.py
@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import fnmatch
+import logging
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import Response
+
+from .authentication import AuthenticationProvider, DenyAuthenticationProvider
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class AuthenticationPolicy:
+    name: str
+    provider: AuthenticationProvider
+    paths: tuple[str, ...] = ("*",)
+    methods: frozenset[str] = field(default_factory=frozenset)
+    required_roles: frozenset[str] = field(default_factory=frozenset)
+    required_scopes: frozenset[str] = field(default_factory=frozenset)
+
+    def matches(self, path: str, method: str) -> bool:
+        method_matches = not self.methods or method.upper() in self.methods
+        return method_matches and any(fnmatch.fnmatchcase(path, pattern) for pattern in self.paths)
+
+
+def _claim_values(claims, names: Sequence[str]) -> set[str]:
+    values: set[str] = set()
+    for name in names:
+        raw = claims.get(name)
+        if isinstance(raw, str):
+            values.update(item for item in raw.replace(",", " ").split() if item)
+        elif isinstance(raw, (list, tuple, set)):
+            values.update(str(item) for item in raw)
+    return values
+
+
+class AuthenticationMiddleware(BaseHTTPMiddleware):
+    """Backward-compatible single-provider middleware."""
+
+    def __init__(self, app, provider: AuthenticationProvider, public_paths: Iterable[str] = (), public_prefixes: Iterable[str] = ()):
+        super().__init__(app)
+        self.provider = provider
+        self.public_paths = frozenset(public_paths)
+        self.public_prefixes = tuple(public_prefixes)
+
+    def _is_public(self, path: str) -> bool:
+        return path in self.public_paths or any(path.startswith(prefix) for prefix in self.public_prefixes)
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        if request.method == "OPTIONS" or self._is_public(request.url.path):
+            return await call_next(request)
+        return await _authenticate_request(request, call_next, self.provider)
+
+
+class PolicyAuthenticationMiddleware(BaseHTTPMiddleware):
+    """Selects the first matching route policy and authenticates the request."""
+
+    def __init__(self, app, policies: Sequence[AuthenticationPolicy], default_provider: AuthenticationProvider | None = None):
+        super().__init__(app)
+        self.policies = tuple(policies)
+        self.default_provider = default_provider or DenyAuthenticationProvider()
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        if request.method == "OPTIONS":
+            return await call_next(request)
+        policy = next((item for item in self.policies if item.matches(request.url.path, request.method)), None)
+        if policy is None:
+            return await _authenticate_request(request, call_next, self.default_provider)
+        return await _authenticate_request(
+            request,
+            call_next,
+            policy.provider,
+            policy_name=policy.name,
+            required_roles=policy.required_roles,
+            required_scopes=policy.required_scopes,
+        )
+
+
+async def _authenticate_request(request: Request, call_next: RequestResponseEndpoint, provider: AuthenticationProvider, *, policy_name: str | None = None, required_roles: frozenset[str] = frozenset(), required_scopes: frozenset[str] = frozenset()) -> Response:
+    result = await provider.authenticate(request)
+    if not result.authenticated or result.principal is None:
+        headers = {"WWW-Authenticate": result.challenge} if result.challenge else None
+        return JSONResponse(status_code=401, content={"detail": "Unauthorized", "code": result.error or "unauthorized", "policy": policy_name}, headers=headers)
+
+    roles = _claim_values(result.principal.claims, ("roles", "role", "groups"))
+    scopes = _claim_values(result.principal.claims, ("scope", "scp", "scopes"))
+    if required_roles and not required_roles.issubset(roles):
+        return JSONResponse(status_code=403, content={"detail": "Forbidden", "code": "missing_required_role", "policy": policy_name})
+    if required_scopes and not required_scopes.issubset(scopes):
+        return JSONResponse(status_code=403, content={"detail": "Forbidden", "code": "missing_required_scope", "policy": policy_name})
+
+    request.state.auth_principal = result.principal
+    request.state.auth_policy = policy_name
+    return await call_next(request)
diff --git a/tests/__pycache__/conftest.cpython-313-pytest-9.0.2.pyc b/tests/__pycache__/conftest.cpython-313-pytest-9.0.2.pyc
index dc006d7..db53f3f 100644
Binary files a/tests/__pycache__/conftest.cpython-313-pytest-9.0.2.pyc and b/tests/__pycache__/conftest.cpython-313-pytest-9.0.2.pyc differ
diff --git a/tests/unit/__pycache__/test_authentication.cpython-313-pytest-9.0.2.pyc b/tests/unit/__pycache__/test_authentication.cpython-313-pytest-9.0.2.pyc
new file mode 100644
index 0000000..a19dcc6
Binary files /dev/null and b/tests/unit/__pycache__/test_authentication.cpython-313-pytest-9.0.2.pyc differ
diff --git a/tests/unit/__pycache__/test_authentication_policies.cpython-313-pytest-9.0.2.pyc b/tests/unit/__pycache__/test_authentication_policies.cpython-313-pytest-9.0.2.pyc
new file mode 100644
index 0000000..f8d2b6b
Binary files /dev/null and b/tests/unit/__pycache__/test_authentication_policies.cpython-313-pytest-9.0.2.pyc differ
diff --git a/tests/unit/test_authentication.py b/tests/unit/test_authentication.py
new file mode 100644
index 0000000..661a6fa
--- /dev/null
+++ b/tests/unit/test_authentication.py
@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from agent_framework.security.authentication import ApiKeyAuthenticationProvider, BasicAuthenticationProvider
+from agent_framework.security.middleware import AuthenticationMiddleware
+
+
+def _basic(value: str) -> str:
+    return "Basic " + base64.b64encode(value.encode()).decode()
+
+
+def test_basic_authentication_protects_endpoint_and_keeps_health_public():
+    app = FastAPI()
+    app.add_middleware(
+        AuthenticationMiddleware,
+        provider=BasicAuthenticationProvider("tia", "sha256:" + hashlib.sha256(b"secret").hexdigest()),
+        public_paths=["/health"],
+    )
+
+    @app.get("/health")
+    async def health():
+        return {"status": "ok"}
+
+    @app.get("/protected")
+    async def protected():
+        return {"status": "protected"}
+
+    client = TestClient(app)
+    assert client.get("/health").status_code == 200
+    assert client.get("/protected").status_code == 401
+    assert client.get("/protected", headers={"Authorization": _basic("tia:wrong")}).status_code == 401
+    assert client.get("/protected", headers={"Authorization": _basic("tia:secret")}).status_code == 200
+
+
+def test_api_key_authentication():
+    app = FastAPI()
+    app.add_middleware(AuthenticationMiddleware, provider=ApiKeyAuthenticationProvider("plain:key-123"))
+
+    @app.get("/protected")
+    async def protected():
+        return {"status": "ok"}
+
+    client = TestClient(app)
+    assert client.get("/protected").status_code == 401
+    assert client.get("/protected", headers={"x-api-key": "key-123"}).status_code == 200
diff --git a/tests/unit/test_authentication_policies.py b/tests/unit/test_authentication_policies.py
new file mode 100644
index 0000000..9b4fcf1
--- /dev/null
+++ b/tests/unit/test_authentication_policies.py
@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import base64
+
+from fastapi import FastAPI, Request
+from fastapi.testclient import TestClient
+
+from agent_framework.security import (
+    AuthenticationPolicy,
+    BasicAuthenticationProvider,
+    NoAuthenticationProvider,
+    PolicyAuthenticationMiddleware,
+)
+
+
+def _basic(client_id: str, secret: str) -> str:
+    value = base64.b64encode(f"{client_id}:{secret}".encode()).decode()
+    return f"Basic {value}"
+
+
+def test_policy_middleware_public_protected_and_default_deny():
+    app = FastAPI()
+    policies = [
+        AuthenticationPolicy("public", NoAuthenticationProvider(), paths=("/health",)),
+        AuthenticationPolicy(
+            "messages",
+            BasicAuthenticationProvider("tia", "plain:secret"),
+            paths=("/gateway/*",),
+        ),
+    ]
+    app.add_middleware(PolicyAuthenticationMiddleware, policies=policies)
+
+    @app.get("/health")
+    async def health():
+        return {"ok": True}
+
+    @app.get("/gateway/message")
+    async def message(request: Request):
+        return {"subject": request.state.auth_principal.subject}
+
+    @app.get("/unknown")
+    async def unknown():
+        return {"unexpected": True}
+
+    client = TestClient(app)
+    assert client.get("/health").status_code == 200
+    assert client.get("/gateway/message").status_code == 401
+    authenticated = client.get("/gateway/message", headers={"Authorization": _basic("tia", "secret")})
+    assert authenticated.status_code == 200
+    assert authenticated.json()["subject"] == "tia"
+    assert client.get("/unknown").status_code == 401
+
+
+def test_policy_method_filter():
+    app = FastAPI()
+    policies = [AuthenticationPolicy("post-only", NoAuthenticationProvider(), paths=("/resource",), methods=frozenset({"POST"}))]
+    app.add_middleware(PolicyAuthenticationMiddleware, policies=policies)
+
+    @app.get("/resource")
+    async def get_resource():
+        return {"method": "GET"}
+
+    @app.post("/resource")
+    async def post_resource():
+        return {"method": "POST"}
+
+    client = TestClient(app)
+    assert client.post("/resource").status_code == 200
+    assert client.get("/resource").status_code == 401