# AgentRunner


```
class AgentRunner : AutoCloseable
```

<br />

*** ** * ** ***

Manages agent execution sessions.

An `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner` orchestrates tool execution loops and manages conversation history across turns. When instantiated via this primary constructor without an explicit `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/prompt/GenerativeModel`, the runner defaults to the on-device model client provided by `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/prompt/Generation#getClient()`.

## Summary

| ### Public constructors |
|---|
| `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#AgentRunner(com.google.mlkit.genai.agent.Agent,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)( agent: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/Agent, temperature: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html?, topK: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html?, maxOutputTokens: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html?, coroutineDispatcher: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html )` |
| `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#AgentRunner(com.google.mlkit.genai.agent.Agent,com.google.mlkit.genai.prompt.GenerativeModel,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)( agent: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/Agent, generativeModel: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/prompt/GenerativeModel, temperature: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html?, topK: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html?, maxOutputTokens: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html?, coroutineDispatcher: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html )` Creates an `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner` backed by the provided ML Kit `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#<init>(com.google.mlkit.genai.agent.Agent,com.google.mlkit.genai.prompt.GenerativeModel,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)`. |
| `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#AgentRunner(android.content.Context,com.google.mlkit.genai.agent.Agent,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)( context: https://developer.android.com/reference/android/content/Context.html, agent: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/Agent, temperature: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html?, topK: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html?, maxOutputTokens: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html?, coroutineDispatcher: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html )` Creates an `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner` with an Android `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#<init>(android.content.Context,com.google.mlkit.genai.agent.Agent,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)` used for AppFunctions and SDK services. |
| `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#AgentRunner(android.content.Context,com.google.mlkit.genai.agent.Agent,com.google.mlkit.genai.prompt.GenerativeModel,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)( context: https://developer.android.com/reference/android/content/Context.html, agent: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/Agent, generativeModel: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/prompt/GenerativeModel, temperature: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html?, topK: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html?, maxOutputTokens: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html?, coroutineDispatcher: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html )` Creates an `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner` backed by the provided ML Kit `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#<init>(android.content.Context,com.google.mlkit.genai.agent.Agent,com.google.mlkit.genai.prompt.GenerativeModel,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)` and Android `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#<init>(android.content.Context,com.google.mlkit.genai.agent.Agent,com.google.mlkit.genai.prompt.GenerativeModel,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)`. |

| ### Public functions |
|---|---|
| `suspend https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#clearAllSessions()()` Clears all in-memory conversation histories across all sessions managed by this runner. |
| `open https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#close()()` Closes the runner and releases all underlying in-memory resources. |
| `suspend https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#deleteSession(kotlin.String)(sessionId: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)` Explicitly clears the in-memory conversation history for a specific session. |
| `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentSession` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#getOrCreateSession(kotlin.String)(sessionId: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)` Retrieves or creates a stateful conversation session identified by `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#getOrCreateSession(kotlin.String)`. |
| `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentEvent>` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#runSingleTurnAsync(com.google.mlkit.genai.prompt.Content)(content: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/prompt/Content)` Runs the agent in single-turn mode with the given multimodal `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#runSingleTurnAsync(com.google.mlkit.genai.prompt.Content)`. |

| ### Public properties |
|---|---|
| `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/Agent` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#agent()` The agent configuration including tools, instructions, and turn limits. |
| `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#coroutineDispatcher()` Dispatcher on which agent orchestration and tool calls execute. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html?` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#maxOutputTokens()` Optional maximum tokens to generate. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html?` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#temperature()` Optional temperature sampling parameter for generation. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html?` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#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: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/Agent` | The agent configuration including tools, instructions, and turn limits. |
| `temperature: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html? = 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: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html? = null` | Optional top-K sampling parameter for generation. |
| `maxOutputTokens: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html? = null` | Optional maximum tokens to generate. |
| `coroutineDispatcher: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html = Dispatchers.IO` | Dispatcher on which agent orchestration and tool calls execute. Defaults to `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-i-o.html`. |

### AgentRunner

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

Creates an `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner` backed by the provided ML Kit `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#<init>(com.google.mlkit.genai.agent.Agent,com.google.mlkit.genai.prompt.GenerativeModel,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)`.

| Parameters |
|---|---|
| `agent: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/Agent` | The agent configuration including tools and system instructions. |
| `generativeModel: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/prompt/GenerativeModel` | The generative model instance to power the agent. |
| `temperature: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html? = 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: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html? = null` | Optional top-K sampling parameter. |
| `maxOutputTokens: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html? = null` | Optional maximum tokens to generate. |
| `coroutineDispatcher: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html = Dispatchers.IO` | Dispatcher on which agent orchestration and tool calls execute. Defaults to `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-i-o.html`. |

### AgentRunner

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

Creates an `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner` with an Android `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#<init>(android.content.Context,com.google.mlkit.genai.agent.Agent,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)` used for AppFunctions and SDK services.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | Android `https://developer.android.com/reference/android/content/Context.html` for tool execution and AppFunctions discovery. |
| `agent: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/Agent` | The agent configuration including tools, instructions, and turn limits. |
| `temperature: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html? = 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: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html? = null` | Optional top-K sampling parameter for generation. |
| `maxOutputTokens: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html? = null` | Optional maximum tokens to generate. |
| `coroutineDispatcher: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html = Dispatchers.IO` | Dispatcher on which agent orchestration and tool calls execute. Defaults to `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-i-o.html`. |

### AgentRunner

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

Creates an `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner` backed by the provided ML Kit `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#<init>(android.content.Context,com.google.mlkit.genai.agent.Agent,com.google.mlkit.genai.prompt.GenerativeModel,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)` and Android `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#<init>(android.content.Context,com.google.mlkit.genai.agent.Agent,com.google.mlkit.genai.prompt.GenerativeModel,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)`.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | Android `https://developer.android.com/reference/android/content/Context.html` for tool execution and AppFunctions discovery. |
| `agent: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/Agent` | The agent configuration including tools and system instructions. |
| `generativeModel: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/prompt/GenerativeModel` | The generative model instance to power the agent. |
| `temperature: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-float/index.html? = 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: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html? = null` | Optional top-K sampling parameter. |
| `maxOutputTokens: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html? = null` | Optional maximum tokens to generate. |
| `coroutineDispatcher: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html = Dispatchers.IO` | Dispatcher on which agent orchestration and tool calls execute. Defaults to `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-i-o.html`. |

## Public functions

### clearAllSessions

```
suspend fun clearAllSessions(): Unit
```

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

| Throws |
|---|---|
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-illegal-state-exception/index.html` | 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: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html` | The session ID to delete from memory. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-illegal-state-exception/index.html` | If this runner has been closed. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-illegal-argument-exception/index.html` | If `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#deleteSession(kotlin.String)` is blank, exceeds 128 characters, or contains invalid characters. |

### getOrCreateSession

```
fun getOrCreateSession(sessionId: String): AgentSession
```

Retrieves or creates a stateful conversation session identified by `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#getOrCreateSession(kotlin.String)`.

If an active session with this `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#getOrCreateSession(kotlin.String)` already exists, returns that same `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/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: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html` | The unique session identifier. Must not be blank, must not exceed 128 characters, and must match `^[a-zA-Z0-9_.-]+$`. |

| Returns |
|---|---|
| `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentSession` | An `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentSession` managing conversation history and turns for this session. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-illegal-state-exception/index.html` | If this runner has been closed. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-illegal-argument-exception/index.html` | If `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#getOrCreateSession(kotlin.String)` fails validation. |

### runSingleTurnAsync

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

Runs the agent in single-turn mode with the given multimodal `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#runSingleTurnAsync(com.google.mlkit.genai.prompt.Content)`.

The returned `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` 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 `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/prompt/ImagePart` in `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentRunner#runSingleTurnAsync(com.google.mlkit.genai.prompt.Content)` has an alpha channel (`https://developer.android.com/reference/android/graphics/Bitmap.html#hasAlpha()` is true), it is encoded as lossless PNG. For large photographic images without transparency, consider calling `https://developer.android.com/reference/android/graphics/Bitmap.html#setHasAlpha(kotlin.Boolean)` with `false` or pre-compressing to reduce payload size.

| Parameters |
|---|---|
| `content: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/prompt/Content` | The multimodal content (text, images, etc.) for the agent. |

| Returns |
|---|---|
| `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/agent/AgentEvent>` | A cold Flow of events representing function calls, function responses, and text messages. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-illegal-state-exception/index.html` | 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 `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-i-o.html`.

### 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.