giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-java/skills/langchain4j-tool-function-calling-patterns
langchain4j-tool-function-calling-patterns
VerifiedProvides and generates LangChain4j tool and function calling patterns: annotates methods as tools with @Tool, configures tool executors, registers tools with AiServices, validates tool parameters, and handles tool execution errors. Use when building AI agents that call tools, define function specifications, manage tool responses, or integrate external APIs with LLM-driven applications.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.2 KB |
| references/advanced-features.md | markdown | 2.3 KB |
| references/core-patterns.md | markdown | 2.2 KB |
| references/error-handling.md | markdown | 2.9 KB |
| references/examples.md | markdown | 16.0 KB |
| references/implementation-patterns.md | markdown | 14.2 KB |
| references/integration-examples.md | markdown | 5.1 KB |
| references/references.md | markdown | 9.3 KB |
| references/setup-configuration.md | markdown | 2.0 KB |
references/implementation-patterns.md
View on GitHub# LangChain4j Tool & Function Calling - Implementation Patterns
Comprehensive implementation patterns for tool and function calling with LangChain4j.
## Core Tool Definition Patterns
### Basic Tool Definition with `@`Tool Annotation
The `@Tool` annotation converts regular Java methods into tools that LLMs can discover and execute.
**Basic Tool Definition:**
```java
public class CalculatorTools {
@Tool("Adds two given numbers")
public double add(double a, double b) {
return a + b;
}
@Tool("Multiplies two given numbers")
public double multiply(double a, double b) {
return a * b;
}
@Tool("Calculates the square root of a given number")
public double squareRoot(double x) {
return Math.sqrt(x);
}
@Tool("Calculates power of a number")
public double power(double base, double exponent) {
return Math.pow(base, exponent);
}
}
```
**Advanced Tool with Parameter Descriptions:**
```java
public class WeatherService {
@Tool("Get current weather conditions for a specific location")
public String getCurrentWeather(@P("The name of the city or location") String location) {
try {
WeatherData weather = weatherClient.getCurrentWeather(location);
return String.format("Weather in %s: %s, %.1f°C, humidity %.0f%%, wind %.1f km/h",
location, weather.getCondition(), weather.getTemperature(),
weather.getHumidity(), weather.getWindSpeed());
} catch (Exception e) {
return "Sorry, I couldn't retrieve weather information for " + location;
}
}
}
```
### Parameter Handling and Validation
**Optional Parameters:**
```java
public class DatabaseTools {
@Tool("Search for users in the database")
public List<User> searchUsers(
@P("Search term for user name or email") String searchTerm,
@P(value = "Maximum number of results to return", required = false) Integer limit,
@P(value = "Sort order: ASC or DESC", required = false) String sortOrder) {
int actualLimit = limit != null ? limit : 10;
String actualSort = sortOrder != null ? sortOrder : "ASC";
return userRepository.searchUsers(searchTerm, actualLimit, actualSort);
}
}
```
**Complex Parameter Types:**
```java
public class OrderManagementTools {
@Description("Customer order information")
public static class OrderRequest {
@Description("Customer ID who is placing the order")
private Long customerId;
@Description("List of items to order")
private List<OrderItem> items;
@Description("Shipping address for the order")
private Address shippingAddress;
@Description("Preferred delivery date (optional)")
@JsonProperty(required = false)
private LocalDate preferredDeliveryDate;
}
@Tool("Create a new customer order")
public String createOrder(OrderRequest orderRequest) {
try {
// Validation and processing logic
Order order = orderService.createOrder(orderRequest);
return String.format("Order created successfully! Order ID: %s, Total: $%.2f",
order.getId(), order.getTotal());
} catch (Exception e) {
return "Failed to create order: " + e.getMessage();
}
}
}
```
## Memory Context Integration
### `@`ToolMemoryId for User Context
Tools can access conversation memory context to provide personalized and contextual responses:
```java
public class PersonalizedTools {
@Tool("Get personalized recommendations based on user preferences")
public String getRecommendations(@ToolMemoryId String userId,
@P("Type of recommendation: books, movies, restaurants") String type) {
UserPreferences prefs = preferenceService.getUserPreferences(userId);
List<String> history = historyService.getSearchHistory(userId, type);
return recommendationEngine.getRecommendations(type, prefs, history);
}
}
```
## Dynamic Tool Provisioning
### ToolProvider for Context-Aware Tools
```java
public class DynamicToolProvider implements ToolProvider {
@Override
public ToolProviderResult provideTools(ToolProviderRequest request) {
String userId = extractUserId(request);
UserPermissions permissions = permissionService.getUserPermissions(userId);
String userMessage = request.userMessage().singleText().toLowerCase();
ToolProviderResult.Builder resultBuilder = ToolProviderResult.builder();
// Always available tools
addBasicTools(resultBuilder);
// Conditional tools based on permissions
if (permissions.canAccessFinancialData()) {
addFinancialTools(resultBuilder);
}
if (permissions.canModifyUserData()) {
addUserManagementTools(resultBuilder);
}
return resultBuilder.build();
}
}
```
### Programmatic Tool Definition
```java
public class ProgrammaticToolsService {
public Map<ToolSpecification, ToolExecutor> createDatabaseTools(DatabaseConfig config) {
Map<ToolSpecification, ToolExecutor> tools = new HashMap<>();
// Query tool
ToolSpecification querySpec = ToolSpecification.builder()
.name("execute_database_query")
.description("Execute a SQL query on the database")
.parameters(JsonObjectSchema.builder()
.addStringProperty("query", "SQL query to execute")
.addBooleanProperty("readOnly", "Whether this is a read-only query")
.required("query", "readOnly")
.build())
.build();
ToolExecutor queryExecutor = (request, memoryId) -> {
Map<String, Object> args = fromJson(request.arguments());
String query = args.get("query").toString();
boolean readOnly = (Boolean) args.get("readOnly");
return databaseService.executeQuery(query, readOnly);
};
tools.put(querySpec, queryExecutor);
return tools;
}
}
```
## AI Services as Tools
AI Services can be used as tools by other AI Services, enabling hierarchical architectures:
```java
// Specialized Expert Services
interface DataAnalysisExpert {
@UserMessage("You are a data analysis expert. Analyze this data and provide insights: {{data}}")
@Tool("Expert data analysis and insights")
String analyzeData(@V("data") String data);
}
// Router Agent that delegates to experts
interface ExpertRouter {
@UserMessage("""
Analyze the user request and determine which expert(s) should handle it:
- Use the data analysis expert for data-related questions
- Use the security expert for security-related concerns
User request: {{it}}
""")
String routeToExperts(String request);
}
@Service
public class ExpertConsultationService {
public ExpertConsultationService(ChatModel chatModel) {
// Build expert services
DataAnalysisExpert dataExpert = AiServices.create(DataAnalysisExpert.class, chatModel);
// Build router with experts as tools
this.router = AiServices.builder(ExpertRouter.class)
.chatModel(chatModel)
.tools(dataExpert)
.build();
}
}
```
## Advanced Tool Patterns
### Immediate Return Tools
```java
public class DirectResponseTools {
@Tool(value = "Get current user information", returnBehavior = ReturnBehavior.IMMEDIATE)
public String getCurrentUserInfo(@ToolMemoryId String userId) {
User user = userService.findById(userId);
return String.format("""
User Information:
Name: %s
Email: %s
Role: %s
""", user.getName(), user.getEmail(), user.getRole());
}
}
```
### Concurrent Tool Execution
```java
public class ConcurrentTools {
@Tool("Get stock price for a company")
public String getStockPrice(@P("Stock symbol") String symbol) {
try {
Thread.sleep(1000);
return stockApiService.getPrice(symbol);
} catch (InterruptedException e) {
return "Error retrieving stock price";
}
}
@Tool("Get company news")
public String getCompanyNews(@P("Company symbol") String symbol) {
// Similar implementation
}
}
// Configure for concurrent execution
Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(chatModel)
.tools(new ConcurrentTools())
.executeToolsConcurrently() // Execute tools in parallel
.build();
```
## Error Handling and Resilience
### Tool Execution Error Handling
```java
public class ResilientTools {
private final CircuitBreaker circuitBreaker;
private final RetryTemplate retryTemplate;
@Tool("Get external data with resilience patterns")
public String getExternalData(@P("Data source identifier") String sourceId) {
return circuitBreaker.executeSupplier(() -> {
return retryTemplate.execute(context -> {
try {
return externalApiService.fetchData(sourceId);
} catch (ApiException e) {
if (e.isRetryable()) {
throw e; // Will be retried
}
return "Data temporarily unavailable: " + e.getMessage();
}
});
});
}
}
```
### Graceful Degradation
```java
public class FallbackTools {
@Tool("Get weather information with fallback providers")
public String getWeather(@P("Location name") String location) {
// Try primary provider first
for (DataProvider provider : dataProviders) {
try {
WeatherData weather = provider.getWeather(location);
if (weather != null) {
return formatWeather(weather, provider.getName());
}
} catch (Exception e) {
// Continue to next provider
}
}
return "Weather information is currently unavailable for " + location;
}
}
```
## Streaming and Tool Execution
### Streaming with Tool Callbacks
```java
interface StreamingToolAssistant {
TokenStream chat(String message);
}
StreamingToolAssistant assistant = AiServices.builder(StreamingToolAssistant.class)
.streamingChatModel(streamingChatModel)
.tools(new CalculatorTools(), new WeatherService())
.build();
TokenStream stream = assistant.chat("What's the weather in Paris and calculate 15 + 27?");
stream
.onToolExecuted(toolExecution -> {
System.out.println("Tool executed: " + toolExecution.request().name());
System.out.println("Result: " + toolExecution.result());
})
.onPartialResponse(partialResponse -> {
System.out.print(partialResponse);
})
.start();
```
### Accessing Tool Execution Results
```java
interface AnalyticsAssistant {
Result<String> analyze(String request);
}
AnalyticsAssistant assistant = AiServices.builder(AnalyticsAssistant.class)
.chatModel(chatModel)
.tools(new DataAnalysisTools(), new DatabaseTools())
.build();
Result<String> result = assistant.analyze("Analyze sales data for Q4 2023");
// Access the response
String response = result.content();
// Access tool execution details
List<ToolExecution> toolExecutions = result.toolExecutions();
for (ToolExecution execution : toolExecutions) {
System.out.println("Tool: " + execution.request().name());
System.out.println("Duration: " + execution.duration().toMillis() + "ms");
}
```
## Complete Tool-Enabled Application
### Spring Boot Integration
```java
@RestController
@RequestMapping("/api/assistant")
@RequiredArgsConstructor
public class ToolAssistantController {
private final ToolEnabledAssistant assistant;
@PostMapping("/chat")
public ResponseEntity<ChatResponse> chat(@RequestBody ChatRequest request) {
try {
Result<String> result = assistant.chat(request.getUserId(), request.getMessage());
ChatResponse response = ChatResponse.builder()
.response(result.content())
.toolsUsed(extractToolNames(result.toolExecutions()))
.tokenUsage(result.tokenUsage())
.build();
return ResponseEntity.ok(response);
} catch (Exception e) {
return ResponseEntity.badRequest().body(
ChatResponse.error("Error processing request: " + e.getMessage())
);
}
}
}
interface ToolEnabledAssistant {
Result<String> chat(@MemoryId String userId, String message);
List<ToolInfo> getAvailableTools(String userId);
}
```
## Performance Optimization
### Tool Performance Monitoring
```java
@Component
public class ToolPerformanceMonitor {
@EventListener
public void handleToolExecution(ToolExecutionEvent event) {
// Record execution metrics
Timer.Sample sample = Timer.start(meterRegistry);
sample.stop(Timer.builder("tool.execution.duration")
.tag("tool", event.getToolName())
.tag("success", String.valueOf(event.isSuccessful()))
.register(meterRegistry));
// Record error rates
if (!event.isSuccessful()) {
meterRegistry.counter("tool.execution.errors",
"tool", event.getToolName(),
"error_type", event.getErrorType())
.increment();
}
}
}
```
## Testing Framework
```java
@Component
public class ToolTestingFramework {
public ToolValidationResult validateTool(Object toolInstance, String methodName) {
try {
TestAssistant testAssistant = AiServices.builder(TestAssistant.class)
.chatModel(testChatModel)
.tools(toolInstance)
.build();
String response = testAssistant.testTool(methodName);
return ToolValidationResult.builder()
.toolName(methodName)
.isValid(response != null && !response.contains("Error"))
.response(response)
.build();
} catch (Exception e) {
return ToolValidationResult.builder()
.toolName(methodName)
.isValid(false)
.error(e.getMessage())
.build();
}
}
}
```Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |