Package com.tnsai.thread

Class AgentThread

java.lang.Object
com.tnsai.thread.AgentThread
public class AgentThread extends Object
Represents a single execution thread for an agent.

An AgentThread provides:

  • Session-scoped conversation state
  • Resource quota tracking and enforcement
  • Checkpoint/recovery capabilities
  • Parent-child thread hierarchies
  • Lifecycle management (pause, resume, cancel)

Usage Example


 // Create a thread
 AgentThread thread = AgentThread.create(ThreadSpec.defaults());

 // Execute with an agent
 String response = thread.execute(agent, "Hello!");

 // Check usage
 System.out.println("Tokens used: " + thread.getUsage().getTotalTokens());

 // Pause for later
 thread.pause();

 // Resume
 thread.resume();
 String response2 = thread.execute(agent, "Continue...");

 // Create child thread for sub-task
 AgentThread child = thread.createChild(ThreadSpec.shortLived());
 child.execute(subAgent, "Sub-task");
Since:
0.0.2

  • Method Details

    • create

      public static AgentThread create(ThreadSpec config)
      Create a new root thread with generated ID.

    • create

      public static AgentThread create(ThreadSpec config, com.tnsai.state.Checkpointer checkpointer)
      Create a new root thread with a checkpointer.

    • withId

      public static AgentThread withId(String threadId, ThreadSpec config, com.tnsai.state.Checkpointer checkpointer)
      Create a thread with a specific ID (for recovery).

    • execute

      public String execute(com.tnsai.agents.Agent agent, String message)
      Execute a chat message within this thread context.
      Parameters:
      agent - The agent to execute with
      message - The user message
      Returns:
      The agent's response
      Throws:
      ThreadException - if execution fails or quota exceeded

    • execute

      public <T> T execute(com.tnsai.agents.Agent agent, String message, Class<T> responseType)
      Execute with structured output. Executes the agent and attempts to parse the response as the specified type.
      Parameters:
      agent - the agent to execute
      message - the message to send
      responseType - the expected response type (must be String.class or a JSON-serializable class)
      Returns:
      the response parsed as the specified type
      Throws:
      ThreadException - if parsing fails

    • pause

      public void pause()
      Pause the thread. State is preserved for later resumption.

    • resume

      public void resume()
      Resume a paused thread.

    • cancel

      public void cancel()
      Cancel the thread.

    • complete

      public void complete()
      Mark as completed.

    • checkpoint

      public void checkpoint()
      Create a checkpoint of current state.

    • restore

      public void restore()
      Restore from latest checkpoint.

    • createChild

      public AgentThread createChild(ThreadSpec childSpec)
      Create a child thread.

    • getChildren

      public List<AgentThread> getChildren()
      Get all child threads.

    • getActiveChildren

      public List<AgentThread> getActiveChildren()
      Get active (non-terminal) children.

    • getState

      public Map<String,Object> getState()
      Get thread-local state.

    • getState

      public <T> T getState(String key)
      Get a state value.

    • getState

      public <T> T getState(String key, T defaultValue)
      Get a state value with default.

    • setState

      public void setState(String key, Object value)
      Set a state value.

    • removeState

      public void removeState(String key)
      Remove a state value.

    • addListener

      public void addListener(Consumer<ThreadEvent> listener)
      Add an event listener.

    • removeListener

      public void removeListener(Consumer<ThreadEvent> listener)
      Remove an event listener.

    • getThreadId

      public String getThreadId()

    • getSpec

      public ThreadSpec getSpec()

    • getUsage

      public ThreadUsage getUsage()

    • getThreadState

      public ThreadState getThreadState()

    • getCreatedAt

      public Instant getCreatedAt()

    • getParent

      public Optional<AgentThread> getParent()

    • getLastError

      public Optional<Throwable> getLastError()

    • getRetryCount

      public int getRetryCount()

    • isRoot

      public boolean isRoot()

    • toString

      public String toString()
      Overrides:
      toString in class Object