@google/adk 1.3.0 → 1.4.0

package/dist/types/models/google_llm.d.ts

@@ -39,20 +39,33 @@ export interface GeminiParams {
      * Headers to merge with internally crafted headers.
      */
     headers?: Record<string, string>;
+    /**
+     * Whether to use the Interactions API for stateful conversations.
+     */
+    useInteractionsApi?: boolean;
 }
+declare const GEMINI_MODEL_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of Gemini.
+ * @param obj The object to check.
+ * @returns True if the object is an instance of Gemini, false otherwise.
+ */
+export declare function isGemini(obj: unknown): obj is Gemini;
 /**
  * Integration for Gemini models.
  */
 export declare class Gemini extends BaseLlm {
+    readonly [GEMINI_MODEL_SYMBOL] = true;
     private readonly apiKey?;
     protected readonly vertexai: boolean;
     private readonly project?;
     private readonly location?;
     private readonly headers?;
+    readonly useInteractionsApi: boolean;
     /**
      * @param params The parameters for creating a Gemini instance.
      */
-    constructor({ model, apiKey, vertexai, project, location, headers, }: GeminiParams);
+    constructor({ model, apiKey, vertexai, project, location, headers, useInteractionsApi, }: GeminiParams);
     /**
      * A list of model name patterns that are supported by this LLM.
      *
@@ -88,3 +101,4 @@ export declare class Gemini extends BaseLlm {
     private preprocessRequest;
 }
 export declare function geminiInitParams({ model, vertexai, project, location, apiKey, }: GeminiParams): GeminiParams;
+export {};

package/dist/types/models/interactions_utils.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content, GenerateContentConfig, GoogleGenAI, Interactions, Part } from '@google/genai';
+import { LlmRequest } from './llm_request.js';
+import { LlmResponse } from './llm_response.js';
+export interface ExtendedInteraction extends Interactions.Interaction {
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface ExtendedInteractionStatusUpdate extends Omit<Interactions.InteractionStatusUpdate, 'error'> {
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface ExtendedFunctionCallStep extends Interactions.FunctionCallStep {
+    signature?: string;
+}
+export interface ExtendedInteractionSSEEvent extends Omit<Interactions.InteractionSSEEvent, 'error' | 'interaction_id' | 'status' | 'event_type'> {
+    event_type?: string;
+    eventType?: string;
+    delta?: {
+        type: string;
+        text?: string;
+        name?: string;
+        id?: string;
+        arguments?: Record<string, unknown>;
+        thought_signature?: string;
+        signature?: string;
+        data?: string;
+        uri?: string;
+        mime_type: string;
+    };
+    status?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+    code?: string;
+    message?: string;
+    interaction_id?: string;
+    interactionId?: string;
+    interaction?: {
+        id: string;
+    };
+    id?: string;
+}
+/**
+ * Extracts the latest turn contents for interactions API.
+ */
+export declare function getLatestUserContents(contents: Content[]): Content[];
+/**
+ * Convert a Content to a list of Steps.
+ */
+export declare function convertContentToSteps(content: Content): Interactions.Step[];
+/**
+ * Convert a Step to a list of Parts.
+ */
+export declare function convertStepToParts(step: Interactions.Step): Part[];
+/**
+ * Convert tools config to interactions format.
+ */
+export declare function convertToolsConfigToInteractionsFormat(config: GenerateContentConfig): Interactions.Tool[];
+/**
+ * Extract the latest model generated parts from a list of steps.
+ */
+export declare function getLatestModelParts(steps: Interactions.Step[]): Part[];
+/**
+ * Convert Interaction response to an LlmResponse.
+ */
+export declare function convertInteractionToLlmResponse(interaction: ExtendedInteraction): LlmResponse;
+/**
+ * Convert InteractionSSEEvent to LlmResponse.
+ */
+export declare function convertInteractionEventToLlmResponse(event: ExtendedInteractionSSEEvent, aggregatedParts: Part[], interactionId?: string): LlmResponse | null;
+/**
+ * Build generation config.
+ */
+export declare function buildGenerationConfig(config: GenerateContentConfig): Record<string, unknown>;
+/**
+ * Extract system instruction.
+ */
+export declare function extractSystemInstruction(config: GenerateContentConfig): string | undefined;
+/**
+ * Generate content using the interactions API.
+ */
+export declare function generateContentViaInteractions(apiClient: GoogleGenAI, llmRequest: LlmRequest, stream: boolean): AsyncGenerator<LlmResponse, void, void>;

package/dist/types/models/llm_request.d.ts

@@ -34,6 +34,10 @@ export interface LlmRequest {
      * The set of allowed tools, populated by request processors.
      */
     allowedTools?: string[];
+    /**
+     * The interaction ID from the previous turn, if any.
+     */
+    previousInteractionId?: string;
 }
 /**
  * Appends instructions to the system instruction.

package/dist/types/models/llm_response.d.ts

@@ -77,6 +77,10 @@ export interface LlmResponse {
      * Audio transcription of model output.
      */
     outputTranscription?: Transcription;
+    /**
+     * The interaction ID returned by the model, if any.
+     */
+    interactionId?: string;
     /** The model version used to generate the response. */
     modelVersion?: string;
     /** The session ID of the Live session. */

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

@@ -16,7 +16,8 @@ import { BaseTool } from '../tools/base_tool.js';
  */
 export declare enum ContextCompactionTrigger {
     Manual = "Manual",
-    Auto = "Auto"
+    Auto = "Auto",
+    AgentControlled = "AgentControlled"
 }
 /**
  * Base class for creating plugins.

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

@@ -4,6 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { BaseAgent } from '../agents/base_agent.js';
+import { App } from '../apps/app.js';
+import { ResumabilityConfig } from '../apps/resumability_config.js';
 import { BasePlugin } from '../plugins/base_plugin.js';
 import { Runner } from './runner.js';
 /**
@@ -30,13 +32,17 @@ export declare class InMemoryRunner extends Runner {
      * Creates a new InMemoryRunner instance.
      *
      * @param params The configuration for the runner.
+     * @param params.app An optional application instance to run.
      * @param params.agent The root agent to run.
      * @param params.appName The application name. Defaults to `'InMemoryRunner'`.
      * @param params.plugins An optional list of plugins.
+     * @param params.resumabilityConfig An optional resumability configuration.
      */
     constructor(params: {
-        agent: BaseAgent;
+        app?: App;
+        agent?: BaseAgent;
         appName?: string;
         plugins?: BasePlugin[];
+        resumabilityConfig?: ResumabilityConfig;
     });
 }

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

@@ -6,6 +6,8 @@
 import { Content } from '@google/genai';
 import { BaseAgent } from '../agents/base_agent.js';
 import { RunConfig } from '../agents/run_config.js';
+import { App } from '../apps/app.js';
+import { ResumabilityConfig } from '../apps/resumability_config.js';
 import { BaseArtifactService } from '../artifacts/base_artifact_service.js';
 import { BaseCredentialService } from '../auth/credential_service/base_credential_service.js';
 import { Event } from '../events/event.js';
@@ -13,18 +15,23 @@ 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';
+import { Session } from '../sessions/session.js';
 /**
  * The configuration parameters for the Runner.
  */
 export interface RunnerConfig {
     /**
-     * The application name.
+     * The application object. If provided, `appName`, `agent`, and `plugins` will default from this app.
      */
-    appName: string;
+    app?: App;
     /**
-     * The agent to run.
+     * The application name. Required if `app` is not provided.
      */
-    agent: BaseAgent;
+    appName?: string;
+    /**
+     * The agent to run. Required if `app` is not provided.
+     */
+    agent?: BaseAgent;
     /**
      * An optional list of plugins to apply globally across all agents.
      */
@@ -45,6 +52,10 @@ export interface RunnerConfig {
      * An optional service for managing authentication credentials.
      */
     credentialService?: BaseCredentialService;
+    /**
+     * An optional resumability configuration applied to the runner.
+     */
+    resumabilityConfig?: ResumabilityConfig;
 }
 /**
  * A unique symbol to identify ADK agent classes.
@@ -91,6 +102,7 @@ export declare class Runner {
     readonly sessionService: BaseSessionService;
     readonly memoryService?: BaseMemoryService;
     readonly credentialService?: BaseCredentialService;
+    readonly resumabilityConfig?: ResumabilityConfig;
     /**
      * Creates a new Runner instance.
      *
@@ -147,18 +159,40 @@ export declare class Runner {
      * Determines the next agent to run to continue the session. This is primarily
      * used for session resumption.
      */
+    /**
+     * Determines the next agent to run to continue the session. This is primarily
+     * used for session resumption across tool and LRO boundaries.
+     */
     private determineAgentForResumption;
     /**
      * Whether the agent to run can transfer to any other agent in the agent tree.
      *
-     * An agent is transferable if:
-     *  - It is an instance of `LlmAgent`.
-     *  - All its ancestors are also transferable (i.e., they have
-     *    `disallowTransferToParent` set to false).
-     *
      * @param agentToRun The agent to check for transferability.
      * @returns True if the agent can transfer, False otherwise.
      */
     private isRoutableLlmAgent;
 }
+/**
+ * Determines the next agent to run to continue the session. This is primarily
+ * used for session resumption across tool and LRO boundaries.
+ */
+export declare function determineAgentForResumption(session: Session, rootAgent: BaseAgent, resumabilityConfig?: ResumabilityConfig): BaseAgent;
+/**
+ * Whether the agent to run can transfer to any other agent in the agent tree.
+ *
+ * An agent is transferable if:
+ *  - It is an instance of `LlmAgent`.
+ *  - All its ancestors are also transferable (i.e., they have
+ *    `disallowTransferToParent` set to false).
+ *
+ * @param agentToRun The agent to check for transferability.
+ * @returns True if the agent can transfer, False otherwise.
+ */
+export declare function isRoutableLlmAgent(agentToRun: BaseAgent): boolean;
+/**
+ * It iterates through the events in reverse order, and returns the event
+ * containing a function call with a functionCall.id matching the
+ * functionResponse.id from the last event in the session.
+ */
+export declare function findEventByLastFunctionResponseId(events: Event[]): Event | null;
 export {};

package/dist/types/sessions/base_session_service.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Event } from '../events/event.js';
-import { Session } from './session.js';
+import { CompositeSessionKey, Session } from './session.js';
 /**
  * The configuration of getting a session.
  */
@@ -30,13 +30,7 @@ export interface CreateSessionRequest {
 /**
  * The parameters for `getSession`.
  */
-export interface GetSessionRequest {
-    /** The name of the application. */
-    appName: string;
-    /** The ID of the user. */
-    userId: string;
-    /** The ID of the session. */
-    sessionId: string;
+export interface GetSessionRequest extends CompositeSessionKey {
     /** The configurations for getting the session. */
     config?: GetSessionConfig;
 }
@@ -60,14 +54,7 @@ export interface ListSessionsRequest {
 /**
  * The parameters for `deleteSession`.
  */
-export interface DeleteSessionRequest {
-    /** The name of the application. */
-    appName: string;
-    /** The ID of the user. */
-    userId: string;
-    /** The ID of the session. */
-    sessionId: string;
-}
+export type DeleteSessionRequest = CompositeSessionKey;
 /**
  * The parameters for `appendEvent`.
  */

package/dist/types/sessions/session.d.ts

@@ -4,6 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Event } from '../events/event.js';
+/**
+ * Represents a unified composite session key grouping application, user, and session identifiers.
+ */
+export interface CompositeSessionKey {
+    /** The name of the application. */
+    appName: string;
+    /** The ID of the user. */
+    userId: string;
+    /** The ID of the session. */
+    sessionId: string;
+}
 /**
  * Represents a session in a conversation between agents and users.
  */

package/dist/types/sessions/vertex_ai_session_service.d.ts

@@ -11,6 +11,14 @@ import { Session } from './session.js';
  * Checks if the given URI is a Vertex AI session service URI.
  */
 export declare function isVertexAiConnectionString(uri?: string): boolean;
+/**
+ * Quotes a value for safe use as a Google AIP-160 filter string literal.
+ *
+ * Backslashes are escaped first, then double quotes, so that caller-controlled
+ * input stays inside the quoted value and cannot break out to inject additional
+ * filter predicates. See https://google.aip.dev/160.
+ */
+export declare function quoteFilterLiteral(value: string): string;
 export interface VertexAiSessionServiceOptions {
     projectId?: string;
     location?: string;
@@ -32,6 +40,6 @@ export declare class VertexAiSessionService extends BaseSessionService {
     createSession({ appName, userId, state, sessionId, }: CreateSessionRequest): Promise<Session>;
     getSession({ appName, userId, sessionId, config, }: GetSessionRequest): Promise<Session | undefined>;
     listSessions({ appName, userId, limit, offset, page, order, }: ListSessionsRequest): Promise<ListSessionsResponse>;
-    deleteSession({ appName, userId: _userId, sessionId, }: DeleteSessionRequest): Promise<void>;
+    deleteSession({ appName, userId, sessionId, }: DeleteSessionRequest): Promise<void>;
     appendEvent({ session, event, }: AppendEventRequest): Promise<Event>;
 }

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

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration } from '@google/genai';
+import { BaseTool, RunAsyncToolRequest } from './base_tool.js';
+/**
+ * Tool for requesting context consolidation (compaction).
+ *
+ * When called by an LLM agent, this tool sets the state flags
+ * `temp:consolidate_context` and optionally `temp:consolidate_context_detail`,
+ * signalling the context compactor to trigger compaction.
+ */
+export declare class ConsolidateContextTool extends BaseTool {
+    constructor();
+    _getDeclaration(): FunctionDeclaration;
+    runAsync({ args, toolContext, }: RunAsyncToolRequest): Promise<unknown>;
+}

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

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Part } from '@google/genai';
-import { ArtifactVersion, BaseArtifactService, DeleteArtifactRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from '../artifacts/base_artifact_service.js';
+import { ArtifactVersion, BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from '../artifacts/base_artifact_service.js';
 import { Context } from '../agents/context.js';
 /**
  * Artifact service that forwards to the parent tool context.
@@ -15,7 +15,8 @@ export declare class ForwardingArtifactService implements BaseArtifactService {
     constructor(toolContext: Context);
     saveArtifact(request: SaveArtifactRequest): Promise<number>;
     loadArtifact(request: LoadArtifactRequest): Promise<Part | undefined>;
-    listArtifactKeys(): Promise<string[]>;
+    listArtifactKeys(_request: ListArtifactKeysRequest): Promise<string[]>;
+    private getArtifactService;
     deleteArtifact(request: DeleteArtifactRequest): Promise<void>;
     listVersions(request: ListVersionsRequest): Promise<number[]>;
     listArtifactVersions(request: ListVersionsRequest): Promise<ArtifactVersion[]>;

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

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare class AsyncLocalStorage<T> {
+    private store;
+    run<R>(store: T, callback: () => R): R;
+    getStore(): T | undefined;
+}

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

@@ -3,6 +3,16 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+export declare function parseUserAgent(userAgent: string): string;
+/**
+ * Runs the given callback within a context that has the specified client label.
+ * All LLM calls made within this callback will include the client label in their tracking headers.
+ *
+ * @param clientLabel The custom client label to apply.
+ * @param callback The callback function to execute.
+ * @return The result of the callback.
+ */
+export declare function runWithClientLabel<R>(clientLabel: string, callback: () => R): R;
 /**
  * Returns the current list of client labels that can be added to HTTP Headers.
  */

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

@@ -9,12 +9,12 @@
 export declare function isBrowser(): boolean;
 export declare function randomUUID(): string;
 /**
- * Encodes the given string to base64.
+ * Encodes the given string or Uint8Array to base64.
  *
- * @param data The string to encode.
+ * @param data The data to encode.
  * @return The base64-encoded string.
  */
-export declare function base64Encode(data: string): string;
+export declare function base64Encode(data: string | Uint8Array): string;
 /**
  * Decodes the given base64 string to a string.
  *

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

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export type TaskExecutable<T = void> = (abortSignal: AbortSignal) => Promise<T>;
+/**
+ * Represents a runtime task wrapping a promise, allowing status check and cancellation.
+ */
+export declare class Task<T = void> {
+    executable: TaskExecutable<T>;
+    private isDone;
+    private abortController;
+    promise: Promise<T>;
+    constructor(executable: TaskExecutable<T>);
+    /**
+     * Cancels the task execution.
+     */
+    cancel(): void;
+    /**
+     * Returns true if the task has completed (either resolved or rejected).
+     */
+    done(): boolean;
+}

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.3.0";
+export declare const version = "1.4.0";

package/dist/web/agents/active_streaming_tool.js

@@ -5,9 +5,14 @@ const require = topLevelCreateRequire(import.meta.url);
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { Task } from "../utils/task.js";
 class ActiveStreamingTool {
   constructor(params = {}) {
-    this.task = params.task;
+    if (params.task instanceof Promise) {
+      this.task = new Task(() => params.task);
+    } else {
+      this.task = params.task;
+    }
     this.stream = params.stream;
   }
 }

package/dist/web/agents/context.js

@@ -56,9 +56,6 @@ class Context extends ReadonlyContext {
       throw new Error("Artifact service is not initialized.");
     }
     return this.invocationContext.artifactService.loadArtifact({
-      appName: this.invocationContext.appName,
-      userId: this.invocationContext.userId,
-      sessionId: this.invocationContext.session.id,
       filename,
       version
     });
@@ -75,9 +72,6 @@ class Context extends ReadonlyContext {
       throw new Error("Artifact service is not initialized.");
     }
     const version = await this.invocationContext.artifactService.saveArtifact({
-      appName: this.invocationContext.appName,
-      userId: this.invocationContext.userId,
-      sessionId: this.invocationContext.session.id,
       filename,
       artifact
     });
@@ -110,11 +104,7 @@ class Context extends ReadonlyContext {
     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
-    });
+    return this.invocationContext.artifactService.listArtifactKeys();
   }
   /**
    * Searches the memory of the current user.

package/dist/web/agents/functions.js

@@ -7,7 +7,11 @@ const require = topLevelCreateRequire(import.meta.url);
  */
 import { createUserContent } from "@google/genai";
 import { isEmpty } from "lodash-es";
-import { createEvent, getFunctionCalls } from "../events/event.js";
+import {
+  createEvent,
+  getFunctionCalls,
+  getFunctionResponses
+} from "../events/event.js";
 import { mergeEventActions } from "../events/event_actions.js";
 import { randomUUID } from "../utils/env_aware_utils.js";
 import { logger } from "../utils/logger.js";
@@ -39,18 +43,6 @@ function populateClientFunctionCallId(modelResponseEvent) {
     }
   }
 }
-function removeClientFunctionCallId(content) {
-  if (content && content.parts) {
-    for (const part of content.parts) {
-      if (part.functionCall && part.functionCall.id && part.functionCall.id.startsWith(AF_FUNCTION_CALL_ID_PREFIX)) {
-        part.functionCall.id = void 0;
-      }
-      if (part.functionResponse && part.functionResponse.id && part.functionResponse.id.startsWith(AF_FUNCTION_CALL_ID_PREFIX)) {
-        part.functionResponse.id = void 0;
-      }
-    }
-  }
-}
 function getLongRunningFunctionCalls(functionCalls, toolsDict) {
   const longRunningToolIds = /* @__PURE__ */ new Set();
   for (const functionCall of functionCalls) {
@@ -393,9 +385,39 @@ function mergeParallelFunctionResponseEvents(functionResponseEvents) {
     timestamp: baseEvent.timestamp
   });
 }
+function findEventByFunctionCallId(events, functionCallId, endIndex = events.length) {
+  for (let i = endIndex - 1; i >= 0; i--) {
+    const event = events[i];
+    const functionCalls = getFunctionCalls(event);
+    for (const functionCall of functionCalls) {
+      if (functionCall.id === functionCallId) {
+        return event;
+      }
+    }
+  }
+  return void 0;
+}
+function findMatchingFunctionCall(events) {
+  if (!events.length) {
+    return void 0;
+  }
+  const lastEvent = events[events.length - 1];
+  const functionResponses = getFunctionResponses(lastEvent);
+  if (!functionResponses.length || !functionResponses[0].id) {
+    return void 0;
+  }
+  return findEventByFunctionCallId(
+    events,
+    functionResponses[0].id,
+    events.length - 1
+  );
+}
 export {
+  AF_FUNCTION_CALL_ID_PREFIX,
   REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
   REQUEST_EUC_FUNCTION_CALL_NAME,
+  findEventByFunctionCallId,
+  findMatchingFunctionCall,
   functionsExportedForTestingOnly,
   generateAuthEvent,
   generateClientFunctionCallId,
@@ -404,6 +426,5 @@ export {
   handleFunctionCallList,
   handleFunctionCallsAsync,
   mergeParallelFunctionResponseEvents,
-  populateClientFunctionCallId,
-  removeClientFunctionCallId
+  populateClientFunctionCallId
 };