cristiano.hoshikawa/agent_contas
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Multi-item documentation

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-09-18 23:35:05 -03:00
parent 3ebdaacabc
commit 2ad9afd974
19 changed files with 1156 additions and 1043 deletions
Download Patch File Download Diff File Expand all files Collapse all files

511
agent_framework_oci/docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE.md
View File

@@ -2,37 +2,69 @@
## Objetivo
Use este guia quando uma única intenção do usuário precisa operar sobre **mais de um item do mesmo tipo** em uma chamada MCP, por exemplo:
Use este guia quando uma única intenção do usuário precisa operar sobre **mais de um item do mesmo tipo** — por exemplo, cancelar vários VAS/produtos, devolver ou consultar vários pedidos, alterar vários ativos ou processar várias faturas/linhas/contratos.
- cancelar vários VAS/produtos;
- devolver ou consultar vários pedidos;
- alterar vários ativos;
- processar uma lista de faturas, linhas, contratos ou recursos.
O framework já possui suporte genérico para **resolução/canonicalização de múltiplos itens**, **confirmação transacional**, **execução MCP/workflow**, **preservação de evidência por item** e **normalização de `SUCCESS` / `PARTIAL_SUCCESS` / `FAILED`**. O desenvolvedor não deve criar um segundo motor de multi-item dentro do agente.
O framework já possui contratos genéricos para **coleta de listas**, **pré-validação/canonicalização**, **confirmação transacional**, **execução MCP** e **normalização do resultado por item**. O desenvolvedor não deve criar um segundo motor de multi-item dentro do agente.
> **Regra central:** multi-item é uma característica da resolução, execução e resultado da operação. **Não é definido pelo tipo do parâmetro de entrada.** Uma tool pode receber `subject: string`, `id: string`, `items: array` ou outro contrato natural de domínio e ainda assim processar múltiplos itens.
## Regra principal
**Não faça loop de negócio no agente.** O agente declara a tool e seus parâmetros; o runtime mantém estado, confirmação e evidência. A operação em lote deve ser exposta como uma tool MCP que aceite uma coleção, ou como uma tool transacional apoiada por um workflow/MCP que processe a coleção.
**Não faça loop de negócio no agente.** O agente seleciona a intenção/tool e usa o runtime. A expansão para múltiplos itens pode ocorrer no pre-validator, na própria tool MCP ou em um workflow de domínio.
Fluxo recomendado:
```text
Usuário cita N itens
-> Router/Agent seleciona a tool
-> Runtime coleta/reconcilia parâmetro array/list
-> (opcional) pre-validation canonicaliza itens
-> Runtime pede UMA confirmação coerente para o conjunto
-> MCP recebe a coleção
-> MCP/workflow processa item a item
-> MCP devolve results[] com success/ok por item
-> Runtime coleta os parâmetros declarados pela tool
-> Entrada pode ser escalar ou coleção
-> (opcional) pre-validation resolve/expande/canonicaliza N itens
-> Runtime pede UMA confirmação coerente para o conjunto efetivo
-> MCP tool/workflow processa 1 ou N itens
-> Tool primária devolve results[] com success/ok por item
-> Framework normaliza SUCCESS / PARTIAL_SUCCESS / FAILED
-> Composição final relata sucessos e falhas individualmente
```
## 1. Declarar um parâmetro de lista em `tools.yaml`
## 1. Declare o contrato natural da operação em `tools.yaml`
O reconciliador transacional do framework aceita `type: array` ou `type: list`.
O framework **não exige `array/list`** para que uma operação seja multi-item.
Use o contrato que faz sentido para a tool e para o domínio:
- **parâmetro escalar** (`subject`, `id`, `query`, etc.) quando a operação recebe uma expressão que pode representar uma ou várias entidades;
- **`array/list`** quando a interface MCP é naturalmente batch e recebe explicitamente uma coleção.
### Padrão A — parâmetro escalar que pode representar vários itens
Este é o padrão usado pelo agente de Contas para cancelamento de VAS.
```yaml
tools:
cancelar_vas_avulso:
description: Cancela um ou mais serviços VAS.
mcp_server: contas
enabled: true
tool_type: action
args_schema:
subject:
type: string
label: o serviço ou os serviços
description: Serviço ou expressão com um ou mais serviços a cancelar.
```
Entrada possível:
```text
subject = "TIM Fashion, Aya Audiobooks, Neymar Jr"
```
O `subject` continua sendo uma `string`. O suporte multi-item aparece posteriormente quando o validator/tool resolve essa expressão em itens independentes.
### Padrão B — coleção explícita
Também é válido quando a API/tool é naturalmente batch:
```yaml
tools:
@@ -41,119 +73,156 @@ tools:
mcp_server: contas
enabled: true
tool_type: action
confirmation_required: true
requires: [items]
args_schema:
items:
type: array
label: os produtos
description: Lista de produtos que o cliente deseja cancelar.
user_prompt: Informe quais produtos deseja cancelar.
```
O runtime pode reconciliar uma frase como:
Os dois padrões são suportados. **Não altere uma interface escalar existente para array apenas para “habilitar multi-item”.**
```text
quero cancelar TIM Fashion, Aya Audiobooks e Neymar Jr
```
## 2. `tool_policies.yaml` não possui sintaxe especial de multi-item
para um argumento lógico semelhante a:
`tool_policies.yaml` continua definindo tipo de operação, confirmação, parâmetros obrigatórios e pre-validation. Não é necessário criar `multi_item: true`, trocar `subject` por `items` ou introduzir outra configuração.
```json
{
"items": ["TIM Fashion", "Aya Audiobooks", "Neymar Jr"]
}
```
A semântica de domínio e a validação dos nomes continuam pertencendo ao MCP/pre-validator, não ao core.
## 2. Quando usar pre-validation
Use `tool_policies.yaml` quando a lista precisa ser resolvida/canonicalizada antes da confirmação.
Exemplo realista do agente de Contas:
```yaml
version: 1
defaults:
operation_type: read_only
require_confirmation: false
tool_policies:
cancelar_produtos:
cancelar_vas_avulso:
operation_type: transactional
require_confirmation: true
requires: [items]
requires:
- subject
pre_validation:
enabled: true
tool: validar_produtos_cancelamento
tool: validar_vas_subject
fail_open: false
```
O pre-validator pode retornar `eligible: true` e substituir argumentos por valores canônicos em `transaction_decision.resolved_arguments`:
`requires: [subject]` significa apenas que a operação precisa saber **o que** será processado. Esse `subject` pode representar um item ou vários.
```json
{
"eligible": true,
"transaction_decision": {
"resolved_arguments": {
"items": [
{"name": "TIM Fashion Mensal", "id": "1001"},
{"name": "Aya Audiobooks Premium", "id": "1002"},
{"name": "Neymar Jr", "id": "1003"}
]
},
"target_tool": "cancelar_produtos",
"confirmation_message": "Você confirma o cancelamento de TIM Fashion Mensal, Aya Audiobooks Premium e Neymar Jr?"
}
}
```
## 3. Pre-validation pode transformar um parâmetro escalar em múltiplos itens
### Importante para validação parcial
O contrato `eligible` da pre-validation é global. Portanto, **não retorne `eligible: false` apenas porque um item da lista falhou**, caso os demais ainda possam ser processados. Isso encerraria toda a transação.
Para permitir resultado parcial, a estratégia recomendada é:
1. retornar `eligible: true` quando existe pelo menos um item acionável;
2. preservar/canonicalizar a coleção em `resolved_arguments`;
3. deixar a tool primária devolver o resultado terminal de **cada item** em `results[]`.
Se nenhum item puder ser processado, então `eligible: false` é apropriado.
## 3. Contrato de entrada do MCP
Prefira uma única chamada MCP com uma coleção explícita:
```json
{
"tool_name": "cancelar_produtos",
"arguments": {
"customer_id": "123",
"items": [
{"name": "TIM Fashion Mensal", "id": "1001"},
{"name": "Aya Audiobooks Premium", "id": "1002"},
{"name": "Neymar Jr", "id": "1003"}
]
}
}
```
O framework **não deve ser usado como um loop improvisado que chama N vezes uma tool escalar a partir do agente**. Se o backend só possui API unitária, o fan-out pode ficar encapsulado no MCP Server ou em um workflow de domínio, mantendo uma única tool lógica para o agente.
## 4. Contrato obrigatório de resultado por item
Para o framework reconhecer multi-item automaticamente, a **tool primária solicitada** deve expor uma lista `results` com **dois ou mais itens**, e cada item deve possuir um booleano `success` ou `ok`.
Quando necessário, o pre-validator resolve nomes, canonicaliza entidades e pode materializar uma lista estrutural em `transaction_decision.resolved_arguments`.
Exemplo:
```json
{
"ok": true,
"result": {
"results": [
{"id": "1001", "subject": "TIM Fashion Mensal", "success": true},
{"id": "1002", "subject": "Aya Audiobooks Premium", "success": false, "reason": "not_found"},
{"id": "1003", "subject": "Neymar Jr", "success": true}
"eligible": true,
"subject": "TIM Fashion, Aya Audiobooks, Neymar Jr",
"resolved_subject": "TIM Fashion Mensal, Aya Audiobooks Premium, Neymar Jr",
"resolved_subjects": [
"TIM Fashion Mensal",
"Aya Audiobooks Premium",
"Neymar Jr"
],
"transaction_decision": {
"resolved_arguments": {
"subject": "TIM Fashion Mensal, Aya Audiobooks Premium, Neymar Jr",
"items": [
{"name": "TIM Fashion Mensal"},
{"name": "Aya Audiobooks Premium"},
{"name": "Neymar Jr"}
]
},
"target_tool": "cancelar_vas_avulso",
"confirmation_message": "Você confirma o cancelamento de TIM Fashion Mensal, Aya Audiobooks Premium e Neymar Jr?"
}
}
```
`resolved_arguments.items[]` é uma representação canônica útil para a execução, mas **não obriga** `tools.yaml` a declarar `items` como parâmetro de entrada.
### Validação parcial e `fail_open: false`
`eligible` é global. Com `fail_open: false`, retornar `eligible: false` encerra a transação inteira.
Portanto, quando alguns itens são válidos e outros não:
1. mantenha `eligible: true` se existe pelo menos um item acionável;
2. preserve o estado individual dos itens resolvidos/rejeitados;
3. deixe a tool primária produzir o resultado terminal por item em `results[]`.
Exemplo conceitual:
```json
{
"eligible": true,
"status": "PARTIALLY_ELIGIBLE",
"transaction_decision": {
"resolved_arguments": {
"items": [
{"name": "TIM Fashion Mensal", "eligible": true},
{"name": "Aya Audiobooks Premium", "eligible": false, "reason": "item_nao_encontrado"},
{"name": "Neymar Jr", "eligible": true}
]
}
}
}
```
Se nenhum item puder ser processado, `eligible: false` é apropriado.
## 4. Contrato de entrada do MCP: uma operação lógica, não necessariamente uma coleção explícita
Prefira **uma única operação lógica MCP para o agente**. Ela pode ser implementada de três formas:
1. receber um parâmetro escalar e expandi-lo no validator/workflow;
2. receber uma coleção explícita (`array/list`);
3. receber uma expressão/identificador e descobrir os itens dentro da própria tool/workflow.
O agente não deve fazer fan-out chamando a mesma tool repetidamente por conta própria.
### Exemplo — escalar expandido
```json
{
"tool_name": "cancelar_vas_avulso",
"arguments": {
"subject": "TIM Fashion Mensal, Aya Audiobooks Premium, Neymar Jr"
}
}
```
### Exemplo — batch explícito
```json
{
"tool_name": "cancelar_produtos",
"arguments": {
"items": [
{"name": "A", "id": "1001"},
{"name": "B", "id": "1002"}
]
}
}
```
Campos como `id`, `subject`, `name`, `reason`, `error`, `protocol` e outros são de domínio e opcionais. O sinal estrutural exigido pelo normalizador é `success: true|false` ou `ok: true|false` por item.
Se o backend só possui API unitária, o fan-out deve ficar encapsulado no **MCP Server ou workflow de domínio**, preservando uma única operação lógica para o agente.
## 5. Contrato obrigatório de resultado por item
Para o framework reconhecer automaticamente o resultado como multi-item, a **tool primária solicitada** deve expor uma lista `results` com **dois ou mais itens**, e cada item deve possuir `success` ou `ok` booleano.
```json
{
"results": [
{"subject": "TIM Fashion Mensal", "success": true},
{"subject": "Aya Audiobooks Premium", "success": false, "reason": "not_found"},
{"subject": "Neymar Jr", "success": true}
]
}
```
Campos como `id`, `subject`, `name`, `reason`, `error`, `protocol` e outros são de domínio e opcionais. O sinal estrutural do normalizador é `success: true|false` ou `ok: true|false` por item.
### Workflow-backed tool
@@ -163,37 +232,20 @@ Se a tool é executada por workflow, o caminho preferencial e autoritativo é:
workflow.output[tool_name].results
```
Uma falha auxiliar posterior não deve apagar itens já concluídos pela tool primária.
## 6. O que o framework produz automaticamente
Com `results[]` válido, o runtime classifica o agregado como:
| Situação | `multi_item_status` |
|---|---|
| todos os itens concluíram | `SUCCESS` |
| parte concluiu e parte falhou | `PARTIAL_SUCCESS` |
| todos falharam | `FAILED` |
Exemplo:
```json
{
"ok": false,
"result": {
"status": "COMPLETED",
"output": {
"cancelar_produtos": {
"results": [
{"subject": "A", "success": true},
{"subject": "B", "success": false, "reason": "not_found"},
{"subject": "C", "success": true}
]
},
"etapa_auxiliar": {
"success": false,
"error": "falha em pós-processamento"
}
}
},
"error": "falha em pós-processamento"
}
```
O runtime preserva o resultado da operação primária e não permite que uma falha auxiliar apague itens já concluídos.
## 5. O que o framework produz automaticamente
Com `results[]` válido, o runtime adiciona:
```json
{
"multi_item_status": "PARTIAL_SUCCESS",
@@ -204,141 +256,178 @@ Com `results[]` válido, o runtime adiciona:
"items_count": 3,
"items_succeeded_count": 2,
"items_failed_count": 1,
"primary_tool": "cancelar_produtos"
"primary_tool": "cancelar_vas_avulso"
}
}
}
```
Estados possíveis:
Se um wrapper/etapa posterior retornar erro depois de existirem resultados terminais válidos, o framework preserva os sucessos individuais e pode registrar o erro como secundário, em vez de converter tudo para falha total.
| Situação | `multi_item_status` |
|---|---|
| todos os itens concluíram | `SUCCESS` |
| parte concluiu e parte falhou | `PARTIAL_SUCCESS` |
| todos falharam | `FAILED` |
## 7. O que NÃO fazer
Se uma etapa posterior fizer o wrapper retornar `ok=false`, mas pelo menos um item primário tiver sucesso, o framework preserva para auditoria:
```json
{
"ok": true,
"original_ok": false,
"secondary_error": "erro da etapa posterior"
}
```
Isso evita transformar sucesso parcial/real em falha total na resposta ao usuário.
## 6. O que NÃO fazer
Evite estes padrões:
Não crie motor multi-item dentro do agente:
```python
# NÃO: motor multi-item paralelo dentro do agente
# NÃO
for product in products:
await tool_router.call("cancelar_produto", {"product": product})
```
Não reduza resultado misto a um único booleano global sem evidência por item:
```json
// NÃO: apenas um approved global sem evidência por item
{
"approved": false,
"error": "um item falhou"
}
```
```json
// NÃO: um único success agregado quando houve resultados mistos
{
"success": false,
"message": "operação bloqueada"
}
Também não altere uma interface existente apenas para trocar:
```text
subject: string
```
Esses formatos perdem a evidência terminal individual e podem fazer itens concluídos desaparecerem da composição final.
por:
## 7. Exemplo completo: vários pedidos
```text
items: array
```
quando o validator/workflow já consegue expandir corretamente o `subject`.
## 8. Exemplo completo — padrão escalar do Contas
### `tools.yaml`
```yaml
tools:
cancelar_pedidos:
description: Cancela um ou mais pedidos.
mcp_server: retail
cancelar_vas_avulso:
description: Cancela um ou mais VAS.
mcp_server: contas
enabled: true
tool_type: action
confirmation_required: true
requires: [order_ids]
args_schema:
order_ids:
type: array
label: os pedidos
description: Lista de identificadores de pedidos a cancelar.
user_prompt: Quais pedidos deseja cancelar?
subject:
type: string
```
### Retorno MCP
### `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
```
### Validator
```json
{
"ok": true,
"result": {
"results": [
{"order_id": "P-100", "success": true, "protocol": "ABC1"},
{"order_id": "P-101", "success": false, "reason": "already_shipped"},
{"order_id": "P-102", "success": true, "protocol": "ABC3"}
]
"eligible": true,
"transaction_decision": {
"resolved_arguments": {
"subject": "TIM Fashion Mensal, Aya Audiobooks Premium, Neymar Jr",
"items": [
{"name": "TIM Fashion Mensal"},
{"name": "Aya Audiobooks Premium"},
{"name": "Neymar Jr"}
]
}
}
}
```
O framework classificará automaticamente como `PARTIAL_SUCCESS` e fornecerá ao LLM a instrução de relatar os resultados item a item.
### Resultado MCP/workflow
## 8. Read-only multi-item
A mesma estrutura serve para consultas em lote. A diferença é que normalmente não existe confirmação:
```yaml
tool_policies:
consultar_pedidos:
operation_type: read_only
require_confirmation: false
```json
{
"results": [
{"subject": "TIM Fashion Mensal", "success": true},
{"subject": "Aya Audiobooks Premium", "success": false, "reason": "not_found"},
{"subject": "Neymar Jr", "success": true}
]
}
```
A tool ainda pode retornar `results[]` com `success/ok` por item para que uma consulta parcialmente indisponível não esconda as consultas bem-sucedidas.
Resultado agregado: `PARTIAL_SUCCESS`.
## 9. Idempotência e protocolos
## 9. Exemplo alternativo — API naturalmente batch
Quando o MCP já define coleção como contrato de entrada, `array/list` continua válido:
```yaml
args_schema:
order_ids:
type: array
```
```json
{
"results": [
{"order_id": "P-100", "success": true},
{"order_id": "P-101", "success": false, "reason": "already_shipped"},
{"order_id": "P-102", "success": true}
]
}
```
O ponto importante é: **array é uma opção de contrato, não o gatilho do mecanismo multi-item.**
## 10. Read-only, conversational e transactional podem ser multi-item
Multi-item é independente do `operation_type`.
É possível ter:
```text
read_only + multi-item
conversational + multi-item
transactional + multi-item
internal + multi-item
```
O que muda é a política de confirmação e execução, não a capacidade de representar vários itens.
## 11. Idempotência e protocolos
Em operações com efeito colateral:
- use uma chave de idempotência de requisição e, quando necessário, uma chave por item;
- use chave de idempotência de requisição e, quando necessário, por item;
- devolva protocolo/operation id no próprio item;
- não dependa apenas de uma mensagem textual agregada;
- em retry, preserve os itens já concluídos e execute apenas o que a regra de domínio permitir.
- preserve itens já concluídos em retry;
- não dependa apenas de mensagem textual agregada.
O framework preserva evidência; a política de idempotência do sistema de destino continua pertencendo ao MCP/workflow de domínio.
A política específica de idempotência do sistema de destino continua pertencendo ao MCP/workflow de domínio.
## 10. Checklist para o desenvolvedor
## 12. Checklist do desenvolvedor
- [ ] A tool aceita `array/list` quando o caso de uso é multi-item.
- [ ] Não existe loop MCP de negócio dentro da classe do agente.
- [ ] Se houver canonicalização, ela está em pre-validation/MCP, não hardcoded no agente.
- [ ] A confirmação mostra o conjunto efetivo de itens.
- [ ] A tool primária retorna `results[]` com `success` ou `ok` por item.
- [ ] O agente seleciona a operação e **não** implementa fan-out/loop MCP de negócio.
- [ ] `tools.yaml` declara o contrato natural da operação, que pode ser escalar ou coleção.
- [ ] Nenhuma chave especial `multi_item: true` foi criada ou é necessária.
- [ ] `tool_policies.yaml` usa os `requires` reais do domínio; não é necessário trocar `subject` por `items`.
- [ ] Se um escalar representar múltiplas entidades, validator/tool/workflow expande e canonicaliza os itens.
- [ ] A confirmação representa o conjunto efetivo resolvido.
- [ ] Com `fail_open: false`, um item inválido não força `eligible: false` global quando outros ainda são acionáveis.
- [ ] A tool primária retorna `results[]` com `success` ou `ok` por item quando há múltiplos resultados.
- [ ] Workflow usa `output[tool_name].results` como evidência terminal preferencial da tool primária.
- [ ] Resultado parcial não é reduzido a um único `approved=false` ou `success=false` global.
- [ ] Workflow usa `output[tool_name].results` para a evidência terminal da tool primária.
- [ ] Testes cobrem todos-sucesso, parcial, todos-falha e falha auxiliar posterior.
- [ ] A resposta final menciona sucessos e falhas quando houver `PARTIAL_SUCCESS`.
- [ ] A apresentação final menciona sucessos e falhas individualmente quando houver `PARTIAL_SUCCESS`.
## 11. Onde o comportamento existe no framework
Referências atuais:
## 13. Onde o comportamento existe no framework
```text
libs/agent_framework/src/agent_framework/runtime/transaction_parameters.py
- coerção de type=array/list
- suporte existente a coerção de array/list quando esse for o contrato declarado
libs/agent_framework/src/agent_framework/runtime/agent_runtime.py
- pre-validation e resolved_arguments
@@ -350,14 +439,14 @@ tests/test_multi_item_result_normalization.py
- regressões de SUCCESS/PARTIAL_SUCCESS e proteção contra falha auxiliar
```
## 12. Resumo de responsabilidade
## 14. Resumo de responsabilidade
| Camada | Responsabilidade |
|---|---|
| Agente | declarar intenção/tool e usar o runtime; não implementar motor multi-item |
| `tools.yaml` | declarar parâmetro `array/list` e schema |
| `tool_policies.yaml` | confirmação e pre-validation |
| Pre-validator MCP | resolver/canonicalizar entidades e argumentos |
| Tool MCP/workflow | executar a coleção e produzir resultado por item |
| Framework runtime | manter estado, confirmação, normalizar resultado multi-item e preservar evidência |
| LLM/presentation | transformar evidências em resposta, sem apagar sucesso/falha individual |
| Agente | selecionar intenção/tool e usar o runtime; não implementar motor multi-item |
| `tools.yaml` | declarar o contrato natural da operação; pode ser escalar ou coleção |
| `tool_policies.yaml` | confirmação, `requires` e pre-validation; sem sintaxe especial de multi-item |
| Pre-validator MCP | identificar, resolver, canonicalizar e, quando necessário, expandir 1 parâmetro em N itens |
| Tool MCP/workflow | executar 1 ou N itens e produzir resultado por item |
| Framework runtime | manter estado/confirmação, interpretar `results[]`, preservar evidência e calcular `SUCCESS` / `PARTIAL_SUCCESS` / `FAILED` |
| LLM/presentation | transformar evidências em resposta sem apagar sucesso/falha individual |

290
agent_framework_oci/docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE_en.md
View File

@@ -2,251 +2,169 @@
## Purpose
Use this guide when a single user intent must operate on **more than one item of the same kind** through MCP, such as multiple products, orders, assets, invoices, lines, contracts, or resources.
Use this guide when one user intent must operate on **more than one item of the same kind**. The framework already supports item resolution/canonicalization, transactional confirmation, MCP/workflow execution, per-item evidence preservation, and `SUCCESS` / `PARTIAL_SUCCESS` / `FAILED` normalization.
The framework already provides generic contracts for **list parameter collection**, **pre-validation/canonicalization**, **transaction confirmation**, **MCP execution**, and **per-item result normalization**. Do not create a second multi-item engine inside an agent.
> **Core rule:** multi-item is a property of resolution, execution, and results. **It is not defined by the input parameter type.** A tool may receive `subject: string`, `id: string`, `items: array`, or another natural domain contract and still process multiple items.
## Main rule
**Do not implement business fan-out loops in the agent.** The agent declares the tool and parameters; the runtime owns state, confirmation, and evidence. A bulk operation should be exposed as an MCP tool that accepts a collection, or as a transactional tool backed by a domain MCP/workflow that processes the collection.
Recommended flow:
**Do not implement business fan-out in the agent.** The agent selects the intent/tool and uses the runtime. Expansion to multiple items may happen in the pre-validator, MCP tool, or domain workflow.
```text
User names N items
-> Router/Agent selects the tool
-> Runtime collects/reconciles an array/list parameter
-> optional pre-validation canonicalizes items
-> Runtime asks ONE coherent confirmation for the set
-> MCP receives the collection
-> MCP/workflow processes each item
-> MCP returns results[] with success/ok per item
-> Runtime collects the parameters declared by the tool
-> Input may be scalar or a collection
-> optional pre-validation resolves/expands/canonicalizes N items
-> Runtime requests ONE coherent confirmation for the effective set
-> MCP tool/workflow processes 1 or N items
-> Primary tool returns results[] with success/ok per item
-> Framework normalizes SUCCESS / PARTIAL_SUCCESS / FAILED
-> Final composition reports successes and failures individually
```
## 1. Declare a list parameter in `tools.yaml`
## 1. Declare the natural operation contract in `tools.yaml`
The transaction parameter reconciler accepts `type: array` and `type: list`.
The framework **does not require `array/list`** for multi-item support.
Use:
- a scalar (`subject`, `id`, `query`, etc.) when the natural interface accepts an expression that may represent one or many entities;
- `array/list` when the MCP interface is naturally batch-oriented.
### Pattern A — scalar expanded later
```yaml
tools:
cancel_products:
description: Cancels one or more customer products.
mcp_server: accounts
enabled: true
tool_type: action
confirmation_required: true
requires: [items]
cancelar_vas_avulso:
args_schema:
subject:
type: string
```
Possible input:
```text
subject = "TIM Fashion, Aya Audiobooks, Neymar Jr"
```
### Pattern B — explicit collection
```yaml
tools:
cancelar_produtos:
args_schema:
items:
type: array
label: the products
description: List of products the customer wants to cancel.
user_prompt: Which products do you want to cancel?
```
A phrase naming several products can therefore be reconciled into a logical list argument. Domain semantics and canonical name validation remain in MCP/pre-validation, not in the core.
Both patterns are valid. **Do not change an existing scalar interface to array only to enable multi-item.**
## 2. Use pre-validation for canonicalization
## 2. `tool_policies.yaml` has no special multi-item syntax
Configure `tool_policies.yaml` when the list must be resolved before confirmation:
Example:
```yaml
tool_policies:
cancel_products:
cancelar_vas_avulso:
operation_type: transactional
require_confirmation: true
requires: [items]
requires:
- subject
pre_validation:
enabled: true
tool: validate_products_for_cancellation
tool: validar_vas_subject
fail_open: false
```
A validator may return `eligible: true` and replace the raw list through `transaction_decision.resolved_arguments`:
`subject` may represent one or multiple entities.
## 3. Pre-validation may expand a scalar into multiple canonical items
```json
{
"eligible": true,
"resolved_subjects": ["A", "B", "C"],
"transaction_decision": {
"resolved_arguments": {
"subject": "A, B, C",
"items": [
{"name": "Product A", "id": "1001"},
{"name": "Product B", "id": "1002"}
{"name": "A"},
{"name": "B"},
{"name": "C"}
]
},
"target_tool": "cancel_products",
"confirmation_message": "Do you confirm cancellation of Product A and Product B?"
}
}
```
### Partial validation
The pre-validation `eligible` flag is global. **Do not return `eligible: false` only because one list item failed** when other items can still run; that would terminate the entire transaction.
For partial outcomes, the recommended pattern is:
1. return `eligible: true` when at least one item is actionable;
2. canonicalize/preserve the collection in `resolved_arguments`;
3. let the primary tool publish terminal status for **every item** in `results[]`.
If no item can be processed, `eligible: false` is appropriate.
## 3. MCP input contract
Prefer one logical MCP call containing the collection:
```json
{
"tool_name": "cancel_products",
"arguments": {
"customer_id": "123",
"items": [
{"name": "Product A", "id": "1001"},
{"name": "Product B", "id": "1002"}
]
}
}
```
Do not use the agent as an improvised loop that invokes a scalar tool N times. If the downstream backend only offers a single-item API, encapsulate fan-out in the MCP Server or domain workflow while keeping one logical tool for the agent.
## 4. Required per-item result contract
For automatic multi-item recognition, the **requested primary tool** must expose a `results` list with **two or more entries**, and every entry must contain boolean `success` or `ok`.
```json
{
"ok": true,
"result": {
"results": [
{"id": "1001", "subject": "Product A", "success": true},
{"id": "1002", "subject": "Product B", "success": false, "reason": "not_found"},
{"id": "1003", "subject": "Product C", "success": true}
]
}
}
```
Fields such as `id`, `subject`, `name`, `reason`, `error`, and `protocol` are domain-specific and optional. The structural signal required by the normalizer is per-item `success: true|false` or `ok: true|false`.
### Workflow-backed tools
For workflow-backed execution, the preferred authoritative location is:
```text
workflow.output[tool_name].results
```
This prevents an auxiliary/post-processing failure from overwriting terminal outcomes of the requested primary operation.
## 5. What the runtime adds automatically
With a valid `results[]`, the runtime derives:
```json
{
"multi_item_status": "PARTIAL_SUCCESS",
"partial_success": true,
"metadata": {
"multi_item": {
"status": "PARTIAL_SUCCESS",
"items_count": 3,
"items_succeeded_count": 2,
"items_failed_count": 1,
"primary_tool": "cancel_products"
}
}
}
```
| Situation | `multi_item_status` |
|---|---|
| all items succeeded | `SUCCESS` |
| mixed success/failure | `PARTIAL_SUCCESS` |
| all items failed | `FAILED` |
`resolved_arguments.items[]` is a useful canonical execution representation, but it does **not** require `tools.yaml` to expose `items` as its input parameter.
If a later step makes the outer wrapper `ok=false` while at least one primary item succeeded, the framework preserves audit information as `original_ok=false` and `secondary_error`, while keeping the executed item outcomes authoritative.
With `fail_open: false`, do not return global `eligible: false` merely because one item fails while other items remain actionable. Keep `eligible: true`, preserve per-item eligibility, and let the primary tool produce terminal `results[]`.
## 6. Anti-patterns
## 4. MCP input contract: one logical operation, not necessarily an explicit collection
Do not implement a business loop in the agent:
Prefer one logical MCP operation for the agent. It may:
1. receive a scalar and expand it in validator/workflow;
2. receive an explicit collection;
3. receive an expression/identifier and discover items inside the tool/workflow.
```python
for product in products:
await tool_router.call("cancel_product", {"product": product})
```
If the backend only exposes a unit API, keep fan-out inside the **MCP Server or domain workflow**, not inside the agent.
Do not return only a global decision such as:
## 5. Required per-item result contract
Automatic multi-item normalization is driven by the **primary tool result**, not by the input schema. The primary tool must expose `results` with at least two items and each item must contain boolean `success` or `ok`.
```json
{"approved": false, "error": "one item failed"}
{
"results": [
{"subject": "A", "success": true},
{"subject": "B", "success": false, "reason": "not_found"},
{"subject": "C", "success": true}
]
}
```
or a single aggregate `success=false` when the actual outcomes are mixed. These formats lose per-item terminal evidence.
## 7. Read-only multi-item calls
The same result contract can be used for bulk queries. Usually only the policy changes:
```yaml
tool_policies:
query_orders:
operation_type: read_only
require_confirmation: false
```
Returning `results[]` with `success/ok` per item ensures one unavailable item does not hide successful queries.
## 8. Idempotency and protocols
For side-effecting operations:
- use a request idempotency key and, when necessary, an item-level key;
- return protocol/operation id on the item itself;
- do not rely only on an aggregate text message;
- on retry, preserve completed items and execute only what domain policy allows.
The runtime preserves evidence; downstream idempotency remains the responsibility of the domain MCP/workflow.
## 9. Developer checklist
- [ ] The tool accepts `array/list` for a multi-item use case.
- [ ] There is no business MCP loop inside the agent class.
- [ ] Canonicalization belongs to pre-validation/MCP, not hardcoded agent logic.
- [ ] Confirmation describes the effective item set.
- [ ] The primary tool returns `results[]` with per-item `success` or `ok`.
- [ ] Partial outcome is not collapsed into a single global failure flag.
- [ ] Workflow-backed tools use `output[tool_name].results` for primary terminal evidence.
- [ ] Tests cover all-success, partial, all-failure, and later auxiliary failure.
- [ ] Final response reports both successes and failures for `PARTIAL_SUCCESS`.
## 10. Framework implementation references
For workflow-backed tools, the preferred authoritative path is:
```text
libs/agent_framework/src/agent_framework/runtime/transaction_parameters.py
- array/list coercion
libs/agent_framework/src/agent_framework/runtime/agent_runtime.py
- pre-validation and resolved_arguments
- _primary_multi_item_outcomes()
- _normalize_multi_item_tool_result()
- multi-item LLM composition instruction
tests/test_multi_item_result_normalization.py
- SUCCESS/PARTIAL_SUCCESS regressions and auxiliary-failure protection
workflow.output[tool_name].results
```
## 11. Responsibility summary
## 6. Framework normalization
| Situation | `multi_item_status` |
|---|---|
| all items succeed | `SUCCESS` |
| some succeed and some fail | `PARTIAL_SUCCESS` |
| all fail | `FAILED` |
A later auxiliary error must not erase terminal per-item evidence already produced by the primary tool.
## 7. Do not
Do not create an MCP loop in the agent, reduce mixed results to one global boolean, or redesign a working scalar contract merely to make it an array.
## 8. Checklist
- [ ] Agent selects the operation and does not implement business fan-out.
- [ ] `tools.yaml` declares the natural contract, scalar or collection.
- [ ] No special `multi_item: true` setting is required.
- [ ] `tool_policies.yaml` keeps the real domain `requires`; `subject` does not need to become `items`.
- [ ] Validator/tool/workflow expands and canonicalizes multiple entities when needed.
- [ ] Confirmation represents the effective resolved set.
- [ ] With `fail_open: false`, one invalid item does not force global `eligible: false` if other items remain actionable.
- [ ] Primary tool returns `results[]` with `success`/`ok` per item.
- [ ] Workflow prefers `output[tool_name].results` for terminal evidence.
- [ ] Partial results remain visible and are reported individually.
## 9. Responsibility summary
| Layer | Responsibility |
|---|---|
| Agent | select/declaratively use the tool; do not implement a multi-item engine |
| `tools.yaml` | declare `array/list` parameter and schema |
| `tool_policies.yaml` | confirmation and pre-validation |
| MCP pre-validator | resolve/canonicalize entities and arguments |
| MCP tool/workflow | execute the collection and return per-item outcomes |
| Framework runtime | state, confirmation, multi-item normalization, evidence preservation |
| LLM/presentation | verbalize evidence without hiding per-item success/failure |
| Agent | select intent/tool; do not implement a multi-item engine |
| `tools.yaml` | declare the natural input contract; scalar or collection |
| `tool_policies.yaml` | confirmation, `requires`, pre-validation; no special multi-item syntax |
| MCP pre-validator | resolve/canonicalize and optionally expand one parameter into N items |
| MCP tool/workflow | execute 1 or N items and return per-item results |
| Framework runtime | maintain state/confirmation, interpret `results[]`, preserve evidence, calculate aggregate status |
| LLM/presentation | report per-item outcomes without erasing successful/failed evidence |

2
agent_framework_oci/docs/developer/en/04_mcp_integration_tools_and_policies.md
View File

@@ -86,7 +86,7 @@ projeto_multi_agent_isolado/
### MCP multi-item: product, order, and resource lists
When one intent must operate on several items, **do not create an MCP loop inside the agent**. The framework supports `array/list` parameters, pre-validation with `resolved_arguments`, set-level transaction confirmation, and automatic normalization of per-item `results[]` into `SUCCESS`, `PARTIAL_SUCCESS`, or `FAILED`.
When one intent must operate on several items, **do not create an MCP loop inside the agent**. The framework supports scalar or `array/list` contracts, pre-validation with `resolved_arguments`, set-level transaction confirmation, and automatic normalization of per-item `results[]` into `SUCCESS`, `PARTIAL_SUCCESS`, or `FAILED`. Multi-item support does not depend on the input parameter type.
The complete contract, `tools.yaml` / `tool_policies.yaml` examples, MCP payloads, per-item output, workflow behavior, partial validation, and anti-patterns are documented in:

2
agent_framework_oci/docs/developer/en/INDEX_DEVELOPER_GUIDE.md
View File

@@ -27,7 +27,7 @@ If something is not working, use **Search by problem** below.
| A tool does not appear or cannot be found | `tools.yaml`, MCP catalog, discovery | [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) |
| MCP Server does not appear in the catalog | registration, manifest/discovery, MCP Gateway | [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) and [Gateways](docs/developer/en/05_agent_gateway_mcp_gateway_and_auth.md) |
| Parameters sent to the tool are wrong | schema, mapping, BusinessContext, extractor | [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) |
| I need to run one operation for multiple products/orders/items | array/list parameter, pre-validation, single confirmation, per-item outcome | [MCP Multi-item](../../MCP_MULTI_ITEM_DEVELOPER_GUIDE_en.md) and [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
| I need to run one operation for multiple products/orders/items | scalar or collection contract, pre-validation, single confirmation, per-item outcome | [MCP Multi-item](../../MCP_MULTI_ITEM_DEVELOPER_GUIDE_en.md) and [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
| A transactional operation executes without confirmation | tool policy, `require_confirmation` | [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) |
| A name search requires an overly exact match | parameter extraction/mapping and agent logic | [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) |
| I receive 401 between gateway/backend/MCP | Basic Auth, credentials per hop | [Gateways and Auth](docs/developer/en/05_agent_gateway_mcp_gateway_and_auth.md) |

2
agent_framework_oci/docs/developer/pt/04_mcp_integration_tools_and_policies.md
View File

@@ -87,7 +87,7 @@ projeto_multi_agent_isolado/
### MCP multi-item: listas de produtos, pedidos e outros recursos
Quando uma única intenção precisa operar sobre vários itens, **não crie um loop MCP dentro do agente**. O framework suporta parâmetros `array/list`, pre-validation com `resolved_arguments`, confirmação transacional do conjunto e normalização de `results[]` por item em `SUCCESS`, `PARTIAL_SUCCESS` ou `FAILED`.
Quando uma única intenção precisa operar sobre vários itens, **não crie um loop MCP dentro do agente**. O framework suporta contratos escalares ou `array/list`, pre-validation com `resolved_arguments`, confirmação transacional do conjunto e normalização de `results[]` por item em `SUCCESS`, `PARTIAL_SUCCESS` ou `FAILED`. Multi-item não depende do tipo do parâmetro de entrada.
O contrato completo, exemplos de `tools.yaml`, `tool_policies.yaml`, payload MCP, retorno por item, workflows, validação parcial e anti-patterns estão em:

2
agent_framework_oci/docs/developer/pt/INDEX_DEVELOPER_GUIDE.md
View File

@@ -28,7 +28,7 @@ Se algo não está funcionando, use **Buscar pelo problema** abaixo.
| Uma tool não aparece ou não é encontrada | `tools.yaml`, catálogo MCP, discovery | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
| MCP Server não aparece no catálogo | registration, manifest/discovery, MCP Gateway | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) e [Gateways](./05_agent_gateway_mcp_gateway_and_auth.md) |
| Parâmetros enviados à tool estão errados | schema, mapping, BusinessContext, extractor | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
| Preciso chamar a mesma operação para vários produtos/pedidos/itens | parâmetro array/list, pre-validation, confirmação única, resultado por item | [MCP Multi-item](../../MCP_MULTI_ITEM_DEVELOPER_GUIDE.md) e [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
| Preciso chamar a mesma operação para vários produtos/pedidos/itens | contrato escalar ou coleção, pre-validation, confirmação única, resultado por item | [MCP Multi-item](../../MCP_MULTI_ITEM_DEVELOPER_GUIDE.md) e [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
| Uma operação transacional executa sem confirmação | tool policy, `require_confirmation` | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
| Uma busca por nome exige correspondência exata demais | extração/mapeamento de parâmetros e lógica do agente | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
| Recebo 401 entre gateway/backend/MCP | Basic Auth, credenciais por hop | [Gateways e Auth](./05_agent_gateway_mcp_gateway_and_auth.md) |