Matriz de Migração — Contas -> agent_framework_oci
| Capacidade |
Destino novo |
Reuso framework |
Código de domínio novo |
Dependência anterior |
| LangGraph |
app/workflows/agent_graph.py |
Sim |
composição mínima |
Não |
| Router |
EnterpriseRouter |
Sim |
routing.yaml |
Não |
| Stickiness |
framework |
Sim |
configuração |
Não |
| Supervisor |
framework |
Sim |
configuração |
Não |
| Confirmação |
AgentRuntimeMixin |
Sim |
tool policy |
Não |
| Clarificação |
AgentRuntimeMixin/MCP mapping |
Sim |
schemas/mapping |
Não |
| Sessions |
framework repository |
Sim |
Não |
Não |
| Message memory |
framework |
Sim |
Não |
Não |
| Summary memory |
framework |
Sim |
Não |
Não |
| LTM |
framework |
Sim |
Não |
Não |
| Checkpoint |
framework |
Sim |
Não |
Não |
| RAG |
RagService |
Sim |
conteúdo/config |
Não |
| Guardrails |
GuardrailPipeline |
Sim |
config |
Não |
| Output Supervisor |
framework |
Sim |
Não |
Não |
| Judges |
JudgePipeline |
Sim |
config |
Não |
| MCP router |
framework |
Sim |
tool catalog |
Não |
| Faturas |
MCP/domain |
Não aplicável |
Sim |
Não |
| Billing Analysis |
MCP/domain |
Não aplicável |
Sim |
Não |
| Consulta/Histórico VAS |
MCP/domain |
Não aplicável |
Sim |
Não |
| Bloqueio/Cancelamento VAS |
MCP/domain |
confirmação no framework |
Sim |
Não |
| Contestação |
MCP/domain |
confirmação/estado no framework |
Sim |
Não |
| Protocol/Status/Tracking |
MCP/domain |
contexto no framework |
Sim |
Não |
| SMS |
MCP/domain |
contexto no framework |
Sim |
Não |
| Secure PDF |
MCP/domain |
contexto no framework |
Sim |
Não |
| Langfuse |
framework |
Sim |
Não |
Não |
| Pub/Sub/sequence |
framework |
Sim |
configuração |
Não |
| OCI Streaming |
framework |
Sim |
configuração |
Não |
| OTEL |
framework |
Sim |
configuração |
Não |
Regra
O pacote anterior não é uma biblioteca do novo projeto. Se uma regra específica for necessária, ela deve ser portada e testada dentro de app/domain/contas; infraestrutura genérica deve ser eliminada em favor do framework.
Contratos TIM validados por regressão
| Integração |
Paridade coberta |
Estado |
| CompleteInvoices |
método/payload/header ClientID |
✅ |
| Query VAS |
URL por MSISDN, clientId=AIAAGENTCR, auth |
✅ |
| VAS History |
query msisdn, clientId, messageId, auth |
✅ |
| Block VAS |
payload PMid + fallbacks e headers |
✅ |
| Cancel VAS |
DELETE, channel, protocol, headers, messageId |
✅ |
| Contract Information |
GET por MSISDN, clientId, auth |
✅ |
| Profile/Line Info |
GET e header ClientID |
✅ |
| Billing Analysis |
GET por MSISDN + channel |
✅ |
| Bill PDF |
POST detalhado + criptografia |
✅ |
| Secure PDF |
GET com parâmetros criptografados |
✅ |
| Customer Contestation |
payload/headers principais |
✅ |
| Service Request Status |
envelope serviceRequest |
✅ |
| Tracking Activities |
customer/invoice/activity/user |
✅ |
| Protocol V2 |
envelope Siebel + headers corporativos |
✅ |
| SMS Barcode |
payload completo + retry/RCT |
✅ |
Jornadas compostas e comportamento conversacional
| Capacidade original |
Implementação migrada |
Reuso do framework |
Regressão |
| Cancelamento VAS -> contestação |
dois workflows encadeados no MCP |
WorkflowRuntime |
✅ |
| Composição final cancelamento |
app/domain/contas/vas_cancellation_message.py |
domínio determinístico |
✅ 19 casos originais |
| Fallback VAS History |
ContasDomainService.cancelar_vas_avulso |
transporte via adapter |
✅ |
| Cancelamento parcial em lote |
action expõe cancelados/falhas/candidatos |
WorkflowRuntime + IdempotencyStore |
✅ |
| Idempotência transacional |
create_idempotency_store() |
framework |
✅ |
| Replay pós-finalização |
Channel short-circuit |
framework |
✅ |
| Idle nudge replay |
Channel short-circuit |
framework |
✅ |
| Processing interruption |
replay + classificador LLM fail-safe |
LLMProvider framework |
✅ |
| Correção Fim/Mim -> Sim |
channel transcription |
framework |
✅ |
| Finalização status/summary |
regra pura de domínio |
workflow framework |
✅ |
| Protocolo informacional final |
action + ProtocolV2 |
WorkflowRuntime |
✅ |
Bootstrap MCP
WorkflowRuntime, checkpointer e IdempotencyStore são inicializados de forma lazy. Isto evita dependência de Oracle/Redis para endpoints de diagnóstico e garante que o backend durável só seja aberto quando um workflow realmente precisar ser executado.
Incrementos de paridade - baseline 420
| Capacidade original |
Implementação migrada |
Responsabilidade |
Estado |
| InvoiceContextProvider / prefetch |
InvoiceContextService + agent_framework.cache.Cache |
domínio escolhe evidências; framework fornece cache |
✅ |
| Isolamento de invoice context por sessão |
chave session_id:msisdn:invoice_id |
framework cache |
✅ |
| Plano família titular/dependente |
normalização antes do workflow + contestação única no titular |
domínio + WorkflowRuntime |
✅ |
| Correção de linha por invoice detail |
normalização determinística |
domínio |
✅ |
| CVAL fail-stop |
edge success=false -> END |
WorkflowRuntime |
✅ |
| Snapshot parcial em falha |
WorkflowRuntime recupera último state do LangGraph |
framework |
✅ |
| Retry Billing Analysis / RCT 079-084 |
metadata _transport + RCTPolicy |
domínio define códigos; observer publica |
✅ |
| Finalização invoice explanation |
protocolo informacional somente após workflow executado |
domínio + WorkflowRuntime |
✅ |
| VEB fechado / force RT15 |
reuso ou novo protocolo conforme flags |
domínio |
✅ |
| Inicialização AgentWorkflow |
router/agentes/grafo dentro de __init__ |
aplicação/framework |
✅ |
Incrementos de paridade — baseline 435
| Capacidade original |
Implementação migrada |
Responsabilidade |
Status |
| Invoice prefetch single-flight |
InvoiceContextService + agent_framework.cache.Cache |
domínio escolhe evidências; framework fornece cache |
✅ |
| CVN de prefetch sem duplicação |
business_events + cache markers |
domínio define código; observer framework publica |
✅ |
| Latch invoice/workflow já executado |
AgentRuntimeMixin.business_workflows_executed |
framework |
✅ |
| Batch cancellation max 5 |
action async + semaphore |
domínio action sobre WorkflowRuntime |
✅ |
| Protocolo por linha antes de cancelar |
action cancelamento_vas_avulso_batch |
domínio + adapter TIM |
✅ |
| Erro estruturado de workflow |
WorkflowRunResult.error_details |
framework |
✅ |
| Provider error de contestação |
MCP mapping sobre error_details |
domínio/MCP fino |
✅ |
Baseline 440 testes - continuação
- 440 testes de migração passando; 2 skipped por dependências indisponíveis neste runtime (
langgraph/jellyfish).
- Cancelamento VAS: falha de bloqueio/cancelamento pode permanecer candidata à contestação sem mascarar sucesso.
- Resposta composta preserva protocolos de cancelamento por linha + protocolo de contestação e sinaliza finalização sugerida.
- Plano família: protocolo de cancelamento em dependente resolve
socialSecNo via LineInfo da própria linha.
- Registro de protocolo aceita aliases de resposta
interactionProtocol, protocolNumber, protocol e protocolo.
- Finalização informacional recalcula Bundle/Estratégico/Avulso pela evidência de
invoice_detail/Billing Analysis quando disponível.
Finalização - paridade adicional (baseline 533)
| Capability original |
Implementação migrada |
Framework reutilizado |
Evidência |
| CVN aceite/recusa no encerramento |
finalizar_atendimento_action |
business_events + AgentObserver |
testes de finalização estendida |
| Protocolo RT-15 informacional |
action de domínio + TIM client |
WorkflowRuntime/observer/idempotência |
RCT.085/086 + CVN.010/011 |
| Nota de invoice explanation |
valor canônico Explicação dos valores da fatura |
workflow latch do framework |
regressão |
| Handoff/retention suppression |
flags no state/domain action |
estado persistido do framework |
regressão |
| SAD decision tree |
SAD.001/002/003/004/005/006/007 como business events |
AgentObserver |
regressão |
| Classificação VAS sem invoice detail |
aliases determinísticos de domínio |
nenhuma engine paralela |
regressão |
| Regressão offline de workflow |
WorkflowRuntime(... allow_deterministic_fallback=True) somente em teste |
DSL/actions do framework |
18 casos históricos executados |
Atualização de paridade - baseline 550
| Capability |
Original |
Migrado |
Evidência |
| Finalização com prefetch de fatura |
CVN lookup + RT-15 quando aplicável |
Implementado |
regressão de finalização |
| Supressão após transição para negócio |
não reemite CVN/MPI |
Implementado |
regressão dedicada |
| VEB terminal |
não duplica RT-15/CVN |
Implementado |
regressão dedicada |
| Precedência de tipo pela fatura |
total/parcial/sem match |
Implementado |
regressão dedicada |
| Protocolo já existente |
não duplica RT-15 |
Implementado |
regressão dedicada |
| Matcher fonético/transcrição |
catálogo real |
Implementado sem xfails |
suíte de transcrição |
VAA — rastreabilidade de cancelamento/contestação
| Capability histórica |
Implementação migrada |
Framework reutilizado |
Estado |
| VAA.001–004 cancelamento |
cancelamento_vas_avulso_batch retorna business_events |
AgentObserver / analytics |
OK |
| VAA.005–009 contestação/boleto |
abrir_contestacao_cliente retorna business_events |
AgentObserver / analytics |
OK |
| VAA.012–015 SMS |
enviar_sms retorna business_events e mantém fluxo em erro |
AgentObserver / analytics |
OK |
| VAA.016–017 status SR |
atualizar_status_sr retorna business_events |
AgentObserver / analytics |
OK |
Baseline 560 testes - metadata corporativa TIM
- 560 testes de migração passando, sem skips/xfails.
- Business events preservam contexto corporativo:
agentProtocolId, adjustedProtocol, billingId, uraCallId, channelId, sessionId, messageId e agentSpecificData.
- Contestação VAA.005-009 preserva itens/valores ajustados e protocolo.
- Finalização CVN.010/011 preserva protocolo TIM/URA e billing context.
- RCTs derivados de retry HTTP carregam
apiUrl, apiStatusCode, apiResponsePayload e latencyMs.
- SMS e Service Request Status carregam metadata de transporte e contexto de protocolo.
tim_payload_mapper aceita o formato histórico agentSpecificData JSON-string e o converte para o objeto canônico TIM no payload final.
Paridade de eventos conversacionais — baseline 565
| Família |
Paridade adicionada |
| VEB |
ordem dos branches de VAS estratégico e metadata do turno/URA |
| MPI |
contexto de invoice explanation, pró-rata e cancelamento |
| CVN |
contexto conversacional/protocolo no encerramento |
| SAD |
llmResponse, messageId, sessão/canal e sessionEndAt normalizado |
Incremento de paridade — baseline 570
| Funcionalidade original |
Implementação migrada |
Responsabilidade |
| Cancelamento solicitado para item estratégico/bundle |
InvoiceResolver redireciona para workflow vas_estrategico |
Domínio + WorkflowRuntime |
| Invoice explanation SIM |
recomenda resolvido pelo último node do workflow |
MCP adapter fino sobre WorkflowRuntime |
| Invoice explanation NÃO sem VAS variado |
recomenda nao_resolvido |
MCP adapter fino sobre WorkflowRuntime |
| Pró-rata aceito / sem Plano Controle |
recomenda resolvido |
MCP adapter fino sobre WorkflowRuntime |
| Orientação de cancelamento de VAS estratégico por parceiro |
action declara requires_rag/rag_queries; AgentRuntimeMixin chama RagService |
Framework |
| Gate padrão de regressão |
pytest -q -> tests/ |
Projeto migrado |
Baseline 578 - wrapper cancelamento + LLM composition
- 593 testes passando; zero skipped/xfail.
- Cancelamento preserva
auto_finalize_on_failure em falha técnica de contestação.
- Item já contestado não mascara cancelamento concluído como falha sistêmica.
cancelamento_vas_protocol e todos os protocolos de resposta são preservados.- Plano família contesta titular + dependentes em uma única
contestacao_tool.
- Lote com muitos no-match continua contestando exatamente os candidatos elegíveis.
- Pró-rata usa
requires_llm_composition do framework em vez de gateway LLM de domínio.
Paridade de wrappers históricos — baseline 593
| Comportamento original |
Implementação migrada |
Estado |
tipo_atendimento=contestacao |
_workflow_payload(contestacao_tool) |
✅ |
| Contexto do turno no workflow |
payload MCP preserva IDs/canal/mensagem |
✅ |
| CPF como alias de socialSecNo |
normalização no wrapper composto |
✅ |
cancelados sem results.success |
fallback agregado do wrapper |
✅ |
itens_para_contestacao |
alias de contestation_candidates |
✅ |
| falha block/cancel ainda elegível a RT-02 |
composição de dois WorkflowRuntime |
✅ |
| SMS falha sem derrubar jornada |
sms_not_send_error |
✅ |
| Bundle + Estratégico + NÃO |
protocolo deferido + RAG obrigatório |
✅ |
Complemento de paridade — baseline 599
| Comportamento histórico |
Implementação migrada |
Prova |
| Itens já contestados |
normalização em abrir_contestacao_cliente + compositor determinístico |
teste de wrapper 1:1 |
| Itens contestados/não contestados |
classificação na action de domínio |
regressão de contestação |
| Total contestado somente dos itens aceitos |
cálculo determinístico no domínio |
regressão de contestação |
| Contestação retorna valor zero |
fallback para total efetivamente cancelado |
teste de wrapper 1:1 |
| Valor na fala em pt-BR |
normalização na borda MCP |
teste R$ 14,99 |
next_subject |
ignorado pelo compositor determinístico |
teste de wrapper 1:1 |
| Billing Analysis indisponível |
fraseologia canônica e auto_finalize_on_failure=false |
regressão invoice explanation |
Cobertura 1:1 de wrappers — baseline 615
Além dos testes de domínio/actions/workflows, a suíte passa a reproduzir diretamente
outcomes históricos dos wrappers cancelar_vas_single e finalize_support, cobrindo
no-match, candidatos explícitos, falhas parciais RT-01→RT-02, SMS, protocolos,
protocol_closed, plano família/titular-dependente e protocolo informacional deferido.
Esses testes são classificados como paridade explícita de contrato externo, e não
apenas cobertura indireta por actions internas.
