Package com.google.genkit.ai.agent

Class SessionRunner<S>

java.lang.Object
com.google.genkit.ai.agent.SessionRunner<S>
Type Parameters:
S - the type of the custom session state
public final class SessionRunner<S> extends Object
Drives ONE turn of an agent session: validates the input, appends the user message, runs the turn body, and persists a snapshot on success (SnapshotStatus.COMPLETED) or on failure (SnapshotStatus.FAILED). Failure snapshots are swallowed — runTurn(com.google.genkit.ai.agent.AgentInput, com.google.genkit.ai.agent.TurnBody<S>) never rethrows exceptions from the turn body.

Client-managed mode (store == null): no persistence; the runner tracks the last snapshot in-memory only and lastSnapshotId() always returns "".

  • Constructor Details

    • SessionRunner

      public SessionRunner(Session<S> session, SessionStore<S> store, SessionStoreOptions opts)
      Constructs a new SessionRunner.
      Parameters:
      session - the in-memory session to drive
      store - the session store, or null for client-managed mode (no server persistence)
      opts - options forwarded to store operations

    • SessionRunner

      public SessionRunner(Session<S> session, SessionStore<S> store, SessionStoreOptions opts, String seedSnapshotId)
      Constructs a new SessionRunner seeded with the id of the snapshot the session was resumed from.

      Seeding lastSnapshotId makes the first post-resume turn chain its parentId to the resumed snapshot (the parentId = lastSnapshotId logic in maybeSnapshot(com.google.genkit.ai.agent.SnapshotStatus, com.google.genkit.ai.agent.AgentFinishReason, com.google.genkit.ai.agent.RuntimeError, java.lang.String, java.lang.String) then threads correctly across invocations). Pass null for a fresh session.

      Parameters:
      session - the in-memory session to drive
      store - the session store, or null for client-managed mode (no server persistence)
      opts - options forwarded to store operations
      seedSnapshotId - the id of the snapshot this session was resumed from, or null

  • Method Details

    • sessionId

      public String sessionId()
      Returns the session ID.
      Returns:
      the session ID (never null)

    • getState

      public SessionState<S> getState()
      Returns a deep copy of the current session state.
      Returns:
      the current session state

    • getMessages

      public List<Message> getMessages()
      Returns a copy of the current messages list.
      Returns:
      the current messages

    • addMessages

      public void addMessages(Message... m)
      Appends messages to the session.
      Parameters:
      m - messages to add

    • getCustom

      public S getCustom()
      Returns a deep copy of the current custom state.
      Returns:
      the custom state

    • updateCustom

      public void updateCustom(UnaryOperator<S> fn)
      Applies fn to the current custom state and stores the result.
      Parameters:
      fn - the update function

    • getArtifacts

      public List<Artifact> getArtifacts()
      Returns a copy of the current artifacts list.
      Returns:
      the artifacts

    • addArtifacts

      public void addArtifacts(Artifact... a)
      Adds artifacts to the session.
      Parameters:
      a - artifacts to add

    • session

      public Session<S> session()
      Returns the underlying session.
      Returns:
      the session

    • turnIndex

      public int turnIndex()
      Returns the number of turns that have completed (including failed turns).
      Returns:
      the turn index (0 before any turn has run)

    • lastSnapshot

      public SessionSnapshot<S> lastSnapshot()
      Returns the last persisted (or in-memory) snapshot, or null if no turn has completed.
      Returns:
      the last snapshot

    • lastSnapshotId

      public String lastSnapshotId()
      Returns the ID of the last snapshot, or null if no turn has completed. Returns "" (empty string) in client-managed mode.
      Returns:
      the last snapshot ID

    • lastGoodState

      public SessionState<S> lastGoodState()
      Returns the session state as of the last successful turn, or null if no successful turn has completed.
      Returns:
      the last good state

    • lastTurnFinishReason

      public AgentFinishReason lastTurnFinishReason()
      Returns the finish reason of the last completed turn.
      Returns:
      the finish reason, or null if no turn has run

    • lastTurnError

      public RuntimeError lastTurnError()
      Returns the error from the last failed turn, or null if the last turn succeeded.
      Returns:
      the last turn error

    • runTurn

      public void runTurn(AgentInput input, TurnBody<S> turnBody)
      Runs ONE turn:
      1. Validates input.message: role must be null/USER; rejects tool-request and tool-response parts → throws GenkitException with INVALID_ARGUMENT (API misuse; not graceful).
      2. Reserves a turn snapshot ID (UUID if store != null, else "").
      3. Appends input.message to the session if non-null.
      4. Runs turnBody.run(input, turnCtx).
      5. On success: persists a COMPLETED snapshot; records lastGoodState; increments turn index.
      6. On exception: records lastTurnError; persists a FAILED snapshot (or ABORTED for InterruptedException); increments turn index; does NOT rethrow.
      Parameters:
      input - the agent input for this turn
      turnBody - the turn body to execute
      Throws:
      GenkitException - (INVALID_ARGUMENT) if the input message is invalid — this IS propagated (it is API misuse, not a graceful turn failure)