🎯 今日核心问题

  1. 工具抛异常时,是让整个请求 500,还是把错误告诉模型让它自己重试?
  2. 模型传了 orderNo: 123(数字)而方法要 String,该宽容还是该拒绝?
  3. 外部 HTTP 接口超时 3 秒,工具该怎么表现,才不拖垮整个 Agent 循环?
  4. 怎么防止模型陷入"重试死循环",同一错误刷 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。

【四】常见误区

💻 代码示例

一个带超时、异常转译和死循环检测的执行器:

@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,其中两个互不依赖可以并行,第三个依赖前两个的结果。怎么调度、怎么合并结果、怎么控制并发数。