agent_contas/tests/docs/MANUAL_AGENT_CONTAS_MIGRADO.md

# Manual do Agent Contas Migrado para agent_framework_oci

## 1. Objetivo

Esta versão reconstrói o Agent Contas sobre o `agent_framework_oci` com uma regra arquitetural simples: **o código executável novo não depende do pacote anterior do Contas**. O projeto anterior é apenas referência funcional para preservar regras, contratos de API, fixtures e comportamentos de negócio durante a migração.

O agente novo reutiliza do framework tudo que é infraestrutura genérica: LangGraph, router, stickiness, supervisor, confirmação transacional, clarificação, memória, summary memory, long-term memory, checkpoints, persistence, RAG, embeddings, MCP Tool Router, guardrails, output supervisor, judges, identity, channels, SSE, usage accounting e telemetria.

O novo domínio Contas mantém somente o que é realmente específico da TIM: chamadas de faturas, VAS, contestação, protocolos, tracking, SMS, Secure PDF e regras que relacionam essas operações.

## 2. Regra de independência

A Definition of Done da migração é:

```bash
grep -R "agente_contas_tim" app mcp config
```

Resultado esperado: nenhuma ocorrência/import do pacote anterior.

O pacote entregue já inclui `tests/migration/test_no_legacy_dependency.py` para impedir regressão dessa regra.

## 3. Arquitetura

```text
Canal / Frontend
      |
      v
app/main.py
      |
      v
agent_framework_oci
  |-- ChannelGateway / IdentityResolver
  |-- LangGraph / AgentWorkflow
  |-- EnterpriseRouter / Route Stickiness / Supervisor
  |-- Guardrails / Output Supervisor / Judges
  |-- Memory / Summary Memory / LTM / Checkpoints
  |-- RAG / Embeddings / Cache
  |-- MCPToolRouter
  |-- Langfuse / Analytics / OTEL / OCI Streaming
      |
      v
MCP Contas :8400
      |
      v
app/domain/contas
  |-- TimApiClient
  |-- ContasDomainService
  `-- fixtures de desenvolvimento
      |
      v
APIs TIM
```

Não existe um segundo LangGraph, LLM gateway, confirmation manager, workflow engine ou memory store dentro do MCP.

## 4. Agentes de domínio

A versão migrada possui quatro agentes reais do domínio Contas:

| Agente | Responsabilidade |
|---|---|
| `faturas_agent` | Consulta de faturas, composição, variação e explicação de cobrança |
| `vas_agent` | Consulta de VAS, histórico, serviços estratégicos/bundles e informação de serviços |
| `contestacao_agent` | Cancelamento transacional de VAS e contestação de cobrança |
| `suporte_contas_agent` | Protocolos, acompanhamento, suporte e encerramento |

Todos herdam `AgentRuntimeMixin` do framework. Eles não implementam máquina de confirmação/clarificação própria.

## 5. LangGraph do framework

O fluxo principal é o `StateGraph` do `agent_framework_oci` usado em `app/workflows/agent_graph.py`:

```text
START
  -> input_guardrails
  -> load_long_term_memory
  -> routing_decision
  -> agente de domínio
  -> output_supervisor
  -> output_guardrails
  -> judge
  -> supervisor_review
  -> persist_long_term_memory
  -> persist
  -> END
```

O `EnterpriseRouter` decide a intent, agente e tools. O route stickiness decide continuidade da conversa. O runtime do framework controla coleta de parâmetros e confirmação de tools transacionais.

## 6. Transações

As tools abaixo são transacionais em `config/tool_policies.yaml`:

- `cancelar_vas_avulso`
- `tratar_vas_estrategico`
- `contestar_cobranca`

A confirmação ocorre **antes** da chamada MCP e é responsabilidade do `AgentRuntimeMixin`. O domínio recebe a chamada somente depois de a política do framework permitir execução.

Isso evita o problema clássico de um "sim" responder à pergunta errada: a confirmação está vinculada ao estado transacional/tool pendente do framework, não a heurísticas no prompt.

## 7. RAG

Conhecimento conceitual não é uma API TIM e por isso não é implementado como "workflow de busca" dentro do MCP.

O projeto usa diretamente:

- `RagService`
- `create_embedding_provider()`
- `VECTOR_STORE_PROVIDER`
- `GRAPH_STORE_PROVIDER`
- `EMBEDDING_PROVIDER`

`buscar_informacao` permanece desabilitada no catálogo MCP; perguntas de conhecimento passam pelo RAG nativo do framework.

## 8. Funcionalidades migradas

| Funcionalidade do Contas | Nova implementação | Responsabilidade do framework |
|---|---|---|
| Consulta de faturas | `ContasDomainService.consultar_faturas` | seleção da tool, identity, cache, resposta |
| Explicação de fatura | API de fatura + billing analysis como evidência | LLM produz explicação grounded |
| Consulta VAS | `consultar_vas` | routing/tool selection |
| Histórico VAS | `consultar_historico_vas` | routing/tool selection |
| Cancelamento VAS avulso | consulta -> match -> bloqueio -> cancelamento | parâmetros + confirmação + estado |
| VAS estratégico/bundle | domínio retorna serviço e orientação | conversa/continuidade no LangGraph |
| Contestação | faturas/contrato/profile -> protocolo -> contestação -> tracking | parâmetros + confirmação + estado |
| Status de solicitação | `consultar_status_solicitacao` | roteamento e contexto |
| SMS | `enviar_sms` | tool policy/contexto |
| Secure PDF | `recuperar_fatura_pdf` | roteamento/identity |
| Encerramento | efeitos de domínio opcionais | `end_session`, memória e telemetria |
| Guardrails | nenhum código local duplicado | framework |
| Judges | nenhum código local duplicado | framework |
| Memória | nenhum store local de conversa | framework |
| LTM | nenhum mecanismo local | framework |
| Checkpoint | nenhum `MemorySaver` dentro do MCP | framework |
| Telemetria | eventos do runtime/framework | framework |

## 9. Estrutura do projeto

```text
app/
  main.py
  state.py
  agents/
    faturas_agent.py
    vas_agent.py
    contestacao_agent.py
    suporte_contas_agent.py
  domain/contas/
    client.py
    service.py
    fixtures/
  workflows/
    agent_graph.py
  observability/

config/
  routing.yaml
  tools.yaml
  tool_policies.yaml
  mcp_servers.yaml
  mcp_parameter_mapping.yaml
  identity.yaml
  prompts/

contas_mcp/servers/contas_mcp_server/
  main.py

agent_framework_oci/
  ... framework reutilizado ...
```

## 10. Arquivo `.env`

O `.env` fornecido para esta reconstrução foi preservado byte a byte no pacote. Não foi recomposto nem reduzido.

O arquivo contém dois grupos:

1. configurações do `agent_framework_oci`;
2. variáveis TIM de domínio/compatibilidade já compiladas para os ambientes.

Embora algumas variáveis antigas possam deixar de ser usadas depois da migração, elas foram mantidas para não perder o trabalho de consolidação. A remoção deve ocorrer apenas após testes de DEV/FQA/PRD.

### Variáveis principais do framework

- `LLM_PROVIDER`
- `OCI_AUTH_MODE`, `OCI_CONFIG_FILE`, `OCI_PROFILE`, `OCI_COMPARTMENT_ID`, `OCI_REGION`
- `SESSION_REPOSITORY_PROVIDER`
- `MEMORY_REPOSITORY_PROVIDER`
- `CHECKPOINT_REPOSITORY_PROVIDER`
- `VECTOR_STORE_PROVIDER`
- `GRAPH_STORE_PROVIDER`
- `EMBEDDING_PROVIDER`
- `ENABLE_LANGFUSE`
- `ENABLE_INPUT_GUARDRAILS`
- `ENABLE_OUTPUT_GUARDRAILS`
- `ENABLE_JUDGES`
- `ENABLE_SUPERVISOR`
- `ENABLE_ROUTE_STICKINESS`
- `ENABLE_MCP_TOOLS`
- `ENABLE_CONVERSATION_SUMMARY_MEMORY`
- `ENABLE_LONG_TERM_MEMORY`

### Modo mock x APIs TIM reais

Mock atual:

```env
TIM_GATEWAY_MODE=mock
TIM_USE_MOCK_GATEWAY=true
```

Integrações reais:

```env
TIM_GATEWAY_MODE=real
TIM_USE_MOCK_GATEWAY=false
```

Os dois valores devem estar coerentes.

## 11. Integrações TIM

| Integração | Variável | Método | VPN TIM provável |
|---|---|---|---|
| Complete Invoices | `TIM_COMPLETE_INVOICES_URL` | POST | Sim em FQA interno |
| Billing Analysis | `TIM_DIVERGENCIA_URL` | POST | Sim |
| Consulta VAS | `TIM_URL_CONSULTA_VAS` | GET | Sim |
| Histórico VAS | `TIM_VAS_HISTORY_URL` | GET | Sim |
| Bloqueio VAS | `TIM_URL_BLOQUEIO_VAS` | POST | Sim |
| Cancelamento VAS | `TIM_CANCELAMENTO_URL` | DELETE | Sim |
| Contrato | `TIM_CONTRATO_URL` | GET | Sim |
| Full Profile | `TIM_PROFILE_FULL_URL` | GET | Sim |
| Contestação | `TIM_CUSTOMER_CONTESTATION_URL` | POST | Sim |
| Protocolo | `TIM_PROTOCOL_URL` | POST | Sim |
| Service Request Status | `TIM_SERVICE_REQUEST_STATUS_URL` | POST | Sim |
| Tracking Activities | `TIM_TRACKING_ACTIVITIES_URL` | POST | Sim |
| SMS | `TIM_SMS_URL` | POST | Sim |
| Secure PDF | `TIM_URL_INVOICE_RECOVER` | POST | Sim |

Os endpoints FQA do `.env` usam `pmidfqa.internal.timbrasil.com.br`; portanto DNS/rota corporativa precisa estar disponível para teste real.

## 12. Outras integrações

| Integração | Uso | Ativação |
|---|---|---|
| OCI GenAI | LLM | `LLM_PROVIDER=oci_sdk` + `OCI_AUTH_MODE` |
| Autonomous DB | session/memory/checkpoint/vector/usage | providers `autonomous` + `ADB_*` |
| OCI Embeddings | RAG | `EMBEDDING_PROVIDER=oci` |
| Langfuse | tracing | `ENABLE_LANGFUSE=true` |
| GCP Pub/Sub | analytics corporativo | `ENABLE_ANALYTICS=true`, provider Pub/Sub e credencial GCP |
| MongoDB | sequence Pub/Sub | `PUBSUB_SEQUENCE_PROVIDER=mongodb` |
| Redis | cache/sequence opcional | `ENABLE_REDIS_CACHE=true` ou provider sequence redis |
| OTEL | logs/traces | `ENABLE_OTEL=true` + endpoint |
| OCI Streaming | eventos alternativos | `ENABLE_OCI_STREAMING=true` |

## 13. Instalação local

Recomendado: Linux/WSL com Python 3.13.

```bash
cd contas_migrado_framework_native
uv sync
```

Se o `uv` ainda não estiver disponível, instale-o conforme o padrão do seu ambiente e depois execute `uv sync`.

## 14. Subir o MCP Contas

Terminal 1:

```bash
uv run uvicorn contas_mcp.servers.contas_mcp_server.main:app \
  --host 0.0.0.0 --port 8400
```

Validar:

```bash
curl http://localhost:8400/health
curl http://localhost:8400/mcp/tools/list
```

`/health` deve reportar:

```json
{
  "status": "ok",
  "architecture": "framework-native",
  "legacy_dependency": false
}
```

## 15. Subir o Agent Contas

Terminal 2:

```bash
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000
```

Validar:

```bash
curl http://localhost:8000/health
```

## 16. Smoke test do MCP em mock

```bash
PYTHONPATH=".:agent_framework_oci/libs/agent_framework/src" \
python scripts/smoke_mcp.py
```

Esse teste cobre faturas, invoice explanation, VAS, histórico, cancelamento e contestação usando fixtures migradas para o novo domínio.

## 17. Testar o agente pelo Gateway

Exemplo de consulta:

```bash
curl -X POST http://localhost:8000/gateway/message \
  -H 'Content-Type: application/json' \
  -d '{
    "channel":"web",
    "agent_id":"telecom_contas",
    "tenant_id":"default",
    "payload":{
      "text":"Quero consultar minha fatura",
      "session_id":"contas-test-001",
      "user_id":"user-001",
      "msisdn":"11999999999",
      "message_id":"msg-001"
    }
  }'
```

Depois teste continuidade na mesma `session_id`.

## 18. Teste transacional de VAS

1. Envie: `Quero cancelar TIM Fashion Mensal`.
2. O framework deve identificar tool transacional e pedir confirmação.
3. Responda `sim` na mesma sessão.
4. Somente então `cancelar_vas_avulso` deve ser chamada.
5. Em modo mock, o resultado deve conter `block.status=200` e `cancellation.status=200`.

Teste negativo importante:

1. Entre em estado aguardando confirmação de cancelamento.
2. Envie `você ainda está por aí?`.
3. A frase não pode confirmar a transação.

## 19. Teste de contestação

Em mock:

```text
Quero contestar Tamboro Mensal no valor de 14,99, não reconheço essa cobrança.
```

Esperado:

- route `contestacao_agent`;
- parâmetros `subject` e `valor` coletados;
- confirmação antes da mutação;
- abertura de protocolo;
- contestação;
- tracking;
- resposta final grounded nos retornos da tool.

## 20. Testes de memória

### Short-term / summary

Na mesma sessão:

```text
Meu serviço é TIM Fashion Mensal.
...
Qual serviço eu mencionei antes?
```

### Long-term memory

Com `ENABLE_LONG_TERM_MEMORY=true`, grave uma informação elegível, encerre a sessão e abra outra sessão com a mesma identidade de negócio. Verifique se o contexto é recuperado conforme as regras de LTM do framework.

## 21. Testes de RAG

Valide que a intent de conhecimento não dispara MCP desnecessariamente. Exemplos:

```text
O que significa cobrança proporcional?
Como funciona o vencimento da fatura?
```

O trace deve mostrar `RagService`; a tool `buscar_informacao` não precisa ser executada.

## 22. Testes de guardrails e judges

Com as flags habilitadas no `.env`:

- prompt injection deve passar pelos input guardrails;
- resposta candidata passa pelo Output Supervisor/output guardrails;
- groundedness deve considerar `mcp_results` quando a resposta usa dados TIM;
- judges rodam após a geração e antes da persistência final.

Use o Langfuse para observar a sequência de nodes do LangGraph.

## 23. Teste de conectividade/VPN

O pacote contém:

```bash
python scripts/check_integrations.py
```

O script resolve DNS e testa TCP dos endpoints configurados. Execute antes e depois de conectar a VPN.

Para APIs FQA, um resultado `DNS_FAIL`, `TCP_FAIL` ou timeout indica que a rede ainda não está pronta. Um `TCP_OK` prova conectividade de rede, mas não autenticação/contrato HTTP.

## 24. Ativar APIs reais gradualmente

Não habilite todas as mutações de uma vez. Ordem recomendada:

1. VPN/DNS;
2. `consultar_faturas`;
3. `consultar_vas`;
4. `consultar_historico_vas`;
5. contrato/profile;
6. billing analysis;
7. Secure PDF;
8. protocol/status/tracking;
9. SMS;
10. cancelamento VAS;
11. contestação.

Depois faça teste end-to-end completo.

## 25. Kubernetes

Use o mesmo `.env` como fonte para construir ConfigMap/Secret, separando segredos no mecanismo corporativo apropriado. O backend necessita alcançar:

- MCP Contas;
- OCI GenAI;
- Autonomous DB;
- Langfuse, se habilitado;
- endpoints TIM internos em modo real;
- providers de analytics habilitados.

O MCP pode rodar no mesmo pod como sidecar ou, preferencialmente, como deployment/service separado. Configure `config/mcp_servers.yaml` para o DNS do Service Kubernetes.

## 26. Critérios de aceite da migração

A migração é considerada concluída quando:

- [ ] zero imports/referências executáveis ao pacote anterior;
- [ ] backend e MCP sobem após o diretório anterior ser removido;
- [ ] read-only APIs funcionam em FQA;
- [ ] cancelamento exige confirmação do framework e funciona em FQA;
- [ ] contestação exige confirmação e reproduz efeitos esperados;
- [ ] RAG usa `RagService` do framework;
- [ ] memory/summary/LTM/checkpoint usam providers do framework;
- [ ] guardrails e judges aparecem nos traces;
- [ ] LangGraph é a única máquina de estados conversacional;
- [ ] Pub/Sub/sequence/OTEL/Langfuse são validados conforme ambiente;
- [ ] testes de carga são executados antes de produção.

## 27. Segurança do `.env`

O arquivo preservado contém material sensível. Ele foi mantido porque isso foi um requisito explícito da reconstrução. Para distribuição fora do ambiente controlado, rotacione credenciais expostas e substitua valores por Secrets/Vault/Key Vault/Kubernetes Secret conforme política corporativa.