first commit

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.

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.

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`.

docs/ENV_REAL_INTEGRATION_STATUS.md

@@ -0,0 +1,51 @@
+# Status real do `.env` legado TIM/FIRST
+
+Esta versão removeu a duplicidade do `.env.example` e do `mcp_servers/legacy_tim_mcp/.env.example`.
+
+## Decisão aplicada
+
+- `TIM_MCP_USE_MOCK=false` por padrão.
+- Mock só é usado quando você definir explicitamente `TIM_MCP_USE_MOCK=true`.
+- Os defaults reais encontrados no `agent_contas_first` original foram copiados.
+- Secrets e URLs que não existiam no original continuam vazios de propósito.
+
+## Defaults efetivamente encontrados no original
+
+| Variável nova | Valor preenchido | Origem no legado |
+|---|---|---|
+| `TIM_PROFILE_BILL_URL` | `http://10.151.3.100:8000` | `TIM_URL_PERFIL_FATURA` / `tim_profile_bill_url` |
+| `TIM_QUERY_VAS_URL` | `http://10.151.3.100:8000` | `TIM_URL_CONSULTA_VAS` / `TIM_CONSULTA_URL` / `tim_query_url` |
+| `TIM_BLOCK_VAS_URL` | `http://10.151.3.100:8000/customers/v1/partialServiceBlocking` | `TIM_URL_BLOQUEIO_VAS` / `TIM_BLOQUEIO_URL` / `tim_block_url` |
+| `TIM_CLIENT_ID` | `AIAGENTCR` | `tim_default_client_id` |
+| `TIM_USER_ID` | `AIAGENTCR` | usado como default nos commands/SR |
+| `TIM_DEFAULT_CSP_ID` | `740` | `tim_default_csp_id` |
+| `TIM_DEFAULT_CHANNEL` | `APP` | `tim_default_channel` |
+| `TIM_BLOCK_VAS_OPERATION_TYPE` | `block` | `tim_block_operation_type` |
+| `TIM_BLOCK_VAS_PAYLOAD_MODE` | `auto` | `tim_block_payload_mode` |
+| `TIM_BLOCK_VAS_ACCEPT_ENCODING` | `gzip,deflate` | `tim_block_accept_encoding` |
+
+## Valores que permanecem vazios
+
+Permanecem vazios porque o pacote original não trouxe valores reais para eles:
+
+- `TIM_COMPLETE_INVOICES_URL`
+- `TIM_CONTRATO_URL`
+- `TIM_BILL_PDF_URL`
+- `TIM_PROTOCOL_URL`
+- `TIM_CUSTOMER_CONTESTATION_URL`
+- `TIM_SERVICE_REQUEST_STATUS_URL`
+- `TIM_CANCEL_VAS_URL`
+- `TIM_SMS_URL`
+- `TIM_TRACKING_ACTIVITIES_URL`
+- todos os `*_AUTH`, `TIM_AUTHORIZATION_OAM`, `TIM_CN_FIELD`, `TIM_TYPE_FIELD`
+
+## Onde alterar
+
+Para executar localmente:
+
+```bash
+cp .env.example .env
+cp mcp_servers/legacy_tim_mcp/.env.example mcp_servers/legacy_tim_mcp/.env
+```
+
+Depois preencha apenas os endpoints/secrets que existirem no seu ambiente.

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
+```

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`.

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.

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.

docs/MCP_DIAGNOSTIC_FIX_V6.md

@@ -0,0 +1,129 @@
+# Correção V6 — Diagnóstico MCP e Judges
+
+## Problema observado
+
+No teste, o `agent_framework_oci` acionava o MCP Router, mas os resultados das tools vinham como:
+
+```text
+ok: False
+result: None
+error: ''
+metadata: {}
+cached: False
+```
+
+Isso impedia saber se a falha era URL, autenticação, payload, timeout, status HTTP, rede ou bug no adapter.
+
+Também apareceu:
+
+```text
+Judge calibrado declarado em judges.yaml, mas nenhum LLM foi fornecido ao pipeline.
+```
+
+## Correções aplicadas
+
+### 1. MCP server preserva erro real
+
+Arquivo alterado:
+
+```text
+mcp_servers/legacy_tim_mcp/main.py
+```
+
+Agora toda falha HTTP ou de rede retorna `metadata` com:
+
+- `server`
+- `tool`
+- `mock`
+- `prefix`
+- `method`
+- `url`
+- `status_code`, quando houver resposta HTTP
+- `response_content_type`
+- `response_body_preview`
+- `exception_type`
+- `timeout_seconds`
+- `request_payload_keys`
+- headers sanitizados, sem segredo
+
+Exemplo esperado:
+
+```json
+{
+  "ok": false,
+  "result": null,
+  "error": "TIM_COMPLETE_INVOICES falhou: status=400 body=...",
+  "metadata": {
+    "server": "legacy_tim",
+    "tool": "consultar_fatura",
+    "mock": false,
+    "method": "POST",
+    "url": "http://10.151.3.100:8000/customers/v1/completeInvoices",
+    "status_code": 400,
+    "exception_type": "HTTPStatusError",
+    "response_body_preview": "..."
+  }
+}
+```
+
+### 2. Judges recebem LLM do framework
+
+Arquivo alterado:
+
+```text
+app/workflows/agent_graph.py
+```
+
+Antes:
+
+```python
+self.judges = JudgePipeline()
+```
+
+Depois:
+
+```python
+self.judges = JudgePipeline(llm=llm, settings=settings)
+```
+
+Assim o `judges.yaml` usa o LLM criado pelo backend e o profile `judge` do `llm_profiles.yaml`.
+
+### 3. `.env` corrigido para uso com `source .env`
+
+Valores com espaço, como `Basic ...` e `Bearer ...`, foram colocados entre aspas.
+
+Exemplo:
+
+```env
+TIM_COMPLETE_INVOICES_AUTH="Basic ..."
+```
+
+## Como validar
+
+Suba o MCP:
+
+```bash
+./scripts/start_legacy_tim_mcp.sh
+```
+
+Teste direto:
+
+```bash
+./tests/curl_mcp_consultar_fatura.sh
+```
+
+Depois teste pelo backend:
+
+```bash
+./tests/curl_gateway_fatura.sh
+```
+
+No log, procure por:
+
+```text
+mcp_results
+metadata
+status_code
+response_body_preview
+mock: false
+```

docs/MCP_ENV_LOADING_FIX_V8.md

@@ -0,0 +1,56 @@
+# MCP ENV Loading Fix - V8
+
+## Problema encontrado
+
+No pacote V7, o MCP Server podia retornar:
+
+```text
+Endpoint externo não configurado para TIM_COMPLETE_INVOICES
+```
+
+mesmo quando `.env` continha:
+
+```env
+TIM_COMPLETE_INVOICES_URL=http://10.151.3.100:8000/customers/v1/completeInvoices
+```
+
+A causa era que o MCP dependia do ambiente já estar carregado pelo shell (`source .env`) ou pelo Docker `env_file`. Quando o `uvicorn main:app` era iniciado diretamente, o arquivo `.env` não era carregado automaticamente.
+
+## Correção aplicada
+
+O MCP Server agora carrega automaticamente:
+
+1. `.env` do diretório corrente.
+2. `.env` local do MCP Server: `mcp_servers/legacy_tim_mcp/.env`.
+3. `.env` da raiz do projeto.
+
+A carga preenche variáveis ausentes ou exportadas como string vazia.
+
+## Novos endpoints de diagnóstico
+
+```bash
+curl http://localhost:8100/health | jq
+curl http://localhost:8100/debug/config | jq
+```
+
+O retorno agora mostra:
+
+- arquivos `.env` carregados;
+- endpoints configurados;
+- URLs resolvidas;
+- presença de autenticação sem expor o secret.
+
+## Validação esperada
+
+Para `TIM_COMPLETE_INVOICES`, deve aparecer:
+
+```json
+{
+  "url": "http://10.151.3.100:8000/customers/v1/completeInvoices",
+  "has_auth": true,
+  "timeout": 30.0,
+  "client_id": "AIAGENTCR"
+}
+```
+
+Se a URL aparecer vazia, o MCP não está lendo o `.env` correto ou o arquivo não contém a variável.

docs/MCP_EXTERNAL_SERVICES_IMPLEMENTATION.md

@@ -0,0 +1,44 @@
+# Implementação MCP dos serviços externos
+
+Esta versão adiciona um MCP Server `legacy_tim_mcp` para adaptar os comandos externos do legado ao contrato do `agent_framework_oci`.
+
+## Contrato
+
+O framework chama:
+
+```text
+POST /mcp/tools/call
+```
+
+Payload:
+
+```json
+{"tool_name":"consultar_fatura","arguments":{"msisdn":"11999999999"}}
+```
+
+## Onde configurar
+
+- Backend: `config/mcp_servers.yaml`
+- Tools: `config/tools.yaml`
+- Mapeamento: `config/mcp_parameter_mapping.yaml`
+- MCP Server: `mcp_servers/legacy_tim_mcp/.env`
+
+## Serviços cobertos
+
+- Fatura completa / perfil de fatura
+- Pagamentos
+- Contrato/plano
+- VAS/SVA/listagem de serviços
+- PDF/segunda via
+- Protocolo
+- Contestação/SR
+- Status/atualização de SR
+- Cancelamento/bloqueio VAS
+- SMS
+- Tracking activities
+
+## Modo mock vs real
+
+`TIM_MCP_USE_MOCK=true` devolve respostas simuladas.
+
+`TIM_MCP_USE_MOCK=false` exige endpoints reais `TIM_*_URL`.

docs/MCP_LEGACY_COMMAND_MIGRATION_V7.md

@@ -0,0 +1,104 @@
+# V7 — MCP legado TIM/FIRST com padrão Command + ApiGateway
+
+Esta versão corrige a camada MCP do `agent_contas_first` para ficar mais próxima do projeto original.
+
+## O que mudou
+
+A versão anterior ainda fazia chamadas HTTP muito genéricas. A V7 implementa no MCP Server local uma camada inspirada no legado:
+
+```text
+MCP Tool
+  -> LegacyTimCommand
+  -> EndpointConfig
+  -> HttpApiGateway
+  -> GatewayError rico
+  -> retorno MCP com error/metadata preservados
+```
+
+## Evidência esperada nos logs
+
+Em caso de erro real do backend TIM, o `mcp_results` deve aparecer assim:
+
+```json
+{
+  "tool_name": "consultar_fatura",
+  "server_name": "legacy_tim",
+  "ok": false,
+  "error": "TIM_COMPLETE_INVOICES falhou: status=400 body=...",
+  "metadata": {
+    "server": "legacy_tim",
+    "tool": "consultar_fatura",
+    "mock": false,
+    "endpoint": "TIM_COMPLETE_INVOICES",
+    "method": "POST",
+    "url": "http://10.151.3.100:8000/customers/v1/completeInvoices",
+    "status_code": 400,
+    "error_code": "HTTP_400",
+    "provider_service": "...",
+    "provider_error_code": "...",
+    "provider_error_message": "...",
+    "message_id": "...",
+    "kong_request_id": "...",
+    "latency_ms": 123,
+    "exception_type": "HTTPStatusError",
+    "response_body_preview": "..."
+  },
+  "cached": false
+}
+```
+
+Se ainda aparecer:
+
+```json
+{"ok": false, "error": "", "metadata": {}}
+```
+
+então provavelmente uma janela antiga do `legacy_tim_mcp` ainda está rodando ou o backend não foi reiniciado depois da troca do pacote.
+
+## Tools migradas para Commands
+
+| MCP Tool | Command V7 | Endpoint |
+|---|---|---|
+| `consultar_fatura` | `CompleteInvoicesCommand` | `TIM_COMPLETE_INVOICES` |
+| `consultar_pagamentos` | `ProfileBillCommand` | `TIM_PROFILE_BILL` |
+| `consultar_plano` | `ContractInformationCommand` | `TIM_CONTRATO` |
+| `listar_servicos` | `QueryVasCommand` | `TIM_QUERY_VAS` |
+| `recuperar_pdf_fatura` | `InvoiceRecoverCommand` | `TIM_BILL_PDF` |
+| `registrar_protocolo` | `ProtocolCommand` | `TIM_PROTOCOL` |
+| `abrir_contestacao` | `CustomerContestationCommand` | `TIM_CUSTOMER_CONTESTATION` |
+| `consultar_status_sr` | `ServiceRequestStatusCommand` | `TIM_SERVICE_REQUEST_STATUS` |
+| `cancelar_vas` | `CancelVasCommand` | `TIM_CANCEL_VAS` |
+| `bloquear_vas` | `BlockVasCommand` | `TIM_BLOCK_VAS` |
+| `enviar_sms` | `SmsCommand` | `TIM_SMS` |
+| `registrar_tracking` | `TrackingActivitiesCommand` | `TIM_TRACKING_ACTIVITIES` |
+
+## Como testar só o MCP
+
+```bash
+cd mcp_servers/legacy_tim_mcp
+set -a
+source .env
+set +a
+uvicorn main:app --host 0.0.0.0 --port 8100 --reload
+```
+
+Em outro terminal:
+
+```bash
+curl -s http://localhost:8100/health | jq
+
+curl -s -X POST http://localhost:8100/mcp/tools/call \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "tool_name":"consultar_fatura",
+    "arguments":{"msisdn":"11999999999","invoice_id":"3000131180"}
+  }' | jq
+```
+
+## Checklist de execução
+
+1. Pare qualquer processo antigo do MCP na porta `8100`.
+2. Suba o MCP V7.
+3. Reinicie o backend do agente.
+4. Rode o curl do gateway.
+5. Verifique se `mcp_results[].metadata.endpoint`, `status_code`, `url` e `response_body_preview` aparecem.

docs/MCP_REAL_INTEGRATION_NOTES.md

@@ -0,0 +1,49 @@
+# MCP Legacy TIM/FIRST — integração real
+
+Esta versão troca o MCP puramente mockado por um adapter HTTP real baseado nos contratos encontrados no projeto original `agent_contas_first`.
+
+## Modo de execução
+
+Por padrão:
+
+```env
+TIM_MCP_USE_MOCK=false
+```
+
+Com isso, as tools chamam os backends externos configurados no `.env`. Para testes locais sem rede TIM, use:
+
+```env
+TIM_MCP_USE_MOCK=true
+```
+
+## Contratos implementados a partir do legado
+
+| Tool MCP | Endpoint/env | Método | Contrato legado usado |
+|---|---|---:|---|
+| `consultar_fatura` | `TIM_COMPLETE_INVOICES_URL` | POST | `CompleteInvoicesCommand`: `{"msisdn": "..."}` |
+| `consultar_pagamentos` | `TIM_PROFILE_BILL_URL` | POST | `QueryProfileBillCommand`: `{"msisdn": "..."}` |
+| `consultar_plano` | `TIM_CONTRATO_URL/{msisdn}` | GET | `ContratoCommand` |
+| `listar_servicos` | `TIM_QUERY_VAS_URL/{msisdn}` | GET | `QueryVasCommand` |
+| `recuperar_pdf_fatura` | `TIM_BILL_PDF_URL?invoiceId=&msisdn=&customerId=` | GET | `InvoiceRecoverCommand` / `BillPdfCommand` |
+| `explicar_fatura` | `TIM_INVOICE_EXPLANATION_URL/{msisdn}?channel=APP` | GET | `InvoiceExplanationCommand` |
+| `registrar_protocolo` | `TIM_PROTOCOL_URL` | POST | `RegisterProtocolV2Command` |
+| `abrir_contestacao` | `TIM_CUSTOMER_CONTESTATION_URL` | POST | `CustomerContestationCommand` |
+| `consultar_status_sr` / `atualizar_status_sr` | `TIM_SERVICE_REQUEST_STATUS_URL` | POST | `UpdateServiceRequestStatusCommand` |
+| `cancelar_vas` | `TIM_CANCEL_VAS_URL` | DELETE | `CancellationVasCommand` |
+| `bloquear_vas` | `TIM_BLOCK_VAS_URL` | POST | `BlockVasCommand` |
+| `enviar_sms` | `TIM_SMS_URL` | POST | `SendSmsCommand` |
+| `registrar_tracking` | `TIM_TRACKING_ACTIVITIES_URL` | POST | `TrackingActivitiesCommand` |
+
+## Observação importante
+
+O projeto original não trazia secrets reais. O adapter usa os nomes de variáveis do legado e aliases compatíveis, mas os valores de autenticação precisam ser preenchidos no `.env` do ambiente.
+
+## Validação rápida
+
+```bash
+./scripts/start_legacy_tim_mcp.sh
+curl http://localhost:8100/health
+curl -s -X POST http://localhost:8100/mcp/tools/call \
+  -H 'Content-Type: application/json' \
+  -d '{"tool_name":"consultar_fatura","arguments":{"msisdn":"11999999999"}}' | jq
+```

docs/TIM_LEGACY_ENV_MAPPING.md

@@ -0,0 +1,55 @@
+# TIM/FIRST Legacy Environment Mapping
+
+Este arquivo documenta o que foi recuperado do `agent_contas_first` original para configurar o MCP server adaptado.
+
+## Resultado da auditoria
+
+O pacote original não trouxe `.env`, Secret, ConfigMap ou arquivo com credenciais reais. A fonte disponível foi `agente_contas_tim/config.py`, que define aliases e alguns defaults. Por isso:
+
+- URLs com default no código foram preenchidas.
+- URLs que no legado tinham default vazio permaneceram vazias.
+- Tokens/Authorization permaneceram vazios por segurança e porque não estavam no pacote.
+- O MCP server agora aceita tanto os nomes novos quanto os aliases antigos.
+
+## Tabela de mapeamento
+
+| Variável nova | Alias/variável no legado | Valor inferido | Status |
+|---|---|---:|---|
+| `TIM_QUERY_VAS_URL` | `TIM_URL_CONSULTA_VAS`, `TIM_CONSULTA_URL` | `http://10.151.3.100:8000` | preenchido |
+| `TIM_QUERY_VAS_AUTH` | `TIM_QUERY_AUTH`, `TIM_CONSULTA_AUTH` | vazio | requer secret |
+| `TIM_BLOCK_VAS_URL` | `TIM_URL_BLOQUEIO_VAS`, `TIM_BLOQUEIO_URL` | `http://10.151.3.100:8000/customers/v1/partialServiceBlocking` | preenchido |
+| `TIM_BLOCK_VAS_AUTH` | `TIM_BLOCK_AUTH`, `TIM_BLOQUEIO_AUTH` | vazio | requer secret |
+| `TIM_CANCEL_VAS_URL` | `TIM_CANCELLATION_URL`, `TIM_CANCELAMENTO_URL` | vazio | não encontrado no pacote |
+| `TIM_CANCEL_VAS_AUTH` | `TIM_CANCELLATION_AUTH`, `TIM_CANCELAMENTO_AUTH` | vazio | requer secret |
+| `TIM_AUTHORIZATION_OAM` | `TIM_CANCELLATION_AUTH_OAM`, `TIM_CANCELAMENTO_AUTH_OAM`, `TIM_CANCELAMENTO_AUTHORIZATION_OAM` | vazio | requer secret |
+| `TIM_CN_FIELD` | `TIM_CANCELLATION_CN_FIELD`, `TIM_CANCELAMENTO_CN_FIELD` | vazio | não encontrado no pacote |
+| `TIM_TYPE_FIELD` | `TIM_CANCELLATION_TYPE_FIELD`, `TIM_CANCELAMENTO_TYPE_FIELD` | vazio | não encontrado no pacote |
+| `TIM_PROFILE_BILL_URL` | `TIM_URL_PERFIL_FATURA` | `http://10.151.3.100:8000` | preenchido |
+| `TIM_COMPLETE_INVOICES_URL` | `TIM_COMPLETE_INVOICES_URL` | vazio | não encontrado no pacote |
+| `TIM_CONTRATO_URL` | `TIM_CONTRATO_URL` | vazio | não encontrado no pacote |
+| `TIM_BILL_PDF_URL` | `TIM_URL_INVOICE_RECOVER` | vazio | não encontrado no pacote |
+| `TIM_BILL_PDF_AUTH` | `TIM_INVOICE_RECOVER_AUTH` | vazio | requer secret |
+| `TIM_PROTOCOL_URL` | `TIM_PROTOCOL_URL` | vazio | não encontrado no pacote |
+| `TIM_CUSTOMER_CONTESTATION_URL` | `TIM_CUSTOMER_CONTESTATION_URL` | vazio | não encontrado no pacote |
+| `TIM_SERVICE_REQUEST_STATUS_URL` | `TIM_SERVICE_REQUEST_STATUS_URL` | vazio | não encontrado no pacote |
+| `TIM_SMS_AUTH` | `SMS_BARCODE_AUTH`, `TIM_SMS_AUTH` | vazio | requer secret |
+| `TIM_TRACKING_ACTIVITIES_URL` | `TIM_TRACKING_ACTIVITIES_URL` | vazio | não encontrado no pacote |
+| `TIM_TRACKING_ACTIVITIES_USER_LOGIN` | igual | vazio | obrigatório no legado, não encontrado |
+| `TIM_TRACKING_ACTIVITIES_CHANNEL` | igual | vazio | obrigatório no legado, não encontrado |
+| `TIM_TRACKING_ACTIVITIES_CLIENT_ID` | igual | vazio | obrigatório no legado, não encontrado |
+
+## Implicação para teste
+
+Para teste local sem rede TIM, use:
+
+```env
+TIM_MCP_USE_MOCK=true
+```
+
+Para teste integrado real, altere para:
+
+```env
+TIM_MCP_USE_MOCK=false
+```
+
+e preencha as URLs/secrets vazias acima.

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
+

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.