Back to AI Tools & Agents
langchain4j-ai-services-patterns
LangChain4jJavaAI servicesdeclarative programmingLLM integrationconversational AIRAGtool integration
Install this skill
npx skills add giuseppe-trisciuoglio/developer-kitWorks across Claude Code, Cursor, Codex, Copilot & Antigravity
LangChain4j AI Services adopt a declarative approach to integrate Large Language Models into Java applications. By defining plain Java interfaces, developers delegate the underlying boilerplate of prompt engineering, model orchestration, and result parsing to the framework. The library acts as an abstraction layer that maps method calls to LLM interactions, allowing for type-safe parameter passing and structured output extraction. It manages complex tasks like session memory, tool invocation, and system-level instruction formatting through annotations. Instead of manually handling low-level API requests, you define the desired behavior in an interface signature, and the framework implementation manages the lifecycle, context retrieval, and function execution. This methodology simplifies building conversational agents and specialized AI handlers while keeping codebase logic separated from specific vendor implementation details.
When to Use This Skill
- •Building stateful chatbots that track user history
- •Implementing customer support agents with tool-calling capabilities
- •Automating data extraction from unstructured text into typed Java objects
- •Creating personas for AI assistants through annotated system instructions
How to Invoke This Skill
Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:
- “Create a LangChain4j interface for an AI assistant
- “How to manage chat memory in LangChain4j AI Services
- “Call a Java method as a tool from an LLM
- “Extract structured JSON data into a Java POJO using LangChain4j
- “Configure a system message for my AI service interface
Pro Tips
- 💡Design your AI service interfaces to be granular and focused on single responsibilities for better modularity and testability.
- 💡Prioritize robust error handling within your AI services, leveraging LangChain4j's capabilities to manage LLM interaction failures gracefully.
- 💡When integrating tools, ensure your tool definitions are precise and cover all necessary input parameters for reliable function calling.
What this skill does
- •Declarative interface-to-LLM mapping
- •Automated memory management for multi-turn conversations
- •Annotation-based system and user prompt injection
- •Automatic tool discovery and function execution from POJOs
- •Direct transformation of LLM output into Java POJOs or Enums
When not to use it
- ✕When you require total control over every raw HTTP request/response cycle
- ✕Simple one-off API calls where overhead of interface definitions is unnecessary
- ✕Environments where reflection or proxy generation is restricted
Example workflow
- Define a Java interface representing your AI capability
- Annotate methods with @SystemMessage or @UserMessage to set behavior
- Configure an AI Service builder with your chosen LLM and memory provider
- Instantiate the interface via AiServices.create()
- Call the interface methods directly within your business logic
- Receive typed return values or objects handled by the framework
Prerequisites
- –Java Development Kit (JDK) 17 or higher
- –LangChain4j core dependency and a specific model provider
- –API key for an LLM provider like OpenAI or Anthropic
Pitfalls & limitations
- !Over-reliance on automatic parsing can lead to runtime errors if prompt outputs are inconsistent
- !Debugging the underlying prompt construction can be obscure compared to manual string concatenation
- !High latency if the AI Service is invoked in a tight loop without streaming
FAQ
How does LangChain4j handle memory across multiple users?
You use the @MemoryId annotation on a method parameter to isolate chat history per user.
Can I return Java objects directly from AI services?
Yes, by defining the return type as a POJO or Enum, the framework automatically maps the LLM text output into that type.
Is manual prompt construction required?
No, the framework uses annotations and parameters to compose prompts dynamically based on your interface definitions.
How it compares
Unlike manual REST API orchestration, AI Services abstract the prompt lifecycle, significantly reducing boilerplate and ensuring consistent type mapping across your Java application.
📄 Full skill instructions — original source: giuseppe-trisciuoglio/developer-kit
# LangChain4j AI Services Patterns
This skill provides guidance for building declarative AI Services with LangChain4j using interface-based patterns, annotations for system and user messages, memory management, tools integration, and advanced AI application patterns that abstract away low-level LLM interactions.
## When to Use
Use this skill when:
- Building declarative AI-powered interfaces with minimal boilerplate code
- Creating type-safe AI services with Java interfaces and annotations
- Implementing conversational AI systems with memory management
- Designing AI services that can call external tools and functions
- Building multi-agent systems with specialized AI components
- Creating AI services with different personas and behaviors
- Implementing RAG (Retrieval-Augmented Generation) patterns declaratively
- Building production AI applications with proper error handling and validation
- Creating AI services that return structured data types (enums, POJOs, lists)
- Implementing streaming AI responses with reactive patterns
## Overview
LangChain4j AI Services allow you to define AI-powered functionality using plain Java interfaces with annotations, eliminating the need for manual prompt construction and response parsing. This pattern provides type-safe, declarative AI capabilities with minimal boilerplate code.
## Quick Start
### Basic AI Service Definition
### System Message and Templates
### Memory Management
### Tool Integration
## Examples
See [examples.md](references/examples.md) for comprehensive practical examples including:
- Basic chat interfaces
- Stateful assistants with memory
- Multi-user scenarios
- Structured output extraction
- Tool calling and function execution
- Streaming responses
- Error handling
- RAG integration
- Production patterns
## API Reference
Complete API documentation, annotations, interfaces, and configuration patterns are available in [references.md](references/references.md).
## Best Practices
1. **Use type-safe interfaces** instead of string-based prompts
2. **Implement proper memory management** with appropriate limits
3. **Design clear tool descriptions** with parameter documentation
4. **Handle errors gracefully** with custom error handlers
5. **Use structured output** for predictable responses
6. **Implement validation** for user inputs
7. **Monitor performance** for production deployments
## Dependencies
## References
- [LangChain4j Documentation](https://langchain4j.com/docs/)
- [LangChain4j AI Services - API References](references/references.md)
- [LangChain4j AI Services - Practical Examples](references/examples.md)
This skill provides guidance for building declarative AI Services with LangChain4j using interface-based patterns, annotations for system and user messages, memory management, tools integration, and advanced AI application patterns that abstract away low-level LLM interactions.
## When to Use
Use this skill when:
- Building declarative AI-powered interfaces with minimal boilerplate code
- Creating type-safe AI services with Java interfaces and annotations
- Implementing conversational AI systems with memory management
- Designing AI services that can call external tools and functions
- Building multi-agent systems with specialized AI components
- Creating AI services with different personas and behaviors
- Implementing RAG (Retrieval-Augmented Generation) patterns declaratively
- Building production AI applications with proper error handling and validation
- Creating AI services that return structured data types (enums, POJOs, lists)
- Implementing streaming AI responses with reactive patterns
## Overview
LangChain4j AI Services allow you to define AI-powered functionality using plain Java interfaces with annotations, eliminating the need for manual prompt construction and response parsing. This pattern provides type-safe, declarative AI capabilities with minimal boilerplate code.
## Quick Start
### Basic AI Service Definition
interface Assistant {
String chat(String userMessage);
}
// Create instance - LangChain4j generates implementation
Assistant assistant = AiServices.create(Assistant.class, chatModel);
// Use the service
String response = assistant.chat("Hello, how are you?");### System Message and Templates
interface CustomerSupportBot {
@SystemMessage("You are a helpful customer support agent for TechCorp")
String handleInquiry(String customerMessage);
@UserMessage("Analyze sentiment: {{it}}")
String analyzeSentiment(String feedback);
}
CustomerSupportBot bot = AiServices.create(CustomerSupportBot.class, chatModel);### Memory Management
interface MultiUserAssistant {
String chat(@MemoryId String userId, String userMessage);
}
Assistant assistant = AiServices.builder(MultiUserAssistant.class)
.chatModel(model)
.chatMemoryProvider(userId -> MessageWindowChatMemory.withMaxMessages(10))
.build();### Tool Integration
class Calculator {
@Tool("Add two numbers") double add(double a, double b) { return a + b; }
}
interface MathGenius {
String ask(String question);
}
MathGenius mathGenius = AiServices.builder(MathGenius.class)
.chatModel(model)
.tools(new Calculator())
.build();## Examples
See [examples.md](references/examples.md) for comprehensive practical examples including:
- Basic chat interfaces
- Stateful assistants with memory
- Multi-user scenarios
- Structured output extraction
- Tool calling and function execution
- Streaming responses
- Error handling
- RAG integration
- Production patterns
## API Reference
Complete API documentation, annotations, interfaces, and configuration patterns are available in [references.md](references/references.md).
## Best Practices
1. **Use type-safe interfaces** instead of string-based prompts
2. **Implement proper memory management** with appropriate limits
3. **Design clear tool descriptions** with parameter documentation
4. **Handle errors gracefully** with custom error handlers
5. **Use structured output** for predictable responses
6. **Implement validation** for user inputs
7. **Monitor performance** for production deployments
## Dependencies
<!-- Maven -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j</artifactId>
<version>1.8.0</version>
</dependency>
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai</artifactId>
<version>1.8.0</version>
</dependency>// Gradle
implementation 'dev.langchain4j:langchain4j:1.8.0'
implementation 'dev.langchain4j:langchain4j-open-ai:1.8.0'## References
- [LangChain4j Documentation](https://langchain4j.com/docs/)
- [LangChain4j AI Services - API References](references/references.md)
- [LangChain4j AI Services - Practical Examples](references/examples.md)
How to Use This Skill Unit
Option A: Project-Specific (Recommended)
- Click "Download" above
- In your project, create the directory:
.agent/skills/langchain4j-ai-services-patterns/ - Save the file as
SKILL.md - The agent will automatically discover the skill based on its description.
Option B: Global Installation (All Agents)
Save the file to these locations to make it available across all projects:
- Claude Code:
~/.claude/skills/giuseppe-trisciuoglio/developer-kit/langchain4j-ai-services-patterns/SKILL.md - Cursor:
~/.cursor/skills/giuseppe-trisciuoglio/developer-kit/langchain4j-ai-services-patterns/SKILL.md - Antigravity:
~/.gemini/antigravity/skills/giuseppe-trisciuoglio/developer-kit/langchain4j-ai-services-patterns/SKILL.md
🚀 Install with CLI:npx skills add giuseppe-trisciuoglio/developer-kit
Recommended Rules
View more rules →Spring Boot Java Expert
Spring BootJavaBackend
You are an expert in Spring Boot and Java enterprise development. Key Principles: - Convention over Configuration - Standalone, production-grade appl...
🧪 Test Writing Agent - Strategic Test Coverage
Agentic AITestingUnit Tests
You are an expert test writing agent specialized in creating comprehensive, maintainable, and meaningful tests. Apply systematic reasoning to ensure p...
JavaScript ES6+ Modern Features Expert
JavaScriptES6+Modern JavaScript
You are an expert in modern JavaScript ES6+ features and best practices. Key Principles: - Use modern JavaScript syntax - Leverage ES6+ features for ...
Recommended Workflows
View more workflows →React Performance Profiling
ReactPerformanceDebugging
--- description: Identify slow components using React Profiler --- 1. **Install DevTools**: - Install React Developer Tools extension for Chrome/F...
Accessibility (a11y) Audit
AccessibilityTestingQuality
--- description: Find and fix accessibility violations --- 1. **Install axe-core**: - Use the CLI tool for quick audits. // turbo - Run `npm...
E2E Testing Setup (Playwright)
TestingE2EPlaywright
--- description: Boilerplate setup for end-to-end testing --- 1. **Initialize Playwright**: - Run the init command. // turbo - Run `npm init...
