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

  • 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

    • afterAgentInvocation

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

    • onAgentInvocationError

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

    • afterAgentToolExecution

      public void afterAgentToolExecution(AfterAgentToolExecution afterAgentToolExecution)
      Specified by:
      afterAgentToolExecution 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.