@google/adk 0.2.3 → 0.2.5

package/dist/types/plugins/base_plugin.d.ts

@@ -110,13 +110,13 @@ export declare abstract class BasePlugin {
      * This callback helps logging and modifying the user message before the
      * runner starts the invocation.
      *
-     * @param invocationContext The context for the entire invocation.
-     * @param userMessage The message content input by user.
+     * @param params.invocationContext The context for the entire invocation.
+     * @param params.userMessage The message content input by user.
      * @returns An optional `Content` to be returned to the ADK. Returning a
      *     value to replace the user message. Returning `undefined` to proceed
      *     normally.
      */
-    onUserMessageCallback({ invocationContext, userMessage }: {
+    onUserMessageCallback(params: {
         invocationContext: InvocationContext;
         userMessage: Content;
     }): Promise<Content | undefined>;
@@ -126,13 +126,13 @@ export declare abstract class BasePlugin {
      * This is the first callback to be called in the lifecycle, ideal for global
      * setup or initialization tasks.
      *
-     * @param invocationContext The context for the entire invocation, containing
+     * @param params.invocationContext The context for the entire invocation, containing
      *     session information, the root agent, etc.
      * @returns 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.
      */
-    beforeRunCallback({ invocationContext }: {
+    beforeRunCallback(params: {
         invocationContext: InvocationContext;
     }): Promise<Content | undefined>;
     /**
@@ -141,13 +141,13 @@ export declare abstract class BasePlugin {
      * This is the ideal place to make modification to the event before the event
      * is handled by the underlying agent app.
      *
-     * @param invocationContext The context for the entire invocation.
-     * @param event The event raised by the runner.
+     * @param params.invocationContext The context for the entire invocation.
+     * @param params.event The event raised by the runner.
      * @returns An optional value. A non-`undefined` return may be used by the
      *     framework to modify or replace the response. Returning `undefined`
      *     allows the original response to be used.
      */
-    onEventCallback({ invocationContext, event }: {
+    onEventCallback(params: {
         invocationContext: InvocationContext;
         event: Event;
     }): Promise<Event | undefined>;
@@ -157,10 +157,10 @@ export declare abstract class BasePlugin {
      * This is the final callback in the ADK lifecycle, suitable for cleanup,
      * final logging, or reporting tasks.
      *
-     * @param invocationContext The context for the entire invocation.
+     * @param params.invocationContext The context for the entire invocation.
      * @returns undefined
      */
-    afterRunCallback({ invocationContext }: {
+    afterRunCallback(params: {
         invocationContext: InvocationContext;
     }): Promise<void>;
     /**
@@ -169,13 +169,13 @@ export declare abstract class BasePlugin {
      * This callback can be used for logging, setup, or to short-circuit the
      * agent's execution by returning a value.
      *
-     * @param agent The agent that is about to run.
-     * @param callbackContext The context for the agent invocation.
+     * @param params.agent The agent that is about to run.
+     * @param params.callbackContext The context for the agent invocation.
      * @returns 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.
      */
-    beforeAgentCallback({ agent, callbackContext }: {
+    beforeAgentCallback(params: {
         agent: BaseAgent;
         callbackContext: CallbackContext;
     }): Promise<Content | undefined>;
@@ -185,13 +185,13 @@ export declare abstract class BasePlugin {
      * This callback can be used to inspect, log, or modify the agent's final
      * result before it is returned.
      *
-     * @param agent The agent that has just run.
-     * @param callbackContext The context for the agent invocation.
+     * @param params.agent The agent that has just run.
+     * @param params.callbackContext The context for the agent invocation.
      * @returns An optional `Content` object. If a value is returned, it will
      *     replace the agent's original result. Returning `undefined` uses the
      *     original, unmodified result.
      */
-    afterAgentCallback({ agent, callbackContext }: {
+    afterAgentCallback(params: {
         agent: BaseAgent;
         callbackContext: CallbackContext;
     }): Promise<Content | undefined>;
@@ -202,13 +202,13 @@ export declare abstract class BasePlugin {
      * object. It can also be used to implement caching by returning a cached
      * `LlmResponse`, which would skip the actual model call.
      *
-     * @param callbackContext The context for the current agent call.
-     * @param llmRequest The prepared request object to be sent to the model.
+     * @param params.callbackContext The context for the current agent call.
+     * @param params.llmRequest The prepared request object to be sent to the model.
      * @returns An optional value. The interpretation of a non-`undefined`
      *     trigger an early exit and returns the response immediately. Returning
      *     `undefined` allows the LLM request to proceed normally.
      */
-    beforeModelCallback({ callbackContext, llmRequest }: {
+    beforeModelCallback(params: {
         callbackContext: CallbackContext;
         llmRequest: LlmRequest;
     }): Promise<LlmResponse | undefined>;
@@ -218,13 +218,13 @@ export declare abstract class BasePlugin {
      * This is the ideal place to log model responses, collect metrics on token
      * usage, or perform post-processing on the raw `LlmResponse`.
      *
-     * @param callbackContext The context for the current agent call.
-     * @param llmResponse The response object received from the model.
+     * @param params.callbackContext The context for the current agent call.
+     * @param params.llmResponse The response object received from the model.
      * @returns An optional value. A non-`undefined` return may be used by the
      *     framework to modify or replace the response. Returning `undefined`
      *     allows the original response to be used.
      */
-    afterModelCallback({ callbackContext, llmResponse }: {
+    afterModelCallback(params: {
         callbackContext: CallbackContext;
         llmResponse: LlmResponse;
     }): Promise<LlmResponse | undefined>;
@@ -234,15 +234,15 @@ export declare abstract class BasePlugin {
      * This callback provides an opportunity to handle model errors gracefully,
      * potentially providing alternative responses or recovery mechanisms.
      *
-     * @param callbackContext The context for the current agent call.
-     * @param llmRequest The request that was sent to the model when the error
+     * @param params.callbackContext The context for the current agent call.
+     * @param params.llmRequest The request that was sent to the model when the error
      *     occurred.
-     * @param error The exception that was raised during model execution.
+     * @param params.error The exception that was raised during model execution.
      * @returns 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.
      */
-    onModelErrorCallback({ callbackContext, llmRequest, error }: {
+    onModelErrorCallback(params: {
         callbackContext: CallbackContext;
         llmRequest: LlmRequest;
         error: Error;
@@ -253,15 +253,15 @@ export declare abstract class BasePlugin {
      * This callback is useful for logging tool usage, input validation, or
      * modifying the arguments before they are passed to the tool.
      *
-     * @param tool The tool instance that is about to be executed.
-     * @param toolArgs The dictionary of arguments to be used for invoking the
+     * @param params.tool The tool instance that is about to be executed.
+     * @param params.toolArgs The dictionary of arguments to be used for invoking the
      *     tool.
-     * @param toolContext The context specific to the tool execution.
+     * @param params.toolContext The context specific to the tool execution.
      * @returns 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.
      */
-    beforeToolCallback({ tool, toolArgs, toolContext }: {
+    beforeToolCallback(params: {
         tool: BaseTool;
         toolArgs: Record<string, unknown>;
         toolContext: ToolContext;
@@ -272,36 +272,46 @@ export declare abstract class BasePlugin {
      * This callback allows for inspecting, logging, or modifying the result
      * returned by a tool.
      *
-     * @param tool The tool instance that has just been executed.
-     * @param toolArgs The original arguments that were passed to the tool.
-     * @param toolContext The context specific to the tool execution.
-     * @param result The dictionary returned by the tool invocation.
+     * @param params.tool The tool instance that has just been executed.
+     * @param params.toolArgs The original arguments that were passed to the tool.
+     * @param params.toolContext The context specific to the tool execution.
+     * @param params.result The dictionary returned by the tool invocation.
      * @returns 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.
      */
-    afterToolCallback({ tool, toolArgs, toolContext, result }: {
+    afterToolCallback(params: {
         tool: BaseTool;
         toolArgs: Record<string, unknown>;
         toolContext: ToolContext;
         result: Record<string, unknown>;
     }): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Callback executed when a tool call encounters an error.
+      tool: BaseTool;
+      toolArgs: Record<string, unknown>;
+      toolContext: ToolContext;
+      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.
      *
-     * @param tool The tool instance that encountered an error.
-     * @param toolArgs The arguments that were passed to the tool.
-     * @param toolContext The context specific to the tool execution.
-     * @param error The exception that was raised during tool execution.
+     * @param params.tool The tool instance that encountered an error.
+     * @param params.toolArgs The arguments that were passed to the tool.
+     * @param params.toolContext The context specific to the tool execution.
+     * @param params.error The exception that was raised during tool execution.
      * @returns 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.
      */
-    onToolErrorCallback({ tool, toolArgs, toolContext, error }: {
+    onToolErrorCallback(params: {
         tool: BaseTool;
         toolArgs: Record<string, unknown>;
         toolContext: ToolContext;

package/dist/types/runner/runner.d.ts

@@ -13,8 +13,17 @@ import { BaseMemoryService } from '../memory/base_memory_service.js';
 import { BasePlugin } from '../plugins/base_plugin.js';
 import { PluginManager } from '../plugins/plugin_manager.js';
 import { BaseSessionService } from '../sessions/base_session_service.js';
-interface RunnerInput {
+/**
+ * The configuration parameters for the Runner.
+ */
+export interface RunnerConfig {
+    /**
+     * The application name.
+     */
     appName: string;
+    /**
+     * The agent to run.
+     */
     agent: BaseAgent;
     plugins?: BasePlugin[];
     artifactService?: BaseArtifactService;
@@ -30,19 +39,19 @@ export declare class Runner {
     readonly sessionService: BaseSessionService;
     readonly memoryService?: BaseMemoryService;
     readonly credentialService?: BaseCredentialService;
-    constructor(input: RunnerInput);
+    constructor(input: RunnerConfig);
     /**
      * Runs the agent with the given message, and returns an async generator of
      * events.
      *
-     * @param userId The user ID of the session.
-     * @param sessionId The session ID of the session.
-     * @param newMessage A new message to append to the session.
-     * @param stateDelta An optional state delta to apply to the session.
-     * @param runConfig The run config for the agent.
+     * @param params.userId The user ID of the session.
+     * @param params.sessionId The session ID of the session.
+     * @param params.newMessage A new message to append to the session.
+     * @param params.stateDelta An optional state delta to apply to the session.
+     * @param params.runConfig The run config for the agent.
      * @yields The events generated by the agent.
      */
-    runAsync({ userId, sessionId, newMessage, stateDelta, runConfig, }: {
+    runAsync(params: {
         userId: string;
         sessionId: string;
         newMessage: Content;
@@ -77,4 +86,3 @@ export declare class Runner {
      */
     private isRoutableLlmAgent;
 }
-export {};

package/dist/types/tools/agent_tool.d.ts

@@ -19,6 +19,17 @@ export interface AgentToolConfig {
      */
     skipSummarization?: boolean;
 }
+/**
+ * A unique symbol to identify ADK agent classes.
+ * Defined once and shared by all BaseTool instances.
+ */
+declare const AGENT_TOOL_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of BaseTool.
+ * @param obj The object to check.
+ * @returns True if the object is an instance of BaseTool, false otherwise.
+ */
+export declare function isAgentTool(obj: unknown): obj is AgentTool;
 /**
  * A tool that wraps an agent.
  *
@@ -29,9 +40,12 @@ export interface AgentToolConfig {
  *  @param config: The configuration of the agent tool.
  */
 export declare class AgentTool extends BaseTool {
+    /** A unique symbol to identify ADK agent tool class. */
+    readonly [AGENT_TOOL_SIGNATURE_SYMBOL] = true;
     private readonly agent;
     private readonly skipSummarization;
     constructor(config: AgentToolConfig);
     _getDeclaration(): FunctionDeclaration;
     runAsync({ args, toolContext }: RunAsyncToolRequest): Promise<unknown>;
 }
+export {};

package/dist/types/tools/base_tool.d.ts

@@ -28,10 +28,23 @@ export interface BaseToolParams {
     description: string;
     isLongRunning?: boolean;
 }
+/**
+ * A unique symbol to identify ADK agent classes.
+ * Defined once and shared by all BaseTool instances.
+ */
+declare const BASE_TOOL_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of BaseTool.
+ * @param obj The object to check.
+ * @returns True if the object is an instance of BaseTool, false otherwise.
+ */
+export declare function isBaseTool(obj: unknown): obj is BaseTool;
 /**
  * The base class for all tools.
  */
 export declare abstract class BaseTool {
+    /** A unique symbol to identify ADK base tool class. */
+    readonly [BASE_TOOL_SIGNATURE_SYMBOL] = true;
     readonly name: string;
     readonly description: string;
     readonly isLongRunning: boolean;
@@ -82,3 +95,4 @@ export declare abstract class BaseTool {
      */
     get apiVariant(): import("../utils/variant_utils.js").GoogleLLMVariant;
 }
+export {};

package/dist/types/tools/function_tool.d.ts

@@ -12,7 +12,7 @@ import { ToolContext } from './tool_context.js';
  */
 export type ToolInputParameters = undefined | ZodObject<ZodRawShape> | Schema;
 export type ToolExecuteArgument<TParameters extends ToolInputParameters> = TParameters extends ZodObject<infer T, infer U, infer V> ? zInfer<ZodObject<T, U, V>> : TParameters extends Schema ? unknown : string;
-type ToolExecuteFunction<TParameters extends ToolInputParameters> = (input: ToolExecuteArgument<TParameters>, tool_context?: ToolContext) => Promise<unknown> | unknown;
+export type ToolExecuteFunction<TParameters extends ToolInputParameters> = (input: ToolExecuteArgument<TParameters>, tool_context?: ToolContext) => Promise<unknown> | unknown;
 /**
  * The configuration options for creating a function-based tool.
  * The `name`, `description` and `parameters` fields are used to generate the
@@ -28,7 +28,20 @@ export type ToolOptions<TParameters extends ToolInputParameters> = {
     execute: ToolExecuteFunction<TParameters>;
     isLongRunning?: boolean;
 };
+/**
+ * A unique symbol to identify ADK agent classes.
+ * Defined once and shared by all BaseTool instances.
+ */
+declare const FUNCTION_TOOL_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of BaseTool.
+ * @param obj The object to check.
+ * @returns True if the object is an instance of BaseTool, false otherwise.
+ */
+export declare function isFunctionTool(obj: unknown): obj is FunctionTool;
 export declare class FunctionTool<TParameters extends ToolInputParameters = undefined> extends BaseTool {
+    /** A unique symbol to identify ADK function tool class. */
+    readonly [FUNCTION_TOOL_SIGNATURE_SYMBOL] = true;
     private readonly execute;
     private readonly parameters?;
     /**

package/dist/types/tools/google_search_tool.d.ts

@@ -6,13 +6,12 @@ import { BaseTool, RunAsyncToolRequest, ToolProcessLlmRequest } from './base_too
  * This tool operates internally within the model and does not require or
  * perform local code execution.
  */
-declare class GoogleSearchTool extends BaseTool {
+export declare class GoogleSearchTool extends BaseTool {
     constructor();
     runAsync(request: RunAsyncToolRequest): Promise<unknown>;
-    processLlmRequest({ toolContext, llmRequest }: ToolProcessLlmRequest): Promise<void>;
+    processLlmRequest({ toolContext, llmRequest, }: ToolProcessLlmRequest): Promise<void>;
 }
 /**
- * A global instance of GoogleSearchTool.
+ * A global instance of {@link GoogleSearchTool}.
  */
 export declare const GOOGLE_SEARCH: GoogleSearchTool;
-export {};

package/dist/types/tools/tool_context.d.ts

@@ -24,7 +24,7 @@ export declare class ToolContext extends CallbackContext {
      * @param params.toolConfirmation The tool confirmation of the current tool
      *     call.
      */
-    constructor({ invocationContext, eventActions, functionCallId, toolConfirmation, }: {
+    constructor(params: {
         invocationContext: InvocationContext;
         eventActions?: EventActions;
         functionCallId?: string;

package/dist/types/version.d.ts

@@ -3,4 +3,4 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-export declare const version = "0.2.3";
+export declare const version = "0.2.5";

package/dist/web/agents/base_agent.js

@@ -60,7 +60,9 @@ class BaseAgent {
     this.parentAgent = config.parentAgent;
     this.subAgents = config.subAgents || [];
     this.rootAgent = getRootAgent(this);
-    this.beforeAgentCallback = getCannonicalCallback(config.beforeAgentCallback);
+    this.beforeAgentCallback = getCannonicalCallback(
+      config.beforeAgentCallback
+    );
     this.afterAgentCallback = getCannonicalCallback(config.afterAgentCallback);
     this.setParentAgentForSubAgents();
   }
@@ -237,7 +239,9 @@ class BaseAgent {
   setParentAgentForSubAgents() {
     for (const subAgent of this.subAgents) {
       if (subAgent.parentAgent) {
-        throw new Error('Agent "'.concat(subAgent.name, '" already has a parent agent, current parent: "').concat(subAgent.parentAgent.name, '", trying to add: "').concat(this.name, '"'));
+        throw new Error(
+          'Agent "'.concat(subAgent.name, '" already has a parent agent, current parent: "').concat(subAgent.parentAgent.name, '", trying to add: "').concat(this.name, '"')
+        );
       }
       subAgent.parentAgent = this;
     }
@@ -245,7 +249,9 @@ class BaseAgent {
 }
 function validateAgentName(name) {
   if (!isIdentifier(name)) {
-    throw new Error('Found invalid agent name: "'.concat(name, '". Agent name must be a valid identifier. It should start with a letter (a-z, A-Z) or an underscore (_), and can only contain letters, digits (0-9), and underscores.'));
+    throw new Error(
+      'Found invalid agent name: "'.concat(name, '". Agent name must be a valid identifier. It should start with a letter (a-z, A-Z) or an underscore (_), and can only contain letters, digits (0-9), and underscores.')
+    );
   }
   if (name === "user") {
     throw new Error(

package/dist/web/agents/content_processor_utils.js

@@ -3,7 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import cloneDeep from "lodash-es/cloneDeep.js";
+import { cloneDeep } from "lodash-es";
 import { createEvent, getFunctionCalls, getFunctionResponses } from "../events/event.js";
 import { removeClientFunctionCallId, REQUEST_CONFIRMATION_FUNCTION_CALL_NAME, REQUEST_EUC_FUNCTION_CALL_NAME } from "./functions.js";
 function getContents(events, agentName, currentBranch) {

package/dist/web/agents/functions.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { createUserContent } from "@google/genai";
-import isEmpty from "lodash-es/isEmpty.js";
+import { isEmpty } from "lodash-es";
 import { createEvent, getFunctionCalls } from "../events/event.js";
 import { mergeEventActions } from "../events/event_actions.js";
 import { ToolContext } from "../tools/tool_context.js";

package/dist/web/agents/invocation_context.js

@@ -17,7 +17,9 @@ class InvocationCostManager {
   incrementAndEnforceLlmCallsLimit(runConfig) {
     this.numberOfLlmCalls++;
     if (runConfig && runConfig.maxLlmCalls > 0 && this.numberOfLlmCalls > runConfig.maxLlmCalls) {
-      throw new Error("Max number of llm calls limit of ".concat(runConfig.maxLlmCalls, " exceeded"));
+      throw new Error(
+        "Max number of llm calls limit of ".concat(runConfig.maxLlmCalls, " exceeded")
+      );
     }
   }
 }