bugfix: Multi-item

Tuning-Performance/Multi_Item_MCP/README.md

@@ -0,0 +1,229 @@
+# Multi-Item MCP
+
+Capability de referência para operações MCP que precisam processar **mais de um item do mesmo tipo** em uma única intenção: produtos, pedidos, VAS, ativos, faturas, linhas, contratos ou recursos.
+
+> Esta capability é **framework-native**. Ela não exige um motor multi-item dentro do agente e não adiciona novos atributos obrigatórios a `tools.yaml` ou `tool_policies.yaml`.
+
+## Quando usar
+
+Use quando o usuário puder solicitar, por exemplo:
+
+```text
+cancele Produto A, Produto B e Produto C
+```
+
+ou:
+
+```text
+consulte os pedidos 1001, 1002 e 1003
+```
+
+O desenvolvedor deve modelar **uma operação lógica** que receba a coleção. O framework cuida de estado, confirmação e interpretação de resultados; o MCP Server ou workflow de domínio cuida da execução dos itens.
+
+## Divisão de responsabilidades
+
+```text
+Agent
+  seleciona a operação
+  NÃO cria motor multi-item
+
+      ↓
+
+tools.yaml
+  declara array/list
+  NÃO exige chave multi_item
+
+      ↓
+
+tool_policies.yaml
+  confirmação + pre-validation
+  usa o mesmo contrato transacional existente
+
+      ↓
+
+MCP validator
+  resolve/canonicaliza os itens
+  pode preencher transaction_decision.resolved_arguments
+
+      ↓
+
+MCP tool / workflow
+  executa os itens
+  devolve results[] com success/ok por item
+
+      ↓
+
+Agent Framework
+  mantém estado
+  controla confirmação
+  interpreta results[]
+  preserva evidência por item
+  calcula SUCCESS / PARTIAL_SUCCESS / FAILED
+
+      ↓
+
+LLM / Presentation
+  apresenta cada sucesso/falha
+```
+
+## Configuração mínima
+
+### `tools.yaml`
+
+O modo de configuração continua o mesmo. Declare o parâmetro como `array` ou `list`:
+
+```yaml
+tools:
+  cancelar_produtos:
+    description: Cancela um ou mais produtos.
+    mcp_server: contas
+    enabled: true
+    tool_type: action
+    confirmation_required: true
+    requires: [items]
+    args_schema:
+      items:
+        type: array
+        label: os produtos
+        description: Produtos solicitados pelo cliente.
+        user_prompt: Informe quais produtos deseja cancelar.
+```
+
+Não é necessário criar configuração como:
+
+```yaml
+# NÃO EXISTE / NÃO É NECESSÁRIO
+multi_item: true
+multi_item_strategy: partial
+fan_out: framework
+```
+
+### `tool_policies.yaml`
+
+O contrato também continua o mesmo:
+
+```yaml
+tool_policies:
+  cancelar_produtos:
+    operation_type: transactional
+    require_confirmation: true
+    requires: [items]
+    pre_validation:
+      enabled: true
+      tool: validar_produtos_cancelamento
+      fail_open: false
+```
+
+## Pre-validation e lista canônica
+
+O validator pode transformar nomes informais em uma coleção canônica antes da confirmação:
+
+```json
+{
+  "eligible": true,
+  "transaction_decision": {
+    "resolved_arguments": {
+      "items": [
+        {"name": "Produto A", "id": "1001"},
+        {"name": "Produto B", "id": "1002"},
+        {"name": "Produto C", "id": "1003"}
+      ]
+    },
+    "target_tool": "cancelar_produtos",
+    "confirmation_message": "Você confirma o cancelamento de Produto A, Produto B e Produto C?"
+  }
+}
+```
+
+### Validação parcial
+
+`eligible` é global para a transação. Portanto, se pelo menos um item puder ser processado, o validator **não deve reprovar o lote inteiro apenas porque outro item falhou**.
+
+Padrão recomendado:
+
+1. `eligible: true` quando existe pelo menos um item acionável;
+2. preservar/canonicalizar todos os itens necessários em `resolved_arguments`;
+3. executar a operação primária;
+4. retornar o resultado terminal individual em `results[]`.
+
+Se nenhum item puder ser processado, `eligible: false` é apropriado.
+
+## Resultado MCP esperado
+
+A tool primária deve retornar `results[]` com `success` ou `ok` booleano por item:
+
+```json
+{
+  "results": [
+    {"name": "Produto A", "success": true},
+    {"name": "Produto B", "success": false, "error": "not_found"},
+    {"name": "Produto C", "success": true}
+  ]
+}
+```
+
+O framework deriva automaticamente:
+
+```text
+PARTIAL_SUCCESS
+2 succeeded
+1 failed
+```
+
+Estados possíveis:
+
+| Resultado dos itens | Status do framework |
+|---|---|
+| todos concluídos | `SUCCESS` |
+| alguns concluídos e alguns falharam | `PARTIAL_SUCCESS` |
+| todos falharam | `FAILED` |
+
+## Uma chamada lógica, não N chamadas no agente
+
+Se o backend suporta batch, prefira:
+
+```text
+Agent -> cancelar_produtos(items=[A,B,C]) -> MCP
+```
+
+Se o backend possui apenas API unitária, o fan-out deve ficar encapsulado no MCP Server ou no workflow de domínio:
+
+```text
+Agent -> cancelar_produtos(items=[A,B,C])
+                   |
+                   v
+              MCP/workflow
+               /   |   \
+              A    B    C
+               \   |   /
+                results[]
+```
+
+Evite:
+
+```python
+# NÃO: lógica multi-item dentro do agente
+for item in items:
+    await tool_router.call("cancelar_produto", {"item": item})
+```
+
+## Workflow-backed tools
+
+Quando a operação é implementada por workflow, o caminho preferencial do resultado primário é:
+
+```text
+workflow.output[tool_name].results
+```
+
+Isso permite distinguir a operação primária de etapas auxiliares. Uma falha posterior não deve apagar o sucesso terminal de itens já executados.
+
+## Documentação completa
+
+Consulte também:
+
+- `docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE.md` — guia canônico em português;
+- `docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE_en.md` — guia canônico em inglês;
+- `templates/agent_template_backend/docs/MCP_MULTI_ITEM.md` — referência junto ao template;
+- `specs/SPEC-010-Agent-Development.md` — regra arquitetural de desenvolvimento.
+
+Para um passo a passo prático, leia `IMPLEMENTACAO_MULTI_ITEM_MCP.md` nesta pasta.