工具执行控制

概述

Agent 执行任务时，大模型可能在一次回复中要求调用一个或多个工具。例如，用户要求比较上海和北京的天气，模型可能同时发起两次天气查询；用户要求“创建订单后再付款”，则可能先后使用创建订单和付款工具。

工具执行控制解决的是：模型选中工具以后，这些工具怎样安全、高效地执行，以及它们返回给模型的内容应该控制在多大范围内。

工具执行控制用于解决以下问题：

问题	可能造成的影响	对应配置能力
多个独立查询逐个执行	总等待时间较长	允许安全的工具并行执行
有先后依赖的工具同时执行	后一个工具可能拿不到前一个工具的结果	强制工具按照顺序执行
并行工具中有一个失败	不清楚是终止任务，还是把错误交给模型处理	配置并行批次的失败处理方式
工具返回日志或文档过长	增加 Token 消耗，甚至超过模型上下文限制	限制工具结果的最大字符数

它控制的是“模型已经选中工具之后，Runner 应当怎样执行这些调用”。它不会决定模型应该选择哪个工具，也不负责限制整个任务最多可以调用多少次工具或决定失败后是否自动重试。这些能力分别由 Agent 指令、运行限制与预算和错误处理与重试负责。

Agents-Flex 默认按照模型返回的顺序逐个执行工具。对于只有一个工具，或者工具之间存在依赖关系的应用，通常不需要修改默认配置。只有在同一轮经常出现多个独立查询、工具结果较大，或者需要明确并行失败行为时，才需要配置本页功能。

例如：

同时查询多个城市的天气，彼此没有依赖，适合并行执行；
先创建订单再发起付款，后一步依赖订单号，应当顺序执行；
搜索工具可能返回数十万字内容，应限制结果大小或从工具端分页。

基本配置

下面的 chatModel 表示已经创建好的大模型客户端，queryTools 表示应用已经定义好的查询工具列表。

java

AgentExecutionPolicy policy = AgentExecutionPolicy.builder()
    .toolExecutionMode(AgentToolExecutionMode.PARALLEL)
    .maxParallelToolCalls(4)
    .parallelFailureStrategy(
        AgentParallelFailureStrategy.FAIL_FAST)
    .toolResultMaxCharacters(20_000)
    .externalToolResultMaxCharacters(10_000)
    .toolResultOverflowStrategy(
        AgentToolResultOverflowStrategy.FAIL)
    .build();

Agent agent = Agent.builder("research-agent")
    .instructions("根据用户要求调用已注册的查询工具，并根据真实结果回答。")
    .chatModel(chatModel)
    .tools(queryTools)
    .executionPolicy(policy) // 将工具执行策略应用到当前 Agent
    .build();

各项配置解决的问题如下：

配置	作用
`toolExecutionMode(...)`	选择多个本地工具按顺序执行还是并行执行
`maxParallelToolCalls(...)`	限制同一批工具最多同时执行多少个
`parallelFailureStrategy(...)`	决定并行执行中某个工具失败后如何处理
`toolResultMaxCharacters(...)`	限制本地 Java 工具返回给模型的内容大小
`externalToolResultMaxCharacters(...)`	限制浏览器、移动端等外部工具返回给模型的内容大小
`toolResultOverflowStrategy(...)`	决定结果超限时直接报错还是截断内容
`executionPolicy(policy)`	将以上设置应用到当前 Agent；只创建 `policy` 不会自动生效

顺序与并行执行

toolExecutionMode(...) 支持两种模式：

模式	行为	适用场景
`SEQUENTIAL`	按模型返回顺序逐个执行；默认模式	工具之间存在依赖，或工具会修改数据
`PARALLEL`	多个本地工具同时执行	彼此独立的查询和计算

即使采用并行模式，工具结果仍会按照模型原始调用顺序写入消息历史，不会因为完成速度不同而改变顺序。

只有同一批次中彼此独立的本地工具适合并行。需要人工审批、用户输入或外部执行器的工具仍会按照可恢复的顺序处理。

并发数量

maxParallelToolCalls(...) 设置一批工具最多可以同时启动多少个，默认值为 8。

如果模型一次返回的工具数量超过该上限，Runner 会回退为顺序执行。该配置限制单个 AgentTurn 的工具批次，不代替应用级线程池、模型限流或第三方接口限流。

并行失败处理

parallelFailureStrategy(...) 决定并行批次中某个工具失败后的处理方式：

策略	行为
`FAIL_FAST`	将失败交给统一的失败或重试流程；这是默认值
`RETURN_ERRORS_TO_MODEL`	将每个失败转换为工具结果，让模型决定下一步

并行调用无法回滚已经完成的工具。即使其中一个工具失败，其他工具也可能已经产生结果或外部影响。因此，并行模式应优先用于只读工具；写入类工具必须具备防重复执行能力。

工具通用的错误处理方式请查看错误处理与重试。

工具结果大小

工具返回内容会进入模型上下文。日志、文档或查询结果过大时，不仅增加 Token 消耗，还可能超过模型上下文限制。

配置	作用
`toolResultMaxCharacters(...)`	限制本地工具结果的字符数
`externalToolResultMaxCharacters(...)`	限制外部执行器返回结果的字符数
`toolResultOverflowStrategy(...)`	决定结果超过限制时如何处理

字符上限为 0 表示不限制。

结果超限支持两种策略：

策略	行为
`FAIL`	将超限作为错误处理；这是默认值
`TRUNCATE`	截取允许长度，并在结果中加入明确的截断标记

只有确认模型可以在不完整结果上安全工作时，才应使用 TRUNCATE。订单明细、计算结果等要求完整性的内容更适合使用 FAIL，然后调整工具的分页或摘要设计。

工具返回设计

结果大小限制是最后一道保护。更推荐从工具接口本身控制数据规模：

查询工具提供分页、筛选条件和条数上限；
搜索工具先返回摘要和关键条目，再通过详情工具按 ID 查询；
日志或报表保存到文件存储，工具只返回文件 ID 或受控链接；
数据被截断时返回 hasMore、nextCursor 等明确字段。

配置建议

默认使用顺序执行，确认工具彼此独立后再开启并行。
退款、扣款、发货等写入工具不应随意并行。
并发上限还要考虑数据库连接池和第三方接口限流。
优先通过分页和摘要控制结果规模，再设置字符上限兜底。
监控工具耗时、失败率、结果大小和截断次数。

工具执行控制 ​

概述 ​

基本配置 ​

顺序与并行执行 ​

并发数量 ​

并行失败处理 ​

工具结果大小 ​

工具返回设计 ​

配置建议 ​

相关文档 ​