agent_contas/IMPLEMENTACAO_MULTI_INTENT.md

Implementação Multi-Intent

Entregas

• Planejador determinístico no framework, limitado às intents, agents e tools cadastrados no routing.yaml.
• Priorização automática pela natureza das tools em tool_policies.yaml, sem política por combinação.
• Persistência padrão em pending_topics e histórico em handled_topics.
• Tratamento de confirmação composta (sim e ...) sem provocar troca de intent durante uma transação aberta.
• Composição das mensagens controladas das operações secundárias antes dos guardrails de saída.
• Tratamento do cancelamento de Tamboro combinado com segunda via ou assunto realmente fora do escopo.
• Desambiguação de cobranças repetidas por seleção relativa, incluindo as duas mais caras, alimentando o batch já suportado pelo workflow de cancelamento.
• Guias em português e inglês em agent_framework_oci/docs/features.
• Integração propagada às dez variantes de backend existentes em agent_framework_oci/Tuning-Performance, sem criar um exemplo artificial.
• Script idempotente agent_framework_oci/scripts/sync_pending_topics_to_tuning.py para manter as cópias sincronizadas.

Testes adicionados

• agent_framework_oci/tests/unit/test_multi_intent_planner.py
• tests/migration/test_multi_intent_contas.py
• agent_framework_oci/tests/unit/test_tuning_pending_topics_sync.py

Evidências recuperadas do Contas antigo

O documento antigo docs/PENDING_TOPICS_CAMADA.md descrevia explicitamente:

• cancelamento simples;
• cancelamento + pergunta conceitual sobre outro serviço;
• cancelamento + solicitação fora do contexto, como alteração de CNPJ;
• drenagem de tópicos pendentes antes da confirmação ou finalização;
• manutenção do tópico para retry quando não fosse produzida resposta útil.

Esses comportamentos foram usados como referência. A segunda via não é tratada como fora de escopo quando a versão atual do Contas possui uma intent/tool para ela; nesse caso ela é executada como consulta secundária. Somente uma solicitação sem capability registrada vira off_context.

Resultado da validação

O recorte de 23 testes do planejador e das integrações transacionais afetadas passa integralmente. A execução ampla de agent_framework_oci/tests/unit e tests/migration resultou em 946 testes aprovados e 33 falhas já presentes em áreas fora desta alteração (principalmente checkpoints, runtime legado de workflows, guardrails e paridade histórica).

Limite de execução

Consultas secundárias conhecidas são executadas e consolidadas. Assuntos sem capability são tratados como off_context. Uma segunda ação mutável permanece pendente e requer confirmação própria ou um workflow transacional coordenador.

Correção de isolamento da operação secundária

O teste real cancelar Tamboro + segunda via revelou que o agent secundário herdava o snapshot operacional da transação primária. Isso fazia o FaturasAgent reutilizar selected_tool_call=cancelar_vas_avulso e repetir a confirmação do cancelamento. O estado filho agora limpa integralmente transação, tool selecionada/pendente, workflow, parâmetros ausentes, resultados MCP, next_state, workflow_id e usa a cláusula secundária também como sanitized_input. O teste test_pending_topics_isolation.py protege essa regra.

Uma segunda execução real mostrou outro campo de roteamento que precisava ser isolado: mcp_tools permanecia com a allowlist da operação primária. O runtime usa esse campo de primeiro nível como fonte de verdade, portanto o FaturasAgent ainda selecionava o cancelamento. O estado filho agora sobrescreve domain, mcp_tools e available_mcp_tools exclusivamente com a capability do tópico secundário.