google-adk-kotlin-core/com.google.adk.kt.plugins/ReflectAndRetryToolPlugin

ReflectAndRetryToolPlugin

class ReflectAndRetryToolPlugin(val maxRetries: Int = 3, val throwExceptionIfRetryExceeded: Boolean = true, val trackingScope: ReflectAndRetryToolPlugin.TrackingScope = TrackingScope.INVOCATION, val resultErrorExtractor: ReflectAndRetryToolPlugin.ResultErrorExtractor? = null, val retryPredicate: ReflectAndRetryToolPlugin.RetryPredicate? = null, val name: String = DEFAULT_NAME) : Plugin

Answers a failed tool call with guidance for the model to reflect on the error and retry, allowing up to maxRetries consecutive failures per tool.

A failure is an exception from the tool, a call to an unregistered tool name, or an error that resultErrorExtractor finds in a result; a success resets that tool's count. Mirrors Python ADK's ReflectAndRetryToolPlugin.

InMemoryRunner(agent = agent, plugins = listOf(ReflectAndRetryToolPlugin(maxRetries = 3)))

Constructors

ReflectAndRetryToolPlugin

constructor(maxRetries: Int = 3, throwExceptionIfRetryExceeded: Boolean = true, trackingScope: ReflectAndRetryToolPlugin.TrackingScope = TrackingScope.INVOCATION, resultErrorExtractor: ReflectAndRetryToolPlugin.ResultErrorExtractor? = null, retryPredicate: ReflectAndRetryToolPlugin.RetryPredicate? = null, name: String = DEFAULT_NAME)

Types

Builder

class Builder

Fluent builder for ReflectAndRetryToolPlugin, provided primarily for Java callers. Any property left unset falls back to the same default as the constructor.

Companion

object Companion

ResultErrorExtractor

@JvmSuppressWildcards

fun interface ResultErrorExtractor

Finds an error that a tool reported in its result instead of throwing.

RetryPredicate

@JvmSuppressWildcards

fun interface RetryPredicate

Decides whether the model may retry a failed tool call.

TrackingScope

enum TrackingScope : Enum<ReflectAndRetryToolPlugin.TrackingScope>

How long ReflectAndRetryToolPlugin keeps counting a tool's consecutive failures.

Properties

maxRetries

val maxRetries: Int

The number of consecutive failures of one tool that are answered with retry guidance; the failure after that exceeds the limit. Must not be negative; 0 disables retries.

name

open override val name: String

The unique name of the plugin instance.

resultErrorExtractor

val resultErrorExtractor: ReflectAndRetryToolPlugin.ResultErrorExtractor?

Finds errors that tools report in their results instead of throwing; when null, no result counts as a failure.

retryPredicate

val retryPredicate: ReflectAndRetryToolPlugin.RetryPredicate?

Decides which failures the model may retry. A failure it rejects is not counted and is answered at once with the guidance to stop using the tool, never by throwing; when null, every failure may be retried.

throwExceptionIfRetryExceeded

val throwExceptionIfRetryExceeded: Boolean

Once the limit is exceeded, whether to stop handling the error or to answer with guidance telling the model to stop using the tool. When set, a thrown error is left to the flow as if the plugin were absent, and an error found in a result is thrown.

trackingScope

val trackingScope: ReflectAndRetryToolPlugin.TrackingScope

Whether a tool's failures are counted per invocation or across them.

Functions

afterAgent

open suspend fun afterAgent(context: CallbackContext): CallbackChoice<Unit, Content>

Callback executed after a specific agent finishes its processing.

afterModel

open suspend fun afterModel(context: CallbackContext, response: LlmResponse): LlmResponse

Callback executed after an LLM response is received.

afterRun

open suspend override fun afterRun(invocationContext: InvocationContext)

Callback executed after the ADK runner completes its execution.

afterTool

open suspend override fun afterTool(context: ToolContext, tool: BaseTool, args: Map<String, Any?>, result: Map<String, Any?>): Map<String, Any?>

Callback executed after a tool runs, or after a before-tool callback answers the call in its place.

beforeAgent

open suspend fun beforeAgent(context: CallbackContext): CallbackChoice<EventActions, Content>

Callback executed before a specific agent starts processing.

beforeModel

open suspend fun beforeModel(context: CallbackContext, request: LlmRequest): CallbackChoice<LlmRequest, LlmResponse>

Callback executed before an LLM request is sent.

beforeRun

open suspend fun beforeRun(invocationContext: InvocationContext): CallbackChoice<Unit, Content>

Callback executed before the ADK runner starts the main execution loop.

beforeTool

open suspend fun beforeTool(context: ToolContext, tool: BaseTool, args: Map<String, Any?>): CallbackChoice<Map<String, Any?>, Map<String, Any?>>

Callback executed before a tool is invoked.

open override fun close()

Method executed when the runner is closed.

onEvent

open suspend fun onEvent(invocationContext: InvocationContext, event: Event): Event

Callback executed when an event is yielded by an agent during execution.

onModelError

open suspend fun onModelError(context: CallbackContext, request: LlmRequest, error: Throwable): CallbackChoice<Unit, LlmResponse>

Callback executed when an error occurs during an LLM interaction.

onRunError

open suspend override fun onRunError(invocationContext: InvocationContext, error: Throwable)

Callback executed when an unhandled error escapes the ADK runner run.

onToolError

open suspend override fun onToolError(context: ToolContext, tool: BaseTool, args: Map<String, Any?>, error: Throwable): CallbackChoice<Unit, Map<String, Any?>>

Callback executed when an error occurs during a tool invocation.

onUserMessage

open suspend fun onUserMessage(invocationContext: InvocationContext, userMessage: Content): Content

Callback executed when a user message is received before an invocation starts.