new feature: Multi-Intent

docs/features/en/16_multi_intent_planning.md

@@ -0,0 +1,27 @@
+# Multi-Intent Planning
+
+`MultiIntentPlanner` recognizes independent requests in one utterance and
+builds a plan constrained to the intents, agents, and tools declared in
+`config/routing.yaml`. It does not execute operations or let the LLM invent a
+sequence: the router selects the primary operation and the domain workflow
+continues to own the transaction.
+
+## Configuration and execution
+
+No additional configuration is required. The planner uses the intents already
+declared in `routing.yaml`, selects the single transactional operation from
+`tool_policies.yaml`, and persists the remaining requests as `pending_topics`.
+
+Known read-only topics execute through their own agent. A second mutation stays
+pending for its own confirmation, while an unknown clause becomes off-context.
+
+The router resolves clauses from registered intent keywords and routes the
+transactional operation first. The graph drains read-only pending topics before
+output supervision. During an open transaction,
+`yes, and send me the invoice` confirms the transaction and records the
+secondary request instead of causing an intent shift.
+
+For multiple side-effecting actions, implement a transactional coordinator
+that persists the plan, confirms it, executes idempotently, and records partial
+failure or compensation. See `tests/unit/test_multi_intent_planner.py`. No
+special Tuning-Performance template is needed because the behavior is native.

docs/features/en/README.md

@@ -17,3 +17,4 @@ Documentation for the main `agent_framework_oci` features.
 - [Dynamic Transaction States](13_dynamic_transaction_states.md)
 - [Post Finalization Replay](14_post_finalization_replay.md)
 - [Retrieval / Tool Guardrails](15_retrieval_tool_guardrails.md)
+- [Multi-Intent Planning](16_multi_intent_planning.md)

docs/features/pt-BR/16_multi_intent_planning.md

@@ -0,0 +1,46 @@
+# Planejamento Multi-Intent
+
+O `MultiIntentPlanner` reconhece solicitações independentes na mesma mensagem e
+cria um plano limitado às intents, agents e tools declarados em
+`config/routing.yaml`. O planejador não executa operações nem permite que o LLM
+invente uma sequência: o roteador escolhe a operação primária e o workflow do
+domínio continua responsável pela transação.
+
+## Configuração
+
+Não existe configuração adicional. O planejador usa as intents do `routing.yaml`
+e lê `tool_policies.yaml` para priorizar automaticamente a única operação
+transacional. Pedidos secundários são persistidos em `pending_topics`.
+
+- intent conhecida e read-only: executada pelo agent correspondente;
+- intent conhecida e transacional: mantida pendente para confirmação própria;
+- trecho sem capability correspondente: respondido como `off_context`.
+
+Consultas secundárias com `execute` podem ser executadas pelo agent correspondente
+e consolidadas. Uma segunda mutação é marcada como `defer`, pois exige um
+workflow transacional coordenador.
+
+## Fluxo de execução
+
+1. O `EnterpriseRouter` separa a entrada em cláusulas e resolve cada uma pelas
+   keywords das intents cadastradas.
+2. `tool_policies.yaml` identifica a operação transacional e a torna primária.
+3. A primeira operação é roteada normalmente para seu agent/workflow.
+4. O `agent_graph` compõe as mensagens públicas antes do supervisor de saída.
+5. Durante uma confirmação, uma frase como `sim e me manda a segunda via`
+   confirma a transação aberta e registra a solicitação secundária, sem causar
+   troca indevida de intent.
+
+## Operações mutáveis
+
+Para executar mais de uma ação com efeito colateral, implemente um workflow
+transacional coordenador. Ele deve persistir o plano, pedir confirmação quando
+necessário, executar cada passo com idempotência e registrar sucesso parcial,
+falha e compensação. O planejador fornece o contrato; a política de negócio e a
+orquestração permanecem no domínio.
+
+## Referência executável
+
+Veja os testes genéricos em `tests/unit/test_multi_intent_planner.py`. Como a
+feature é padrão do runtime, não existe uma cópia especial do
+`agent_template_backend` em `Tuning-Performance`.

docs/features/pt-BR/README.md

@@ -17,3 +17,4 @@ Documentação das principais features do `agent_framework_oci`.
 - [Estados Transacionais Dinâmicos](13_dynamic_transaction_states.md)
 - [Replay Após Finalização](14_post_finalization_replay.md)
 - [Guardrails de Retrieval e Tools](15_retrieval_tool_guardrails.md)
+- [Planejamento Multi-Intent](16_multi_intent_planning.md)