AgentRunner

Kotlin |Java

public final class AgentRunner implements AutoCloseable

---

Manages agent execution sessions.

An AgentRunner orchestrates tool execution loops and manages conversation history across turns. When instantiated via this primary constructor without an explicit GenerativeModel, the runner defaults to the on-device model client provided by Generation.getClient.

Summary

Public constructors
AgentRunner(     @NonNull Agent agent,     Float temperature,     Integer topK,     Integer maxOutputTokens,     @NonNull CoroutineDispatcher coroutineDispatcher )
AgentRunner(     @NonNull Agent agent,     @NonNull GenerativeModel generativeModel,     Float temperature,     Integer topK,     Integer maxOutputTokens,     @NonNull CoroutineDispatcher coroutineDispatcher ) Creates an AgentRunner backed by the provided ML Kit generativeModel.
AgentRunner(     @NonNull Context context,     @NonNull Agent agent,     Float temperature,     Integer topK,     Integer maxOutputTokens,     @NonNull CoroutineDispatcher coroutineDispatcher ) Creates an AgentRunner with an Android context used for AppFunctions and SDK services.
AgentRunner(     @NonNull Context context,     @NonNull Agent agent,     @NonNull GenerativeModel generativeModel,     Float temperature,     Integer topK,     Integer maxOutputTokens,     @NonNull CoroutineDispatcher coroutineDispatcher ) Creates an AgentRunner backed by the provided ML Kit generativeModel and Android context.

Public methods
final void	clearAllSessions() Clears all in-memory conversation histories across all sessions managed by this runner.
void	close() Closes the runner and releases all underlying in-memory resources.
final void	deleteSession(@NonNull String sessionId) Explicitly clears the in-memory conversation history for a specific session.
final @NonNull Agent	getAgent() The agent configuration including tools, instructions, and turn limits.
final @NonNull CoroutineDispatcher	getCoroutineDispatcher() Dispatcher on which agent orchestration and tool calls execute.
final Integer	getMaxOutputTokens() Optional maximum tokens to generate.
final @NonNull AgentSession	getOrCreateSession(@NonNull String sessionId) Retrieves or creates a stateful conversation session identified by sessionId.
final Float	getTemperature() Optional temperature sampling parameter for generation.
final Integer	getTopK() Optional top-K sampling parameter for generation.
final @NonNull Flow<@NonNull AgentEvent>	runSingleTurnAsync(@NonNull Content content) Runs the agent in single-turn mode with the given multimodal content.

Public constructors

AgentRunner

public AgentRunner(
    @NonNull Agent agent,
    Float temperature,
    Integer topK,
    Integer maxOutputTokens,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Parameters
@NonNull Agent agent	The agent configuration including tools, instructions, and turn limits.
Float temperature	Optional temperature sampling parameter for generation. Defaults to null, which uses the underlying model's default (typically 0.0 for deterministic greedy decoding).
Integer topK	Optional top-K sampling parameter for generation.
Integer maxOutputTokens	Optional maximum tokens to generate.
@NonNull CoroutineDispatcher coroutineDispatcher	Dispatcher on which agent orchestration and tool calls execute. Defaults to Dispatchers.IO.

AgentRunner

public AgentRunner(
    @NonNull Agent agent,
    @NonNull GenerativeModel generativeModel,
    Float temperature,
    Integer topK,
    Integer maxOutputTokens,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Creates an AgentRunner backed by the provided ML Kit generativeModel.

Parameters
@NonNull Agent agent	The agent configuration including tools and system instructions.
@NonNull GenerativeModel generativeModel	The generative model instance to power the agent.
Float temperature	Optional temperature sampling parameter for generation. Defaults to null, which uses the underlying model's default (typically 0.0 for deterministic greedy decoding).
Integer topK	Optional top-K sampling parameter.
Integer maxOutputTokens	Optional maximum tokens to generate.
@NonNull CoroutineDispatcher coroutineDispatcher	Dispatcher on which agent orchestration and tool calls execute. Defaults to Dispatchers.IO.

AgentRunner

public AgentRunner(
    @NonNull Context context,
    @NonNull Agent agent,
    Float temperature,
    Integer topK,
    Integer maxOutputTokens,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Creates an AgentRunner with an Android context used for AppFunctions and SDK services.

Parameters
@NonNull Context context	Android Context for tool execution and AppFunctions discovery.
@NonNull Agent agent	The agent configuration including tools, instructions, and turn limits.
Float temperature	Optional temperature sampling parameter for generation. Defaults to null, which uses the underlying model's default (typically 0.0 for deterministic greedy decoding).
Integer topK	Optional top-K sampling parameter for generation.
Integer maxOutputTokens	Optional maximum tokens to generate.
@NonNull CoroutineDispatcher coroutineDispatcher	Dispatcher on which agent orchestration and tool calls execute. Defaults to Dispatchers.IO.

AgentRunner

public AgentRunner(
    @NonNull Context context,
    @NonNull Agent agent,
    @NonNull GenerativeModel generativeModel,
    Float temperature,
    Integer topK,
    Integer maxOutputTokens,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Creates an AgentRunner backed by the provided ML Kit generativeModel and Android context.

Parameters
@NonNull Context context	Android Context for tool execution and AppFunctions discovery.
@NonNull Agent agent	The agent configuration including tools and system instructions.
@NonNull GenerativeModel generativeModel	The generative model instance to power the agent.
Float temperature	Optional temperature sampling parameter for generation. Defaults to null, which uses the underlying model's default (typically 0.0 for deterministic greedy decoding).
Integer topK	Optional top-K sampling parameter.
Integer maxOutputTokens	Optional maximum tokens to generate.
@NonNull CoroutineDispatcher coroutineDispatcher	Dispatcher on which agent orchestration and tool calls execute. Defaults to Dispatchers.IO.

Public methods

clearAllSessions

public final void clearAllSessions()

Clears all in-memory conversation histories across all sessions managed by this runner.

Throws
IllegalStateException	If this runner has been closed.

close

public void close()

Closes the runner and releases all underlying in-memory resources.

deleteSession

public final void deleteSession(@NonNull String sessionId)

Explicitly clears the in-memory conversation history for a specific session.

Parameters
@NonNull String sessionId	The session ID to delete from memory.

Throws
IllegalStateException	If this runner has been closed.
IllegalArgumentException	If sessionId is blank, exceeds 128 characters, or contains invalid characters.

getAgent

public final @NonNull Agent getAgent()

The agent configuration including tools, instructions, and turn limits.

getCoroutineDispatcher

public final @NonNull CoroutineDispatcher getCoroutineDispatcher()

Dispatcher on which agent orchestration and tool calls execute. Defaults to Dispatchers.IO.

getMaxOutputTokens

public final Integer getMaxOutputTokens()

Optional maximum tokens to generate.

getOrCreateSession

public final @NonNull AgentSession getOrCreateSession(@NonNull String sessionId)

Retrieves or creates a stateful conversation session identified by sessionId.

If an active session with this sessionId already exists, returns that same AgentSession instance continuing its dialogue history. If it does not exist or was closed/deleted, a new session with this identifier is initialized.

Parameters
@NonNull String sessionId	The unique session identifier. Must not be blank, must not exceed 128 characters, and must match ^[a-zA-Z0-9_.-]+$.

Returns
@NonNull AgentSession	An AgentSession managing conversation history and turns for this session.

Throws
IllegalStateException	If this runner has been closed.
IllegalArgumentException	If sessionId fails validation.

getTemperature

public final Float getTemperature()

Optional temperature sampling parameter for generation. Defaults to null, which uses the underlying model's default (typically 0.0 for deterministic greedy decoding).

getTopK

public final Integer getTopK()

Optional top-K sampling parameter for generation.

runSingleTurnAsync

public final @NonNull Flow<@NonNull AgentEvent> runSingleTurnAsync(@NonNull Content content)

Runs the agent in single-turn mode with the given multimodal content.

The returned Flow is cold: agent execution begins only when the flow is collected, and collecting multiple times triggers independent executions.

Executes in ephemeral single-turn mode with automatic in-memory cleanup upon completion or cancellation. Dialogue history is not retained across calls.

Note: If any com.google.mlkit.genai.prompt.ImagePart in content has an alpha channel (android.graphics.Bitmap.hasAlpha is true), it is encoded as lossless PNG. For large photographic images without transparency, consider calling android.graphics.Bitmap.setHasAlpha with false or pre-compressing to reduce payload size.

Parameters
@NonNull Content content	The multimodal content (text, images, etc.) for the agent.

Returns
@NonNull Flow<@NonNull AgentEvent>	A cold Flow of events representing function calls, function responses, and text messages.

Throws
IllegalStateException	If this runner has been closed.