Package akka.javasdk.agent

Interface Agent.Effect.Builder

Enclosing interface:
Agent.Effect<T>
public static interface Agent.Effect.Builder
Construct the effect that is returned by the message handler.

  • Method Details

    • model

      Agent.Effect.Builder model(ModelProvider provider)
      Define the AI model (LLM) to use. If undefined, the model is defined by the default configuration in akka.javasdk.agent.model-provider

    • systemMessage

      Agent.Effect.Builder systemMessage(String message)
      Provides system-level instructions to the AI model that defines its behavior and context. The system message acts as a foundational prompt that establishes the AI's role, constraints, and operational parameters. It is processed before user messages and helps maintain consistent behavior throughout the interaction.

    • tools

      Agent.Effect.Builder tools(Object tool, Object... otherTools)
      Adds one or more tool instances or classes that the AI model can use.

      Each argument can be either an object instance or a Class object. If a Class is provided, it will be instantiated at runtime using the configured DependencyProvider.

      Workflows, Event Sourced Entities, Key Value Entities, and Views can also be used as tools. Unlike regular objects, component instances cannot be passed to this method. Instead, you must pass the component Class object.

      Each instance or class must have at least one public method annotated with FunctionTool. If no such method is found, an IllegalArgumentException will be thrown. These methods will be available as tools for the AI model to invoke.

      When using components as tools, special rules apply to which methods can be annotated with FunctionTool. See FunctionTool for details.

      Returns:
      this builder for method chaining

    • tools

      Agent.Effect.Builder tools(List<Object> toolInstancesOrClasses)
      Adds one or more tool instances or classes that the AI model can use.

      Each element in the list can be either an object instance or a Class object. If a Class is provided, it will be instantiated at runtime using the configured DependencyProvider.

      Workflows, Event Sourced Entities, Key Value Entities, and Views can also be used as tools. Unlike regular objects, component instances cannot be passed to this method. Instead, you must pass the component Class object.

      Each instance or class must have at least one public method annotated with FunctionTool. If no such method is found, an IllegalArgumentException will be thrown. These methods will be available as tools for the AI model to invoke.

      When using components as tools, special rules apply to which methods can be annotated with FunctionTool. See FunctionTool for details.

      Parameters:
      toolInstancesOrClasses - one or more objects or classes exposing tool methods
      Returns:
      this builder for method chaining

    • systemMessageFromTemplate

      Agent.Effect.Builder systemMessageFromTemplate(String templateId)
      Create a system message from a template. Call @PromptTemplate before to initiate or update template value.

      Provides system-level instructions to the AI model that defines its behavior and context. The system message acts as a foundational prompt that establishes the AI's role, constraints, and operational parameters. It is processed before user messages and helps maintain consistent behavior throughout the interaction.

      Parameters:
      templateId - the id of the template to use

    • systemMessageFromTemplate

      Agent.Effect.Builder systemMessageFromTemplate(String templateId, Object... args)
      Create a system message from a template. Call @PromptTemplate before to initiate or update template value. Provide arguments that will be applied to the template using Java String.formatted(java.lang.Object...) method.

      Provides system-level instructions to the AI model that defines its behavior and context. The system message acts as a foundational prompt that establishes the AI's role, constraints, and operational parameters. It is processed before user messages and helps maintain consistent behavior throughout the interaction.

      Parameters:
      templateId - the id of the template to use
      args - the arguments to apply to the template

    • memory

      Agent.Effect.Builder memory(MemoryProvider provider)

    • mcpTools

      Agent.Effect.Builder mcpTools(RemoteMcpTools tools, RemoteMcpTools... moreTools)
      Adds tools from one or more remote MCP servers.

      Construct instances using RemoteMcpTools.fromServer(String)

    • mcpTools

      Agent.Effect.Builder mcpTools(List<RemoteMcpTools> tools)
      Adds tools from one or more remote MCP servers.

      Construct instances using RemoteMcpTools.fromServer(String)

    • userMessage

      Agent.Effect.OnSuccessBuilder userMessage(String message)
      The user message to the AI model. This message represents the specific query, instruction, or input that will be processed by the model to generate a response.

    • reply

      <T> Agent.Effect<T> reply(T message)
      Create a message reply without calling the model.
      Type Parameters:
      T - The type of the message that must be returned by this call.
      Parameters:
      message - The payload of the reply.
      Returns:
      A message reply.

    • reply

      <T> Agent.Effect<T> reply(T message, Metadata metadata)
      Create a message reply without calling the model.
      Type Parameters:
      T - The type of the message that must be returned by this call.
      Parameters:
      message - The payload of the reply.
      metadata - The metadata for the message.
      Returns:
      A message reply.

    • error

      <T> Agent.Effect<T> error(String message)
      Create an error reply without calling the model. A short version of { effects().error(new CommandException(message))}.
      Type Parameters:
      T - The type of the message that must be returned by this call.
      Parameters:
      message - The error message.
      Returns:
      An error reply.

    • error

      <T> Agent.Effect<T> error(CommandException commandException)
      Create an error reply. CommandException will be serialized and sent to the client. It's possible to catch it with try-catch statement or CompletionStage API when using async ComponentClient API.
      Type Parameters:
      T - The type of the message that must be returned by this call.
      Parameters:
      commandException - The command exception to be returned.
      Returns:
      An error reply.