@google/adk 0.1.0

package/dist/esm/tools/agent_tool.js

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Type } from "@google/genai";
+import { LlmAgent } from "../agents/llm_agent.js";
+import { InMemoryMemoryService } from "../memory/in_memory_memory_service.js";
+import { Runner } from "../runner/runner.js";
+import { InMemorySessionService } from "../sessions/in_memory_session_service.js";
+import { GoogleLLMVariant } from "../utils/variant_utils.js";
+import { BaseTool } from "./base_tool.js";
+import { ForwardingArtifactService } from "./forwarding_artifact_service.js";
+class AgentTool extends BaseTool {
+  constructor(config) {
+    super(
+      { name: config.agent.name, description: config.agent.description || "" }
+    );
+    this.agent = config.agent;
+    this.skipSummarization = config.skipSummarization || false;
+  }
+  _getDeclaration() {
+    let declaration;
+    if (this.agent instanceof LlmAgent && this.agent.inputSchema) {
+      declaration = {
+        name: this.name,
+        description: this.description,
+        // TODO(b/425992518): We should not use the agent's input schema as is.
+        // It should be validated and possibly transformed. Consider similar
+        // logic to one we have in Python ADK.
+        parameters: this.agent.inputSchema
+      };
+    } else {
+      declaration = {
+        name: this.name,
+        description: this.description,
+        parameters: {
+          type: Type.OBJECT,
+          properties: {
+            "request": {
+              type: Type.STRING
+            }
+          },
+          required: ["request"]
+        }
+      };
+    }
+    if (this.apiVariant !== GoogleLLMVariant.GEMINI_API) {
+      const hasOutputSchema = this.agent instanceof LlmAgent && this.agent.outputSchema;
+      declaration.response = hasOutputSchema ? { type: Type.OBJECT } : { type: Type.STRING };
+    }
+    return declaration;
+  }
+  async runAsync({ args, toolContext }) {
+    var _a, _b;
+    if (this.skipSummarization) {
+      toolContext.actions.skipSummarization = true;
+    }
+    const hasInputSchema = this.agent instanceof LlmAgent && this.agent.inputSchema;
+    const content = {
+      role: "user",
+      parts: [
+        {
+          // TODO(b/425992518): Should be validated. Consider similar
+          // logic to one we have in Python ADK.
+          text: hasInputSchema ? JSON.stringify(args) : args["request"]
+        }
+      ]
+    };
+    const runner = new Runner({
+      appName: this.agent.name,
+      agent: this.agent,
+      artifactService: new ForwardingArtifactService(toolContext),
+      sessionService: new InMemorySessionService(),
+      memoryService: new InMemoryMemoryService(),
+      credentialService: toolContext.invocationContext.credentialService
+    });
+    const session = await runner.sessionService.createSession({
+      appName: this.agent.name,
+      userId: "tmp_user",
+      state: toolContext.state.toRecord()
+    });
+    let lastEvent;
+    for await (const event of runner.runAsync({
+      userId: session.userId,
+      sessionId: session.id,
+      newMessage: content
+    })) {
+      if (event.actions.stateDelta) {
+        toolContext.state.update(event.actions.stateDelta);
+      }
+      lastEvent = event;
+    }
+    if (!((_b = (_a = lastEvent == null ? void 0 : lastEvent.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.length)) {
+      return "";
+    }
+    const hasOutputSchema = this.agent instanceof LlmAgent && this.agent.outputSchema;
+    const mergetText = lastEvent.content.parts.map((part) => part.text).filter((text) => text).join("\n");
+    return hasOutputSchema ? JSON.parse(mergetText) : mergetText;
+  }
+}
+export {
+  AgentTool
+};

package/dist/esm/tools/base_tool.js

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { getGoogleLlmVariant } from "../utils/variant_utils.js";
+class BaseTool {
+  /**
+   * Base constructor for a tool.
+   *
+   * @param params The parameters for `BaseTool`.
+   */
+  constructor(params) {
+    var _a;
+    this.name = params.name;
+    this.description = params.description;
+    this.isLongRunning = (_a = params.isLongRunning) != null ? _a : false;
+  }
+  /**
+   * Gets the OpenAPI specification of this tool in the form of a
+   * FunctionDeclaration.
+   *
+   * NOTE
+   * - Required if subclass uses the default implementation of
+   *   `processLlmRequest` to add function declaration to LLM request.
+   * - Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
+   *   Gemini.
+   *
+   * @return The FunctionDeclaration of this tool, or undefined if it doesn't
+   *     need to be added to LlmRequest.config.
+   */
+  _getDeclaration() {
+    return void 0;
+  }
+  /**
+   * Processes the outgoing LLM request for this tool.
+   *
+   * Use cases:
+   * - Most common use case is adding this tool to the LLM request.
+   * - Some tools may just preprocess the LLM request before it's sent out.
+   *
+   * @param request The request to process the LLM request.
+   */
+  async processLlmRequest({ toolContext, llmRequest }) {
+    const functionDeclaration = this._getDeclaration();
+    if (!functionDeclaration) {
+      return;
+    }
+    llmRequest.toolsDict[this.name] = this;
+    const tool = findToolWithFunctionDeclarations(llmRequest);
+    if (tool) {
+      if (!tool.functionDeclarations) {
+        tool.functionDeclarations = [];
+      }
+      tool.functionDeclarations.push(functionDeclaration);
+    } else {
+      llmRequest.config = llmRequest.config || {};
+      llmRequest.config.tools = llmRequest.config.tools || [];
+      llmRequest.config.tools.push({
+        functionDeclarations: [functionDeclaration]
+      });
+    }
+  }
+  /**
+   * The Google API LLM variant to use.
+   */
+  get apiVariant() {
+    return getGoogleLlmVariant();
+  }
+}
+function findToolWithFunctionDeclarations(llmRequest) {
+  var _a;
+  return (((_a = llmRequest.config) == null ? void 0 : _a.tools) || []).find((tool) => "functionDeclarations" in tool);
+}
+export {
+  BaseTool
+};

package/dist/esm/tools/base_toolset.js

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class BaseToolset {
+  constructor(toolFilter) {
+    this.toolFilter = toolFilter;
+  }
+  /**
+   * Returns whether the tool should be exposed to LLM.
+   *
+   * @param tool The tool to check.
+   * @param context Context used to filter tools available to the agent.
+   * @return Whether the tool should be exposed to LLM.
+   */
+  isToolSelected(tool, context) {
+    if (!this.toolFilter) {
+      return true;
+    }
+    if (typeof this.toolFilter === "function") {
+      return this.toolFilter(tool, context);
+    }
+    if (Array.isArray(this.toolFilter)) {
+      return this.toolFilter.includes(tool.name);
+    }
+    return false;
+  }
+  /**
+   * Processes the outgoing LLM request for this toolset. This method will be
+   * called before each tool processes the llm request.
+   *
+   * Use cases:
+   * - Instead of let each tool process the llm request, we can let the toolset
+   *   process the llm request. e.g. ComputerUseToolset can add computer use
+   *   tool to the llm request.
+   *
+   * @param toolContext The context of the tool.
+   * @param llmRequest The outgoing LLM request, mutable this method.
+   */
+  async processLlmRequest(toolContext, llmRequest) {
+  }
+}
+export {
+  BaseToolset
+};

package/dist/esm/tools/forwarding_artifact_service.js

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class ForwardingArtifactService {
+  constructor(toolContext) {
+    this.toolContext = toolContext;
+    this.invocationContext = toolContext.invocationContext;
+  }
+  // TODO - b/425992518: Remove unnecessary parameters. We should rethink the
+  // abstraction layer to make it more clear.
+  async saveArtifact(request) {
+    return this.toolContext.saveArtifact(request.filename, request.artifact);
+  }
+  async loadArtifact(request) {
+    return this.toolContext.loadArtifact(request.filename, request.version);
+  }
+  async listArtifactKeys(request) {
+    return this.toolContext.listArtifacts();
+  }
+  async deleteArtifact(request) {
+    if (!this.toolContext.invocationContext.artifactService) {
+      throw new Error("Artifact service is not initialized.");
+    }
+    return this.toolContext.invocationContext.artifactService.deleteArtifact(
+      request
+    );
+  }
+  async listVersions(request) {
+    if (!this.toolContext.invocationContext.artifactService) {
+      throw new Error("Artifact service is not initialized.");
+    }
+    return this.toolContext.invocationContext.artifactService.listVersions(
+      request
+    );
+  }
+}
+export {
+  ForwardingArtifactService
+};

package/dist/esm/tools/function_tool.js

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Type } from "@google/genai";
+import { ZodObject } from "zod";
+import { isZodObject, zodObjectToSchema } from "../utils/simple_zod_to_json.js";
+import { BaseTool } from "./base_tool.js";
+function toSchema(parameters) {
+  if (parameters === void 0) {
+    return { type: Type.OBJECT, properties: {} };
+  }
+  if (isZodObject(parameters)) {
+    return zodObjectToSchema(parameters);
+  }
+  return parameters;
+}
+class FunctionTool extends BaseTool {
+  /**
+   * The constructor acts as the user-friendly factory.
+   * @param options The configuration for the tool.
+   */
+  constructor(options) {
+    var _a;
+    const name = (_a = options.name) != null ? _a : options.execute.name;
+    if (!name) {
+      throw new Error(
+        "Tool name cannot be empty. Either name the `execute` function or provide a `name`."
+      );
+    }
+    super({
+      name,
+      description: options.description,
+      isLongRunning: options.isLongRunning
+    });
+    this.execute = options.execute;
+    this.parameters = options.parameters;
+  }
+  /**
+   * Provide a schema for the function.
+   */
+  _getDeclaration() {
+    return {
+      name: this.name,
+      description: this.description,
+      parameters: toSchema(this.parameters)
+    };
+  }
+  /**
+   * Logic for running the tool.
+   */
+  async runAsync(req) {
+    try {
+      let validatedArgs = req.args;
+      if (this.parameters instanceof ZodObject) {
+        validatedArgs = this.parameters.parse(req.args);
+      }
+      return await this.execute(
+        validatedArgs,
+        req.toolContext
+      );
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`Error in tool '${this.name}': ${errorMessage}`);
+    }
+  }
+}
+export {
+  FunctionTool
+};

package/dist/esm/tools/google_search_tool.js

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isGemini1Model, isGeminiModel } from "../utils/model_name.js";
+import { BaseTool } from "./base_tool.js";
+class GoogleSearchTool extends BaseTool {
+  constructor() {
+    super({ name: "google_search", description: "Google Search Tool" });
+  }
+  runAsync(request) {
+    return Promise.resolve();
+  }
+  async processLlmRequest({ toolContext, llmRequest }) {
+    if (!llmRequest.model) {
+      return;
+    }
+    llmRequest.config = llmRequest.config || {};
+    llmRequest.config.tools = llmRequest.config.tools || [];
+    if (isGemini1Model(llmRequest.model)) {
+      if (llmRequest.config.tools.length > 0) {
+        throw new Error(
+          "Google search tool can not be used with other tools in Gemini 1.x."
+        );
+      }
+      llmRequest.config.tools.push({
+        googleSearchRetrieval: {}
+      });
+      return;
+    }
+    if (isGeminiModel(llmRequest.model)) {
+      llmRequest.config.tools.push({
+        googleSearch: {}
+      });
+      return;
+    }
+    throw new Error(
+      `Google search tool is not supported for model ${llmRequest.model}`
+    );
+  }
+}
+const GOOGLE_SEARCH = new GoogleSearchTool();
+export {
+  GOOGLE_SEARCH
+};

package/dist/esm/tools/long_running_tool.js

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionTool } from "./function_tool.js";
+const LONG_RUNNING_INSTRUCTION = `
+
+NOTE: This is a long-running operation. Do not call this tool again if it has already returned some intermediate or pending status.`;
+class LongRunningFunctionTool extends FunctionTool {
+  /**
+   * The constructor acts as the user-friendly factory.
+   * @param options The configuration for the tool.
+   */
+  constructor(options) {
+    super({ ...options, isLongRunning: true });
+  }
+  /**
+   * Provide a schema for the function.
+   */
+  _getDeclaration() {
+    const declaration = super._getDeclaration();
+    if (declaration.description) {
+      declaration.description += LONG_RUNNING_INSTRUCTION;
+    } else {
+      declaration.description = LONG_RUNNING_INSTRUCTION.trimStart();
+    }
+    return declaration;
+  }
+}
+export {
+  LongRunningFunctionTool
+};

package/dist/esm/tools/mcp/mcp_session_manager.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+class MCPSessionManager {
+  constructor(connectionParams) {
+    this.connectionParams = connectionParams;
+  }
+  async createSession() {
+    const client = new Client({ name: "MCPClient", version: "1.0.0" });
+    switch (this.connectionParams.type) {
+      case "StdioConnectionParams":
+        await client.connect(
+          new StdioClientTransport(this.connectionParams.serverParams)
+        );
+        break;
+      case "StreamableHTTPConnectionParams":
+        await client.connect(new StreamableHTTPClientTransport(
+          new URL(this.connectionParams.url)
+        ));
+        break;
+      default:
+        const _exhaustiveCheck = this.connectionParams;
+        break;
+    }
+    return client;
+  }
+}
+export {
+  MCPSessionManager
+};

package/dist/esm/tools/mcp/mcp_tool.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { toGeminiSchema } from "../../utils/gemini_schema_util.js";
+import { BaseTool } from "../base_tool.js";
+class MCPTool extends BaseTool {
+  constructor(mcpTool, mcpSessionManager) {
+    super({ name: mcpTool.name, description: mcpTool.description || "" });
+    this.mcpTool = mcpTool;
+    this.mcpSessionManager = mcpSessionManager;
+  }
+  _getDeclaration() {
+    let declaration;
+    declaration = {
+      name: this.mcpTool.name,
+      description: this.mcpTool.description,
+      parameters: toGeminiSchema(this.mcpTool.inputSchema),
+      // TODO: need revisit, refer to this
+      // https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result
+      response: toGeminiSchema(this.mcpTool.outputSchema)
+    };
+    return declaration;
+  }
+  async runAsync(request) {
+    const session = await this.mcpSessionManager.createSession();
+    const callRequest = {};
+    callRequest.params = { name: this.mcpTool.name, arguments: request.args };
+    return await session.callTool(callRequest.params);
+  }
+}
+export {
+  MCPTool
+};

package/dist/esm/tools/mcp/mcp_toolset.js

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from "../../utils/logger.js";
+import { BaseToolset } from "../base_toolset.js";
+import { MCPSessionManager } from "./mcp_session_manager.js";
+import { MCPTool } from "./mcp_tool.js";
+class MCPToolset extends BaseToolset {
+  constructor(connectionParams, toolFilter = []) {
+    super(toolFilter);
+    this.mcpSessionManager = new MCPSessionManager(connectionParams);
+  }
+  async getTools(context) {
+    const session = await this.mcpSessionManager.createSession();
+    const listResult = await session.listTools();
+    logger.debug(`number of tools: ${listResult.tools.length}`);
+    for (const tool of listResult.tools) {
+      logger.debug(`tool: ${tool.name}`);
+    }
+    return listResult.tools.map(
+      (tool) => new MCPTool(tool, this.mcpSessionManager)
+    );
+  }
+  async close() {
+  }
+}
+export {
+  MCPToolset
+};

package/dist/esm/tools/tool_confirmation.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class ToolConfirmation {
+  constructor({
+    hint,
+    confirmed,
+    payload
+  }) {
+    this.hint = hint != null ? hint : "";
+    this.confirmed = confirmed;
+    this.payload = payload;
+  }
+}
+export {
+  ToolConfirmation
+};

package/dist/esm/tools/tool_context.js

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CallbackContext } from "../agents/callback_context.js";
+import { AuthHandler } from "../auth/auth_handler.js";
+import { ToolConfirmation } from "../tools/tool_confirmation.js";
+class ToolContext extends CallbackContext {
+  /**
+   * @param params.invocationContext The invocation context of the tool.
+   * @param params.eventActions The event actions of the current tool call.
+   * @param params.functionCallId The function call id of the current tool call.
+   *     This id was returned in the function call event from LLM to identify a
+   *     function call. If LLM didn't return this id, ADK will assign one to it.
+   *     This id is used to map function call response to the original function
+   *     call.
+   * @param params.toolConfirmation The tool confirmation of the current tool
+   *     call.
+   */
+  constructor({
+    invocationContext,
+    eventActions,
+    functionCallId,
+    toolConfirmation
+  }) {
+    super({ invocationContext, eventActions });
+    this.functionCallId = functionCallId;
+    this.toolConfirmation = toolConfirmation;
+  }
+  get actions() {
+    return this.eventActions;
+  }
+  requestCredential(authConfig) {
+    if (!this.functionCallId) {
+      throw new Error("functionCallId is not set.");
+    }
+    const authHandler = new AuthHandler(authConfig);
+    this.eventActions.requestedAuthConfigs[this.functionCallId] = authHandler.generateAuthRequest();
+  }
+  /**
+   * Gets the auth credential for the given auth config.
+   *
+   * @param authConfig The auth config to get the auth credential for.
+   * @return The auth credential for the given auth config.
+   */
+  getAuthResponse(authConfig) {
+    const authHandler = new AuthHandler(authConfig);
+    return authHandler.getAuthResponse(this.state);
+  }
+  /**
+   * Lists the filenames of the artifacts attached to the current session.
+   *
+   * @return A promise that resolves to a list of artifact filenames.
+   */
+  listArtifacts() {
+    if (!this.invocationContext.artifactService) {
+      throw new Error("Artifact service is not initialized.");
+    }
+    return this.invocationContext.artifactService.listArtifactKeys({
+      appName: this.invocationContext.session.appName,
+      userId: this.invocationContext.session.userId,
+      sessionId: this.invocationContext.session.id
+    });
+  }
+  /**
+   * Searches the memory of the current user.
+   *
+   * @param query The query to search memory for.
+   * @return A promise that resolves to SearchMemoryResponse containing the
+   *     matching memories.
+   */
+  searchMemory(query) {
+    if (!this.invocationContext.memoryService) {
+      throw new Error("Memory service is not initialized.");
+    }
+    return this.invocationContext.memoryService.searchMemory({
+      appName: this.invocationContext.session.appName,
+      userId: this.invocationContext.session.userId,
+      query
+    });
+  }
+  /**
+   * Requests confirmation for the current tool call.
+   */
+  requestConfirmation({ hint, payload }) {
+    if (!this.functionCallId) {
+      throw new Error("functionCallId is not set.");
+    }
+    this.eventActions.requestedToolConfirmations[this.functionCallId] = new ToolConfirmation({
+      hint,
+      confirmed: false,
+      payload
+    });
+  }
+}
+export {
+  ToolContext
+};

package/dist/esm/utils/deep_clone.js

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function deepClone(obj) {
+  if (obj === void 0) {
+    return void 0;
+  }
+  return JSON.parse(JSON.stringify(obj));
+}
+export {
+  deepClone
+};