Class BasePlugin

java.lang.Object
com.google.adk.plugins.BasePlugin
Direct Known Subclasses:
LoggingPlugin
public abstract class BasePlugin extends Object
Base class for creating plugins.

Plugins provide a structured way to intercept and modify agent, tool, and LLM behaviors at critical execution points in a callback manner. While agent callbacks apply to a particular agent, plugins applies globally to all agents added in the runner. Plugins are best used for adding custom behaviors like logging, monitoring, caching, or modifying requests and responses at key stages.

A plugin can implement one or more methods of callbacks, but should not implement the same method of callback for multiple times.

  • Field Details

    • name

      protected final String name

  • Constructor Details

    • BasePlugin

      public BasePlugin(String name)

  • Method Details

    • getName

      public String getName()

    • onUserMessageCallback

      public io.reactivex.rxjava3.core.Maybe<com.google.genai.types.Content> onUserMessageCallback(InvocationContext invocationContext, com.google.genai.types.Content userMessage)
      Callback executed when a user message is received before an invocation starts.
      Parameters:
      invocationContext - The context for the entire invocation.
      userMessage - The message content input by user.
      Returns:
      An optional Content to replace the user message. Returning Empty to proceed normally.

    • beforeRunCallback

      public io.reactivex.rxjava3.core.Maybe<com.google.genai.types.Content> beforeRunCallback(InvocationContext invocationContext)
      Callback executed before the ADK runner runs.
      Parameters:
      invocationContext - The context for the entire invocation.
      Returns:
      An optional Content to halt execution. Returning Empty to proceed normally.

    • onEventCallback

      public io.reactivex.rxjava3.core.Maybe<Event> onEventCallback(InvocationContext invocationContext, Event event)
      Callback executed after an event is yielded from runner.
      Parameters:
      invocationContext - The context for the entire invocation.
      event - The event raised by the runner.
      Returns:
      An optional Event to modify or replace the response. Returning Empty to proceed normally.

    • afterRunCallback

      public io.reactivex.rxjava3.core.Completable afterRunCallback(InvocationContext invocationContext)
      Callback executed after an ADK runner run has completed.
      Parameters:
      invocationContext - The context for the entire invocation.

    • beforeAgentCallback

      public io.reactivex.rxjava3.core.Maybe<com.google.genai.types.Content> beforeAgentCallback(BaseAgent agent, CallbackContext callbackContext)
      Callback executed before an agent's primary logic is invoked.
      Parameters:
      agent - The agent that is about to run.
      callbackContext - The context for the agent invocation.
      Returns:
      An optional Content object to bypass the agent's execution. Returning Empty to proceed normally.

    • afterAgentCallback

      public io.reactivex.rxjava3.core.Maybe<com.google.genai.types.Content> afterAgentCallback(BaseAgent agent, CallbackContext callbackContext)
      Callback executed after an agent's primary logic has completed.
      Parameters:
      agent - The agent that has just run.
      callbackContext - The context for the agent invocation.
      Returns:
      An optional Content object to replace the agent's original result. Returning Empty to use the original result.

    • beforeModelCallback

      public io.reactivex.rxjava3.core.Maybe<LlmResponse> beforeModelCallback(CallbackContext callbackContext, LlmRequest llmRequest)
      Callback executed before a request is sent to the model.
      Parameters:
      callbackContext - The context for the current agent call.
      llmRequest - The prepared request object to be sent to the model.
      Returns:
      An optional LlmResponse to trigger an early exit. Returning Empty to proceed normally.

    • afterModelCallback

      public io.reactivex.rxjava3.core.Maybe<LlmResponse> afterModelCallback(CallbackContext callbackContext, LlmResponse llmResponse)
      Callback executed after a response is received from the model.
      Parameters:
      callbackContext - The context for the current agent call.
      llmResponse - The response object received from the model.
      Returns:
      An optional LlmResponse to modify or replace the response. Returning Empty to use the original response.

    • onModelErrorCallback

      public io.reactivex.rxjava3.core.Maybe<LlmResponse> onModelErrorCallback(CallbackContext callbackContext, LlmRequest llmRequest, Throwable error)
      Callback executed when a model call encounters an error.
      Parameters:
      callbackContext - The context for the current agent call.
      llmRequest - The request that was sent to the model.
      error - The exception that was raised.
      Returns:
      An optional LlmResponse to use instead of propagating the error. Returning Empty to allow the original error to be raised.

    • beforeToolCallback

      public io.reactivex.rxjava3.core.Maybe<Map<String,Object>> beforeToolCallback(BaseTool tool, Map<String,Object> toolArgs, ToolContext toolContext)
      Callback executed before a tool is called.
      Parameters:
      tool - The tool instance that is about to be executed.
      toolArgs - The dictionary of arguments to be used for invoking the tool.
      toolContext - The context specific to the tool execution.
      Returns:
      An optional Map to stop the tool execution and return this response immediately. Returning Empty to proceed normally.

    • afterToolCallback

      public io.reactivex.rxjava3.core.Maybe<Map<String,Object>> afterToolCallback(BaseTool tool, Map<String,Object> toolArgs, ToolContext toolContext, Map<String,Object> result)
      Callback executed after a tool has been called.
      Parameters:
      tool - The tool instance that has just been executed.
      toolArgs - The original arguments that were passed to the tool.
      toolContext - The context specific to the tool execution.
      result - The dictionary returned by the tool invocation.
      Returns:
      An optional Map to replace the original result from the tool. Returning Empty to use the original result.

    • onToolErrorCallback

      public io.reactivex.rxjava3.core.Maybe<Map<String,Object>> onToolErrorCallback(BaseTool tool, Map<String,Object> toolArgs, ToolContext toolContext, Throwable error)
      Callback executed when a tool call encounters an error.
      Parameters:
      tool - The tool instance that encountered an error.
      toolArgs - The arguments that were passed to the tool.
      toolContext - The context specific to the tool execution.
      error - The exception that was raised during tool execution.
      Returns:
      An optional Map to be used as the tool response instead of propagating the error. Returning Empty to allow the original error to be raised.