compass_backoffice/README_BACKOFFICE_CONVERTIDO_100.md

Backoffice TIM/ANATEL convertido para o Agent Framework — versão 100% de paridade

Esta versão foi gerada a partir de dois insumos:

• tim-ai-atend-agnt-backoffice(3).zip: branch develop do backoffice original.
• backoffice_convertido_framework(2).zip: primeira versão convertida para o framework.

O que mudou

A versão anterior tinha uma implementação genérica de BackofficeAgent com MCP tools e endpoints de compatibilidade simplificados. Esta versão preserva os fluxos reais da branch develop como workflows de domínio dentro da aplicação do framework.

Camadas mantidas pelo framework

O framework continua responsável por:

• /gateway/message e /gateway/events/{session_id}.
• Normalização de canais.
• AgentIdentity e BusinessContext.
• Sessão, memória, checkpoint e uso.
• EnterpriseRouter e modo supervisor.
• Guardrails de entrada e saída.
• OutputSupervisor.
• Judges.
• Telemetria, IC, NOC e GRL.
• MCP Tool Router.

Fluxos originais preservados

O pacote src/ foi copiado da branch develop e preserva os grafos originais:

Checklist ANATEL

Arquivo: src/agent/graphs/main_graph.py

Fluxo preservado:

fetch_ticket
 -> validation
 -> bypass_rules
 -> cache_check
 -> imdb_enrichment
 -> identity_verification
 -> speech_enrichment
 -> knowledge_base_enrichment
 -> canceling_analysis
 -> tim_complaint_analysis
 -> tim_complaint / different_complaint_operator / undefined_complaint_operator
 -> reclassification_analysis
 -> treatment_decision
 -> siebel_sr_opening

Response Emulator

Arquivo: src/agent/graphs/emulator_graph.py

Fluxo preservado:

start_response_emulation
 -> fetch_case
 -> validate_actions
 -> router
 -> retrieve_templates
 -> retrieve_history
 -> generate_response
 -> validate_response
 -> persist_draft
 -> approve_draft / close_case

Rotas preservadas do backoffice original

Registradas em app/main.py:

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

Serviços TIM preservados

Os clients originais foram preservados em src/components/clients/:

imdb_client.py
siebel_client.py
speech_analytics_client.py
tais_kb_client.py
abrt_client.py
portability_client.py
emulator_rag_client.py
rag/history_rag_client.py
rag/templates_rag_client.py

Prompts preservados

Os prompts originais foram preservados em src/agent/local_prompts/:

canceling_analysis.py
duplicate_analysis.py
tim_complaint_analysis.py
ticket_reclassification.py
treatment_decision_prompt.py
speech_history_analysis.py
preprocess_tais_kb_query.py
postprocess_tais_kb_query.py
emulator/response_emulator_generation.py
anatel_motives/anatel_motives.py

Guardrails e judges

A configuração do agente backoffice foi reforçada em:

config/agents/backoffice_anatel/guardrails.yaml
config/agents/backoffice_anatel/judges.yaml
config/agents/backoffice_anatel/prompt_policy.yaml

A lógica de domínio original continua fazendo validações operacionais por nó, e o framework envolve a execução com guardrails, OutputSupervisor e judges.

Como subir localmente

cp .env.example .env
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Como validar rapidamente

curl http://localhost:8000/health
curl http://localhost:8000/debug/backoffice/parity
curl http://localhost:8000/health/live
curl http://localhost:8000/health/ready

Observação importante

O arquivo .env real foi removido do pacote gerado. Configure credenciais reais somente localmente ou via secret manager. Não versionar chaves OCI, Autonomous Database, Langfuse, Siebel, IMDB, Speech Analytics ou qualquer segredo TIM.