# 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.