@google/adk 1.1.0 → 1.3.0

package/dist/esm/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/esm/agents/llm_agent.js

@@ -7,10 +7,12 @@ const require = topLevelCreateRequire(import.meta.url);
  */
 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";
@@ -32,6 +34,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";
@@ -78,6 +81,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,
@@ -303,18 +307,26 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
     event.actions.stateDelta[this.outputKey] = result;
   }
   async *runAsyncImpl(context2) {
-    var _a2;
+    var _a2, _b2;
     while (true) {
       let lastEvent = void 0;
+      let stepHadToolCalls = false;
       for await (const event of this.runOneStepAsync(context2)) {
         if ((_a2 = context2.abortSignal) == null ? void 0 : _a2.aborted) {
           return;
         }
         lastEvent = event;
+        if (getFunctionCalls(event).length > 0 || getFunctionResponses(event).length > 0) {
+          stepHadToolCalls = true;
+        }
         this.maybeSaveOutputToState(event);
         yield event;
       }
-      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) {
@@ -339,6 +351,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
   async *runLiveFlow(_invocationContext) {
     await Promise.resolve();
@@ -362,13 +388,28 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
         yield event;
       }
     }
-    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 = (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) {
         await tool.processLlmRequest({ toolContext, llmRequest });
@@ -448,7 +489,14 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
     });
     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/esm/agents/processors/agent_transfer_llm_request_processor.js

@@ -30,6 +30,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
   async *runAsync(invocationContext, llmRequest) {
     if (!isLlmAgent(invocationContext.agent)) {

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

@@ -9,6 +9,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
   async *runAsync(invocationContext, llmRequest) {
     var _a;
@@ -18,7 +25,7 @@ class BasicLlmRequestProcessor extends BaseLlmRequestProcessor {
     }
     llmRequest.model = agent.canonicalModel.model;
     llmRequest.config = { ...(_a = agent.generateContentConfig) != null ? _a : {} };
-    if (agent.outputSchema) {
+    if (agent.outputSchema && (!agent.tools || agent.tools.length === 0)) {
       setOutputSchema(llmRequest, agent.outputSchema);
     }
     if (invocationContext.runConfig) {

package/dist/esm/agents/processors/content_processor_utils.js

@@ -109,17 +109,19 @@ function convertForeignEvent(event) {
         text: `[${event.author}] said: ${part.text}`
       });
     } else if (part.functionCall) {
-      const argsText = safeStringify(part.functionCall.args);
       (_d = content.parts) == null ? void 0 : _d.push({
-        text: `[${event.author}] called tool \`${part.functionCall.name}\` with parameters: ${argsText}`
+        text: `[${event.author}] called tool \`${part.functionCall.name}\` with parameters: ${safeStringify(
+          part.functionCall.args
+        )}`
       });
     } else if (part.functionResponse) {
-      const responseText = safeStringify(part.functionResponse.response);
       (_e = content.parts) == null ? void 0 : _e.push({
-        text: `[${event.author}] tool \`${part.functionResponse.name}\` returned result: ${responseText}`
+        text: `[${event.author}] tool \`${part.functionResponse.name}\` returned result: ${safeStringify(
+          part.functionResponse.response
+        )}`
       });
     } else {
-      (_f = content.parts) == null ? void 0 : _f.push(part);
+      (_f = content.parts) == null ? void 0 : _f.push(cloneDeep(part));
     }
   }
   return createEvent({
@@ -135,9 +137,12 @@ function mergeFunctionResponseEvents(events) {
   if (events.length === 0) {
     throw new Error("Cannot merge an empty list of events.");
   }
-  const mergedEvent = createEvent(events[0]);
-  const partsInMergedEvent = ((_a = mergedEvent.content) == null ? void 0 : _a.parts) || [];
-  if (partsInMergedEvent.length === 0) {
+  const mergedEvent = createEvent({
+    ...events[0],
+    content: events[0].content ? cloneDeep(events[0].content) : void 0
+  });
+  const partsInMergedEvent = (_a = mergedEvent.content) == null ? void 0 : _a.parts;
+  if (!partsInMergedEvent || partsInMergedEvent.length === 0) {
     throw new Error("There should be at least one function_response part.");
   }
   const partIndicesInMergedEvent = {};
@@ -152,16 +157,17 @@ function mergeFunctionResponseEvents(events) {
       throw new Error("There should be at least one function_response part.");
     }
     for (const part of event.content.parts) {
-      if (part.functionResponse && part.functionResponse.id) {
-        const functionCallId = part.functionResponse.id;
+      const clonedPart = cloneDeep(part);
+      if (clonedPart.functionResponse && clonedPart.functionResponse.id) {
+        const functionCallId = clonedPart.functionResponse.id;
         if (functionCallId in partIndicesInMergedEvent) {
-          partsInMergedEvent[partIndicesInMergedEvent[functionCallId]] = part;
+          partsInMergedEvent[partIndicesInMergedEvent[functionCallId]] = clonedPart;
         } else {
-          partsInMergedEvent.push(part);
+          partsInMergedEvent.push(clonedPart);
           partIndicesInMergedEvent[functionCallId] = partsInMergedEvent.length - 1;
         }
       } else {
-        partsInMergedEvent.push(part);
+        partsInMergedEvent.push(clonedPart);
       }
     }
   }
@@ -176,7 +182,7 @@ function rearrangeEventsForLatestFunctionResponse(events) {
   if (!(functionResponses == null ? void 0 : functionResponses.length)) {
     return events;
   }
-  let functionResponsesIds = new Set(
+  const functionResponsesIds = new Set(
     functionResponses.filter((response) => !!response.id).map((response) => response.id)
   );
   const secondLatestEvent = events.at(-2);
@@ -190,16 +196,16 @@ function rearrangeEventsForLatestFunctionResponse(events) {
       }
     }
   }
-  let functionCallEventIdx = -1;
+  let match;
   for (let idx = events.length - 2; idx >= 0; idx--) {
     const event = events[idx];
     const functionCalls = getFunctionCalls(event);
     if (!(functionCalls == null ? void 0 : functionCalls.length)) {
       continue;
     }
+    let matchedInEvent = false;
     for (const functionCall of functionCalls) {
       if (functionCall.id && functionResponsesIds.has(functionCall.id)) {
-        functionCallEventIdx = idx;
         const functionCallIds = new Set(
           functionCalls.map((fc) => fc.id).filter((id) => !!id)
         );
@@ -213,12 +219,16 @@ function rearrangeEventsForLatestFunctionResponse(events) {
             )}, function response ids provided: ${Array.from(functionResponsesIds).join(", ")}`
           );
         }
-        functionResponsesIds = functionCallIds;
+        match = { eventIdx: idx, responseIds: functionCallIds };
+        matchedInEvent = true;
         break;
       }
     }
+    if (matchedInEvent) {
+      break;
+    }
   }
-  if (functionCallEventIdx === -1) {
+  if (!match) {
     throw new Error(
       `No function call event found for function responses ids: ${Array.from(
         functionResponsesIds
@@ -226,17 +236,18 @@ function rearrangeEventsForLatestFunctionResponse(events) {
     );
   }
   const functionResponseEvents = [];
-  for (let idx = functionCallEventIdx + 1; idx < events.length - 1; idx++) {
+  const activeResponses = match.responseIds;
+  for (let idx = match.eventIdx + 1; idx < events.length - 1; idx++) {
     const event = events[idx];
     const responses = getFunctionResponses(event);
     if (responses && responses.some(
-      (response) => response.id && functionResponsesIds.has(response.id)
+      (response) => response.id && activeResponses.has(response.id)
     )) {
       functionResponseEvents.push(event);
     }
   }
   functionResponseEvents.push(events[events.length - 1]);
-  const resultEvents = events.slice(0, functionCallEventIdx + 1);
+  const resultEvents = events.slice(0, match.eventIdx + 1);
   resultEvents.push(mergeFunctionResponseEvents(functionResponseEvents));
   return resultEvents;
 }
@@ -275,7 +286,7 @@ function rearrangeEventsForAsyncFunctionResponsesInHistory(events) {
         continue;
       }
       if (functionResponseEventsIndices.size === 1) {
-        const [responseIndex] = [...functionResponseEventsIndices];
+        const [responseIndex] = Array.from(functionResponseEventsIndices);
         resultEvents.push(events[responseIndex]);
       } else {
         const indicesArray = Array.from(functionResponseEventsIndices).sort(
@@ -315,5 +326,6 @@ ${event.compactedContent}`
 }
 export {
   getContents,
-  getCurrentTurnContents
+  getCurrentTurnContents,
+  mergeFunctionResponseEvents
 };

package/dist/esm/agents/processors/content_request_processor.js

@@ -12,6 +12,13 @@ import {
   getCurrentTurnContents
 } from "./content_processor_utils.js";
 class ContentRequestProcessor {
+  /**
+   * Fills {@link LlmRequest.contents} based on the session event history and
+   * agent configuration.
+   *
+   * @param invocationContext - The current invocation context.
+   * @param llmRequest - The request whose contents field will be populated.
+   */
   // eslint-disable-next-line require-yield
   async *runAsync(invocationContext, llmRequest) {
     const agent = invocationContext.agent;

package/dist/esm/agents/processors/context_compactor_request_processor.js

@@ -7,9 +7,21 @@ const require = topLevelCreateRequire(import.meta.url);
  */
 import { ContextCompactionTrigger } from "../../plugins/base_plugin.js";
 class ContextCompactorRequestProcessor {
+  /**
+   * @param compactors - Ordered list of compactors to evaluate; the first one
+   *   that reports it should compact will perform the compaction.
+   */
   constructor(compactors) {
     this.compactors = compactors;
   }
+  /**
+   * Evaluates compactors in priority order. The first compactor that indicates
+   * it should compact will compact the session history, fire plugin hooks, and
+   * yield any newly generated events. Iteration stops after one compaction.
+   *
+   * @param invocationContext - The current invocation context.
+   * @param _llmRequest - Unused; present to satisfy the {@link BaseLlmRequestProcessor} interface.
+   */
   async *runAsync(invocationContext, _llmRequest) {
     for (const compactor of this.compactors) {
       const shouldCompact = await Promise.resolve(

package/dist/esm/agents/processors/identity_llm_request_processor.js

@@ -8,6 +8,13 @@ const require = topLevelCreateRequire(import.meta.url);
 import { appendInstructions } from "../../models/llm_request.js";
 import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
 class IdentityLlmRequestProcessor extends BaseLlmRequestProcessor {
+  /**
+   * Appends agent name and description as identity instructions to the system
+   * prompt of the request.
+   *
+   * @param invocationContext - The current invocation context.
+   * @param llmRequest - The request object to append instructions to.
+   */
   // eslint-disable-next-line require-yield
   async *runAsync(invocationContext, llmRequest) {
     const agent = invocationContext.agent;

package/dist/esm/agents/processors/instructions_llm_request_processor.js

@@ -47,6 +47,11 @@ class InstructionsLlmRequestProcessor extends BaseLlmRequestProcessor {
       }
       appendInstructions(llmRequest, [instructionWithState]);
     }
+    if (agent.outputSchema && agent.tools && agent.tools.length > 0) {
+      appendInstructions(llmRequest, [
+        'To output the final result, you must call the "set_model_response" function with the appropriate values. Do not output anything else.'
+      ]);
+    }
   }
 }
 const INSTRUCTIONS_LLM_REQUEST_PROCESSOR = new InstructionsLlmRequestProcessor();

package/dist/esm/agents/processors/request_confirmation_llm_request_processor.js

@@ -18,7 +18,15 @@ import { isLlmAgent } from "../llm_agent.js";
 import { ReadonlyContext } from "../readonly_context.js";
 import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
 class RequestConfirmationLlmRequestProcessor extends BaseLlmRequestProcessor {
-  /** Handles tool confirmation information to build the LLM request. */
+  /**
+   * Resumes tool calls that were paused for user confirmation, re-invoking
+   * them with the confirmed or denied decision before the next LLM turn.
+   *
+   * @param invocationContext - The current invocation context, including the
+   *   session event history used to locate pending confirmation responses.
+   * @yields Function response events for tools that have been confirmed and
+   *   are ready to resume.
+   */
   async *runAsync(invocationContext) {
     const agent = invocationContext.agent;
     if (!isLlmAgent(agent)) {

package/dist/esm/agents/processors/tool_filter_request_processor.js

@@ -10,7 +10,13 @@ import { isLlmAgent } from "../llm_agent.js";
 import { ReadonlyContext } from "../readonly_context.js";
 import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
 class ToolFilterRequestProcessor extends BaseLlmRequestProcessor {
-  /** Filters the set of tools on the request based on plugins. */
+  /**
+   * Invokes plugin-based tool filtering and updates {@link LlmRequest.allowedTools}
+   * with the reduced tool set if any plugin returns a filtered result.
+   *
+   * @param invocationContext - The current invocation context.
+   * @param llmRequest - The request whose allowed tools may be restricted.
+   */
   // eslint-disable-next-line require-yield
   async *runAsync(invocationContext, llmRequest) {
     const agent = invocationContext.agent;

package/dist/esm/auth/auth_preprocessor.js

@@ -17,6 +17,7 @@ import {
   getFunctionResponses
 } from "../events/event.js";
 import { State } from "../sessions/state.js";
+import { camelCaseKeys } from "../utils/case_utils.js";
 import { AuthHandler } from "./auth_handler.js";
 const TOOLSET_AUTH_CREDENTIAL_ID_PREFIX = "_adk_toolset_auth_";
 async function storeAuthAndCollectResumeTargets(events, authFcIds, authResponses, state) {
@@ -25,17 +26,15 @@ async function storeAuthAndCollectResumeTargets(events, authFcIds, authResponses
     const eventFunctionCalls = getFunctionCalls(event);
     for (const functionCall of eventFunctionCalls) {
       if (functionCall.id && authFcIds.has(functionCall.id) && functionCall.name === REQUEST_EUC_FUNCTION_CALL_NAME) {
-        const args = functionCall.args;
-        if (args && args.authConfig) {
-          requestedAuthConfigById[functionCall.id] = args.authConfig;
+        const args = camelCaseKeys(functionCall.args);
+        const authConfig = args == null ? void 0 : args.authConfig;
+        if (authConfig) {
+          requestedAuthConfigById[functionCall.id] = authConfig;
         }
       }
     }
   }
   for (const fcId of authFcIds) {
-    if (!(fcId in authResponses)) {
-      continue;
-    }
     const authConfig = authResponses[fcId];
     const requestedAuthConfig = requestedAuthConfigById[fcId];
     if (requestedAuthConfig && requestedAuthConfig.credentialKey) {
@@ -53,12 +52,15 @@ async function storeAuthAndCollectResumeTargets(events, authFcIds, authResponses
       const eventFunctionCalls = getFunctionCalls(event);
       for (const functionCall of eventFunctionCalls) {
         if (functionCall.id === fcId && functionCall.name === REQUEST_EUC_FUNCTION_CALL_NAME) {
-          const args = functionCall.args;
-          if (args && args.functionCallId) {
-            if (args.functionCallId.startsWith(TOOLSET_AUTH_CREDENTIAL_ID_PREFIX)) {
+          const args = camelCaseKeys(
+            functionCall.args
+          );
+          const functionCallId = args == null ? void 0 : args.functionCallId;
+          if (functionCallId) {
+            if (functionCallId.startsWith(TOOLSET_AUTH_CREDENTIAL_ID_PREFIX)) {
               continue;
             }
-            toolsToResume.add(args.functionCallId);
+            toolsToResume.add(functionCallId);
           }
         }
       }

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

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