Package com.tnsai.agents.orchestration

Class AgentOrchestrator

java.lang.Object

com.tnsai.agents.orchestration.AgentOrchestrator

All Implemented Interfaces:

AgentChatOrchestrator.ChatContext, AgentToolExecutor.AgentContext, AgentStreamingSupport.StreamingContext

public final class AgentOrchestrator
extends Object
implements AgentToolExecutor.AgentContext, AgentChatOrchestrator.ChatContext, AgentStreamingSupport.StreamingContext

Orchestrates chat, streaming, tool execution, and knowledge base operations.

Extracted from Agent as part of the god-class refactoring (#47). Implements the three sub-delegate context interfaces so that AgentToolExecutor, AgentChatOrchestrator, and AgentStreamingSupport continue to work unchanged.

Since:

0.3.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	AgentOrchestrator.OrchestratorContext	Bridge interface implemented by Agent to provide core data and callbacks to the orchestrator.

Constructor Summary

Constructors

Constructor	Description
AgentOrchestrator(AgentOrchestrator.OrchestratorContext context, ResilienceExecutor resilienceExecutor, RetryPolicy retryPolicy, AgentRecoveryManager recoveryManager, AgentStateRecoveryManager stateRecoveryManager, List<ErrorRecoveryScenario> errorRecoveryScenarios)

Method Summary

Modifier and Type	Method	Description
String	chat(String message, boolean useHistory, boolean useTools)
String	chat(String message, boolean useHistory, boolean useTools, ChatRetrievalContext retrievalContext)
String	chatInternal(String message, boolean useHistory)	Callback for follow-up chat after tool execution (tools disabled, prevents recursion)
String	chatInternal(String message, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext)	No-tools follow-up preserving the originating RAG turn.
Object	chatInternalWithTools(String message, boolean useHistory)	Callback for follow-up chat with tools enabled (for multi-turn tool loops).
Object	chatInternalWithTools(String message, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext)	Tool-loop follow-up preserving the originating RAG turn.
String	chatWithEvents(String message, String sessionId)
String	chatWithEvents(String message, String sessionId, ChatRetrievalContext retrievalContext)
String	chatWithEvents(String message, Consumer<TnsAIEvent> eventConsumer)
String	chatWithEvents(String message, Consumer<TnsAIEvent> eventConsumer, ChatRetrievalContext retrievalContext)
<T> T	chatWithFormat(String message, Class<T> targetClass, int maxRetries)
<T> T	chatWithFormat(String message, Class<T> targetClass, int maxRetries, ChatRetrievalContext retrievalContext)
<T> T	chatWithFormat(String message, Class<T> targetClass, OutputFormat format, int maxRetries)
<T> T	chatWithFormat(String message, Class<T> targetClass, OutputFormat format, int maxRetries, ChatRetrievalContext retrievalContext)
<T> T	chatWithStructure(String message, OutputParser<T> parser, int maxRetries)
<T> T	chatWithStructure(String message, OutputParser<T> parser, int maxRetries, ChatRetrievalContext retrievalContext)
void	clearConversationHistory()
Object	executeAction(String actionName, Map<String,Object> parameters)
Object	executeAction(String actionName, Map<String,Object> parameters, ChatRetrievalContext retrievalContext)
Object	executeActionOnRole(String roleId, String actionName, Map<String,Object> parameters)
Object	executeActionOnRole(String roleId, String actionName, Map<String,Object> parameters, ChatRetrievalContext retrievalContext)
ActionResponse	executeActionOnRoleTyped(String roleId, ActionRequest request)
ActionResponse	executeActionOnRoleTyped(String roleId, ActionRequest request, ChatRetrievalContext retrievalContext)
Object	executeActionPublic(String actionName, Map<String,Object> parameters)
Object	executeActionPublic(String actionName, Map<String,Object> parameters, ChatRetrievalContext retrievalContext)
ActionResponse	executeActionTyped(ActionRequest request)
ActionResponse	executeActionTyped(ActionRequest request, ChatRetrievalContext retrievalContext)
String	executeToolCalls(ChatResponse chatResponse, boolean useHistory)	Executes tool calls from a ChatResponse
String	executeToolCalls(ChatResponse chatResponse, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext)	Executes tool calls while preserving the originating RAG turn.
AgentToolExecutor.ToolCallResult	executeToolCallWithHooks(ChatResponse.ToolCall toolCall)	Executes a tool call with permission check and listener notification.
AgentToolExecutor.ToolCallResult	executeToolCallWithHooks(ChatResponse.ToolCall toolCall, ChatRetrievalContext retrievalContext)
<T> T	executeWithSpinner(Supplier<T> operation)	Callback for executing spinner-wrapped operations
void	fireOnAfterToolCall(String toolName, Object result, boolean success, long latencyMs)	Fires onAfterToolCall hook
void	fireOnBeforeToolCall(String toolName, Map<String,Object> arguments)	Fires onBeforeToolCall hook
ActionExecutor	getAgentActionExecutor()
Map<String,List<String>>	getAgentActionKnowledge()	The knowledge some actions use instead of what their @ActionSpec names: entry names by action name.
Class<?>	getAgentClass()	Returns the agent's concrete class (for annotation inspection)
String	getAgentId()	Returns the agent's unique identifier
List<KnowledgeEntry>	getAgentKnowledgeEntries()	The agent's action-level knowledge with each entry's use.
Optional<KnowledgeScope>	getAgentKnowledgeScope()
List<KnowledgeSourceConfig>	getAgentKnowledgeSources()	The sources of the agent's action-level knowledge.
LLMClient	getAgentLLM()	Returns the LLM client for chat operations
MemoryStore	getAgentMemoryStore()	Returns the memory store for conversation history
String	getAgentName()	Returns the agent's display name
List<Role>	getAgentRoles()
ToolSchemaGenerator	getAgentSchemaGenerator()
Optional<ChatKnowledgeBinding>	getChatKnowledgeBinding()	Returns the canonical chat retrieval binding, if configured.
Optional<ChatKnowledgeContext>	getChatKnowledgeContext()	Returns the DIRECT and SEQUENTIAL knowledge each chat turn gives, if the agent declares any.
Integer	getContextTokenLimit()
List<Map<String,Object>>	getConversationHistory()
int	getConversationSize()
AgentEnsembleExecutor	getEnsembleExecutor()
EvalContext	getEvalContext()	Gets the evaluation context for metric collection
TnsAIEventPublisher	getEventPublisher()
AgentOutputFormatter	getOutputFormatter()
String	getSystemPrompt()	Returns the system prompt for the agent
String	getToolsDescription()
List<Map<String,Object>>	getToolsForLLM()	Returns the tools available for LLM function calling (List<Map<String, Object>> JSON-Schema fragments).
void	reportKnowledgeUsage(String scope, List<KnowledgeUsage> usage)	Receives what each knowledge source gave one scope: an action name, or "chat" for a chat turn.
void	restartAgent(String reason)	Callback for agent restart
void	setChatKnowledgeBinding(ChatKnowledgeBinding binding)
void	setChatKnowledgeContext(ChatKnowledgeContext knowledge)	Installs the DIRECT and SEQUENTIAL knowledge each chat turn gives.
void	setToolCallFilter(ToolCallFilter filter)
void	setToolCallListener(ToolCallListener listener)
void	shutdown()	Called from Agent.stop() to end context conversations.
Stream<String>	streamChat(String message)
String	streamChatWithRetrievedContext(String outboundMessage, String historyMessage, Consumer<ChatChunk> handler)
String	streamChatWithRetrievedContext(String outboundMessage, String historyMessage, Consumer<ChatChunk> handler, ChatRetrievalContext retrievalContext)
String	streamChatWithTools(String message, Consumer<ChatChunk> handler)
String	streamChatWithTools(String message, Consumer<ChatChunk> handler, ChatRetrievalContext retrievalContext)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

AgentOrchestrator

public AgentOrchestrator(AgentOrchestrator.OrchestratorContext context,
 ResilienceExecutor resilienceExecutor,
 RetryPolicy retryPolicy,
 AgentRecoveryManager recoveryManager,
 AgentStateRecoveryManager stateRecoveryManager,
 List<ErrorRecoveryScenario> errorRecoveryScenarios)

Method Details

getAgentId

public String getAgentId()

Description copied from interface: AgentChatOrchestrator.ChatContext

Returns the agent's unique identifier

Specified by:

getAgentId in interface AgentChatOrchestrator.ChatContext

Specified by:

getAgentId in interface AgentStreamingSupport.StreamingContext

Specified by:

getAgentId in interface AgentToolExecutor.AgentContext

getAgentName

public String getAgentName()

Description copied from interface: AgentChatOrchestrator.ChatContext

Returns the agent's display name

Specified by:

getAgentName in interface AgentChatOrchestrator.ChatContext

Specified by:

getAgentName in interface AgentStreamingSupport.StreamingContext

Specified by:

getAgentName in interface AgentToolExecutor.AgentContext

getAgentRoles

public List<Role> getAgentRoles()

Specified by:

getAgentRoles in interface AgentToolExecutor.AgentContext

getAgentLLM

public LLMClient getAgentLLM()

Description copied from interface: AgentChatOrchestrator.ChatContext

Returns the LLM client for chat operations

Specified by:

getAgentLLM in interface AgentChatOrchestrator.ChatContext

Specified by:

getAgentLLM in interface AgentStreamingSupport.StreamingContext

Specified by:

getAgentLLM in interface AgentToolExecutor.AgentContext

getAgentMemoryStore

public MemoryStore getAgentMemoryStore()

Description copied from interface: AgentChatOrchestrator.ChatContext

Returns the memory store for conversation history

Specified by:

getAgentMemoryStore in interface AgentChatOrchestrator.ChatContext

Specified by:

getAgentMemoryStore in interface AgentStreamingSupport.StreamingContext

Specified by:

getAgentMemoryStore in interface AgentToolExecutor.AgentContext

getAgentActionExecutor

public ActionExecutor getAgentActionExecutor()

Specified by:

getAgentActionExecutor in interface AgentToolExecutor.AgentContext

getAgentSchemaGenerator

public ToolSchemaGenerator getAgentSchemaGenerator()

Specified by:

getAgentSchemaGenerator in interface AgentToolExecutor.AgentContext

getAgentKnowledgeSources

public List<KnowledgeSourceConfig> getAgentKnowledgeSources()

Description copied from interface: AgentToolExecutor.AgentContext

The sources of the agent's action-level knowledge.

Specified by:

getAgentKnowledgeSources in interface AgentToolExecutor.AgentContext

Returns:

action-level knowledge sources

getAgentKnowledgeEntries

public List<KnowledgeEntry> getAgentKnowledgeEntries()

Description copied from interface: AgentToolExecutor.AgentContext

The agent's action-level knowledge with each entry's use. By default every AgentToolExecutor.AgentContext.getAgentKnowledgeSources() source, searched.

Specified by:

getAgentKnowledgeEntries in interface AgentToolExecutor.AgentContext

Returns:

the agent's knowledge entries

getAgentActionKnowledge

public Map<String,List<String>> getAgentActionKnowledge()

Description copied from interface: AgentToolExecutor.AgentContext

The knowledge some actions use instead of what their @ActionSpec names: entry names by action name.

Specified by:

getAgentActionKnowledge in interface AgentToolExecutor.AgentContext

Returns:

entry names by action name; empty by default

getAgentKnowledgeScope

public Optional<KnowledgeScope> getAgentKnowledgeScope()

Specified by:

getAgentKnowledgeScope in interface AgentStreamingSupport.StreamingContext

Specified by:

getAgentKnowledgeScope in interface AgentToolExecutor.AgentContext

executeWithSpinner

public <T> T executeWithSpinner(Supplier<T> operation)

Description copied from interface: AgentToolExecutor.AgentContext

Callback for executing spinner-wrapped operations

Specified by:

executeWithSpinner in interface AgentChatOrchestrator.ChatContext

Specified by:

executeWithSpinner in interface AgentToolExecutor.AgentContext

chatInternal

public String chatInternal(String message,
 boolean useHistory)

Description copied from interface: AgentToolExecutor.AgentContext

Callback for follow-up chat after tool execution (tools disabled, prevents recursion)

Specified by:

chatInternal in interface AgentStreamingSupport.StreamingContext

Specified by:

chatInternal in interface AgentToolExecutor.AgentContext

chatInternalWithTools

public Object chatInternalWithTools(String message,
 boolean useHistory)

Description copied from interface: AgentToolExecutor.AgentContext

Callback for follow-up chat with tools enabled (for multi-turn tool loops). Returns raw Object (ChatResponse or String) so caller can check for more tool calls.

Specified by:

chatInternalWithTools in interface AgentToolExecutor.AgentContext

chatInternalWithTools

public Object chatInternalWithTools(String message,
 boolean useHistory,
 String retrievalQuery,
 ChatRetrievalContext retrievalContext)

Description copied from interface: AgentToolExecutor.AgentContext

Tool-loop follow-up preserving the originating RAG turn.

Specified by:

chatInternalWithTools in interface AgentToolExecutor.AgentContext

chatInternal

public String chatInternal(String message,
 boolean useHistory,
 String retrievalQuery,
 ChatRetrievalContext retrievalContext)

Description copied from interface: AgentToolExecutor.AgentContext

No-tools follow-up preserving the originating RAG turn.

Specified by:

chatInternal in interface AgentToolExecutor.AgentContext

restartAgent

public void restartAgent(String reason)

Description copied from interface: AgentToolExecutor.AgentContext

Callback for agent restart

Specified by:

restartAgent in interface AgentToolExecutor.AgentContext

getEvalContext

public EvalContext getEvalContext()

Description copied from interface: AgentToolExecutor.AgentContext

Gets the evaluation context for metric collection

Specified by:

getEvalContext in interface AgentToolExecutor.AgentContext

fireOnBeforeToolCall

public void fireOnBeforeToolCall(String toolName,
 Map<String,Object> arguments)

Description copied from interface: AgentToolExecutor.AgentContext

Fires onBeforeToolCall hook

Specified by:

fireOnBeforeToolCall in interface AgentToolExecutor.AgentContext

fireOnAfterToolCall

public void fireOnAfterToolCall(String toolName,
 Object result,
 boolean success,
 long latencyMs)

Description copied from interface: AgentToolExecutor.AgentContext

Fires onAfterToolCall hook

Specified by:

fireOnAfterToolCall in interface AgentToolExecutor.AgentContext

getSystemPrompt

public String getSystemPrompt()

Description copied from interface: AgentChatOrchestrator.ChatContext

Returns the system prompt for the agent

Specified by:

getSystemPrompt in interface AgentChatOrchestrator.ChatContext

Specified by:

getSystemPrompt in interface AgentStreamingSupport.StreamingContext

getAgentClass

public Class<?> getAgentClass()

Description copied from interface: AgentChatOrchestrator.ChatContext

Returns the agent's concrete class (for annotation inspection)

Specified by:

getAgentClass in interface AgentChatOrchestrator.ChatContext

getChatKnowledgeBinding

public Optional<ChatKnowledgeBinding> getChatKnowledgeBinding()

Description copied from interface: AgentChatOrchestrator.ChatContext

Returns the canonical chat retrieval binding, if configured.

Specified by:

getChatKnowledgeBinding in interface AgentChatOrchestrator.ChatContext

getChatKnowledgeContext

public Optional<ChatKnowledgeContext> getChatKnowledgeContext()

Description copied from interface: AgentChatOrchestrator.ChatContext

Returns the DIRECT and SEQUENTIAL knowledge each chat turn gives, if the agent declares any.

Specified by:

getChatKnowledgeContext in interface AgentChatOrchestrator.ChatContext

reportKnowledgeUsage

public void reportKnowledgeUsage(String scope,
 List<KnowledgeUsage> usage)

Description copied from interface: AgentToolExecutor.AgentContext

Receives what each knowledge source gave one scope: an action name, or "chat" for a chat turn. Does nothing by default.

Specified by:

reportKnowledgeUsage in interface AgentChatOrchestrator.ChatContext

Specified by:

reportKnowledgeUsage in interface AgentToolExecutor.AgentContext

Parameters:

scope - the action name or "chat"

usage - one row per source, in declaration order

getToolsForLLM

public List<Map<String,Object>> getToolsForLLM()

Description copied from interface: AgentChatOrchestrator.ChatContext

Returns the tools available for LLM function calling (List<Map<String, Object>> JSON-Schema fragments).

Specified by:

getToolsForLLM in interface AgentChatOrchestrator.ChatContext

Specified by:

getToolsForLLM in interface AgentStreamingSupport.StreamingContext

executeToolCalls

public String executeToolCalls(ChatResponse chatResponse,
 boolean useHistory)

Description copied from interface: AgentChatOrchestrator.ChatContext

Executes tool calls from a ChatResponse

Specified by:

executeToolCalls in interface AgentChatOrchestrator.ChatContext

executeToolCalls

public String executeToolCalls(ChatResponse chatResponse,
 boolean useHistory,
 String retrievalQuery,
 ChatRetrievalContext retrievalContext)

Description copied from interface: AgentChatOrchestrator.ChatContext

Executes tool calls while preserving the originating RAG turn.

Specified by:

executeToolCalls in interface AgentChatOrchestrator.ChatContext

getContextTokenLimit

public Integer getContextTokenLimit()

Specified by:

getContextTokenLimit in interface AgentStreamingSupport.StreamingContext

getEventPublisher

public TnsAIEventPublisher getEventPublisher()

Specified by:

getEventPublisher in interface AgentStreamingSupport.StreamingContext

executeAction

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

Specified by:

executeAction in interface AgentStreamingSupport.StreamingContext

executeAction

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

Specified by:

executeAction in interface AgentStreamingSupport.StreamingContext

executeToolCallWithHooks

public AgentToolExecutor.ToolCallResult executeToolCallWithHooks(ChatResponse.ToolCall toolCall)

Description copied from interface: AgentStreamingSupport.StreamingContext

Executes a tool call with permission check and listener notification.

Specified by:

executeToolCallWithHooks in interface AgentStreamingSupport.StreamingContext

executeToolCallWithHooks

public AgentToolExecutor.ToolCallResult executeToolCallWithHooks(ChatResponse.ToolCall toolCall,
 ChatRetrievalContext retrievalContext)

Specified by:

executeToolCallWithHooks in interface AgentStreamingSupport.StreamingContext

chat

public String chat(String message,
 boolean useHistory,
 boolean useTools)

chat

public String chat(String message,
 boolean useHistory,
 boolean useTools,
 ChatRetrievalContext retrievalContext)

chatWithStructure

public <T> T chatWithStructure(String message,
 OutputParser<T> parser,
 int maxRetries)

chatWithStructure

public <T> T chatWithStructure(String message,
 OutputParser<T> parser,
 int maxRetries,
 ChatRetrievalContext retrievalContext)

chatWithFormat

public <T> T chatWithFormat(String message,
 Class<T> targetClass,
 OutputFormat format,
 int maxRetries)

chatWithFormat

public <T> T chatWithFormat(String message,
 Class<T> targetClass,
 OutputFormat format,
 int maxRetries,
 ChatRetrievalContext retrievalContext)

chatWithFormat

public <T> T chatWithFormat(String message,
 Class<T> targetClass,
 int maxRetries)

chatWithFormat

public <T> T chatWithFormat(String message,
 Class<T> targetClass,
 int maxRetries,
 ChatRetrievalContext retrievalContext)

streamChat

public Stream<String> streamChat(String message)

streamChatWithTools

public String streamChatWithTools(String message,
 Consumer<ChatChunk> handler)

streamChatWithTools

public String streamChatWithTools(String message,
 Consumer<ChatChunk> handler,
 ChatRetrievalContext retrievalContext)

streamChatWithRetrievedContext

public String streamChatWithRetrievedContext(String outboundMessage,
 String historyMessage,
 Consumer<ChatChunk> handler)

streamChatWithRetrievedContext

public String streamChatWithRetrievedContext(String outboundMessage,
 String historyMessage,
 Consumer<ChatChunk> handler,
 ChatRetrievalContext retrievalContext)

chatWithEvents

public String chatWithEvents(String message,
 Consumer<TnsAIEvent> eventConsumer)

chatWithEvents

public String chatWithEvents(String message,
 Consumer<TnsAIEvent> eventConsumer,
 ChatRetrievalContext retrievalContext)

chatWithEvents

public String chatWithEvents(String message,
 String sessionId)

chatWithEvents

public String chatWithEvents(String message,
 String sessionId,
 ChatRetrievalContext retrievalContext)

executeActionPublic

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

executeActionPublic

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

executeActionTyped

public ActionResponse executeActionTyped(ActionRequest request)

executeActionTyped

public ActionResponse executeActionTyped(ActionRequest request,
 ChatRetrievalContext retrievalContext)

executeActionOnRole

public Object executeActionOnRole(String roleId,
 String actionName,
 Map<String,Object> parameters)

executeActionOnRole

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

executeActionOnRoleTyped

public ActionResponse executeActionOnRoleTyped(String roleId,
 ActionRequest request)

executeActionOnRoleTyped

public ActionResponse executeActionOnRoleTyped(String roleId,
 ActionRequest request,
 ChatRetrievalContext retrievalContext)

setToolCallFilter

public void setToolCallFilter(ToolCallFilter filter)

setToolCallListener

public void setToolCallListener(ToolCallListener listener)

getToolsDescription

public String getToolsDescription()

setChatKnowledgeBinding

public void setChatKnowledgeBinding(ChatKnowledgeBinding binding)

setChatKnowledgeContext

public void setChatKnowledgeContext(ChatKnowledgeContext knowledge)

Installs the DIRECT and SEQUENTIAL knowledge each chat turn gives.

Parameters:

knowledge - the prepared knowledge, or null for none

Since:

0.18.0

clearConversationHistory

public void clearConversationHistory()

getConversationHistory

public List<Map<String,Object>> getConversationHistory()

getConversationSize

public int getConversationSize()

getEnsembleExecutor

public AgentEnsembleExecutor getEnsembleExecutor()

getOutputFormatter

public AgentOutputFormatter getOutputFormatter()

shutdown

public void shutdown()

Called from Agent.stop() to end context conversations.