Package com.tnsai.roles

Class Role

java.lang.Object
com.tnsai.roles.Role
Direct Known Subclasses:
ConfigurableRole
public abstract class Role extends Object
Abstract base class for organizational roles in the Gaia methodology.

A Role defines a set of capabilities (actions) that can be assigned to an Agent. Roles follow the Gaia methodology for Multi-Agent Systems, providing clear separation of concerns and reusability.

Key Concepts

  • Identity - Name, goal, and domain of the role (RoleIdentity)
  • Actions - Executable methods discovered via @ActionSpec annotation, which carry their own mustNever / mustAlways safety constraints

Quick Start


 public class ResearchRole extends Role {
     @Override
     public RoleIdentity getIdentity() {
         return new RoleIdentity(
             "Researcher",
             "Find and analyze information",
             "Research"
         );
     }

     @ActionSpec(
         type = ActionType.LOCAL,
         description = "Search for papers on a topic",
         mustNever = {"fabricate references", "plagiarize content"},
         mustAlways = {"cite sources properly"}
     )
     public List<Paper> searchPapers(String topic, int maxResults) {
         // Implementation
     }
 }

Action Discovery

Public methods annotated with @ActionSpec are automatically discovered and made available as tools for LLM-driven agents. Safety constraints declared via mustNever / mustAlways are rendered into the system prompt alongside the action they constrain.

Author:
TnsAI Team
See Also:

  • Method Details

    • create

      public static <T extends Role> T create(Class<T> roleClass)
      Safe factory method for creating Role instances. Uses two-phase initialization to prevent issues with virtual method calls in constructor.
      Type Parameters:
      T - the Role type
      Parameters:
      roleClass - the Role subclass to instantiate
      Returns:
      initialized Role instance
      Throws:
      RoleInitializationException - if creation fails

    • getIdentity

      public abstract RoleIdentity getIdentity()
      Template method: Define the role's identity. Subclasses MUST override this method to return a RoleIdentity.
      Returns:
      role identity (name, goal, domain)

    • identity

      public final RoleIdentity identity()
      Gets the role identity.
      Returns:
      role identity
      Throws:
      IllegalStateException - if not initialized

    • getSpec

      public final DiscoveredRoleActions getSpec()
      Gets the role metadata (including discovered actions).

    • getName

      public final String getName()

    • getGoal

      public final String getGoal()

    • getDomain

      public final String getDomain()

    • getActions

      public final List<ActionMetadata> getActions()
      Gets all discovered actions.

    • getActionCount

      public final int getActionCount()

    • hasAction

      public final boolean hasAction(String actionName)

    • getAction

      public final Optional<ActionMetadata> getAction(String actionName)

    • getLLM

      public final LLMClient getLLM()
      Gets the LLM client for this role.
      Returns:
      the LLM client, or null if not set (uses agent's LLM)

    • getResilienceConfig

      public ResilienceConfig getResilienceConfig()
      Programmatic resilience policy for this role's actions (TNS-567) — the builder-path counterpart of a class-level @Resilience. Default is ResilienceConfig.NONE; ConfigurableRole overrides it with the RoleBuilder.resilience(...) value. ActionExecutor consults this when no @Resilience annotation is present.
      Returns:
      the role's resilience config, never null
      Since:
      0.12.0 (TNS-567)

    • getInputGuardrailConfig

      public InputGuardrailConfig getInputGuardrailConfig()
      Programmatic input-guardrail config for this role's actions (TNS-561) — the builder-path counterpart of a class-level @InputGuardrail. Default null (no builder guardrail); ConfigurableRole overrides it with the RoleBuilder.inputGuardrail(...) value. InputGuardrailEnforcer consults this (precedence: method annotation > this > class annotation).
      Returns:
      the role's input-guardrail config, or null if none set via builder
      Since:
      0.12.0 (TNS-561)

    • getOutputGuardrailConfig

      public OutputGuardrailConfig getOutputGuardrailConfig()
      Programmatic output-guardrail config for this role's actions (TNS-561) — the builder-path counterpart of a class-level @OutputGuardrail. Default null (no builder guardrail); ConfigurableRole overrides it with the RoleBuilder.outputGuardrail(...) value. OutputGuardrailEnforcer consults this (precedence: method annotation > this > class annotation).
      Returns:
      the role's output-guardrail config, or null if none set via builder
      Since:
      0.12.0 (TNS-561)

    • setLLM

      public final Role setLLM(LLMClient llm)
      Sets the LLM client for this role.
      Parameters:
      llm - the LLM client, or null to use agent's LLM
      Returns:
      this role for method chaining

    • hasLLM

      public final boolean hasLLM()

    • getSystemPrompt

      public final String getSystemPrompt()
      Generates a complete system prompt for this role. Includes identity and all actions (with their per-action constraints).

    • getMinimalPrompt

      public final String getMinimalPrompt()
      Generates a minimal prompt (identity only, without actions).

    • toString

      public String toString()
      Overrides:
      toString in class Object