Package dyntabs.ai

Class AgentBuilder

java.lang.Object
dyntabs.ai.AgentBuilder
public class AgentBuilder extends Object
Builder for creating an EasyAgent that autonomously plans and executes multi-step tasks using your registered Java services.

Basic usage


 EasyAgent agent = EasyAI.agent()
     .withServices(inventoryService, paymentService, orderService)
     .withMaxSteps(10)
     .withPlanningPrompt(true)
     .withStepListener(step ->
         log.info("[AGENT] Step {}: {}({}) -> {}",
             step.stepNumber(), step.toolName(),
             step.arguments(), step.result()))
     .build();

 String result = agent.execute("Order 2 laptops, apply loyalty credit.");
See Also:

  • Method Details

    • withServices

      public AgentBuilder withServices(Object... services)
      Adds service objects whose public methods the agent can call.

      Accepts plain POJOs and Jakarta EJB proxies (@Stateless, @Stateful, @Singleton) obtained via @Inject. No annotations are needed on the service methods.

      
 EasyAgent agent = EasyAI.agent()
     .withServices(inventoryService, paymentService, shippingService)
     .build();
      Parameters:
      services - one or more service objects (POJOs or injected EJB proxies)
      Returns:
      this builder

    • withMaxSteps

      public AgentBuilder withMaxSteps(int maxSteps)
      Sets the maximum number of sequential service method calls the agent is allowed to make before returning a response.

      This parameter is strongly recommended. Without a limit, a complex task could trigger many sequential calls, significantly increasing token usage and cost. Default is 10 steps.

      
 EasyAgent agent = EasyAI.agent()
     .withServices(...)
     .withMaxSteps(15)   // allow up to 15 tool calls per execute()
     .build();
      Parameters:
      maxSteps - maximum number of tool calls per task (must be > 0)
      Returns:
      this builder

    • withPlanningPrompt

      public AgentBuilder withPlanningPrompt(boolean enable)
      Enables the built-in planning system message that instructs the LLM to think step by step before calling tools.

      When true, the agent receives a system message that says: "Think step by step, plan which tools to call, execute sequentially, adapt if a step fails." This improves reliability for complex, multi-step tasks with branching logic.

      If you also call withSystemMessage(String), the planning prompt is prepended to your custom message.

      
 EasyAgent agent = EasyAI.agent()
     .withServices(inventoryService, orderService)
     .withPlanningPrompt(true)
     .build();
      Parameters:
      enable - true to inject the built-in planning system message
      Returns:
      this builder

    • withStepListener

      public AgentBuilder withStepListener(StepListener stepListener)
      Registers a listener that is called after each tool execution.

      Use this to log or observe every step the agent takes. The listener receives the step number, tool name, arguments, and result.

      
 EasyAgent agent = EasyAI.agent()
     .withServices(orderService)
     .withStepListener(step ->
         log.info("[AGENT] Step {}: {}({}) -> {}",
             step.stepNumber(), step.toolName(),
             step.arguments(), step.result()))
     .build();
      Parameters:
      stepListener - the listener to call after each tool execution
      Returns:
      this builder

    • withEventListener

      public AgentBuilder withEventListener(EasyAIListener eventListener)
      Registers a transport-agnostic EasyAIListener that receives a richer, live stream of EasyAIEvents as the agent runs.

      This is the modern, library-wide observability hook shared by every EasyAI capability, and it is strictly additive to withStepListener(StepListener) — you may use either, both, or neither. Compared to the older StepListener (which fires only after each tool returns), the event listener also emits:

      Familiar analogy: StepListener is a receipt printed after each purchase; EasyAIListener is the live store-camera feed showing the whole shopping trip, including the moments between purchases.

      
 EasyAgent agent = EasyAI.agent()
     .withServices(orderService)
     .withEventListener(e -> log.info("{}", e))   // started → step_started → step → finished
     .build();
      Parameters:
      eventListener - the listener to receive the agent's live event stream (may be null)
      Returns:
      this builder
      See Also:

    • withSystemMessage

      public AgentBuilder withSystemMessage(String systemMessage)
      Sets a custom system message for the agent.

      If withPlanningPrompt(boolean) is also enabled, the planning prompt is prepended to this message.

      Parameters:
      systemMessage - the system message to set
      Returns:
      this builder

    • withModel

      public AgentBuilder withModel(String modelName)
      Overrides the model name for this agent.
      Parameters:
      modelName - the model name (e.g. "gpt-4o", "llama3")
      Returns:
      this builder

    • withApiKey

      public AgentBuilder withApiKey(String apiKey)
      Overrides the API key for this agent.
      Parameters:
      apiKey - the API key
      Returns:
      this builder

    • withChatModel

      public AgentBuilder withChatModel(dev.langchain4j.model.chat.ChatModel model)
      Uses the given ChatModel directly, bypassing easyai.properties and EasyAI.configure().
      Parameters:
      model - the model to use
      Returns:
      this builder

    • build

      public EasyAgent build()
      Builds and returns the EasyAgent.
      Returns:
      a ready-to-use agent