AgentRunner

Kotlin |Java

class AgentRunner : 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( agent: Agent, temperature: Float?, topK: Int?, maxOutputTokens: Int?, coroutineDispatcher: CoroutineDispatcher )`
`AgentRunner( agent: Agent, generativeModel: GenerativeModel, temperature: Float?, topK: Int?, maxOutputTokens: Int?, coroutineDispatcher: CoroutineDispatcher )` Creates an `AgentRunner` backed by the provided ML Kit `generativeModel`.
`AgentRunner( context: Context, agent: Agent, temperature: Float?, topK: Int?, maxOutputTokens: Int?, coroutineDispatcher: CoroutineDispatcher )` Creates an `AgentRunner` with an Android `context` used for AppFunctions and SDK services.
`AgentRunner( context: Context, agent: Agent, generativeModel: GenerativeModel, temperature: Float?, topK: Int?, maxOutputTokens: Int?, coroutineDispatcher: CoroutineDispatcher )` Creates an `AgentRunner` backed by the provided ML Kit `generativeModel` and Android `context`.

Public functions
`suspend Unit`	`clearAllSessions()` Clears all in-memory conversation histories across all sessions managed by this runner.
`open Unit`	`close()` Closes the runner and releases all underlying in-memory resources.
`suspend Unit`	`deleteSession(sessionId: String)` Explicitly clears the in-memory conversation history for a specific session.
`AgentSession`	`getOrCreateSession(sessionId: String)` Retrieves or creates a stateful conversation session identified by `sessionId`.
`Flow<AgentEvent>`	`runSingleTurnAsync(content: Content)` Runs the agent in single-turn mode with the given multimodal `content`.

Public properties
`Agent`	`agent` The agent configuration including tools, instructions, and turn limits.
`CoroutineDispatcher`	`coroutineDispatcher` Dispatcher on which agent orchestration and tool calls execute.
`Int?`	`maxOutputTokens` Optional maximum tokens to generate.
`Float?`	`temperature` Optional temperature sampling parameter for generation.
`Int?`	`topK` Optional top-K sampling parameter for generation.

Public constructors

AgentRunner

AgentRunner(
    agent: Agent,
    temperature: Float? = null,
    topK: Int? = null,
    maxOutputTokens: Int? = null,
    coroutineDispatcher: CoroutineDispatcher = Dispatchers.IO
)

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

AgentRunner

AgentRunner(
    agent: Agent,
    generativeModel: GenerativeModel,
    temperature: Float? = null,
    topK: Int? = null,
    maxOutputTokens: Int? = null,
    coroutineDispatcher: CoroutineDispatcher = Dispatchers.IO
)

Creates an AgentRunner backed by the provided ML Kit generativeModel.

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

AgentRunner

AgentRunner(
    context: Context,
    agent: Agent,
    temperature: Float? = null,
    topK: Int? = null,
    maxOutputTokens: Int? = null,
    coroutineDispatcher: CoroutineDispatcher = Dispatchers.IO
)

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

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

AgentRunner

AgentRunner(
    context: Context,
    agent: Agent,
    generativeModel: GenerativeModel,
    temperature: Float? = null,
    topK: Int? = null,
    maxOutputTokens: Int? = null,
    coroutineDispatcher: CoroutineDispatcher = Dispatchers.IO
)

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

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

Public functions

clearAllSessions

suspend fun clearAllSessions(): Unit

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

Throws
`IllegalStateException`	If this runner has been closed.

close

open fun close(): Unit

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

deleteSession

suspend fun deleteSession(sessionId: String): Unit

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

Parameters
`sessionId: String`	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.

getOrCreateSession

fun getOrCreateSession(sessionId: String): AgentSession

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
`sessionId: String`	The unique session identifier. Must not be blank, must not exceed 128 characters, and must match `^[a-zA-Z0-9_.-]+$`.

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

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

runSingleTurnAsync

fun runSingleTurnAsync(content: Content): Flow<AgentEvent>

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
`content: Content`	The multimodal content (text, images, etc.) for the agent.

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

Throws
`IllegalStateException`	If this runner has been closed.

Public properties

agent

val agent: Agent

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

coroutineDispatcher

val coroutineDispatcher: CoroutineDispatcher

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

maxOutputTokens

val maxOutputTokens: Int?

Optional maximum tokens to generate.

temperature

val temperature: Float?

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

topK

val topK: Int?

Optional top-K sampling parameter for generation.