cristiano.hoshikawa/agent_contas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Projeto do Agent Contas ORACLE

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-08-19 09:35:50 -03:00
commit 950a2bcd33
1366 changed files with 177217 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

472
docs/MANUAL_AGENT_CONTAS_MIGRADO.md Normal file
View File

@@ -0,0 +1,472 @@
# 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.