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/examples.md
View on GitHub# LangChain4j Tool & Function Calling - Practical Examples
Production-ready examples for tool calling and function execution patterns with LangChain4j.
## 1. Basic Tool Calling
**Scenario**: Simple tools that LLM can invoke automatically.
```java
import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.agent.tool.P;
import dev.langchain4j.service.AiServices;
import dev.langchain4j.model.openai.OpenAiChatModel;
class Calculator {
@Tool("Add two numbers together")
int add(@P("first number") int a, @P("second number") int b) {
return a + b;
}
@Tool("Multiply two numbers")
int multiply(@P("first number") int a, @P("second number") int b) {
return a * b;
}
@Tool("Divide two numbers")
double divide(@P("dividend") double a, @P("divisor") double b) {
if (b == 0) throw new IllegalArgumentException("Cannot divide by zero");
return a / b;
}
}
interface CalculatorAssistant {
String chat(String query);
}
public class BasicToolExample {
public static void main(String[] args) {
var chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.temperature(0.0) // Deterministic for tools
.build();
var assistant = AiServices.builder(CalculatorAssistant.class)
.chatModel(chatModel)
.tools(new Calculator())
.build();
System.out.println(assistant.chat("What is 25 + 37?"));
System.out.println(assistant.chat("Calculate 12 * 8"));
System.out.println(assistant.chat("Divide 100 by 4"));
}
}
```
## 2. Multiple Tool Objects
**Scenario**: LLM selecting from multiple tool domains.
```java
class WeatherService {
@Tool("Get current weather for a city")
String getWeather(@P("city name") String city) {
// Simulate API call
return "Weather in " + city + ": 22°C, Partly cloudy";
}
@Tool("Get weather forecast for next 5 days")
String getForecast(@P("city name") String city) {
return "5-day forecast for " + city + ": Sunny, Cloudy, Rainy, Sunny, Cloudy";
}
}
class DateTimeService {
@Tool("Get current date and time")
String getCurrentDateTime() {
return LocalDateTime.now().toString();
}
@Tool("Get day of week for a date")
String getDayOfWeek(@P("date in YYYY-MM-DD format") String date) {
LocalDate localDate = LocalDate.parse(date);
return localDate.getDayOfWeek().toString();
}
}
interface MultiToolAssistant {
String help(String query);
}
public class MultipleToolsExample {
public static void main(String[] args) {
var chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
var assistant = AiServices.builder(MultiToolAssistant.class)
.chatModel(chatModel)
.tools(new WeatherService(), new DateTimeService())
.build();
System.out.println(assistant.help("What's the weather in Paris?"));
System.out.println(assistant.help("What time is it?"));
System.out.println(assistant.help("What day is 2024-12-25?"));
}
}
```
## 3. Tool with Complex Return Types
**Scenario**: Tools returning structured objects.
```java
class UserRecord {
public String id;
public String name;
public String email;
public LocalDate createdDate;
public UserRecord(String id, String name, String email, LocalDate createdDate) {
this.id = id;
this.name = name;
this.email = email;
this.createdDate = createdDate;
}
}
class UserService {
@Tool("Look up user information by ID")
UserRecord getUserById(@P("user ID") String userId) {
// Simulate database lookup
return new UserRecord(userId, "John Doe", "john@example.com", LocalDate.now());
}
@Tool("List all users (returns top 10)")
List<UserRecord> listUsers() {
return Arrays.asList(
new UserRecord("1", "Alice", "alice@example.com", LocalDate.now()),
new UserRecord("2", "Bob", "bob@example.com", LocalDate.now())
);
}
@Tool("Search users by name pattern")
List<UserRecord> searchByName(@P("name pattern") String pattern) {
return Arrays.asList(
new UserRecord("1", "John Smith", "john.smith@example.com", LocalDate.now())
);
}
}
interface UserAssistant {
String answer(String query);
}
public class ComplexReturnTypeExample {
public static void main(String[] args) {
var chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
var assistant = AiServices.builder(UserAssistant.class)
.chatModel(chatModel)
.tools(new UserService())
.build();
System.out.println(assistant.answer("Who is user 123?"));
System.out.println(assistant.answer("List all users"));
System.out.println(assistant.answer("Find users named John"));
}
}
```
## 4. Error Handling in Tools
**Scenario**: Graceful handling of tool errors.
```java
class DatabaseService {
@Tool("Execute read query on database")
String queryDatabase(@P("SQL query") String query) {
// Validate query is SELECT only
if (!query.trim().toUpperCase().startsWith("SELECT")) {
throw new IllegalArgumentException("Only SELECT queries allowed");
}
return "Query result: 42 rows returned";
}
@Tool("Get user count by status")
int getUserCount(@P("status") String status) {
if (!Arrays.asList("active", "inactive", "pending").contains(status)) {
throw new IllegalArgumentException("Invalid status: " + status);
}
return 150;
}
}
interface ResilientAssistant {
String execute(String command);
}
public class ErrorHandlingExample {
public static void main(String[] args) {
var chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
var assistant = AiServices.builder(ResilientAssistant.class)
.chatModel(chatModel)
.tools(new DatabaseService())
// Handle tool execution errors
.toolExecutionErrorHandler((toolCall, exception) -> {
System.err.println("Tool error in " + toolCall.name() + ": " + exception.getMessage());
return "Error: " + exception.getMessage();
})
// Handle malformed tool arguments
.toolArgumentsErrorHandler((toolCall, exception) -> {
System.err.println("Invalid arguments for " + toolCall.name());
return "Invalid arguments";
})
.build();
System.out.println(assistant.execute("Execute SELECT * FROM users"));
System.out.println(assistant.execute("How many active users?"));
}
}
```
## 5. Streaming Tool Execution
**Scenario**: Tools called during streaming responses.
```java
import dev.langchain4j.service.TokenStream;
interface StreamingToolAssistant {
TokenStream execute(String command);
}
public class StreamingToolsExample {
public static void main(String[] args) {
var streamingModel = OpenAiStreamingChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
var assistant = AiServices.builder(StreamingToolAssistant.class)
.streamingChatModel(streamingModel)
.tools(new Calculator())
.build();
assistant.execute("Calculate (5 + 3) * 4 and explain")
.onNext(token -> System.out.print(token))
.onToolExecuted(execution ->
System.out.println("\n[Tool: " + execution.request().name() + "]"))
.onCompleteResponse(response ->
System.out.println("\n--- Complete ---"))
.onError(error -> System.err.println("Error: " + error))
.start();
try {
Thread.sleep(3000);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
}
```
## 6. Dynamic Tool Provider
**Scenario**: Select tools dynamically based on query context.
```java
interface DynamicToolAssistant {
String help(String query);
}
class MathTools {
@Tool("Add two numbers")
int add(@P("a") int a, @P("b") int b) { return a + b; }
}
class TextTools {
@Tool("Convert text to uppercase")
String toUpper(@P("text") String text) { return text.toUpperCase(); }
@Tool("Convert text to lowercase")
String toLower(@P("text") String text) { return text.toLowerCase(); }
}
public class DynamicToolProviderExample {
public static void main(String[] args) {
var chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
var assistant = AiServices.builder(DynamicToolAssistant.class)
.chatModel(chatModel)
// Provide tools dynamically
.toolProvider(context -> {
if (context.userMessage().contains("math") || context.userMessage().contains("calculate")) {
return Collections.singletonList(new MathTools());
} else if (context.userMessage().contains("text") || context.userMessage().contains("convert")) {
return Collections.singletonList(new TextTools());
}
return Collections.emptyList();
})
.build();
System.out.println(assistant.help("Calculate 25 + 37"));
System.out.println(assistant.help("Convert HELLO to lowercase"));
}
}
```
## 7. Tool with Memory Context
**Scenario**: Tools accessing conversation memory.
```java
class ContextAwareDataService {
private Map<String, String> userPreferences = new HashMap<>();
@Tool("Save user preference")
void savePreference(@P("key") String key, @P("value") String value) {
userPreferences.put(key, value);
System.out.println("Saved: " + key + " = " + value);
}
@Tool("Get user preference")
String getPreference(@P("key") String key) {
return userPreferences.getOrDefault(key, "Not found");
}
@Tool("List all preferences")
Map<String, String> listPreferences() {
return new HashMap<>(userPreferences);
}
}
interface ContextAssistant {
String chat(String message);
}
public class ToolMemoryExample {
public static void main(String[] args) {
var chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
var dataService = new ContextAwareDataService();
var assistant = AiServices.builder(ContextAssistant.class)
.chatModel(chatModel)
.chatMemory(MessageWindowChatMemory.withMaxMessages(10))
.tools(dataService)
.build();
System.out.println(assistant.chat("Remember that I like Java"));
System.out.println(assistant.chat("What do I like?"));
System.out.println(assistant.chat("Also remember I use Spring Boot"));
System.out.println(assistant.chat("What are all my preferences?"));
}
}
```
## 8. Stateful Tool Execution
**Scenario**: Tools that maintain state across calls.
```java
class StatefulCounter {
private int count = 0;
@Tool("Increment counter by 1")
int increment() {
return ++count;
}
@Tool("Decrement counter by 1")
int decrement() {
return --count;
}
@Tool("Get current counter value")
int getCount() {
return count;
}
@Tool("Reset counter to zero")
void reset() {
count = 0;
}
}
interface CounterAssistant {
String interact(String command);
}
public class StatefulToolExample {
public static void main(String[] args) {
var chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
var counter = new StatefulCounter();
var assistant = AiServices.builder(CounterAssistant.class)
.chatModel(chatModel)
.tools(counter)
.build();
System.out.println(assistant.interact("Increment the counter"));
System.out.println(assistant.interact("Increment again"));
System.out.println(assistant.interact("What's the current count?"));
System.out.println(assistant.interact("Reset the counter"));
System.out.println(assistant.interact("Decrement"));
}
}
```
## 9. Tool Validation and Authorization
**Scenario**: Validate and authorize tool execution.
```java
class SecureDataService {
@Tool("Get sensitive data")
String getSensitiveData(@P("data_id") String dataId) {
// This should normally check authorization
if (!dataId.matches("^[A-Z][0-9]{3}$")) {
throw new IllegalArgumentException("Invalid data ID format");
}
return "Sensitive data for " + dataId;
}
@Tool("Delete data (requires authorization)")
void deleteData(@P("data_id") String dataId) {
if (!dataId.matches("^[A-Z][0-9]{3}$")) {
throw new IllegalArgumentException("Invalid data ID");
}
System.out.println("Data " + dataId + " deleted");
}
}
interface SecureAssistant {
String execute(String command);
}
public class AuthorizationExample {
public static void main(String[] args) {
var chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
var assistant = AiServices.builder(SecureAssistant.class)
.chatModel(chatModel)
.tools(new SecureDataService())
.toolExecutionErrorHandler((request, exception) -> {
System.err.println("Authorization/validation failed: " + exception.getMessage());
return "Operation denied: " + exception.getMessage();
})
.build();
System.out.println(assistant.execute("Get data A001"));
System.out.println(assistant.execute("Get data invalid"));
}
}
```
## 10. Advanced: Tool Result Processing
**Scenario**: Process and transform tool results before returning to LLM.
```java
class DataService {
@Tool("Fetch user data from API")
String fetchUserData(@P("user_id") String userId) {
return "User{id=" + userId + ", name=John, role=Admin}";
}
}
interface ProcessingAssistant {
String answer(String query);
}
public class ToolResultProcessingExample {
public static void main(String[] args) {
var chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
var assistant = AiServices.builder(ProcessingAssistant.class)
.chatModel(chatModel)
.tools(new DataService())
// Can add interceptors for tool results if needed
// This would be in a future LangChain4j version
.build();
System.out.println(assistant.answer("What is the role of user 123?"));
}
}
```
## Best Practices
1. **Clear Descriptions**: Write detailed `@`Tool descriptions for LLM context
2. **Strong Typing**: Use specific types (int, String) instead of generic Object
3. **Parameter Descriptions**: Use `@`P with clear descriptions of expected formats
4. **Error Handling**: Always implement error handlers for graceful failures
5. **Temperature**: Set temperature=0 for deterministic tool selection
6. **Validation**: Validate all parameters before execution
7. **Logging**: Log tool calls and results for debugging
8. **State Management**: Keep tools stateless or manage state explicitly
9. **Timeout**: Set timeouts on long-running tools
10. **Authorization**: Validate authorization before executing sensitive operations
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: 468k | 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 |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |