Package com.google.genkit.ai.agent

Class Agent<S>

java.lang.Object

com.google.genkit.ai.agent.Agent<S>

Type Parameters:

S - the type of custom session state

All Implemented Interfaces:

AgentApi<S>, Action<AgentInput,AgentOutput<S>,AgentStreamChunk>, BidiAction<AgentInput,AgentOutput<S>,AgentStreamChunk,AgentInit<S>>, Registerable

public final class Agent<S>
extends Object
implements BidiAction<AgentInput,AgentOutput<S>,AgentStreamChunk,AgentInit<S>>, AgentApi<S>

Agent is a bidirectional streaming agent action that manages session state and provides typed facades for snapshot retrieval and abort.

Instances are created via AgentActions.defineCustomAgent. Do not instantiate directly.

Nested Class Summary

Nested classes/interfaces inherited from interface com.google.genkit.core.BidiAction

BidiAction.BidiHandler<I,O,S,Init>

Constructor Summary

Constructors

Constructor	Description
Agent(BidiActionImpl<AgentInput,AgentOutput<S>,AgentStreamChunk,AgentInit<S>> impl, SessionStore<S> store, boolean serverManaged, Action<?,?,?> snapshotAction, Action<?,?,?> abortAction, ClientTransform<S> clientTransform, SessionStoreOptions opts, String name, String description, Registry registry)	Constructs an Agent.

Method Summary

Modifier and Type	Method	Description
SnapshotStatus	abort(String snapshotId)	Attempts to abort a snapshot that is currently in SnapshotStatus.PENDING state.
Action<?,?,?>	abortAgentAction()	Returns the companion abort action, or null if not applicable.
AgentChat<S>	chat()	Creates a fresh AgentChat for a new conversation, using a default action context built from the registry the agent was defined in.
AgentChat<S>	chat(AgentInit<S> init)	Creates an AgentChat seeded from init (snapshotId / sessionId / inline state), using a default action context built from the registry the agent was defined in.
AgentChat<S>	chat(ActionContext ctx)	Creates a fresh AgentChat for a new conversation.
AgentChat<S>	chat(ActionContext ctx, AgentInit<S> init)	Creates an AgentChat seeded from init (snapshotId / sessionId / inline state).
ActionDesc	getDesc()	Returns the descriptor of the action containing metadata, schemas, etc.
Map<String,Object>	getInputSchema()	Returns the JSON schema for the action's input type.
Map<String,Object>	getMetadata()	Returns additional metadata for the action.
String	getName()	Returns the name of the action.
Map<String,Object>	getOutputSchema()	Returns the JSON schema for the action's output type.
SessionSnapshot<S>	getSnapshotData(GetSnapshotRequest req)	Retrieves a session snapshot by snapshot ID or session ID.
Action<?,?,?>	getSnapshotDataAction()	Returns the companion snapshot action, or null if not applicable.
ActionType	getType()	Returns the type of the action.
AgentChat<S>	loadChat(GetSnapshotRequest lookup)	Loads a snapshot and hydrates an AgentChat whose next send resumes it, using a default action context built from the registry the agent was defined in.
AgentChat<S>	loadChat(ActionContext ctx, GetSnapshotRequest lookup)	Loads a snapshot and hydrates an AgentChat whose next send resumes it.
AgentRef	ref()	Returns a lightweight reference to this agent.
void	register(Registry registry)	Registers this primitive with the given registry.
AgentOutput<S>	run(ActionContext ctx, AgentInput input)	Runs the action with the given input.
AgentOutput<S>	run(ActionContext ctx, AgentInput input, Consumer<AgentStreamChunk> cb)	Runs the action with the given input and streaming callback.
AgentOutput<S>	runBidi(ActionContext ctx, AgentInit<S> init, InputSource<AgentInput> inputs, Consumer<AgentStreamChunk> streamCallback)	Runs the action in bidirectional-streaming mode.
com.fasterxml.jackson.databind.JsonNode	runBidiJson(ActionContext ctx, com.fasterxml.jackson.databind.JsonNode init, InputSource<com.fasterxml.jackson.databind.JsonNode> inputs, Consumer<com.fasterxml.jackson.databind.JsonNode> streamCallback)	Runs the action in bidirectional-streaming mode with JSON-typed arguments.
ActionRunResult<com.fasterxml.jackson.databind.JsonNode>	runBidiJsonWithTelemetry(ActionContext ctx, com.fasterxml.jackson.databind.JsonNode init, InputSource<com.fasterxml.jackson.databind.JsonNode> inputs, Consumer<com.fasterxml.jackson.databind.JsonNode> streamCallback)	Runs the action in bidirectional-streaming mode with JSON-typed arguments and telemetry.
com.fasterxml.jackson.databind.JsonNode	runJson(ActionContext ctx, com.fasterxml.jackson.databind.JsonNode input, Consumer<com.fasterxml.jackson.databind.JsonNode> streamCallback)	Runs the action with JSON input and returns JSON output.
ActionRunResult<com.fasterxml.jackson.databind.JsonNode>	runJsonWithTelemetry(ActionContext ctx, com.fasterxml.jackson.databind.JsonNode input, Consumer<com.fasterxml.jackson.databind.JsonNode> streamCallback)	Runs the action with JSON input and returns the result with telemetry information.
boolean	serverManaged()	Returns whether this agent uses server-managed session state.
SessionStore<S>	store()	Returns the session store, or null for client-managed agents.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Agent

public Agent(BidiActionImpl<AgentInput,AgentOutput<S>,AgentStreamChunk,AgentInit<S>> impl,
 SessionStore<S> store,
 boolean serverManaged,
 Action<?,?,?> snapshotAction,
 Action<?,?,?> abortAction,
 ClientTransform<S> clientTransform,
 SessionStoreOptions opts,
 String name,
 String description,
 Registry registry)

Constructs an Agent. Called exclusively by AgentActions.

Parameters:

impl - the underlying BidiActionImpl

store - the session store, or null for client-managed mode

serverManaged - whether the agent is server-managed

snapshotAction - companion snapshot action; nullable

abortAction - companion abort action; nullable

clientTransform - state transform for client-managed mode; nullable

opts - store options; nullable

name - the agent name

description - the agent description; nullable

registry - the registry the agent is defined in; used to build a default ActionContext for the no-arg chat() convenience overloads

Method Details

getName

public String getName()

Description copied from interface: Action

Returns the name of the action.

Specified by:

getName in interface Action<AgentInput,AgentOutput<S>,AgentStreamChunk>

Returns:

the action name

getType

public ActionType getType()

Description copied from interface: Action

Returns the type of the action.

Specified by:

getType in interface Action<AgentInput,AgentOutput<S>,AgentStreamChunk>

Returns:

the action type

getDesc

public ActionDesc getDesc()

Description copied from interface: Action

Returns the descriptor of the action containing metadata, schemas, etc.

Specified by:

getDesc in interface Action<AgentInput,AgentOutput<S>,AgentStreamChunk>

Returns:

the action descriptor

getInputSchema

public Map<String,Object> getInputSchema()

Description copied from interface: Action

Returns the JSON schema for the action's input type.

Specified by:

getInputSchema in interface Action<AgentInput,AgentOutput<S>,AgentStreamChunk>

Returns:

the input schema as a map, or null if not defined

getOutputSchema

public Map<String,Object> getOutputSchema()

Description copied from interface: Action

Returns the JSON schema for the action's output type.

Specified by:

getOutputSchema in interface Action<AgentInput,AgentOutput<S>,AgentStreamChunk>

Returns:

the output schema as a map, or null if not defined

getMetadata

public Map<String,Object> getMetadata()

Description copied from interface: Action

Returns additional metadata for the action.

Specified by:

getMetadata in interface Action<AgentInput,AgentOutput<S>,AgentStreamChunk>

Returns:

the metadata map

run

public AgentOutput<S> run(ActionContext ctx,
 AgentInput input)
                   throws GenkitException

Description copied from interface: Action

Runs the action with the given input.

Specified by:

run in interface Action<AgentInput,AgentOutput<S>,AgentStreamChunk>

Parameters:

ctx - the action context

input - the input to the action

Returns:

the output of the action

Throws:

GenkitException - if the action fails

run

public AgentOutput<S> run(ActionContext ctx,
 AgentInput input,
 Consumer<AgentStreamChunk> cb)
                   throws GenkitException

Description copied from interface: Action

Runs the action with the given input and streaming callback.

Specified by:

run in interface Action<AgentInput,AgentOutput<S>,AgentStreamChunk>

Parameters:

ctx - the action context

input - the input to the action

cb - callback for receiving streaming chunks, may be null

Returns:

the output of the action

Throws:

GenkitException - if the action fails

runJson

public com.fasterxml.jackson.databind.JsonNode runJson(ActionContext ctx,
 com.fasterxml.jackson.databind.JsonNode input,
 Consumer<com.fasterxml.jackson.databind.JsonNode> streamCallback)
                                                throws GenkitException

Description copied from interface: Action

Runs the action with JSON input and returns JSON output.

Specified by:

runJson in interface Action<AgentInput,AgentOutput<S>,AgentStreamChunk>

Parameters:

ctx - the action context

input - the JSON input

streamCallback - callback for receiving streaming JSON chunks, may be null

Returns:

the JSON output

Throws:

GenkitException - if the action fails

runJsonWithTelemetry

public ActionRunResult<com.fasterxml.jackson.databind.JsonNode> runJsonWithTelemetry(ActionContext ctx,
 com.fasterxml.jackson.databind.JsonNode input,
 Consumer<com.fasterxml.jackson.databind.JsonNode> streamCallback)
                                                                              throws GenkitException

Description copied from interface: Action

Runs the action with JSON input and returns the result with telemetry information.

Specified by:

runJsonWithTelemetry in interface Action<AgentInput,AgentOutput<S>,AgentStreamChunk>

Parameters:

ctx - the action context

input - the JSON input

streamCallback - callback for receiving streaming JSON chunks, may be null

Returns:

the action result including telemetry data

Throws:

GenkitException - if the action fails

runBidi

public AgentOutput<S> runBidi(ActionContext ctx,
 AgentInit<S> init,
 InputSource<AgentInput> inputs,
 Consumer<AgentStreamChunk> streamCallback)
                       throws GenkitException

Description copied from interface: BidiAction

Runs the action in bidirectional-streaming mode.

Specified by:

runBidi in interface BidiAction<AgentInput,AgentOutput<S>,AgentStreamChunk,AgentInit<S>>

Parameters:

ctx - the action context

init - the one-time session-init value; may be null

inputs - the stream of per-turn inputs

streamCallback - callback invoked for each emitted chunk; may be null

Returns:

the final output

Throws:

GenkitException - if execution fails

runBidiJson

public com.fasterxml.jackson.databind.JsonNode runBidiJson(ActionContext ctx,
 com.fasterxml.jackson.databind.JsonNode init,
 InputSource<com.fasterxml.jackson.databind.JsonNode> inputs,
 Consumer<com.fasterxml.jackson.databind.JsonNode> streamCallback)
                                                    throws GenkitException

Description copied from interface: BidiAction

Runs the action in bidirectional-streaming mode with JSON-typed arguments.

Deserializes init and each element from inputs before handing them to the typed handler, and serializes all chunks and the final result back to JsonNode.

Specified by:

runBidiJson in interface BidiAction<AgentInput,AgentOutput<S>,AgentStreamChunk,AgentInit<S>>

Parameters:

ctx - the action context

init - the one-time session-init as a JsonNode; may be null

inputs - the stream of per-turn inputs as JsonNode values

streamCallback - callback invoked for each emitted chunk serialized to JsonNode; may be null

Returns:

the final output serialized to JsonNode

Throws:

GenkitException - if execution fails

runBidiJsonWithTelemetry

public ActionRunResult<com.fasterxml.jackson.databind.JsonNode> runBidiJsonWithTelemetry(ActionContext ctx,
 com.fasterxml.jackson.databind.JsonNode init,
 InputSource<com.fasterxml.jackson.databind.JsonNode> inputs,
 Consumer<com.fasterxml.jackson.databind.JsonNode> streamCallback)
                                                                                  throws GenkitException

Description copied from interface: BidiAction

Runs the action in bidirectional-streaming mode with JSON-typed arguments and telemetry.

Behaves like BidiAction.runBidiJson(com.google.genkit.core.ActionContext, com.fasterxml.jackson.databind.JsonNode, com.google.genkit.core.InputSource<com.fasterxml.jackson.databind.JsonNode>, java.util.function.Consumer<com.fasterxml.jackson.databind.JsonNode>) (deserializing init and each element from inputs, serializing all chunks and the final result back to JsonNode) but additionally creates a new tracing span and captures the resulting trace/span IDs, returning them in an ActionRunResult. Unlike the unary Action.runJsonWithTelemetry(com.google.genkit.core.ActionContext, com.fasterxml.jackson.databind.JsonNode, java.util.function.Consumer<com.fasterxml.jackson.databind.JsonNode>), this threads the real init and the full stream of inputs through to the handler.

Specified by:

runBidiJsonWithTelemetry in interface BidiAction<AgentInput,AgentOutput<S>,AgentStreamChunk,AgentInit<S>>

Parameters:

ctx - the action context

init - the one-time session-init as a JsonNode; may be null

inputs - the stream of per-turn inputs as JsonNode values

streamCallback - callback invoked for each emitted chunk serialized to JsonNode; may be null

Returns:

the final output serialized to JsonNode together with the captured trace/span IDs

Throws:

GenkitException - if execution fails

register

public void register(Registry registry)

Description copied from interface: Registerable

Registers this primitive with the given registry.

Specified by:

register in interface Registerable

Parameters:

registry - the registry to register with

getSnapshotData

public SessionSnapshot<S> getSnapshotData(GetSnapshotRequest req)

Description copied from interface: AgentApi

Retrieves a session snapshot by snapshot ID or session ID.

Specified by:

getSnapshotData in interface AgentApi<S>

Parameters:

req - the request specifying which snapshot to retrieve

Returns:

the matching session snapshot, or null if not found

abort

public SnapshotStatus abort(String snapshotId)

Description copied from interface: AgentApi

Attempts to abort a snapshot that is currently in SnapshotStatus.PENDING state.

If the snapshot is already in a terminal state, returns that state unchanged. If the snapshot does not exist, returns null.

Specified by:

abort in interface AgentApi<S>

Parameters:

snapshotId - the ID of the snapshot to abort

Returns:

the resulting SnapshotStatus, or null if the snapshot was not found

ref

public AgentRef ref()

Description copied from interface: AgentApi

Returns a lightweight reference to this agent.

Specified by:

ref in interface AgentApi<S>

Returns:

an AgentRef carrying the agent's name and description

chat

public AgentChat<S> chat()

Description copied from interface: AgentApi

Creates a fresh AgentChat for a new conversation, using a default action context built from the registry the agent was defined in.

This is the convenience overload for the common case. Use AgentApi.chat(ActionContext) when you need to supply request-scoped context (e.g. auth / user info that tools should observe).

Specified by:

chat in interface AgentApi<S>

Returns:

a new chat

chat

public AgentChat<S> chat(AgentInit<S> init)

Description copied from interface: AgentApi

Creates an AgentChat seeded from init (snapshotId / sessionId / inline state), using a default action context built from the registry the agent was defined in.

Specified by:

chat in interface AgentApi<S>

Parameters:

init - the seed init (may be null for a fresh chat)

Returns:

a new chat

loadChat

public AgentChat<S> loadChat(GetSnapshotRequest lookup)

Description copied from interface: AgentApi

Loads a snapshot and hydrates an AgentChat whose next send resumes it, using a default action context built from the registry the agent was defined in.

Specified by:

loadChat in interface AgentApi<S>

Parameters:

lookup - which snapshot to load (by snapshotId or sessionId)

Returns:

a hydrated chat

chat

public AgentChat<S> chat(ActionContext ctx)

Description copied from interface: AgentApi

Creates a fresh AgentChat for a new conversation.

Specified by:

chat in interface AgentApi<S>

Parameters:

ctx - the action context used to run each turn

Returns:

a new chat

chat

public AgentChat<S> chat(ActionContext ctx,
 AgentInit<S> init)

Description copied from interface: AgentApi

Creates an AgentChat seeded from init (snapshotId / sessionId / inline state).

Specified by:

chat in interface AgentApi<S>

Parameters:

ctx - the action context used to run each turn

init - the seed init (may be null for a fresh chat)

Returns:

a new chat

loadChat

public AgentChat<S> loadChat(ActionContext ctx,
 GetSnapshotRequest lookup)

Description copied from interface: AgentApi

Loads a snapshot and hydrates an AgentChat whose next send resumes it.

Specified by:

loadChat in interface AgentApi<S>

Parameters:

ctx - the action context used to run each turn

lookup - which snapshot to load (by snapshotId or sessionId)

Returns:

a hydrated chat

serverManaged

public boolean serverManaged()

Returns whether this agent uses server-managed session state.

Returns:

true if server-managed, false if client-managed

store

public SessionStore<S> store()

Returns the session store, or null for client-managed agents.

Returns:

the session store, or null

getSnapshotDataAction

public Action<?,?,?> getSnapshotDataAction()

Returns the companion snapshot action, or null if not applicable.

Returns:

the snapshot action, or null

abortAgentAction

public Action<?,?,?> abortAgentAction()

Returns the companion abort action, or null if not applicable.

Returns:

the abort action, or null