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`:

```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
```