Package com.tnsai.agents.interrupt

Interface InterruptibleAgent

public interface InterruptibleAgent
Interface for agents that support graceful interruption and state preservation.

Implements the AgentScope-inspired interruptability pattern, allowing:

  • Graceful stopping of running agents
  • State checkpointing for later resume
  • Event-based interrupt handling
  • Pause/resume functionality

Usage


 // Setup interrupt handler
 agent.onInterrupt(event -> {
     if (event instanceof InterruptEvent.UserInterrupt) {
         agent.checkpoint();
         agent.respond("Paused. What would you like to change?");
     }
 });

 // Start async execution
 agent.chatAsync("Complex 10-step task...")
      .thenAccept(result -> System.out.println(result));

 // Later, interrupt if needed
 agent.interrupt("User changed direction");

 // Resume from checkpoint
 agent.restore(previousCheckpoint);
 agent.chat("New direction: focus on security");

  • Method Details

    • interrupt

      void interrupt()
      Interrupts the current execution gracefully.

      The agent will complete any critical operations (like tool calls) before stopping and optionally creating a checkpoint.

    • interrupt

      void interrupt(String reason)
      Interrupts with a specific reason.
      Parameters:
      reason - Human-readable reason for the interrupt

    • interrupt

      void interrupt(InterruptEvent event)
      Interrupts with a specific event.
      Parameters:
      event - The interrupt event

    • isInterrupted

      boolean isInterrupted()
      Checks if the agent is currently interrupted.

    • pause

      void pause()
      Pauses execution (can be resumed without checkpoint restore).

    • resume

      void resume()
      Resumes execution after a pause.

    • isPaused

      boolean isPaused()
      Checks if the agent is currently paused.

    • checkpoint

      AgentCheckpoint checkpoint()
      Creates a checkpoint of the current state.
      Returns:
      The checkpoint containing full agent state

    • checkpoint

      AgentCheckpoint checkpoint(InterruptEvent trigger)
      Creates a checkpoint with a specific trigger event.
      Parameters:
      trigger - The event that triggered the checkpoint
      Returns:
      The checkpoint

    • restore

      void restore(AgentCheckpoint checkpoint)
      Restores agent state from a checkpoint.
      Parameters:
      checkpoint - The checkpoint to restore

    • getLastCheckpoint

      Optional<AgentCheckpoint> getLastCheckpoint()
      Gets the most recent checkpoint, if any.

    • onInterrupt

      void onInterrupt(Consumer<InterruptEvent> handler)
      Registers a callback for interrupt events.
      Parameters:
      handler - The handler to invoke on interrupt

    • onPause

      void onPause(Runnable handler)
      Registers a callback for pause events.
      Parameters:
      handler - The handler to invoke on pause

    • onResume

      void onResume(Runnable handler)
      Registers a callback for resume events.
      Parameters:
      handler - The handler to invoke on resume

    • clearInterrupt

      void clearInterrupt()
      Clears the interrupted state.

    • getCurrentInterrupt

      Optional<InterruptEvent> getCurrentInterrupt()
      Gets the current interrupt event, if any.