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

    • toolSearchStrategy

      public B toolSearchStrategy(ToolSearchStrategy toolSearchStrategy)
      Sets the ToolSearchStrategy this agent uses to discover its tools, so that the model initially receives only the tool search tools and the tools marked as always visible, instead of every tool. Applies to the tools configured with tools(...) and to those supplied by a ToolProvider. Discovered tools stay available for the rest of the invocation and, when the agent has a chat memory, until the tool search result is evicted from it.
      Parameters:
      toolSearchStrategy - the tool search strategy
      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

    • activationCondition

      public B activationCondition(Predicate<AgenticScope> activationCondition)
      Sets the condition under which this agent runs when it is invoked as a subagent of an agentic system. When the condition is false the agent is skipped, without writing anything to the AgenticScope. The condition is ignored when this agent is invoked directly. It can be evaluated more than once, so it must be free of side effects.
      Parameters:
      activationCondition - the predicate deciding whether this agent runs
      Returns:
      this

    • activationCondition

      public B activationCondition(String description, Predicate<AgenticScope> activationCondition)
      Sets the condition under which this agent runs when it is invoked as a subagent of an agentic system. When the condition is false the agent is skipped, without writing anything to the AgenticScope. The condition is ignored when this agent is invoked directly. It can be evaluated more than once, so it must be free of side effects.
      Parameters:
      description - a human-readable description of the condition, used in logs, listeners and reports
      activationCondition - the predicate deciding whether this agent runs
      Returns:
      this

    • compensateOnError

      public B compensateOnError(boolean compensateOnError)

    • 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.

      The summary is generated by an additional, blocking call to this agent's model, made before the agent's own request. If the agent uses a StreamingChatModel, the summary is fully generated before the agent starts streaming its response.

      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