first commit

docs/AJUSTES_IC_NOC_GRL_OCI_OPENAI.md

@@ -0,0 +1,39 @@
+# Ajustes IC/NOC/GRL e LLM_PROVIDER=oci_openai
+
+Esta versão corrige dois pontos do runtime nativo do backoffice:
+
+1. **IC/NOC/GRL padronizados pelo framework**
+   - O workflow nativo agora emite eventos pelo `AgentObserver` do framework.
+   - Eventos legados `AGA.*`, `NOC.*` e `GRL.*` capturados dos nós originais são reemitidos pela ponte `_bridge_legacy_ics`.
+   - O runtime emite explicitamente eventos de início, conclusão e falha do workflow.
+   - Os guardrails emitem GRL explícitos para input, output supervisor e output guardrails.
+
+2. **Suporte ao `LLM_PROVIDER=oci_openai`**
+   - `src/core/config.py` agora aceita `oci_openai` no validador local usado pelos nós do backoffice original.
+   - `.env.example` usa `LLM_PROVIDER=oci_openai` por padrão e documenta as variáveis esperadas para OCI/OpenAI-compatible.
+
+## Eventos adicionados no workflow nativo
+
+- `IC.BACKOFFICE_WORKFLOW_STARTED`
+- `IC.BACKOFFICE_WORKFLOW_COMPLETED`
+- `IC.BACKOFFICE_NODE_STARTED`
+- `IC.BACKOFFICE_NODE_COMPLETED`
+- `NOC.001` workflow started
+- `NOC.006` workflow completed
+- `NOC.009` workflow/node failed
+- `GRL.001` input guardrails started
+- `GRL.002` input guardrails completed
+- `GRL.003` input blocked
+- `GRL.004` output supervisor started
+- `GRL.005` output supervisor completed
+- `GRL.006` output supervisor blocked/handover
+- `GRL.007` output guardrails started
+- `GRL.008` output guardrails completed
+- `GRL.009` output blocked/sanitized
+
+## Arquivos alterados
+
+- `app/workflows/backoffice_native_runtime.py`
+- `src/core/config.py`
+- `.env.example`
+- `tools/validate_parity.py`

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/CORRECAO_ENV_MCP_TIM_CLIENTS.md

@@ -0,0 +1,88 @@
+# Correção: .env original TIM + MCP Server + URLs
+
+## Problema corrigido
+
+O pacote anterior ainda tratava o MCP Server como um backend REST genérico baseado em `BACKOFFICE_MCP_REST_BASE_URL`. Quando essa variável não existia, uma chamada HTTP podia ser montada com URL vazia, gerando erro como:
+
+```text
+Request URL is missing an 'http://' or 'https://' protocol.
+```
+
+Além disso, o `.env` original do backoffice `develop` usa variáveis específicas:
+
+```text
+PMID_API_HOST
+SIEBEL_API_HOST
+SPEECH_PREDICTION_BASE_URL
+SPEECH_HISTORY_BASE_URL
+TAIS_DB_DSN
+TAIS_GENAI_ENDPOINT
+...
+```
+
+Essas variáveis não devem ser substituídas por uma URL REST genérica.
+
+## Ajustes implementados
+
+1. `src/core/config.py` agora carrega explicitamente o `.env` da raiz do projeto.
+2. `config/mcp_servers.yaml` agora usa endpoint literal seguro:
+
+```yaml
+endpoint: http://localhost:8010
+```
+
+Isso evita depender de expansão YAML `${VAR:default}` caso o `MCPToolRouter` do framework não suporte esse formato.
+
+3. `mcp_servers/backoffice_mcp_server/settings.py` agora aceita:
+
+- variáveis `BACKOFFICE_MCP_*`, quando existirem;
+- variáveis originais TIM/develop, como `PMID_API_HOST`, `SIEBEL_API_HOST`, `SPEECH_*`, `TAIS_*`.
+
+4. O default do MCP Server passou a ser:
+
+```text
+BACKOFFICE_MCP_BACKEND_TYPE=tim_clients
+BACKOFFICE_MCP_USE_MOCK=false
+```
+
+Assim o MCP não mascara erro usando mock quando o `.env` real está presente.
+
+5. As tools IMDB/PMID, Speech, TAIS, ABRT e Portabilidade passam a chamar os clients originais do projeto quando `backend_type=tim_clients`.
+
+## Como testar
+
+Suba o MCP Server:
+
+```bash
+uvicorn mcp_servers.backoffice_mcp_server.main:app --host 0.0.0.0 --port 8010 --reload
+```
+
+Confirme o health:
+
+```bash
+curl http://localhost:8010/health
+```
+
+O retorno deve indicar:
+
+```json
+{
+  "use_mock": false,
+  "backend_type": "tim_clients",
+  "tim_clients_configured": true
+}
+```
+
+Depois suba o backend principal:
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 9000 --reload
+```
+
+Teste a lista de tools via backend:
+
+```bash
+curl http://localhost:9000/debug/mcp/tools
+```
+
+Se o MCP estiver ativo, essa chamada deve chegar no processo da porta `8010`.

docs/CORRECAO_EXTRACAO_CPF_TEXTO_LIVRE.md

@@ -0,0 +1,57 @@
+# Correção: extração de CPF/CNPJ/protocolo em texto livre
+
+## Problema
+
+Mensagem como:
+
+```text
+consultar dados do cliente cpf 169.323.728-86
+```
+
+não preenchia `BusinessContext.customer_key`, porque o `IdentityResolver` do framework resolve campos estruturados do payload/contexto, mas não extraía identificadores digitados livremente no texto.
+
+## Ajuste
+
+Adicionado:
+
+```text
+app/identity_extraction.py
+```
+
+com extração defensiva de:
+
+- CPF
+- CNPJ
+- MSISDN com rótulo explícito
+- protocolo/chamado/reclamação/ticket
+
+## Integração
+
+`app/main.py` agora enriquece o payload antes de chamar o `IdentityResolver`:
+
+```python
+payload = enrich_payload_with_text_identity(req.payload or {})
+```
+
+`app/agents/backoffice_agent.py` também usa a extração como fallback antes de chamar tools MCP, garantindo que `customer_key` e `protocol_id` sejam preenchidos quando vierem no texto.
+
+## Exemplo
+
+Entrada:
+
+```json
+{
+  "message": "consultar dados do cliente cpf 169.323.728-86"
+}
+```
+
+Contexto extraído:
+
+```json
+{
+  "customer_key": "16932372886",
+  "cpf": "16932372886",
+  "document": "16932372886",
+  "document_type": "cpf"
+}
+```

docs/CORRECAO_IMPORTS_AGENT_FRAMEWORK_7.md

@@ -0,0 +1,55 @@
+# Correção de compatibilidade com agent_framework(7)
+
+Esta versão remove referências a módulos que não existem no `agent_framework(7).zip`, principalmente:
+
+- `agent_framework.core`
+- `agent_framework.components`
+- `agent_framework.llm.factory`
+- `agent_framework.observer.application_log`
+- `agent_framework.observer.publishers`
+- `agent_framework.observer.types`
+
+## LLM
+
+O provider de LLM do backoffice agora usa o ponto real do framework:
+
+```python
+from agent_framework.llm.providers import create_llm
+from agent_framework.config.settings import settings as fw_settings
+```
+
+Assim, `LLM_PROVIDER=oci_openai` passa a operar pelo provider oficial do framework:
+
+```python
+agent_framework.llm.providers.OCICompatibleOpenAIProvider
+```
+
+## Exceptions
+
+Como o framework atual não possui `agent_framework.core.exceptions`, as exceções HTTP/de domínio do backoffice foram isoladas em:
+
+```text
+src/core/exceptions.py
+```
+
+Isso mantém o tratamento de erro do backoffice sem inventar módulos inexistentes no framework.
+
+## Logging
+
+A dependência inexistente de `observer.application_log.StructuredLogger` foi removida. O backoffice usa um helper local mínimo apenas para compatibilidade do formatter.
+
+## Validação
+
+O script abaixo agora falha se algum import proibido reaparecer em `app/` ou `src/`:
+
+```bash
+python tools/validate_parity.py
+```
+
+Validações executadas nesta versão:
+
+```text
+OK: backoffice framework-native structural validation passed
+OK: no forbidden agent_framework imports
+COMPILE_OK
+```

docs/CORRECAO_MCP_PARAMETROS_CPF_EXPLICITO.md

@@ -0,0 +1,8 @@
+# Correção MCP parâmetros + CPF explícito
+
+Esta versão corrige dois problemas observados no teste `consultar dados do cliente cpf 169.323.728-86`:
+
+1. O `BusinessContext.customer_key` permanecia com o `msisdn` padrão da sessão (`11999999999`) porque o `IdentityResolver` do framework preserva chaves já definidas. Agora CPF/CNPJ/protocolo explicitamente digitados na mensagem atual prevalecem sobre valores herdados da sessão.
+2. O `MCPToolRouter` preserva `original_context` e `extra_args`; isso enviava muitos campos extras para o MCP Server, gerando `TypeError: unexpected keyword argument`. Agora o MCP Server filtra os argumentos usando o `input_schema` da tool antes de chamar o handler.
+
+Também foram adicionados aliases `cpf`, `cnpj`, `document` e `document_type` para tools de cliente/IMDB/Speech/ABRT/Portabilidade.

docs/CORRECAO_PROTOCOL_ID_MCP_MAPPING.md

@@ -0,0 +1,81 @@
+# Correção: protocol_id ausente nas tools MCP
+
+## Problema
+
+O backend retornava mensagens como:
+
+```text
+[BackofficeAgent] Não foi possível consultar os dados do cliente. As ferramentas retornaram erro de protocolo ausente na requisição.
+```
+
+A causa principal era o arquivo `config/mcp_parameter_mapping.yaml` com o mapeamento invertido.
+
+O `MCPParameterMapper` do framework interpreta o mapa como:
+
+```yaml
+canonical_key: tool_argument_name
+```
+
+Mas o pacote estava usando:
+
+```yaml
+protocol_id: interaction_key
+```
+
+Como `protocol_id` não é uma chave canônica de `BusinessContext`, o mapper não enviava `protocol_id` para o MCP Server.
+
+## Correção
+
+O mapeamento foi corrigido para:
+
+```yaml
+interaction_key: protocol_id
+customer_key: customer_key
+contract_key: contract_key
+session_key: session_key
+```
+
+Também foram adicionadas fontes no `config/identity.yaml` para resolver `interaction_key` a partir de contratos legados do backoffice:
+
+- `protocol_id`
+- `protocolo`
+- `complaint_id`
+- `complaintProtocol`
+- `complaint.complaintProtocol`
+- `complaint.protocol`
+- `complaint.protocol_id`
+- `complaint.id`
+- `transactionId`
+- `transaction_id`
+- `ticket_id`
+
+Além disso, `app/agents/backoffice_agent.py` passou a enviar aliases defensivos (`protocol_id`, `interaction_key`, `customer_key`, `contract_key`, `session_key`) em `extra_args` para o `MCPToolRouter`, sem substituir o mapper do framework.
+
+## Resultado esperado
+
+Chamadas como:
+
+```json
+{
+  "channel": "web",
+  "payload": {
+    "message": "consultar cliente",
+    "protocol_id": "12345",
+    "customer_key": "11999999999"
+  }
+}
+```
+
+ou payloads legados como:
+
+```json
+{
+  "payload": {
+    "transactionId": "12345",
+    "complaint": {"complaintProtocol": "12345"},
+    "customer": {"msisdn": "11999999999"}
+  }
+}
+```
+
+agora alimentam `BusinessContext.interaction_key` e chegam nas tools MCP como `protocol_id`.

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/OPCAO_B_LLM_PROVIDER_TELEMETRY.md

@@ -0,0 +1,32 @@
+# Ajuste Opção B — Telemetria de LLM pelo framework
+
+Esta versão remove o uso de `generation(...)` dos nós de domínio do backoffice.
+
+## Decisão arquitetural
+
+- O backend backoffice não implementa nem simula `generation`.
+- Os nós de domínio chamam `chat_llm_with_usage(...)`.
+- `chat_llm_with_usage(...)` usa `agent_framework.llm.providers.create_llm(...)`.
+- A telemetria de geração, tokens, custo, modelo e latência fica centralizada no provider do framework.
+
+## Arquivos ajustados
+
+- `src/agent/nodes/speech_enrichment_node.py`
+- `src/agent/nodes/tim_complaint_analysis_node.py`
+- `src/agent/nodes/treatment_decision_node.py`
+- `src/agent/nodes/siebel_triplet_classification_node.py`
+- `src/compat/framework_observer.py`
+- `src/utils/ics_collector.py`
+
+## Removido
+
+- Import de `generation` nos nós de domínio.
+- Context managers `with generation(...)`.
+- Monkey patch de `agent_framework.observer.generation`.
+- Provider legado `src/providers/langfuse_tracer.py`, que era redundante com o framework.
+
+## Mantido
+
+- Eventos AGA/NOC/IC/GRL continuam emitidos via `src.compat.framework_observer.event(...)`, que delega para `agent_framework.observer`.
+- Eventos de erro LLM (`NOC.004`, `NOC.009`) continuam preservados nos nós.
+- Tokens e uso do LLM continuam retornando em `LLMResponse` para ICs de negócio, mas a observabilidade de geração é responsabilidade do framework.

docs/RELATORIO_FRAMEWORK_NATIVE_100.md

@@ -0,0 +1,110 @@
+# Relatório da refatoração framework-native
+
+## Resultado
+
+A versão foi refatorada para que o backoffice não execute mais grafos LangGraph legados diretamente. Os grafos originais do develop foram movidos para `legacy_reference_disabled/` e deixados apenas como referência/auditoria.
+
+## Arquitetura ativa
+
+O backend ativo usa:
+
+- `app/main.py` como camada de rotas/adapters.
+- `app/workflows/backoffice_native_runtime.py` como runtime de workflows do framework.
+- `src/agent/nodes/*` como nós de domínio.
+- `src/components/clients/*` como services/clients de domínio.
+- `src/agent/local_prompts/*` como prompts de domínio.
+- `config/agents/backoffice_anatel/*` como políticas de guardrails, judges e prompt policy.
+
+## Fluxo checklist ativo
+
+```text
+framework_input_guardrails
+fetch_ticket
+validation
+bypass_rules
+cache_check
+imdb_enrichment
+identity_verification
+speech_enrichment
+knowledge_base_enrichment
+canceling_analysis
+tim_complaint_analysis
+operator_route
+reclassification_analysis
+treatment_decision
+siebel_sr_opening
+framework_output_supervisor
+framework_output_guardrails
+framework_judges
+framework_supervisor_review
+framework_persist
+```
+
+## Fluxo response emulator ativo
+
+```text
+framework_input_guardrails
+start_response_emulation
+fetch_case
+validate_actions
+router
+retrieve_templates
+retrieve_history
+generate_response
+validate_response
+persist_draft / approve_draft / close_case
+framework_output_supervisor
+framework_output_guardrails
+framework_judges
+framework_supervisor_review
+framework_persist
+```
+
+## Diferença em relação à versão anterior
+
+Antes:
+
+```text
+app/main.py registrava routers originais
+rotas originais chamavam src.api.executors
+executors chamavam src.agent.graphs
+src.agent.graphs criava StateGraph diretamente
+```
+
+Agora:
+
+```text
+app/main.py chama backoffice_runtime.execute_workflow
+BackofficeNativeRuntime compila os workflows
+os nós originais são apenas plugins de domínio
+guardrails/judges/supervisor/checkpoint/telemetry entram no runtime
+```
+
+## Limites honestos
+
+A compilação está validada. A execução real depende das mesmas integrações externas do develop: IMDB, Siebel, Speech Analytics, TAIS KB, ABRT, Portabilidade, Autonomous DB, OCI Streaming e credenciais.
+
+## Ajuste aplicado: binding explícito dos guardrails do agente
+
+O runtime nativo agora resolve `config/agents.yaml`, localiza o profile `backoffice_anatel` e carrega explicitamente `guardrails_config_path`:
+
+```text
+config/agents/backoffice_anatel/guardrails.yaml
+```
+
+Com isso, os guardrails continuam sendo **executados pelo framework** (`GuardrailPipeline` e `OutputSupervisor`), mas a política ativa vem do backend/domínio do agente. A metadata do workflow também passa a registrar:
+
+```text
+agent_id
+ guardrails_profile
+ guardrails_config_path
+ active_input_rails
+ active_output_rails
+```
+
+Assim é possível validar em telemetry/debug que o backoffice não está usando apenas `config/guardrails.yaml` global, mas sim a configuração completa do agente:
+
+```text
+INPUT_SIZE, MSK, PINJ, TOX, DLEX_IN, RAGSEC, VLOOP
+REVPREC, DLEX_OUT, OOS, CMP, AOFERTA
+```

docs/RELATORIO_PARIDADE_BACKOFFICE_100.md

@@ -0,0 +1,45 @@
+# Relatório de paridade — Backoffice convertido 100%
+
+## Resultado
+
+Esta versão deixa de ser apenas um agente genérico com ferramentas MCP e passa a hospedar a implementação original da branch `develop` dentro da aplicação do Agent Framework.
+
+## Paridade implementada
+
+| Item | Status |
+|---|---|
+| Grafo checklist original | Implementado |
+| Grafo response emulator original | Implementado |
+| Rotas REST originais | Implementadas |
+| Schemas originais | Implementados |
+| Clients TIM originais | Implementados |
+| Prompts originais | Implementados |
+| Nós de negócio originais | Implementados |
+| Testes originais | Copiados em `tests_original_develop/` |
+| Gateway novo do framework | Mantido |
+| Guardrails do framework | Mantidos e reforçados |
+| Judges do framework | Mantidos e reforçados |
+| Supervisor do framework | Mantido |
+| MCP Tool Router | Mantido |
+| IC/NOC/AGA original | Preservado via `src/utils/ics_collector.py` e observer original |
+| IC/NOC/GRL framework | Mantido via `AgentObserver` |
+
+## Decisão de arquitetura
+
+A lógica original de domínio foi mantida em `src/` para garantir paridade. O framework hospeda essa lógica e a envolve com as capacidades enterprise novas.
+
+Isso evita perder comportamento dos nós originais como validação ANATEL, IMDB, Speech Analytics, TAIS KB, cancelamento, reclassificação, tratamento, Siebel SR e Response Emulator.
+
+## Arquivos centrais alterados
+
+- `app/main.py`: registra workflows e rotas originais dentro do app do framework.
+- `app/agents/backoffice_agent.py`: quando recebe ticket ANATEL completo pelo gateway, executa o workflow checklist original como workflow de domínio.
+- `config/agents/backoffice_anatel/guardrails.yaml`: reforço dos rails de domínio.
+- `config/agents/backoffice_anatel/judges.yaml`: judges específicos para protocolo, Siebel, rastreabilidade e emulator.
+- `.env.example`: substitui `.env` com segredos reais.
+
+## Limites conhecidos
+
+- A execução real dos serviços TIM depende das variáveis de ambiente e conectividade corporativa.
+- Em ambiente local sem VPN/credenciais, os clients originais podem falhar ou usar fallback/mock conforme o código original.
+- Os testes copiados de `tests_original_develop/` ainda devem ser executados no ambiente com dependências completas do projeto original.

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.