Package com.tnsai.agents.lifecycle

Class IdleMonitor

java.lang.Object
com.tnsai.agents.lifecycle.IdleMonitor
public final class IdleMonitor extends Object
Monitors agent idle time and triggers callbacks when timeout is reached.

IdleMonitor implements the idleTimeoutMs parameter from AgentSpec, allowing agents to be notified (and optionally suspended) when they've been idle for too long.

Key Features

  • Per-agent idle timer management
  • Timer reset on agent activity
  • Configurable timeout callbacks
  • Thread-safe operation

Usage Example


 IdleMonitor monitor = IdleMonitor.getInstance();

 // Start monitoring with callback
 monitor.startMonitoring(agent, 30000, () -> {
     agent.suspend();  // or any other idle action
 });

 // Reset timer on activity
 monitor.resetTimer(agent);

 // Stop monitoring when done
 monitor.stopMonitoring(agent);

Integration with Agent Lifecycle

The Agent class automatically integrates with IdleMonitor:

  • Monitoring starts during agent initialization if idleTimeoutMs > 0
  • Timer is reset on each chat(), executeAction(), or message receipt
  • Monitoring stops when agent is stopped
Author:
TnsAI Team
See Also:

  • Method Details

    • getInstance

      public static IdleMonitor getInstance()
      Returns the singleton instance.
      Returns:
      the IdleMonitor instance

    • startMonitoring

      public void startMonitoring(Agent agent, int timeoutMs, Runnable onIdle)
      Starts monitoring an agent for idle timeout.

      If the agent is already being monitored, the existing timer is cancelled and a new one is started with the new settings.

      Parameters:
      agent - the agent to monitor
      timeoutMs - the idle timeout in milliseconds
      onIdle - callback to execute when idle timeout is reached
      Throws:
      IllegalArgumentException - if agent is null or timeoutMs invalid input: '<'= 0

    • resetTimer

      public void resetTimer(Agent agent)
      Resets the idle timer for an agent.

      This should be called whenever the agent performs any activity (chat, action execution, message handling, etc.).

      Parameters:
      agent - the agent

    • stopMonitoring

      public void stopMonitoring(Agent agent)
      Stops monitoring an agent.
      Parameters:
      agent - the agent

    • isMonitoring

      public boolean isMonitoring(Agent agent)
      Checks if an agent is being monitored.
      Parameters:
      agent - the agent
      Returns:
      true if monitoring is active

    • getIdleTime

      public long getIdleTime(Agent agent)
      Gets the time since last activity for an agent.
      Parameters:
      agent - the agent
      Returns:
      milliseconds since last activity, or -1 if not monitored

    • getTimeout

      public int getTimeout(Agent agent)
      Gets the configured timeout for an agent.
      Parameters:
      agent - the agent
      Returns:
      timeout in milliseconds, or -1 if not monitored

    • shutdown

      public void shutdown()
      Shuts down the scheduler.

      Called during application shutdown. All monitoring stops.

    • getMonitoredCount

      public int getMonitoredCount()
      Gets the number of agents being monitored.
      Returns:
      count of monitored agents

    • clear

      public void clear()
      Clears all monitoring (for testing).