bugfix

FRAMEWORK_NATIVE_CORRECTIONS.md

@@ -0,0 +1,31 @@
+# Correções framework-native aplicadas no Compass Backoffice
+
+Este pacote foi corrigido para reduzir forks locais e usar o máximo possível do `agent_framework_oci`.
+
+## Correções principais
+
+1. `app/agents/runtime.py` deixou de manter um runtime próprio.
+   - Agora reexporta `AgentRuntimeMixin`, `RuntimeContext` e `MessageBuilder` diretamente de `agent_framework.runtime.agent_runtime`.
+   - Isso ativa o comportamento nativo do framework para MCP, cache MCP por `args_schema`, deduplicação intra-turno, RAG, memória, cache LLM e eventos IC/NOC/GRL.
+
+2. `BackofficeWorkflowExecutor` passou a carregar judges pelo profile do agente.
+   - Antes: `JudgePipeline()` usava o caminho global por padrão.
+   - Agora: `JudgePipeline(settings=settings, config_path=self.agent_profile.get("judges_config_path"))`.
+   - Com isso o agente `backoffice_anatel` usa `config/agents/backoffice_anatel/judges.yaml`.
+
+3. `config/guardrails.yaml` foi alinhado com `config/agents/backoffice_anatel/guardrails.yaml`.
+   - Evita que estágios do framework que leem o arquivo global executem uma política mais fraca.
+   - Guardrails ativos: `INPUT_SIZE`, `MSK`, `PINJ`, `TOX`, `DLEX_IN`, `RAGSEC`, `VLOOP`, `REVPREC`, `DLEX_OUT`, `OOS`, `CMP`, `AOFERTA`.
+
+4. `config/judges.yaml` foi alinhado com `config/agents/backoffice_anatel/judges.yaml`.
+   - Evita divergência entre execução global e execução por agente.
+   - Inclui judges de qualidade, groundedness e políticas específicas do domínio backoffice.
+
+5. `config/tools.yaml` recebeu política declarativa de MCP.
+   - Tools de consulta: `tool_type: read` e `cache.enabled: true`.
+   - Tools mutáveis/de ação: `tool_type: action`, `requires` e `cache.enabled: false`.
+   - A chave de cache passa a ser controlada pelo runtime do framework usando `args_schema`.
+
+## Regra arquitetural preservada
+
+As regras genéricas de segurança, qualidade, vazamento, repetição, escopo, groundedness e revisão de resposta ficam no framework. As regras específicas do domínio ANATEL/Backoffice permanecem como workflow de domínio, porque representam etapas de negócio e não guardrails reutilizáveis.