Package com.tnsai.annotations

Annotation Interface RoleSpec

@Documented @Inherited @Retention(RUNTIME) @Target(TYPE) public @interface RoleSpec
Defines role specification for agents.

This is the primary annotation for defining agent roles with LLM configuration and metadata. Safety constraints (mustNever / mustAlways) are declared on @ActionSpec methods of the role class — every constraint lives on the action it applies to.

A class without its own specification inherits the nearest superclass specification. A subclass declaration replaces the complete specification; individual fields are not merged. Interface specifications are not inherited.

Automatic Extraction

The following are extracted automatically from code:

  • State: From @State annotated fields
  • Actions: From @ActionSpec annotated methods

Usage


 @RoleSpec(
     name = "LifeCell",
     description = "Conway's Game of Life cellular automaton"
 )
 public class LifeCellRole extends Role {

     @State(description = "Current cell state")
     private CellState cellState = CellState.DEAD;

     @ActionSpec(
         type = ActionType.LOCAL,
         description = "Update cell state",
         mustNever = {"transition to invalid state"}
     )
     public void updateState() { ... }
 }
Author:
TnsAI Team
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Communication
    communication
    Communication configuration for this role.
    Config
    config
    The role's own configuration file, which can override and add to this role's llm and knowledge.
    String
    description
    Role description.
    String[]
    domains
    Domains this role operates in.
    Goal[]
    goals
    Goals this role wants to achieve.
    Knowledge[]
    knowledge
    Knowledge this role's actions can use.
    KnowledgePolicy[]
    knowledgePolicy
    Presence policies for the sources knowledge() and this role's configuration file declare.
    LLMSpec
    llm
    LLM configuration for this role.
    String
    name
    Role name.
    int
    priority
    Role priority (higher = more important).
    LLMCapability[]
    requires
    LLM capabilities this role actually exercises at runtime — surfaced to the build-time validation pipeline (AGENT-V004, issue #238) so a missing capability on the configured LLM fails fast at AgentBuilder.build() rather than at the first streaming / vision / structured-output call.
    boolean
    shared
    Whether this role can be assigned to multiple agents simultaneously.
    String
    version
    Role version (semantic versioning).

  • Element Details

    • name

      String name
      Role name.

      If empty, class name is used.

      Returns:
      role name
      Default:
      ""

    • description

      String description
      Role description.

      Used in system prompts and documentation.

      Returns:
      description
      Default:
      ""

    • version

      String version
      Role version (semantic versioning).
      Returns:
      version string
      Default:
      "1.0.0"

    • priority

      int priority
      Role priority (higher = more important).

      Used when multiple roles could handle a task.

      Default:
      5

    • shared

      boolean shared
      Whether this role can be assigned to multiple agents simultaneously.
      Default:
      true

    • domains

      String[] domains
      Domains this role operates in.
      Returns:
      domain names
      Default:
      {}

    • llm

      LLMSpec llm
      LLM configuration for this role. 
      
 @RoleSpec(
     name = "ResearchAgent",
     llm = @LLMSpec(
         provider = Provider.OLLAMA,
         model = "llama3",
         temperature = 0.7f
     )
 )
      Returns:
      LLM configuration
      Default:
      @com.tnsai.annotations.LLMSpec

    • communication

      Communication communication
      Communication configuration for this role.
      Returns:
      Communication configuration
      Default:
      @com.tnsai.annotations.Communication

    • requires

      LLMCapability[] requires
      LLM capabilities this role actually exercises at runtime — surfaced to the build-time validation pipeline (AGENT-V004, issue #238) so a missing capability on the configured LLM fails fast at AgentBuilder.build() rather than at the first streaming / vision / structured-output call.

      Each value in the array maps 1:1 to a flag on LLMCapabilities; the validator emits one AGENT-V004 WARNING per capability the LLM reports as unsupported.

      Default empty array — undeclared roles are silent (validator has no signal to act on). Function calling is NOT a value of LLMCapability on purpose: that case is already covered by AGENT-V003 via tool-presence detection, no annotation required. 

      
 @RoleSpec(
     name = "VisionResearcher",
     requires = {LLMCapability.VISION, LLMCapability.STREAMING}
 )
 public class VisionResearcherRole extends Role { ... }
      Returns:
      required LLM capabilities for this role
      Since:
      0.8.5 (issue #238)
      Default:
      {}

    • goals

      Goal[] goals
      Goals this role wants to achieve.

      Goals define desired states that the planner will work towards. Each goal has a condition that determines when it's satisfied. 

      
 @RoleSpec(
     name = "LifeCell",
     goals = {
         @Goal(name = "survive", condition = "state == ALIVE", priority = Priority.CRITICAL),
         @Goal(name = "reproduce", condition = "neighborCount == 3", priority = Priority.HIGH)
     }
 )

      Actions can be linked to goals via

      invalid reference 
      Action#fulfills()
      : 
      
 @ActionSpec(
     precondition = "state == DEAD && neighborCount == 3",
     postcondition = "state = ALIVE",
     fulfills = {"survive", "reproduce"}
 )
 public void reproduce() { ... }
      Returns:
      goals for planning
      See Also:
      • Goal
      • invalid reference 
        com.tnsai.planning.Planner
      Default:
      {}

    • knowledge

      Knowledge[] knowledge
      Knowledge this role's actions can use.

      Each entry declares a source once; an action sees a source only when its ActionSpec.knowledge() names it. Two entries with the same Knowledge.name() fail at startup.

      Returns:
      knowledge declarations (empty by default)
      Since:
      0.18.0
      See Also:
      Default:
      {}

    • knowledgePolicy

      KnowledgePolicy[] knowledgePolicy
      Presence policies for the sources knowledge() and this role's configuration file declare. A source without a policy must load.
      Returns:
      knowledge policies (empty by default)
      Since:
      0.18.1
      See Also:
      Default:
      {}

    • config

      Config config
      The role's own configuration file, which can override and add to this role's llm and knowledge. It wins over the roles section of an agent's file. No path means no file.
      Returns:
      the configuration file
      Since:
      0.18.0
      See Also:
      Default:
      @com.tnsai.annotations.Config