@google/adk 1.0.0 → 1.2.0

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

@@ -5,6 +5,15 @@
  */
 import { FunctionDeclaration } from '@google/genai';
 import { FunctionTool, ToolInputParameters, ToolOptions } from './function_tool.js';
+/**
+ * A {@link FunctionTool} for long-running operations whose result is returned
+ * asynchronously.
+ *
+ * The framework invokes the user-provided function and delivers the response
+ * back to the model once it completes, identified by the `function_call_id`.
+ * The model is also instructed not to re-invoke the tool while a call is
+ * already in flight.
+ */
 export declare class LongRunningFunctionTool<TParameters extends ToolInputParameters = undefined> extends FunctionTool<TParameters> {
     /**
      * The constructor acts as the user-friendly factory.
@@ -12,7 +21,8 @@ export declare class LongRunningFunctionTool<TParameters extends ToolInputParame
      */
     constructor(options: ToolOptions<TParameters>);
     /**
-     * Provide a schema for the function.
+     * Returns the function declaration with an appended instruction warning the
+     * model not to re-invoke the tool while it is still running.
      */
     _getDeclaration(): FunctionDeclaration;
 }

package/dist/types/tools/mcp/mcp_session_manager.d.ts

@@ -59,6 +59,9 @@ export type MCPConnectionParams = StdioConnectionParams | StreamableHTTPConnecti
  */
 export declare class MCPSessionManager {
     private readonly connectionParams;
+    private readonly activeSessions;
     constructor(connectionParams: MCPConnectionParams);
     createSession(): Promise<Client>;
+    closeSession(client: Client): Promise<void>;
+    getActiveSessions(): Client[];
 }

package/dist/types/tools/mcp/mcp_tool.d.ts

@@ -20,11 +20,17 @@ import { MCPSessionManager } from './mcp_session_manager.js';
  * invoked, which in turn establishes an MCP session, sends a `callTool`
  * request with the provided arguments, and returns the result from the
  * remote tool.
+ *
+ * The originalName parameter allows the tool to track the native tool name
+ * exposed by the MCP server. This is critical when the toolset applies a
+ * prefix to tool names (e.g., for LLM namespace disambiguation), ensuring
+ * the correct original name is used when executing on the server.
  */
 export declare class MCPTool extends BaseTool {
     private readonly mcpTool;
     private readonly mcpSessionManager;
-    constructor(mcpTool: Tool, mcpSessionManager: MCPSessionManager);
+    private readonly originalName;
+    constructor(mcpTool: Tool, mcpSessionManager: MCPSessionManager, originalName?: string);
     _getDeclaration(): FunctionDeclaration;
     runAsync(request: RunAsyncToolRequest): Promise<unknown>;
 }

package/dist/types/tools/mcp/mcp_toolset.d.ts

@@ -3,6 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { ReadonlyContext } from '../../agents/readonly_context.js';
 import { BaseTool } from '../base_tool.js';
 import { BaseToolset, ToolPredicate } from '../base_toolset.js';
 import { MCPConnectionParams } from './mcp_session_manager.js';
@@ -17,6 +18,11 @@ import { MCPConnectionParams } from './mcp_session_manager.js';
  * The toolset can be configured with a filter to selectively expose a subset
  * of the tools provided by the MCP server.
  *
+ * It can also be configured with a prefix. If provided, all tools discovered
+ * from the MCP server will have their names prefixed with `${prefix}_`. When the
+ * LLM invokes the prefixed tool, this toolset transparently strips the prefix
+ * before sending the request to the underlying MCP server.
+ *
  * Usage:
  *   import { MCPToolset } from '@google/adk';
  *   import { StreamableHTTPConnectionParamsSchema } from '@google/adk';
@@ -33,6 +39,6 @@ import { MCPConnectionParams } from './mcp_session_manager.js';
 export declare class MCPToolset extends BaseToolset {
     private readonly mcpSessionManager;
     constructor(connectionParams: MCPConnectionParams, toolFilter?: ToolPredicate | string[], prefix?: string);
-    getTools(): Promise<BaseTool[]>;
+    getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
     close(): Promise<void>;
 }

package/dist/types/tools/openapi_tool/auth/auth_helpers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { OpenAPIV3 } from 'openapi-types';
+import { AuthCredential } from '../../../auth/auth_credential.js';
+/**
+ * Applies the given credential to the request headers and URL.
+ *
+ * @param url The target URL.
+ * @param headers The request headers.
+ * @param credential The auth credential.
+ * @param authScheme The auth scheme from OpenAPI spec.
+ * @returns The updated URL (if modified by query params).
+ */
+export declare function applyCredential(url: string, headers: Record<string, string>, credential?: AuthCredential, authScheme?: OpenAPIV3.SecuritySchemeObject): string;
+/**
+ * Helper to create a simple API Key auth scheme.
+ */
+export declare function createApiKeyScheme(name: string, inLocation: 'header' | 'query' | 'cookie'): OpenAPIV3.SecuritySchemeObject;
+/**
+ * Helper to create a simple Bearer Token auth scheme.
+ */
+export declare function createBearerScheme(): OpenAPIV3.SecuritySchemeObject;

package/dist/types/tools/openapi_tool/auth/credential_exchangers/auto_auth_credential_exchanger.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from '../../../../auth/auth_credential.js';
+import { AuthScheme } from '../../../../auth/auth_schemes.js';
+import { BaseCredentialExchanger, ExchangeResult } from '../../../../auth/exchanger/base_credential_exchanger.js';
+/**
+ * Automatically selects the appropriate credential exchanger based on the auth scheme.
+ * Ported from Python implementation.
+ */
+export declare class AutoAuthCredentialExchanger implements BaseCredentialExchanger {
+    private exchangers;
+    constructor();
+    exchange(params: {
+        authScheme?: AuthScheme;
+        authCredential: AuthCredential;
+    }): Promise<ExchangeResult>;
+}

package/dist/types/tools/openapi_tool/auth/credential_exchangers/service_account_exchanger.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from '../../../../auth/auth_credential.js';
+import { AuthScheme } from '../../../../auth/auth_schemes.js';
+import { BaseCredentialExchanger, ExchangeResult } from '../../../../auth/exchanger/base_credential_exchanger.js';
+/**
+ * Fetches credentials for Google Service Account.
+ * Ported from Python implementation.
+ */
+export declare class ServiceAccountCredentialExchanger implements BaseCredentialExchanger {
+    exchange(params: {
+        authScheme?: AuthScheme;
+        authCredential: AuthCredential;
+    }): Promise<ExchangeResult>;
+    private exchangeForDefaultCredential;
+    private exchangeForExplicitCredential;
+}

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

@@ -0,0 +1,17 @@
+import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+/**
+ * A built-in tool that allows Gemini 2+ models to retrieve content from URLs
+ * provided in the conversation.
+ *
+ * This tool operates internally within the model and does not require or
+ * perform local code execution.
+ */
+export declare class UrlContextTool extends BaseTool {
+    constructor();
+    runAsync(): Promise<unknown>;
+    processLlmRequest({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+}
+/**
+ * A global instance of {@link UrlContextTool}.
+ */
+export declare const URL_CONTEXT: UrlContextTool;

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

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ReadonlyContext } from '../agents/readonly_context.js';
+import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+export interface VertexAISearchDataStoreSpec {
+    dataStore?: string;
+}
+export interface VertexAISearchConfig {
+    datastore?: string;
+    dataStoreSpecs?: VertexAISearchDataStoreSpec[];
+    engine?: string;
+    filter?: string;
+    maxResults?: number;
+}
+export interface BaseVertexAiSearchToolParams {
+    filter?: string;
+    maxResults?: number;
+    bypassMultiToolsLimit?: boolean;
+}
+export interface DataStoreParams extends BaseVertexAiSearchToolParams {
+    dataStoreId: string;
+    searchEngineId?: never;
+    dataStoreSpecs?: never;
+}
+export interface SearchEngineParams extends BaseVertexAiSearchToolParams {
+    searchEngineId: string;
+    dataStoreId?: never;
+    dataStoreSpecs?: VertexAISearchDataStoreSpec[];
+}
+export type VertexAiSearchToolParams = DataStoreParams | SearchEngineParams;
+/**
+ * A built-in tool using Vertex AI Search.
+ */
+export declare class VertexAiSearchTool extends BaseTool {
+    readonly dataStoreId?: string;
+    readonly dataStoreSpecs?: VertexAISearchDataStoreSpec[];
+    readonly searchEngineId?: string;
+    readonly filter?: string;
+    readonly maxResults?: number;
+    readonly bypassMultiToolsLimit: boolean;
+    constructor(params: VertexAiSearchToolParams);
+    runAsync(): Promise<unknown>;
+    /**
+     * Builds the VertexAISearch configuration.
+     *
+     * Override this method in a subclass to dynamically customize the search
+     * configuration based on the context (e.g., set filter based on session
+     * state).
+     */
+    protected buildVertexAiSearchConfig(_readonlyContext: ReadonlyContext): VertexAISearchConfig;
+    processLlmRequest({ toolContext, llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { VertexRagStore } from '@google/genai';
+import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+/**
+ * A tool that retrieves relevant content from a Vertex AI RAG corpus to ground
+ * model responses.
+ *
+ * This tool operates server-side; it modifies the LLM request config to enable
+ * RAG retrieval via the `retrieval.vertexRagStore` field and does not perform
+ * local code execution.
+ *
+ * **Note:** The Vertex AI RAG Engine only supports one corpus per
+ * `ragResources` array. Create one `VertexRagRetrievalTool` instance per
+ * corpus.
+ *
+ * @example
+ * ```ts
+ * import { VertexRagRetrievalTool } from '@google/adk';
+ * import { VertexRagStore } from '@google/genai';
+ *
+ * const ragTool = new VertexRagRetrievalTool({
+ *   ragResources: [{ragCorpus: 'projects/my-project/locations/us-central1/ragCorpora/my-corpus'}],
+ *   similarityTopK: 5,
+ * });
+ *
+ * const agent = new LlmAgent({ tools: [ragTool], ... });
+ * ```
+ */
+export declare class VertexRagRetrievalTool extends BaseTool {
+    private readonly vertexRagStore;
+    constructor(config: VertexRagStore);
+    /**
+     * This tool is executed server-side by the Vertex AI RAG Engine.
+     * Local execution is not required.
+     */
+    runAsync(): Promise<unknown>;
+    processLlmRequest({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+}

package/dist/types/utils/file_utils.d.ts

@@ -9,3 +9,5 @@ import { File } from '../code_executors/code_execution_utils.js';
  * @param files The files to materialize.
  */
 export declare function materializeFiles(files: File[], dir?: string): Promise<File[]>;
+export declare const EXTENSION_TO_MIME_TYPE: Record<string, string>;
+export declare function guessMimeType(filePath: string): string;

package/dist/types/utils/model_name.d.ts

@@ -32,3 +32,7 @@ export declare function isGemini1Model(modelString: string): boolean;
  * @return true if it's a Gemini 2.x model, false otherwise.
  */
 export declare function isGemini2OrAbove(modelString: string): boolean;
+/**
+ * Returns True when Gemini model-id validation should be bypassed.
+ */
+export declare function isGeminiModelIdCheckDisabled(): boolean;

package/dist/types/utils/partial_copy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Copies a set of keys from one object to another.
+ *
+ * @param source The source object.
+ * @param targetKeys The keys to copy.
+ * @returns A new object with the specified keys copied from source.
+ */
+export declare function partialCopy<TDest extends object>(source: object, targetKeys: (keyof TDest)[]): TDest;

package/dist/types/utils/streaming_utils.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { GenerateContentResponse } from '@google/genai';
+import { GenerateContentResponse, Part } from '@google/genai';
 import { LlmResponse } from '../models/llm_response.js';
 /**
  * Aggregates partial streaming responses.
@@ -17,24 +17,15 @@ export declare class StreamingResponseAggregator {
     private groundingMetadata?;
     private citationMetadata?;
     private response?;
-    private text;
-    private thoughtText;
-    private partsSequence;
-    private currentTextBuffer;
-    private currentTextIsThought?;
     private finishReason?;
-    private currentFcName?;
-    private currentFcArgs;
-    private currentFcId?;
-    private currentThoughtSignature?;
-    private lastThoughtSignature?;
+    private lastThoughtSignature;
+    private sawFunctionCall;
+    private readonly strategy;
     constructor(isProgressiveMode?: boolean);
-    private flushTextBufferToSequence;
-    private getValueFromPartialArg;
-    private setValueByJsonPath;
-    private flushFunctionCallToSequence;
-    private processStreamingFunctionCall;
-    private processFunctionCallPart;
     processResponse(response: GenerateContentResponse): AsyncGenerator<LlmResponse, void, void>;
     close(): LlmResponse | undefined;
 }
+/**
+ * Checks if a response part has no meaningful content (empty text, no tool calls, etc.)
+ */
+export declare function isEmptyContentPart(part: Part): boolean;

package/dist/types/utils/vertex_ai_utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Validates and returns the API key for Express Mode.
+ *
+ * @param project The project id.
+ * @param location The location.
+ * @param expressModeApiKey The API key for Express Mode.
+ * @returns The resolved API key or undefined.
+ */
+export declare function getExpressModeApiKey(project?: string, location?: string, expressModeApiKey?: string): string | undefined;

package/dist/types/version.d.ts

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

package/dist/web/agents/functions.js

@@ -159,6 +159,8 @@ function buildResponseEvent(tool, functionResult, toolContext, invocationContext
   let responseResult;
   if (typeof functionResult !== "object" || functionResult == null) {
     responseResult = { result: functionResult };
+  } else if (Array.isArray(functionResult)) {
+    responseResult = { results: functionResult };
   } else {
     responseResult = functionResult;
   }
@@ -297,6 +299,8 @@ async function handleFunctionCallList({
       functionResponse = { error: functionResponseError };
     } else if (typeof functionResponse !== "object" || functionResponse == null) {
       functionResponse = { result: functionResponse };
+    } else if (Array.isArray(functionResponse)) {
+      functionResponse = { results: functionResponse };
     }
     const functionResponseEvent = createEvent({
       invocationId: invocationContext.invocationId,

package/dist/web/auth/oauth2/oauth2_discovery.js

@@ -123,6 +123,18 @@ class OAuth2DiscoveryManager {
     return void 0;
   }
 }
+function normaliseHostname(raw) {
+  const stripped = raw.replace(/^\[|\]$/g, "");
+  const m = stripped.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+  if (m) {
+    const hi = parseInt(m[1], 16);
+    const lo = parseInt(m[2], 16);
+    return [hi >> 8 & 255, hi & 255, lo >> 8 & 255, lo & 255].join(".");
+  }
+  const mDot = stripped.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  if (mDot) return mDot[1];
+  return raw;
+}
 function validateDiscoveryUrl(urlStr) {
   try {
     const url = new URL(urlStr);
@@ -130,8 +142,8 @@ function validateDiscoveryUrl(urlStr) {
       logger.warn("Unsafe protocol for discovery URL: ".concat(url.protocol));
       return false;
     }
-    const host = url.hostname.toLowerCase();
-    if (host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.startsWith("10.") || host.startsWith("192.168.") || host.startsWith("169.254.")) {
+    const host = normaliseHostname(url.hostname.toLowerCase());
+    if (host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "0.0.0.0" || host.startsWith("10.") || host.startsWith("192.168.") || host.startsWith("169.254.")) {
       logger.warn("Unsafe host for discovery URL: ".concat(host));
       return false;
     }
@@ -143,6 +155,18 @@ function validateDiscoveryUrl(urlStr) {
         return false;
       }
     }
+    const cgnatMatch = host.match(/^100\.(\d+)\./);
+    if (cgnatMatch) {
+      const secondOctet = parseInt(cgnatMatch[1], 10);
+      if (secondOctet >= 64 && secondOctet <= 127) {
+        logger.warn("Unsafe host for discovery URL: ".concat(host));
+        return false;
+      }
+    }
+    if (/^\[(f[cd][0-9a-f]{2}|fe[89ab][0-9a-f]):/i.test(url.hostname)) {
+      logger.warn("Unsafe host for discovery URL: ".concat(url.hostname));
+      return false;
+    }
     return true;
   } catch (e) {
     logger.warn("Failed to parse URL for validation ".concat(urlStr, ": ").concat(e));