Package com.tnsai.agents.execution

Class AgentToolExecutor

java.lang.Object
com.tnsai.agents.execution.AgentToolExecutor
public class AgentToolExecutor extends Object
Handles tool/action execution for an Agent.

This class is extracted from Agent to separate tool execution concerns:

  • Tool discovery and schema generation
  • Action execution with resilience
  • MCP tool integration
  • Tool call processing from LLM responses

The executor is created during agent initialization and delegates back to the agent for certain operations (like chatInternal for follow-ups).

  • Constructor Details

    • AgentToolExecutor

      public AgentToolExecutor(AgentToolExecutor.AgentContext context)
      Creates a new AgentToolExecutor.
      Parameters:
      context - the agent context providing access to agent internals

  • Method Details

    • setMaxToolIterations

      public void setMaxToolIterations(int maxIterations)
      Sets the maximum number of consecutive tool call iterations. Default is 10. Set higher for complex agentic workflows, lower for simpler tasks.
      Parameters:
      maxIterations - maximum iterations (must be >= 1)

    • getMaxToolIterations

      public int getMaxToolIterations()
      Returns the current maximum tool call iterations limit.

    • configureResilience

      public void configureResilience(ResilienceExecutor resilienceExecutor, RetryPolicy defaultRetryPolicy, AgentRecoveryManager agentRecoveryManager, AgentStateRecoveryManager stateRecoveryManager, List<ErrorRecoveryScenario> errorRecoveryScenarios)
      Configures resilience components for the executor.
      Parameters:
      resilienceExecutor - the resilience executor
      defaultRetryPolicy - the default retry policy
      agentRecoveryManager - the agent recovery manager
      stateRecoveryManager - the state recovery manager
      errorRecoveryScenarios - the error recovery scenarios

    • getHealthState

      public AgentHealthState getHealthState()
      Returns the current health state.

    • setHealthState

      public void setHealthState(AgentHealthState state)
      Sets the health state.

    • setToolCallFilter

      public void setToolCallFilter(ToolCallFilter filter)
      Sets the tool call filter for permission enforcement. When set, each tool call is checked against this filter before execution. If the filter returns false, the tool call is blocked and a denial message is sent back to the LLM.
      Parameters:
      filter - the filter, or null to allow all tool calls

    • setToolCallListener

      public void setToolCallListener(ToolCallListener listener)
      Sets the tool call listener for visualization. When set, the listener is notified before and after each tool call.
      Parameters:
      listener - the listener, or null to disable

    • getToolsForLLM

      public List<Map<String,Object>> getToolsForLLM()
      Returns tool schemas for the LLM as JSON-Schema fragments (List<Map<String, Object>>). Type changed from List<ToolDefinition> in v0.6.0 (RFC #188 Wave 3b). Combines role-defined actions with MCP tools and externally registered tools.

    • getToolsDescription

      public String getToolsDescription()

    • discoverMcpToolsAtStartup

      public void discoverMcpToolsAtStartup()
      Discovers MCP tools at startup from all MCP_TOOL actions in roles.

    • executeAction

      public Object executeAction(String actionName, Map<String,Object> parameters)

    • executeAction

      public Object executeAction(String actionName, Map<String,Object> parameters, ChatRetrievalContext retrievalContext)

    • executeActionOnRole

      public Object executeActionOnRole(String roleId, String actionName, Map<String,Object> parameters)
      Executes an action on a specific role.
      Parameters:
      roleId - the role name
      actionName - the action name
      parameters - the action parameters
      Returns:
      the action result
      Throws:
      IllegalArgumentException - if role or action is not found

    • executeActionOnRole

      public Object executeActionOnRole(String roleId, String actionName, Map<String,Object> parameters, ChatRetrievalContext retrievalContext)
      Executes an action on a role with request-local retrieval context.

    • setGraceCallEnabled

      public void setGraceCallEnabled(boolean enabled)
      Toggles the grace call on iteration exhaustion.

      When enabled (default), reaching getMaxToolIterations() fires one final LLM turn with tools stripped and a system note instructing the model to summarise what it accomplished. The model can close cleanly and the caller sees a real response rather than "Maximum tool call iterations reached.". When disabled, the legacy hard-cut behaviour returns.

      Parameters:
      enabled - true to issue the grace call (default), false for hard cut

    • isGraceCallEnabled

      public boolean isGraceCallEnabled()
      Returns whether the iteration-exhaustion grace call is enabled.

    • executeToolCalls

      public String executeToolCalls(ChatResponse chatResponse, boolean useHistory)
      Executes tool calls from an LLM response.

      Supports multi-turn tool calling: after executing tools and sending results back to the LLM, if the LLM requests more tool calls, this method loops until the LLM produces a final text response or the iteration limit is reached.

      If the iteration limit is hit and isGraceCallEnabled() is true (default), one final no-tools LLM call fires asking the model to summarise its progress — turning a runaway loop into a graceful close rather than a hard error string.

      Parameters:
      chatResponse - the chat response containing tool calls
      useHistory - whether to use conversation history for follow-up
      Returns:
      the result of tool execution and follow-up

    • executeToolCalls

      public String executeToolCalls(ChatResponse chatResponse, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext)
      Executes a tool loop while preserving the originating RAG turn.

    • executeToolCallSingle

      public AgentToolExecutor.ToolCallResult executeToolCallSingle(ChatResponse.ToolCall toolCall)
      Executes a single tool call with permission check, listener notification, and eval hooks. Used by streaming+tools mode where tool calls are handled individually.
      Parameters:
      toolCall - the tool call to execute
      Returns:
      the result of tool execution

    • executeToolCallSingle

      public AgentToolExecutor.ToolCallResult executeToolCallSingle(ChatResponse.ToolCall toolCall, ChatRetrievalContext retrievalContext)
      Executes one streaming tool call with its originating retrieval turn.