# AgentRunner


```
public final class AgentRunner implements AutoCloseable
```

<br />

*** ** * ** ***

Manages agent execution sessions.

An `https://developers.google.com/android/reference/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/com/google/mlkit/genai/prompt/GenerativeModel`, the runner defaults to the on-device model client provided by `https://developers.google.com/android/reference/com/google/mlkit/genai/prompt/Generation#getClient()`.

## Summary

| ### Public constructors |
|---|
| `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#AgentRunner(com.google.mlkit.genai.agent.Agent,kotlin.Float,kotlin.Int,kotlin.Int,kotlinx.coroutines.CoroutineDispatcher)( @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/Agent agent, https://developer.android.com/reference/java/lang/Float.html temperature, https://developer.android.com/reference/java/lang/Integer.html topK, https://developer.android.com/reference/java/lang/Integer.html maxOutputTokens, @https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html coroutineDispatcher )` |
| `https://developers.google.com/android/reference/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)( @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/Agent agent, @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/prompt/GenerativeModel generativeModel, https://developer.android.com/reference/java/lang/Float.html temperature, https://developer.android.com/reference/java/lang/Integer.html topK, https://developer.android.com/reference/java/lang/Integer.html maxOutputTokens, @https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html coroutineDispatcher )` Creates an `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner` backed by the provided ML Kit `https://developers.google.com/android/reference/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/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)( @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developer.android.com/reference/android/content/Context.html context, @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/Agent agent, https://developer.android.com/reference/java/lang/Float.html temperature, https://developer.android.com/reference/java/lang/Integer.html topK, https://developer.android.com/reference/java/lang/Integer.html maxOutputTokens, @https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html coroutineDispatcher )` Creates an `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner` with an Android `https://developers.google.com/android/reference/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/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)( @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developer.android.com/reference/android/content/Context.html context, @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/Agent agent, @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/prompt/GenerativeModel generativeModel, https://developer.android.com/reference/java/lang/Float.html temperature, https://developer.android.com/reference/java/lang/Integer.html topK, https://developer.android.com/reference/java/lang/Integer.html maxOutputTokens, @https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html coroutineDispatcher )` Creates an `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner` backed by the provided ML Kit `https://developers.google.com/android/reference/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/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 methods |
|---|---|
| `final void` | `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#clearAllSessions()()` Clears all in-memory conversation histories across all sessions managed by this runner. |
| `void` | `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#close()()` Closes the runner and releases all underlying in-memory resources. |
| `final void` | `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#deleteSession(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developer.android.com/reference/java/lang/String.html sessionId)` Explicitly clears the in-memory conversation history for a specific session. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/Agent` | `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#getAgent()()` The agent configuration including tools, instructions, and turn limits. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html` | `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#getCoroutineDispatcher()()` Dispatcher on which agent orchestration and tool calls execute. |
| `final https://developer.android.com/reference/java/lang/Integer.html` | `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#getMaxOutputTokens()()` Optional maximum tokens to generate. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentSession` | `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#getOrCreateSession(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developer.android.com/reference/java/lang/String.html sessionId)` Retrieves or creates a stateful conversation session identified by `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#getOrCreateSession(kotlin.String)`. |
| `final https://developer.android.com/reference/java/lang/Float.html` | `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#getTemperature()()` Optional temperature sampling parameter for generation. |
| `final https://developer.android.com/reference/java/lang/Integer.html` | `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#getTopK()()` Optional top-K sampling parameter for generation. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentEvent>` | `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#runSingleTurnAsync(com.google.mlkit.genai.prompt.Content)(@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/prompt/Content content)` Runs the agent in single-turn mode with the given multimodal `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#runSingleTurnAsync(com.google.mlkit.genai.prompt.Content)`. |

## Public constructors

### AgentRunner

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/Agent agent` | The agent configuration including tools, instructions, and turn limits. |
| `https://developer.android.com/reference/java/lang/Float.html temperature` | Optional temperature sampling parameter for generation. Defaults to null, which uses the underlying model's default (typically 0.0 for deterministic greedy decoding). |
| `https://developer.android.com/reference/java/lang/Integer.html topK` | Optional top-K sampling parameter for generation. |
| `https://developer.android.com/reference/java/lang/Integer.html maxOutputTokens` | Optional maximum tokens to generate. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html 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`. |

### AgentRunner

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

Creates an `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner` backed by the provided ML Kit `https://developers.google.com/android/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/Agent agent` | The agent configuration including tools and system instructions. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/prompt/GenerativeModel generativeModel` | The generative model instance to power the agent. |
| `https://developer.android.com/reference/java/lang/Float.html temperature` | Optional temperature sampling parameter for generation. Defaults to null, which uses the underlying model's default (typically 0.0 for deterministic greedy decoding). |
| `https://developer.android.com/reference/java/lang/Integer.html topK` | Optional top-K sampling parameter. |
| `https://developer.android.com/reference/java/lang/Integer.html maxOutputTokens` | Optional maximum tokens to generate. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html 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`. |

### AgentRunner

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

Creates an `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner` with an Android `https://developers.google.com/android/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developer.android.com/reference/android/content/Context.html context` | Android `https://developer.android.com/reference/android/content/Context.html` for tool execution and AppFunctions discovery. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/Agent agent` | The agent configuration including tools, instructions, and turn limits. |
| `https://developer.android.com/reference/java/lang/Float.html temperature` | Optional temperature sampling parameter for generation. Defaults to null, which uses the underlying model's default (typically 0.0 for deterministic greedy decoding). |
| `https://developer.android.com/reference/java/lang/Integer.html topK` | Optional top-K sampling parameter for generation. |
| `https://developer.android.com/reference/java/lang/Integer.html maxOutputTokens` | Optional maximum tokens to generate. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html 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`. |

### AgentRunner

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

Creates an `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner` backed by the provided ML Kit `https://developers.google.com/android/reference/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/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developer.android.com/reference/android/content/Context.html context` | Android `https://developer.android.com/reference/android/content/Context.html` for tool execution and AppFunctions discovery. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/Agent agent` | The agent configuration including tools and system instructions. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/prompt/GenerativeModel generativeModel` | The generative model instance to power the agent. |
| `https://developer.android.com/reference/java/lang/Float.html temperature` | Optional temperature sampling parameter for generation. Defaults to null, which uses the underlying model's default (typically 0.0 for deterministic greedy decoding). |
| `https://developer.android.com/reference/java/lang/Integer.html topK` | Optional top-K sampling parameter. |
| `https://developer.android.com/reference/java/lang/Integer.html maxOutputTokens` | Optional maximum tokens to generate. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html 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`. |

## Public methods

### clearAllSessions

```
public final void clearAllSessions()
```

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

```
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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developer.android.com/reference/java/lang/String.html sessionId` | 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/com/google/mlkit/genai/agent/AgentRunner#deleteSession(kotlin.String)` 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 `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-i-o.html`.

### 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 `https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentRunner#getOrCreateSession(kotlin.String)`.

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

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/agent/AgentSession` | An `https://developers.google.com/android/reference/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/com/google/mlkit/genai/agent/AgentRunner#getOrCreateSession(kotlin.String)` 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 `https://developers.google.com/android/reference/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/com/google/mlkit/genai/prompt/ImagePart` in `https://developers.google.com/android/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/prompt/Content content` | The multimodal content (text, images, etc.) for the agent. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/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. |