O compass_backoffice é um backend de agente para atendimento operacional de Backoffice/ANATEL, migrado para utilizar o agent_framework_oci como motor principal de execução.

Ele foi construído para receber solicitações de backoffice, reclamações ANATEL, protocolos, casos de cliente e demandas operacionais, acionar ferramentas externas por MCP, consultar contexto via RAG, aplicar guardrails, registrar observabilidade IC/NOC/GRL e produzir uma resposta controlada pelo workflow corporativo do framework.

Em termos práticos, o projeto permite testar um agente de backoffice com:

entrada conversacional via /gateway/message;
entrada REST compatível com o contrato legado via /agent/process-and-stream e rotas relacionadas;
roteamento por intents configuradas em YAML;
execução de ferramentas pelo MCPToolRouter do framework;
isolamento por tenant_id, agent_id, session_id e BusinessContext;
RAG, memória, checkpoints, cache, telemetria, guardrails, judges e output supervisor do agent_framework_oci.

2. Finalidade da aplicação

O agente foi criado para apoiar fluxos como:

triagem de reclamações ANATEL;
consulta de protocolo, chamado, cliente, contrato, linha, CPF/CNPJ e contexto operacional;
enriquecimento de caso usando IMDB/PMID, Siebel, Speech Analytics, TAIS KB, ABRT e Portabilidade;
geração de rascunho ou resposta para emulador ANATEL;
registro controlado de ação operacional, parecer, conclusão, encaminhamento ou atualização de demanda;
validação de segurança, conformidade, precisão e aderência ao domínio antes da resposta final.

O objetivo da migração é evitar que o agente tenha um grafo paralelo ou regras “quebra-galho”. A aplicação deve delegar ao framework tudo que o framework já oferece: workflow, roteamento, identidade, MCP, RAG, guardrails, judges, observabilidade, memória, checkpoint e cache.

3. Arquitetura resumida

Fluxo principal do agente conversacional:

HTTP /gateway/message ou /gateway/message/sse
  -> ChannelGateway
  -> IdentityResolver + BusinessContext
  -> SessionRepository / Memory / Checkpoint
  -> AgentWorkflow LangGraph
      -> input_guardrails
      -> routing_decision
      -> backoffice_agent
      -> output_supervisor
      -> output_guardrails
      -> judge
      -> supervisor_review
      -> persist
  -> ChannelResponse

Fluxo REST legado adaptado ao framework:

HTTP /agent/process-and-stream
  -> BackofficeRestChannelAdapter
  -> BackofficeWorkflowDispatcher
  -> BackofficeWorkflowExecutor
  -> etapas framework-native de guardrails, output supervisor, judges, telemetry e persistência

Fluxo de ferramentas:

BackofficeAgent
  -> MCPToolRouter do agent_framework_oci
  -> config/tools.yaml
  -> config/mcp_parameter_mapping.yaml
  -> config/mcp_servers.yaml
  -> Backoffice MCP Server HTTP na porta 8010
  -> backend mock, REST, Oracle ou clientes TIM

4. Componentes principais do projeto

app/main.py

API FastAPI principal. Inicializa LLM, memória, summary memory, sessão, checkpoint, cache, ChannelGateway, analytics, observer, MCPToolRouter, IdentityResolver, AgentWorkflow, executor REST e rotas de debug/teste.

app/workflows/agent_graph.py

Workflow LangGraph principal. Usa componentes do framework para guardrails, roteamento, supervisor, output supervisor, judges, RAG, telemetria profunda de LangGraph e persistência.

app/agents/backoffice_agent.py

Agente de domínio Backoffice/ANATEL. Ele não deve recriar capacidades do framework. Recebe intent, route, mcp_tools e contexto do workflow; consulta RAG; aciona ferramentas MCP; emite IC/NOC/GRL; gera a resposta final.

app/workflows/backoffice_workflow_executor.py
app/workflows/backoffice_workflow_dispatcher.py
app/channels/backoffice_rest_adapter.py

Camada de compatibilidade para contratos REST de backoffice. Preserva endpoints antigos, mas executa o fluxo dentro do runtime do framework.

config/agents.yaml

Registra o agente backoffice_anatel, define o agent default e aponta configs específicas de prompt, guardrails, judges, MCP e tools.

config/routing.yaml

Define intents, palavras-chave, exemplos, tools por intent e state policies. O roteamento ativo padrão é router, com fallback para backoffice_agent.

config/agents/backoffice_anatel/guardrails.yaml

Configuração de guardrails específica do agente. Ativa rails de entrada e saída como INPUT_SIZE, MSK, PINJ, TOX, DLEX_IN, RAGSEC, VLOOP, REVPREC, DLEX_OUT, OOS, CMP e AOFERTA.

config/agents/backoffice_anatel/judges.yaml

Configuração de judges pós-resposta para avaliação de qualidade, precisão e aderência.

config/tools.yaml

Contrato das ferramentas disponíveis para o agente. Exemplos: consultar_reclamacao, consultar_cliente_backoffice, consultar_siebel_caso, consultar_imdb_cliente, consultar_speech_analytics, consultar_tais_kb, consultar_abrt, consultar_portabilidade, registrar_acao_backoffice e ferramentas do emulador.

config/mcp_parameter_mapping.yaml

Mapeia BusinessContext canônico para argumentos das tools MCP. Exemplo: interaction_key -> protocol_id, customer_key -> customer_key, contract_key -> contract_key, session_key -> operator_session.

mcp_servers/backoffice_mcp_server/

Servidor MCP HTTP compatível com o MCPToolRouter do framework. Expõe /health, /tools/list e /tools/call.

5. O que o projeto utiliza do `agent_framework_oci`

O compass_backoffice utiliza as seguintes capacidades do framework:

Capacidade do framework	Uso no projeto
LangGraph / workflow corporativo	`app/workflows/agent_graph.py`
ChannelGateway	Normalização/renderização de mensagens por canal
IdentityResolver	Resolução de identidade técnica e `BusinessContext`
BusinessContext	Chaves canônicas para MCP e sessão
AgentProfileRegistry	Carregamento de `config/agents.yaml`
EnterpriseRouter	Roteamento por intents em `config/routing.yaml`
Supervisor	Modo alternativo quando `ROUTING_MODE=supervisor`
GuardrailPipeline	Guardrails de entrada e saída
OutputSupervisor	Revisão/retry/sanitize/block de resposta
JudgePipeline	Avaliação pós-resposta
MCPToolRouter	Chamada de tools via servidor MCP HTTP
RagService	Consulta RAG nativa do framework
Cache	Cache criado por `create_cache(settings)`
Memory	Histórico conversacional
ConversationSummaryMemory	Resumo de conversa
SessionRepository	Sessões persistentes
CheckpointRepository	Checkpoints por sessão
Telemetry / Langfuse	Spans, eventos, usage e debug
AgentObserver / Analytics	Emissão de IC, NOC e GRL
SSEHub	Eventos SSE por sessão

6. Pré-requisitos

6.1 Python

O pyproject.toml declara:

requires-python = >=3.11

Recomendação prática:

Python 3.11 ou 3.12

O Dockerfile usa python:3.12-slim.

6.2 Dependências Python

O projeto possui requirements.txt com dependências como:

fastapi
uvicorn[standard]
pydantic
pydantic-settings
python-dotenv
langgraph
langchain-core
openai
oci
oracledb
pymongo
redis
PyYAML
langfuse
httpx
opentelemetry-*
pytest
pytest-asyncio
motor
aiokafka
google-auth
requests
tenacity
python-json-logger

6.3 `agent_framework_oci`

O backend depende do pacote agent_framework_oci, importado como agent_framework.

Existem duas formas comuns de disponibilizar o framework:

Opção A — instalação editável local

Estrutura sugerida:

workspace/
  agent_framework_oci/
  compass_backoffice/

Instalação:

cd workspace/compass_backoffice
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e ../agent_framework_oci
pip install -r requirements.txt

Se o diretório do framework tiver outro nome, ajuste o caminho do pip install -e.

Opção B — Docker

O Dockerfile espera copiar o framework para /agent_framework. Em builds Docker, garanta que o contexto inclua o diretório do framework conforme esperado pelo arquivo.

6.4 Serviços opcionais

Para testes locais mínimos, é possível usar SQLite e MCP mock.

Para execução integrada, podem ser necessários:

Redis, se o cache estiver configurado para Redis;
MongoDB, se algum repositório estiver configurado para Mongo;
Oracle Autonomous DB, se memória/checkpoint/RAG/TAIS real forem usados;
Langfuse, se telemetria estiver habilitada;
credenciais OCI Generative AI;
credenciais TIM/Siebel/PMID/Speech/TAIS, se o MCP estiver em modo real.

7. Configuração local

Crie o .env principal:

cp .env.example .env

Principais variáveis para teste local:

APP_ENV=local
LOG_LEVEL=INFO
CORS_ORIGINS=*

DEFAULT_AGENT_ID=backoffice_anatel
ROUTING_MODE=router
ENABLE_SSE=true
ENABLE_PARALLEL_GUARDRAILS=true
GUARDRAILS_FAIL_FAST=true

SESSION_REPOSITORY_PROVIDER=sqlite
MEMORY_REPOSITORY_PROVIDER=sqlite
CHECKPOINT_REPOSITORY_PROVIDER=sqlite
USAGE_REPOSITORY_PROVIDER=sqlite
SQLITE_DB_PATH=.local/backoffice_framework.db

LLM_PROVIDER=oci_openai
LLM_MODEL=cohere.command-r-08-2024

MCP_ENABLED=true
MCP_SERVERS_CONFIG_PATH=config/mcp_servers.yaml
MCP_PARAMETER_MAPPING_PATH=config/mcp_parameter_mapping.yaml
BACKOFFICE_MCP_BASE_URL=http://localhost:8010

Para rodar com LLM real, preencha também as variáveis do provider OCI/OpenAI-compatible exigidas pelo seu agent_framework_oci, por exemplo endpoint, chave, profile, região e compartment.

Para testes sem integrações reais de backoffice, configure o MCP em modo mock.

8. Como subir o Legacy Backoffice MCP Server

Crie o arquivo de ambiente do MCP:

cp .env.backoffice_mcp.example .env.backoffice_mcp

Para teste local com dados simulados:

BACKOFFICE_MCP_HOST=0.0.0.0
BACKOFFICE_MCP_PORT=8010
BACKOFFICE_MCP_USE_MOCK=true
BACKOFFICE_MCP_BACKEND_TYPE=mock

Suba o servidor MCP:

source .venv/bin/activate
./scripts/run_backoffice_mcp.sh

Teste o health:

curl http://localhost:8010/health

Liste as tools:

curl http://localhost:8010/tools/list

Chamada direta de tool:

curl --location 'http://localhost:8010/tools/call' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "consultar_reclamacao",
    "arguments": {
      "protocol_id": "202603279001551",
      "customer_key": "06252533106"
    }
  }'

Modos de backend do MCP

O MCP server suporta os modos abaixo:

Modo	Uso
`mock`	Teste local com dados simulados em memória
`rest`	Chamada para backend REST configurado por `BACKOFFICE_MCP_REST_BASE_URL`
`oracle`	Placeholder para integração Oracle real
`tim_clients`	Uso de clientes TIM/develop configurados no `.env`

Para usar integrações reais, desative mock e preencha as credenciais correspondentes:

BACKOFFICE_MCP_USE_MOCK=false
BACKOFFICE_MCP_BACKEND_TYPE=tim_clients
BACKOFFICE_MCP_FAIL_OPEN_ON_BACKEND_ERROR=true

9. Como subir a aplicação principal

Em outro terminal:

cd compass_backoffice
source .venv/bin/activate
mkdir -p .local
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Teste o health:

curl http://localhost:8000/health

Endpoints úteis de diagnóstico:

curl http://localhost:8000/agents
curl http://localhost:8000/debug/env
curl http://localhost:8000/debug/mcp/tools
curl http://localhost:8000/test-llm

Teste de identidade:

curl --location 'http://localhost:8000/debug/identity' \
  --header 'Content-Type: application/json' \
  --data '{
    "channel": "web",
    "agent_id": "backoffice_anatel",
    "tenant_id": "default",
    "payload": {
      "message": "Consultar protocolo 202603279001551 do CPF 06252533106",
      "session_id": "teste-readme-001",
      "user_id": "operador"
    }
  }'

Teste de roteamento:

curl --location 'http://localhost:8000/debug/route' \
  --header 'Content-Type: application/json' \
  --data '{
    "channel": "web",
    "agent_id": "backoffice_anatel",
    "tenant_id": "default",
    "payload": {
      "message": "Preciso analisar uma reclamação da ANATEL do protocolo 202603279001551",
      "session_id": "teste-readme-001",
      "user_id": "operador"
    }
  }'

10. Teste conversacional pelo gateway do framework

curl --location 'http://localhost:8000/gateway/message' \
  --header 'Content-Type: application/json' \
  --data '{
    "channel": "web",
    "agent_id": "backoffice_anatel",
    "tenant_id": "default",
    "payload": {
      "message": "Preciso analisar a reclamação ANATEL protocolo 202603279001551 do CPF 06252533106. A TIM está ligando cobrando planos que o cliente diz não ter assinado.",
      "session_id": "teste-backoffice-001",
      "user_id": "operador-bko",
      "business_context": {
        "customer_key": "06252533106",
        "interaction_key": "202603279001551",
        "session_key": "teste-backoffice-001"
      }
    }
  }'

Resposta esperada em alto nível:

text com resposta do agente;
metadata.agent_id = backoffice_anatel;
metadata.route e/ou metadata.intent;
metadata.business_context resolvido;
metadata.mcp_results, quando tools forem acionadas;
metadata.guardrails e metadata.judges, quando habilitados/retornados pelo pipeline.

11. Teste com SSE

Primeiro envie uma mensagem com SSE habilitado:

curl --location 'http://localhost:8000/gateway/message/sse' \
  --header 'Content-Type: application/json' \
  --data '{
    "channel": "web",
    "agent_id": "backoffice_anatel",
    "tenant_id": "default",
    "payload": {
      "message": "Consultar protocolo ANATEL 202603279001551",
      "session_id": "teste-sse-001",
      "user_id": "operador-bko",
      "business_context": {
        "interaction_key": "202603279001551",
        "customer_key": "06252533106"
      }
    }
  }'

Depois acompanhe os eventos usando o conversation_key retornado na resposta. Em geral, o formato é:

tenant_id:agent_id:session_id

Exemplo:

curl -N 'http://localhost:8000/gateway/events/default:backoffice_anatel:teste-sse-001'

Eventos esperados:

flow.start
session.upserted
message.received
workflow.started
workflow.completed
message.responded
flow.end

12. Teste com o curl anexado

O arquivo anexado curl_test.txt usa a rota:

POST /agent/process-and-stream

Esse endpoint preserva o contrato REST do backoffice e passa pelo adapter framework-native.

Com a aplicação na porta 8000, execute o conteúdo do arquivo:

bash curl_test.txt

Ou copie o curl abaixo:

curl --location 'http://localhost:8000/agent/process-and-stream' \
--header 'Content-Type: application/json' \
--data-raw '{
    "caseType": "anatel",
    "origin": {
        "sourceSystem": "turbina_odc",
        "submittedBy": {
            "userId": "f8052701",
            "name": "Nicolas Silva",
            "email": null
        }
    },
    "crmProtocol": "DS-987654321",
    "ticketId": "ert",
    "customer": {
        "cpfCnpj": "06252533106",
        "phones": ["62981152324"],
        "msisdn": "62981152324",
        "name": "Nicolas Ferreira da Silva",
        "email": "nicolas.silva@exemplo.com.br",
        "govBrSeal": null,
        "odcCustomer": false,
        "contumazCustomer": false,
        "address": {
            "cep": "01001-000",
            "street": "Praca da Se",
            "neighborhood": "Se",
            "city": "Sao Paulo",
            "state": "SP"
        },
        "subscriber": {
            "cpfCnpj": "06252533106",
            "subscriberName": "Assinante Exemplo",
            "contactPhone": "62981152324",
            "contactName": "Nicolas Ferreira da Silva"
        }
    },
    "complaint": {
        "complaintProtocol": "202603279001551",
        "actionType": "nova",
        "providerProtocol": null,
        "inputChannel": "Anatel",
        "service": "Celular Pós-pago",
        "firstService": "Celular Pós-pago",
        "modality": "Cobrança",
        "motive": "Operadora liga ou envia mensagens indevidas de cobrança",
        "description": "A TIM está me ligando cobrando planos que eu não assinei. Quero que parem",
        "openedAt": "2026-03-27T11:45:00-03:00",
        "dueAt": null
    }
}'

13. Teste de MCP via backend principal

O backend principal também permite chamar tools usando o router do framework:

curl --location 'http://localhost:8000/debug/mcp/call/consultar_reclamacao' \
  --header 'Content-Type: application/json' \
  --data '{
    "business_context": {
      "interaction_key": "202603279001551",
      "customer_key": "06252533106",
      "session_key": "teste-mcp-001"
    }
  }'

Esse teste é importante porque valida o caminho correto:

FastAPI principal -> MCPToolRouter -> mcp_parameter_mapping.yaml -> Backoffice MCP Server

Não é recomendado chamar clientes TIM/Siebel diretamente dentro do agente. O caminho correto é via MCP.

14. Como subir com Docker Compose

O projeto inclui docker-compose.yml com dois serviços:

backoffice-api, porta 8000;
backoffice-mcp, porta 8010.

Execute:

cp .env.example .env
cp .env.backoffice_mcp.example .env.backoffice_mcp

docker compose up --build

Teste:

curl http://localhost:8000/health
curl http://localhost:8010/health

Observação: confira o Dockerfile e o contexto de build. Ele espera que o framework esteja disponível no contexto como agent_framework e a aplicação como agent_template_backend. Se a pasta local tiver outro nome, ajuste o Dockerfile ou o contexto antes do build.

15. Guardrails, judges e output supervisor

O agente usa duas camadas de configuração:

config/guardrails.yaml
config/agents/backoffice_anatel/guardrails.yaml

A configuração específica do agente é a mais importante para o backoffice_anatel.

Guardrails de entrada configurados:

INPUT_SIZE
MSK
PINJ
TOX
DLEX_IN
RAGSEC
VLOOP

Guardrails de saída configurados:

REVPREC
DLEX_OUT
OOS
CMP
AOFERTA

O workflow também usa:

OutputSupervisor, para revisão, retry, sanitização ou bloqueio;
JudgePipeline, para avaliação pós-resposta;
supervisor_review, para revisão final do fluxo.

16. IC, NOC e GRL

A emissão de observabilidade passa por:

AgentObserver
create_analytics_publisher(settings)
src.compat.framework_observer.configure(...)

No agente de backoffice, os eventos principais aparecem em app/agents/backoffice_agent.py.

Exemplos de ICs usados no agente:

AGA.001: entrada recebida pelo agente nativo;
AGA.018: contexto canônico validado;
AGA.012: RAG/TAIS KB consultado;
AGA.014: ferramentas MCP selecionadas;
AGA.008: registro operacional ignorado por ausência de action_text;
AGA.010: Speech Analytics consultado;
AGA.011: cliente/IMDB consultado;
AGA.020: templates/TAIS consultados;
AGA.006: ação operacional solicitada;
AGA.043: resposta produzida.

Exemplo de NOC:

NOC.001: conclusão do agente nativo de backoffice.

Os GRLs são esperados principalmente nas etapas de guardrails/output supervisor/judges do framework e nos pontos de observabilidade plugados pelo AgentObserver.

17. RAG

O workflow inicializa:

create_embedding_provider(settings)
RagService(settings, telemetry=telemetry)

O agente usa RAG para enriquecer a resposta quando configurado. O namespace de referência do agente aparece em config/agents.yaml:

metadata:
  rag_namespace: backoffice_anatel

Para uso real do RAG, configure no .env os providers e stores exigidos pelo agent_framework_oci, como embeddings OCI, vector store e credenciais de banco quando aplicável.

18. Rotas disponíveis

Framework/gateway

GET  /health
GET  /agents
GET  /debug/env
GET  /test-llm
POST /debug/route
POST /debug/identity
GET  /debug/usage
GET  /debug/mcp/tools
POST /debug/mcp/call/{tool_name}
POST /gateway/message
POST /gateway/message/sse
GET  /gateway/events/{session_id}
GET  /sessions/{session_id}/messages
GET  /sessions/{session_id}/checkpoint

Contratos REST de backoffice preservados

POST /agent/process-ticket
POST /agent/execute
POST /agent/process-and-stream
POST /agent/search-tais-kb
POST /case/{transaction_id}/response-emulator/generate
POST /case/{transaction_id}/response-emulator/finalize
GET  /case/{transaction_id}/response-emulator
POST /emulator-rag/search
GET  /health/live
GET  /health/ready
GET  /debug/backoffice/parity

MCP server

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

19. Validação estrutural

Antes de executar testes funcionais, valide sintaxe e imports básicos:

python -m compileall -q app src tools mcp_servers
python tools/validate_parity.py

20. Troubleshooting

`ModuleNotFoundError: agent_framework`

Instale o framework em modo editável:

pip install -e ../agent_framework_oci

Ou ajuste o PYTHONPATH temporariamente:

export PYTHONPATH="../agent_framework_oci:$PYTHONPATH"

`/debug/mcp/tools` sem tools

Verifique:

MCP_ENABLED=true
MCP_SERVERS_CONFIG_PATH=config/mcp_servers.yaml
MCP_PARAMETER_MAPPING_PATH=config/mcp_parameter_mapping.yaml

E confirme se o MCP está ativo:

curl http://localhost:8010/health

MCP retorna erro de conexão

Confirme se config/mcp_servers.yaml aponta para:

endpoint: http://localhost:8010

No Docker, o endpoint deve ser o nome do serviço:

endpoint: http://backoffice-mcp:8010

LLM não responde

Teste:

curl http://localhost:8000/test-llm

Se falhar, revise as variáveis do provider OCI/OpenAI-compatible.

SQLite não cria banco

Crie a pasta local:

mkdir -p .local

Endpoint legado funciona, mas gateway não aciona tools

Teste o roteamento:

curl http://localhost:8000/debug/mcp/tools

Depois teste /debug/route e confirme se a intent retorna mcp_tools.

21. Sequência recomendada de teste local

# Terminal 1
cd compass_backoffice
source .venv/bin/activate
cp .env.backoffice_mcp.example .env.backoffice_mcp
./scripts/run_backoffice_mcp.sh

# Terminal 2
cd compass_backoffice
source .venv/bin/activate
cp .env.example .env
mkdir -p .local
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Terminal 3
cd compass_backoffice
source .venv/bin/activate
cd legacy_backend
uvicorn mock_imdb_server:app --port 8011

# Terminal 4
curl http://localhost:8010/health
curl http://localhost:8000/health
curl http://localhost:8000/debug/mcp/tools
bash curl_test.txt

22. Diretriz de evolução

Ao evoluir o compass_backoffice, mantenha a regra arquitetural:

identidade e chaves de negócio: IdentityResolver e BusinessContext;
roteamento: config/routing.yaml e EnterpriseRouter;
ferramentas externas: MCPToolRouter + MCP server;
conhecimento: RagService do framework;
segurança e conformidade: guardrails, output supervisor e judges do framework;
observabilidade: AgentObserver, IC, NOC, GRL, Langfuse e telemetry;
persistência: memória, sessão e checkpoint do framework.

Só implemente código de domínio fora do framework quando a capacidade realmente não existir no agent_framework_oci.

README.md

compass_backoffice — Manual de execução e testes

1. O que é o compass_backoffice