Package com.tnsai.agents.chat

Class AgentChatOrchestrator

java.lang.Object
com.tnsai.agents.chat.AgentChatOrchestrator
public class AgentChatOrchestrator extends Object
Handles chat orchestration for an Agent.

This class is extracted from Agent to separate chat concerns:

  • LLM invocation and response processing
  • History management during chat
  • Tool call handling (delegation to toolExecutor)
  • Tracing of chat operations

The orchestrator is created during agent initialization and delegates back to the agent for certain operations (like tool execution).

  • Constructor Details

    • AgentChatOrchestrator

      public AgentChatOrchestrator(AgentChatOrchestrator.ChatContext context)
      Creates a new AgentChatOrchestrator.
      Parameters:
      context - the chat context providing access to agent internals

  • Method Details

    • invokeLLM

      public Object invokeLLM(String message, boolean useHistory)
      Invokes the LLM with the given message.
      Parameters:
      message - the user message
      useHistory - whether to include conversation history
      Returns:
      the LLM response (String or ChatResponse)

    • invokeLLM

      public Object invokeLLM(String message, boolean useHistory, boolean useTools)
      Invokes the LLM with the given message and tool settings.
      Parameters:
      message - the user message
      useHistory - whether to include conversation history
      useTools - whether to include tools in the request
      Returns:
      the LLM response (String or ChatResponse)

    • invokeLLM

      public Object invokeLLM(String message, boolean useHistory, boolean useTools, boolean trace)
      Invokes the LLM with full control over all settings.
      Parameters:
      message - the user message
      useHistory - whether to include conversation history
      useTools - whether to include tools in the request
      trace - whether to trace the request/response
      Returns:
      the LLM response (String or ChatResponse)

    • invokeLLM

      public Object invokeLLM(String message, boolean useHistory, boolean useTools, boolean trace, ChatRetrievalContext retrievalContext)
      Invokes the LLM with request-local retrieval identity and lifecycle context.

    • invokeLLM

      public Object invokeLLM(String message, boolean useHistory, boolean useTools, boolean trace, String retrievalQuery, ChatRetrievalContext retrievalContext)
      Invokes the LLM while retrieving against the originating turn query.

    • invokeReasoning

      public ReasoningStrategyHandle.ReasoningResult invokeReasoning(ReasoningStrategyHandle strategy, String message, ChatRetrievalContext retrievalContext, List<Map<String,Object>> tools, List<Map<String,Object>> history)
      Invokes a reasoning strategy through canonical chat grounding.

    • processLLMResponse

      public String processLLMResponse(Object response, boolean useHistory)
      Processes an LLM response, handling text responses and tool calls.
      Parameters:
      response - the LLM response (String or ChatResponse)
      useHistory - whether to update conversation history
      Returns:
      the processed response string

    • processLLMResponse

      public String processLLMResponse(Object response, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext)
      Processes a response while preserving the originating RAG turn.

    • processLLMResponseInternal

      public String processLLMResponseInternal(Object response, boolean useHistory)
      Internal version of processLLMResponse that does not trace. Used by chatInternal to avoid duplicate trace output.
      Parameters:
      response - the LLM response (String or ChatResponse)
      useHistory - whether to update conversation history
      Returns:
      the processed response string

    • chatInternal

      public String chatInternal(String message, boolean useHistory)
      Internal chat without tool execution (prevents recursion in tool calls). Does not trace request/response to avoid duplicate output.
      Parameters:
      message - the message to send
      useHistory - whether to use conversation history
      Returns:
      the LLM response

    • chatInternal

      public String chatInternal(String message, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext)
      Internal no-tools follow-up preserving the originating RAG turn.

    • chatInternalWithTools

      public Object chatInternalWithTools(String message, boolean useHistory)
      Internal chat WITH tools enabled for multi-turn tool loops. Returns raw Object (ChatResponse or String) so the caller can check for additional tool calls and continue the loop.
      Parameters:
      message - the message to send (typically tool execution results)
      useHistory - whether to use conversation history
      Returns:
      raw LLM response (ChatResponse or String)

    • chatInternalWithTools

      public Object chatInternalWithTools(String message, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext)
      Internal tool-loop follow-up preserving the originating RAG turn.

    • chatWithStructure

      public <T> T chatWithStructure(String message, OutputParser<T> parser, int maxRetries)
      Sends a message and returns a structured, validated response using guardrails pattern.
      Type Parameters:
      T - the output type
      Parameters:
      message - the user message to send
      parser - the output parser defining structure and validation rules
      maxRetries - maximum number of correction attempts (0 = no retries)
      Returns:
      the parsed structured object

    • chatWithStructure

      public <T> T chatWithStructure(String message, OutputParser<T> parser, int maxRetries, ChatRetrievalContext retrievalContext)
      Sends a structured chat turn with request-local retrieval context. The original query and context are retained across parse retries.

    • chatWithFormat

      public <T> T chatWithFormat(String message, Class<T> targetClass, OutputFormat format, int maxRetries)
      Chat with structured output in a specific format.
      Type Parameters:
      T - The output type
      Parameters:
      message - The user message
      targetClass - The expected output class
      format - The output format (JSON, YAML, TOON, TONL)
      maxRetries - Maximum correction attempts
      Returns:
      The parsed structured object

    • chatWithFormat

      public <T> T chatWithFormat(String message, Class<T> targetClass, OutputFormat format, int maxRetries, ChatRetrievalContext retrievalContext)
      Chat with structured output and request-local retrieval context.

    • chatWithFormat

      public <T> T chatWithFormat(String message, Class<T> targetClass, int maxRetries)
      Chat with structured output using annotation-defined format or JSON default.
      Type Parameters:
      T - The output type
      Parameters:
      message - The user message
      targetClass - The expected output class
      maxRetries - Maximum correction attempts
      Returns:
      The parsed structured object

    • chatWithFormat

      public <T> T chatWithFormat(String message, Class<T> targetClass, int maxRetries, ChatRetrievalContext retrievalContext)
      Chat with annotation-defined output and retrieval context.