First commit

Tuning-Performance/Multi_Item_MCP/IMPLEMENTACAO_MULTI_ITEM_MCP.md

@@ -0,0 +1,196 @@
+# Implementação prática — MCP Multi-Item
+
+Este documento mostra como adicionar uma operação multi-item sem criar lógica paralela no agente e sem alterar desnecessariamente contratos já existentes.
+
+## 1. Modele uma única operação lógica
+
+```text
+quero cancelar Produto A, Produto B e Produto C
+```
+
+A operação lógica continua sendo uma só. Não crie tools/intents por item nem loops no Agent.
+
+## 2. Escolha o contrato natural da operação
+
+### Opção A — parâmetro escalar
+
+Use quando a interface já recebe um `subject`, `id`, `query` ou expressão que pode representar uma ou várias entidades:
+
+```yaml
+tools:
+  cancelar_vas_avulso:
+    args_schema:
+      subject:
+        type: string
+```
+
+Entrada:
+
+```text
+subject = "Produto A, Produto B, Produto C"
+```
+
+### Opção B — coleção explícita
+
+Use quando a API/tool é naturalmente batch:
+
+```yaml
+tools:
+  cancelar_produtos:
+    args_schema:
+      items:
+        type: array
+```
+
+**Não transforme uma tool escalar em array apenas para obter suporte multi-item.**
+
+## 3. Use a policy existente
+
+Exemplo escalar:
+
+```yaml
+tool_policies:
+  cancelar_vas_avulso:
+    operation_type: transactional
+    require_confirmation: true
+    requires:
+      - subject
+    pre_validation:
+      enabled: true
+      tool: validar_vas_subject
+      fail_open: false
+```
+
+Nenhuma chave específica de multi-item é necessária.
+
+## 4. Canonicalize/expanda no validator quando necessário
+
+Entrada:
+
+```json
+{"subject": "produto a, produto b, produto c"}
+```
+
+Saída possível:
+
+```json
+{
+  "eligible": true,
+  "transaction_decision": {
+    "resolved_arguments": {
+      "subject": "Produto A, Produto B, Produto C",
+      "items": [
+        {"name": "Produto A", "id": "1001"},
+        {"name": "Produto B", "id": "1002"},
+        {"name": "Produto C", "id": "1003"}
+      ]
+    },
+    "confirmation_message": "Você confirma o cancelamento de Produto A, Produto B e Produto C?"
+  }
+}
+```
+
+O validator deve ser side-effect-free.
+
+## 5. Não transforme uma falha individual em rejeição global
+
+Caso:
+
+```text
+A = válido
+B = inválido
+C = válido
+```
+
+Com `fail_open: false`, isto bloquearia tudo:
+
+```json
+{"eligible": false, "reason": "B inválido"}
+```
+
+Quando A e C ainda podem ser executados, mantenha a transação globalmente elegível e preserve o estado individual dos itens.
+
+## 6. Execute no MCP Server ou workflow
+
+A tool/workflow pode receber `subject` e expandir internamente, ou receber `items[]` já canonicalizado.
+
+### Backend com API unitária
+
+```python
+async def cancelar_produtos(items):
+    results = []
+    for item in items:
+        try:
+            response = await backend.cancel_one(item)
+            results.append({"name": item["name"], "success": True, "response": response})
+        except Exception as exc:
+            results.append({"name": item["name"], "success": False, "error": str(exc)})
+    return {"results": results}
+```
+
+O loop pertence ao **MCP Server/workflow**, não ao Agent.
+
+## 7. Retorne `results[]` por item
+
+```json
+{
+  "results": [
+    {"name": "Produto A", "success": true},
+    {"name": "Produto B", "success": false, "error": "not_found"},
+    {"name": "Produto C", "success": true}
+  ]
+}
+```
+
+O framework aceita `success` ou `ok` booleano por item.
+
+## 8. Resultado interpretado pelo framework
+
+```text
+items_count            = 3
+items_succeeded_count  = 2
+items_failed_count     = 1
+multi_item_status      = PARTIAL_SUCCESS
+```
+
+## 9. Workflow com etapa auxiliar
+
+O resultado autoritativo da operação principal deve estar em:
+
+```text
+workflow.output[tool_name].results
+```
+
+Assim uma falha auxiliar posterior não apaga itens já concluídos.
+
+## 10. Checklist do desenvolvedor
+
+- [ ] existe uma única tool lógica para a operação;
+- [ ] `tools.yaml` declara o contrato natural, escalar ou coleção;
+- [ ] não existe requisito de `type: array` para habilitar multi-item;
+- [ ] `tool_policies.yaml` mantém os `requires` reais do domínio;
+- [ ] se um escalar representa vários itens, validator/tool/workflow faz a expansão;
+- [ ] com `fail_open: false`, falha individual não bloqueia automaticamente todos os itens acionáveis;
+- [ ] fan-out, se necessário, pertence ao MCP Server/workflow;
+- [ ] a tool primária devolve `results[]`;
+- [ ] cada item contém `success` ou `ok` booleano;
+- [ ] sucessos parciais não são apagados por uma falha global posterior;
+- [ ] a apresentação comunica sucesso/falha por item;
+- [ ] não foi criado um segundo motor multi-item no Agent.
+
+## 11. Testes mínimos recomendados
+
+```text
+1 item / sucesso
+N itens / todos sucesso
+N itens / sucesso parcial
+N itens / todos falha
+entrada escalar expandida para N itens
+entrada batch explícita
+item não canonicalizado
+confirmação única para N itens
+falha auxiliar após sucesso primário
+replay/idempotência da mesma operação
+```
+
+Para detalhes do contrato interno do runtime, consulte `docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE.md`.

Tuning-Performance/Multi_Item_MCP/README.md

@@ -0,0 +1,205 @@
+# 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`.
+
+> **Importante:** multi-item não é definido por `type: array`. O parâmetro de entrada pode ser escalar (`subject`, `id`, `query`) ou uma coleção. O que torna a execução multi-item é a resolução/execução de vários itens e o retorno por item em `results[]`.
+
+## 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**. O framework cuida de estado, confirmação e interpretação de resultados; validator/MCP Server/workflow cuidam da resolução e execução dos itens.
+
+## Divisão de responsabilidades
+
+```text
+Agent
+  seleciona a operação
+  NÃO cria motor multi-item
+
+      ↓
+
+tools.yaml
+  declara o contrato natural da operação
+  pode ser escalar OU coleção
+  NÃO exige chave multi_item
+
+      ↓
+
+tool_policies.yaml
+  confirmação + requires + pre-validation
+  NÃO possui sintaxe especial de multi-item
+
+      ↓
+
+MCP validator
+  resolve/canonicaliza itens
+  pode expandir subject/id/query em items[]
+  pode preencher transaction_decision.resolved_arguments
+
+      ↓
+
+MCP tool / workflow
+  executa 1 ou N 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 — padrão escalar
+
+Este padrão é útil quando a interface natural já usa `subject` e o validator expande múltiplas entidades.
+
+### `tools.yaml`
+
+```yaml
+tools:
+  cancelar_vas_avulso:
+    description: Cancela um ou mais VAS.
+    mcp_server: contas
+    enabled: true
+    tool_type: action
+    args_schema:
+      subject:
+        type: string
+```
+
+### `tool_policies.yaml`
+
+```yaml
+tool_policies:
+  cancelar_vas_avulso:
+    operation_type: transactional
+    require_confirmation: true
+    requires:
+      - subject
+    pre_validation:
+      enabled: true
+      tool: validar_vas_subject
+      fail_open: false
+```
+
+Nenhuma chave abaixo existe ou é necessária:
+
+```yaml
+multi_item: true
+multi_item_strategy: partial
+fan_out: framework
+```
+
+## Configuração alternativa — API batch
+
+Quando a tool MCP recebe naturalmente uma coleção, `array/list` continua válido:
+
+```yaml
+args_schema:
+  items:
+    type: array
+```
+
+Isso é **uma opção de contrato**, não um pré-requisito para multi-item.
+
+## Pre-validation e expansão de itens
+
+Um `subject` escalar pode ser transformado em argumentos canônicos:
+
+```json
+{
+  "eligible": true,
+  "transaction_decision": {
+    "resolved_arguments": {
+      "subject": "Produto A, Produto B, Produto C",
+      "items": [
+        {"name": "Produto A", "id": "1001"},
+        {"name": "Produto B", "id": "1002"},
+        {"name": "Produto C", "id": "1003"}
+      ]
+    },
+    "confirmation_message": "Você confirma o cancelamento de Produto A, Produto B e Produto C?"
+  }
+}
+```
+
+### Validação parcial
+
+`eligible` é global. Com `fail_open: false`, não retorne `eligible: false` apenas porque um item falhou se outros ainda são acionáveis.
+
+Padrão recomendado:
+
+1. `eligible: true` enquanto houver pelo menos um item acionável;
+2. preservar resolução/eligibilidade individual;
+3. executar a operação primária;
+4. produzir o resultado terminal individual em `results[]`.
+
+## Resultado MCP esperado
+
+```json
+{
+  "results": [
+    {"name": "Produto A", "success": true},
+    {"name": "Produto B", "success": false, "error": "not_found"},
+    {"name": "Produto C", "success": true}
+  ]
+}
+```
+
+O framework deriva automaticamente `SUCCESS`, `PARTIAL_SUCCESS` ou `FAILED`.
+
+## Uma operação lógica, sem N chamadas no agente
+
+São válidos:
+
+```text
+Agent -> cancelar(subject="A, B, C") -> validator/workflow -> results[]
+```
+
+ou:
+
+```text
+Agent -> cancelar(items=[A,B,C]) -> MCP/workflow -> results[]
+```
+
+Se o backend possui apenas API unitária, o fan-out fica no MCP Server/workflow. Evite loop MCP de negócio dentro do agente.
+
+## Workflow-backed tools
+
+Quando a operação é implementada por workflow, o caminho preferencial do resultado primário é:
+
+```text
+workflow.output[tool_name].results
+```
+
+Uma falha posterior não deve apagar sucesso terminal de itens já executados.
+
+## Documentação completa
+
+- `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.
+
+Para o passo a passo prático, leia `IMPLEMENTACAO_MULTI_ITEM_MCP.md`.

Tuning-Performance/Multi_Item_MCP/README_en.md

@@ -0,0 +1,58 @@
+# Multi-Item MCP
+
+Reference capability for MCP operations that process more than one item under a single logical user intent.
+
+> Multi-item support is **not enabled by `type: array`**. The input may be scalar (`subject`, `id`, `query`) or a collection. Multi-item behavior comes from resolving/executing several items and returning per-item `results[]`.
+
+```text
+Agent               selects the operation; no business fan-out
+  -> tools.yaml     declares the natural input contract: scalar OR collection
+  -> tool_policies  confirmation/requires/pre-validation; no special multi-item syntax
+  -> validator      resolves/canonicalizes and may expand one value into items[]
+  -> MCP/workflow   executes 1 or N items and returns results[]
+  -> framework      preserves per-item evidence and derives SUCCESS/PARTIAL_SUCCESS/FAILED
+  -> presentation   reports each success/failure
+```
+
+## Scalar pattern
+
+```yaml
+tool_policies:
+  cancelar_vas_avulso:
+    operation_type: transactional
+    require_confirmation: true
+    requires:
+      - subject
+    pre_validation:
+      enabled: true
+      tool: validar_vas_subject
+      fail_open: false
+```
+
+`subject` may represent one or many entities. The validator/workflow may expand it into canonical `items[]`.
+
+## Explicit batch pattern
+
+```yaml
+args_schema:
+  items:
+    type: array
+```
+
+This is supported, but it is **an interface option, not a requirement**.
+
+## Result contract
+
+```json
+{
+  "results": [
+    {"name": "A", "success": true},
+    {"name": "B", "success": false},
+    {"name": "C", "success": true}
+  ]
+}
+```
+
+The runtime derives `PARTIAL_SUCCESS` and preserves the successful items.
+
+For full details, read `docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE_en.md`.