compass_backoffice/FRAMEWORK_NATIVE_CORRECTIONS.md

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.