LangChain4j全集-09-Tool-Error Handling

Error Handling#error-handling这里的Error Handling指的是当大模型调用 Tool 时如果 Tool 执行出错了LangChain4j 应该怎么处理这个错误。因为 Tool 本质上就是你的 Java 方法所以它可能会出现各种异常参数为空 参数格式不对 订单不存在 用户无权限 数据库异常 第三方接口超时 空指针 业务状态不允许操作Error Handling就是告诉你Tool 出错时不要让整个 AI 调用莫名其妙失败而是要把错误处理成模型能理解、用户能接受、系统可控的结果。1. 为什么 Tool 需要错误处理比如你有一个查询订单的 ToolTool(根据订单号查询订单状态)publicStringgetOrderStatus(P(订单号)StringorderId){returnorderService.getStatus(orderId);}用户问帮我查一下订单10001正常情况下没问题。但如果出现这些情况呢orderId 为空 orderId 格式不对 订单不存在 数据库连接失败 orderService 抛异常如果你不处理可能会导致AI Service 方法直接抛异常 用户看到 500 错误 模型无法继续回答 日志里一堆异常所以需要 Error Handling。2. Tool 出错时有两种处理思路LangChain4j 里的 Tool 错误处理大体可以分成两层1. Tool 方法内部自己处理 2. 配置全局 ToolExecutionExceptionHandler3. 方式一Tool 方法内部自己处理这是最推荐、最基础的方式。你在 Tool 方法里自己判断参数、业务状态然后返回模型能理解的错误信息。例如ComponentpublicclassOrderTools{privatefinalOrderServiceorderService;publicOrderTools(OrderServiceorderService){this.orderServiceorderService;}Tool(根据订单号查询订单状态)publicStringgetOrderStatus(P(订单号例如 10001)StringorderId){if(orderIdnull||orderId.isBlank()){return订单号不能为空请让用户提供订单号。;}if(!orderId.matches(\\d)){return订单号格式不正确订单号应该是数字。;}OrderorderorderService.findByOrderId(orderId);if(ordernull){return没有找到订单orderId请确认订单号是否正确。;}return 订单号%s 当前状态%s 预计送达%s .formatted(order.getOrderId(),order.getStatus(),order.getEstimatedDeliveryTime());}}这种方式的好处是错误信息可控 模型能理解 用户体验好 不会轻易抛 5004. 为什么建议 Tool 自己先处理业务错误因为很多错误其实不是“系统异常”而是“业务结果”。比如订单不存在 订单已取消 余额不足 库存不足 当前用户无权限 参数缺失这些最好不要直接抛异常给 LangChain4j而是返回清楚的业务信息。比如不推荐thrownewRuntimeException(Order not found);更推荐return没有找到该订单请确认订单号是否正确。;因为 Tool 的返回值会交给大模型大模型可以继续组织回答没有查到订单 10001请你确认一下订单号是否正确。5. 方式二配置 ToolExecutionExceptionHandler如果 Tool 方法里真的抛异常了可以通过ToolExecutionExceptionHandler统一处理。它的作用是捕获 Tool 执行过程中抛出的异常然后返回一个字符串作为 Tool 执行结果。大概配置方式是ConfigurationpublicclassAiConfig{BeanpublicOrderAssistantorderAssistant(ChatLanguageModelchatLanguageModel,OrderToolsorderTools){returnAiServices.builder(OrderAssistant.class).chatLanguageModel(chatLanguageModel).tools(orderTools).toolExecutionExceptionHandler((exception,context)-{return工具执行失败请稍后再试。;}).build();}}不同 LangChain4j 版本里lambda 参数可能略有差异有的版本可能是.toolExecutionExceptionHandler(exception-{return工具执行失败请稍后再试。;})或者带上 tool request/context 信息。但核心思想一样Tool 抛异常 ↓ ToolExecutionExceptionHandler 捕获 ↓ 返回一个错误信息字符串 ↓ 这个字符串作为 Tool 执行结果交给模型6. ToolExecutionExceptionHandler 的作用流程假设 Tool 是这样的Tool(根据订单号查询订单状态)publicStringgetOrderStatus(StringorderId){thrownewRuntimeException(数据库连接失败);}用户问查一下订单10001流程可能是1. 大模型决定调用 getOrderStatus 2. LangChain4j 执行 Tool 3. Tool 抛异常 4. ToolExecutionExceptionHandler 捕获异常 5. Handler 返回“系统暂时无法查询订单请稍后再试。” 6. 这个结果交给模型 7. 模型回答用户 抱歉当前系统暂时无法查询订单请稍后再试。7. 一个更真实的异常处理配置你可以根据不同异常类型返回不同信息。ConfigurationpublicclassAiConfig{BeanpublicOrderAssistantorderAssistant(ChatLanguageModelchatLanguageModel,OrderToolsorderTools){returnAiServices.builder(OrderAssistant.class).chatLanguageModel(chatLanguageModel).tools(orderTools).toolExecutionExceptionHandler((exception,context)-{Throwablecauseexception.getCause();if(causeinstanceofIllegalArgumentException){return参数不合法请检查后重新提供。;}if(causeinstanceofAccessDeniedException){return当前用户没有权限执行该操作。;}if(causeinstanceofOrderNotFoundException){return没有找到对应订单请确认订单号是否正确。;}return系统暂时无法完成该操作请稍后再试。;}).build();}}如果你当前版本的 handler 只有一个参数可以写成类似.toolExecutionExceptionHandler(exception-{Throwablecauseexception.getCause();if(causeinstanceofIllegalArgumentException){return参数不合法请检查后重新提供。;}return工具执行失败请稍后再试。;})8. Error Handling 返回的字符串会去哪这点很重要。如果你使用的是普通 Tool 调用模式Handler 返回的字符串一般会作为 Tool 执行结果交给大模型。比如 Handler 返回没有找到订单请确认订单号是否正确。然后大模型可能最终回答我没有查到这个订单请你确认一下订单号是否正确。也就是说异常信息 → Handler 转成可理解文本 → 交给模型 → 模型回复用户9. 如果是立即返回 Tool 呢你前面问过returnBehavior IMMEDIATE。如果 Tool 是立即返回类型Tool(value生成支付链接,returnBehaviorIMMEDIATE)publicStringcreatePaymentUrl(StringorderId){...}或者 ToolProvider 中.returnBehavior(IMMEDIATE)那么 Tool 执行失败时Handler 返回的错误信息可能会直接作为最终结果返回。所以立即返回类型的 Tool错误信息更要写得适合直接给用户看。例如return生成支付链接失败请稍后再试。;不要返回returnNullPointerException at PaymentService.java:35;10. ToolProvider 里怎么处理 Error Handling如果你使用ToolProvider手动写ToolExecutor有两种方式。10.1 在 ToolExecutor 里自己 try-catch这是最直接的方式。privateToolExecutorcreatePaymentUrlExecutor(){return(request,memoryId)-{try{JsonNodejsonobjectMapper.readTree(request.arguments());StringorderIdjson.get(orderId).asText();if(orderIdnull||orderId.isBlank()){return订单号不能为空。;}StringuserIdString.valueOf(memoryId);if(!paymentService.canPay(userId,orderId)){return你无权支付该订单。;}returnpaymentService.createPaymentUrl(userId,orderId);}catch(Exceptione){return生成支付链接失败请稍后再试。;}};}这种写法适合你想对某个 Tool 单独处理异常。10.2 抛出去让全局 ToolExecutionExceptionHandler 处理也可以不 catch让异常往外抛privateToolExecutorcreatePaymentUrlExecutor(){return(request,memoryId)-{JsonNodejsonobjectMapper.readTree(request.arguments());StringorderIdjson.get(orderId).asText();StringuserIdString.valueOf(memoryId);returnpaymentService.createPaymentUrl(userId,orderId);};}然后在AiServices.builder里统一处理.toolExecutionExceptionHandler((exception,context)-{return工具执行失败请稍后再试。;})11. 实战建议业务异常自己处理系统异常统一处理推荐你按这个原则来业务可预期错误Tool 内部处理并返回 系统不可预期异常交给 ToolExecutionExceptionHandler 统一兜底例如Tool 内处理订单不存在 订单号为空 用户无权限 订单状态不允许取消 余额不足 库存不足全局 Handler 处理数据库连接失败 第三方接口超时 空指针 JSON 解析异常 未知 RuntimeException12. 完整示例Spring Boot 查询订单12.1 AssistantpublicinterfaceOrderAssistant{Stringchat(Stringmessage);}12.2 ToolComponentpublicclassOrderTools{privatefinalOrderServiceorderService;publicOrderTools(OrderServiceorderService){this.orderServiceorderService;}Tool(根据订单号查询订单状态)publicStringgetOrderStatus(P(订单号例如 10001)StringorderId){if(orderIdnull||orderId.isBlank()){return订单号不能为空请让用户提供订单号。;}if(!orderId.matches(\\d)){return订单号格式不正确请提供纯数字订单号。;}OrderorderorderService.findByOrderId(orderId);if(ordernull){return没有找到订单orderId;}return 订单号%s 状态%s 预计送达%s .formatted(order.getOrderId(),order.getStatus(),order.getEstimatedDeliveryTime());}Tool(取消订单)publicStringcancelOrder(P(订单号)StringorderId){if(orderIdnull||orderId.isBlank()){return订单号不能为空。;}OrderorderorderService.findByOrderId(orderId);if(ordernull){return订单不存在。;}if(!order.canCancel()){return该订单当前状态不允许取消。;}orderService.cancel(orderId);return订单 orderId 已取消。;}}12.3 配置全局异常处理ConfigurationpublicclassAiConfig{BeanpublicOrderAssistantorderAssistant(ChatLanguageModelchatLanguageModel,OrderToolsorderTools){returnAiServices.builder(OrderAssistant.class).chatLanguageModel(chatLanguageModel).tools(orderTools).toolExecutionExceptionHandler((exception,context)-{// 这里建议记录完整日志// log.error(Tool execution failed, exception);Throwablecauseexception.getCause();if(causeinstanceofTimeoutException){return系统查询超时请稍后再试。;}if(causeinstanceofAccessDeniedException){return当前用户没有权限执行该操作。;}return系统暂时无法完成该操作请稍后再试。;}).build();}}13. 不要把异常堆栈直接返回给用户不推荐.toolExecutionExceptionHandler((exception,context)-{returnexception.getMessage();})因为异常信息里可能有数据库表名 SQL 服务器路径 内部类名 第三方接口地址 token 用户隐私信息 堆栈信息比如com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure这种东西不应该暴露给用户也不应该直接交给模型。推荐return系统暂时无法完成该操作请稍后再试。;同时你在服务端日志里记录详细异常log.error(Tool execution failed,exception);14. 参数错误也算 Error Handling大模型传参不一定稳定。比如 Tool 需要{orderId:10001}但模型可能传{orderId:订单10001}或者{orderId:}甚至参数缺失。所以每个 Tool 最好都做参数校验if(orderIdnull||orderId.isBlank()){return订单号不能为空请让用户提供订单号。;}不要因为参数不对就直接空指针。15. 高风险 Tool 更要严格处理错误比如这些 Tool退款 取消订单 转账 删除数据 冻结账户 发送短信 修改权限错误处理不能随便。例如退款 ToolTool(给订单发起退款)publicStringrefund(ToolMemoryIdStringuserId,P(订单号)StringorderId,P(退款原因)Stringreason){if(!permissionService.canRefund(userId)){return当前用户没有退款权限。;}if(orderIdnull||orderId.isBlank()){return订单号不能为空。;}if(reasonnull||reason.isBlank()){return退款原因不能为空。;}RefundResultresultrefundService.refund(orderId,reason);if(!result.success()){return退款失败原因result.message();}return退款已提交退款单号result.refundNo();}不要让异常随便抛出去更不要返回内部错误。16. Error Handling 和 Accessing Executed Tools 可以配合你前面学过Accessing Executed Tools。如果 Tool 出错了你可以通过工具执行记录看到调用了哪个 Tool 传了什么参数 返回了什么错误结果比如ResultStringresultassistant.chat(帮我查订单abc);result.toolExecutions().forEach(toolExecution-{System.out.println(toolExecution.request().name());System.out.println(toolExecution.request().arguments());System.out.println(toolExecution.result());});可能输出getOrderStatus {orderId:abc} 订单号格式不正确请提供纯数字订单号。这对调试非常有用。17. Error Handling 和 ToolProvider 的关系如果你用ToolProviderError Handling 也一样重要。区别只是使用方式错误处理位置Tool注解Tool 方法内部处理或全局 ToolExecutionExceptionHandlerToolProviderToolExecutor 内部处理或全局 ToolExecutionExceptionHandler简单说Tool 方式错误可能出现在 Java 方法里 ToolProvider 方式错误可能出现在 ToolExecutor 里但本质一样都是 Tool 执行失败。18. 最佳实践总结错误类型推荐处理方式参数为空Tool 内部返回友好提示参数格式错误Tool 内部返回格式说明业务数据不存在Tool 内部返回业务提示用户无权限Tool 内部返回无权限提示并记录日志业务状态不允许Tool 内部返回原因第三方接口失败Tool 内部或全局 Handler 返回稍后再试数据库异常全局 Handler 兜底日志记录未知异常全局 Handler 兜底隐藏技术细节19. 一句话总结Error Handling的作用就是当大模型调用 Tool 时如果 Tool 参数错误、业务失败或代码抛异常你可以把这些错误处理成可控、友好、安全的结果而不是让 AI 调用直接崩掉。实际使用建议1. Tool 内部处理可预期业务错误 2. AiServices.builder 配置 toolExecutionExceptionHandler 兜底未知异常 3. 不要把技术异常、堆栈、SQL、token 暴露给模型或用户 4. 高风险 Tool 必须做参数校验、权限校验、审计日志