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

bugfix: Multi-item

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-09-18 23:12:01 -03:00
parent 6eee4514e8
commit 3ebdaacabc
217 changed files with 2583 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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
```

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

@@ -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)

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

@@ -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
```

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

@@ -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)