Package akka.javasdk.agent

Class Agent

Object
akka.javasdk.agent.Agent
All Implemented Interfaces:
AgentDelegationWorker
Direct Known Subclasses:
HallucinationEvaluator, SummarizationEvaluator, ToxicityEvaluator
public abstract class Agent extends Object implements AgentDelegationWorker
An AI agent component that interacts with an AI model, such as a large language model (LLM), to perform specific tasks.

An Agent is typically backed by a large language model and maintains contextual history in a session memory, which may be shared between multiple agents collaborating on the same goal. It can provide function tools and call them as requested by the model.

Key Features:

  • Session-based: Participates in a session with contextual memory
  • Memory Management: Automatically stores user and AI messages for context
  • Function Tools: Can be extended with custom tools for the model to invoke
  • Model Integration: Supports multiple AI model providers (OpenAI, Anthropic, etc.)
  • Streaming Support: Can stream responses token by token for real-time UX

Session Memory: The agent maintains contextual history in session memory, identified by a session id accessible via context(). This memory is persistent and shared between agents using the same session id.

Component Identification: The agent must be annotated with Component to provide a unique identifier for the component class. For multi-agent systems, use Component.name(), Component.description() and AgentRole to provide metadata for the AgentRegistry.

Calling Agents: Agents are typically called from workflows, endpoints, or consumers using the ComponentClient: 


 String response = componentClient
     .forAgent()
     .inSession(sessionId)
     .method(MyAgent::query)
     .invoke("What is the weather like?");

For reliable execution with error handling and retries, consider calling agents from a Workflow.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    Agent.AgentReply<T>
    A detailed reply from an agent component call, containing both the result and additional information, like token usage.
    static interface 
    Agent.Effect<T>
    An Effect is a description of what the runtime needs to do after the command is handled.
    static interface 
    Agent.StreamEffect
    A StreamEffect is a description of what the runtime needs to do after the command is handled, for a message handler that streams the model's response token by token instead of returning it as a single reply.
    static final record 
    Agent.TokenUsage
    The number of tokens consumed by a model interaction.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Agent()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected final AgentContext
    context()
    Additional context and metadata for a command handler.
    final Agent.Effect.Builder
    effects()
    Start building an Agent.Effect to return from a message handler that replies with the model's full response.
    final Agent.StreamEffect.Builder
    streamEffects()
    Start building a Agent.StreamEffect to return from a message handler that streams the model's response token by token.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Agent

      public Agent()

  • Method Details

    • context

      protected final AgentContext context()
      Additional context and metadata for a command handler.

      It will throw an exception if accessed from constructor.

    • effects

      public final Agent.Effect.Builder effects()
      Start building an Agent.Effect to return from a message handler that replies with the model's full response.

    • streamEffects

      public final Agent.StreamEffect.Builder streamEffects()
      Start building a Agent.StreamEffect to return from a message handler that streams the model's response token by token.