Package com.tnsai.session

Class AgentSession

java.lang.Object
com.tnsai.session.AgentSession
public class AgentSession extends Object
Represents a complete agent session with all conversation turns.

An AgentSession captures the full history of an agent's interaction, including user messages, assistant responses, tool calls, and outcomes.

Usage


 AgentSession session = AgentSession.start("my-agent", "/path/to/project");
 session.addTurn(ConversationTurn.user("Fix the bug"));
 session.addTurn(ConversationTurn.assistant("I'll analyze the code..."));
 session.complete(SessionOutcome.SUCCESS);

Thread safety: turns are held in a CopyOnWriteArrayList, so addTurn(ConversationTurn) and the read methods (getTurns(), getTurnsByType(TurnType), getLastTurn(), getFirstUserMessage()) are safe to call concurrently. Metadata and tags follow the same concurrent-access intent but individual compound operations (e.g. add-tag-if-absent) are not atomic.

Author:
TnsAI Team

  • Method Details

    • start

      public static AgentSession start(String agentName, String projectPath)
      Starts a new session.
      Parameters:
      agentName - the agent name
      projectPath - the project path
      Returns:
      new session

    • start

      public static AgentSession start(String id, String agentName, String projectPath)
      Starts a new session with custom ID.
      Parameters:
      id - the session ID
      agentName - the agent name
      projectPath - the project path
      Returns:
      new session

    • restore

      public static AgentSession restore(String id, String agentName, Instant startTime, Instant endTime, String projectPath, List<ConversationTurn> turns, Map<String,Object> metadata, List<String> tags, SessionOutcome outcome)
      Restores a session from saved data. The persisted startTime is honored when non-null; otherwise the current time is used.

    • addTurn

      public AgentSession addTurn(ConversationTurn turn)
      Adds a turn to the session.
      Parameters:
      turn - the conversation turn
      Returns:
      this session for chaining

    • addUserMessage

      public AgentSession addUserMessage(String content)
      Adds a user message turn.
      Parameters:
      content - the message content
      Returns:
      this session

    • addAssistantMessage

      public AgentSession addAssistantMessage(String content)
      Adds an assistant message turn.
      Parameters:
      content - the message content
      Returns:
      this session

    • addToolCall

      public AgentSession addToolCall(String toolName, Map<String,Object> arguments)
      Adds a tool call turn.
      Parameters:
      toolName - the tool name
      arguments - the tool arguments
      Returns:
      this session

    • addToolResult

      public AgentSession addToolResult(String toolName, String result)
      Adds a tool result turn.
      Parameters:
      toolName - the tool name
      result - the tool result
      Returns:
      this session

    • addMetadata

      public AgentSession addMetadata(String key, Object value)
      Adds metadata to the session.
      Parameters:
      key - the metadata key
      value - the metadata value
      Returns:
      this session

    • addTag

      public AgentSession addTag(String tag)
      Adds a tag to the session.
      Parameters:
      tag - the tag
      Returns:
      this session

    • addTags

      public AgentSession addTags(String... newTags)
      Adds multiple tags.
      Parameters:
      newTags - the tags to add
      Returns:
      this session

    • complete

      public void complete(SessionOutcome outcome)
      Marks the session as complete.
      Parameters:
      outcome - the session outcome

    • success

      public void success()
      Marks the session as successful.

    • fail

      public void fail(String error)
      Marks the session as failed.
      Parameters:
      error - the error message

    • cancel

      public void cancel()
      Marks the session as cancelled.

    • getId

      public String getId()

    • getAgentName

      public String getAgentName()

    • getStartTime

      public Instant getStartTime()

    • getEndTime

      public Instant getEndTime()

    • getProjectPath

      public String getProjectPath()

    • getTurns

      public List<ConversationTurn> getTurns()

    • getMetadata

      public Map<String,Object> getMetadata()

    • getTags

      public List<String> getTags()

    • getOutcome

      public SessionOutcome getOutcome()

    • getDuration

      public Duration getDuration()
      Gets the session duration.
      Returns:
      duration or null if not ended

    • getTurnCount

      public int getTurnCount()
      Gets the number of turns.
      Returns:
      turn count

    • getTurnsByType

      public List<ConversationTurn> getTurnsByType(TurnType type)
      Gets turns of a specific type.
      Parameters:
      type - the turn type
      Returns:
      list of matching turns

    • getLastTurn

      public ConversationTurn getLastTurn()
      Gets the last turn.
      Returns:
      last turn or null

    • getFirstUserMessage

      public String getFirstUserMessage()
      Gets the first user message.
      Returns:
      first user message or null

    • isComplete

      public boolean isComplete()
      Checks if session is complete.
      Returns:
      true if ended

    • isSuccess

      public boolean isSuccess()
      Checks if session was successful.
      Returns:
      true if success

    • toString

      public String toString()
      Overrides:
      toString in class Object