first commit

README_BACKOFFICE_NATIVE_FRAMEWORK.md

@@ -0,0 +1,64 @@
+# Backoffice/ANATEL migrado para uso nativo do framework
+
+Esta versão remove o fluxo `backoffice_legacy_flow.py` do caminho ativo do agente.
+O agente passa a usar apenas capacidades nativas do framework:
+
+- LangGraph corporativo do projeto;
+- EnterpriseRouter configurado em `config/routing.yaml`;
+- `BusinessContext` e `identity.yaml`;
+- `MCPToolRouter` e `mcp_parameter_mapping.yaml`;
+- RAG via `RagService`;
+- cache via `create_cache`;
+- IC/NOC/GRL via `AgentObserver`;
+- OutputSupervisor, guardrails de saída, judges e persistência do workflow.
+
+## Arquivo principal
+
+```text
+app/agents/backoffice_agent.py
+```
+
+O agente não importa mais `app.workflows.backoffice_legacy_flow` e não executa um grafo particular.
+Ele recebe `intent`, `route` e `mcp_tools` do roteador nativo e aciona as ferramentas pelo helper
+`AgentRuntimeMixin._call_mcp_tool()`.
+
+## Onde ficam as decisões
+
+| Decisão | Local correto |
+|---|---|
+| Roteamento/intents/tools | `config/routing.yaml` |
+| Contratos de tool | `config/tools.yaml` |
+| Mapeamento de parâmetros | `config/mcp_parameter_mapping.yaml` |
+| Isolamento de identidade | `config/identity.yaml` |
+| Prompt e regras de redação | `config/agents/backoffice_anatel/prompt_policy.yaml` |
+| Guardrails | `config/agents/backoffice_anatel/guardrails.yaml` |
+| Judges | `config/agents/backoffice_anatel/judges.yaml` |
+| Implementação de integração | `mcp_servers/backoffice_mcp_server/*` |
+
+## Diferença para a versão anterior
+
+Antes, o agente executava um fluxo recomposto chamado `BackofficeLegacyFlow`.
+Agora, o fluxo do agente é o fluxo padrão do framework:
+
+```text
+input_guardrails
+  -> routing_decision
+  -> backoffice_agent
+  -> output_supervisor
+  -> output_guardrails
+  -> judge
+  -> supervisor_review
+  -> persist
+```
+
+## Observação importante
+
+Regras de negócio que realmente não existem no framework ainda devem entrar como:
+
+1. configuração YAML;
+2. rail/guardrail plugável;
+3. judge plugável;
+4. tool MCP;
+5. serviço de domínio reutilizável do framework.
+
+Não devem entrar como grafo paralelo dentro do agente.