Class AgentMonitor
java.lang.Object
dev.langchain4j.agentic.observability.AgentMonitor
- All Implemented Interfaces:
AgentListener
Monitors agent executions and provides observability for the LangChain4j Agentic system.
Generates a self-contained HTML report visualizing the static topology of an agentic system
and the dynamic execution traces.
The report includes:
- A visual tree chart of the agent hierarchy showing topology types, names, and properties
- A waterfall timeline of execution traces grouped by memory/session ID
An execution suspended by a human-in-the-loop step stays among the ongoing ones, with the invocations of the root agent and of the workflows containing that step in progress and marked as suspended: when the agentic system is resumed by invoking the root agent again, those agents continue their recorded invocations instead of starting new ones. A suspended execution is dropped when its scope is evicted, since nothing can resume it anymore. A monitor created after the suspension, for instance after a restart, has no record of the suspended execution and records the resumed invocation as a new execution.
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoidafterAgentInvocation(AgentResponse agentResponse) voidafterAgentToolExecution(AfterAgentToolExecution afterAgentToolExecution) allExecutionsFor(AgenticScope agenticScope) Returns all executions (successful, failed, and ongoing) for a given memory ID.allExecutionsFor(Object memoryId) Returns all executions (successful, failed, and ongoing) for a given memory ID.Returns the set of all memory IDs that have been tracked by this monitor, including successful, failed, and ongoing executions.voidasyncAgentCompleted(AgenticScope agenticScope, String agentId, boolean failed) Notified by the agentic system when an asynchronous agent submitted withasyncAgentSubmitted(AgentRequest)completes, after its error handler ran if it failed: the execution stays ongoing until then, since the failure of the agent is reported toonAgentInvocationError(AgentInvocationError)before the handler decides whether to recover it.voidasyncAgentSubmitted(AgentRequest agentRequest) Notified by the agentic system when an asynchronous agent is submitted to its executor, on the submitting thread, before thebeforeAgentInvocation(AgentRequest)of the agent is notified on the thread of the executor: the invocation is nested under its parent, still ongoing at that point, also when the executor starts the agent after the parent completed.voidbeforeAgenticScopeDestroyed(AgenticScope agenticScope) Drops the execution of the evicted scope if it is suspended: nothing can resume it anymore, so the next root call on that memory id, on a new scope, is a new execution.voidbeforeAgentInvocation(AgentRequest agentRequest) voidclear()Removes all retained successful and failed executions.failedExecutionsFor(AgenticScope agenticScope) failedExecutionsFor(Object memoryId) booleanIndicates whether this listener should be used only to the agent where it is registered (default) or also inherited by its subagents.voidonAgenticSystemSuspended(AgenticScope agenticScope) voidonAgentInvocationError(AgentInvocationError agentInvocationError) voidonAgentSkipped(AgentSkipped agentSkipped) Called when an agent is skipped instead of being invoked, because its activation condition is false or because it is optional and one of its arguments is missing.ongoingExecutionFor(AgenticScope agenticScope) ongoingExecutionFor(Object memoryId) voidonPlannerModelResponse(PlannerModelResponse plannerModelResponse) Called each time the planner of an agent, like a supervisor, a decision router or a customPlanner, receives the response of a model that it called itself to decide what to do, as reported by the planner through thereportChatModelResponseorreportDecisionModelResponsemethod of itsPlanningContext.voidsetMaxRetainedSessions(int maxRetainedSessions) Sets the maximum number of sessions (distinct memory IDs, per outcome: successful or failed) retained by this monitor.voidsetRootAgent(AgentInstance rootAgent) successfulExecutionsFor(AgenticScope agenticScope) successfulExecutionsFor(Object memoryId) Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface AgentListener
afterAgenticScopeCreated, beforeAgentToolExecution, onAgentAiServiceEvent
-
Constructor Details
-
AgentMonitor
public AgentMonitor()
-
-
Method Details
-
setMaxRetainedSessions
public void setMaxRetainedSessions(int maxRetainedSessions) Sets the maximum number of sessions (distinct memory IDs, per outcome: successful or failed) retained by this monitor. When the limit is exceeded, the oldest sessions are evicted automatically. If the new limit is lower than the current number of retained sessions, excess entries are evicted immediately.Defaults to 100.
- Parameters:
maxRetainedSessions- the maximum number of retained sessions per outcome, must be ≥ 0- Throws:
IllegalArgumentException- ifmaxRetainedSessionsis negative
-
clear
public void clear()Removes all retained successful and failed executions. Ongoing executions are not affected. -
setRootAgent
-
beforeAgentInvocation
- Specified by:
beforeAgentInvocationin interfaceAgentListener
-
asyncAgentSubmitted
Notified by the agentic system when an asynchronous agent is submitted to its executor, on the submitting thread, before thebeforeAgentInvocation(AgentRequest)of the agent is notified on the thread of the executor: the invocation is nested under its parent, still ongoing at that point, also when the executor starts the agent after the parent completed. -
afterAgentInvocation
- Specified by:
afterAgentInvocationin interfaceAgentListener
-
onAgentInvocationError
- Specified by:
onAgentInvocationErrorin interfaceAgentListener
-
asyncAgentCompleted
Notified by the agentic system when an asynchronous agent submitted withasyncAgentSubmitted(AgentRequest)completes, after its error handler ran if it failed: the execution stays ongoing until then, since the failure of the agent is reported toonAgentInvocationError(AgentInvocationError)before the handler decides whether to recover it.failedtells whether a failure was not recovered, which records the execution as failed, whether the root call already ended or not. -
onAgenticSystemSuspended
- Specified by:
onAgenticSystemSuspendedin interfaceAgentListener
-
beforeAgenticScopeDestroyed
Drops the execution of the evicted scope if it is suspended: nothing can resume it anymore, so the next root call on that memory id, on a new scope, is a new execution. An execution still running is left alone, its root call ends it.- Specified by:
beforeAgenticScopeDestroyedin interfaceAgentListener
-
onAgentSkipped
Description copied from interface:AgentListenerCalled when an agent is skipped instead of being invoked, because its activation condition is false or because it is optional and one of its arguments is missing. A skipped agent is not followed by any other callback.- Specified by:
onAgentSkippedin interfaceAgentListener
-
afterAgentToolExecution
- Specified by:
afterAgentToolExecutionin interfaceAgentListener
-
onPlannerModelResponse
Description copied from interface:AgentListenerCalled each time the planner of an agent, like a supervisor, a decision router or a customPlanner, receives the response of a model that it called itself to decide what to do, as reported by the planner through thereportChatModelResponseorreportDecisionModelResponsemethod of itsPlanningContext. The notification carries the token usage and the model name of that response. The model calls of the subagents are not notified here, but by their own invocations. It is called on the thread running the planner, before the planner acts on the response, so also when the invocation of the agent later fails.- Specified by:
onPlannerModelResponsein interfaceAgentListener
-
inheritedBySubagents
public boolean inheritedBySubagents()Description copied from interface:AgentListenerIndicates whether this listener should be used only to the agent where it is registered (default) or also inherited by its subagents.- Specified by:
inheritedBySubagentsin interfaceAgentListener- Returns:
- true if the listener should be inherited by sub-agents, false otherwise
-
ongoingExecutions
-
ongoingExecutionFor
-
ongoingExecutionFor
-
successfulExecutions
-
successfulExecutionsFor
-
successfulExecutionsFor
-
failedExecutions
-
failedExecutionsFor
-
failedExecutionsFor
-
allMemoryIds
-
allExecutionsFor
Returns all executions (successful, failed, and ongoing) for a given memory ID. -
allExecutionsFor
Returns all executions (successful, failed, and ongoing) for a given memory ID.
-