first commit

README_MIGRACAO_BACKOFFICE.md

@@ -0,0 +1,184 @@
+# Backoffice convertido para o seu Agent Framework
+
+Esta pasta é uma versão convertida do desenho do `tim-ai-atend-agnt-backoffice` para usar o framework local `agent_framework`.
+
+## O que foi convertido
+
+O backoffice original foi tratado como uma aplicação FastAPI + LangGraph + nodes + checkpoint MongoDB. A conversão substitui o acoplamento com a dependência corporativa externa `agent-framework` por imports do seu framework local.
+
+### Mapeamento arquitetural
+
+| Backoffice original | Versão convertida |
+|---|---|
+| `src/api/main.py` | `app/main.py` |
+| `src/api/routes/agent.py` | `/gateway/message`, `/gateway/message/sse`, `/gateway/events/{session_id}` em `app/main.py` |
+| `src/agent/graphs/main_graph.py` | `app/workflows/agent_graph.py` |
+| `src/agent/state/agent_state.py` | `app/state.py` |
+| `src/agent/nodes/router_node.py` | `EnterpriseRouter` via `config/routing.yaml` |
+| `src/agent/nodes/llm_node.py` | `BackofficeAgent` + `create_llm(settings)` |
+| `src/agent/nodes/tool_node.py` | `MCPToolRouter` + `config/tools.yaml` |
+| `src/components/checkpointing/mongodb_saver.py` | `agent_framework.checkpoints` / `create_langgraph_checkpointer` |
+| `configs/config.example.yaml` | `.env` + `config/*.yaml` |
+
+## Arquivos principais adicionados
+
+- `app/agents/backoffice_agent.py`
+- `config/agents.yaml`
+- `config/routing.yaml`
+- `config/tools.yaml`
+- `config/mcp_servers.yaml`
+- `config/mcp_parameter_mapping.yaml`
+- `config/identity.yaml`
+- `config/agents/backoffice_anatel/*`
+
+## Execução local
+
+Coloque esta pasta ao lado do projeto `agent_framework`:
+
+```text
+workspace/
+  agent_framework/
+  backoffice_convertido_framework/
+```
+
+Instale dependências:
+
+```bash
+cd backoffice_convertido_framework
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e ../agent_framework
+```
+
+Suba a aplicação:
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Teste:
+
+```bash
+curl -s -X POST http://localhost:8000/gateway/message \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channel":"web",
+    "agent_id":"backoffice_anatel",
+    "tenant_id":"default",
+    "payload":{
+      "text":"Preciso analisar uma reclamação da ANATEL do protocolo 12345",
+      "session_id":"teste-bko-001",
+      "protocol_id":"12345",
+      "customer_key":"11999999999"
+    }
+  }' | jq
+```
+
+## Pontos que ainda exigem o ZIP real do backoffice
+
+Esta conversão preserva a arquitetura e cria um backend funcional no seu padrão, mas não migra regras de negócio específicas que não estavam disponíveis no ambiente atual. Quando o ZIP real do backoffice for anexado, os seguintes itens devem ser migrados arquivo por arquivo:
+
+1. Tools reais de `src/components/tools/*` para `config/tools.yaml` e/ou adaptadores MCP.
+2. Regras específicas dos nodes antigos para `BackofficeAgent` ou agentes especializados.
+3. Schemas reais da API para compatibilidade retroativa.
+4. Checkpoint MongoDB customizado, se houver semântica diferente do saver do framework.
+5. Testes unitários e integração do backoffice original.
+
+## Decisão de design
+
+A migração usa um único agente `backoffice_agent`, porque a análise estrutural indicava que o backoffice era mais um runtime/boilerplate de agente do que um domínio funcional completo. Caso o ZIP real mostre subdomínios claros, o próximo passo é quebrar em agentes especializados:
+
+- `anatel_triage_agent`
+- `customer_lookup_agent`
+- `case_resolution_agent`
+- `action_register_agent`
+
+## Complemento: MCP do backoffice migrado
+
+A versão atual inclui também um servidor MCP/HTTP próprio do backoffice em:
+
+```text
+mcp_servers/backoffice_mcp_server/
+```
+
+Esse servidor substitui a lógica que antes ficaria em `src/components/tools/*` no backoffice original. Ele expõe o contrato consumido pelo `MCPToolRouter` do framework:
+
+```text
+GET  /health
+GET  /tools/list
+POST /tools/call
+```
+
+Ferramentas migradas inicialmente:
+
+```text
+consultar_reclamacao
+consultar_cliente_backoffice
+registrar_acao_backoffice
+```
+
+### Rodar API e MCP separados
+
+Terminal 1:
+
+```bash
+./scripts/run_backoffice_mcp.sh
+```
+
+Terminal 2:
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+### Testar MCP diretamente
+
+```bash
+curl -s http://localhost:8010/tools/list | jq
+
+curl -s -X POST http://localhost:8010/tools/call \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "consultar_reclamacao",
+    "arguments": {
+      "protocol_id": "12345",
+      "customer_key": "11999999999",
+      "interaction_key": "12345"
+    }
+  }' | jq
+```
+
+### Rodar com Docker Compose
+
+```bash
+docker compose up --build
+```
+
+O compose sobe dois serviços:
+
+```text
+backoffice-api  -> porta 8000
+backoffice-mcp  -> porta 8010
+```
+
+A API aponta para o MCP usando:
+
+```text
+BACKOFFICE_MCP_BASE_URL=http://backoffice-mcp:8010
+```
+
+### Onde colocar serviços reais
+
+Hoje o MCP usa dados simulados em:
+
+```text
+mcp_servers/backoffice_mcp_server/store.py
+```
+
+Para plugar sistemas reais, substitua as funções desse arquivo por chamadas para APIs, bancos, filas ou SDKs internos. Mantenha o contrato das ferramentas para não quebrar:
+
+```text
+config/tools.yaml
+config/mcp_parameter_mapping.yaml
+```