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 Summary

    Constructors
    Constructor
    Description
    AgentBuilder(Class<T> agentServiceClass)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    B
    agentInstanceFactory(Function<InternalAgent, Object> factory)
    Sets a custom factory for creating the agent proxy instance.
    B
    async(boolean async)
    Controls whether this agent executes asynchronously within an agentic system.
    T
    build()
     
    protected void
    build(DefaultAgenticScope agenticScope, dev.langchain4j.service.AiServiceContext context, dev.langchain4j.service.AiServices<T> aiServices)
     
    B
    chatMemory(dev.langchain4j.memory.ChatMemory chatMemory)
    Sets the ChatMemory used to maintain conversation history for this agent.
    B
    chatMemoryProvider(dev.langchain4j.memory.chat.ChatMemoryProvider chatMemoryProvider)
    Sets a ChatMemoryProvider for creating per-user or per-session chat memory instances.
    B
    chatModel(dev.langchain4j.model.chat.ChatModel model)
    Sets the ChatModel used by this agent.
    B
    chatModel(Function<AgenticScope, dev.langchain4j.model.chat.ChatModel> chatModelProvider)
    Sets a provider that resolves the ChatModel from the AgenticScope at execution time.
    B
    contentRetriever(dev.langchain4j.rag.content.retriever.ContentRetriever contentRetriever)
    Sets the ContentRetriever used for RAG (Retrieval-Augmented Generation).
    B
    context(Function<AgenticScope, String> contextProvider)
    Sets a function that provides additional context from the AgenticScope to this agent's prompt.
    <K> B
    defaultKeyValue(Class<? extends TypedKey<K>> key, K value)
    Sets a default value for an agent argument identified by a TypedKey class.
    B
    defaultKeyValue(String key, Object value)
    Sets a default value for an agent argument identified by key name.
    B
    description(String description)
    Sets a human-readable description of what this agent does, used by planners and orchestrators.
    B
    executeToolsConcurrently()
    Enables concurrent execution of tool calls using the default executor.
    B
    executeToolsConcurrently(Executor executor)
    Enables concurrent execution of tool calls using the provided executor.
    B
    hallucinatedToolNameStrategy(Function<dev.langchain4j.agent.tool.ToolExecutionRequest, dev.langchain4j.data.message.ToolExecutionResultMessage> hallucinatedToolNameStrategy)
    Sets the strategy for handling tool calls when the model hallucinates a non-existent tool name.
    <I extends dev.langchain4j.guardrail.InputGuardrail>
    B
    inputGuardrailClasses(Class<? extends I>... inputGuardrailClasses)
    Sets the input guardrail classes to be instantiated and applied before each request.
    <I extends dev.langchain4j.guardrail.InputGuardrail>
    B
    inputGuardrails(I... inputGuardrails)
    Sets the input guardrail instances applied before each request.
    B
    inputGuardrailsConfig(dev.langchain4j.guardrail.config.InputGuardrailsConfig inputGuardrailsConfig)
    Sets the configuration for input guardrails applied before sending requests to the model.
    static Class[]
    interfacesToImplement(Class clazz)
     
    B
    listener(AgentListener agentListener)
    Adds an AgentListener for observability and lifecycle hooks.
    B
    maxSequentialToolsInvocations(int maxSequentialToolsInvocations)
    Deprecated.
    Use maxToolCallingRoundTrips(int) instead.
    B
    maxToolCallingRoundTrips(int maxToolCallingRoundTrips)
    Sets the maximum number of tool-calling round trips the agent may perform in a single invocation.
    B
    name(String name)
    Sets the agent name used for identification in multi-agent systems.
    B
    optional(boolean optional)
    Controls whether this agent is optional, allowing the system to skip it if it fails.
    <O extends dev.langchain4j.guardrail.OutputGuardrail>
    B
    outputGuardrailClasses(Class<? extends O>... outputGuardrailClasses)
    Sets the output guardrail classes to be instantiated and applied after each response.
    <O extends dev.langchain4j.guardrail.OutputGuardrail>
    B
    outputGuardrails(O... outputGuardrails)
    Sets the output guardrail instances applied after each response.
    B
    outputGuardrailsConfig(dev.langchain4j.guardrail.config.OutputGuardrailsConfig outputGuardrailsConfig)
    Sets the configuration for output guardrails applied after receiving responses from the model.
    B
    outputKey(Class<? extends TypedKey<?>> outputKey)
    Sets the output key using a TypedKey class for type-safe scope access.
    B
    outputKey(String outputKey)
    Sets the key under which this agent's output is stored in the AgenticScope.
    B
    retrievalAugmentor(dev.langchain4j.rag.RetrievalAugmentor retrievalAugmentor)
    Sets the RetrievalAugmentor for advanced RAG pipelines.
    B
    streamingChatModel(dev.langchain4j.model.chat.StreamingChatModel streamingChatModel)
    Sets the StreamingChatModel used by this agent.
    B
    streamingChatModel(Function<AgenticScope, dev.langchain4j.model.chat.StreamingChatModel> streamingChatModelProvider)
    Sets a provider that resolves the StreamingChatModel from the AgenticScope at execution time.
    B
    summarizedContext(String... contextProvidingAgents)
    Sets the names of other agents whose outputs are summarized and injected as context into this agent's prompt.
    B
    systemMessage(String systemMessage)
    Sets a static system message for this agent.
    B
    systemMessageProvider(Function<Object,String> systemMessageProvider)
    Sets a function that dynamically provides the system message based on the user message object.
    B
    systemMessageTransformer(BiFunction<String, dev.langchain4j.invocation.InvocationContext, String> systemMessageTransformer)
    Sets a transformer that modifies the system message using both the message and the invocation context.
    B
    systemMessageTransformer(UnaryOperator<String> systemMessageTransformer)
    Sets a transformer that modifies the system message before it is sent to the model.
    B
    toolArgumentsErrorHandler(dev.langchain4j.service.tool.ToolArgumentsErrorHandler toolArgumentsErrorHandler)
    Sets the handler invoked when the model provides invalid arguments for a tool call.
    B
    toolExecutionErrorHandler(dev.langchain4j.service.tool.ToolExecutionErrorHandler toolExecutionErrorHandler)
    Sets the handler invoked when a tool execution throws an exception.
    B
    toolProvider(dev.langchain4j.service.tool.ToolProvider toolProvider)
    Adds a ToolProvider that dynamically supplies tools to this agent.
    B
    toolProviders(dev.langchain4j.service.tool.ToolProvider... toolProviders)
    Adds multiple ToolProvider instances that dynamically supply tools to this agent (varargs overload).
    B
    toolProviders(Collection<dev.langchain4j.service.tool.ToolProvider> toolProviders)
    Adds multiple ToolProvider instances that dynamically supply tools to this agent.
    B
    tools(Object... objectsWithTools)
    Sets the tool objects whose @Tool-annotated methods will be available to this agent.
    B
    tools(Map<dev.langchain4j.agent.tool.ToolSpecification, dev.langchain4j.service.tool.ToolExecutor> toolsMap)
    Sets the tool specifications and their executors available to this agent.
    B
    tools(Map<dev.langchain4j.agent.tool.ToolSpecification, dev.langchain4j.service.tool.ToolExecutor> toolsMap, Set<String> immediateReturnToolNames)
    Sets the tool specifications and their executors, with a set of tool names that cause immediate return.
    B
    userMessage(String userMessage)
    Sets a static user message for this agent.
    B
    userMessageProvider(Function<Object,String> userMessageProvider)
    Sets a function that dynamically provides the user message based on the user message object.
    static <T> AgentBuilder<T, AgentBuilder<T,?>>
    withoutDeclarativeConfiguration(Class<T> agentServiceClass)
     

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • 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, dev.langchain4j.service.AiServiceContext context, dev.langchain4j.service.AiServices<T> aiServices)

    • chatModel

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

    • streamingChatModel

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

    • chatModel

      public B chatModel(Function<AgenticScope, dev.langchain4j.model.chat.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, dev.langchain4j.model.chat.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(dev.langchain4j.memory.ChatMemory chatMemory)
      Sets the ChatMemory used to maintain conversation history for this agent.
      Parameters:
      chatMemory - the chat memory
      Returns:
      this

    • chatMemoryProvider

      public B chatMemoryProvider(dev.langchain4j.memory.chat.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<dev.langchain4j.agent.tool.ToolSpecification, dev.langchain4j.service.tool.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<dev.langchain4j.agent.tool.ToolSpecification, dev.langchain4j.service.tool.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(dev.langchain4j.service.tool.ToolProvider toolProvider)
      Adds a ToolProvider that dynamically supplies tools to this agent.
      Parameters:
      toolProvider - the tool provider
      Returns:
      this

    • toolProviders

      public B toolProviders(Collection<dev.langchain4j.service.tool.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(dev.langchain4j.service.tool.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<dev.langchain4j.agent.tool.ToolExecutionRequest, dev.langchain4j.data.message.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(dev.langchain4j.rag.content.retriever.ContentRetriever contentRetriever)
      Sets the ContentRetriever used for RAG (Retrieval-Augmented Generation).
      Parameters:
      contentRetriever - the content retriever
      Returns:
      this

    • retrievalAugmentor

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

    • inputGuardrailsConfig

      public B inputGuardrailsConfig(dev.langchain4j.guardrail.config.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(dev.langchain4j.guardrail.config.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 dev.langchain4j.guardrail.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 dev.langchain4j.guardrail.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 dev.langchain4j.guardrail.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 dev.langchain4j.guardrail.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, dev.langchain4j.invocation.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(dev.langchain4j.service.tool.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(dev.langchain4j.service.tool.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