Files

cristiano.hoshikawa 950a2bcd33 Projeto do Agent Contas ORACLE

2026-08-19 09:35:50 -03:00

15 KiB

Raw Blame History

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

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

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:

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

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:

configurações do agent_framework_oci;
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:

TIM_GATEWAY_MODE=mock
TIM_USE_MOCK_GATEWAY=true

Integrações reais:

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.

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:

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

Validar:

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

/health deve reportar:

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

15. Subir o Agent Contas

Terminal 2:

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

Validar:

curl http://localhost:8000/health

16. Smoke test do MCP em mock

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:

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

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

Teste negativo importante:

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

19. Teste de contestação

Em mock:

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:

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:

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:

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:

VPN/DNS;
consultar_faturas;
consultar_vas;
consultar_historico_vas;
contrato/profile;
billing analysis;
Secure PDF;
protocol/status/tracking;
SMS;
cancelamento VAS;
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.

15 KiB Raw Blame History