Package com.tnsai.agents

package com.tnsai.agents
Agent classes and lifecycle management for the TnsAI framework.

This package contains the core Agent class which serves as the foundation for all agents in the system. Agents combine BDI reasoning with Role-based behavior to create intelligent, purposeful entities.

Agent Architecture

 ┌─────────────────────────────────────────────────────────────┐
 │                         Agent                                │
 ├─────────────────────────────────────────────────────────────┤
 │  ┌───────────┐  ┌───────────┐  ┌───────────┐               │
 │  │  Beliefs  │  │  Desires  │  │ Intentions│   BDI Layer   │
 │  └───────────┘  └───────────┘  └───────────┘               │
 ├─────────────────────────────────────────────────────────────┤
 │  ┌───────────────────────────────────────────┐             │
 │  │                   Role                     │  Gaia Layer │
 │  │  (Identity, Duties, Safety Properties)    │             │
 │  └───────────────────────────────────────────┘             │
 ├─────────────────────────────────────────────────────────────┤
 │  ┌───────────┐  ┌───────────┐  ┌───────────┐               │
 │  │ LLMClient │  │  Memory   │  │  Actions  │  Infrastructure│
 │  └───────────┘  └───────────┘  └───────────┘               │
 └─────────────────────────────────────────────────────────────┘

Creating an Agent

Role actions run only on an ActionExecutor with a principal and a default authority scope; without them a dispatch is refused before the action body runs. AgentBuilder always wires both. A direct subclass passes a wired executor through the four-argument constructor: 


 import com.tnsai.agents.Agent;
 import com.tnsai.actions.ActionExecutor;
 import com.tnsai.accountability.AuthorityScope;
 import com.tnsai.identity.AgentPrincipal;
 import com.tnsai.llm.LLMClient;
 import com.tnsai.roles.Role;
 import java.util.List;
 import java.time.Duration;

 // Supply a configured LLM client, a role, and an issued principal.
 public class ResearchAgent extends Agent {
     private final Role role;

     public ResearchAgent(LLMClient llmClient, Role role,
             AgentPrincipal principal, AuthorityScope scope) {
         super("research-agent", llmClient, null, wired(principal, scope));
         this.role = role;
     }

     private static ActionExecutor wired(AgentPrincipal principal, AuthorityScope scope) {
         ActionExecutor executor = new ActionExecutor();
         executor.setPrincipal(principal);
         executor.setDefaultScope(scope);
         return executor;
     }

     @Override
     protected List<Role> getRoles() {
         return List.of(role);
     }
 }

Agent Lifecycle

  1. Initialization: Agent is created with identity and LLM client
  2. Configuration: Role, beliefs, desires, and actions are registered
  3. Execution: Agent processes messages via run() method
  4. Reasoning: LLM generates responses based on system prompt and context
  5. Action: If tool calls are made, actions are executed
  6. Memory: Conversation history is persisted

Key Features

  • Role-based behavior: Agents act according to their assigned Role
  • BDI reasoning: Beliefs inform, Desires motivate, Intentions commit
  • Tool/Action support: Methods annotated with @Action become callable tools
  • Memory persistence: Configurable memory stores for conversation history
  • Observability: Built-in OpenTelemetry tracing support
See Also: