Package akka.javasdk.agent.autonomous

Interface AgentDefinition

public interface AgentDefinition
Defines an autonomous agent's configuration: tools, model provider, guardrails, capabilities, and optional instructions. Built via AutonomousAgent.define() and returned from AutonomousAgent.definition().

The @Component description captures the agent's purpose and expected outcome: a short statement of what the agent does, when to use it, and what it produces. The runtime injects the description into the model's system message and uses it when other agents need to choose a delegation or handoff target. The description is mandatory for autonomous agents.

Instructions are optional supplementary text for tone, persona, domain rules, or procedural guidance to the model, also appended to the system message. Multi-agent orchestration mechanics (when to delegate, when to hand off, who to message) do not belong in instructions — they are derived automatically from the capabilities and from the descriptions of the participating agents.

Each fluent method returns a new immutable instance.

  • Method Details

    • instructions

      AgentDefinition instructions(String instructions)
      Optional internal, LLM-facing instructions appended to the system message. Use this for tone, persona, role, domain rules (for example "Always cite sources" or "Never quote prices in non-USD currencies"), or procedural guidance on how the model should approach a task. The agent's purpose and expected outcome belong in @Component description, not here.

      Multi-agent orchestration mechanics do not belong here. Coordination details such as when to delegate, when to hand off, or who to message are derived automatically from the capabilities and from the descriptions of the participating agents. If you find yourself writing "delegate to X first, then to Y, then synthesize," the work belongs in capabilities and task definitions instead.

    • capability

      AgentDefinition capability(AgentCapability capability)
      Add a capability to this agent: task acceptance, delegation, etc.

    • modelProvider

      AgentDefinition modelProvider(ModelProvider provider)
      The LLM model provider for this agent.

    • tools

      AgentDefinition tools(Object... toolInstancesOrClasses)
      Adds one or more tool instances or classes that the agent can use.

      Each element 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.

      Parameters:
      toolInstancesOrClasses - one or more objects or classes exposing tool methods

    • mcpTools

      AgentDefinition mcpTools(RemoteMcpTools... mcpTools)
      Remote MCP tool endpoints available to the agent.

    • requestGuardrails

      AgentDefinition requestGuardrails(Class<? extends Guardrail>... guardrails)
      Guardrails evaluated on requests before they are sent to the LLM.

    • responseGuardrails

      AgentDefinition responseGuardrails(Class<? extends Guardrail>... guardrails)
      Guardrails evaluated on responses received from the LLM.

    • contentLoader

      AgentDefinition contentLoader(ContentLoader contentLoader)
      Sets a custom content loader.

      When multimodal messages contain image or PDF references, the runtime resolves them automatically for built-in URI schemes: http(s):// (public HTTP fetch) and object://bucket/key (resolved against a configured object-storage bucket). Defining a custom loader is for other cases, such as authenticated endpoints, databases, or custom URI schemes.

      Parameters:
      contentLoader - The content loader implementation
      See Also: