ADK for TypeScript: API Reference
    Preparing search index...

    Class ReflectAndRetryModelPlugin

    Provides self-healing, concurrent-safe error recovery for model failures.

    This plugin intercepts model failures (such as MALFORMED_FUNCTION_CALL), provides structured guidance to the LLM for reflection and correction, and retries the turn up to a configurable limit.

    import {ReflectAndRetryModelPlugin, TrackingScope} from '@google/adk';

    const modelRetryPlugin = new ReflectAndRetryModelPlugin({
      maxRetries: 3,
      trackingScope: TrackingScope.INVOCATION,
    });

    Hierarchy (View Summary)

    Constructors

    Properties

    maxRetries: number
    name: string
    onModelErrors: FinishReason[]
    scope: TrackingScope
    throwExceptionIfRetryExceeded: boolean

    Methods

    • Internal framework reflection tool handler.

      Parameters

      • __namedParameters: {
            errorDetails?: string;
            errorType?: string;
            finishReason?: string;
            responseType?: string;
            retryCount?: number;
        }

      Returns { reflection_guidance: string }

    • Callback executed after an agent's primary logic has completed.

      This callback can be used to inspect, log, or modify the agent's final result before it is returned.

      Parameters

      • _params: { agent: BaseAgent; callbackContext: Context }
        • agent: BaseAgent

          The agent that has just run.

        • callbackContext: Context

          The context for the agent invocation.

      Returns Promise<Content | undefined>

      An optional Content object. If a value is returned, it will replace the agent's original result. Returning undefined uses the original, unmodified result.

    • Callback executed after a workflow node has run.

      Not called for a node whose body was skipped by beforeNodeCallback, and not called when the node throws.

      Parameters

      • params: { node: BaseNode; nodeContext: NodeContext; output: unknown }
        • node: BaseNode

          The node that has just run.

        • nodeContext: NodeContext

          The node's execution context.

        • output: unknown

          The output the node produced.

      Returns Promise<unknown>

      An optional value replacing the node's output. Returning undefined keeps the original.

    • Callback executed after a tool has been called.

      This callback allows for inspecting, logging, or modifying the result returned by a tool.

      Parameters

      • _params: {
            result: Record<string, unknown>;
            tool: BaseTool;
            toolArgs: Record<string, unknown>;
            toolContext: Context;
        }
        • result: Record<string, unknown>

          The dictionary returned by the tool invocation.

        • tool: BaseTool

          The tool instance that has just been executed.

        • toolArgs: Record<string, unknown>

          The original arguments that were passed to the tool.

        • toolContext: Context

          The context specific to the tool execution.

      Returns Promise<Record<string, unknown> | undefined>

      An optional dictionary. If a dictionary is returned, it will replace the original result from the tool. This allows for post-processing or altering tool outputs. Returning undefined uses the original, unmodified result.

    • Callback executed before an agent's primary logic is invoked.

      This callback can be used for logging, setup, or to short-circuit the agent's execution by returning a value.

      Parameters

      • _params: { agent: BaseAgent; callbackContext: Context }
        • agent: BaseAgent

          The agent that is about to run.

        • callbackContext: Context

          The context for the agent invocation.

      Returns Promise<Content | undefined>

      An optional Content object. If a value is returned, it will bypass the agent's callbacks and its execution, and return this value directly. Returning undefined allows the agent to proceed normally.

    • Callback executed before a workflow node runs.

      Parameters

      • params: { input: unknown; node: BaseNode; nodeContext: NodeContext }
        • input: unknown

          The input the node is about to receive.

        • node: BaseNode

          The node that is about to run.

        • nodeContext: NodeContext

          The node's execution context.

      Returns Promise<unknown>

      An optional value. If anything other than undefined is returned, the node's body is skipped and the returned value becomes its output, which is how a plugin implements a node-level cache or a stub. Returning undefined lets the node run normally.

    • Callback executed before the ADK runner runs.

      This is the first callback to be called in the lifecycle, ideal for global setup or initialization tasks.

      Parameters

      • _params: { invocationContext: InvocationContext }
        • invocationContext: InvocationContext

          The context for the entire invocation, containing session information, the root agent, etc.

      Returns Promise<Content | undefined>

      An optional Event to be returned to the ADK. Returning a value to halt execution of the runner and ends the runner with that event. Return undefined to proceed normally.

    • Callback executed before a tool is called.

      This callback is useful for logging tool usage, input validation, or modifying the arguments before they are passed to the tool.

      Parameters

      • _params: { tool: BaseTool; toolArgs: Record<string, unknown>; toolContext: Context }
        • tool: BaseTool

          The tool instance that is about to be executed.

        • toolArgs: Record<string, unknown>

          The dictionary of arguments to be used for invoking the tool.

        • toolContext: Context

          The context specific to the tool execution.

      Returns Promise<Record<string, unknown> | undefined>

      An optional dictionary. If a dictionary is returned, it will stop the tool execution and return this response immediately. Returning undefined uses the original, unmodified arguments.

    • Callback executed before a tool is selected.

      This callback provides an opportunity to inspect, log, or modify the available tools before they are selected.

      Parameters

      • _params: { callbackContext: Context; tools: Readonly<Record<string, BaseTool>> }
        • callbackContext: Context

          The context for the current agent call.

        • tools: Readonly<Record<string, BaseTool>>

          The available tools.

      Returns Promise<Readonly<Record<string, BaseTool>> | undefined>

      An optional value. A non-undefined return may be used by the framework to modify or replace the available tools. Returning undefined allows the original tools to be used.

    • Generates a function call part for the model retry tool.

      Parameters

      • retryCount: number
      • OptionalerrorType: string
      • OptionalerrorDetails: string
      • OptionalfinishReason: FinishReason

      Returns Part

    • Tracks retry count, generates retry response, and checks against limits.

      Parameters

      • callbackContext: Context
      • OptionalerrorType: string
      • OptionalerrorDetails: string
      • OptionalfinishReason: FinishReason

      Returns Promise<LlmResponse | undefined>

    • Increment the failure count for a model within a scope.

      Parameters

      • scopeKey: string
      • itemName: string

      Returns Promise<number>

    • Callback executed after an event is yielded from runner.

      This is the ideal place to make modification to the event before the event is handled by the underlying agent app.

      Parameters

      Returns Promise<Event | undefined>

      An optional value. A non-undefined return may be used by the framework to modify or replace the response. Copy the incoming event when constructing a replacement to preserve fields that are not being modified, such as event actions. Returning undefined allows the original response to be used.

    • Callback executed when a model call encounters an error.

      This callback provides an opportunity to handle model errors gracefully, potentially providing alternative responses or recovery mechanisms.

      Parameters

      • _params: { callbackContext: Context; error: Error; llmRequest: LlmRequest }
        • callbackContext: Context

          The context for the current agent call.

        • error: Error

          The exception that was raised during model execution.

        • llmRequest: LlmRequest

          The request that was sent to the model when the error occurred.

      Returns Promise<LlmResponse | undefined>

      An optional LlmResponse. If an LlmResponse is returned, it will be used instead of propagating the error. Returning undefined allows the original error to be raised.

    • Callback executed when a tool call encounters an error. tool: BaseTool; toolArgs: Record<string, unknown>; toolContext: Context; result: Record<string, unknown>; }): Promise<Record<string, unknown> | undefined> { return; }

      /** Callback executed when a tool call encounters an error.

      This callback provides an opportunity to handle tool errors gracefully, potentially providing alternative responses or recovery mechanisms.

      Parameters

      • _params: {
            error: Error;
            tool: BaseTool;
            toolArgs: Record<string, unknown>;
            toolContext: Context;
        }
        • error: Error

          The exception that was raised during tool execution.

        • tool: BaseTool

          The tool instance that encountered an error.

        • toolArgs: Record<string, unknown>

          The arguments that were passed to the tool.

        • toolContext: Context

          The context specific to the tool execution.

      Returns Promise<Record<string, unknown> | undefined>

      An optional dictionary. If a dictionary is returned, it will be used as the tool response instead of propagating the error. Returning undefined allows the original error to be raised.

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

      This callback helps logging and modifying the user message before the runner starts the invocation.

      Parameters

      • _params: { invocationContext: InvocationContext; userMessage: Content }
        • invocationContext: InvocationContext

          The context for the entire invocation.

        • userMessage: Content

          The message content input by user.

      Returns Promise<Content | undefined>

      An optional Content to be returned to the ADK. Returning a value to replace the user message. Returning undefined to proceed normally.

    Constructors
    Properties
    Methods