mirror of
https://github.com/hoshikawa2/agent_platform_oci.git
synced 2026-11-06 03:14:12 +00:00
bugfix: Multi-item
This commit is contained in:
363
docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE.md
Normal file
363
docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# MCP Multi-item — Guia do Desenvolvedor
|
||||
|
||||
## 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:
|
||||
|
||||
- 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 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 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.
|
||||
|
||||
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
|
||||
-> Framework normaliza SUCCESS / PARTIAL_SUCCESS / FAILED
|
||||
-> Composição final relata sucessos e falhas individualmente
|
||||
```
|
||||
|
||||
## 1. Declarar um parâmetro de lista em `tools.yaml`
|
||||
|
||||
O reconciliador transacional do framework aceita `type: array` ou `type: list`.
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
cancelar_produtos:
|
||||
description: Cancela um ou mais produtos do cliente.
|
||||
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:
|
||||
|
||||
```text
|
||||
quero cancelar TIM Fashion, Aya Audiobooks e Neymar Jr
|
||||
```
|
||||
|
||||
para um argumento lógico semelhante a:
|
||||
|
||||
```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.
|
||||
|
||||
```yaml
|
||||
tool_policies:
|
||||
cancelar_produtos:
|
||||
operation_type: transactional
|
||||
require_confirmation: true
|
||||
requires: [items]
|
||||
pre_validation:
|
||||
enabled: true
|
||||
tool: validar_produtos_cancelamento
|
||||
fail_open: false
|
||||
```
|
||||
|
||||
O pre-validator pode retornar `eligible: true` e substituir argumentos por valores canônicos em `transaction_decision.resolved_arguments`:
|
||||
|
||||
```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?"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 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`.
|
||||
|
||||
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}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### Workflow-backed tool
|
||||
|
||||
Se a tool é executada por workflow, o caminho preferencial e autoritativo é:
|
||||
|
||||
```text
|
||||
workflow.output[tool_name].results
|
||||
```
|
||||
|
||||
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",
|
||||
"partial_success": true,
|
||||
"metadata": {
|
||||
"multi_item": {
|
||||
"status": "PARTIAL_SUCCESS",
|
||||
"items_count": 3,
|
||||
"items_succeeded_count": 2,
|
||||
"items_failed_count": 1,
|
||||
"primary_tool": "cancelar_produtos"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Estados possíveis:
|
||||
|
||||
| Situação | `multi_item_status` |
|
||||
|---|---|
|
||||
| todos os itens concluíram | `SUCCESS` |
|
||||
| parte concluiu e parte falhou | `PARTIAL_SUCCESS` |
|
||||
| todos falharam | `FAILED` |
|
||||
|
||||
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:
|
||||
|
||||
```python
|
||||
# NÃO: motor multi-item paralelo dentro do agente
|
||||
for product in products:
|
||||
await tool_router.call("cancelar_produto", {"product": product})
|
||||
```
|
||||
|
||||
```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"
|
||||
}
|
||||
```
|
||||
|
||||
Esses formatos perdem a evidência terminal individual e podem fazer itens concluídos desaparecerem da composição final.
|
||||
|
||||
## 7. Exemplo completo: vários pedidos
|
||||
|
||||
### `tools.yaml`
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
cancelar_pedidos:
|
||||
description: Cancela um ou mais pedidos.
|
||||
mcp_server: retail
|
||||
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?
|
||||
```
|
||||
|
||||
### Retorno MCP
|
||||
|
||||
```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"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
O framework classificará automaticamente como `PARTIAL_SUCCESS` e fornecerá ao LLM a instrução de relatar os resultados item a item.
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 9. 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;
|
||||
- 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.
|
||||
|
||||
O framework preserva evidência; a política de idempotência do sistema de destino continua pertencendo ao MCP/workflow de domínio.
|
||||
|
||||
## 10. Checklist para o 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.
|
||||
- [ ] 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`.
|
||||
|
||||
## 11. Onde o comportamento existe no framework
|
||||
|
||||
Referências atuais:
|
||||
|
||||
```text
|
||||
libs/agent_framework/src/agent_framework/runtime/transaction_parameters.py
|
||||
- coerção de type=array/list
|
||||
|
||||
libs/agent_framework/src/agent_framework/runtime/agent_runtime.py
|
||||
- pre-validation e resolved_arguments
|
||||
- _primary_multi_item_outcomes()
|
||||
- _normalize_multi_item_tool_result()
|
||||
- instrução de composição multi-item para o LLM
|
||||
|
||||
tests/test_multi_item_result_normalization.py
|
||||
- regressões de SUCCESS/PARTIAL_SUCCESS e proteção contra falha auxiliar
|
||||
```
|
||||
|
||||
## 12. 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 |
|
||||
252
docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE_en.md
Normal file
252
docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE_en.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# MCP Multi-item — Developer Guide
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
## 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:
|
||||
|
||||
```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
|
||||
-> Framework normalizes SUCCESS / PARTIAL_SUCCESS / FAILED
|
||||
-> Final composition reports successes and failures individually
|
||||
```
|
||||
|
||||
## 1. Declare a list parameter in `tools.yaml`
|
||||
|
||||
The transaction parameter reconciler accepts `type: array` and `type: list`.
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
cancel_products:
|
||||
description: Cancels one or more customer products.
|
||||
mcp_server: accounts
|
||||
enabled: true
|
||||
tool_type: action
|
||||
confirmation_required: true
|
||||
requires: [items]
|
||||
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.
|
||||
|
||||
## 2. Use pre-validation for canonicalization
|
||||
|
||||
Configure `tool_policies.yaml` when the list must be resolved before confirmation:
|
||||
|
||||
```yaml
|
||||
tool_policies:
|
||||
cancel_products:
|
||||
operation_type: transactional
|
||||
require_confirmation: true
|
||||
requires: [items]
|
||||
pre_validation:
|
||||
enabled: true
|
||||
tool: validate_products_for_cancellation
|
||||
fail_open: false
|
||||
```
|
||||
|
||||
A validator may return `eligible: true` and replace the raw list through `transaction_decision.resolved_arguments`:
|
||||
|
||||
```json
|
||||
{
|
||||
"eligible": true,
|
||||
"transaction_decision": {
|
||||
"resolved_arguments": {
|
||||
"items": [
|
||||
{"name": "Product A", "id": "1001"},
|
||||
{"name": "Product B", "id": "1002"}
|
||||
]
|
||||
},
|
||||
"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` |
|
||||
|
||||
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.
|
||||
|
||||
## 6. Anti-patterns
|
||||
|
||||
Do not implement a business loop in the agent:
|
||||
|
||||
```python
|
||||
for product in products:
|
||||
await tool_router.call("cancel_product", {"product": product})
|
||||
```
|
||||
|
||||
Do not return only a global decision such as:
|
||||
|
||||
```json
|
||||
{"approved": false, "error": "one item failed"}
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 11. 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 |
|
||||
@@ -82,6 +82,31 @@ projeto_multi_agent_isolado/
|
||||
### Main components
|
||||
|
||||
|
||||
|
||||
|
||||
### 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`.
|
||||
|
||||
The complete contract, `tools.yaml` / `tool_policies.yaml` examples, MCP payloads, per-item output, workflow behavior, partial validation, and anti-patterns are documented in:
|
||||
|
||||
- [MCP Multi-item — Developer Guide](../../MCP_MULTI_ITEM_DEVELOPER_GUIDE_en.md)
|
||||
|
||||
Minimum structural result from the primary tool:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": {
|
||||
"results": [
|
||||
{"subject": "A", "success": true},
|
||||
{"subject": "B", "success": false, "reason": "not_found"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Every item must expose boolean `success` or `ok`. For workflow-backed tools, prefer `workflow.output[tool_name].results`. A later auxiliary failure must not erase terminal item outcomes.
|
||||
|
||||
### Simplified HTTP contract used by the project
|
||||
|
||||
```
|
||||
|
||||
@@ -27,6 +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) |
|
||||
| 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) |
|
||||
@@ -73,9 +74,9 @@ If something is not working, use **Search by problem** below.
|
||||
|
||||
### [04 — MCP, Tools, Policies, and Parameter Extraction](docs/developer/en/04_mcp_integration_tools_and_policies.md)
|
||||
|
||||
**What it is:** reference for tools, MCP Servers, mappings, policies, and parameter extraction.
|
||||
**What it is:** reference for tools, MCP Servers, mappings, policies, parameter extraction, and multi-item calls.
|
||||
|
||||
**Use when:** tool integration/execution is incorrect or needs to be created.
|
||||
**Use when:** tool integration/execution is incorrect, needs to be created, or must process item lists without parallel logic in the agent.
|
||||
|
||||
### [05 — Agent Gateway, MCP Gateway, and Authentication](docs/developer/en/05_agent_gateway_mcp_gateway_and_auth.md)
|
||||
|
||||
|
||||
@@ -83,6 +83,31 @@ projeto_multi_agent_isolado/
|
||||
### Componentes principais
|
||||
|
||||
|
||||
|
||||
|
||||
### 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`.
|
||||
|
||||
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:
|
||||
|
||||
- [MCP Multi-item — Guia do Desenvolvedor](../../MCP_MULTI_ITEM_DEVELOPER_GUIDE.md)
|
||||
|
||||
Regra estrutural mínima do retorno da tool primária:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": {
|
||||
"results": [
|
||||
{"subject": "A", "success": true},
|
||||
{"subject": "B", "success": false, "reason": "not_found"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Cada item deve expor `success` ou `ok` booleano. Para tool baseada em workflow, prefira `workflow.output[tool_name].results`. Uma falha auxiliar posterior não deve apagar resultados terminais já executados.
|
||||
|
||||
### Contrato HTTP simplificado usado no projeto
|
||||
|
||||
```
|
||||
|
||||
@@ -28,6 +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) |
|
||||
| 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) |
|
||||
@@ -74,9 +75,9 @@ Se algo não está funcionando, use **Buscar pelo problema** abaixo.
|
||||
|
||||
### [04 — MCP, Tools, Policies e Extração de Parâmetros](./04_mcp_integration_tools_and_policies.md)
|
||||
|
||||
**O que é:** referência de tools, MCP Servers, mappings, policies e parameter extraction.
|
||||
**O que é:** referência de tools, MCP Servers, mappings, policies, parameter extraction e chamadas multi-item.
|
||||
|
||||
**Use quando:** integração/execução de tool está incorreta ou precisa ser criada.
|
||||
**Use quando:** integração/execução de tool está incorreta, precisa ser criada ou deve processar listas de itens sem lógica paralela no agente.
|
||||
|
||||
### [05 — Agent Gateway, MCP Gateway e Autenticação](./05_agent_gateway_mcp_gateway_and_auth.md)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user