@google/adk 0.3.0 → 0.5.0

package/dist/esm/artifacts/gcs_artifact_service.js

@@ -5,11 +5,15 @@
  */
 import { Storage } from "@google-cloud/storage";
 import { createPartFromBase64, createPartFromText } from "@google/genai";
+import { logger } from "../utils/logger.js";
 class GcsArtifactService {
   constructor(bucket) {
     this.bucket = new Storage().bucket(bucket);
   }
   async saveArtifact(request) {
+    if (!request.artifact.inlineData && !request.artifact.text) {
+      throw new Error("Artifact must have either inlineData or text content.");
+    }
     const versions = await this.listVersions(request);
     const version = versions.length > 0 ? Math.max(...versions) + 1 : 0;
     const file = this.bucket.file(
@@ -18,62 +22,69 @@ class GcsArtifactService {
         version
       })
     );
+    const metadata = request.customMetadata || {};
     if (request.artifact.inlineData) {
-      await file.save(JSON.stringify(request.artifact.inlineData.data), {
-        contentType: request.artifact.inlineData.mimeType
-      });
-      return version;
-    }
-    if (request.artifact.text) {
-      await file.save(request.artifact.text, {
-        contentType: "text/plain"
-      });
+      await file.save(
+        Buffer.from(request.artifact.inlineData.data || "", "base64"),
+        {
+          contentType: request.artifact.inlineData.mimeType,
+          metadata
+        }
+      );
       return version;
     }
-    throw new Error("Artifact must have either inlineData or text.");
+    await file.save(request.artifact.text, {
+      contentType: "text/plain",
+      metadata
+    });
+    return version;
   }
   async loadArtifact(request) {
-    let version = request.version;
-    if (version === void 0) {
-      const versions = await this.listVersions(request);
-      if (versions.length === 0) {
-        return void 0;
+    try {
+      let version = request.version;
+      if (version === void 0) {
+        const versions = await this.listVersions(request);
+        if (versions.length === 0) {
+          return void 0;
+        }
+        version = Math.max(...versions);
       }
-      version = Math.max(...versions);
-    }
-    const file = this.bucket.file(
-      getFileName({
-        ...request,
-        version
-      })
-    );
-    const [[metadata], [rawDataBuffer]] = await Promise.all([
-      file.getMetadata(),
-      file.download()
-    ]);
-    if (metadata.contentType === "text/plain") {
-      return createPartFromText(rawDataBuffer.toString("utf-8"));
+      const file = this.bucket.file(
+        getFileName({
+          ...request,
+          version
+        })
+      );
+      const [[metadata], [rawDataBuffer]] = await Promise.all([
+        file.getMetadata(),
+        file.download()
+      ]);
+      if (metadata.contentType === "text/plain") {
+        return createPartFromText(rawDataBuffer.toString("utf-8"));
+      }
+      return createPartFromBase64(
+        rawDataBuffer.toString("base64"),
+        metadata.contentType
+      );
+    } catch (e) {
+      logger.warn(
+        `[GcsArtifactService] loadArtifact: Failed to load artifact ${request.filename}`,
+        e
+      );
+      return void 0;
     }
-    return createPartFromBase64(
-      rawDataBuffer.toString("base64"),
-      metadata.contentType
-    );
   }
   async listArtifactKeys(request) {
-    const fileNames = [];
     const sessionPrefix = `${request.appName}/${request.userId}/${request.sessionId}/`;
     const usernamePrefix = `${request.appName}/${request.userId}/user/`;
     const [[sessionFiles], [userSessionFiles]] = await Promise.all([
       this.bucket.getFiles({ prefix: sessionPrefix }),
       this.bucket.getFiles({ prefix: usernamePrefix })
     ]);
-    for (const file of sessionFiles) {
-      fileNames.push(file.name.split("/").pop());
-    }
-    for (const file of userSessionFiles) {
-      fileNames.push(file.name.split("/").pop());
-    }
-    return fileNames.sort((a, b) => a.localeCompare(b));
+    return [
+      ...extractArtifactKeys(sessionFiles, sessionPrefix),
+      ...extractArtifactKeys(userSessionFiles, usernamePrefix, "user:")
+    ].sort((a, b) => a.localeCompare(b));
   }
   async deleteArtifact(request) {
     const versions = await this.listVersions(request);
@@ -92,13 +103,62 @@ class GcsArtifactService {
   }
   async listVersions(request) {
     const prefix = getFileName(request);
-    const [files] = await this.bucket.getFiles({ prefix });
+    const searchPrefix = prefix + "/";
+    const [files] = await this.bucket.getFiles({ prefix: searchPrefix });
     const versions = [];
     for (const file of files) {
       const version = file.name.split("/").pop();
-      versions.push(parseInt(version, 10));
+      const v = parseInt(version, 10);
+      if (!isNaN(v)) {
+        versions.push(v);
+      }
+    }
+    return versions.sort((a, b) => a - b);
+  }
+  async listArtifactVersions(request) {
+    const versions = await this.listVersions(request);
+    const artifactVersions = [];
+    for (const version of versions) {
+      const artifactVersion = await this.getArtifactVersion({
+        ...request,
+        version
+      });
+      if (artifactVersion) {
+        artifactVersions.push(artifactVersion);
+      }
+    }
+    return artifactVersions;
+  }
+  async getArtifactVersion(request) {
+    try {
+      let version = request.version;
+      if (version === void 0) {
+        const versions = await this.listVersions(request);
+        if (versions.length === 0) {
+          return void 0;
+        }
+        version = Math.max(...versions);
+      }
+      const file = this.bucket.file(
+        getFileName({
+          ...request,
+          version
+        })
+      );
+      const [metadata] = await file.getMetadata();
+      return {
+        version,
+        mimeType: metadata.contentType,
+        customMetadata: metadata.metadata,
+        canonicalUri: file.publicUrl()
+      };
+    } catch (e) {
+      logger.warn(
+        `[GcsArtifactService] getArtifactVersion: Failed to get artifact version for userId: ${request.userId} sessionId: ${request.sessionId} filename: ${request.filename} version: ${request.version}`,
+        e
+      );
+      return void 0;
     }
-    return versions;
   }
 }
 function getFileName({
@@ -108,10 +168,29 @@ function getFileName({
   filename,
   version
 }) {
-  if (filename.startsWith("user:")) {
-    return `${appName}/${userId}/user/${filename}/${version}`;
+  const isUser = filename.startsWith("user:");
+  const cleanFilename = isUser ? filename.substring(5) : filename;
+  const prefix = isUser ? `${appName}/${userId}/user/${cleanFilename}` : `${appName}/${userId}/${sessionId}/${cleanFilename}`;
+  return version !== void 0 ? `${prefix}/${version}` : prefix;
+}
+function extractArtifactKeys(files, fileNamePrefix, keyPrefix = "") {
+  const keys = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    if (!file.name.startsWith(fileNamePrefix)) {
+      continue;
+    }
+    const relative = file.name.substring(fileNamePrefix.length);
+    const name = getFileNameFromPath(relative);
+    keys.add(`${keyPrefix}${name}`);
+  }
+  return [...keys];
+}
+function getFileNameFromPath(filePath) {
+  const parts = filePath.split("/");
+  if (parts.length < 2) {
+    return filePath;
   }
-  return `${appName}/${userId}/${sessionId}/${filename}/${version}`;
+  return parts.slice(0, -1).join("/");
 }
 export {
   GcsArtifactService

package/dist/esm/artifacts/in_memory_artifact_service.js

@@ -3,6 +3,9 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+function isInMemoryConnectionString(uri) {
+  return uri === "memory://";
+}
 class InMemoryArtifactService {
   constructor() {
     this.artifacts = {};
@@ -12,14 +15,24 @@ class InMemoryArtifactService {
     userId,
     sessionId,
     filename,
-    artifact
+    artifact,
+    customMetadata
   }) {
+    if (!artifact.inlineData && !artifact.text) {
+      return Promise.reject(
+        new Error("Artifact must have either inlineData or text content.")
+      );
+    }
     const path = artifactPath(appName, userId, sessionId, filename);
     if (!this.artifacts[path]) {
       this.artifacts[path] = [];
     }
     const version = this.artifacts[path].length;
-    this.artifacts[path].push(artifact);
+    const metadata = {
+      version,
+      customMetadata
+    };
+    this.artifacts[path].push({ part: artifact, metadata });
     return Promise.resolve(version);
   }
   loadArtifact({
@@ -37,7 +50,7 @@ class InMemoryArtifactService {
     if (version === void 0) {
       version = versions.length - 1;
     }
-    return Promise.resolve(versions[version]);
+    return Promise.resolve(versions[version].part);
   }
   listArtifactKeys({
     appName,
@@ -88,6 +101,39 @@ class InMemoryArtifactService {
     }
     return Promise.resolve(versions);
   }
+  listArtifactVersions({
+    appName,
+    userId,
+    sessionId,
+    filename
+  }) {
+    const path = artifactPath(appName, userId, sessionId, filename);
+    const artifacts = this.artifacts[path];
+    if (!artifacts) {
+      return Promise.resolve([]);
+    }
+    return Promise.resolve(artifacts.map((a) => a.metadata));
+  }
+  getArtifactVersion({
+    appName,
+    userId,
+    sessionId,
+    filename,
+    version
+  }) {
+    const path = artifactPath(appName, userId, sessionId, filename);
+    const versions = this.artifacts[path];
+    if (!versions) {
+      return Promise.resolve(void 0);
+    }
+    if (version === void 0) {
+      version = versions.length - 1;
+    }
+    if (versions[version]) {
+      return Promise.resolve(versions[version].metadata);
+    }
+    return Promise.resolve(void 0);
+  }
 }
 function artifactPath(appName, userId, sessionId, filename) {
   if (fileHasUserNamespace(filename)) {
@@ -99,5 +145,6 @@ function fileHasUserNamespace(filename) {
   return filename.startsWith("user:");
 }
 export {
-  InMemoryArtifactService
+  InMemoryArtifactService,
+  isInMemoryConnectionString
 };

package/dist/esm/artifacts/registry.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FileArtifactService } from "./file_artifact_service.js";
+import { GcsArtifactService } from "./gcs_artifact_service.js";
+import {
+  InMemoryArtifactService,
+  isInMemoryConnectionString
+} from "./in_memory_artifact_service.js";
+function getArtifactServiceFromUri(uri) {
+  if (isInMemoryConnectionString(uri)) {
+    return new InMemoryArtifactService();
+  }
+  if (uri.startsWith("gs://")) {
+    const bucket = uri.split("://")[1];
+    return new GcsArtifactService(bucket);
+  }
+  if (uri.startsWith("file://")) {
+    const rootDir = uri.split("://")[1];
+    return new FileArtifactService(rootDir);
+  }
+  throw new Error(`Unsupported artifact service URI: ${uri}`);
+}
+export {
+  getArtifactServiceFromUri
+};

package/dist/esm/common.js

@@ -5,17 +5,17 @@
  */
 import { ActiveStreamingTool } from "./agents/active_streaming_tool.js";
 import { BaseAgent, isBaseAgent } from "./agents/base_agent.js";
-import {
-  BaseLlmRequestProcessor,
-  BaseLlmResponseProcessor
-} from "./agents/base_llm_processor.js";
-import { CallbackContext } from "./agents/callback_context.js";
+import { Context } from "./agents/context.js";
 import { functionsExportedForTestingOnly } from "./agents/functions.js";
 import { InvocationContext } from "./agents/invocation_context.js";
 import { LiveRequestQueue } from "./agents/live_request_queue.js";
 import { LlmAgent, isLlmAgent } from "./agents/llm_agent.js";
 import { LoopAgent, isLoopAgent } from "./agents/loop_agent.js";
 import { ParallelAgent, isParallelAgent } from "./agents/parallel_agent.js";
+import {
+  BaseLlmRequestProcessor,
+  BaseLlmResponseProcessor
+} from "./agents/processors/base_llm_processor.js";
 import { ReadonlyContext } from "./agents/readonly_context.js";
 import { StreamingMode } from "./agents/run_config.js";
 import { SequentialAgent, isSequentialAgent } from "./agents/sequential_agent.js";
@@ -32,13 +32,15 @@ import {
   stringifyContent
 } from "./events/event.js";
 import { createEventActions } from "./events/event_actions.js";
+import { EventType, toStructuredEvents } from "./events/structured_events.js";
 import {
   BaseExampleProvider,
   isBaseExampleProvider
 } from "./examples/base_example_provider.js";
 import { InMemoryMemoryService } from "./memory/in_memory_memory_service.js";
+import { ApigeeLlm } from "./models/apigee_llm.js";
 import { BaseLlm, isBaseLlm } from "./models/base_llm.js";
-import { Gemini } from "./models/google_llm.js";
+import { Gemini, geminiInitParams } from "./models/google_llm.js";
 import { LLMRegistry } from "./models/registry.js";
 import { BasePlugin } from "./plugins/base_plugin.js";
 import { LoggingPlugin } from "./plugins/logging_plugin.js";
@@ -52,17 +54,18 @@ import {
 } from "./plugins/security_plugin.js";
 import { InMemoryRunner } from "./runner/in_memory_runner.js";
 import { Runner } from "./runner/runner.js";
+import { BaseSessionService } from "./sessions/base_session_service.js";
 import { InMemorySessionService } from "./sessions/in_memory_session_service.js";
 import { createSession } from "./sessions/session.js";
 import { State } from "./sessions/state.js";
 import { AgentTool, isAgentTool } from "./tools/agent_tool.js";
 import { BaseTool, isBaseTool } from "./tools/base_tool.js";
-import { BaseToolset } from "./tools/base_toolset.js";
+import { BaseToolset, isBaseToolset } from "./tools/base_toolset.js";
+import { EXIT_LOOP, ExitLoopTool } from "./tools/exit_loop_tool.js";
 import { FunctionTool, isFunctionTool } from "./tools/function_tool.js";
 import { GOOGLE_SEARCH, GoogleSearchTool } from "./tools/google_search_tool.js";
 import { LongRunningFunctionTool } from "./tools/long_running_tool.js";
 import { ToolConfirmation } from "./tools/tool_confirmation.js";
-import { ToolContext } from "./tools/tool_context.js";
 import { LogLevel, getLogger, setLogLevel, setLogger } from "./utils/logger.js";
 import { isGemini2OrAbove } from "./utils/model_name.js";
 import { zodObjectToSchema } from "./utils/simple_zod_to_json.js";
@@ -75,6 +78,7 @@ export * from "./tools/base_tool.js";
 export {
   ActiveStreamingTool,
   AgentTool,
+  ApigeeLlm,
   AuthCredentialTypes,
   BaseAgent,
   BaseCodeExecutor,
@@ -83,10 +87,14 @@ export {
   BaseLlmRequestProcessor,
   BaseLlmResponseProcessor,
   BasePlugin,
+  BaseSessionService,
   BaseTool,
   BaseToolset,
   BuiltInCodeExecutor,
-  CallbackContext,
+  Context,
+  EXIT_LOOP,
+  EventType,
+  ExitLoopTool,
   FunctionTool,
   GOOGLE_SEARCH,
   Gemini,
@@ -116,11 +124,11 @@ export {
   State,
   StreamingMode,
   ToolConfirmation,
-  ToolContext,
   createEvent,
   createEventActions,
   createSession,
   functionsExportedForTestingOnly,
+  geminiInitParams,
   getAskUserConfirmationFunctionCalls,
   getFunctionCalls,
   getFunctionResponses,
@@ -131,6 +139,7 @@ export {
   isBaseExampleProvider,
   isBaseLlm,
   isBaseTool,
+  isBaseToolset,
   isFinalResponse,
   isFunctionTool,
   isGemini2OrAbove,
@@ -141,6 +150,7 @@ export {
   setLogLevel,
   setLogger,
   stringifyContent,
+  toStructuredEvents,
   version,
   zodObjectToSchema
 };

package/dist/esm/events/event.js

@@ -1,8 +1,9 @@
 /**
  * @license
- * Copyright 2025 Google LLC
+ * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { toCamelCase, toSnakeCase } from "../utils/object_notation_utils.js";
 import { createEventActions } from "./event_actions.js";
 function createEvent(params = {}) {
   return {
@@ -70,6 +71,30 @@ function createNewEventId() {
   }
   return id;
 }
+const PRESERVE_KEYS_CAMEL_CASE = [
+  "actions.stateDelta",
+  "actions.artifactDelta",
+  "actions.requestedAuthConfigs",
+  "actions.requestedToolConfirmations",
+  "actions.customMetadata",
+  "content.parts.functionCall.args",
+  "content.parts.functionResponse.response"
+];
+const PRESERVE_KEYS_SNAKE_CASE = [
+  "actions.state_delta",
+  "actions.artifact_delta",
+  "actions.requested_auth_configs",
+  "actions.requested_tool_confirmations",
+  "actions.custom_metadata",
+  "content.parts.function_call.args",
+  "content.parts.function_response.response"
+];
+function transformToCamelCaseEvent(event) {
+  return toCamelCase(event, PRESERVE_KEYS_SNAKE_CASE);
+}
+function transformToSnakeCaseEvent(event) {
+  return toSnakeCase(event, PRESERVE_KEYS_CAMEL_CASE);
+}
 export {
   createEvent,
   createNewEventId,
@@ -77,5 +102,7 @@ export {
   getFunctionResponses,
   hasTrailingCodeExecutionResult,
   isFinalResponse,
-  stringifyContent
+  stringifyContent,
+  transformToCamelCaseEvent,
+  transformToSnakeCaseEvent
 };

package/dist/esm/events/event_actions.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2025 Google LLC
+ * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
 function createEventActions(state = {}) {

package/dist/esm/events/structured_events.js

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isEmpty } from "lodash-es";
+import { isFinalResponse } from "./event.js";
+var EventType = /* @__PURE__ */ ((EventType2) => {
+  EventType2["THOUGHT"] = "thought";
+  EventType2["CONTENT"] = "content";
+  EventType2["TOOL_CALL"] = "tool_call";
+  EventType2["TOOL_RESULT"] = "tool_result";
+  EventType2["CALL_CODE"] = "call_code";
+  EventType2["CODE_RESULT"] = "code_result";
+  EventType2["ERROR"] = "error";
+  EventType2["ACTIVITY"] = "activity";
+  EventType2["TOOL_CONFIRMATION"] = "tool_confirmation";
+  EventType2["FINISHED"] = "finished";
+  return EventType2;
+})(EventType || {});
+function toStructuredEvents(event) {
+  var _a, _b;
+  const structuredEvents = [];
+  if (event.errorCode) {
+    structuredEvents.push({
+      type: "error" /* ERROR */,
+      error: new Error(event.errorMessage || event.errorCode)
+    });
+    return structuredEvents;
+  }
+  for (const part of (_b = (_a = event.content) == null ? void 0 : _a.parts) != null ? _b : []) {
+    if (part.functionCall && !isEmpty(part.functionCall)) {
+      structuredEvents.push({
+        type: "tool_call" /* TOOL_CALL */,
+        call: part.functionCall
+      });
+    } else if (part.functionResponse && !isEmpty(part.functionResponse)) {
+      structuredEvents.push({
+        type: "tool_result" /* TOOL_RESULT */,
+        result: part.functionResponse
+      });
+    } else if (part.executableCode && !isEmpty(part.executableCode)) {
+      structuredEvents.push({
+        type: "call_code" /* CALL_CODE */,
+        code: part.executableCode
+      });
+    } else if (part.codeExecutionResult && !isEmpty(part.codeExecutionResult)) {
+      structuredEvents.push({
+        type: "code_result" /* CODE_RESULT */,
+        result: part.codeExecutionResult
+      });
+    } else if (part.text) {
+      if (part.thought) {
+        structuredEvents.push({ type: "thought" /* THOUGHT */, content: part.text });
+      } else {
+        structuredEvents.push({ type: "content" /* CONTENT */, content: part.text });
+      }
+    }
+  }
+  if (event.actions.requestedToolConfirmations && !isEmpty(event.actions.requestedToolConfirmations)) {
+    structuredEvents.push({
+      type: "tool_confirmation" /* TOOL_CONFIRMATION */,
+      confirmations: event.actions.requestedToolConfirmations
+    });
+  }
+  if (isFinalResponse(event)) {
+    structuredEvents.push({ type: "finished" /* FINISHED */, output: void 0 });
+  }
+  return structuredEvents;
+}
+export {
+  EventType,
+  toStructuredEvents
+};