Annotation Interface Agent

@Retention(RUNTIME) @Target(METHOD) public @interface Agent
Java methods annotated with @Agent are considered agents that other agents can invoke.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Agent.NoTypedKey
     

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    async
    If true, the agent will be invoked in an asynchronous manner, allowing the workflow to continue without waiting for the agent's result.
    boolean
    compensateOnError
    If true, all previously successful tool invocations with @CompensateFor actions will be compensated in reverse order when any tool in this agent fails.
    String
    description
    Description of the agent.
    String
    name
    Name of the agent.
    boolean
    optional
    If true, the agent's execution will be silently skipped when any of its arguments is missing in the agentic scope, instead of making the agentic system's execution fail.
    String
    outputKey
    Key of the output variable that will be used to store the result of the agent's invocation.
    String[]
    summarizedContext
    Names of other agents participating in the definition of the context of this agent.
    Class<? extends TypedKey<?>>
    typedOutputKey
    Strongly typed key of the output variable that will be used to store the result of this agent's invocation in the AgenticScope.
    String
    value
    Description of the agent.

  • Element Details

    • name

      String name
      Name of the agent. If not provided, method name will be used.
      Returns:
      name of the agent.
      Default:
      ""

    • value

      String value
      Description of the agent. This is an alias of the description attribute, and it is possible to use either. It should be clear and descriptive to allow language model to understand the agent's purpose and its intended use.
      Returns:
      description of the agent.
      Default:
      ""

    • description

      String description
      Description of the agent. This is an alias of the value attribute, and it is possible to use either. It should be clear and descriptive to allow language model to understand the agent's purpose and its intended use.
      Returns:
      description of the agent.
      Default:
      ""

    • outputKey

      String outputKey
      Key of the output variable that will be used to store the result of the agent's invocation.
      Returns:
      name of the output variable.
      Default:
      ""

    • typedOutputKey

      Class<? extends TypedKey<?>> typedOutputKey
      Strongly typed key of the output variable that will be used to store the result of this agent's invocation in the AgenticScope.

      This attribute provides a type-safe alternative to outputKey(). Instead of identifying the output variable using a String, the output is identified by a class implementing TypedKey.

      The generic type declared by the TypedKey represents the type of value associated with the output variable.

      For example: 

      public class Category implements TypedKey<RequestCategory> {
}

@Agent(
        name = "categoryRouter",
        typedOutputKey = Category.class
)
RequestCategory classify(String request);

      When the agent completes successfully, its returned RequestCategory value is stored in the agentic scope using Category.class as the typed state key.

      The value can later be retrieved without using a string key and without requiring an explicit type cast: 

      RequestCategory category =
        scope.readState(Category.class);

      This is particularly useful in multi-agent workflows where the output of one agent becomes the input of another agent. The typed key acts as both:

      • the identity of the state variable, and
      • the declaration of the Java type associated with that variable.

      Multiple typed keys may use the same Java value type while still representing different state variables. For example: 

      public class InitialCategory
        implements TypedKey<RequestCategory> {
}

public class ValidatedCategory
        implements TypedKey<RequestCategory> {
}

      Even though both keys contain RequestCategory values, InitialCategory.class and ValidatedCategory.class identify two independent variables in the agentic scope.

      typedOutputKey and outputKey() are alternative ways of defining the output variable. Only one of them should be configured for an agent:

      • outputKey() identifies the output using a String.
      • typedOutputKey identifies the output using a TypedKey implementation and preserves its associated Java type.
      Returns:
      the TypedKey class identifying the strongly typed output variable where the result of this agent invocation will be stored
      See Also:
      Default:
      dev.langchain4j.agentic.Agent.NoTypedKey.class

    • async

      boolean async
      If true, the agent will be invoked in an asynchronous manner, allowing the workflow to continue without waiting for the agent's result.
      Returns:
      true if the agent should be invoked in an asynchronous manner, false otherwise.
      Default:
      false

    • optional

      boolean optional
      If true, the agent's execution will be silently skipped when any of its arguments is missing in the agentic scope, instead of making the agentic system's execution fail.
      Returns:
      true if the agent is optional, false otherwise.
      Default:
      false

    • compensateOnError

      boolean compensateOnError
      If true, all previously successful tool invocations with @CompensateFor actions will be compensated in reverse order when any tool in this agent fails.
      Returns:
      true if cross-agent compensation should be enabled, false otherwise.
      Default:
      false

    • summarizedContext

      String[] summarizedContext
      Names of other agents participating in the definition of the context of this agent.
      Returns:
      array of names of other agents participating in the definition of the context of this agent.
      Default:
      {}