CtrlK
BlogDocsLog inGet started
Tessl Logo

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

runtime-support.mddocs/

Runtime Support

This document describes the low-level runtime classes for agent creation metadata and initialization. These classes are typically used internally by the extension but are part of the public API.

Capabilities

AI Agent Create Info

Container record for agent creation metadata, used during agent instantiation at runtime.

/**
 * Metadata for creating an AI agent
 *
 * @param agentClassName - Fully qualified name of the agent class
 * @param chatModelInfo - Information about the chat model configuration
 */
public record AiAgentCreateInfo(String agentClassName, ChatModelInfo chatModelInfo) {
}

Package: io.quarkiverse.langchain4j.agentic.runtime

Usage Context: This record is created during build-time processing and used at runtime to instantiate agents.

Chat Model Info Interface

Sealed interface representing different ways to configure the chat model for an agent.

/**
 * Sealed interface for chat model configuration
 * Permits two implementations: FromAnnotation and FromBeanWithName
 */
public sealed interface ChatModelInfo
    permits ChatModelInfo.FromAnnotation, ChatModelInfo.FromBeanWithName {
}

Package: io.quarkiverse.langchain4j.agentic.runtime.AiAgentCreateInfo

From Annotation

Marker class indicating the chat model is provided via @ChatModelSupplier annotation.

/**
 * Indicates chat model comes from @ChatModelSupplier annotation
 */
final class FromAnnotation implements ChatModelInfo {
}

Usage: When an agent interface defines a @ChatModelSupplier method, FromAnnotation is used to signal this at runtime.

Example:

public interface MyAgent {
    @Agent
    String process(@V("input") String input);

    @ChatModelSupplier  // Triggers FromAnnotation
    static ChatModel chatModel() {
        return new OpenAiChatModel.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .modelName("gpt-4")
            .build();
    }
}

From Bean With Name

Record specifying a named CDI bean to resolve the chat model.

/**
 * Indicates chat model should be resolved from a named CDI bean
 *
 * @param name - Name of the CDI bean providing the ChatModel
 */
record FromBeanWithName(String name) implements ChatModelInfo {
}

Usage: When an agent should use a specific named ChatModel bean from CDI, FromBeanWithName specifies the bean name.

Example:

// Configuration specifies a named chat model bean
// Extension creates AiAgentCreateInfo with FromBeanWithName("customModel")

@ApplicationScoped
public class ChatModelProducer {
    @Produces
    @Named("customModel")
    public ChatModel customChatModel() {
        return new OpenAiChatModel.builder()
            .apiKey(System.getenv("CUSTOM_API_KEY"))
            .modelName("gpt-4-turbo")
            .build();
    }
}

Agentic Recorder

Quarkus recorder for runtime initialization of AI agents, handling CDI integration and agent instantiation.

/**
 * Quarkus recorder for agentic runtime initialization
 * Annotated with @Recorder to participate in Quarkus build/runtime phases
 */
@Recorder
public class AgenticRecorder {
    /**
     * Registers agents that should have MCP ToolBox support
     * Called during static initialization phase
     *
     * @param agentsWithMcpToolBox - Set of fully qualified agent class names
     */
    @StaticInit
    public void setAgentsWithMcpToolBox(Set<String> agentsWithMcpToolBox);

    /**
     * Creates an AI agent at runtime
     * Called during runtime initialization phase
     *
     * @param info - Agent creation metadata
     * @return Function that creates the agent when invoked with CDI context
     */
    @RuntimeInit
    public Function<SyntheticCreationalContext<Object>, Object> createAiAgent(
        AiAgentCreateInfo info
    );
}

Package: io.quarkiverse.langchain4j.agentic.runtime

Usage Context: This recorder is called by the extension's build-time processor to set up agents at runtime. Application code does not typically interact with this class directly.

setAgentsWithMcpToolBox

Registers which agents should have MCP (Model Context Protocol) ToolBox integration.

/**
 * Registers agents requiring MCP ToolBox support
 * Static initialization method - runs at build time
 *
 * @param agentsWithMcpToolBox - Unmodifiable set of agent class names
 */
@StaticInit
public void setAgentsWithMcpToolBox(Set<String> agentsWithMcpToolBox);

Behavior:

  • Stores agent class names that need MCP ToolBox
  • Called during Quarkus static initialization
  • Agent names stored as fully qualified class names

Example Internal Usage:

// Called by extension processor
recorder.setAgentsWithMcpToolBox(Set.of(
    "com.example.MyAgentWithMcpTools",
    "com.example.AnotherAgentWithMcp"
));

createAiAgent

Creates an AI agent at runtime with proper CDI context integration.

/**
 * Creates an AI agent at runtime
 * Runtime initialization method
 *
 * @param info - Metadata containing agent class name and chat model info
 * @return Function accepting CDI context and returning agent instance
 */
@RuntimeInit
public Function<SyntheticCreationalContext<Object>, Object> createAiAgent(
    AiAgentCreateInfo info
);

Behavior:

  1. Resolves the ChatModel based on ChatModelInfo:
    • FromAnnotation: ChatModel provided via @ChatModelSupplier
    • FromBeanWithName: Injects named ChatModel bean from CDI
  2. Loads the agent class using the thread context class loader
  3. Invokes AgenticServices.createAgenticSystem() from LangChain4j
  4. If agent is registered for MCP, injects ToolProvider from CDI

Example Internal Usage:

// Called by extension processor
AiAgentCreateInfo info = new AiAgentCreateInfo(
    "com.example.MyAgent",
    new AiAgentCreateInfo.ChatModelInfo.FromBeanWithName("defaultChatModel")
);

Function<SyntheticCreationalContext<Object>, Object> agentFactory =
    recorder.createAiAgent(info);

// Factory is used by CDI to create agent instances

Planner Agent Prompt Template Content Filter Provider

SPI implementation that filters prompt template content for PlannerAgent, ensuring compatibility with Qute templating.

/**
 * Content filter provider for PlannerAgent prompt templates
 * Implements Quarkus SPI for prompt template processing
 */
public class PlannerAgentPromptTemplateContentFilterProvider
    implements PromptTemplateFactoryContentFilterProvider {

    /**
     * Returns a content filter function for template processing
     *
     * @return Function that transforms template content
     */
    public Function<String, String> getContentFilter();
}

Package: io.quarkiverse.langchain4j.agentic.runtime

Purpose: Transforms LangChain4j prompt template syntax to Qute-compatible syntax for PlannerAgent templates.

SPI Registration: Registered via META-INF/services/io.quarkiverse.langchain4j.spi.PromptTemplateFactoryContentFilterProvider

Example Internal Behavior:

// Replaces incompatible syntax
String template = """
    Plan the following task: {task}
    """;

// After filtering:
String filtered = """
    Plan the following task: {{task}}
    """;

Runtime Lifecycle

Understanding how these components work together:

Build Time

  1. Agent Detection: AgenticProcessor scans for @Agent annotations
  2. Metadata Creation: Creates AiAgentCreateInfo for each agent
  3. MCP Registration: Identifies agents needing MCP ToolBox
  4. Recorder Invocation: Calls setAgentsWithMcpToolBox() and createAiAgent()

Runtime Initialization

  1. Static Init: setAgentsWithMcpToolBox() stores MCP-enabled agents
  2. Runtime Init: createAiAgent() creates agent factories
  3. CDI Integration: Factories registered as synthetic bean producers

Runtime Execution

  1. Bean Request: Application injects agent interface
  2. Factory Invocation: CDI calls agent factory function
  3. ChatModel Resolution: Factory resolves ChatModel (annotation or CDI)
  4. Agent Creation: LangChain4j AgenticServices creates agent instance
  5. ToolProvider Injection: If MCP-enabled, injects ToolProvider
  6. Proxy Return: Returns agent proxy to application

Advanced Usage

Custom Chat Model Configuration

While not common, you can programmatically work with these classes:

import io.quarkiverse.langchain4j.agentic.runtime.AiAgentCreateInfo;
import io.quarkiverse.langchain4j.agentic.runtime.AiAgentCreateInfo.ChatModelInfo;

// Example: Understanding agent creation metadata
public class AgentInspector {
    public void inspectAgent(AiAgentCreateInfo info) {
        System.out.println("Agent class: " + info.agentClassName());

        ChatModelInfo modelInfo = info.chatModelInfo();
        if (modelInfo instanceof ChatModelInfo.FromAnnotation) {
            System.out.println("Chat model from @ChatModelSupplier");
        } else if (modelInfo instanceof ChatModelInfo.FromBeanWithName bean) {
            System.out.println("Chat model from CDI bean: " + bean.name());
        }
    }
}

Understanding Extension Processing

The runtime support classes are part of the Quarkus extension architecture:

┌─────────────────────┐
│   Application Code  │
│  (Agent Interfaces) │
└──────────┬──────────┘
           │
           │ @Agent, @SupervisorAgent, etc.
           │
┌──────────▼──────────┐
│  AgenticProcessor   │  (Build Time)
│  (deployment module)│
└──────────┬──────────┘
           │
           │ Creates AiAgentCreateInfo
           │ Invokes AgenticRecorder
           │
┌──────────▼──────────┐
│  AgenticRecorder    │  (Runtime)
│    (runtime module) │
└──────────┬──────────┘
           │
           │ Registers with CDI
           │
┌──────────▼──────────┐
│   CDI Container     │
└──────────┬──────────┘
           │
           │ Injects agents
           │
┌──────────▼──────────┐
│  Application Code   │
│   (Agent Usage)     │
└─────────────────────┘

Extension Configuration

While these classes are internal, understanding them helps with extension configuration:

# Quarkus configuration affecting agent runtime behavior

# Default chat model configuration
quarkus.langchain4j.openai.api-key=${OPENAI_API_KEY}
quarkus.langchain4j.openai.model-name=gpt-4

# Named chat model configurations
quarkus.langchain4j.openai.custom.api-key=${CUSTOM_API_KEY}
quarkus.langchain4j.openai.custom.model-name=gpt-4-turbo
quarkus.langchain4j.openai.custom.temperature=0.7

# MCP ToolBox configuration (when using MCP integration)
# ...additional MCP-specific settings...

Summary

These runtime support classes form the foundation of the agentic extension:

  • AiAgentCreateInfo: Carries agent metadata from build to runtime
  • ChatModelInfo: Encodes chat model configuration strategy
  • AgenticRecorder: Bridges build-time processing with runtime execution
  • PlannerAgentPromptTemplateContentFilterProvider: Ensures template compatibility

Application developers rarely interact with these classes directly—they work behind the scenes to enable the declarative agent programming model.

Install with Tessl CLI

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

docs

agent-definition.md

error-handling.md

index.md

lifecycle-control.md

memory-parameters.md

multi-agent-orchestration.md

resource-suppliers.md

runtime-support.md

scope-state.md

tile.json