🎯 今日核心问题
- 工具抛异常时,是让整个请求 500,还是把错误告诉模型让它自己重试?
- 模型传了
orderNo: 123(数字)而方法要 String,该宽容还是该拒绝? - 外部 HTTP 接口超时 3 秒,工具该怎么表现,才不拖垮整个 Agent 循环?
- 怎么防止模型陷入"重试死循环",同一错误刷 20 次 token?
📖 精读提纲
【一】错误的两种归属:可自愈与不可自愈
把所有失败分成两类,处理方式完全不同。可自愈错误:参数格式不对、订单号写错、缺少必填字段、查询条件太宽导致超时——这类错误模型有能力修正,正确做法是把错误作为 tool 消息返回给模型,附上人能看懂的提示("orderNo 必须是字符串且不含空格,你给的是 123"),模型下一轮通常能改对。不可自愈错误:数据库连接断了、外部服务 503、权限不足、磁盘满——模型再怎么改参数也没用,这类必须立刻中断循环并降级,返回兜底话术,同时上报监控。混淆这两类是 Agent 系统最常见的架构性缺陷:把所有错误都丢给模型,它会在无解的问题上反复尝试直到耗尽预算。
【二】超时与并发隔离
工具调用必须有独立于模型调用的超时。模型请求超时设 60s,单个工具执行必须更短,比如 3s 或 5s,否则一个慢接口会把整轮对话拖死。做法是把工具执行包在一个受控的线程池里 future.get(3, SECONDS),超时则 cancel(true) 并返回"查询超时,请稍后重试或缩小范围"。注意这是协作式中断,底层 HTTP 客户端需要配置 connect/read timeout 才能真正断开,光靠 Future 取消只会让线程继续跑、白占资源。并发上限也要设,避免模型一次发起 10 个并行工具把连接池打满。
【三】实战应用:Spring Boot 场景
在 DynamicToolRegistry.invoke 外面套一层 ToolExecutor,职责是:参数预校验(用 JSON Schema validator 校验必填与类型)→ 受控执行(线程池 + 超时)→ 异常转译(业务异常 → ToolResult.fail(code, hint))→ 重试计数(同一 (toolName, argsHash) 出现两次即判定死循环,强制中断)。业务代码里不要写 try-catch 吞异常,让 ToolExecutionException 冒到 Executor 统一处理。Controller 层不需要感知这些细节,它只看到最终的 ChatResponse。
【四】常见误区
- ❌ 用
catch (Exception e) { return "查询失败"; }——模型不知道失败原因,只能重试同样的错误。 - ❌ 把 Java 异常类名(
NullPointerException)原样返回——模型看不懂,还会照着编。 - ❌ 无限重试——必须有
maxRetries与"相同参数重复"检测。 - ❌ 超时后不中断底层请求——线程泄漏,压测时线程池会被打爆。
- ❌ 校验放在模型侧(靠 prompt 说"请传字符串")——服务端的 schema 校验才是唯一可靠防线。
💻 代码示例
一个带超时、异常转译和死循环检测的执行器:
@Component
@Slf4j
public class ToolExecutor {
private final DynamicToolRegistry registry;
private final ExecutorService pool = Executors.newFixedThreadPool(8, r -> {
Thread t = new Thread(r, "tool-exec");
t.setDaemon(true);
return t;
});
private final Semaphore permits = new Semaphore(8); // 并发闸门
private final ObjectMapper mapper;
public ToolExecutor(DynamicToolRegistry registry, ObjectMapper mapper) {
this.registry = registry;
this.mapper = mapper;
}
/** 返回给模型的内容永远是一个 ToolResult 外壳 */
public String execute(String toolName, String argsJson, CallContext ctx) {
String key = toolName + "#" + Integer.toHexString(argsJson.hashCode());
int attempts = ctx.bump(key);
if (attempts > 2) {
// 同参数重复失败 → 强制中断,防止死循环
return json(ToolResult.fail("LOOP_DETECTED",
"同一调用已重复失败 " + attempts + " 次,请停止重试并直接告知用户当前无法完成"));
}
if (!permits.tryAcquire()) {
return json(ToolResult.fail("BUSY", "工具调用并发已满,请稍后重试"));
}
Future<Object> f = pool.submit(() -> registry.invoke(toolName, argsJson));
try {
Object result = f.get(ctx.toolTimeout(), TimeUnit.MILLISECONDS);
return json(result instanceof ToolResult<?> r ? r : ToolResult.ok(result, "ok"));
} catch (TimeoutException e) {
f.cancel(true);
log.warn("tool {} timeout after {}ms", toolName, ctx.toolTimeout());
return json(ToolResult.fail("TIMEOUT",
"工具执行超过 " + ctx.toolTimeout() + "ms,请缩小查询范围后重试"));
} catch (ExecutionException e) {
return json(translate(toolName, e.getCause()));
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
return json(ToolResult.fail("INTERRUPTED", "调用被中断"));
} finally {
permits.release();
}
}
/** 异常 → 模型能理解的错误码 + 修正提示;不可自愈的直接标记 fatal */
private ToolResult<Void> translate(String tool, Throwable ex) {
if (ex instanceof ToolArgumentException a) {
return ToolResult.fail("INVALID_ARGS", "参数不合法:" + a.getMessage() + "。请检查参数类型与格式后重试");
}
if (ex instanceof UnknownToolException) {
return ToolResult.fail("UNKNOWN_TOOL", "不存在工具 " + tool + ",可用工具见工具列表");
}
if (ex instanceof DataAccessResourceFailureException) {
return ToolResult.fail("FATAL_DB_DOWN", "数据库不可用,请直接告知用户系统暂时故障");
}
if (ex instanceof WebClientResponseException w) {
int s = w.getStatusCode().value();
if (s == 404) return ToolResult.fail("NOT_FOUND", "上游资源不存在,请确认标识是否正确");
if (s >= 500) return ToolResult.fail("FATAL_UPSTREAM", "上游服务异常(" + s + "),请停止重试");
}
log.error("tool {} failed", tool, ex);
return ToolResult.fail("FATAL_INTERNAL", "工具内部错误,请直接告知用户暂时无法完成");
}
private String json(Object o) {
try { return mapper.writeValueAsString(o); }
catch (Exception e) { return "{\"ok\":false,\"code\":\"SERIALIZE_ERROR\",\"message\":\"结果序列化失败\"}"; }
}
}
/** 每次会话的重试计数,10 分钟过期 */
public class CallContext {
private final Map<String, AtomicInteger> counters = new ConcurrentHashMap<>();
private final long toolTimeout;
public CallContext(long toolTimeoutMs) { this.toolTimeout = toolTimeoutMs; }
public int bump(String key) {
return counters.computeIfAbsent(key, k -> new AtomicInteger()).incrementAndGet();
}
public long toolTimeout() { return toolTimeout; }
}
外部 HTTP 工具必须自己管超时,别指望 Future 取消能断开 socket:
@Bean
WebClient orderClient() {
HttpClient http = HttpClient.create()
.option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 1000)
.responseTimeout(Duration.ofMillis(2500))
.doOnConnected(c -> c.addHandlerLast(new ReadTimeoutHandler(3)));
return WebClient.builder().baseUrl("https://api.example.com").clientConnector(
new ReactorClientHttpConnector(http)).build();
}
@Component
@RequiredArgsConstructor
public class ShippingTools {
private final WebClient orderClient;
@Tool("查询物流轨迹,当用户问包裹到哪了、什么时候送达时调用")
public ToolResult<TraceView> getShippingTrace(@P("订单号,形如 A123") String orderNo) {
TraceView v = orderClient.get().uri("/trace/{no}", orderNo)
.retrieve().bodyToMono(TraceView.class).block();
if (v == null) return ToolResult.fail("NOT_FOUND", "暂无物流信息,可能还未发货");
return ToolResult.ok(v, "最新节点:" + v.latestNode() + " " + v.latestTime());
}
}
✏️ 今日动手
1)给你的工具集加一个 slowTool()(Thread.sleep(10000)),把超时设 2s,验证:返回 TIMEOUT、总耗时约 2s、线程池没有堆积(打印活跃线程数)。
2)构造参数错误三连:类型错(orderNo: 123)、缺必填、多余字段。逐个跑,看模型能否在返回提示后一轮修正——这就是"可自愈错误"的验证方法。
3)把同一个错误参数连续发三次,确认第二次之后返回 LOOP_DETECTED 并终止,记录模型最终给用户的话术是否合理。
🔖 明日预告
单个工具的错误处理通了,明天面对更复杂的场景:模型一次返回 3 个 tool_call,其中两个互不依赖可以并行,第三个依赖前两个的结果。怎么调度、怎么合并结果、怎么控制并发数。