@google/adk 2.1.0 → 2.2.1

package/dist/esm/utils/gemini_schema_util.js

@@ -8,6 +8,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Type } from "@google/genai";
+import { toSnakeCaseName } from "./case_utils.js";
 function toGeminiType(mcpType) {
   if (!mcpType) return Type.TYPE_UNSPECIFIED;
   switch (mcpType.toLowerCase()) {
@@ -48,10 +49,18 @@ function toGeminiSchema(mcpSchema) {
     let isNullable = false;
     let nonNullTypes;
     if (Array.isArray(sourceType)) {
-      nonNullTypes = sourceType.filter(
+      const fromAnyOf = Boolean(mcp.anyOf);
+      const branches = sourceType.map(
+        (branch) => {
+          if (typeof branch !== "boolean") return branch;
+          return fromAnyOf ? { type: "object" } : "object";
+        }
+      );
+      mcp = fromAnyOf ? { ...mcp, anyOf: branches } : { ...mcp, type: branches };
+      nonNullTypes = branches.filter(
         (t) => getTypeFromArrayItem(t) !== "null"
       );
-      isNullable = sourceType.some(
+      isNullable = branches.some(
         (t) => getTypeFromArrayItem(t) === "null"
       );
       if (nonNullTypes.length === 1) {
@@ -108,7 +117,7 @@ function toGeminiSchema(mcpSchema) {
       geminiSchema.description = mcp.description;
     }
     if (mcp.enum) {
-      geminiSchema.enum = mcp.enum.map(String);
+      geminiSchema.enum = mcp.enum.filter((v) => v != null).map(String);
     }
     if (isNullable && mcp.type !== "null") {
       geminiSchema.nullable = true;
@@ -136,6 +145,96 @@ function toGeminiSchema(mcpSchema) {
   return recursiveConvert(mcpSchema);
 }
 __name(toGeminiSchema, "toGeminiSchema");
+const GEMINI_SCHEMA_FIELDS = /* @__PURE__ */ new Set([
+  "anyOf",
+  "default",
+  "description",
+  "enum",
+  "example",
+  "format",
+  "items",
+  "maxItems",
+  "maxLength",
+  "maxProperties",
+  "maximum",
+  "minItems",
+  "minLength",
+  "minProperties",
+  "minimum",
+  "nullable",
+  "pattern",
+  "properties",
+  "propertyOrdering",
+  "required",
+  "title",
+  "type"
+]);
+const GEMINI_REJECTED_SCHEMA_FIELDS = /* @__PURE__ */ new Set([
+  "title",
+  "default",
+  "format"
+]);
+const EMPTY_OBJECT_PLACEHOLDER = "dummy_DO_NOT_GENERATE";
+function toGeminiSchemaField(key) {
+  return toSnakeCaseName(key).replace(
+    /_([a-z0-9])/g,
+    (_match, letter) => letter.toUpperCase()
+  );
+}
+__name(toGeminiSchemaField, "toGeminiSchemaField");
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__name(isPlainObject, "isPlainObject");
+function convertSchemaField(field, value) {
+  if (field === "type") {
+    return toGeminiType(typeof value === "string" ? value : void 0);
+  }
+  if (field === "properties" && isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([name, property]) => [
+        name,
+        openApiSchemaToGeminiSchema(property)
+      ])
+    );
+  }
+  if (field === "items" && isPlainObject(value)) {
+    return openApiSchemaToGeminiSchema(value);
+  }
+  if (field === "anyOf" && Array.isArray(value)) {
+    return value.map((item) => openApiSchemaToGeminiSchema(item));
+  }
+  return value;
+}
+__name(convertSchemaField, "convertSchemaField");
+function openApiSchemaToGeminiSchema(openApiSchema) {
+  if (openApiSchema === void 0 || openApiSchema === null) {
+    return void 0;
+  }
+  if (!isPlainObject(openApiSchema)) {
+    throw new TypeError("openapi_schema must be a dictionary");
+  }
+  const source = { ...openApiSchema };
+  if (!source["type"]) {
+    source["type"] = "object";
+  }
+  const properties = source["properties"];
+  const hasProperties = isPlainObject(properties) && Object.keys(properties).length > 0;
+  if (source["type"] === "object" && !hasProperties) {
+    source["properties"] = { [EMPTY_OBJECT_PLACEHOLDER]: { type: "string" } };
+  }
+  const converted = {};
+  for (const [key, value] of Object.entries(source)) {
+    const field = toGeminiSchemaField(key);
+    if (!GEMINI_SCHEMA_FIELDS.has(field) || GEMINI_REJECTED_SCHEMA_FIELDS.has(field)) {
+      continue;
+    }
+    converted[field] = convertSchemaField(field, value);
+  }
+  return converted;
+}
+__name(openApiSchemaToGeminiSchema, "openApiSchemaToGeminiSchema");
 export {
+  openApiSchemaToGeminiSchema,
   toGeminiSchema
 };

package/dist/esm/utils/hash_utils.js

@@ -0,0 +1,45 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const FNV_OFFSET_BASIS = 2166136261;
+const FNV_PRIME = 16777619;
+function stableStringify(value) {
+  var _a;
+  return (_a = JSON.stringify(sortKeysDeep(value))) != null ? _a : "undefined";
+}
+__name(stableStringify, "stableStringify");
+function stableHash(value) {
+  const text = stableStringify(value);
+  let hash = FNV_OFFSET_BASIS;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return (hash >>> 0).toString(16);
+}
+__name(stableHash, "stableHash");
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortKeysDeep);
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  const source = value;
+  const sorted = {};
+  for (const key of Object.keys(source).sort()) {
+    sorted[key] = sortKeysDeep(source[key]);
+  }
+  return sorted;
+}
+__name(sortKeysDeep, "sortKeysDeep");
+export {
+  stableHash,
+  stableStringify
+};

package/dist/esm/utils/live_connection_utils.js

@@ -7,7 +7,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { isGemini3xFlashLive } from "./model_name.js";
+import { isGemini3xLive } from "./model_name.js";
 const _LiveResponseAggregator = class _LiveResponseAggregator {
   constructor(modelVersion) {
     this.modelVersion = modelVersion;
@@ -69,18 +69,19 @@ const _LiveResponseAggregator = class _LiveResponseAggregator {
         yield llmResponse;
       }
       if (serverContent.inputTranscription) {
-        if (serverContent.inputTranscription.text) {
-          this.inputTranscriptionText += serverContent.inputTranscription.text;
+        const isGemini3x = isGemini3xLive(this.modelVersion);
+        const { text, finished } = serverContent.inputTranscription;
+        if (text) {
+          if (!isGemini3x) {
+            this.inputTranscriptionText += text;
+          }
           yield {
-            inputTranscription: {
-              text: serverContent.inputTranscription.text,
-              finished: false
-            },
-            partial: true,
+            inputTranscription: { text, finished: isGemini3x },
+            partial: !isGemini3x,
             ...this.modelVersion ? { modelVersion: this.modelVersion } : {}
           };
         }
-        if (serverContent.inputTranscription.finished) {
+        if (finished && !isGemini3x) {
           yield {
             inputTranscription: {
               text: this.inputTranscriptionText,
@@ -198,7 +199,7 @@ const _LiveResponseAggregator = class _LiveResponseAggregator {
           }))
         );
       }
-      const isGemini3x = isGemini3xFlashLive(this.modelVersion);
+      const isGemini3x = isGemini3xLive(this.modelVersion);
       if (isGemini3x && this.toolCallParts.length > 0) {
         yield {
           content: { role: "model", parts: this.toolCallParts },

package/dist/esm/utils/model_name.js

@@ -53,12 +53,23 @@ function isGemini2OrAbove(modelString) {
   return parsedVersion.valid && parsedVersion.major >= 2;
 }
 __name(isGemini2OrAbove, "isGemini2OrAbove");
-function isGemini3xFlashLive(modelString) {
+function isGemini3xLive(modelString) {
   if (!modelString) {
     return false;
   }
   const modelName = extractModelName(modelString);
-  return modelName.startsWith("gemini-3.") && modelName.includes("-flash-live");
+  return modelName.startsWith("gemini-3.") && modelName.includes("-live") && !isGemini35LiveTranslate(modelString);
+}
+__name(isGemini3xLive, "isGemini3xLive");
+function isGemini35LiveTranslate(modelString) {
+  if (!modelString) {
+    return false;
+  }
+  return extractModelName(modelString).startsWith("gemini-3.5-live-translate");
+}
+__name(isGemini35LiveTranslate, "isGemini35LiveTranslate");
+function isGemini3xFlashLive(modelString) {
+  return isGemini3xLive(modelString);
 }
 __name(isGemini3xFlashLive, "isGemini3xFlashLive");
 function isGeminiModelIdCheckDisabled() {
@@ -69,7 +80,9 @@ export {
   extractModelName,
   isGemini1Model,
   isGemini2OrAbove,
+  isGemini35LiveTranslate,
   isGemini3xFlashLive,
+  isGemini3xLive,
   isGeminiModel,
   isGeminiModelIdCheckDisabled
 };

package/dist/esm/utils/simple_zod_to_json.js

@@ -86,6 +86,11 @@ function zodObjectToSchema(schema) {
   if (isZodV3Schema(schema)) {
     return toJSONSchemaV3(schema, {
       target: "openApi3",
+      // The genai `Schema` type has no `$ref`, so a pointer back at an earlier
+      // occurrence of a reused sub-schema reaches the model as an untyped
+      // parameter. Inline every occurrence instead. A cycle has no finite
+      // inlining and degrades to an unconstrained schema.
+      $refStrategy: "none",
       emailStrategy: "format:email",
       postProcess: /* @__PURE__ */ __name((jsonSchema) => {
         var _a, _b, _c, _d, _e, _f, _g;

package/dist/esm/version.js

@@ -5,7 +5,7 @@ const require = topLevelCreateRequire(import.meta.url);
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-const version = "2.1.0";
+const version = "2.2.1";
 export {
   version
 };

package/dist/types/agents/llm_agent.d.ts

@@ -16,6 +16,7 @@ import { Example } from '../examples/example.js';
 import { BaseLlm } from '../models/base_llm.js';
 import { LlmRequest } from '../models/llm_request.js';
 import { LlmResponse } from '../models/llm_response.js';
+import type { BasePlanner } from '../planners/base_planner.js';
 import { BaseTool } from '../tools/base_tool.js';
 import { BaseToolset } from '../tools/base_toolset.js';
 import { Context } from './context.js';
@@ -146,7 +147,9 @@ export interface LlmAgentConfig extends BaseAgentConfig {
      * Three fields are rejected by the constructor, because the agent owns them:
      * `tools` (set them through `tools`), `systemInstruction` (through
      * `instruction`) and `responseSchema` (through `outputSchema`). Every other
-     * field is forwarded to the model as given — `thinkingConfig` included.
+     * field is forwarded to the model as given. That includes `thinkingConfig`,
+     * unless `planner` is a `BuiltInPlanner` with its own `thinkingConfig`: the
+     * planner's `thinkingConfig` then takes precedence.
      *
      * For example: use this config to adjust model temperature, configure safety
      * settings, etc.
@@ -226,6 +229,13 @@ export interface LlmAgentConfig extends BaseAgentConfig {
      * Instructs the agent to make a plan and execute it step by step.
      */
     codeExecutor?: BaseCodeExecutor;
+    /**
+     * Instructs the agent to make a plan and execute it step by step.
+     *
+     * NOTE: to use the model's built-in thinking features, set `thinkingConfig`
+     * on a `BuiltInPlanner`.
+     */
+    planner?: BasePlanner;
 }
 /**
  * A unique symbol to identify ADK agent classes.
@@ -288,6 +298,7 @@ export declare class LlmAgent extends BaseAgent<LlmAgentConfig> {
     requestProcessors: BaseLlmRequestProcessor[];
     responseProcessors: BaseLlmResponseProcessor[];
     codeExecutor?: BaseCodeExecutor;
+    planner?: BasePlanner;
     constructor(config: LlmAgentConfig);
     /**
      * The resolved BaseLlm instance.

package/dist/types/agents/processors/nl_planning_processor.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { LlmRequest } from '../../models/llm_request.js';
+import { LlmResponse } from '../../models/llm_response.js';
+import { InvocationContext } from '../invocation_context.js';
+import { BaseLlmRequestProcessor, BaseLlmResponseProcessor } from './base_llm_processor.js';
+/**
+ * Prepares the LLM request for the agent's planner.
+ *
+ * Applies a `BuiltInPlanner`'s thinking config, appends the planner's
+ * planning instruction, and clears the `thought` flag on every request part
+ * so that earlier planning output goes back to the model as plain text.
+ */
+export declare class NlPlanningRequestProcessor extends BaseLlmRequestProcessor {
+    runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+}
+/**
+ * Replaces the LLM response parts with the planner's processed parts.
+ *
+ * Partial responses are processed too.
+ */
+export declare class NlPlanningResponseProcessor extends BaseLlmResponseProcessor {
+    runAsync(invocationContext: InvocationContext, llmResponse: LlmResponse): AsyncGenerator<Event, void, void>;
+}
+export declare const NL_PLANNING_REQUEST_PROCESSOR: NlPlanningRequestProcessor;
+export declare const NL_PLANNING_RESPONSE_PROCESSOR: NlPlanningResponseProcessor;

package/dist/types/auth/auth_credential.d.ts

@@ -247,3 +247,12 @@ export interface AuthCredential {
     serviceAccount?: ServiceAccount;
     oauth2?: OAuth2Auth;
 }
+/**
+ * Reports whether `value` is an {@link AuthCredential}.
+ *
+ * Use it on a value that crossed a boundary where the type was lost, such as a
+ * credential read back out of session state. The check is a shallow one on
+ * `authType`, because the payload members are all optional and the type they
+ * carry depends on the scheme.
+ */
+export declare function isAuthCredential(value: unknown): value is AuthCredential;

package/dist/types/common.d.ts

@@ -39,7 +39,7 @@ export { InMemoryArtifactService } from './artifacts/in_memory_artifact_service.
 export { ScopedArtifactService } from './artifacts/scoped_artifact_service.js';
 export { isSessionArtifactService } from './artifacts/session_artifact_service.js';
 export type { SessionArtifactService, SessionLoadArtifactRequest, SessionSaveArtifactRequest, } from './artifacts/session_artifact_service.js';
-export { AuthCredentialTypes } from './auth/auth_credential.js';
+export { AuthCredentialTypes, isAuthCredential } from './auth/auth_credential.js';
 export type { AuthCredential, HttpAuth, HttpCredentials, OAuth2Auth, ServiceAccount, ServiceAccountCredential, } from './auth/auth_credential.js';
 export { AuthHandler } from './auth/auth_handler.js';
 export { AUTH_PREPROCESSOR, AuthPreprocessor } from './auth/auth_preprocessor.js';
@@ -87,10 +87,12 @@ export { createEvent, generateClientFunctionCallId, getFunctionCalls, getFunctio
 export type { CreateEventParams, Event, NodeInfo, Route, RouteKey, } from './events/event.js';
 export { createEventActions } from './events/event_actions.js';
 export type { EventActions } from './events/event_actions.js';
+export { INTERNAL_METADATA_PREFIX, RESTORED_EVENT_KEY, markRestored, publicEvent, publicMetadata, publicSession, } from './events/internal_metadata.js';
 export { EventType, toStructuredEvents } from './events/structured_events.js';
 export type { ActivityEvent, CallCodeEvent, CodeResultEvent, ContentEvent, ErrorEvent, FinishedEvent, StructuredEvent, ThoughtEvent, ToolCallEvent, ToolConfirmationEvent, ToolResultEvent, } from './events/structured_events.js';
 export { BaseExampleProvider, isBaseExampleProvider, } from './examples/base_example_provider.js';
-export type { Example } from './examples/example.js';
+export { VertexAiExampleStore } from './examples/example.js';
+export type { Example, ExampleStoreApiClient, SearchExamplesRequest, SearchExamplesResponse, SearchExamplesResult, StoredContentsExample, } from './examples/example.js';
 export type { BaseMemoryService, SearchMemoryRequest, SearchMemoryResponse, } from './memory/base_memory_service.js';
 export { InMemoryMemoryService } from './memory/in_memory_memory_service.js';
 export type { MemoryEntry } from './memory/memory_entry.js';
@@ -108,6 +110,9 @@ export { LLMRegistry } from './models/registry.js';
 export type { BaseLlmType } from './models/registry.js';
 export { RoutedLlm } from './models/routed_llm.js';
 export type { LlmRouter } from './models/routed_llm.js';
+export { BasePlanner, isBasePlanner } from './planners/base_planner.js';
+export { BuiltInPlanner, isBuiltInPlanner } from './planners/built_in_planner.js';
+export { PlanReActPlanner } from './planners/plan_re_act_planner.js';
 export { GLOBAL_SCOPE_KEY, REFLECT_AND_RETRY_RESPONSE_TYPE, ScopedFailureTracker, TrackingScope, resolveScopeKey, type PerItemFailuresCounter, type ToolFailureResponse, } from './plugins/_reflect_retry_utils.js';
 export { BasePlugin, ContextCompactionTrigger } from './plugins/base_plugin.js';
 export { GlobalInstructionPlugin } from './plugins/global_instruction_plugin.js';
@@ -117,6 +122,8 @@ export { ADK_HANDLE_MODEL_ERROR_TOOL_NAME, RESERVED_TOOL_CALL_ERROR_TYPE, Reflec
 export { ReflectAndRetryToolPlugin, type ReflectAndRetryToolPluginOptions, } from './plugins/reflect_retry_tool_plugin.js';
 export { InMemoryPolicyEngine, PolicyOutcome, SecurityPlugin, getAskUserConfirmationFunctionCalls, } from './plugins/security_plugin.js';
 export type { BasePolicyEngine, PolicyCheckResult, ToolCallPolicyContext, } from './plugins/security_plugin.js';
+export { ToolCallIntegrityError, ToolCallIntegrityPlugin, } from './plugins/tool_call_integrity_plugin.js';
+export type { ToolCallIntegrityPluginOptions } from './plugins/tool_call_integrity_plugin.js';
 export { InMemoryRunner } from './runner/in_memory_runner.js';
 export { Runner, determineAgentForResumption, findEventByLastFunctionResponseId, isRoutableLlmAgent, isRunner, } from './runner/runner.js';
 export type { RunnerConfig } from './runner/runner.js';
@@ -155,15 +162,23 @@ export { LlamaIndexRetrieval } from './tools/retrieval/llama_index_retrieval.js'
 export type { LlamaIndexNode, LlamaIndexNodeWithScore, LlamaIndexRetrievalParams, LlamaIndexRetriever, } from './tools/retrieval/llama_index_retrieval.js';
 export { IntentMismatchError, ToolConfirmation, isIntentMismatchError, } from './tools/tool_confirmation.js';
 export type { IntentMismatchReason } from './tools/tool_confirmation.js';
+export { CallbackContext, ToolContext } from './tools/tool_context.js';
 export { URL_CONTEXT, UrlContextTool } from './tools/url_context_tool.js';
 export { VertexAiSearchTool } from './tools/vertex_ai_search_tool.js';
 export type { DataStoreParams, SearchEngineParams, VertexAISearchConfig, VertexAISearchDataStoreSpec, VertexAiSearchToolParams, } from './tools/vertex_ai_search_tool.js';
 export { VertexRagRetrievalTool } from './tools/vertex_rag_retrieval_tool.js';
+export { WebMCPTool } from './tools/webmcp/webmcp_tool.js';
+export type { WebMCPToolParams } from './tools/webmcp/webmcp_tool.js';
+export { WebMCPToolset } from './tools/webmcp/webmcp_toolset.js';
+export type { WebMCPToolsetOptions } from './tools/webmcp/webmcp_toolset.js';
+export { getModelContext, isWebMCPSupported, } from './tools/webmcp/webmcp_types.js';
+export type { WebMCPDocument, WebMCPExecuteToolOptions, WebMCPGetToolsOptions, WebMCPModelContext, WebMCPRegisteredTool, WebMCPToolAnnotations, } from './tools/webmcp/webmcp_types.js';
 export { AsyncQueue } from './utils/async_queue.js';
+export { renameReservedKeywords, toSnakeCaseName } from './utils/case_utils.js';
 export { getClientLabels, runWithClientLabel } from './utils/client_labels.js';
-export { LogLevel, getLogger, resetLogger, setLogLevel, setLogger, } from './utils/logger.js';
+export { LogLevel, getLogger, logger, resetLogger, setLogLevel, setLogger, } from './utils/logger.js';
 export type { Logger } from './utils/logger.js';
-export { isGemini2OrAbove, isGemini3xFlashLive } from './utils/model_name.js';
+export { isGemini2OrAbove, isGemini35LiveTranslate, isGemini3xFlashLive, isGemini3xLive, } from './utils/model_name.js';
 export type { SchemaLike } from './utils/schema.js';
 export { zodObjectToSchema } from './utils/simple_zod_to_json.js';
 export { Task } from './utils/task.js';

package/dist/types/events/abort_events.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from './event.js';
+export declare const INVOCATION_ABORTED = "INVOCATION_ABORTED";
+export declare const ABORT_MESSAGE = "Invocation was aborted by client.";
+/**
+ * Returns whether `event` was synthesized to seal an aborted invocation.
+ */
+export declare function isAbortEvent(event: Event): boolean;
+/** Parameters for {@link buildAbortEvents}. */
+export interface BuildAbortEventsParams {
+    /** The session history, in chronological order. */
+    events: Event[];
+    /** The aborted invocation; only its events are considered. */
+    invocationId: string;
+    /** Author of the abort event returned when nothing is dangling. */
+    rootAgentName: string;
+    /**
+     * Branch for calls whose event has no branch, and for the abort event
+     * returned when nothing is dangling.
+     */
+    branch?: string;
+}
+/**
+ * Returns the events that seal an aborted invocation.
+ *
+ * Each dangling function call gets a synthetic error response carrying the
+ * author, branch and isolation scope of the event that issued it, so the
+ * response pairs with its call in the issuing agent's own view. Calls sharing
+ * those three values are grouped into one event. If nothing is dangling, a
+ * single content-less abort event authored by the root agent is returned
+ * instead.
+ *
+ * Long-running calls (including confirmation and credential requests) are
+ * sealed too: the invocation that issued them is gone, so they are not left
+ * pending for a later turn.
+ *
+ * @returns The synthetic events, in the order they should be appended.
+ */
+export declare function buildAbortEvents({ events, invocationId, rootAgentName, branch, }: BuildAbortEventsParams): Event[];

package/dist/types/events/internal_metadata.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * `Event.customMetadata` keys that only ADK code may write.
+ *
+ * Mirrors adk-python's `google.adk.events._internal_metadata`.
+ */
+import type { Session } from '../sessions/session.js';
+import type { Event } from './event.js';
+type Metadata = Record<string, unknown>;
+/**
+ * Prefix of `customMetadata` keys that callers cannot set.
+ *
+ * Keys with this prefix are dropped from the `customMetadata` passed to
+ * `Runner.runAsync`, and from events that are restored into a session or
+ * received from a remote A2A agent. Stored events keep them, but they are
+ * removed from API responses, saved session files and A2A messages.
+ *
+ * The value matches adk-python so a session store shared between the two
+ * treats the same keys as internal.
+ */
+export declare const INTERNAL_METADATA_PREFIX = "__adk_internal_";
+/** Set on events that ADK restored into a session from outside it. */
+export declare const RESTORED_EVENT_KEY = "__adk_internal_restored_event";
+/**
+ * Returns `metadata` without keys that have the internal prefix.
+ *
+ * Use it where callers supply metadata. Dropped keys are logged at debug level,
+ * because a caller set a key it cannot set.
+ *
+ * @param metadata A `customMetadata` value. It is not modified.
+ * @returns A new object without internal keys. A value that is not a plain
+ *     object, such as `undefined`, is returned unchanged.
+ */
+export declare function withoutInternalMetadata<T>(metadata: T): T;
+/**
+ * Returns `metadata` as callers see it, without internal keys.
+ *
+ * Use it where events leave ADK. Removal there is routine, so nothing is
+ * logged.
+ *
+ * @param metadata A `customMetadata` value. It is not modified.
+ * @returns A new object without internal keys, or `undefined` if nothing is
+ *     left. A value that is not a plain object is returned unchanged.
+ */
+export declare function publicMetadata<T>(metadata: T): T | undefined;
+/** Returns only the keys of `metadata` that have the internal prefix. */
+export declare function internalMetadata(metadata: unknown): Metadata;
+/**
+ * Marks an event restored from outside the session, in place.
+ *
+ * Internal metadata carried by the event is removed first, so a caller cannot
+ * supply its own.
+ *
+ * @param event The event about to be appended to a new session.
+ * @returns The same event.
+ */
+export declare function markRestored<T extends Event>(event: T): T;
+/**
+ * Returns the event as callers see it, without internal metadata.
+ *
+ * @param event A stored event. It is not modified.
+ * @returns The same event if it has no internal keys. Otherwise a copy whose
+ *     `customMetadata` drops them, or is `undefined` if nothing else is left.
+ */
+export declare function publicEvent<T extends Event>(event: T): T;
+/**
+ * Returns the session as callers see it, without internal metadata.
+ *
+ * @param session A stored session. It is not modified.
+ * @returns The same session if no event changes. Otherwise a copy whose events
+ *     are passed through {@link publicEvent}.
+ */
+export declare function publicSession<T extends Session>(session: T): T;
+export {};

package/dist/types/examples/base_example_provider.d.ts

@@ -29,8 +29,8 @@ export declare abstract class BaseExampleProvider {
      * Returns a list of examples for a given query.
      *
      * @param query The query to get examples for.
-     * @return A list of Example objects.
+     * @return A promise that resolves to a list of Example objects.
      */
-    abstract getExamples(query: string): Example[];
+    abstract getExamples(query: string): Promise<Example[]>;
 }
 export {};

package/dist/types/examples/example.d.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Content } from '@google/genai';
+import { BaseExampleProvider } from './base_example_provider.js';
 /**
  * A few-shot example.
  */
@@ -17,3 +18,77 @@ export interface Example {
      */
     output: Content[];
 }
+/**
+ * Request payload for searching examples in Vertex AI Example Store.
+ */
+export interface SearchExamplesRequest {
+    storedContentsExampleParameters: {
+        contentSearchKey: {
+            contents: Content[];
+            searchKeyGenerationMethod: {
+                lastEntry: Record<string, never>;
+            };
+        };
+    };
+    topK: number;
+    exampleStore: string;
+}
+/**
+ * A stored example returned inside a {@link SearchExamplesResult}.
+ */
+export interface StoredContentsExample {
+    searchKey?: string;
+    contentsExample?: {
+        expectedContents?: Array<{
+            content?: Content;
+        }>;
+    };
+}
+/**
+ * Single result item returned by {@link ExampleStoreApiClient.searchExamples}.
+ */
+export interface SearchExamplesResult {
+    similarityScore?: number;
+    example?: {
+        storedContentsExample?: StoredContentsExample;
+    };
+}
+/**
+ * Response returned by {@link ExampleStoreApiClient.searchExamples}.
+ */
+export interface SearchExamplesResponse {
+    results?: SearchExamplesResult[];
+}
+/**
+ * API client interface for the Vertex AI Example Store.
+ *
+ * The Python SDK obtains this client from its bundled `vertexai` dependency.
+ * adk-js does not bundle that dependency, so the caller injects a client that
+ * reaches the Vertex AI Example Store API.
+ */
+export interface ExampleStoreApiClient {
+    searchExamples(request: SearchExamplesRequest): Promise<SearchExamplesResponse>;
+}
+/**
+ * Provides examples from a Vertex AI Example Store.
+ */
+export declare class VertexAiExampleStore extends BaseExampleProvider {
+    readonly examplesStoreName: string;
+    private readonly apiClient;
+    /**
+     * Initializes the VertexAiExampleStore.
+     *
+     * @param examplesStoreName The resource name of the vertex example store, in
+     *   the format of
+     *   `projects/{project}/locations/{location}/exampleStores/{example_store}`.
+     * @param apiClient A client that reaches the Vertex AI Example Store API.
+     *   adk-js does not bundle the `vertexai` dependency the Python SDK relies
+     *   on, so the caller supplies this client.
+     */
+    constructor(examplesStoreName: string, apiClient: ExampleStoreApiClient);
+    /**
+     * Retrieves relevant examples from the Vertex AI Example Store for the given
+     * query.
+     */
+    getExamples(query: string): Promise<Example[]>;
+}