@google/adk 1.2.0 → 1.3.0

package/dist/types/tools/openapi_tool/rest_api_tool.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration } from '@google/genai';
+import { OpenAPIV3 } from 'openapi-types';
+import { ReadonlyContext } from '../../agents/readonly_context.js';
+import { AuthCredential } from '../../auth/auth_credential.js';
+import { BaseTool, RunAsyncToolRequest } from '../base_tool.js';
+import { ApiParameter } from './openapi_spec_parser/operation_parser.js';
+import { OperationEndpoint } from './openapi_spec_parser/openapi_spec_parser.js';
+export declare class RestApiTool extends BaseTool {
+    private readonly endpoint;
+    private readonly operation;
+    private authScheme?;
+    private authCredential?;
+    private operationParser;
+    private headerProvider?;
+    private credentialKey?;
+    constructor(name: string, description: string, endpoint: OperationEndpoint, operation: OpenAPIV3.OperationObject, authScheme?: OpenAPIV3.SecuritySchemeObject | undefined, authCredential?: AuthCredential | undefined, options?: {
+        preservePropertyNames?: boolean;
+        headerProvider?: (context: ReadonlyContext) => Record<string, string>;
+        credentialKey?: string;
+    });
+    configureAuthScheme(authScheme: OpenAPIV3.SecuritySchemeObject): void;
+    configureAuthCredential(authCredential: AuthCredential): void;
+    configureCredentialKey(credentialKey: string): void;
+    _getDeclaration(): FunctionDeclaration;
+    runAsync(request: RunAsyncToolRequest): Promise<unknown>;
+}
+export interface PreparedParams {
+    url: string;
+    headers: Record<string, string>;
+    body: unknown;
+    bodyData: Record<string, unknown>;
+}
+export declare function prepareRequestParams(endpoint: OperationEndpoint, parameters: ApiParameter[], args: Record<string, unknown>): PreparedParams;
+export declare function prepareRequestBody(requestBody: OpenAPIV3.RequestBodyObject | OpenAPIV3.ReferenceObject | undefined, body: unknown, bodyData: Record<string, unknown>, headers: Record<string, string>): unknown;
+export declare function createRestApiTool(parsed: {
+    name: string;
+    description: string;
+    endpoint: OperationEndpoint;
+    operation: OpenAPIV3.OperationObject;
+    authScheme?: OpenAPIV3.SecuritySchemeObject;
+}, options?: {
+    preservePropertyNames?: boolean;
+    headerProvider?: (context: ReadonlyContext) => Record<string, string>;
+    credentialKey?: string;
+}): RestApiTool;

package/dist/types/tools/skill/load_skill_resource_tool.d.ts

@@ -10,6 +10,6 @@ export declare class LoadSkillResourceTool extends BaseTool {
     private toolset;
     constructor(toolset: SkillToolset);
     _getDeclaration(): FunctionDeclaration;
-    runAsync({ args }: RunAsyncToolRequest): Promise<unknown>;
+    runAsync({ args, toolContext, }: RunAsyncToolRequest): Promise<unknown>;
     processLlmRequest(request: ToolProcessLlmRequest): Promise<void>;
 }

package/dist/types/tools/skill/search_skills_tool.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration } from '@google/genai';
+import { BaseTool, RunAsyncToolRequest } from '../base_tool.js';
+import { SkillToolset } from './skill_toolset.js';
+export declare class SearchSkillsTool extends BaseTool {
+    private toolset;
+    constructor(toolset: SkillToolset);
+    _getDeclaration(): FunctionDeclaration;
+    runAsync({ args }: RunAsyncToolRequest): Promise<unknown>;
+}

package/dist/types/tools/skill/skill_toolset.d.ts

@@ -8,6 +8,7 @@ import { ReadonlyContext } from '../../agents/readonly_context.js';
 import { BaseCodeExecutor } from '../../code_executors/base_code_executor.js';
 import { LlmRequest } from '../../models/llm_request.js';
 import { Skill } from '../../skills/skill.js';
+import { SkillRegistry } from '../../skills/skill_registry.js';
 import { BaseTool } from '../base_tool.js';
 import { BaseToolset } from '../base_toolset.js';
 export declare class SkillToolset extends BaseToolset {
@@ -15,14 +16,18 @@ export declare class SkillToolset extends BaseToolset {
     private tools;
     additionalTools: Array<BaseTool | BaseToolset>;
     codeExecutor?: BaseCodeExecutor;
+    registry?: SkillRegistry;
     private toolCache;
+    private fetchedSkillCache;
     constructor(skills: Record<string, Skill> | Skill[], options?: {
         codeExecutor?: BaseCodeExecutor;
         additionalTools?: Array<BaseTool | BaseToolset>;
+        registry?: SkillRegistry;
     });
     getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
     close(): Promise<void>;
     getSkill(name: string): Skill | undefined;
+    getOrFetchSkill(name: string, invocationId?: string): Promise<Skill | undefined>;
     processLlmRequest(toolContext: Context, llmRequest: LlmRequest): Promise<void>;
     private resolveAdditionalTools;
 }

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

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A generic, async-safe queue that implements AsyncIterable.
+ */
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    private queue;
+    private resolvers;
+    private closed;
+    private errorVal?;
+    push(value: T): void;
+    error(err: unknown): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Recursively converts snake_case keys of an object to camelCase.
+ *
+ * @param val The value to convert.
+ * @returns The converted value.
+ */
+export declare function camelCaseKeys(val: unknown): unknown;

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

@@ -19,7 +19,6 @@ export declare class StreamingResponseAggregator {
     private response?;
     private finishReason?;
     private lastThoughtSignature;
-    private sawFunctionCall;
     private readonly strategy;
     constructor(isProgressiveMode?: boolean);
     processResponse(response: GenerateContentResponse): AsyncGenerator<LlmResponse, void, void>;

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.2.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/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) {