This is an automated email from the ASF dual-hosted git repository. orpiske pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/camel.git
commit 6605142b28a0dc520fcbc6168cee934157b03cb3 Author: Otavio Rodolfo Piske <[email protected]> AuthorDate: Fri Aug 8 14:09:47 2025 +0200 CAMEL-22326: increase documentation for the API classes --- .../component/langchain4j/agent/api/Agent.java | 41 ++++++- .../langchain4j/agent/api/AgentConfiguration.java | 123 ++++++++++++++++++++- .../langchain4j/agent/api/AgentFactory.java | 28 ++++- .../langchain4j/agent/api/AiAgentBody.java | 119 ++++++++++++++++++++ 4 files changed, 295 insertions(+), 16 deletions(-) diff --git a/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/Agent.java b/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/Agent.java index a47733db526..fff853701a7 100644 --- a/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/Agent.java +++ b/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/Agent.java @@ -19,18 +19,47 @@ package org.apache.camel.component.langchain4j.agent.api; import dev.langchain4j.service.tool.ToolProvider; /** - * Agent interface that abstracts the different types of AI agents (with or without memory). This interface provides a - * unified way to interact with AI agents regardless of their underlying implementation details. + * Core agent interface that abstracts different types of AI agents within the Apache Camel LangChain4j integration. * - * This is an internal interface used only within the LangChain4j agent component. + * <p> + * This interface provides a unified abstraction for interacting with AI agents, regardless of whether they support + * memory persistence or operate in a stateless manner. It serves as the primary contract for chat interactions between + * Camel routes and LangChain4j AI services. + * </p> + * + * <p> + * Implementations handle the complexity of configuring LangChain4j AI services, including: + * </p> + * <ul> + * <li>Chat model integration</li> + * <li>Memory management (for stateful agents)</li> + * <li>Tool provider integration</li> + * <li>Retrieval-Augmented Generation (RAG) support</li> + * <li>Input and output guardrails</li> + * </ul> + * + * @since 4.9.0 + * @see AgentWithMemory + * @see AgentWithoutMemory */ public interface Agent { /** - * Executes a chat interaction with the AI agent using the provided body. + * Executes a chat interaction with the AI agent using the provided request body and tool provider. + * + * <p> + * This method processes user messages and optional system messages through the configured LangChain4j AI service. + * For agents with memory support, the memory ID in the request body is used to maintain conversation context across + * multiple interactions. + * </p> * - * @param aiAgentBody the body containing user message, system message, and memory ID - * @return the AI agent's response + * @param aiAgentBody the request body containing the user message, optional system message, and memory ID + * (for stateful agents) + * @param toolProvider the tool provider that enables the agent to execute functions and interact with external + * systems; may be {@code null} if no tools are needed + * @return the AI agent's response as a string + * @throws RuntimeException if the chat interaction fails due to model errors, configuration issues, or tool + * execution failures */ String chat(AiAgentBody aiAgentBody, ToolProvider toolProvider); diff --git a/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AgentConfiguration.java b/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AgentConfiguration.java index c7223e3fd04..83dcc70c384 100644 --- a/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AgentConfiguration.java +++ b/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AgentConfiguration.java @@ -27,6 +27,28 @@ import dev.langchain4j.rag.RetrievalAugmentor; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +/** + * Configuration class for AI agents in the Apache Camel LangChain4j integration. + * + * <p> + * This class encapsulates all the configuration parameters needed to create and configure AI agents, including chat + * models, memory providers, RAG components, and security guardrails. It provides a fluent builder-style API for easy + * configuration setup. + * </p> + * + * <p> + * Supported configuration options include: + * </p> + * <ul> + * <li><strong>Chat Model:</strong> The underlying LLM for processing conversations</li> + * <li><strong>Memory Provider:</strong> For maintaining conversation history in stateful agents</li> + * <li><strong>Retrieval Augmentor:</strong> For RAG (Retrieval-Augmented Generation) capabilities</li> + * <li><strong>Input Guardrails:</strong> Security filters applied to incoming messages</li> + * <li><strong>Output Guardrails:</strong> Security filters applied to agent responses</li> + * </ul> + * + * @since 4.9.0 + */ public class AgentConfiguration { private static final Logger LOG = LoggerFactory.getLogger(AgentConfiguration.class); @@ -36,64 +58,148 @@ public class AgentConfiguration { private List<Class<?>> inputGuardrailClasses; private List<Class<?>> outputGuardrailClasses; + /** + * Gets the configured chat model. + * + * @return the chat model instance, or {@code null} if not configured + */ public ChatModel getChatModel() { return chatModel; } + /** + * Sets the chat model for this agent configuration. + * + * @param chatModel the LangChain4j chat model to use for AI interactions + * @return this configuration instance for method chaining + */ public AgentConfiguration withChatModel(ChatModel chatModel) { this.chatModel = chatModel; return this; } + /** + * Gets the configured chat memory provider. + * + * @return the chat memory provider instance, or {@code null} if not configured + */ public ChatMemoryProvider getChatMemoryProvider() { return chatMemoryProvider; } + /** + * Sets the chat memory provider for stateful agent conversations. + * + * @param chatMemoryProvider the memory provider for maintaining conversation history + * @return this configuration instance for method chaining + */ public AgentConfiguration withChatMemoryProvider(ChatMemoryProvider chatMemoryProvider) { this.chatMemoryProvider = chatMemoryProvider; return this; } + /** + * Gets the configured retrieval augmentor for RAG (Retrieval-Augmented Generation) support. + * + * @return the retrieval augmentor instance, or {@code null} if not configured + */ public RetrievalAugmentor getRetrievalAugmentor() { return retrievalAugmentor; } + /** + * Sets the retrieval augmentor for enabling RAG (Retrieval-Augmented Generation) capabilities. + * + * @param retrievalAugmentor the retrieval augmentor to enhance responses with external knowledge + * @return this configuration instance for method chaining + */ public AgentConfiguration withRetrievalAugmentor(RetrievalAugmentor retrievalAugmentor) { this.retrievalAugmentor = retrievalAugmentor; return this; } + /** + * Gets the configured input guardrail classes for security filtering. + * + * @return the list of input guardrail classes, or {@code null} if not configured + */ public List<Class<?>> getInputGuardrailClasses() { return inputGuardrailClasses; } + /** + * Sets input guardrail classes from a comma-separated string of class names. + * + * @param inputGuardrailClasses comma-separated list of fully qualified class names + * @return this configuration instance for method chaining + * @see #parseGuardrailClasses(String) + */ public AgentConfiguration withInputGuardrailClassesList(String inputGuardrailClasses) { return withInputGuardrailClasses(parseGuardrailClasses(inputGuardrailClasses)); } + /** + * Sets input guardrail classes for security filtering of incoming messages. + * + * @param inputGuardrailClasses list of guardrail classes to apply to user inputs + * @return this configuration instance for method chaining + */ public AgentConfiguration withInputGuardrailClasses(List<Class<?>> inputGuardrailClasses) { this.inputGuardrailClasses = inputGuardrailClasses; return this; } + /** + * Gets the configured output guardrail classes for security filtering. + * + * @return the list of output guardrail classes, or {@code null} if not configured + */ public List<Class<?>> getOutputGuardrailClasses() { return outputGuardrailClasses; } + /** + * Sets output guardrail classes from a comma-separated string of class names. + * + * @param outputGuardrailClasses comma-separated list of fully qualified class names + * @return this configuration instance for method chaining + * @see #parseGuardrailClasses(String) + */ public AgentConfiguration withOutputGuardrailClassesList(String outputGuardrailClasses) { return withOutputGuardrailClasses(parseGuardrailClasses(outputGuardrailClasses)); } + /** + * Sets output guardrail classes for security filtering of agent responses. + * + * @param outputGuardrailClasses list of guardrail classes to apply to agent outputs + * @return this configuration instance for method chaining + */ public AgentConfiguration withOutputGuardrailClasses(List<Class<?>> outputGuardrailClasses) { this.outputGuardrailClasses = outputGuardrailClasses; return this; } /** - * Parse comma-separated guardrail class names into a list of loaded classes. + * Parses comma-separated guardrail class names into a list of loaded classes. + * + * <p> + * This utility method takes a string containing comma-separated fully qualified class names and attempts to load + * each class using reflection. Classes that cannot be loaded are logged as warnings and excluded from the result. + * </p> + * + * <p> + * Example usage: + * </p> * - * @param guardrailClassNames comma-separated class names, can be null or empty - * @return list of loaded classes, empty list if input is null or empty + * <pre>{@code + * List<Class<?>> classes = AgentConfiguration.parseGuardrailClasses( + * "com.example.InputFilter,com.example.OutputValidator"); + * }</pre> + * + * @param guardrailClassNames comma-separated class names, may be {@code null} or empty + * @return a list of successfully loaded classes; empty list if input is {@code null}, empty, or + * if no classes could be loaded */ public static List<Class<?>> parseGuardrailClasses(String guardrailClassNames) { if (guardrailClassNames == null || guardrailClassNames.trim().isEmpty()) { @@ -109,10 +215,15 @@ public class AgentConfiguration { } /** - * Load a guardrail class by name. + * Loads a guardrail class by its fully qualified name using reflection. + * + * <p> + * This method attempts to load the specified class using {@link Class#forName(String)}. If the class cannot be + * found, a warning is logged and {@code null} is returned. + * </p> * - * @param className the fully qualified class name - * @return the loaded class, or null if loading failed + * @param className the fully qualified class name to load + * @return the loaded {@link Class} object, or {@code null} if the class could not be found */ protected static Class<?> loadGuardrailClass(String className) { try { diff --git a/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AgentFactory.java b/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AgentFactory.java index eb46faa3b4c..e7a3659e491 100644 --- a/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AgentFactory.java +++ b/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AgentFactory.java @@ -20,15 +20,35 @@ package org.apache.camel.component.langchain4j.agent.api; import org.apache.camel.CamelContextAware; /** - * Provides a common interface for factories of agents. + * Factory interface for creating AI agent instances within the Apache Camel LangChain4j integration. + * + * <p> + * This factory provides a standardized way to create and manage AI agents, supporting both agents with memory + * capabilities and stateless agents. Implementations of this interface are responsible for configuring the underlying + * LangChain4j AI services with appropriate models, memory providers, and other necessary components. + * </p> + * + * <p> + * The factory extends {@link CamelContextAware} to ensure proper integration with the Camel context and access to + * registry components. + * </p> + * + * @since 4.9.0 */ public interface AgentFactory extends CamelContextAware { /** - * Create a new agent instance (might be cached) + * Creates a new AI agent instance configured with the appropriate settings. + * + * <p> + * Implementations may choose to cache agent instances for performance optimization, especially when the underlying + * configuration remains unchanged. The returned agent will be fully configured and ready to handle chat + * interactions. + * </p> * - * @return An agent instance - * @throws Exception if unable to create the agent + * @return a configured {@link Agent} instance ready for chat interactions + * @throws Exception if unable to create the agent due to configuration issues, missing dependencies, or + * initialization failures */ Agent createAgent() throws Exception; } diff --git a/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AiAgentBody.java b/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AiAgentBody.java index c54772c9875..06f74e42397 100644 --- a/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AiAgentBody.java +++ b/components/camel-ai/camel-langchain4j-agent-api/src/main/java/org/apache/camel/component/langchain4j/agent/api/AiAgentBody.java @@ -16,59 +16,178 @@ */ package org.apache.camel.component.langchain4j.agent.api; +/** + * Request body class for AI agent chat interactions in the Apache Camel LangChain4j integration. + * + * <p> + * This class encapsulates all the information needed for a chat interaction with an AI agent, including the user's + * message, optional system instructions, and memory identification for stateful conversations. + * </p> + * + * <p> + * The class provides both constructor-based initialization and fluent builder-style methods for convenient object + * creation and configuration. + * </p> + * + * <p> + * Usage examples: + * </p> + * + * <pre>{@code + * // Simple user message + * AiAgentBody body = new AiAgentBody("Hello, how are you?"); + * + * // With system message and memory ID + * AiAgentBody body = new AiAgentBody( + * "What's the weather like?", + * "You are a helpful weather assistant", + * "user123"); + * + * // Using fluent API + * AiAgentBody body = new AiAgentBody() + * .withUserMessage("Tell me a joke") + * .withSystemMessage("You are a comedian") + * .withMemoryId("session456"); + * }</pre> + * + * @since 4.9.0 + */ public class AiAgentBody { private String userMessage; private String systemMessage; private Object memoryId; + /** + * Creates an empty AI agent body. Use the fluent setter methods to configure the instance. + */ public AiAgentBody() { } + /** + * Creates an AI agent body with a user message. + * + * @param userMessage the message from the user + */ public AiAgentBody(String userMessage) { this.userMessage = userMessage; } + /** + * Creates an AI agent body with all parameters. + * + * @param userMessage the message from the user + * @param systemMessage the system instructions for the AI agent + * @param memoryId the identifier for conversation memory (for stateful agents) + */ public AiAgentBody(String userMessage, String systemMessage, Object memoryId) { this.userMessage = userMessage; this.systemMessage = systemMessage; this.memoryId = memoryId; } + /** + * Sets the user message and returns this instance for method chaining. + * + * @param userMessage the message from the user to send to the AI agent + * @return this AiAgentBody instance for fluent method chaining + */ public AiAgentBody withUserMessage(String userMessage) { this.userMessage = userMessage; return this; } + /** + * Sets the system message and returns this instance for method chaining. + * + * <p> + * The system message provides instructions or context to the AI agent about how it should behave or respond. This + * is optional and may be {@code null}. + * </p> + * + * @param systemMessage the system instructions for the AI agent behavior + * @return this AiAgentBody instance for fluent method chaining + */ public AiAgentBody withSystemMessage(String systemMessage) { this.systemMessage = systemMessage; return this; } + /** + * Sets the memory identifier and returns this instance for method chaining. + * + * <p> + * The memory ID is used by stateful agents to maintain conversation history across multiple interactions. Different + * memory IDs represent separate conversation sessions. This is optional and only relevant for agents with memory + * support. + * </p> + * + * @param memoryId the identifier for conversation memory (typically a string or number) + * @return this AiAgentBody instance for fluent method chaining + */ public AiAgentBody withMemoryId(Object memoryId) { this.memoryId = memoryId; return this; } + /** + * Gets the user message. + * + * @return the message from the user, or {@code null} if not set + */ public String getUserMessage() { return userMessage; } + /** + * Sets the user message. + * + * @param userMessage the message from the user to send to the AI agent + */ public void setUserMessage(String userMessage) { this.userMessage = userMessage; } + /** + * Gets the system message. + * + * @return the system instructions for the AI agent, or {@code null} if not set + */ public String getSystemMessage() { return systemMessage; } + /** + * Sets the system message. + * + * <p> + * The system message provides instructions or context to the AI agent about how it should behave or respond. + * </p> + * + * @param systemMessage the system instructions for the AI agent behavior + */ public void setSystemMessage(String systemMessage) { this.systemMessage = systemMessage; } + /** + * Gets the memory identifier. + * + * @return the identifier for conversation memory, or {@code null} if not set + */ public Object getMemoryId() { return memoryId; } + /** + * Sets the memory identifier. + * + * <p> + * The memory ID is used by stateful agents to maintain conversation history across multiple interactions. Different + * memory IDs represent separate conversation sessions. + * </p> + * + * @param memoryId the identifier for conversation memory (typically a string or number) + */ public void setMemoryId(Object memoryId) { this.memoryId = memoryId; }
