Package com.google.genkit.ai.agent

Class AgentChat<S>

java.lang.Object
com.google.genkit.ai.agent.AgentChat<S>
Type Parameters:
S - the type of custom session state
public final class AgentChat<S> extends Object
AgentChat is the ergonomic programmatic client for driving an agent across multiple turns while carrying session state automatically.

Each send(java.lang.String) is exactly one invocation of the agent's bidi action (one-turn-per-send). The chat tracks the evolving snapshotId / sessionId / custom state / messages / artifacts so the next send resumes correctly. Resume is carried in the per-turn AgentInit:

  • Server-managed agents persist state server-side; the init carries the latest snapshotId (and sessionId once known) so the server resumes from there.
  • Client-managed agents do not persist; the init carries the full SessionState (sessionId, messages, custom, artifacts) so the agent rehydrates from it each turn.

Instances are created via Agent.chat(com.google.genkit.core.ActionContext) / Agent.chat(com.google.genkit.core.ActionContext, AgentInit) / Agent.loadChat(com.google.genkit.core.ActionContext, GetSnapshotRequest).

Not thread-safe: a chat is a single conversation and is expected to be driven from one thread.

  • Method Details

    • over

      public static <S> AgentChat<S> over(AgentTransport<S> transport, AgentInit<S> init)
      Creates a chat over any transport. External code (e.g. RemoteAgent) uses this factory so they do not need to be in the same package.
      Type Parameters:
      S - the type of custom session state
      Parameters:
      transport - the transport that runs each turn (must not be null)
      init - optional seed init; may be null for a fresh chat
      Returns:
      a new AgentChat backed by transport

    • send

      public AgentResponse<S> send(String text)
      Sends a user text message and returns the turn's response.
      Parameters:
      text - the user message text
      Returns:
      the response

    • send

      public AgentResponse<S> send(AgentInput input)
      Sends a fully-formed input and returns the turn's response.
      Parameters:
      input - the turn input
      Returns:
      the response

    • sendStream

      public AgentResponse<S> sendStream(String text, Consumer<AgentChunk<S>> onChunk)
      Sends a user text message, streaming chunks to onChunk, and returns the final response.
      Parameters:
      text - the user message text
      onChunk - per-chunk callback (may be a no-op)
      Returns:
      the response

    • sendStream

      public AgentResponse<S> sendStream(AgentInput input, Consumer<AgentChunk<S>> onChunk)
      Sends a fully-formed input, streaming chunks to onChunk, and returns the final response.
      Parameters:
      input - the turn input
      onChunk - per-chunk callback (may be a no-op)
      Returns:
      the response

    • resume

      public AgentResponse<S> resume(List<Part> respond)
      Resumes a paused turn by responding to its interrupts.
      Parameters:
      respond - the response parts
      Returns:
      the response

    • restart

      public AgentResponse<S> restart(List<Part> restart)
      Resumes a paused turn by restarting its interrupted tool requests.

      Each restart part is a tool-request part (typically produced by Tool.restart(...)) carrying the resumed metadata; the tool is re-executed with that metadata so a restart-aware handler can observe its resumed status via ActionContext.isResumed()/ getResumed(). Sibling to resume(List).

      Parameters:
      restart - the restart tool-request parts
      Returns:
      the response

    • abort

      public SnapshotStatus abort()
      Aborts the latest pending snapshot for this chat.
      Returns:
      the resulting status, or null if there is no snapshot / abort is unsupported

    • snapshotId

      public String snapshotId()
      Returns the latest snapshot ID (server-managed agents).
      Returns:
      the snapshot ID, or null before the first turn / for client-managed agents

    • sessionId

      public String sessionId()
      Returns the session ID.
      Returns:
      the session ID, or null before it is known

    • state

      public S state()
      Returns the current custom session state.
      Returns:
      the custom state, or null

    • messages

      public List<Message> messages()
      Returns the accumulated conversation messages.
      Returns:
      an unmodifiable view of the messages

    • artifacts

      public List<Artifact> artifacts()
      Returns the accumulated artifacts.
      Returns:
      an unmodifiable view of the artifacts