agent_platform_oci/Tuning-Performance/Multi_Item_MCP/README.md

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:

cancele Produto A, Produto B e Produto C

ou:

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

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

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

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:

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:

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:

{
  "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

{
  "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:

Agent -> cancelar(subject="A, B, C") -> validator/workflow -> results[]

ou:

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 é:

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.