tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-agentic

Quarkus extension that integrates LangChain4j's agentic capabilities, enabling developers to build AI agent-based applications using declarative patterns with support for multiple agent types, agent-to-agent communication, and CDI integration.

Overview

Eval results

Files

Quarkus LangChain4j Agentic Extension

Name: tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-agentic
Author: tessl

The Quarkus LangChain4j Agentic extension integrates LangChain4j's agentic capabilities into Quarkus applications, enabling developers to build AI agent-based applications using declarative patterns. This extension supports multiple agent types including basic agents, supervisor agents, sequence agents, parallel agents, loop agents, conditional agents, planner agents, and agent-to-agent (A2A) communication. It provides seamless CDI integration, allowing agents to be injected and used throughout your Quarkus application.

Package Information

Package Name: quarkus-langchain4j-agentic
Group ID: io.quarkiverse.langchain4j
Artifact ID: quarkus-langchain4j-agentic
Package Type: Maven (Quarkus Extension)
Language: Java
Version: 1.7.4
Status: Preview
Installation:
```
<dependency>
    <groupId>io.quarkiverse.langchain4j</groupId>
    <artifactId>quarkus-langchain4j-agentic</artifactId>
    <version>1.7.4</version>
</dependency>
```

Required Dependencies

The Quarkus LangChain4j Agentic extension requires LangChain4j core dependencies. These are typically included transitively, but you may need to add them explicitly for certain features:

<!-- LangChain4j Core (included transitively) -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-core</artifactId>
    <version>0.36.2</version>
</dependency>

<!-- For OpenAI ChatModel support -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>0.36.2</version>
</dependency>

<!-- For Ollama ChatModel support -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-ollama</artifactId>
    <version>0.36.2</version>
</dependency>

<!-- For RAG/Embedding support -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-embeddings</artifactId>
    <version>0.36.2</version>
</dependency>

<!-- For in-memory embedding store -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-embeddings-all-minilm-l6-v2</artifactId>
    <version>0.36.2</version>
</dependency>

Note: Version numbers may vary. Check the LangChain4j releases for the latest compatible versions.

Core Imports

// Agent annotations (package: dev.langchain4j.agentic)
import dev.langchain4j.agentic.Agent;

// Orchestration annotations (package: dev.langchain4j.agentic.declarative)
import dev.langchain4j.agentic.declarative.SupervisorAgent;
import dev.langchain4j.agentic.declarative.SequenceAgent;
import dev.langchain4j.agentic.declarative.ParallelAgent;
import dev.langchain4j.agentic.declarative.LoopAgent;
import dev.langchain4j.agentic.declarative.ConditionalAgent;
import dev.langchain4j.agentic.declarative.PlannerAgent;
import dev.langchain4j.agentic.declarative.A2AClientAgent;

// Supplier annotations (package: dev.langchain4j.agentic.declarative)
import dev.langchain4j.agentic.declarative.ChatModelSupplier;
import dev.langchain4j.agentic.declarative.ChatMemorySupplier;
import dev.langchain4j.agentic.declarative.ChatMemoryProviderSupplier;
import dev.langchain4j.agentic.declarative.ToolsSupplier;
import dev.langchain4j.agentic.declarative.ToolProviderSupplier;
import dev.langchain4j.agentic.declarative.ContentRetrieverSupplier;
import dev.langchain4j.agentic.declarative.RetrievalAugmentorSupplier;
import dev.langchain4j.agentic.declarative.HumanInTheLoopResponseSupplier;

// Control flow annotations (package: dev.langchain4j.agentic.declarative)
import dev.langchain4j.agentic.declarative.ActivationCondition;
import dev.langchain4j.agentic.declarative.ExitCondition;
import dev.langchain4j.agentic.declarative.ErrorHandler;
import dev.langchain4j.agentic.declarative.HumanInTheLoop;
import dev.langchain4j.agentic.declarative.Output;
import dev.langchain4j.agentic.declarative.ParallelExecutor;
import dev.langchain4j.agentic.declarative.SupervisorRequest;

// Scope and result types (package: dev.langchain4j.agentic.scope)
import dev.langchain4j.agentic.scope.AgenticScope;
import dev.langchain4j.agentic.scope.ResultWithAgenticScope;
import dev.langchain4j.agentic.scope.AgenticScopeAccess;

// Error handling (package: dev.langchain4j.agentic.agent)
import dev.langchain4j.agentic.agent.ErrorContext;
import dev.langchain4j.agentic.agent.ErrorRecoveryResult;
import dev.langchain4j.agentic.agent.MissingArgumentException;
import dev.langchain4j.agentic.agent.ChatMessagesAccess;

// Message and template annotations (package: dev.langchain4j.service)
import dev.langchain4j.service.V;
import dev.langchain4j.service.MemoryId;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.SystemMessage;

// Tool annotations (package: dev.langchain4j.agent.tool)
import dev.langchain4j.agent.tool.Tool;

// MCP Integration (package: io.quarkiverse.langchain4j.mcp.runtime)
import io.quarkiverse.langchain4j.mcp.runtime.McpToolBox;

// Runtime support classes (package: io.quarkiverse.langchain4j.agentic.runtime)
import io.quarkiverse.langchain4j.agentic.runtime.AiAgentCreateInfo;
import io.quarkiverse.langchain4j.agentic.runtime.AgenticRecorder;

// LangChain4j core types (for supplier implementations)
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.service.memory.ChatMemory;
import dev.langchain4j.service.tool.ToolProvider;
import dev.langchain4j.data.retriever.ContentRetriever;
import dev.langchain4j.rag.RetrievalAugmentor;

Basic Usage

// Define a simple agent interface
public interface GreetingAgent {
    @Agent(description = "Generates personalized greetings", outputKey = "greeting")
    String greet(@V("name") String name, @V("language") String language);

    @ChatModelSupplier
    static ChatModel chatModel() {
        return new OpenAiChatModel.builder()
            .apiKey("your-api-key")
            .modelName("gpt-4")
            .build();
    }
}

// Inject and use the agent in your application
@ApplicationScoped
public class GreetingService {
    @Inject
    GreetingAgent greetingAgent;

    public String greetUser(String name, String language) {
        return greetingAgent.greet(name, language);
    }
}

Multi-agent workflow example:

// Define sub-agents
public interface ResearchAgent {
    @Agent(description = "Research information on a topic", outputKey = "research")
    String research(@V("topic") String topic);
}

public interface WriterAgent {
    @Agent(description = "Write content based on research", outputKey = "content")
    String write(@V("research") String research, @V("style") String style);
}

public interface EditorAgent {
    @Agent(description = "Edit and refine content", outputKey = "finalContent")
    String edit(@V("content") String content);
}

// Compose agents in a sequence
public interface ContentCreator {
    @SequenceAgent(
        outputKey = "finalContent",
        subAgents = { ResearchAgent.class, WriterAgent.class, EditorAgent.class }
    )
    ResultWithAgenticScope<String> createContent(@V("topic") String topic, @V("style") String style);
}

Architecture

The Quarkus LangChain4j Agentic extension is built around several key architectural components:

Declarative Agent Definition: Define agents using Java interfaces with annotations, eliminating boilerplate
Build-Time Processing: Agent interfaces are processed at build time, generating synthetic CDI beans for runtime use
CDI Integration: Agents are seamlessly integrated with Quarkus dependency injection, accessible via @Inject
Agent Composition: Complex workflows composed from simpler agent building blocks (supervisor, sequence, parallel, loop, conditional, planner)
Shared State Management: AgenticScope provides shared state across agents in a workflow
Runtime Initialization: Agents are created lazily at runtime with proper ChatModel resolution and tool provider integration
Native Image Support: Full GraalVM native image compilation support with build-time reflection registration

Capabilities

Basic Agent Definition

Define standalone AI agents with custom prompts, tools, and configuration. Suitable for single-purpose agents that perform specific tasks.

@Agent(description = "Description of agent", outputKey = "key")
ReturnType methodName(@V("varName") ParamType param);

Agent Definition

Multi-Agent Orchestration

Coordinate multiple agents using supervisor, sequence, parallel, loop, conditional, and planner patterns. Enables complex workflows and agent collaboration.

@SupervisorAgent(
    subAgents = { Agent1.class, Agent2.class }
)
String coordinate(@V("request") String request);

@SequenceAgent(outputKey = "result", subAgents = { Agent1.class, Agent2.class })
String execute(@V("input") String input);

@ParallelAgent(outputKey = "results", subAgents = { Agent1.class, Agent2.class })
String processInParallel(@V("input") String input);

@LoopAgent(
    description = "Repeat until condition met",
    outputKey = "result",
    maxIterations = 5,
    subAgents = { EvaluatorAgent.class, RefinementAgent.class }
)
String refineUntilReady(@V("input") String input);

@ConditionalAgent(
    outputKey = "result",
    subAgents = { OptionA.class, OptionB.class, OptionC.class }
)
String route(@V("input") String input);

@PlannerAgent(
    description = "Plans and executes complex tasks",
    outputKey = "result",
    subAgents = { Task1.class, Task2.class, Task3.class }
)
String plan(@V("goal") String goal);

Multi-Agent Orchestration

Resource Suppliers

Provide ChatModels, ChatMemory, Tools, ContentRetrievers, and other resources to agents via static supplier methods.

@ChatModelSupplier
static ChatModel chatModel();

@ChatMemorySupplier
static ChatMemory chatMemory();

@ChatMemoryProviderSupplier
static ChatMemory chatMemoryProvider(Object memoryId);

@ToolsSupplier
static Object[] tools();

@ToolProviderSupplier
static ToolProvider toolProvider();

@ContentRetrieverSupplier
static ContentRetriever contentRetriever();

@RetrievalAugmentorSupplier
static RetrievalAugmentor retrievalAugmentor();

@ParallelExecutor
static Executor executor();

@HumanInTheLoopResponseSupplier
static String getHumanResponse();

Resource Suppliers

Lifecycle and Control Flow

Control agent execution with activation conditions, exit conditions, error handlers, and human-in-the-loop integration.

@ActivationCondition(SubAgentClass.class)
static boolean shouldActivate(@V("condition") ConditionType condition);

@ExitCondition
static boolean shouldExit(@V("metric") double metric);

@ErrorHandler
static ErrorRecoveryResult handleError(ErrorContext context);

@HumanInTheLoop
static void requestHumanInput(@V("data") DataType data);

@Output
void processOutput(@V("result") ResultType result);

@SupervisorRequest
static String buildRequest(@V("input") InputType input);

Lifecycle and Control Flow

Shared State and Scope

Access and manipulate shared state across agents in a workflow using AgenticScope, enabling data flow between agents.

interface AgenticScope {
    <T> T readState(String key);
    <T> T readState(String key, T defaultValue);
    <T> void writeState(String key, T value);
}

class ResultWithAgenticScope<T> {
    T result();
    AgenticScope agenticScope();
}

interface AgenticScopeAccess {
    AgenticScope agenticScope();
}

Shared State and Scope

Error Handling and Recovery

Handle errors gracefully with error context information and recovery strategies (retry or throw).

interface ErrorContext {
    String agentName();
    Throwable exception();
    AgenticScope agenticScope();
}

class ErrorRecoveryResult {
    static ErrorRecoveryResult retry();
    static ErrorRecoveryResult throwException();
}

Error Handling

Memory and Parameter Management

Manage chat memory isolation and parameter passing using @MemoryId and @V annotations.

@Agent
String chat(@MemoryId String userId, @V("message") String message);

@Agent
String process(@V("input") String input, @V("context") String context);

Memory and Parameters

Runtime Support Classes

Low-level runtime classes for agent creation metadata and initialization (typically used internally by the extension).

public record AiAgentCreateInfo(String agentClassName, ChatModelInfo chatModelInfo) {
    sealed interface ChatModelInfo {
        final class FromAnnotation implements ChatModelInfo { }
        record FromBeanWithName(String name) implements ChatModelInfo { }
    }
}

@Recorder
public class AgenticRecorder {
    @StaticInit
    public void setAgentsWithMcpToolBox(Set<String> agentsWithMcpToolBox);

    @RuntimeInit
    public Function<SyntheticCreationalContext<Object>, Object> createAiAgent(AiAgentCreateInfo info);
}

Runtime Support

Types

Common LangChain4j Types

The extension uses standard LangChain4j types throughout:

// Chat model interface
interface ChatModel {
    ChatResponse doChat(ChatRequest request);
}

// Chat memory interface
interface ChatMemory {
    void add(ChatMessage message);
    List<ChatMessage> messages();
}

// Tool provider interface
interface ToolProvider {
    Collection<ToolSpecification> provideTools(Object context);
}

// Content retriever interface
interface ContentRetriever {
    List<Content> retrieve(Query query);
}

// Retrieval augmentor interface
interface RetrievalAugmentor {
    ChatMessage augment(UserMessage userMessage, List<ChatMessage> chatMemory);
}

// UserMessage structure (for custom implementations)
class UserMessage extends ChatMessage {
    List<Content> contents();  // Access message contents
    String name();              // Optional user name
}

// TextContent for extracting text from UserMessage
class TextContent implements Content {
    String text();  // Extract text content
}

// Metadata for RAG and content retrieval (package: dev.langchain4j.data.document)
class Metadata {
    // Create metadata with single key-value pair
    static Metadata from(String key, String value);
    static Metadata from(String key, Object value);

    // Create metadata from map
    static Metadata from(Map<String, String> map);

    // Note: Metadata.from() does NOT support varargs
    // For multiple key-value pairs, use a Map or chain put() calls
}

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-agentic@1.7.0

Workspace: tessl
Visibility: Public
Created: 5 days ago
Last updated: 5 days ago
Describes: pkg:maven/io.quarkiverse.langchain4j/quarkus-langchain4j-agentic@1.7.x