Package com.tnsai.agents

Class Agent

java.lang.Object

com.tnsai.agents.Agent

All Implemented Interfaces:

AgentGroupManager.GroupContext, AgentHierarchyManager.HierarchyContext, AgentInitializer.InitializerContext, AgentMessagingHandler.MessagingContext, AgentOrchestrator.OrchestratorContext, AgentCommunicationManager.MessageReceiver

Direct Known Subclasses:

ConfigurableAgent

public abstract class Agent
extends Object
implements AgentCommunicationManager.MessageReceiver, AgentOrchestrator.OrchestratorContext, AgentHierarchyManager.HierarchyContext, AgentMessagingHandler.MessagingContext, AgentInitializer.InitializerContext, AgentGroupManager.GroupContext

Abstract base class for autonomous agents in the TnsAI framework.

Agent = identity (WHO). Role = capabilities (WHAT: @Goal, @State, @Action). Subclasses implement getLLM() and getRoles(). Uses lazy init with double-checked locking; template methods are never called in the constructor.

Supports DI via the 4-arg constructor for testability. Chat, tool execution, streaming, knowledge base are delegated to AgentOrchestrator. Cognitive features (planning, reasoning, evaluation, environment, feedback) are in AgentCognitiveSupport and AgentCapabilities.

Author:

TnsAI Team

See Also:

• Role
• LLMClient
• AgentOrchestrator
• AgentCapabilities

Method Summary

Modifier and Type	Method	Description
final ActionOutcome	actOnEnvironment(String actionName, Map<String,Object> parameters)	Acts on the attached environment.
final void	addChild(Agent child)	Adds a child agent (maintains bidirectional consistency).
final boolean	addChildDirect(Agent child)	Adds a child directly to the internal list.
final void	addChildren(Agent... children)	Adds multiple child agents at once.
final void	addEvalHook(EvalHook hook)	Adds an evaluation hook for metric collection.
final boolean	autoStart()	Returns whether the agent should auto-start (default: true).
final String	chat(String message)	Sends a message to the agent and returns the LLM response.
final String	chat(String message, boolean useHistory)	Sends a message with optional conversation history.
final String	chat(String message, boolean useHistory, boolean useTools)	Sends a message with full control over history and tools.
final String	chat(String message, boolean useHistory, boolean useTools, ChatRetrievalContext retrievalContext)	Sends a message with request-local retrieval isolation and lifecycle context.
final String	chatInternal(String message, boolean useHistory)	Internal chat method for query handling.
final String	chatWithEvents(String message, String sessionId)	Chat with events published to a session on the configured publisher.
final String	chatWithEvents(String message, Consumer<TnsAIEvent> eventConsumer)	Chat with real-time TnsAI event emission (AG-UI integration).
final String	chatWithEvents(String message, Consumer<TnsAIEvent> eventConsumer, ChatRetrievalContext retrievalContext)	Emits events with request-local retrieval isolation and lifecycle context.
final <T> T	chatWithFormat(String message, Class<T> targetClass, int maxRetries)	Chat with structured output using annotation-defined format or JSON default.
final <T> T	chatWithFormat(String message, Class<T> targetClass, int maxRetries, ChatRetrievalContext retrievalContext)	Annotation-formatted chat with request-local retrieval context.
final <T> T	chatWithFormat(String message, Class<T> targetClass, OutputFormat format, int maxRetries)	Chat with structured output in a specific format.
final <T> T	chatWithFormat(String message, Class<T> targetClass, OutputFormat format, int maxRetries, ChatRetrievalContext retrievalContext)	Formatted chat with request-local retrieval isolation and lifecycle context.
final <T> T	chatWithStructure(String message, OutputParser<T> parser, int maxRetries)	Sends a message and returns a structured, validated response using guardrails pattern.
final <T> T	chatWithStructure(String message, OutputParser<T> parser, int maxRetries, ChatRetrievalContext retrievalContext)	Structured chat with request-local retrieval isolation and lifecycle context.
final void	clearConversationHistory()	Clears all stored conversation messages.
final EvalContext	clearEvalContext()	Clears the current evaluation context and creates a new session.
final void	delegateToChild(String childId, String actionName, Map<String,Object> parameters)	Delegates an action to a child agent.
final String	description()	Returns the agent description from @AgentSpec (may be empty).
final void	detachFromParent()	Internal: detaches from parent without triggering bidirectional updates.
final String	did()	Returns the DID (Decentralized Identifier) for this agent.
Agent	enableContextGraph(SnapshotStore snapshotStore, DecisionTraceStore decisionTraceStore)	Enables context graph tracking (decision tracing + snapshots).
final void	ensureEvalContext()
final void	escalateToParent(String actionName, Map<String,Object> parameters)	Escalates an action to the parent agent.
final ActionResponse	executeAction(ActionRequest request)	Executes an action using a typed request.
final ActionResponse	executeAction(ActionRequest request, ChatRetrievalContext retrievalContext)	Executes a typed action request with request-local retrieval context.
final Object	executeAction(String actionName, Object input)	Executes a named action with a typed input bean — Java record, POJO with getX / isX accessors, or class with public fields.
final Object	executeAction(String actionName, Map<String,Object> parameters)	Executes a named action (untyped).
final Object	executeAction(String actionName, Map<String,Object> parameters, ChatRetrievalContext retrievalContext)	Executes an action with request-local retrieval isolation and lifecycle context.
final ActionResponse	executeActionOnRole(String roleId, ActionRequest request)	Executes a typed action on a specific role.
final ActionResponse	executeActionOnRole(String roleId, ActionRequest request, ChatRetrievalContext retrievalContext)	Executes a typed role action with request-local retrieval context.
final Object	executeActionOnRole(String roleId, String actionName, Object input)	Executes an action on a specific role with a typed input bean.
final Object	executeActionOnRole(String roleId, String actionName, Map<String,Object> parameters)	Executes an action on a specific role (untyped).
final Object	executeActionOnRole(String roleId, String actionName, Map<String,Object> parameters, ChatRetrievalContext retrievalContext)	Executes a role action with request-local retrieval context.
final PlannerHandle.PlanResult	executePlan(List<PlannerHandle.PlanStep> steps)	Executes a plan on the first role.
final Map<String,Object>	extractCurrentState()	Extracts current @State from all roles.
final Agent	findChildById(String childId)	Finds a child by ID.
final void	fireOnAfterChat(String result, long latencyMs)
final void	fireOnAfterToolCall(String toolName, Object result, boolean success, long latencyMs)
final void	fireOnBeforeChat(String message)
final void	fireOnBeforeToolCall(String toolName, Map<String,Object> arguments)
final void	fireOnError(Exception e, String context)
final ActionExecutor	getAgentActionExecutor()
final Map<String,List<String>>	getAgentActionKnowledge()	The getActionKnowledge() names, copied.
final Class<?>	getAgentClass()	Returns the agent's class for reflection
final String	getAgentId()	Returns the agent's unique identifier.
final List<KnowledgeEntry>	getAgentKnowledgeEntries()	The agent's knowledge with each entry's use: what its @AgentSpec declares, with the getKnowledge() entries layered over it by name.
final Optional<KnowledgeScope>	getAgentKnowledgeScope()
final List<KnowledgeSourceConfig>	getAgentKnowledgeSources()
final LLMClient	getAgentLLM()
final MemoryStore	getAgentMemoryStore()
final String	getAgentName()	Returns the agent's name for logging.
final Agent	getAgentRef()	Returns the agent reference itself.
final AgentRestartPolicy	getAgentRestartPolicyTemplate()
final List<Role>	getAgentRoles()
final ToolSchemaGenerator	getAgentSchemaGenerator()
final MessageCallbackDispatcher	getCallbackDispatcher()	Returns the callback dispatcher for @OnMessageReceived callbacks.
final Optional<ChatKnowledgeBinding>	getChatKnowledgeBinding()	Returns the owner-scoped canonical chat binding, if configured.
final List<Agent>	getChildren()	Returns the child agents (unmodifiable).
final List<Agent>	getChildrenSnapshot()	Returns an unmodifiable snapshot of the children list.
final AgentCommunicationManager	getCommunicationManager()	Returns the communication manager for inter-agent messaging.
final Communication	getCommunicationTemplate()
final MemoryConsolidationPipeline	getConsolidationPipeline()	Returns the memory consolidation pipeline resolved from @Memory (TAN-5049), or null when the agent has no @Memory annotation or conversation memory is disabled.
Optional<ContextManagerHandle>	getContextManager()	Returns the context manager if context graph is enabled.
final ContextManagerHandle	getContextManagerDirect()
final List<Map<String,Object>>	getConversationHistory()	Returns an immutable copy of the conversation history.
final int	getConversationSize()	Returns the number of messages in conversation history.
final RetryPolicy	getDefaultRetryPolicyTemplate()
final AgentEnsembleExecutor	getEnsembleExecutor()	Returns the ensemble executor for parallel LLM operations.
final Optional<Environment>	getEnvironment()	Returns the environment if configured.
final List<ErrorRecoveryScenario>	getErrorRecoveryScenariosDirect()
final List<ErrorRecoveryScenario>	getErrorRecoveryScenariosTemplate()
final EvalContext	getEvalContext()
final EventHandlerRegistry	getEventHandlerRegistry()
final TnsAIEventPublisher	getEventPublisher()
final FeedbackCollector	getFeedbackCollector()	Returns the feedback collector (never null; no-op if tnsai-intelligence absent).
final Set<AgentGroup>	getGroups()	Returns all groups this agent is a member of.
final AgentHealthState	getHealthState()	Returns the current resilience health state.
final String	getId()	Alias for getAgentId().
final List<AgentIdentity>	getIdentitiesTemplate()
final long	getIdleTime()	Returns milliseconds since last activity, or -1 if not monitored.
final ActionExecutor	getInjectedActionExecutor()
final LLMClient	getInjectedLLM()
final MemoryStore	getInjectedMemoryStore()
final Optional<ReasoningStrategyHandle.ReasoningResult>	getLastReasoningResult()	Returns the last reasoning result, or empty.
final LLMClient	getLLMTemplate()
final Integer	getMaxContextTokensDirect()
final Optional<Integer>	getMaxContextTokensTemplate()
final MemoryStore	getMemoryStoreTemplate()
final String	getName()	Alias for getAgentName().
final AgentOutputFormatter	getOutputFormatter()	Returns the output formatter for serialization.
final Agent	getParent()	Returns the parent agent, or null if root.
final Agent	getParentRef()	Returns the current parent agent.
final PaymentBroker	getPaymentBroker()	Returns the payment broker (never null; defaults to PaymentBroker.noOp()).
final Optional<PlannerHandle>	getPlannerHandle()	Returns the planner handle if configured.
final List<Plan>	getPlansTemplate()
final ProtocolManagerHandle	getProtocolManager()	Returns the protocol manager (null if no protocol annotations).
final Optional<ReasoningStrategyHandle>	getReasoningStrategy()	Returns the reasoning strategy if configured.
final ReasoningStrategyHandle	getReasoningStrategyRaw()
final AgentResilienceManager	getResilienceManager()	Returns the resilience manager.
final Optional<RetrievalConfig>	getRetrievalConfig()	The settings a chat turn searches with: the chat defaults under the merged search of the SEARCH entries in the chat scope of getAgentKnowledgeEntries().
final Role	getRole()	Returns the primary (first) role, or null.
final List<Role>	getRolesTemplate()
final SkillManager	getSkillManager()	Returns the wired SkillManager, or null when no SkillStore was configured on the builder.
final AgentState	getState()	Returns the agent's current lifecycle state.
final String	getSystemPrompt()	Returns the complete system prompt (identity + roles + learned behavior).
final String	getSystemPromptForMessage(String latestUserMessage)	System prompt rendered for a specific user message — used by the chat orchestrator so the SkillResolver sees the latest turn and can surface the most-relevant descriptions for that turn (TNS-289).
final String	getToolsDescription()	Returns a human-readable description of all available tools/actions.
final List<Map<String,Object>>	getToolsForLLM()	Returns tool catalog as JSON-Schema fragments for LLM binding (List<Map<String, Object>> per Anthropic-style tool-use).
final AgentVariant	getVariant()	Gets the current agent variant (quality/speed/cost tier).
final VariantSelector	getVariantSelector()	Gets the configured variant selector.
final void	handleCNPMessageHook(AgentMessage message, CNPMessageType type)	Hook for CNP message handling (delegated back to Agent for override support).
void	handleMessage(AgentMessage message)	Handles an incoming agent message.
final boolean	hasChild(Agent child)	Checks if the given agent is a child.
final String	id()	Returns the agent ID (never null, no init required).
final int	idleTimeoutMs()	Returns the idle timeout in milliseconds (0 = never suspend).
final long	invalidateChatKnowledge()	Advances the chat source revision used by subsequent retrievals.
final Optional<ActiveSkill>	invokeSkill(String name, List<String> arguments, Map<String,String> environment)	Programmatically activate a skill by name (TNS-289).
final boolean	isContextGraphEnabled()
final boolean	isEnvironmentEnabled()	Returns true if an environment is attached.
final boolean	isEvalEnabled()	Checks if evaluation hooks are enabled.
final boolean	isIdleMonitoringEnabled()	Returns true if idle monitoring is active.
final boolean	isPlanningEnabled()	Returns true if a PlannerHandle is configured.
final boolean	isReasoningEnabled()
final void	joinGroup(AgentGroup group)	Joins an existing group.
final void	joinGroup(String groupId)	Joins a group by ID.
final void	leaveGroup(AgentGroup group)	Leaves a group.
final void	leaveGroup(String groupId)	Leaves a group by ID.
final LLMClient	llm()	Returns the LLM client used by this agent.
final String	name()	Returns the human-readable agent name (derived from class name).
final void	notifyActivity()
final Percept	perceive()	Perceives the current environment state.
final List<PlannerHandle.PlanStep>	plan()	Generates a plan for all unsatisfied goals.
final List<PlannerHandle.PlanStep>	planForGoal(String goalName)	Generates a plan for a specific goal.
final void	receiveMessage(AgentMessage message)
final void	recordGoalCompletion(String goalId, boolean success, Map<String,Object> details)	Manually records a goal completion event for evaluation.
final void	recordToolOutcome(String toolName, Object result, boolean success, long latencyMs)
final void	removeChild(Agent child)	Removes a child agent.
final boolean	removeChildDirect(Agent child)	Removes a child directly from the internal list.
final boolean	removeEvalHook(EvalHook hook)	Removes an evaluation hook.
void	reportKnowledgeUsage(String scope, List<KnowledgeUsage> usage)	Hands a call's knowledge usage to the listener.
final AgentVariant	resolveVariant(String taskDescription)	Resolves the effective variant for a given task.
final void	restartAgent(String reason)	Restarts the agent with fresh state.
final List<Role>	roles()	Returns the assigned roles (never null, never empty).
final void	setChatKnowledgeBinding(ChatKnowledgeBinding binding)	Binds a live or provider-backed canonical retrieval source to chat.
final void	setCommunicationManager(AgentCommunicationManager manager)	Sets the communication manager for inter-agent messaging.
final void	setEnvironment(Environment environment)	Sets the environment (null to detach).
final void	setEvalEnabled(boolean enabled)	Enables or disables evaluation hooks.
final void	setEventPublisher(TnsAIEventPublisher eventPublisher)	Sets the event publisher for event-based chat methods.
final void	setFeedbackCollector(FeedbackCollector collector)	Sets the feedback collector (null resets to no-op).
final void	setLastReasoningResult(ReasoningStrategyHandle.ReasoningResult result)
final void	setLLM(LLMClient newLlm)	Replaces the LLM client; conversation history is preserved.
final void	setParent(Agent parent)	Sets the parent agent (maintains bidirectional consistency).
final void	setParentRef(Agent parent)	Sets the parent agent reference directly (no bidirectional updates).
final void	setPaymentBroker(PaymentBroker broker)	Sets the payment broker (null resets to PaymentBroker.noOp()).
final void	setPlannerHandle(PlannerHandle handle)	Sets the planner handle (null to disable).
final void	setReasoningStrategy(ReasoningStrategyHandle strategy)	Sets the reasoning strategy (null to disable).
final void	setToolCallFilter(ToolCallFilter filter)	Sets a filter controlling which tool calls are allowed.
final void	setToolCallListener(ToolCallListener listener)	Sets a listener for tool call lifecycle events.
final void	setVariant(AgentVariant variant)	Sets the agent variant for runtime quality tier switching.
final void	setVariantSelector(VariantSelector selector)	Sets the variant selector for automatic variant selection.
final void	start()	No-op: protocols auto-start when annotations are detected.
final void	stop()	Stops the protocol manager, idle monitor, role registry and releases resources.
final Stream<String>	streamChat(String message)	Streams response tokens without tool support.
final String	streamChatWithRetrievedContext(String outboundMessage, String historyMessage, Consumer<ChatChunk> handler)	Streams canonically fenced retrieved context while persisting only the original user message.
final String	streamChatWithRetrievedContext(String outboundMessage, String historyMessage, Consumer<ChatChunk> handler, ChatRetrievalContext retrievalContext)	Streams pre-rendered evidence with request-local retrieval lifecycle context.
final String	streamChatWithTools(String message, Consumer<ChatChunk> handler)	Streams response with full tool-calling loop.
final String	streamChatWithTools(String message, Consumer<ChatChunk> handler, ChatRetrievalContext retrievalContext)	Streams tools with request-local retrieval isolation and lifecycle context.
final String	version()	Returns the agent version from @AgentSpec (default: "1.0.0").

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.tnsai.agents.init.AgentInitializer.InitializerContext

getAutoStartOverride, getDescriptionOverride, getDidConfigOverride, getGroupSpecOverride, getIdleTimeoutMsOverride, getVersionOverride

Method Details

getState

public final AgentState getState()

Returns the agent's current lifecycle state. See AgentState for the transition graph.

Since:

0.5.0 (issue #21)

reportKnowledgeUsage

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

Hands a call's knowledge usage to the listener. A listener that throws is logged at WARN and the turn or action continues.

Specified by:

reportKnowledgeUsage in interface AgentOrchestrator.OrchestratorContext

Parameters:

scope - "chat" or the action name

usage - one row per source, in declaration order

Since:

0.18.0

getAgentId

public final String getAgentId()

Description copied from interface: AgentHierarchyManager.HierarchyContext

Returns the agent's unique identifier.

Specified by:

getAgentId in interface AgentGroupManager.GroupContext

Specified by:

getAgentId in interface AgentHierarchyManager.HierarchyContext

Specified by:

getAgentId in interface AgentInitializer.InitializerContext

Specified by:

getAgentId in interface AgentMessagingHandler.MessagingContext

Specified by:

getAgentId in interface AgentOrchestrator.OrchestratorContext

getId

public final String getId()

Alias for getAgentId().

getName

public final String getName()

Alias for getAgentName().

getRole

public final Role getRole()

Returns the primary (first) role, or null.

handleMessage

public void handleMessage(AgentMessage message)

Handles an incoming agent message. Override for custom behavior.

getAgentName

public final String getAgentName()

Description copied from interface: AgentMessagingHandler.MessagingContext

Returns the agent's name for logging.

Specified by:

getAgentName in interface AgentMessagingHandler.MessagingContext

Specified by:

getAgentName in interface AgentOrchestrator.OrchestratorContext

getAgentRoles

public final List<Role> getAgentRoles()

Specified by:

getAgentRoles in interface AgentOrchestrator.OrchestratorContext

getAgentLLM

public final LLMClient getAgentLLM()

Specified by:

getAgentLLM in interface AgentOrchestrator.OrchestratorContext

getAgentMemoryStore

public final MemoryStore getAgentMemoryStore()

Specified by:

getAgentMemoryStore in interface AgentOrchestrator.OrchestratorContext

getConsolidationPipeline

public final MemoryConsolidationPipeline getConsolidationPipeline()

Returns the memory consolidation pipeline resolved from @Memory (TAN-5049), or null when the agent has no @Memory annotation or conversation memory is disabled.

The pipeline is driven automatically on stop() (final consolidation via onSessionEnd()). @Memory.conversation() exposes no interval setting, so periodic auto-consolidation is NOT started by the framework — call MemoryConsolidationPipeline.startAutoConsolidation(java.time.Duration) yourself if you want time-based consolidation, or onIdle() / consolidate() for event-/demand-driven runs.

clearConversationHistory

public final void clearConversationHistory()

Clears all stored conversation messages. @see AgentOrchestrator#clearConversationHistory()

getConversationHistory

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

Returns an immutable copy of the conversation history. @see AgentOrchestrator#getConversationHistory()

getConversationSize

public final int getConversationSize()

Returns the number of messages in conversation history. @see AgentOrchestrator#getConversationSize()

getAgentActionExecutor

public final ActionExecutor getAgentActionExecutor()

Specified by:

getAgentActionExecutor in interface AgentOrchestrator.OrchestratorContext

getAgentSchemaGenerator

public final ToolSchemaGenerator getAgentSchemaGenerator()

Specified by:

getAgentSchemaGenerator in interface AgentOrchestrator.OrchestratorContext

getAgentRef

public final Agent getAgentRef()

Description copied from interface: AgentHierarchyManager.HierarchyContext

Returns the agent reference itself.

Specified by:

getAgentRef in interface AgentGroupManager.GroupContext

Specified by:

getAgentRef in interface AgentHierarchyManager.HierarchyContext

getParentRef

public final Agent getParentRef()

Description copied from interface: AgentHierarchyManager.HierarchyContext

Returns the current parent agent.

Specified by:

getParentRef in interface AgentHierarchyManager.HierarchyContext

setParentRef

public final void setParentRef(Agent parent)

Description copied from interface: AgentHierarchyManager.HierarchyContext

Sets the parent agent reference directly (no bidirectional updates).

Specified by:

setParentRef in interface AgentHierarchyManager.HierarchyContext

getChildrenSnapshot

public final List<Agent> getChildrenSnapshot()

Description copied from interface: AgentHierarchyManager.HierarchyContext

Returns an unmodifiable snapshot of the children list.

Specified by:

getChildrenSnapshot in interface AgentHierarchyManager.HierarchyContext

hasChild

public final boolean hasChild(Agent child)

Description copied from interface: AgentHierarchyManager.HierarchyContext

Checks if the given agent is a child.

Specified by:

hasChild in interface AgentHierarchyManager.HierarchyContext

addChildDirect

public final boolean addChildDirect(Agent child)

Description copied from interface: AgentHierarchyManager.HierarchyContext

Adds a child directly to the internal list.

Specified by:

addChildDirect in interface AgentHierarchyManager.HierarchyContext

Returns:

true if added, false if already present

removeChildDirect

public final boolean removeChildDirect(Agent child)

Description copied from interface: AgentHierarchyManager.HierarchyContext

Removes a child directly from the internal list.

Specified by:

removeChildDirect in interface AgentHierarchyManager.HierarchyContext

Returns:

true if removed, false if not present

findChildById

public final Agent findChildById(String childId)

Description copied from interface: AgentHierarchyManager.HierarchyContext

Finds a child by ID.

Specified by:

findChildById in interface AgentHierarchyManager.HierarchyContext

Returns:

the child agent or null if not found

getCommunicationManager

public final AgentCommunicationManager getCommunicationManager()

Description copied from interface: AgentHierarchyManager.HierarchyContext

Returns the communication manager for inter-agent messaging.

Specified by:

getCommunicationManager in interface AgentHierarchyManager.HierarchyContext

Specified by:

getCommunicationManager in interface AgentMessagingHandler.MessagingContext

detachFromParent

public final void detachFromParent()

Internal: detaches from parent without triggering bidirectional updates.

getCallbackDispatcher

public final MessageCallbackDispatcher getCallbackDispatcher()

Description copied from interface: AgentMessagingHandler.MessagingContext

Returns the callback dispatcher for @OnMessageReceived callbacks.

Specified by:

getCallbackDispatcher in interface AgentMessagingHandler.MessagingContext

chatInternal

public final String chatInternal(String message,
 boolean useHistory)

Description copied from interface: AgentMessagingHandler.MessagingContext

Internal chat method for query handling.

Specified by:

chatInternal in interface AgentMessagingHandler.MessagingContext

handleCNPMessageHook

public final void handleCNPMessageHook(AgentMessage message,
 CNPMessageType type)

Description copied from interface: AgentMessagingHandler.MessagingContext

Hook for CNP message handling (delegated back to Agent for override support).

Specified by:

handleCNPMessageHook in interface AgentMessagingHandler.MessagingContext

getMaxContextTokensDirect

public final Integer getMaxContextTokensDirect()

Specified by:

getMaxContextTokensDirect in interface AgentOrchestrator.OrchestratorContext

getErrorRecoveryScenariosDirect

public final List<ErrorRecoveryScenario> getErrorRecoveryScenariosDirect()

Specified by:

getErrorRecoveryScenariosDirect in interface AgentOrchestrator.OrchestratorContext

getEventPublisher

public final TnsAIEventPublisher getEventPublisher()

Specified by:

getEventPublisher in interface AgentOrchestrator.OrchestratorContext

getEventHandlerRegistry

public final EventHandlerRegistry getEventHandlerRegistry()

Specified by:

getEventHandlerRegistry in interface AgentOrchestrator.OrchestratorContext

ensureEvalContext

public final void ensureEvalContext()

Specified by:

ensureEvalContext in interface AgentOrchestrator.OrchestratorContext

getEvalContext

public final EvalContext getEvalContext()

Specified by:

getEvalContext in interface AgentOrchestrator.OrchestratorContext

fireOnBeforeChat

public final void fireOnBeforeChat(String message)

Specified by:

fireOnBeforeChat in interface AgentOrchestrator.OrchestratorContext

fireOnAfterChat

public final void fireOnAfterChat(String result,
 long latencyMs)

Specified by:

fireOnAfterChat in interface AgentOrchestrator.OrchestratorContext

fireOnError

public final void fireOnError(Exception e,
 String context)

Specified by:

fireOnError in interface AgentOrchestrator.OrchestratorContext

fireOnBeforeToolCall

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

Specified by:

fireOnBeforeToolCall in interface AgentOrchestrator.OrchestratorContext

fireOnAfterToolCall

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

Specified by:

fireOnAfterToolCall in interface AgentOrchestrator.OrchestratorContext

recordToolOutcome

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

Specified by:

recordToolOutcome in interface AgentOrchestrator.OrchestratorContext

isReasoningEnabled

public final boolean isReasoningEnabled()

Specified by:

isReasoningEnabled in interface AgentOrchestrator.OrchestratorContext

getReasoningStrategyRaw

public final ReasoningStrategyHandle getReasoningStrategyRaw()

Specified by:

getReasoningStrategyRaw in interface AgentOrchestrator.OrchestratorContext

setLastReasoningResult

public final void setLastReasoningResult(ReasoningStrategyHandle.ReasoningResult result)

Specified by:

setLastReasoningResult in interface AgentOrchestrator.OrchestratorContext

notifyActivity

public final void notifyActivity()

Specified by:

notifyActivity in interface AgentOrchestrator.OrchestratorContext

isContextGraphEnabled

public final boolean isContextGraphEnabled()

Specified by:

isContextGraphEnabled in interface AgentOrchestrator.OrchestratorContext

getContextManagerDirect

public final ContextManagerHandle getContextManagerDirect()

Specified by:

getContextManagerDirect in interface AgentOrchestrator.OrchestratorContext

setToolCallFilter

public final void setToolCallFilter(ToolCallFilter filter)

Sets a filter controlling which tool calls are allowed. @see AgentOrchestrator#setToolCallFilter

setToolCallListener

public final void setToolCallListener(ToolCallListener listener)

Sets a listener for tool call lifecycle events. @see AgentOrchestrator#setToolCallListener

setChatKnowledgeBinding

public final void setChatKnowledgeBinding(ChatKnowledgeBinding binding)

Binds a live or provider-backed canonical retrieval source to chat. A builder-supplied KnowledgeBase is installed as a snapshot binding and retains precedence during initialization.

getChatKnowledgeBinding

public final Optional<ChatKnowledgeBinding> getChatKnowledgeBinding()

Returns the owner-scoped canonical chat binding, if configured.

invalidateChatKnowledge

public final long invalidateChatKnowledge()

Advances the chat source revision used by subsequent retrievals.

getFeedbackCollector

public final FeedbackCollector getFeedbackCollector()

Returns the feedback collector (never null; no-op if tnsai-intelligence absent). @see AgentCapabilities#getFeedbackCollector()

setFeedbackCollector

public final void setFeedbackCollector(FeedbackCollector collector)

Sets the feedback collector (null resets to no-op). @see AgentCapabilities#setFeedbackCollector

getPaymentBroker

public final PaymentBroker getPaymentBroker()

Returns the payment broker (never null; defaults to PaymentBroker.noOp()). @see AgentCapabilities#getPaymentBroker()

setPaymentBroker

public final void setPaymentBroker(PaymentBroker broker)

Sets the payment broker (null resets to PaymentBroker.noOp()). @see AgentCapabilities#setPaymentBroker

getAgentClass

public final Class<?> getAgentClass()

Description copied from interface: AgentInitializer.InitializerContext

Returns the agent's class for reflection

Specified by:

getAgentClass in interface AgentInitializer.InitializerContext

Specified by:

getAgentClass in interface AgentOrchestrator.OrchestratorContext

getLLMTemplate

public final LLMClient getLLMTemplate()

Specified by:

getLLMTemplate in interface AgentInitializer.InitializerContext

getRolesTemplate

public final List<Role> getRolesTemplate()

Specified by:

getRolesTemplate in interface AgentInitializer.InitializerContext

getIdentitiesTemplate

public final List<AgentIdentity> getIdentitiesTemplate()

Specified by:

getIdentitiesTemplate in interface AgentInitializer.InitializerContext

getCommunicationTemplate

public final Communication getCommunicationTemplate()

Specified by:

getCommunicationTemplate in interface AgentInitializer.InitializerContext

getPlansTemplate

public final List<Plan> getPlansTemplate()

Specified by:

getPlansTemplate in interface AgentInitializer.InitializerContext

getErrorRecoveryScenariosTemplate

public final List<ErrorRecoveryScenario> getErrorRecoveryScenariosTemplate()

Specified by:

getErrorRecoveryScenariosTemplate in interface AgentInitializer.InitializerContext

getMemoryStoreTemplate

public final MemoryStore getMemoryStoreTemplate()

Specified by:

getMemoryStoreTemplate in interface AgentInitializer.InitializerContext

getMaxContextTokensTemplate

public final Optional<Integer> getMaxContextTokensTemplate()

Specified by:

getMaxContextTokensTemplate in interface AgentInitializer.InitializerContext

getRetrievalConfig

public final Optional<RetrievalConfig> getRetrievalConfig()

The settings a chat turn searches with: the chat defaults under the merged search of the SEARCH entries in the chat scope of getAgentKnowledgeEntries().

Returns:

the chat search settings, or empty when chat searches nothing

Since:

0.13.0

getAgentKnowledgeSources

public final List<KnowledgeSourceConfig> getAgentKnowledgeSources()

Specified by:

getAgentKnowledgeSources in interface AgentOrchestrator.OrchestratorContext

Returns:

the sources of the agent's action-level knowledge

getAgentKnowledgeEntries

public final List<KnowledgeEntry> getAgentKnowledgeEntries()

The agent's knowledge with each entry's use: what its @AgentSpec declares, with the getKnowledge() entries layered over it by name.

Specified by:

getAgentKnowledgeEntries in interface AgentOrchestrator.OrchestratorContext

Returns:

the agent's knowledge with each entry's use; by default every AgentOrchestrator.OrchestratorContext.getAgentKnowledgeSources() source, searched

Since:

0.18.0

getAgentActionKnowledge

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

The getActionKnowledge() names, copied.

Specified by:

getAgentActionKnowledge in interface AgentOrchestrator.OrchestratorContext

Returns:

entry names by action name that replace an action's own knowledge; empty by default

Since:

0.18.0

getAgentKnowledgeScope

public final Optional<KnowledgeScope> getAgentKnowledgeScope()

Specified by:

getAgentKnowledgeScope in interface AgentOrchestrator.OrchestratorContext

getDefaultRetryPolicyTemplate

public final RetryPolicy getDefaultRetryPolicyTemplate()

Specified by:

getDefaultRetryPolicyTemplate in interface AgentInitializer.InitializerContext

getAgentRestartPolicyTemplate

public final AgentRestartPolicy getAgentRestartPolicyTemplate()

Specified by:

getAgentRestartPolicyTemplate in interface AgentInitializer.InitializerContext

getInjectedLLM

public final LLMClient getInjectedLLM()

Specified by:

getInjectedLLM in interface AgentInitializer.InitializerContext

getInjectedMemoryStore

public final MemoryStore getInjectedMemoryStore()

Specified by:

getInjectedMemoryStore in interface AgentInitializer.InitializerContext

getInjectedActionExecutor

public final ActionExecutor getInjectedActionExecutor()

Specified by:

getInjectedActionExecutor in interface AgentInitializer.InitializerContext

id

public final String id()

Returns the agent ID (never null, no init required).

Specified by:

id in interface AgentCommunicationManager.MessageReceiver

name

public final String name()

Returns the human-readable agent name (derived from class name).

description

public final String description()

Returns the agent description from @AgentSpec (may be empty).

version

public final String version()

Returns the agent version from @AgentSpec (default: "1.0.0").

autoStart

public final boolean autoStart()

Returns whether the agent should auto-start (default: true).

idleTimeoutMs

public final int idleTimeoutMs()

Returns the idle timeout in milliseconds (0 = never suspend).

did

public final String did()

Returns the DID (Decentralized Identifier) for this agent.

roles

public final List<Role> roles()

Returns the assigned roles (never null, never empty).

llm

public final LLMClient llm()

Returns the LLM client used by this agent.

setLLM

public final void setLLM(LLMClient newLlm)

Replaces the LLM client; conversation history is preserved.

getProtocolManager

public final ProtocolManagerHandle getProtocolManager()

Returns the protocol manager (null if no protocol annotations).

getHealthState

public final AgentHealthState getHealthState()

Returns the current resilience health state. @see AgentCapabilities#getHealthState()

getResilienceManager

public final AgentResilienceManager getResilienceManager()

Returns the resilience manager. @see AgentCapabilities#getResilienceManager()

getVariant

public final AgentVariant getVariant()

Gets the current agent variant (quality/speed/cost tier).

setVariant

public final void setVariant(AgentVariant variant)

Sets the agent variant for runtime quality tier switching.

setVariantSelector

public final void setVariantSelector(VariantSelector selector)

Sets the variant selector for automatic variant selection.

getVariantSelector

public final VariantSelector getVariantSelector()

Gets the configured variant selector.

resolveVariant

public final AgentVariant resolveVariant(String taskDescription)

Resolves the effective variant for a given task.

getSystemPrompt

public final String getSystemPrompt()

Returns the complete system prompt (identity + roles + learned behavior). Sent to LLM with every request.

Specified by:

getSystemPrompt in interface AgentOrchestrator.OrchestratorContext

getSystemPromptForMessage

public final String getSystemPromptForMessage(String latestUserMessage)

System prompt rendered for a specific user message — used by the chat orchestrator so the SkillResolver sees the latest turn and can surface the most-relevant descriptions for that turn (TNS-289).

When no SkillStore is wired, this is exactly getSystemPrompt().

invokeSkill

public final Optional<ActiveSkill> invokeSkill(String name,
 List<String> arguments,
 Map<String,String> environment)

Programmatically activate a skill by name (TNS-289). Equivalent to the user typing /skill-name args... but bypasses the user-invocable flag so framework code can drive activation regardless of the skill's user-facing visibility.

Returns:

the ActiveSkill on success, or Optional.empty() if no skill with the given name is registered or no skill manager is wired

getSkillManager

public final SkillManager getSkillManager()

Returns the wired SkillManager, or null when no SkillStore was configured on the builder.

setCommunicationManager

public final void setCommunicationManager(AgentCommunicationManager manager)

Sets the communication manager for inter-agent messaging.

start

public final void start()

No-op: protocols auto-start when annotations are detected.

stop

public final void stop()

Stops the protocol manager, idle monitor, role registry and releases resources. Idempotent — calling on an already-stopped agent is a no-op (issue #21). Transitions RUNNING → STOPPING → STOPPED; if called from STARTING the agent transitions directly to STOPPED without ever reaching RUNNING.

addEvalHook

public final void addEvalHook(EvalHook hook)

Adds an evaluation hook for metric collection.

removeEvalHook

public final boolean removeEvalHook(EvalHook hook)

Removes an evaluation hook.

clearEvalContext

public final EvalContext clearEvalContext()

Clears the current evaluation context and creates a new session.

setEvalEnabled

public final void setEvalEnabled(boolean enabled)

Enables or disables evaluation hooks.

isEvalEnabled

public final boolean isEvalEnabled()

Checks if evaluation hooks are enabled.

recordGoalCompletion

public final void recordGoalCompletion(String goalId,
 boolean success,
 Map<String,Object> details)

Manually records a goal completion event for evaluation.

restartAgent

public final void restartAgent(String reason)

Restarts the agent with fresh state.

Specified by:

restartAgent in interface AgentOrchestrator.OrchestratorContext

chat

public final String chat(String message)

Sends a message to the agent and returns the LLM response. Uses history and tools by default.

chat

public final String chat(String message,
 boolean useHistory)

Sends a message with optional conversation history. Tools enabled by default.

chat

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

Sends a message with full control over history and tools.

chat

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

Sends a message with request-local retrieval isolation and lifecycle context.

chatWithStructure

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

Sends a message and returns a structured, validated response using guardrails pattern.

chatWithStructure

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

Structured chat with request-local retrieval isolation and lifecycle context.

chatWithFormat

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

Chat with structured output in a specific format.

chatWithFormat

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

Formatted chat with request-local retrieval isolation and lifecycle context.

chatWithFormat

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

Chat with structured output using annotation-defined format or JSON default.

chatWithFormat

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

Annotation-formatted chat with request-local retrieval context.

getEnsembleExecutor

public final AgentEnsembleExecutor getEnsembleExecutor()

Returns the ensemble executor for parallel LLM operations. @see AgentOrchestrator#getEnsembleExecutor()

getOutputFormatter

public final AgentOutputFormatter getOutputFormatter()

Returns the output formatter for serialization. @see AgentOrchestrator#getOutputFormatter()

streamChat

public final Stream<String> streamChat(String message)

Streams response tokens without tool support. @see AgentOrchestrator#streamChat(String)

streamChatWithTools

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

Streams response with full tool-calling loop. @see AgentOrchestrator#streamChatWithTools

streamChatWithTools

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

Streams tools with request-local retrieval isolation and lifecycle context.

streamChatWithRetrievedContext

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

Streams canonically fenced retrieved context while persisting only the original user message.

Parameters:

outboundMessage - message sent to the LLM for this request

historyMessage - original user message persisted in conversation history

handler - callback receiving streamed chunks

Returns:

the complete response

streamChatWithRetrievedContext

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

Streams pre-rendered evidence with request-local retrieval lifecycle context.

chatWithEvents

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

Chat with real-time TnsAI event emission (AG-UI integration). @see AgentOrchestrator#chatWithEvents

chatWithEvents

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

Emits events with request-local retrieval isolation and lifecycle context.

chatWithEvents

public final String chatWithEvents(String message,
 String sessionId)

Chat with events published to a session on the configured publisher. @see #setEventPublisher

setEventPublisher

public final void setEventPublisher(TnsAIEventPublisher eventPublisher)

Sets the event publisher for event-based chat methods.

executeAction

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

Executes a named action (untyped). Prefer executeAction(com.tnsai.actions.model.ActionRequest). @see AgentOrchestrator#executeActionPublic

Specified by:

executeAction in interface AgentMessagingHandler.MessagingContext

executeAction

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

Executes an action with request-local retrieval isolation and lifecycle context.

executeAction

public final Object executeAction(String actionName,
 Object input)

Executes a named action with a typed input bean — Java record, POJO with getX / isX accessors, or class with public fields. The bean's components are mapped to the action's parameter parameters by name via ParamBeanMapper.

Eliminates the Map.of(...) call site for the common case:

 public record SummariseInput(String path, String question) {}

 agent.executeAction("summarise", new SummariseInput(
     "/data/sales.csv", "Top region?"
 ));
 

Java overload resolution routes Map<String, Object> call sites to executeAction(String, Map) (more specific), so existing code is unchanged. Records and other beans bind to this overload.

Parameters:

actionName - the action's method name

input - a Java record, POJO, Map, or null

Returns:

the action's return value, as produced by the underlying executor

Since:

0.8.0

See Also:

• ParamBeanMapper

executeAction

public final ActionResponse executeAction(ActionRequest request)

Executes an action using a typed request. @see AgentOrchestrator#executeActionTyped

executeAction

public final ActionResponse executeAction(ActionRequest request,
 ChatRetrievalContext retrievalContext)

Executes a typed action request with request-local retrieval context.

executeActionOnRole

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

Executes an action on a specific role (untyped). Prefer the typed overload. @see AgentOrchestrator#executeActionOnRole

executeActionOnRole

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

Executes a role action with request-local retrieval context.

executeActionOnRole

public final Object executeActionOnRole(String roleId,
 String actionName,
 Object input)

Executes an action on a specific role with a typed input bean. See executeAction(String, Object) for the bean shapes accepted.

Parameters:

roleId - the role identifier

actionName - the action's method name

input - a Java record, POJO, Map, or null

Returns:

the action's return value

Since:

0.8.0

executeActionOnRole

public final ActionResponse executeActionOnRole(String roleId,
 ActionRequest request)

Executes a typed action on a specific role. @see AgentOrchestrator#executeActionOnRoleTyped

executeActionOnRole

public final ActionResponse executeActionOnRole(String roleId,
 ActionRequest request,
 ChatRetrievalContext retrievalContext)

Executes a typed role action with request-local retrieval context.

getParent

public final Agent getParent()

Returns the parent agent, or null if root. @see AgentHierarchyManager#getParent()

setParent

public final void setParent(Agent parent)

Sets the parent agent (maintains bidirectional consistency). @see AgentHierarchyManager#setParent

getChildren

public final List<Agent> getChildren()

Returns the child agents (unmodifiable). @see AgentHierarchyManager#getChildren()

addChild

public final void addChild(Agent child)

Adds a child agent (maintains bidirectional consistency). @see AgentHierarchyManager#addChild

addChildren

public final void addChildren(Agent... children)

Adds multiple child agents at once. @see AgentHierarchyManager#addChildren

removeChild

public final void removeChild(Agent child)

Removes a child agent. @see AgentHierarchyManager#removeChild

delegateToChild

public final void delegateToChild(String childId,
 String actionName,
 Map<String,Object> parameters)

Delegates an action to a child agent. @see AgentHierarchyManager#delegateToChild

escalateToParent

public final void escalateToParent(String actionName,
 Map<String,Object> parameters)

Escalates an action to the parent agent. @see AgentHierarchyManager#escalateToParent

receiveMessage

public final void receiveMessage(AgentMessage message)

Specified by:

receiveMessage in interface AgentCommunicationManager.MessageReceiver

getToolsDescription

public final String getToolsDescription()

Returns a human-readable description of all available tools/actions. @see AgentOrchestrator#getToolsDescription()

getToolsForLLM

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

Returns tool catalog as JSON-Schema fragments for LLM binding (List<Map<String, Object>> per Anthropic-style tool-use). Type changed from List<ToolDefinition> in v0.6.0 (RFC #188).

See Also:

• AgentOrchestrator.getToolsForLLM()

joinGroup

public final void joinGroup(String groupId)

Joins a group by ID.

joinGroup

public final void joinGroup(AgentGroup group)

Joins an existing group.

leaveGroup

public final void leaveGroup(String groupId)

Leaves a group by ID.

leaveGroup

public final void leaveGroup(AgentGroup group)

Leaves a group.

getGroups

public final Set<AgentGroup> getGroups()

Returns all groups this agent is a member of.

isIdleMonitoringEnabled

public final boolean isIdleMonitoringEnabled()

Returns true if idle monitoring is active.

getIdleTime

public final long getIdleTime()

Returns milliseconds since last activity, or -1 if not monitored.

plan

public final List<PlannerHandle.PlanStep> plan()

Generates a plan for all unsatisfied goals. @see AgentCapabilities#plan()

planForGoal

public final List<PlannerHandle.PlanStep> planForGoal(String goalName)

Generates a plan for a specific goal. @see AgentCapabilities#planForGoal

executePlan

public final PlannerHandle.PlanResult executePlan(List<PlannerHandle.PlanStep> steps)

Executes a plan on the first role. Plan steps do not pass the access gate, so the bundled planner refuses a plan whose step declares an execution policy or @Security with SecurityException before any step runs; a custom PlannerHandle decides for itself.

See Also:

• AgentCapabilities.executePlan(java.util.List<com.tnsai.planning.PlannerHandle.PlanStep>)

extractCurrentState

public final Map<String,Object> extractCurrentState()

Extracts current @State from all roles. @see AgentCapabilities#extractCurrentState()

getPlannerHandle

public final Optional<PlannerHandle> getPlannerHandle()

Returns the planner handle if configured.

setPlannerHandle

public final void setPlannerHandle(PlannerHandle handle)

Sets the planner handle (null to disable).

isPlanningEnabled

public final boolean isPlanningEnabled()

Returns true if a PlannerHandle is configured.

setEnvironment

public final void setEnvironment(Environment environment)

Sets the environment (null to detach). @see AgentCapabilities#setEnvironment

getEnvironment

public final Optional<Environment> getEnvironment()

Returns the environment if configured.

isEnvironmentEnabled

public final boolean isEnvironmentEnabled()

Returns true if an environment is attached.

perceive

public final Percept perceive()

Perceives the current environment state. @see AgentCapabilities#perceive()

actOnEnvironment

public final ActionOutcome actOnEnvironment(String actionName,
 Map<String,Object> parameters)

Acts on the attached environment. @see AgentCapabilities#actOnEnvironment

enableContextGraph

public Agent enableContextGraph(SnapshotStore snapshotStore,
 DecisionTraceStore decisionTraceStore)

Enables context graph tracking (decision tracing + snapshots). @see AgentCapabilities#enableContextGraph

getContextManager

public Optional<ContextManagerHandle> getContextManager()

Returns the context manager if context graph is enabled. @see AgentCapabilities#getContextManager()

getReasoningStrategy

public final Optional<ReasoningStrategyHandle> getReasoningStrategy()

Returns the reasoning strategy if configured. @see AgentCapabilities#getReasoningStrategy()

setReasoningStrategy

public final void setReasoningStrategy(ReasoningStrategyHandle strategy)

Sets the reasoning strategy (null to disable). @see AgentCapabilities#setReasoningStrategy

getLastReasoningResult

public final Optional<ReasoningStrategyHandle.ReasoningResult> getLastReasoningResult()

Returns the last reasoning result, or empty. @see AgentCapabilities#getLastReasoningResult()