langchain4j-tool-function-calling-patterns

LangChain4j 工具和函数调用模式

介绍在 LangChain4j 应用中将方法标注为工具、配置工具执行器、向 AI 服务注册工具、验证参数以及处理工具执行错误的模式。

概览

LangChain4j 使用 @Tool 注解，将 Java 方法公开为可供 AI Agent 调用的函数。AiServices 构建器会将工具注册到聊天模型，使大模型能够执行文本生成以外的操作：数据库查询、API 调用、计算以及业务系统集成。参数使用 @P 提供说明，引导大模型调用。

适用场景

• 构建可调用外部工具的 AI Agent（天气、股票、数据库查询）
• 为大模型工具使用定义函数规范（@Tool、@P 注解）
• 使用 AiServices.builder().tools() 注册和管理工具集
• 处理工具执行错误、超时以及虚构的工具名称
• 实现通过 @ToolMemoryId 注入用户状态的上下文感知工具
• 为大型或有条件的工具集配置动态工具提供程序

说明

1. 使用 @Tool 标注方法

定义一个工具类，并使用 @Tool 标注方法。将说明作为第一个参数。使用 @P 为每个参数添加说明。

public class WeatherTools {
    private final WeatherService weatherService;

    public WeatherTools(WeatherService weatherService) {
        this.weatherService = weatherService;
    }

    @Tool("Get current weather for a city")
    public String getWeather(
            @P("City name") String city,
            @P("Temperature unit: celsius or fahrenheit") String unit) {
        return weatherService.getWeather(city, unit);
    }
}

验证：创建一个实例，并确认该类加载时没有错误。

2. 向 AiServices 注册工具

使用 AiServices.builder() 将工具实例注册到聊天模型。

MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new Calculator(), new WeatherTools(weatherService))
    .build();

验证：调用 assistant.chat("What is 2 + 2?")，并确认大模型响应时没有抛出异常。

3. 端到端测试工具调用

发送一个会触发工具使用的提示词，并验证工具已执行，且其结果已纳入响应。

String response = assistant.chat("What is the weather in Rome?");
System.out.println(response);

验证：检查日志中的工具调用，并确认响应使用了工具输出。

4. 处理工具执行错误

添加错误处理程序，以妥善处理故障，同时不暴露堆栈跟踪。

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new ExternalServiceTools())
    .toolExecutionErrorHandler((request, exception) -> {
        logger.error("Tool '{}' failed: {}", request.name(), exception.getMessage());
        return "An error occurred while processing your request";
    })
    .hallucinatedToolNameStrategy(request ->
        ToolExecutionResultMessage.from(request,
            "Error: tool '" + request.name() + "' does not exist"))
    .toolArgumentsErrorHandler((error, context) ->
        ToolErrorHandlerResult.text("Invalid arguments: " + error.getMessage()))
    .build();

验证：触发错误条件，并确认大模型收到安全的错误消息。

5. 优化性能和扩展能力

启用并发工具执行，并为长时间运行的工具设置超时。

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new DbTools(), new HttpTools())
    .executeToolsConcurrently(Executors.newFixedThreadPool(5))
    .toolExecutionTimeout(Duration.ofSeconds(30))
    .build();

验证：运行并发请求，并确认没有线程争用或死锁。

示例

带完整类定义的计算器工具

public class Calculator {
    @Tool("Perform basic arithmetic")
    public double calculate(
            @P("Expression like 2+2 or 10*5") String expression) {
        // Parse and evaluate expression
        return eval(expression);
    }
}

Assistant assistant = AiServices.builder(Assistant.class)
    .chatModel(ChatModel.builder()
        .apiKey(System.getenv("API_KEY"))
        .model("gpt-4o")
        .build())
    .tools(new Calculator())
    .build();

立即返回工具（不等待大模型响应）

@Tool(value = "Send email notification", returnBehavior = ReturnBehavior.IMMEDIATELY)
public void sendEmail(@P("Recipient email address") String to,
                     @P("Email subject") String subject,
                     @P("Email body") String body) {
    emailService.send(to, subject, body);
}

动态工具提供程序

ToolProvider provider = request -> {
    if (request.userContext().contains("admin")) {
        return List.of(new AdminTools());
    }
    return List.of(new UserTools());
};

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .toolProvider(provider)
    .build();

最佳实践

• 使用描述性 @Tool 名称：使用带有明确范围的祈使动词（“Get”“Send”“Calculate”）
• 提供精确的 @P 说明：包括格式、约束和有效值；说明模糊会导致大模型调用错误
• 安全处理错误：切勿暴露堆栈跟踪；返回便于用户理解的错误字符串
• 配置超时：对外部服务调用始终设置 .toolExecutionTimeout()
• 并发执行：工具之间相互独立时，启用 .executeToolsConcurrently()
• 输入验证：在工具方法内部验证参数；返回描述清晰的错误
• 权限检查：在工具内部执行授权检查，而不是在 AI 服务层执行
• 审计日志：记录工具名称、参数和执行结果，以便调试并满足合规要求

有关弹性处理模式，请参阅 references/error-handling.md；有关参数和返回类型的详细信息，请参阅 references/core-patterns.md。

快速参考

注解 / API	用途
@Tool	将方法标记为可调用的工具
@P	为大模型描述工具参数
@ToolMemoryId	将对话 / 用户 ID 注入工具
AiServices.builder()	创建已注册工具的 AI 服务
ReturnBehavior.IMMEDIATELY	无需等待大模型响应即可执行工具
ToolProvider	根据上下文动态提供工具
executeToolsConcurrently()	并行运行独立的工具调用
toolExecutionTimeout()	设置单次工具调用的超时时间

限制与警告

• 敏感数据：切勿在 @Tool 或 @P 描述中传入 API 密钥、密码或凭据
• 副作用：会修改数据的工具应在描述中发出警告；AI 模型可能会多次调用它们
• 工具集过大：工具过多会使大模型困惑——使用 ToolProvider 进行条件注册
• 阻塞操作：未配置超时时，工具不应执行耗时较长的同步 I/O 操作
• 堆栈跟踪泄露：始终通过错误处理程序处理异常，并返回安全字符串
• 参数精确性：模糊的 @P 描述会直接导致错误的工具调用——请明确说明格式和限制
• 并发安全：使用 executeToolsConcurrently() 时，确保工具类无状态或线程安全

相关技能

• langchain4j-ai-services-patterns — 高级 AI 服务配置
• langchain4j-rag-implementation-patterns — 集成工具的 RAG 检索
• langchain4j-spring-boot-integration — 在 Spring Boot 应用程序中注册工具

参考资料

• references/setup-configuration.md — Maven 配置、聊天模型配置、首次注册工具
• references/core-patterns.md — 基本工具定义、复杂参数、返回类型
• references/advanced-features.md — 记忆上下文、动态工具提供器、流式传输、立即返回
• references/error-handling.md — 错误处理程序、重试逻辑、监控
• references/integration-examples.md — 数据库、REST API 和上下文感知工具示例