Package com.tnsai.actions

package com.tnsai.actions

Action execution framework for agent tool/function calling.

This package provides the infrastructure for defining and executing actions that agents can perform. Actions bridge the gap between LLM tool calls and actual functionality.

Action Flow

 ┌─────────────────────────────────────────────────────────────┐
 │                      Action Execution                        │
 ├─────────────────────────────────────────────────────────────┤
 │                                                              │
 │  LLM ────► ToolCall ────► ActionDiscovery ────► Method      │
 │                                │                   │         │
 │                                │                   │         │
 │                                ▼                   ▼         │
 │                          ActionRegistry     ActionExecutor   │
 │                                │                   │         │
 │                                │                   │         │
 │                                ▼                   ▼         │
 │  LLM ◄──── ToolResult ◄──── Result ◄───── Execution        │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘
 

Defining Actions

Actions are defined using the ActionSpec annotation:

 public class WeatherAgent extends Agent {

     @ActionSpec("Get the current weather for a location")
     public String getWeather(
         @ActionParam(description = "City name") String city,
         @ActionParam(description = "Temperature unit", required = false) String unit
     ) {
         // Implementation
         return weatherService.getWeather(city, unit);
     }
 }
 

Key Components

Component	Purpose
ActionDiscovery	Finds @Action methods via reflection
ActionRegistry	Stores and retrieves action metadata
ActionExecutor	Invokes actions with parameters
ActionResult	Encapsulates execution result

Action Executors

The com.tnsai.actions.executors sub-package provides specialized executors for different action types:

• WebServiceExecutor: HTTP API calls
• LLMRoleExecutor: LLM-typed actions (tool calls dispatched by the agent's ToolMethodDispatcher)
• McpToolExecutor: MCP (Model Context Protocol) tools

JSON Schema Generation

Actions are automatically converted to JSON Schema for LLM tool definitions, including parameter types, descriptions, and required fields.

Thread Safety

Action execution is thread-safe. Multiple concurrent calls to the same action are supported, provided the action implementation is thread-safe.

See Also:

• ActionSpec
• com.tnsai.actions.executors

Related Packages

Package	Description
com.tnsai	TnsAI Java SDK - A multi-agent framework with BDI architecture and Gaia methodology.
com.tnsai.actions.contracts	Design-by-contract support for action execution with pre/post condition validation.
com.tnsai.actions.executors	Specialized action executors for different execution contexts.
com.tnsai.actions.model	Typed models for action execution.

Class	Description
ActionDiscovery	Discovers actions from Role classes using reflection.
ActionExecutor	Main router for action execution in the TnsAI framework.
ActionParams	Holds parameters for action execution, supporting transformation between LLM-provided parameters and actual action parameters.
ActionResult	Wrapper for action execution results.
Actions	Framework-owned helpers for action-body wiring.
Actions.DispatchedByFrameworkException	Dedicated exception type so tests can assert the cause without string-matching and operators can wire dedicated alerts on this failure mode.
ParamBeanMapper	Reflectively maps a typed input bean (Java record or POJO with accessors / public fields) to a Map<String, Object> suitable for the framework's existing executeAction(String, Map) dispatch path.
TypeConverter	Utility class for converting values between types in action parameter handling.