Package com.tnsai.agents.init

Class AgentSpecExtractor

java.lang.Object
com.tnsai.agents.init.AgentSpecExtractor
public class AgentSpecExtractor extends Object
Extracts agent configuration from AgentSpec annotation.

Converts annotation values to runtime models, providing defaults when annotation is not present.

Usage


 AgentSpecExtractor extractor = new AgentSpecExtractor(MyAgent.class);

 String description = extractor.getDescription();
 Communication communication = extractor.getCommunication();
Author:
TnsAI Team
See Also:

  • Constructor Details

    • AgentSpecExtractor

      public AgentSpecExtractor(Class<?> agentClass)
      Creates extractor for an agent class.
      Parameters:
      agentClass - the agent class to extract metadata from

  • Method Details

    • hasSpec

      public boolean hasSpec()
      Checks if the class has @AgentSpec annotation.
      Returns:
      true if annotation is present

    • getDescription

      public String getDescription()
      Returns the agent description.
      Returns:
      description or empty string if not set

    • getVersion

      public String getVersion()
      Returns the agent version.
      Returns:
      version string (default: "1.0.0")

    • isAutoStart

      public boolean isAutoStart()
      Returns whether agent should auto-start.
      Returns:
      true for auto-start (default: true)

    • getIdleTimeoutMs

      public int getIdleTimeoutMs()
      Returns idle timeout in milliseconds.
      Returns:
      timeout (0 = never suspend)

    • getMaxContextTokens

      public int getMaxContextTokens()
      Returns the agent-level context-token budget from @AgentSpec.maxContextTokens (TNS-609). 0 when no @AgentSpec is present or the field is unset.
      Returns:
      max context tokens (0 = no agent-level cap)

    • getToolCallFilter

      public ToolCallFilter getToolCallFilter()
      Instantiates the declarative ToolCallFilter from @AgentSpec.toolCallFilter (TNS-611). The default AllowAllToolFilter is treated as the "not set" sentinel and returns null so the agent runs with no filter wired (preserving the pre-TNS-611 behaviour and keeping AGENT-V006 honest).
      Returns:
      an instantiated filter, or null when no declarative filter is set
      Throws:
      IllegalStateException - AGENT-V009 if the declared filter class lacks a public no-arg constructor or otherwise fails to instantiate
      Since:
      0.12.0 (TNS-611)

    • getRoles

      public List<Role> getRoles()
      Instantiates the role classes declared in @AgentSpec.roles (TNS-536) — the annotation counterpart of AgentBuilder.role(...). Each class is created via its public no-arg constructor.
      Returns:
      the instantiated roles (empty if none declared)
      Throws:
      IllegalStateException - if a declared role class lacks a public no-arg constructor or otherwise fails to instantiate
      Since:
      0.11.0

    • getCommunication

      public Communication getCommunication()
      Extracts communication configuration as runtime model.
      Returns:
      Communication model, or default if not configured

    • generateDID

      public String generateDID(String agentId)
      Generates the full DID string for the agent, delegating the default substitution to DIDConfig.toDid(String) so the annotation and builder paths produce identical DIDs.

      A fixed did.agentId is an identity, so it is not inherited: a class that takes its @AgentSpec from a superclass naming a non-empty agentId is refused, even when it is the only subclass. A class that wants a fixed DID declares it on its own @AgentSpec.

      Parameters:
      agentId - fallback agent ID if not specified in annotation
      Returns:
      DID string (e.g., "did:wba:example.com:agent-1")
      Throws:
      IllegalStateException - if the class inherits a fixed did.agentId

    • getGroupSpec

      public GroupMemberSpec getGroupSpec()
      Extracts group membership configuration from @AgentSpec.groups.
      Returns:
      GroupMemberSpec if groups are configured, or empty config

    • hasGroupSpec

      public boolean hasGroupSpec()
      Checks if the agent has group membership configured.
      Returns:
      true if groups are configured

    • extractGroupSpec

      public static Optional<GroupMemberSpec> extractGroupSpec(Class<?> agentClass)
      Static method to extract group configuration from an agent class.
      Parameters:
      agentClass - the agent class
      Returns:
      GroupMemberSpec if configured

    • getMemorySpec

      public MemorySpec getMemorySpec()
      Extracts memory configuration from @AgentSpec.memory.
      Returns:
      MemorySpec annotation or null if not configured

    • hasMemorySpec

      public boolean hasMemorySpec()
      Checks if the agent has memory configuration.

      Compares every declared MemorySpec member against its annotation default reflectively (TAN-5039), so newly added members are covered automatically — an all-defaults @MemorySpec() still returns false and does not shadow the Priority-4 template-method path.

      Returns:
      true if memory is configured (any non-default value)

    • extractMemorySpec

      public static Optional<MemorySpec> extractMemorySpec(Class<?> agentClass)
      Static method to extract memory configuration from an agent class.
      Parameters:
      agentClass - the agent class
      Returns:
      MemorySpec if configured

    • extractMaxContextTokens

      public static int extractMaxContextTokens(Class<?> agentClass)
      Static accessor for the agent-level context-token budget from @AgentSpec.maxContextTokens (TNS-609).
      Parameters:
      agentClass - the agent class
      Returns:
      max context tokens (0 = no @AgentSpec or unset)

    • extractToolCallFilter

      public static ToolCallFilter extractToolCallFilter(Class<?> agentClass)
      Static accessor for the declarative ToolCallFilter from @AgentSpec.toolCallFilter (TNS-611). Returns null when no declarative filter is configured (the default sentinel AllowAllToolFilter is treated as "not set").
      Parameters:
      agentClass - the agent class
      Returns:
      an instantiated filter, or null

    • getKnowledgeEntries

      public List<KnowledgeEntry> getKnowledgeEntries()
      Knowledge declared on @AgentSpec.knowledge(), each entry with its resolved use, budget and search settings.

      The class configuration of @AgentSpec.config() overrides and adds to them, so an agent may declare knowledge in its file alone. Empty when the annotation is absent or neither declares knowledge. Duplicate names fail initialization.

      Returns:
      the declared entries, in declaration order
      Since:
      0.18.0

    • getKnowledgeSources

      public List<KnowledgeSourceConfig> getKnowledgeSources()
      Action-level sources declared on @AgentSpec.knowledge().

      Empty when the annotation is absent or knowledge is empty. Duplicate names fail initialization.

      Returns:
      normalized source configurations
      Since:
      0.14.0

    • getRetrieval

      public Optional<RetrievalConfig> getRetrieval()
      Search settings of the @AgentSpec.knowledge() entries searched together, merged field by field. MEMORY knowledge is searched apart from the other SEARCH knowledge, so when chat searches a MEMORY entry beside other SEARCH entries these are the settings of the entries other than MEMORY; the MEMORY entry's binding carries its own.

      Empty when no entry's use is SEARCH.

      Returns:
      normalized retrieval configuration
      Since:
      0.14.0
      See Also:

    • extractKnowledgeSources

      public static List<KnowledgeSourceConfig> extractKnowledgeSources(Class<?> agentClass)
      Static accessor for getKnowledgeSources().
      Parameters:
      agentClass - the agent class
      Returns:
      normalized source configurations
      Since:
      0.14.0

    • extractRetrieval

      public static Optional<RetrievalConfig> extractRetrieval(Class<?> agentClass)
      Static accessor for getRetrieval().
      Parameters:
      agentClass - the agent class
      Returns:
      normalized retrieval configuration
      Since:
      0.14.0

    • getKnowledgeSource

      public Optional<KnowledgeSourceConfig> getKnowledgeSource(String name)
      Resolves a named knowledge source declared on the Agent class and normalizes it to the canonical runtime model.
      Parameters:
      name - the declared source name
      Returns:
      the normalized source configuration, or empty
      Since:
      0.13.0