Package com.google.genkit.ai.agent

Class Session<S>

java.lang.Object
com.google.genkit.ai.agent.Session<S>
Type Parameters:
S - the type of the custom state object
All Implemented Interfaces:
ArtifactStore
public final class Session<S> extends Object implements ArtifactStore
Session is the per-invocation in-memory state holder managed by the agent runtime. It stores messages, custom state, and artifacts; provides mutation methods that increment a version counter and fire listener callbacks; and implements ArtifactStore for middleware/tools that do not need to know the custom state type.

Thread-safety: the runtime drives a session from one turn at a time. Mutations are synchronized to guard against concurrent reads in edge cases, but over-engineering with lock-free structures is intentionally avoided.

  • Constructor Details

    • Session

      public Session(SessionState<S> initialState)
      Constructs a new Session from the given initial state. Deep-copies initialState so that subsequent external mutations to the original object cannot affect this session. If initialState.sessionId is null or empty, a new UUID is minted.
      Parameters:
      initialState - the initial session state (must not be null)

  • Method Details

    • sessionId

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

    • getVersion

      public long getVersion()
      Returns the current mutation version counter. Increments on every mutating operation.
      Returns:
      the version

    • getState

      public SessionState<S> getState()
      Returns a deep copy of the current session state. Callers must not mutate the returned object to avoid leaking changes back into the session.
      Returns:
      a deep copy of the current SessionState

    • getMessages

      public List<Message> getMessages()
      Returns a copy of the current messages list. Mutating the returned list does not affect the session.
      Returns:
      a copy of the messages (never null)

    • addMessages

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

    • addMessages

      public void addMessages(List<Message> msgs)
      Appends the given messages to the session.
      Parameters:
      msgs - messages to add (must not be null)

    • setMessages

      public void setMessages(List<Message> msgs)
      Replaces the session's message list with a copy of the given list.
      Parameters:
      msgs - the new messages (must not be null)

    • updateMessages

      public void updateMessages(UnaryOperator<List<Message>> fn)
      Applies fn to the current messages list and stores the result.
      Parameters:
      fn - the update function

    • getCustom

      public S getCustom()
      Returns a deep copy of the current custom state. Mutating the returned value does not affect the session — prefer updateCustom(java.util.function.UnaryOperator<S>) for modifications.
      Returns:
      a deep copy of the current custom state, or null if not set

    • updateCustom

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

    • getArtifacts

      public List<Artifact> getArtifacts()
      Returns a copy of the current artifacts list. Mutating the returned list does not affect the session.
      Specified by:
      getArtifacts in interface ArtifactStore
      Returns:
      a copy of the artifacts (never null)

    • addArtifacts

      public void addArtifacts(Artifact... arts)
      Adds artifacts with deduplication by name. If an artifact with the same non-null name already exists, it is replaced in place. Artifacts with null names are always appended. Fires the onArtifactChanged listener for each artifact added or updated.
      Specified by:
      addArtifacts in interface ArtifactStore
      Parameters:
      arts - artifacts to add

    • addArtifacts

      public void addArtifacts(List<Artifact> arts)
      Adds artifacts with deduplication by name (list overload).
      Parameters:
      arts - artifacts to add (must not be null)

    • updateArtifacts

      public void updateArtifacts(UnaryOperator<List<Artifact>> fn)
      Applies fn to the current artifacts list and stores the result.
      Parameters:
      fn - the update function

    • setOnCustomChanged

      public void setOnCustomChanged(Runnable cb)
      Sets the callback to be invoked after updateCustom(java.util.function.UnaryOperator<S>) completes.
      Parameters:
      cb - the callback (may be null to clear)

    • setOnArtifactChanged

      public void setOnArtifactChanged(Consumer<Artifact> cb)
      Sets the callback to be invoked for each artifact added or updated via addArtifacts(com.google.genkit.ai.agent.Artifact...).
      Parameters:
      cb - the callback (may be null to clear)