@google/adk 1.1.0 → 1.3.0

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/live_connection_utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LiveServerMessage } from '@google/genai';
+import { LlmResponse } from '../models/llm_response.js';
+/**
+ * Aggregator and mapper for Gemini Live WebSocket server messages.
+ *
+ * Translates incoming raw WebSocket server messages (push stream) into unified
+ * agent-consumable LlmResponse objects (pull stream), managing transcription buffers,
+ * grounding metadata, text segments, and tool calls.
+ */
+export declare class LiveResponseAggregator {
+    private readonly modelVersion?;
+    private text;
+    private isThought;
+    private toolCallParts;
+    private pendingGroundingMetadata;
+    private inputTranscriptionText;
+    private outputTranscriptionText;
+    constructor(modelVersion?: string | undefined);
+    processMessage(message: LiveServerMessage): Generator<LlmResponse, void, void>;
+    /**
+     * Flushes any remaining aggregated components when the connection is closed.
+     */
+    close(): Generator<LlmResponse, void, void>;
+    private buildFullTextResponse;
+}

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

@@ -32,6 +32,13 @@ 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;
+/**
+ * Check if the model is a Gemini 3.x Flash Live model.
+ *
+ * @param modelString Either a simple model name or path-based model name
+ * @return true if it's a Gemini 3.x Flash Live model, false otherwise.
+ */
+export declare function isGemini3xFlashLive(modelString: string | undefined): boolean;
 /**
  * Returns True when Gemini model-id validation should be bypassed.
  */

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,14 @@ 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 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.1.0";
+export declare const version = "1.3.0";

package/dist/web/agents/base_agent.js

@@ -184,10 +184,40 @@ class BaseAgent {
           this,
           function() {
             return __asyncGenerator(this, null, function* () {
+              var _a2, _b;
+              const context2 = this.createInvocationContext(parentContext);
+              const beforeAgentCallbackEvent = yield new __await(this.handleBeforeAgentCallback(context2));
+              if (beforeAgentCallbackEvent) {
+                yield beforeAgentCallbackEvent;
+              }
+              if (context2.endInvocation || ((_a2 = parentContext.abortSignal) == null ? void 0 : _a2.aborted)) {
+                return;
+              }
+              try {
+                for (var iter = __forAwait(this.runLiveImpl(context2)), more, temp, error; more = !(temp = yield new __await(iter.next())).done; more = false) {
+                  const event = temp.value;
+                  yield event;
+                }
+              } catch (temp) {
+                error = [temp];
+              } finally {
+                try {
+                  more && (temp = iter.return) && (yield new __await(temp.call(iter)));
+                } finally {
+                  if (error)
+                    throw error[0];
+                }
+              }
+              if (context2.endInvocation || ((_b = parentContext.abortSignal) == null ? void 0 : _b.aborted)) {
+                return;
+              }
+              const afterAgentCallbackEvent = yield new __await(this.handleAfterAgentCallback(context2));
+              if (afterAgentCallbackEvent) {
+                yield afterAgentCallbackEvent;
+              }
             });
           }
         ));
-        throw new Error("Live mode is not implemented yet.");
       } finally {
         span.end();
       }

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/agents/instructions.js

@@ -6,50 +6,98 @@ const require = topLevelCreateRequire(import.meta.url);
  * SPDX-License-Identifier: Apache-2.0
  */
 import { State } from "../sessions/state.js";
-async function injectSessionState(template, readonlyContext) {
+const ARTIFACT_PREFIX = "artifact.";
+async function resolveKey(key, isOptional, rawMatch, readonlyContext) {
   const invocationContext = readonlyContext.invocationContext;
-  async function replaceMatchedKeyWithItsValue(match) {
-    let key = match[0].replace(/^\{+/, "").replace(/\}+$/, "").trim();
+  if (key.startsWith(ARTIFACT_PREFIX)) {
+    const fileName = key.substring(ARTIFACT_PREFIX.length);
+    if (invocationContext.artifactService === void 0) {
+      throw new Error("Artifact service is not initialized.");
+    }
+    const artifact = await invocationContext.artifactService.loadArtifact({
+      appName: invocationContext.session.appName,
+      userId: invocationContext.session.userId,
+      sessionId: invocationContext.session.id,
+      filename: fileName
+    });
+    if (!artifact) {
+      if (isOptional) {
+        return "";
+      }
+      throw new Error("Artifact ".concat(fileName, " not found."));
+    }
+    return String(artifact);
+  }
+  if (!isValidStateName(key)) {
+    return rawMatch;
+  }
+  if (key in invocationContext.session.state) {
+    return String(invocationContext.session.state[key]);
+  }
+  if (isOptional) {
+    return "";
+  }
+  throw new Error("Context variable not found: `".concat(key, "`."));
+}
+async function injectSessionState(template, readonlyContext) {
+  const pattern = /\{+[^{}]*}+/g;
+  const matches = Array.from(template.matchAll(pattern));
+  if (matches.length === 0) {
+    return template;
+  }
+  const parsedMatches = matches.map((match) => {
+    const raw = match[0];
+    let key = raw.replace(/^\{+/, "").replace(/\}+$/, "").trim();
     const isOptional = key.endsWith("?");
     if (isOptional) {
       key = key.slice(0, -1);
     }
-    if (key.startsWith("artifact.")) {
-      const fileName = key.substring("artifact.".length);
-      if (invocationContext.artifactService === void 0) {
-        throw new Error("Artifact service is not initialized.");
+    const isValid = key.startsWith(ARTIFACT_PREFIX) || isValidStateName(key);
+    return {
+      raw,
+      key,
+      isOptional,
+      isValid,
+      index: match.index
+    };
+  });
+  const uniqueKeys = /* @__PURE__ */ new Map();
+  for (const pm of parsedMatches) {
+    if (!pm.isValid) {
+      continue;
+    }
+    const existing = uniqueKeys.get(pm.key);
+    if (existing) {
+      if (existing.isOptional && !pm.isOptional) {
+        existing.isOptional = false;
       }
-      const artifact = await invocationContext.artifactService.loadArtifact({
-        appName: invocationContext.session.appName,
-        userId: invocationContext.session.userId,
-        sessionId: invocationContext.session.id,
-        filename: fileName
+    } else {
+      uniqueKeys.set(pm.key, {
+        key: pm.key,
+        isOptional: pm.isOptional,
+        raw: pm.raw
       });
-      if (!artifact) {
-        throw new Error("Artifact ".concat(fileName, " not found."));
-      }
-      return String(artifact);
-    }
-    if (!isValidStateName(key)) {
-      return match[0];
-    }
-    if (key in invocationContext.session.state) {
-      return String(invocationContext.session.state[key]);
     }
-    if (isOptional) {
-      return "";
-    }
-    throw new Error("Context variable not found: `".concat(key, "`."));
   }
-  const pattern = /\{+[^{}]*}+/g;
+  const resolutions = /* @__PURE__ */ new Map();
+  for (const info of uniqueKeys.values()) {
+    resolutions.set(
+      info.key,
+      resolveKey(info.key, info.isOptional, info.raw, readonlyContext)
+    );
+  }
+  await Promise.all(resolutions.values());
   const result = [];
   let lastEnd = 0;
-  const matches = template.matchAll(pattern);
-  for (const match of matches) {
-    result.push(template.slice(lastEnd, match.index));
-    const replacement = await replaceMatchedKeyWithItsValue(match);
-    result.push(replacement);
-    lastEnd = match.index + match[0].length;
+  for (const pm of parsedMatches) {
+    result.push(template.slice(lastEnd, pm.index));
+    if (pm.isValid) {
+      const replacement = await resolutions.get(pm.key);
+      result.push(replacement);
+    } else {
+      result.push(pm.raw);
+    }
+    lastEnd = pm.index + pm.raw.length;
   }
   result.push(template.slice(lastEnd));
   return result.join("");

package/dist/web/agents/invocation_context.js

@@ -46,7 +46,6 @@ class InvocationContext {
     this.endInvocation = params.endInvocation || false;
     this.transcriptionCache = params.transcriptionCache;
     this.runConfig = params.runConfig;
-    this.liveRequestQueue = params.liveRequestQueue;
     this.activeStreamingTools = params.activeStreamingTools;
     this.pluginManager = params.pluginManager;
     this.abortSignal = params.abortSignal;

package/dist/web/agents/llm_agent.js

@@ -71,10 +71,12 @@ var __forAwait = (obj, it, method) => (it = obj[__knownSymbol("asyncIterator")])
  */
 var _a, _b;
 import { context, trace } from "@opentelemetry/api";
+import { FunctionTool } from "../tools/function_tool.js";
 import {
   createEvent,
   createNewEventId,
   getFunctionCalls,
+  getFunctionResponses,
   isFinalResponse
 } from "../events/event.js";
 import { isBaseLlm } from "../models/base_llm.js";
@@ -96,6 +98,7 @@ import {
   handleFunctionCallsAsync,
   populateClientFunctionCallId
 } from "./functions.js";
+import { AUTH_PREPROCESSOR } from "../auth/auth_preprocessor.js";
 import { AGENT_TRANSFER_LLM_REQUEST_PROCESSOR } from "./processors/agent_transfer_llm_request_processor.js";
 import { BASIC_LLM_REQUEST_PROCESSOR } from "./processors/basic_llm_request_processor.js";
 import { CODE_EXECUTION_REQUEST_PROCESSOR } from "./processors/code_execution_request_processor.js";
@@ -142,6 +145,7 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
     this.codeExecutor = config.codeExecutor;
     this.requestProcessors = (_g = config.requestProcessors) != null ? _g : [
       BASIC_LLM_REQUEST_PROCESSOR,
+      AUTH_PREPROCESSOR,
       IDENTITY_LLM_REQUEST_PROCESSOR,
       INSTRUCTIONS_LLM_REQUEST_PROCESSOR,
       REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR,
@@ -368,9 +372,10 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
   }
   runAsyncImpl(context2) {
     return __asyncGenerator(this, null, function* () {
-      var _a2;
+      var _a2, _b2;
       while (true) {
         let lastEvent = void 0;
+        let stepHadToolCalls = false;
         try {
           for (var iter = __forAwait(this.runOneStepAsync(context2)), more, temp, error; more = !(temp = yield new __await(iter.next())).done; more = false) {
             const event = temp.value;
@@ -378,6 +383,9 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
               return;
             }
             lastEvent = event;
+            if (getFunctionCalls(event).length > 0 || getFunctionResponses(event).length > 0) {
+              stepHadToolCalls = true;
+            }
             this.maybeSaveOutputToState(event);
             yield event;
           }
@@ -391,7 +399,11 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
               throw error[0];
           }
         }
-        if (!lastEvent || isFinalResponse(lastEvent)) {
+        if (!lastEvent) {
+          break;
+        }
+        const isEmptyMetadataEvent = lastEvent.author === this.name && !lastEvent.partial && (!((_b2 = lastEvent.content) == null ? void 0 : _b2.parts) || lastEvent.content.parts.length === 0);
+        if (isFinalResponse(lastEvent) && !(isEmptyMetadataEvent && stepHadToolCalls)) {
           break;
         }
         if (lastEvent.partial) {
@@ -431,6 +443,20 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
   // --------------------------------------------------------------------------
   // #START LlmFlow Logic
   // --------------------------------------------------------------------------
+  /**
+   * Runs the bidirectional (live) flow for this agent.
+   *
+   * Establishes a live connection to the model, drains the invocation's
+   * `liveRequestQueue` into the connection on a parallel task, and yields
+   * events derived from server messages until the queue closes, the model
+   * finishes, or an agent transfer occurs.
+   *
+   * If the live connection drops (network failure, server `goAway`) and a
+   * session resumption handle has been observed, the flow transparently
+   * reconnects using that handle up to {@link MAX_LIVE_RECONNECT_ATTEMPTS}
+   * times. Subsequent reconnects skip `sendHistory` because the server
+   * already holds the conversation state associated with the handle.
+   */
   // eslint-disable-next-line require-yield
   runLiveFlow(_invocationContext) {
     return __asyncGenerator(this, null, function* () {
@@ -469,13 +495,28 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
           }
         }
       }
-      for (const toolUnion of this.tools) {
+      const allTools = [...this.tools];
+      if (this.outputSchema && allTools.length > 0) {
+        const setModelResponseTool = new FunctionTool({
+          name: "set_model_response",
+          description: "Call this tool to submit your final response conforming to the output schema. Use this tool only when you have collected all the information and are ready to return the final answer.",
+          parameters: this.outputSchema,
+          execute: async (args, toolContext) => {
+            if (toolContext) {
+              toolContext.actions.skipSummarization = true;
+            }
+            return JSON.stringify(args);
+          }
+        });
+        allTools.push(setModelResponseTool);
+      }
+      for (const toolUnion of allTools) {
         const toolContext = new Context({ invocationContext });
         const tools = (yield new __await(convertToolUnionToTools(
           toolUnion,
           new ReadonlyContext(invocationContext)
         ))).filter((tool) => {
-          return !llmRequest.allowedTools || llmRequest.allowedTools.includes(tool.name);
+          return !llmRequest.allowedTools || llmRequest.allowedTools.includes(tool.name) || tool.name === "set_model_response";
         });
         for (const tool of tools) {
           yield new __await(tool.processLlmRequest({ toolContext, llmRequest }));
@@ -594,7 +635,14 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
       const mergedEvent = createEvent(__spreadValues(__spreadValues({}, modelResponseEvent), llmResponse));
       if (mergedEvent.content) {
         const functionCalls = getFunctionCalls(mergedEvent);
-        if (functionCalls == null ? void 0 : functionCalls.length) {
+        const setModelResponseCall = functionCalls.find(
+          (call) => call.name === "set_model_response"
+        );
+        if (setModelResponseCall) {
+          const args = setModelResponseCall.args;
+          mergedEvent.content.parts = [{ text: JSON.stringify(args) }];
+          mergedEvent.actions.skipSummarization = true;
+        } else if (functionCalls && functionCalls.length) {
           populateClientFunctionCallId(mergedEvent);
           mergedEvent.longRunningToolIds = Array.from(
             getLongRunningFunctionCalls(functionCalls, llmRequest.toolsDict)

package/dist/web/agents/processors/agent_transfer_llm_request_processor.js

@@ -46,6 +46,13 @@ class AgentTransferLlmRequestProcessor extends BaseLlmRequestProcessor {
       }
     });
   }
+  /**
+   * Appends transfer instructions and registers the `transfer_to_agent` tool
+   * when the agent has reachable transfer targets.
+   *
+   * @param invocationContext - The current invocation context.
+   * @param llmRequest - The request to augment with transfer instructions and the transfer tool.
+   */
   // eslint-disable-next-line require-yield
   runAsync(invocationContext, llmRequest) {
     return __asyncGenerator(this, null, function* () {

package/dist/web/agents/processors/basic_llm_request_processor.js

@@ -41,6 +41,13 @@ import { setOutputSchema } from "../../models/llm_request.js";
 import { isLlmAgent } from "../llm_agent.js";
 import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
 class BasicLlmRequestProcessor extends BaseLlmRequestProcessor {
+  /**
+   * Populates model name, generation config, output schema, and live connect
+   * settings on the request from the agent and run config.
+   *
+   * @param invocationContext - The current invocation context.
+   * @param llmRequest - The request object to populate in place.
+   */
   // eslint-disable-next-line require-yield
   runAsync(invocationContext, llmRequest) {
     return __asyncGenerator(this, null, function* () {
@@ -51,7 +58,7 @@ class BasicLlmRequestProcessor extends BaseLlmRequestProcessor {
       }
       llmRequest.model = agent.canonicalModel.model;
       llmRequest.config = __spreadValues({}, (_a = agent.generateContentConfig) != null ? _a : {});
-      if (agent.outputSchema) {
+      if (agent.outputSchema && (!agent.tools || agent.tools.length === 0)) {
         setOutputSchema(llmRequest, agent.outputSchema);
       }
       if (invocationContext.runConfig) {