Class AgentMonitor

java.lang.Object
dev.langchain4j.agentic.observability.AgentMonitor
All Implemented Interfaces:
AgentListener

public class AgentMonitor extends Object implements 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 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 - if maxRetainedSessions is negative
    • clear

      public void clear()
      Removes all retained successful and failed executions. Ongoing executions are not affected.
    • setRootAgent

      public void setRootAgent(AgentInstance rootAgent)
    • beforeAgentInvocation

      public void beforeAgentInvocation(AgentRequest agentRequest)
      Specified by:
      beforeAgentInvocation in interface AgentListener
    • asyncAgentSubmitted

      public void asyncAgentSubmitted(AgentRequest agentRequest)
      Notified by the agentic system when an asynchronous agent is submitted to its executor, on the submitting thread, before the beforeAgentInvocation(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

      public void afterAgentInvocation(AgentResponse agentResponse)
      Specified by:
      afterAgentInvocation in interface AgentListener
    • onAgentInvocationError

      public void onAgentInvocationError(AgentInvocationError agentInvocationError)
      Specified by:
      onAgentInvocationError in interface AgentListener
    • asyncAgentCompleted

      public void asyncAgentCompleted(AgenticScope agenticScope, String agentId, boolean failed)
      Notified by the agentic system when an asynchronous agent submitted with asyncAgentSubmitted(AgentRequest) completes, after its error handler ran if it failed: the execution stays ongoing until then, since the failure of the agent is reported to onAgentInvocationError(AgentInvocationError) before the handler decides whether to recover it. failed tells whether a failure was not recovered, which records the execution as failed, whether the root call already ended or not.
    • onAgenticSystemSuspended

      public void onAgenticSystemSuspended(AgenticScope agenticScope)
      Specified by:
      onAgenticSystemSuspended in interface AgentListener
    • beforeAgenticScopeDestroyed

      public void beforeAgenticScopeDestroyed(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. An execution still running is left alone, its root call ends it.
      Specified by:
      beforeAgenticScopeDestroyed in interface AgentListener
    • onAgentSkipped

      public void onAgentSkipped(AgentSkipped agentSkipped)
      Description copied from interface: AgentListener
      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. A skipped agent is not followed by any other callback.
      Specified by:
      onAgentSkipped in interface AgentListener
    • afterAgentToolExecution

      public void afterAgentToolExecution(AfterAgentToolExecution afterAgentToolExecution)
      Specified by:
      afterAgentToolExecution in interface AgentListener
    • onPlannerModelResponse

      public void onPlannerModelResponse(PlannerModelResponse plannerModelResponse)
      Description copied from interface: AgentListener
      Called each time the planner of an agent, like a supervisor, a decision router or a custom Planner, receives the response of a model that it called itself to decide what to do, as reported by the planner through the reportChatModelResponse or reportDecisionModelResponse method of its PlanningContext. 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:
      onPlannerModelResponse in interface AgentListener
    • inheritedBySubagents

      public boolean inheritedBySubagents()
      Description copied from interface: AgentListener
      Indicates whether this listener should be used only to the agent where it is registered (default) or also inherited by its subagents.
      Specified by:
      inheritedBySubagents in interface AgentListener
      Returns:
      true if the listener should be inherited by sub-agents, false otherwise
    • ongoingExecutions

      public Map<Object, MonitoredExecution> ongoingExecutions()
    • ongoingExecutionFor

      public MonitoredExecution ongoingExecutionFor(AgenticScope agenticScope)
    • ongoingExecutionFor

      public MonitoredExecution ongoingExecutionFor(Object memoryId)
    • successfulExecutions

      public List<MonitoredExecution> successfulExecutions()
    • successfulExecutionsFor

      public List<MonitoredExecution> successfulExecutionsFor(AgenticScope agenticScope)
    • successfulExecutionsFor

      public List<MonitoredExecution> successfulExecutionsFor(Object memoryId)
    • failedExecutions

      public List<MonitoredExecution> failedExecutions()
    • failedExecutionsFor

      public List<MonitoredExecution> failedExecutionsFor(AgenticScope agenticScope)
    • failedExecutionsFor

      public List<MonitoredExecution> failedExecutionsFor(Object memoryId)
    • allMemoryIds

      public Set<Object> allMemoryIds()
      Returns the set of all memory IDs that have been tracked by this monitor, including successful, failed, and ongoing executions.
    • allExecutionsFor

      public List<MonitoredExecution> allExecutionsFor(AgenticScope agenticScope)
      Returns all executions (successful, failed, and ongoing) for a given memory ID.
    • allExecutionsFor

      public List<MonitoredExecution> allExecutionsFor(Object memoryId)
      Returns all executions (successful, failed, and ongoing) for a given memory ID.