cristiano.hoshikawa/agent_contas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9ed4782f9ddd2d906e9b765bce555b302079f569
agent_contas/tests/docs/MANUAL_AGENT_CONTAS_MIGRADO.md
T3782834 9ed4782f9d ajuste no guardraild COE
2026-08-31 21:11:57 -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:

  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:

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

  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:

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:

  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.

Reference in New Issue View Git Blame Copy Permalink