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 ClassesModifier and TypeClassDescriptionstatic interfaceBridge interface implemented byAgentto provide core data and callbacks to the orchestrator. -
Constructor Summary
ConstructorsConstructorDescriptionAgentOrchestrator(AgentOrchestrator.OrchestratorContext context, ResilienceExecutor resilienceExecutor, RetryPolicy retryPolicy, AgentRecoveryManager recoveryManager, AgentStateRecoveryManager stateRecoveryManager, List<ErrorRecoveryScenario> errorRecoveryScenarios) -
Method Summary
Modifier and TypeMethodDescriptionchat(String message, boolean useHistory, boolean useTools, ChatRetrievalContext retrievalContext) chatInternal(String message, boolean useHistory) Callback for follow-up chat after tool execution (tools disabled, prevents recursion)chatInternal(String message, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext) No-tools follow-up preserving the originating RAG turn.chatInternalWithTools(String message, boolean useHistory) Callback for follow-up chat with tools enabled (for multi-turn tool loops).chatInternalWithTools(String message, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext) Tool-loop follow-up preserving the originating RAG turn.chatWithEvents(String message, String sessionId) chatWithEvents(String message, String sessionId, ChatRetrievalContext retrievalContext) chatWithEvents(String message, Consumer<TnsAIEvent> eventConsumer) chatWithEvents(String message, Consumer<TnsAIEvent> eventConsumer, ChatRetrievalContext retrievalContext) <T> TchatWithFormat(String message, Class<T> targetClass, int maxRetries) <T> TchatWithFormat(String message, Class<T> targetClass, int maxRetries, ChatRetrievalContext retrievalContext) <T> TchatWithFormat(String message, Class<T> targetClass, OutputFormat format, int maxRetries) <T> TchatWithFormat(String message, Class<T> targetClass, OutputFormat format, int maxRetries, ChatRetrievalContext retrievalContext) <T> TchatWithStructure(String message, OutputParser<T> parser, int maxRetries) <T> TchatWithStructure(String message, OutputParser<T> parser, int maxRetries, ChatRetrievalContext retrievalContext) voidClears the stored conversation and advances the source revision of every chat binding, the MEMORY binding and the other SEARCH binding alike.executeAction(String actionName, Map<String, Object> parameters) executeAction(String actionName, Map<String, Object> parameters, ChatRetrievalContext retrievalContext) executeActionOnRole(String roleId, String actionName, Map<String, Object> parameters, ChatRetrievalContext retrievalContext) executeActionOnRoleTyped(String roleId, ActionRequest request) executeActionOnRoleTyped(String roleId, ActionRequest request, ChatRetrievalContext retrievalContext) executeActionPublic(String actionName, Map<String, Object> parameters) executeActionPublic(String actionName, Map<String, Object> parameters, ChatRetrievalContext retrievalContext) executeActionTyped(ActionRequest request) executeActionTyped(ActionRequest request, ChatRetrievalContext retrievalContext) executeToolCalls(ChatResponse chatResponse, boolean useHistory) Executes tool calls from a ChatResponseexecuteToolCalls(ChatResponse chatResponse, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext) Executes tool calls while preserving the originating RAG turn.Executes a tool call with permission check and listener notification.executeToolCallWithHooks(ChatResponse.ToolCall toolCall, ChatRetrievalContext retrievalContext) <T> TexecuteWithSpinner(Supplier<T> operation) Callback for executing spinner-wrapped operationsvoidfireOnAfterToolCall(String toolName, Object result, boolean success, long latencyMs) Fires onAfterToolCall hookvoidfireOnBeforeToolCall(String toolName, Map<String, Object> arguments) Fires onBeforeToolCall hookThe knowledge some actions use instead of what their@ActionSpecnames: entry names by action name.Class<?> Returns the agent's concrete class (for annotation inspection)Returns the agent's unique identifierThe agent's action-level knowledge with each entry'suse.The sources of the agent's action-level knowledge.Returns the LLM client for chat operationsReturns the memory store for conversation historyReturns the agent's display nameReturns the canonical chat retrieval binding, if configured.The installed chat bindings: the binding of the SEARCH knowledge other than MEMORY first, then the MEMORY binding, each when installed.Returns the DIRECT and SEQUENTIAL knowledge each chat turn gives, if the agent declares any.intGets the evaluation context for metric collectionReturns the system prompt for the agentReturns the tools available for LLM function calling (List<Map<String, Object>>JSON-Schema fragments).voidreportKnowledgeUsage(String scope, List<KnowledgeUsage> usage) Receives what each knowledge source gave onescope: an action name, or"chat"for a chat turn.voidrestartAgent(String reason) Callback for agent restartvoidInstalls the binding of the agent's SEARCH chat knowledge other than MEMORY.voidsetChatKnowledgeContext(ChatKnowledgeContext knowledge) Installs the DIRECT and SEQUENTIAL knowledge each chat turn gives.voidInstalls the binding of the agent's MEMORY chat knowledge, which a chat turn searches beside the bindingsetChatKnowledgeBinding(com.tnsai.rag.ChatKnowledgeBinding)installs.voidsetToolCallFilter(ToolCallFilter filter) voidsetToolCallListener(ToolCallListener listener) voidshutdown()Called from Agent.stop() to end context conversations.streamChat(String message) streamChatWithRetrievedContext(String outboundMessage, String historyMessage, Consumer<ChatChunk> handler) streamChatWithRetrievedContext(String outboundMessage, String historyMessage, Consumer<ChatChunk> handler, ChatRetrievalContext retrievalContext) streamChatWithTools(String message, Consumer<ChatChunk> handler) streamChatWithTools(String message, Consumer<ChatChunk> handler, ChatRetrievalContext retrievalContext)
-
Constructor Details
-
AgentOrchestrator
public AgentOrchestrator(AgentOrchestrator.OrchestratorContext context, ResilienceExecutor resilienceExecutor, RetryPolicy retryPolicy, AgentRecoveryManager recoveryManager, AgentStateRecoveryManager stateRecoveryManager, List<ErrorRecoveryScenario> errorRecoveryScenarios)
-
-
Method Details
-
getAgentId
Description copied from interface:AgentChatOrchestrator.ChatContextReturns the agent's unique identifier- Specified by:
getAgentIdin interfaceAgentChatOrchestrator.ChatContext- Specified by:
getAgentIdin interfaceAgentStreamingSupport.StreamingContext- Specified by:
getAgentIdin interfaceAgentToolExecutor.AgentContext
-
getAgentName
Description copied from interface:AgentChatOrchestrator.ChatContextReturns the agent's display name- Specified by:
getAgentNamein interfaceAgentChatOrchestrator.ChatContext- Specified by:
getAgentNamein interfaceAgentStreamingSupport.StreamingContext- Specified by:
getAgentNamein interfaceAgentToolExecutor.AgentContext
-
getAgentRoles
- Specified by:
getAgentRolesin interfaceAgentToolExecutor.AgentContext
-
getAgentLLM
Description copied from interface:AgentChatOrchestrator.ChatContextReturns the LLM client for chat operations- Specified by:
getAgentLLMin interfaceAgentChatOrchestrator.ChatContext- Specified by:
getAgentLLMin interfaceAgentStreamingSupport.StreamingContext- Specified by:
getAgentLLMin interfaceAgentToolExecutor.AgentContext
-
getAgentMemoryStore
Description copied from interface:AgentChatOrchestrator.ChatContextReturns the memory store for conversation history- Specified by:
getAgentMemoryStorein interfaceAgentChatOrchestrator.ChatContext- Specified by:
getAgentMemoryStorein interfaceAgentStreamingSupport.StreamingContext- Specified by:
getAgentMemoryStorein interfaceAgentToolExecutor.AgentContext
-
getAgentActionExecutor
- Specified by:
getAgentActionExecutorin interfaceAgentToolExecutor.AgentContext
-
getAgentSchemaGenerator
- Specified by:
getAgentSchemaGeneratorin interfaceAgentToolExecutor.AgentContext
-
getAgentKnowledgeSources
Description copied from interface:AgentToolExecutor.AgentContextThe sources of the agent's action-level knowledge.- Specified by:
getAgentKnowledgeSourcesin interfaceAgentToolExecutor.AgentContext- Returns:
- action-level knowledge sources
-
getAgentKnowledgeEntries
Description copied from interface:AgentToolExecutor.AgentContextThe agent's action-level knowledge with each entry'suse. By default everyAgentToolExecutor.AgentContext.getAgentKnowledgeSources()source, searched.- Specified by:
getAgentKnowledgeEntriesin interfaceAgentToolExecutor.AgentContext- Returns:
- the agent's knowledge entries
-
getAgentActionKnowledge
Description copied from interface:AgentToolExecutor.AgentContextThe knowledge some actions use instead of what their@ActionSpecnames: entry names by action name.- Specified by:
getAgentActionKnowledgein interfaceAgentToolExecutor.AgentContext- Returns:
- entry names by action name; empty by default
-
getAgentKnowledgeScope
- Specified by:
getAgentKnowledgeScopein interfaceAgentStreamingSupport.StreamingContext- Specified by:
getAgentKnowledgeScopein interfaceAgentToolExecutor.AgentContext
-
executeWithSpinner
Description copied from interface:AgentToolExecutor.AgentContextCallback for executing spinner-wrapped operations- Specified by:
executeWithSpinnerin interfaceAgentChatOrchestrator.ChatContext- Specified by:
executeWithSpinnerin interfaceAgentToolExecutor.AgentContext
-
chatInternal
Description copied from interface:AgentToolExecutor.AgentContextCallback for follow-up chat after tool execution (tools disabled, prevents recursion)- Specified by:
chatInternalin interfaceAgentStreamingSupport.StreamingContext- Specified by:
chatInternalin interfaceAgentToolExecutor.AgentContext
-
chatInternalWithTools
Description copied from interface:AgentToolExecutor.AgentContextCallback 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:
chatInternalWithToolsin interfaceAgentToolExecutor.AgentContext
-
chatInternalWithTools
public Object chatInternalWithTools(String message, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext) Description copied from interface:AgentToolExecutor.AgentContextTool-loop follow-up preserving the originating RAG turn.- Specified by:
chatInternalWithToolsin interfaceAgentToolExecutor.AgentContext
-
chatInternal
public String chatInternal(String message, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext) Description copied from interface:AgentToolExecutor.AgentContextNo-tools follow-up preserving the originating RAG turn.- Specified by:
chatInternalin interfaceAgentToolExecutor.AgentContext
-
restartAgent
Description copied from interface:AgentToolExecutor.AgentContextCallback for agent restart- Specified by:
restartAgentin interfaceAgentToolExecutor.AgentContext
-
getEvalContext
Description copied from interface:AgentToolExecutor.AgentContextGets the evaluation context for metric collection- Specified by:
getEvalContextin interfaceAgentToolExecutor.AgentContext
-
fireOnBeforeToolCall
Description copied from interface:AgentToolExecutor.AgentContextFires onBeforeToolCall hook- Specified by:
fireOnBeforeToolCallin interfaceAgentToolExecutor.AgentContext
-
fireOnAfterToolCall
Description copied from interface:AgentToolExecutor.AgentContextFires onAfterToolCall hook- Specified by:
fireOnAfterToolCallin interfaceAgentToolExecutor.AgentContext
-
getSystemPrompt
Description copied from interface:AgentChatOrchestrator.ChatContextReturns the system prompt for the agent- Specified by:
getSystemPromptin interfaceAgentChatOrchestrator.ChatContext- Specified by:
getSystemPromptin interfaceAgentStreamingSupport.StreamingContext
-
getAgentClass
Description copied from interface:AgentChatOrchestrator.ChatContextReturns the agent's concrete class (for annotation inspection)- Specified by:
getAgentClassin interfaceAgentChatOrchestrator.ChatContext
-
getChatKnowledgeBinding
Description copied from interface:AgentChatOrchestrator.ChatContextReturns the canonical chat retrieval binding, if configured.- Specified by:
getChatKnowledgeBindingin interfaceAgentChatOrchestrator.ChatContext
-
getChatKnowledgeBindings
The installed chat bindings: the binding of the SEARCH knowledge other than MEMORY first, then the MEMORY binding, each when installed.- Specified by:
getChatKnowledgeBindingsin interfaceAgentChatOrchestrator.ChatContext- Since:
- 0.18.6
-
getChatKnowledgeContext
Description copied from interface:AgentChatOrchestrator.ChatContextReturns the DIRECT and SEQUENTIAL knowledge each chat turn gives, if the agent declares any.- Specified by:
getChatKnowledgeContextin interfaceAgentChatOrchestrator.ChatContext
-
reportKnowledgeUsage
Description copied from interface:AgentToolExecutor.AgentContextReceives what each knowledge source gave onescope: an action name, or"chat"for a chat turn. Does nothing by default.- Specified by:
reportKnowledgeUsagein interfaceAgentChatOrchestrator.ChatContext- Specified by:
reportKnowledgeUsagein interfaceAgentToolExecutor.AgentContext- Parameters:
scope- the action name or"chat"usage- one row per source, in declaration order
-
getToolsForLLM
Description copied from interface:AgentChatOrchestrator.ChatContextReturns the tools available for LLM function calling (List<Map<String, Object>>JSON-Schema fragments).- Specified by:
getToolsForLLMin interfaceAgentChatOrchestrator.ChatContext- Specified by:
getToolsForLLMin interfaceAgentStreamingSupport.StreamingContext
-
executeToolCalls
Description copied from interface:AgentChatOrchestrator.ChatContextExecutes tool calls from a ChatResponse- Specified by:
executeToolCallsin interfaceAgentChatOrchestrator.ChatContext
-
executeToolCalls
public String executeToolCalls(ChatResponse chatResponse, boolean useHistory, String retrievalQuery, ChatRetrievalContext retrievalContext) Description copied from interface:AgentChatOrchestrator.ChatContextExecutes tool calls while preserving the originating RAG turn.- Specified by:
executeToolCallsin interfaceAgentChatOrchestrator.ChatContext
-
getContextTokenLimit
- Specified by:
getContextTokenLimitin interfaceAgentStreamingSupport.StreamingContext
-
getEventPublisher
- Specified by:
getEventPublisherin interfaceAgentStreamingSupport.StreamingContext
-
executeAction
- Specified by:
executeActionin interfaceAgentStreamingSupport.StreamingContext
-
executeAction
public Object executeAction(String actionName, Map<String, Object> parameters, ChatRetrievalContext retrievalContext) - Specified by:
executeActionin interfaceAgentStreamingSupport.StreamingContext
-
executeToolCallWithHooks
Description copied from interface:AgentStreamingSupport.StreamingContextExecutes a tool call with permission check and listener notification.- Specified by:
executeToolCallWithHooksin interfaceAgentStreamingSupport.StreamingContext
-
executeToolCallWithHooks
public AgentToolExecutor.ToolCallResult executeToolCallWithHooks(ChatResponse.ToolCall toolCall, ChatRetrievalContext retrievalContext) - Specified by:
executeToolCallWithHooksin interfaceAgentStreamingSupport.StreamingContext
-
chat
-
chat
public String chat(String message, boolean useHistory, boolean useTools, ChatRetrievalContext retrievalContext) -
chatWithStructure
-
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
-
chatWithFormat
public <T> T chatWithFormat(String message, Class<T> targetClass, int maxRetries, ChatRetrievalContext retrievalContext) -
streamChat
-
streamChatWithTools
-
streamChatWithTools
public String streamChatWithTools(String message, Consumer<ChatChunk> handler, ChatRetrievalContext retrievalContext) -
streamChatWithRetrievedContext
-
streamChatWithRetrievedContext
-
chatWithEvents
-
chatWithEvents
public String chatWithEvents(String message, Consumer<TnsAIEvent> eventConsumer, ChatRetrievalContext retrievalContext) -
chatWithEvents
-
chatWithEvents
public String chatWithEvents(String message, String sessionId, ChatRetrievalContext retrievalContext) -
executeActionPublic
-
executeActionPublic
-
executeActionTyped
-
executeActionTyped
public ActionResponse executeActionTyped(ActionRequest request, ChatRetrievalContext retrievalContext) -
executeActionOnRole
-
executeActionOnRole
-
executeActionOnRoleTyped
-
executeActionOnRoleTyped
public ActionResponse executeActionOnRoleTyped(String roleId, ActionRequest request, ChatRetrievalContext retrievalContext) -
setToolCallFilter
-
setToolCallListener
-
getToolsDescription
-
setChatKnowledgeBinding
Installs the binding of the agent's SEARCH chat knowledge other than MEMORY. A previous such binding is closed.The binding is not checked here:
Agent.setChatKnowledgeBindingchecks a binding against the agent's knowledge and routes it to this method orsetMemoryChatKnowledgeBinding(com.tnsai.rag.ChatKnowledgeBinding).- Parameters:
binding- the binding- Throws:
IllegalStateException- when the chat knowledge lifecycle is closed; the binding is closed first
-
setMemoryChatKnowledgeBinding
Installs the binding of the agent's MEMORY chat knowledge, which a chat turn searches beside the bindingsetChatKnowledgeBinding(com.tnsai.rag.ChatKnowledgeBinding)installs. A previous MEMORY binding is closed.The binding is not checked here:
Agent.setChatKnowledgeBindingchecks a binding against the agent's knowledge and routes it here.- Parameters:
binding- the MEMORY binding- Throws:
IllegalStateException- when the chat knowledge lifecycle is closed; the binding is closed first- Since:
- 0.18.6
-
setChatKnowledgeContext
Installs the DIRECT and SEQUENTIAL knowledge each chat turn gives.- Parameters:
knowledge- the prepared knowledge, ornullfor none- Since:
- 0.18.0
-
clearConversationHistory
public void clearConversationHistory()Clears the stored conversation and advances the source revision of every chat binding, the MEMORY binding and the other SEARCH binding alike. -
getConversationHistory
-
getConversationSize
public int getConversationSize() -
getEnsembleExecutor
-
getOutputFormatter
-
shutdown
public void shutdown()Called from Agent.stop() to end context conversations.
-