Back to Details

langchain4j-tool-function-calling-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LangChain4j Tool & Function Calling Patterns

LangChain4j 工具与函数调用模式

Define tools and enable AI agents to interact with external systems, APIs, and services using LangChain4j's annotation-based and programmatic tool system.
使用LangChain4j基于注解和程序化的工具系统，定义工具并让AI Agent与外部系统、API及服务进行交互。

When to Use This Skill

何时使用该技能

Use this skill when:
  • Building AI applications that need to interact with external APIs and services
  • Creating AI assistants that can perform actions beyond text generation
  • Implementing AI systems that need access to real-time data (weather, stocks, etc.)
  • Building multi-agent systems where agents can use specialized tools
  • Creating AI applications with database read/write capabilities
  • Implementing AI systems that need to integrate with existing business systems
  • Building context-aware AI applications where tool availability depends on user state
  • Developing production AI applications that require robust error handling and monitoring
在以下场景中使用该技能：
  • 构建需要与外部API和服务交互的AI应用
  • 创建除文本生成外还能执行操作的AI助手
  • 实现需要访问实时数据（天气、股票等）的AI系统
  • 构建Agent可使用专用工具的多智能体系统
  • 创建具备数据库读写能力的AI应用
  • 实现需要与现有业务系统集成的AI系统
  • 构建工具可用性取决于用户状态的上下文感知型AI应用
  • 开发需要强大错误处理和监控能力的生产级AI应用

Setup and Configuration

设置与配置

Basic Tool Registration

基础工具注册

java
// Define tools using @Tool annotation
public class CalculatorTools {
    @Tool("Add two numbers")
    public double add(double a, double b) {
        return a + b;
    }
}

// Register with AiServices builder
interface MathAssistant {
    String ask(String question);
}

MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new CalculatorTools())
    .build();
java
// Define tools using @Tool annotation
public class CalculatorTools {
    @Tool("Add two numbers")
    public double add(double a, double b) {
        return a + b;
    }
}

// Register with AiServices builder
interface MathAssistant {
    String ask(String question);
}

MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new CalculatorTools())
    .build();

Builder Configuration Options

构建器配置选项

java
AiServices.builder(AssistantInterface.class)

    // Static tool registration
    .tools(new Calculator(), new WeatherService())

    // Dynamic tool provider
    .toolProvider(new DynamicToolProvider())

    // Concurrent execution
    .executeToolsConcurrently()

    // Error handling
    .toolExecutionErrorHandler((request, exception) -> {
        return "Error: " + exception.getMessage();
    })

    // Memory for context
    .chatMemoryProvider(userId -> MessageWindowChatMemory.withMaxMessages(20))

    .build();
java
AiServices.builder(AssistantInterface.class)

    // Static tool registration
    .tools(new Calculator(), new WeatherService())

    // Dynamic tool provider
    .toolProvider(new DynamicToolProvider())

    // Concurrent execution
    .executeToolsConcurrently()

    // Error handling
    .toolExecutionErrorHandler((request, exception) -> {
        return "Error: " + exception.getMessage();
    })

    // Memory for context
    .chatMemoryProvider(userId -> MessageWindowChatMemory.withMaxMessages(20))

    .build();

Core Patterns

核心模式

Basic Tool Definition

基础工具定义

Use 
@Tool
annotation to define methods as executable tools:
java
public class BasicTools {

    @Tool("Add two numbers")
    public int add(@P("first number") int a, @P("second number") int b) {
        return a + b;
    }

    @Tool("Get greeting")
    public String greet(@P("name to greet") String name) {
        return "Hello, " + name + "!";
    }
}
使用
@Tool
注解将方法定义为可执行工具：
java
public class BasicTools {

    @Tool("Add two numbers")
    public int add(@P("first number") int a, @P("second number") int b) {
        return a + b;
    }

    @Tool("Get greeting")
    public String greet(@P("name to greet") String name) {
        return "Hello, " + name + "!";
    }
}

Parameter Descriptions and Validation

参数描述与验证

Provide clear parameter descriptions using 
@P
annotation:
java
public class WeatherService {

    @Tool("Get current weather conditions")
    public String getCurrentWeather(
        @P("City name or coordinates") String location,
        @P("Temperature unit (celsius, fahrenheit)", required = false) String unit) {

        // Implementation with validation
        if (location == null || location.trim().isEmpty()) {
            return "Location is required";
        }

        return weatherClient.getCurrentWeather(location, unit);
    }
}
使用
@P
注解提供清晰的参数描述：
java
public class WeatherService {

    @Tool("Get current weather conditions")
    public String getCurrentWeather(
        @P("City name or coordinates") String location,
        @P("Temperature unit (celsius, fahrenheit)", required = false) String unit) {

        // Implementation with validation
        if (location == null || location.trim().isEmpty()) {
            return "Location is required";
        }

        return weatherClient.getCurrentWeather(location, unit);
    }
}

Complex Parameter Types

复杂参数类型

Use Java records and descriptions for complex objects:
java
public class OrderService {

    @Description("Customer order information")
    public record OrderRequest(
        @Description("Customer ID") String customerId,
        @Description("List of items") List<OrderItem> items,
        @JsonProperty(required = false) @Description("Delivery instructions") String instructions
    ) {}

    @Tool("Create customer order")
    public String createOrder(OrderRequest order) {
        return orderService.processOrder(order);
    }
}
使用Java记录（record）和描述信息处理复杂对象：
java
public class OrderService {

    @Description("Customer order information")
    public record OrderRequest(
        @Description("Customer ID") String customerId,
        @Description("List of items") List<OrderItem> items,
        @JsonProperty(required = false) @Description("Delivery instructions") String instructions
    ) {}

    @Tool("Create customer order")
    public String createOrder(OrderRequest order) {
        return orderService.processOrder(order);
    }
}

Advanced Features

高级功能

Memory Context Integration

内存上下文集成

Access user context using 
@ToolMemoryId
:
java
public class PersonalizedTools {

    @Tool("Get user preferences")
    public String getPreferences(
        @ToolMemoryId String userId,
        @P("Preference category") String category) {

        return preferenceService.getPreferences(userId, category);
    }
}
使用
@ToolMemoryId
访问用户上下文：
java
public class PersonalizedTools {

    @Tool("Get user preferences")
    public String getPreferences(
        @ToolMemoryId String userId,
        @P("Preference category") String category) {

        return preferenceService.getPreferences(userId, category);
    }
}

Dynamic Tool Provisioning

动态工具提供

Create tools that change based on context:
java
public class ContextAwareToolProvider implements ToolProvider {

    @Override
    public ToolProviderResult provideTools(ToolProviderRequest request) {
        String message = request.userMessage().singleText().toLowerCase();
        var builder = ToolProviderResult.builder();

        if (message.contains("weather")) {
            builder.add(weatherToolSpec, weatherExecutor);
        }

        if (message.contains("calculate")) {
            builder.add(calcToolSpec, calcExecutor);
        }

        return builder.build();
    }
}
创建可根据上下文变化的工具：
java
public class ContextAwareToolProvider implements ToolProvider {

    @Override
    public ToolProviderResult provideTools(ToolProviderRequest request) {
        String message = request.userMessage().singleText().toLowerCase();
        var builder = ToolProviderResult.builder();

        if (message.contains("weather")) {
            builder.add(weatherToolSpec, weatherExecutor);
        }

        if (message.contains("calculate")) {
            builder.add(calcToolSpec, calcExecutor);
        }

        return builder.build();
    }
}

Immediate Return Tools

即时返回工具

Return results immediately without full AI response:
java
public class QuickTools {

    @Tool(value = "Get current time", returnBehavior = ReturnBehavior.IMMEDIATE)
    public String getCurrentTime() {
        return LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    }
}
无需完整AI响应，直接返回结果：
java
public class QuickTools {

    @Tool(value = "Get current time", returnBehavior = ReturnBehavior.IMMEDIATE)
    public String getCurrentTime() {
        return LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    }
}

Error Handling

错误处理

Tool Error Handling

工具错误处理

Handle tool execution errors gracefully:
java
AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new ExternalServiceTools())
    .toolExecutionErrorHandler((request, exception) -> {
        if (exception instanceof ApiException) {
            return "Service temporarily unavailable: " + exception.getMessage();
        }
        return "An error occurred while processing your request";
    })
    .build();
优雅处理工具执行错误：
java
AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new ExternalServiceTools())
    .toolExecutionErrorHandler((request, exception) -> {
        if (exception instanceof ApiException) {
            return "Service temporarily unavailable: " + exception.getMessage();
        }
        return "An error occurred while processing your request";
    })
    .build();

Resilience Patterns

弹性模式

Implement circuit breakers and retries:
java
public class ResilientService {

    private final CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("external-api");

    @Tool("Get external data")
    public String getExternalData(@P("Data identifier") String id) {
        return circuitBreaker.executeSupplier(() -> {
            return externalApi.getData(id);
        });
    }
}
实现断路器与重试机制：
java
public class ResilientService {

    private final CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("external-api");

    @Tool("Get external data")
    public String getExternalData(@P("Data identifier") String id) {
        return circuitBreaker.executeSupplier(() -> {
            return externalApi.getData(id);
        });
    }
}

Integration Examples

集成示例

Multi-Domain Tool Service

多领域工具服务

java
@Service
public class MultiDomainToolService {

    public String processRequest(String userId, String request, String domain) {
        String contextualRequest = String.format("[Domain: %s] %s", domain, request);

        Result<String> result = assistant.chat(userId, contextualRequest);

        // Log tool usage
        result.toolExecutions().forEach(execution ->
            analyticsService.recordToolUsage(userId, domain, execution.request().name()));

        return result.content();
    }
}
java
@Service
public class MultiDomainToolService {

    public String processRequest(String userId, String request, String domain) {
        String contextualRequest = String.format("[Domain: %s] %s", domain, request);

        Result<String> result = assistant.chat(userId, contextualRequest);

        // Log tool usage
        result.toolExecutions().forEach(execution ->
            analyticsService.recordToolUsage(userId, domain, execution.request().name()));

        return result.content();
    }
}

Streaming with Tool Execution

流式处理与工具执行

java
interface StreamingAssistant {
    TokenStream chat(String message);
}

StreamingAssistant assistant = AiServices.builder(StreamingAssistant.class)
    .streamingChatModel(streamingChatModel)
    .tools(new Tools())
    .build();

TokenStream stream = assistant.chat("What's the weather and calculate 15*8?");

stream
    .onToolExecuted(execution ->
        System.out.println("Executed: " + execution.request().name()))
    .onPartialResponse(System.out::print)
    .onComplete(response -> System.out.println("Complete!"))
    .start();
java
interface StreamingAssistant {
    TokenStream chat(String message);
}

StreamingAssistant assistant = AiServices.builder(StreamingAssistant.class)
    .streamingChatModel(streamingChatModel)
    .tools(new Tools())
    .build();

TokenStream stream = assistant.chat("What's the weather and calculate 15*8?");

stream
    .onToolExecuted(execution ->
        System.out.println("Executed: " + execution.request().name()))
    .onPartialResponse(System.out::print)
    .onComplete(response -> System.out.println("Complete!"))
    .start();

Best Practices

最佳实践

Tool Design Guidelines

工具设计指南

  1. Descriptive Names: Use clear, actionable tool names
  2. Parameter Validation: Validate inputs before processing
  3. Error Messages: Provide meaningful error messages
  4. Return Types: Use appropriate return types that LLMs can understand
  5. Performance: Avoid blocking operations in tools
  1. 描述性名称：使用清晰、可操作的工具名称
  2. 参数验证：处理前验证输入
  3. 错误信息：提供有意义的错误提示
  4. 返回类型：使用LLM可理解的合适返回类型
  5. 性能：避免在工具中使用阻塞操作

Security Considerations

安全注意事项

  1. Permission Checks: Validate user permissions before tool execution
  2. Input Sanitization: Sanitize all tool inputs
  3. Audit Logging: Log tool usage for security monitoring
  4. Rate Limiting: Implement rate limiting for external APIs
  1. 权限检查：工具执行前验证用户权限
  2. 输入清理：清理所有工具输入
  3. 审计日志：记录工具使用情况以进行安全监控
  4. 速率限制：为外部API实现速率限制

Performance Optimization

性能优化

  1. Concurrent Execution: Use 
    executeToolsConcurrently()
    for independent tools
  2. Caching: Cache frequently accessed data
  3. Monitoring: Monitor tool performance and error rates
  4. Resource Management: Handle external service timeouts gracefully
  1. 并发执行：对独立工具使用
    executeToolsConcurrently()
  2. 缓存：缓存频繁访问的数据
  3. 监控：监控工具性能和错误率
  4. 资源管理：优雅处理外部服务超时

Reference Documentation

参考文档

For detailed API reference, examples, and advanced patterns, see:
  • API Reference - Complete API documentation
  • Implementation Patterns - Advanced implementation examples
  • Examples - Practical usage examples
如需详细API参考、示例和高级模式，请查看：
  • API 参考 - 完整API文档
  • 实现模式 - 高级实现示例
  • 示例 - 实际使用案例

Common Issues and Solutions

常见问题与解决方案

Tool Not Found

工具未找到

Problem: LLM calls tools that don't exist
Solution: Implement hallucination handler:
java
.hallucinatedToolNameStrategy(request -> {
    return ToolExecutionResultMessage.from(request,
        "Error: Tool '" + request.name() + "' does not exist");
})
问题：LLM调用不存在的工具
解决方案：实现幻觉处理程序：
java
.hallucinatedToolNameStrategy(request -> {
    return ToolExecutionResultMessage.from(request,
        "Error: Tool '" + request.name() + "' does not exist");
})

Parameter Validation Errors

参数验证错误

Problem: Tools receive invalid parameters
Solution: Add input validation and error handlers:
java
.toolArgumentsErrorHandler((error, context) -> {
    return ToolErrorHandlerResult.text("Invalid arguments: " + error.getMessage());
})
问题：工具收到无效参数
解决方案：添加输入验证和错误处理程序：
java
.toolArgumentsErrorHandler((error, context) -> {
    return ToolErrorHandlerResult.text("Invalid arguments: " + error.getMessage());
})

Performance Issues

性能问题

Problem: Tools are slow or timeout
Solution: Use concurrent execution and resilience patterns:
java
.executeToolsConcurrently(Executors.newFixedThreadPool(5))
.toolExecutionTimeout(Duration.ofSeconds(30))
问题：工具运行缓慢或超时
解决方案：使用并发执行和弹性模式：
java
.executeToolsConcurrently(Executors.newFixedThreadPool(5))
.toolExecutionTimeout(Duration.ofSeconds(30))

Related Skills

相关技能

  • langchain4j-ai-services-patterns
  • langchain4j-rag-implementation-patterns
  • langchain4j-spring-boot-integration
  • langchain4j-ai-services-patterns
  • langchain4j-rag-implementation-patterns
  • langchain4j-spring-boot-integration

References

参考资料

  • LangChain4j Tool & Function Calling - API References
  • LangChain4j Tool & Function Calling - Implementation Patterns
  • LangChain4j Tool & Function Calling - Examples
  • LangChain4j Tool & Function Calling - API References
  • LangChain4j Tool & Function Calling - Implementation Patterns
  • LangChain4j Tool & Function Calling - Examples