Class AgentBuilder<T, B extends AgentBuilder<T,?>>

java.lang.Object
dev.langchain4j.agentic.agent.AgentBuilder<T,B>
Direct Known Subclasses:
UntypedAgentBuilder
public class AgentBuilder<T, B extends AgentBuilder<T,?>> extends Object

  • Constructor Details

    • AgentBuilder

      public AgentBuilder(Class<T> agentServiceClass)

  • Method Details

    • withoutDeclarativeConfiguration

      public static <T> AgentBuilder<T, AgentBuilder<T,?>> withoutDeclarativeConfiguration(Class<T> agentServiceClass)

    • build

      public T build()

    • interfacesToImplement

      public static Class[] interfacesToImplement(Class clazz)

    • build

      protected void build(DefaultAgenticScope agenticScope, AiServiceContext context, AiServices<T> aiServices)

    • chatModel

      public B chatModel(ChatModel model)
      Sets the ChatModel used by this agent.
      Parameters:
      model - the chat model
      Returns:
      this

    • streamingChatModel

      public B streamingChatModel(StreamingChatModel streamingChatModel)
      Sets the StreamingChatModel used by this agent.
      Parameters:
      streamingChatModel - the streaming chat model
      Returns:
      this

    • chatModel

      public B chatModel(Function<AgenticScope, ChatModel> chatModelProvider)
      Sets a provider that resolves the ChatModel from the AgenticScope at execution time.
      Parameters:
      chatModelProvider - the chat model provider function
      Returns:
      this

    • streamingChatModel

      public B streamingChatModel(Function<AgenticScope, StreamingChatModel> streamingChatModelProvider)
      Sets a provider that resolves the StreamingChatModel from the AgenticScope at execution time.
      Parameters:
      streamingChatModelProvider - the streaming chat model provider function
      Returns:
      this

    • chatMemory

      public B chatMemory(ChatMemory chatMemory)
      Sets the ChatMemory used to maintain conversation history for this agent.
      Parameters:
      chatMemory - the chat memory
      Returns:
      this

    • chatMemoryProvider

      public B chatMemoryProvider(ChatMemoryProvider chatMemoryProvider)
      Sets a ChatMemoryProvider for creating per-user or per-session chat memory instances.
      Parameters:
      chatMemoryProvider - the chat memory provider
      Returns:
      this

    • tools

      public B tools(Object... objectsWithTools)
      Sets the tool objects whose @Tool-annotated methods will be available to this agent.
      Parameters:
      objectsWithTools - the objects containing tool methods
      Returns:
      this

    • tools

      public B tools(Map<ToolSpecification, ToolExecutor> toolsMap)
      Sets the tool specifications and their executors available to this agent.
      Parameters:
      toolsMap - the map of tool specifications to executors
      Returns:
      this

    • tools

      public B tools(Map<ToolSpecification, ToolExecutor> toolsMap, Set<String> immediateReturnToolNames)
      Sets the tool specifications and their executors, with a set of tool names that cause immediate return.
      Parameters:
      toolsMap - the map of tool specifications to executors
      immediateReturnToolNames - tool names whose results are returned immediately without further LLM calls
      Returns:
      this

    • toolProvider

      public B toolProvider(ToolProvider toolProvider)
      Adds a ToolProvider that dynamically supplies tools to this agent.
      Parameters:
      toolProvider - the tool provider
      Returns:
      this

    • toolProviders

      public B toolProviders(Collection<ToolProvider> toolProviders)
      Adds multiple ToolProvider instances that dynamically supply tools to this agent.
      Parameters:
      toolProviders - the collection of tool providers
      Returns:
      this

    • toolProviders

      public B toolProviders(ToolProvider... toolProviders)
      Adds multiple ToolProvider instances that dynamically supply tools to this agent (varargs overload).
      Parameters:
      toolProviders - the tool providers
      Returns:
      this

    • maxToolCallingRoundTrips

      public B maxToolCallingRoundTrips(int maxToolCallingRoundTrips)
      Sets the maximum number of tool-calling round trips the agent may perform in a single invocation.
      Parameters:
      maxToolCallingRoundTrips - the maximum number of round trips
      Returns:
      this

    • maxSequentialToolsInvocations

      @Deprecated(since="1.15.0") public B maxSequentialToolsInvocations(int maxSequentialToolsInvocations)
      Deprecated.
      Use maxToolCallingRoundTrips(int) instead.

    • hallucinatedToolNameStrategy

      public B hallucinatedToolNameStrategy(Function<ToolExecutionRequest, ToolExecutionResultMessage> hallucinatedToolNameStrategy)
      Sets the strategy for handling tool calls when the model hallucinates a non-existent tool name.
      Parameters:
      hallucinatedToolNameStrategy - the function that produces a result message for the hallucinated tool call
      Returns:
      this

    • contentRetriever

      public B contentRetriever(ContentRetriever contentRetriever)
      Sets the ContentRetriever used for RAG (Retrieval-Augmented Generation).
      Parameters:
      contentRetriever - the content retriever
      Returns:
      this

    • retrievalAugmentor

      public B retrievalAugmentor(RetrievalAugmentor retrievalAugmentor)
      Sets the RetrievalAugmentor for advanced RAG pipelines.
      Parameters:
      retrievalAugmentor - the retrieval augmentor
      Returns:
      this

    • inputGuardrailsConfig

      public B inputGuardrailsConfig(InputGuardrailsConfig inputGuardrailsConfig)
      Sets the configuration for input guardrails applied before sending requests to the model.
      Parameters:
      inputGuardrailsConfig - the input guardrails configuration
      Returns:
      this

    • outputGuardrailsConfig

      public B outputGuardrailsConfig(OutputGuardrailsConfig outputGuardrailsConfig)
      Sets the configuration for output guardrails applied after receiving responses from the model.
      Parameters:
      outputGuardrailsConfig - the output guardrails configuration
      Returns:
      this

    • inputGuardrailClasses

      public <I extends InputGuardrail> B inputGuardrailClasses(Class<? extends I>... inputGuardrailClasses)
      Sets the input guardrail classes to be instantiated and applied before each request.
      Type Parameters:
      I - the guardrail type
      Parameters:
      inputGuardrailClasses - the input guardrail classes
      Returns:
      this

    • outputGuardrailClasses

      public <O extends OutputGuardrail> B outputGuardrailClasses(Class<? extends O>... outputGuardrailClasses)
      Sets the output guardrail classes to be instantiated and applied after each response.
      Type Parameters:
      O - the guardrail type
      Parameters:
      outputGuardrailClasses - the output guardrail classes
      Returns:
      this

    • inputGuardrails

      public <I extends InputGuardrail> B inputGuardrails(I... inputGuardrails)
      Sets the input guardrail instances applied before each request.
      Type Parameters:
      I - the guardrail type
      Parameters:
      inputGuardrails - the input guardrails
      Returns:
      this

    • outputGuardrails

      public <O extends OutputGuardrail> B outputGuardrails(O... outputGuardrails)
      Sets the output guardrail instances applied after each response.
      Type Parameters:
      O - the guardrail type
      Parameters:
      outputGuardrails - the output guardrails
      Returns:
      this

    • name

      public B name(String name)
      Sets the agent name used for identification in multi-agent systems.
      Parameters:
      name - the agent name
      Returns:
      this

    • description

      public B description(String description)
      Sets a human-readable description of what this agent does, used by planners and orchestrators.
      Parameters:
      description - the agent description
      Returns:
      this

    • outputKey

      public B outputKey(String outputKey)
      Sets the key under which this agent's output is stored in the AgenticScope.
      Parameters:
      outputKey - the output key name
      Returns:
      this

    • outputKey

      public B outputKey(Class<? extends TypedKey<?>> outputKey)
      Sets the output key using a TypedKey class for type-safe scope access.
      Parameters:
      outputKey - the typed key class
      Returns:
      this

    • async

      public B async(boolean async)
      Controls whether this agent executes asynchronously within an agentic system.
      Parameters:
      async - true to run asynchronously
      Returns:
      this

    • optional

      public B optional(boolean optional)
      Controls whether this agent is optional, allowing the system to skip it if it fails.
      Parameters:
      optional - true to mark the agent as optional
      Returns:
      this

    • context

      public B context(Function<AgenticScope, String> contextProvider)
      Sets a function that provides additional context from the AgenticScope to this agent's prompt.
      Parameters:
      contextProvider - the context provider function
      Returns:
      this

    • summarizedContext

      public B summarizedContext(String... contextProvidingAgents)
      Sets the names of other agents whose outputs are summarized and injected as context into this agent's prompt.
      Parameters:
      contextProvidingAgents - the names of agents whose outputs to summarize
      Returns:
      this

    • systemMessage

      public B systemMessage(String systemMessage)
      Sets a static system message for this agent.
      Parameters:
      systemMessage - the system message text
      Returns:
      this

    • systemMessageProvider

      public B systemMessageProvider(Function<Object,String> systemMessageProvider)
      Sets a function that dynamically provides the system message based on the user message object.
      Parameters:
      systemMessageProvider - the system message provider function
      Returns:
      this

    • userMessage

      public B userMessage(String userMessage)
      Sets a static user message for this agent.
      Parameters:
      userMessage - the user message text
      Returns:
      this

    • userMessageProvider

      public B userMessageProvider(Function<Object,String> userMessageProvider)
      Sets a function that dynamically provides the user message based on the user message object.
      Parameters:
      userMessageProvider - the user message provider function
      Returns:
      this

    • systemMessageTransformer

      public B systemMessageTransformer(UnaryOperator<String> systemMessageTransformer)
      Sets a transformer that modifies the system message before it is sent to the model.
      Parameters:
      systemMessageTransformer - the system message transformer
      Returns:
      this

    • systemMessageTransformer

      public B systemMessageTransformer(BiFunction<String, InvocationContext, String> systemMessageTransformer)
      Sets a transformer that modifies the system message using both the message and the invocation context.
      Parameters:
      systemMessageTransformer - the system message transformer with context
      Returns:
      this

    • executeToolsConcurrently

      public B executeToolsConcurrently()
      Enables concurrent execution of tool calls using the default executor.
      Returns:
      this

    • executeToolsConcurrently

      public B executeToolsConcurrently(Executor executor)
      Enables concurrent execution of tool calls using the provided executor.
      Parameters:
      executor - the executor to use for concurrent tool execution
      Returns:
      this

    • toolArgumentsErrorHandler

      public B toolArgumentsErrorHandler(ToolArgumentsErrorHandler toolArgumentsErrorHandler)
      Sets the handler invoked when the model provides invalid arguments for a tool call.
      Parameters:
      toolArgumentsErrorHandler - the tool arguments error handler
      Returns:
      this

    • toolExecutionErrorHandler

      public B toolExecutionErrorHandler(ToolExecutionErrorHandler toolExecutionErrorHandler)
      Sets the handler invoked when a tool execution throws an exception.
      Parameters:
      toolExecutionErrorHandler - the tool execution error handler
      Returns:
      this

    • defaultKeyValue

      public B defaultKeyValue(String key, Object value)
      Sets a default value for an agent argument identified by key name.
      Parameters:
      key - the argument key name
      value - the default value
      Returns:
      this

    • defaultKeyValue

      public <K> B defaultKeyValue(Class<? extends TypedKey<K>> key, K value)
      Sets a default value for an agent argument identified by a TypedKey class.
      Type Parameters:
      K - the value type
      Parameters:
      key - the typed key class
      value - the default value
      Returns:
      this

    • agentInstanceFactory

      public B agentInstanceFactory(Function<InternalAgent, Object> factory)
      Sets a custom factory for creating the agent proxy instance.
      Parameters:
      factory - the agent instance factory
      Returns:
      this

    • listener

      public B listener(AgentListener agentListener)
      Adds an AgentListener for observability and lifecycle hooks.
      Parameters:
      agentListener - the agent listener
      Returns:
      this