compass_backoffice/README_MIGRACAO_BACKOFFICE.md

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:

workspace/
  agent_framework/
  backoffice_convertido_framework/

Instale dependências:

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:

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Teste:

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:

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:

GET  /health
GET  /tools/list
POST /tools/call

Ferramentas migradas inicialmente:

consultar_reclamacao
consultar_cliente_backoffice
registrar_acao_backoffice

Rodar API e MCP separados

Terminal 1:

./scripts/run_backoffice_mcp.sh

Terminal 2:

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Testar MCP diretamente

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

docker compose up --build

O compose sobe dois serviços:

backoffice-api  -> porta 8000
backoffice-mcp  -> porta 8010

A API aponta para o MCP usando:

BACKOFFICE_MCP_BASE_URL=http://backoffice-mcp:8010

Onde colocar serviços reais

Hoje o MCP usa dados simulados em:

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:

config/tools.yaml
config/mcp_parameter_mapping.yaml