Package com.tnsai.annotations

Annotation Interface AgentSpec

@Documented @Retention(RUNTIME) @Target(TYPE) public @interface AgentSpec
Defines agent specification including identity and default configuration.

This is the primary annotation for defining agent identity with:

  • Description: What the agent is for
  • DID: W3C Decentralized Identifier for authentication
  • Communication: Default communication style (fallback for roles)
  • LLM: Language model configuration

Name Derivation

Agent name is automatically derived from class name:

  • ResearchAgent → "Research"
  • CustomerSupportAgent → "CustomerSupport"

Usage


 @AgentSpec(
     description = "Research assistant for academic work",
     llm = @LLMSpec(
         provider = Provider.OPENAI,
         model = "gpt-4o",
         temperature = 0.7f
     )
 )
 public class ResearchAgent extends Agent { }

The annotation configures the agent; it does not wire accountability. Role actions run only on an executor with a principal and a default authority scope, which AgentBuilder sets and a direct subclass passes through the four-argument Agent constructor; see com.tnsai.agents.

Author:
TnsAI Team
See Also:

  • Element Details

    • description

      String description
      Agent description.

      Used in system prompts, documentation, and export.

      Returns:
      description
      Default:
      ""

    • did

      DIDSpec did
      DID (Decentralized Identifier) configuration.

      W3C-compliant identifier for agent authentication and inter-agent communication.

      Returns:
      DID configuration
      See Also:
      Default:
      @com.tnsai.annotations.DIDSpec

    • communication

      Communication communication
      Default communication style (fallback).

      Used when a Role doesn't define its own @Communication.

      Returns:
      default communication configuration
      See Also:
      Default:
      @com.tnsai.annotations.Communication

    • version

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

    • autoStart

      boolean autoStart
      Whether agent should auto-start on creation.

      If true, lifecycle INIT and START phases run automatically.

      Returns:
      true for auto-start
      Default:
      true

    • idleTimeoutMs

      int idleTimeoutMs
      Maximum idle time before agent suspension (milliseconds).

      0 means never suspend.

      Returns:
      idle timeout in ms
      Default:
      0

    • llm

      LLMSpec llm
      LLM configuration for this agent. 
      
 @AgentSpec(
     description = "Support agent",
     llm = @LLMSpec(
         provider = Provider.OLLAMA,
         model = "llama3.2",
         temperature = 0.7f
     )
 )
      Returns:
      LLM configuration
      See Also:
      Default:
      @com.tnsai.annotations.LLMSpec

    • memory

      MemorySpec memory
      Memory configuration for this agent.
      Returns:
      Memory configuration
      See Also:
      Default:
      @com.tnsai.annotations.MemorySpec

    • toolCallFilter

      Class<? extends ToolCallFilter> toolCallFilter
      Declarative ToolCallFilter for this agent (TNS-611).

      The top-level annotation counterpart of AgentBuilder.toolCallFilter(...). The supplied class is instantiated via its public no-arg constructor at agent initialization and wired into the orchestrator before the first tool call. The default — AllowAllToolFilter — is treated as the "not set" sentinel and leaves the agent with no filter wired (the historical behaviour), so existing agents are unaffected and the AGENT-V006 approval-gate warning still fires for confirmation-required tools without an explicit filter. 

      
 @AgentSpec(role = "filtered", toolCallFilter = AllowlistToolFilter.class)
 public class FilteredAgent extends Agent { ... }

      Precedence: an explicit AgentBuilder.toolCallFilter(...) (or Agent.setToolCallFilter(...)) call wins over this annotation. Filter classes that lack a public no-arg constructor fail with the same AGENT-V009 error as @AgentSpec.roles.

      Returns:
      the filter class to instantiate, or AllowAllToolFilter when no declarative filter is configured
      Default:
      com.tnsai.agents.execution.AllowAllToolFilter.class

    • maxContextTokens

      int maxContextTokens
      Maximum context-window budget in tokens for this agent (TNS-609).

      The top-level, declarative counterpart of AgentBuilder.maxContextTokens(int): when set (> 0) the agent's conversation history is pruned to this budget before each LLM call (the same pruning the builder shortcut drives). 0 means no agent-level cap. 

      
 @AgentSpec(role = "long-context", maxContextTokens = 200_000)
 public class LongContextAgent extends Agent { ... }

      This is a shortcut for the common "just set the budget" case. It takes precedence over the nested MemorySpec.maxContextTokens() (set via memory()) when both are present; a template-method override still wins over both. Setting both the shortcut and the nested value to different numbers is discouraged — prefer one.

      Returns:
      the agent-level context-token budget (0 = no cap)
      See Also:
      Default:
      0

    • groups

      GroupMember groups
      Group membership configuration.
      Returns:
      Group membership
      See Also:
      Default:
      @com.tnsai.annotations.GroupMember(groups={})

    • roles

      Class<? extends Role>[] roles
      Role classes this agent plays (TNS-536) — the annotation counterpart of AgentBuilder.role(Role) / roles(List). Each class is instantiated via its public no-arg constructor during agent initialization. Roles that need constructor arguments must use AgentBuilder.role(new MyRole(...)) instead.

      Precedence: if the agent also supplies roles programmatically (builder or a getRoles() override), those win and these are ignored.

      Returns:
      role classes to instantiate (empty by default)
      Since:
      0.11.0
      See Also:
      Default:
      {}

    • knowledge

      Knowledge[] knowledge
      Knowledge this agent's actions and chat turn can use.

      Each entry declares a source once; an action sees a source only when its ActionSpec.knowledge() names it, and the chat turn sees the enabled entries. Two entries with the same Knowledge.name() fail at startup. A builder that already added sources wins.

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

    • knowledgePolicy

      KnowledgePolicy[] knowledgePolicy
      Presence policies for the sources knowledge() and the class 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 class configuration file, which can override and add to this agent's llm and knowledge and its roles'. No path means no file.
      Returns:
      the configuration file
      Since:
      0.18.0
      See Also:
      Default:
      @com.tnsai.annotations.Config