@google/adk 0.3.0 → 0.4.0

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

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { HttpOptions } from '@google/genai';
+import { BaseLlmConnection } from './base_llm_connection.js';
+import { Gemini, GeminiParams } from './google_llm.js';
+import { LlmRequest } from './llm_request.js';
+import { LlmResponse } from './llm_response.js';
+export interface ApigeeLlmParams extends GeminiParams {
+    /**
+     * The name of the model to use. The model string specifies the LLM provider
+     * (e.g., Vertex AI, Gemini), API version, and the model ID. Supported format:
+     *     `apigee/[<provider>/][<version>/]<model_id>`
+     *     Components:
+     *       `provider` (optional): `vertex_ai` or `gemini`.
+     *       `version` (optional): The API version (e.g., `v1`, `v1beta`). If not
+     *         provided, a default version will selected based on the provider.
+     *       `model_id` (required): The model identifier (e.g.,
+     *         `gemini-2.5-flash`).
+     *     Examples:
+     *       - `apigee/gemini-2.5-flash`
+     *       - `apigee/v1/gemini-2.5-flash`
+     *       - `apigee/vertex_ai/gemini-2.5-flash`
+     *       - `apigee/gemini/v1/gemini-2.5-flash`
+     *       - `apigee/vertex_ai/v1beta/gemini-2.5-flash`
+     */
+    model: string;
+    /**
+     * The proxy URL for the provider API. If not provided, it will look for
+     * the APIGEE_PROXY_URL environment variable.
+     */
+    proxyUrl?: string;
+    /**
+     * API key to use. If not provided, it will look for
+     * the GOOGLE_GENAI_API_KEY or GEMINI_API_KEY environment variable. If gemini
+     * provider is selected and no key is provided, the fake key "-" will be
+     * used for the "x-goog-api-key" header.
+     */
+    apiKey?: string;
+}
+export declare class ApigeeLlm extends Gemini {
+    private readonly proxyUrl;
+    /**
+     * A list of model name patterns that are supported by this LLM.
+     *
+     * @returns A list of supported models.
+     */
+    static readonly supportedModels: Array<string | RegExp>;
+    constructor({ model, proxyUrl, apiKey, vertexai, location, project, headers, }: ApigeeLlmParams);
+    protected getHttpOptions(): HttpOptions;
+    protected getLiveHttpOptions(): HttpOptions;
+    private identifyApiVersion;
+    private _apigeeLiveApiVersion?;
+    get liveApiVersion(): string;
+    generateContentAsync(llmRequest: LlmRequest, stream?: boolean): AsyncGenerator<LlmResponse, void>;
+    connect(llmRequest: LlmRequest): Promise<BaseLlmConnection>;
+}

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

@@ -3,7 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { GoogleGenAI } from '@google/genai';
+import { GoogleGenAI, HttpOptions } from '@google/genai';
 import { GoogleLLMVariant } from '../utils/variant_utils.js';
 import { BaseLlm } from './base_llm.js';
 import { BaseLlmConnection } from './base_llm_connection.js';
@@ -45,7 +45,7 @@ export interface GeminiParams {
  */
 export declare class Gemini extends BaseLlm {
     private readonly apiKey?;
-    private readonly vertexai;
+    protected readonly vertexai: boolean;
     private readonly project?;
     private readonly location?;
     private readonly headers?;
@@ -72,9 +72,11 @@ export declare class Gemini extends BaseLlm {
      * @yields LlmResponse: The model response.
      */
     generateContentAsync(llmRequest: LlmRequest, stream?: boolean): AsyncGenerator<LlmResponse, void>;
+    protected getHttpOptions(): HttpOptions;
     get apiClient(): GoogleGenAI;
     get apiBackend(): GoogleLLMVariant;
     get liveApiVersion(): string;
+    protected getLiveHttpOptions(): HttpOptions;
     get liveApiClient(): GoogleGenAI;
     /**
      * Connects to the Gemini model and returns an llm connection.
@@ -85,3 +87,4 @@ export declare class Gemini extends BaseLlm {
     connect(llmRequest: LlmRequest): Promise<BaseLlmConnection>;
     private preprocessRequest;
 }
+export declare function geminiInitParams({ model, vertexai, project, location, apiKey, }: GeminiParams): GeminiParams;

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

@@ -40,6 +40,21 @@ export declare class Runner {
     readonly memoryService?: BaseMemoryService;
     readonly credentialService?: BaseCredentialService;
     constructor(input: RunnerConfig);
+    /**
+     * Runs the agent with a new, ephemeral session.
+     *
+     * @param params.userId The user ID of the session.
+     * @param params.newMessage A new message to append to the session.
+     * @param params.stateDelta An optional state delta to apply to the session.
+     * @param params.runConfig The run config for the agent.
+     * @yields The Events generated by the agent.
+     */
+    runEphemeral(params: {
+        userId: string;
+        newMessage: Content;
+        stateDelta?: Record<string, unknown>;
+        runConfig?: RunConfig;
+    }): AsyncGenerator<Event, void, undefined>;
     /**
      * Runs the agent with the given message, and returns an async generator of
      * events.

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

@@ -99,6 +99,13 @@ export declare abstract class BaseSessionService {
      *     found.
      */
     abstract getSession(request: GetSessionRequest): Promise<Session | undefined>;
+    /**
+     * Gets a session or creates one if it doesn't exist.
+     *
+     * @param request The request to get or create a session.
+     * @return A promise that resolves to the session instance.
+     */
+    getOrCreateSession(request: CreateSessionRequest): Promise<Session>;
     /**
      * Lists sessions for a user.
      *
@@ -127,3 +134,16 @@ export declare abstract class BaseSessionService {
      */
     private updateSessionState;
 }
+/**
+ * Removes temporary state delta keys from the event.
+ */
+export declare function trimTempDeltaState(event: Event): Event;
+/**
+ * Merges app state, user state, and session state.
+ *
+ * @param appState The application state.
+ * @param userState The user state.
+ * @param sessionState The session state.
+ * @return The merged state.
+ */
+export declare function mergeStates(appState?: Record<string, unknown>, userState?: Record<string, unknown>, sessionState?: Record<string, unknown>): Record<string, unknown>;

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

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Options as MikroDBOptions } from '@mikro-orm/core';
+import { Event } from '../events/event.js';
+import { AppendEventRequest, BaseSessionService, CreateSessionRequest, DeleteSessionRequest, GetSessionRequest, ListSessionsRequest, ListSessionsResponse } from './base_session_service.js';
+import { Session } from './session.js';
+/**
+ * Checks if a URI is a database connection URI.
+ *
+ * @param uri The URI to check.
+ * @returns True if the URI is a database connection URI, false otherwise.
+ */
+export declare function isDatabaseConnectionString(uri?: string): boolean;
+/**
+ * A session service that uses a SQL database for storage via MikroORM.
+ */
+export declare class DatabaseSessionService extends BaseSessionService {
+    private orm?;
+    private initialized;
+    private options;
+    constructor(connectionStringOrOptions: MikroDBOptions | string);
+    init(): Promise<void>;
+    createSession({ appName, userId, state, sessionId, }: CreateSessionRequest): Promise<Session>;
+    getSession({ appName, userId, sessionId, config, }: GetSessionRequest): Promise<Session | undefined>;
+    listSessions({ appName, userId, }: ListSessionsRequest): Promise<ListSessionsResponse>;
+    deleteSession({ appName, userId, sessionId, }: DeleteSessionRequest): Promise<void>;
+    appendEvent({ session, event, }: AppendEventRequest): Promise<Event>;
+}

package/dist/types/sessions/db/operations.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MikroORM, Options as MikroORMOptions } from '@mikro-orm/core';
+/**
+ * Parses a database connection URI and returns MikroORM Options.
+ *
+ * @param uri The database connection URI (e.g., "postgres://user:password@host:port/database")
+ * @returns MikroORM Options configured for the database
+ * @throws Error if the URI is invalid or unsupported
+ */
+export declare function getConnectionOptionsFromUri(uri: string): MikroORMOptions;
+/**
+ * Creates a database and tables if they don't exist.
+ *
+ * @param url The database connection URI (e.g., "postgres://user:password@host:port/database")
+ * @returns Promise<void>
+ * @throws Error if the URI is invalid or unsupported
+ */
+export declare function ensureDatabaseCreated(ormOrUrlOrOptions: MikroORM | MikroORMOptions | string): Promise<void>;
+/**
+ * Validates the schema version.
+ *
+ * @param orm The MikroORM instance.
+ * @throws Error if the schema version is not compatible.
+ */
+export declare function validateDatabaseSchemaVersion(orm: MikroORM): Promise<void>;

package/dist/types/sessions/db/schema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { PrimaryKey } from '@mikro-orm/core';
+import { Event } from '../../events/event.js';
+export declare const SCHEMA_VERSION_KEY = "schema_version";
+export declare const SCHEMA_VERSION_1_JSON = "1";
+export declare class StorageMetadata {
+    key: string;
+    value: string;
+}
+export declare class StorageAppState {
+    appName: string;
+    state: Record<string, unknown>;
+    updateTime: Date;
+}
+export declare class StorageUserState {
+    [PrimaryKey.name]?: [string, string] | undefined;
+    appName: string;
+    userId: string;
+    state: Record<string, unknown>;
+    updateTime: Date;
+}
+export declare class StorageSession {
+    [PrimaryKey.name]?: [string, string, string] | undefined;
+    id: string;
+    appName: string;
+    userId: string;
+    state: Record<string, unknown>;
+    createTime: Date;
+    updateTime: Date;
+}
+export declare class StorageEvent {
+    [PrimaryKey.name]?: [string, string, string, string] | undefined;
+    id: string;
+    appName: string;
+    userId: string;
+    sessionId: string;
+    invocationId: string;
+    timestamp: Date;
+    eventData: Event;
+}
+export declare const ENTITIES: (typeof StorageMetadata | typeof StorageAppState | typeof StorageEvent)[];

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

@@ -1,6 +1,10 @@
 import { Event } from '../events/event.js';
 import { AppendEventRequest, BaseSessionService, CreateSessionRequest, DeleteSessionRequest, GetSessionRequest, ListSessionsRequest, ListSessionsResponse } from './base_session_service.js';
 import { Session } from './session.js';
+/**
+ * Checks if the given URI is an in-memory memory service URI.
+ */
+export declare function isInMemoryConnectionString(uri?: string): boolean;
 /**
  * An in-memory implementation of the session service.
  */
@@ -23,5 +27,4 @@ export declare class InMemorySessionService extends BaseSessionService {
     listSessions({ appName, userId, }: ListSessionsRequest): Promise<ListSessionsResponse>;
     deleteSession({ appName, userId, sessionId, }: DeleteSessionRequest): Promise<void>;
     appendEvent({ session, event, }: AppendEventRequest): Promise<Event>;
-    private mergeState;
 }

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

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseSessionService } from './base_session_service.js';
+export declare function getSessionServiceFromUri(uri: string): BaseSessionService;

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 { BaseArtifactService, DeleteArtifactRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from '../artifacts/base_artifact_service.js';
+import { ArtifactVersion, BaseArtifactService, DeleteArtifactRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from '../artifacts/base_artifact_service.js';
 import { ToolContext } from './tool_context.js';
 /**
  * Artifact service that forwards to the parent tool context.
@@ -18,4 +18,6 @@ export declare class ForwardingArtifactService implements BaseArtifactService {
     listArtifactKeys(): Promise<string[]>;
     deleteArtifact(request: DeleteArtifactRequest): Promise<void>;
     listVersions(request: ListVersionsRequest): Promise<number[]>;
+    listArtifactVersions(request: ListVersionsRequest): Promise<ArtifactVersion[]>;
+    getArtifactVersion(request: LoadArtifactRequest): Promise<ArtifactVersion | undefined>;
 }

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

@@ -29,3 +29,10 @@ export declare function base64Decode(data: string): string;
  * @return True if the string is base64-encoded, false otherwise.
  */
 export declare function isBase64Encoded(data: string): boolean;
+/**
+ * Gets the boolean value of the given environment variable.
+ *
+ * @param envVar The environment variable to get the value of.
+ * @return The boolean value of the environment variable.
+ */
+export declare function getBooleanEnvVar(envVar: string): boolean;

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

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Converts an object with snake_case keys to camelCase keys.
+ *
+ * @param obj The object to convert.
+ * @param preserveKeys Keys to preserve in their original form.
+ * @returns The object with camelCase keys.
+ */
+export declare function toCamelCase(obj: unknown, preserveKeys?: string[]): unknown;
+/**
+ * Converts an object with camelCase keys to snake_case keys.
+ *
+ * @param obj The object to convert.
+ * @param preserveKeys Keys to preserve in their original form.
+ * @returns The object with snake_case keys.
+ */
+export declare function toSnakeCase(obj: unknown, preserveKeys?: string[]): unknown;

package/dist/types/version.d.ts

@@ -3,4 +3,4 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-export declare const version = "0.3.0";
+export declare const version = "0.4.0";

package/dist/web/a2a/part_converter_utils.js

@@ -0,0 +1,171 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var MetadataKeys = /* @__PURE__ */ ((MetadataKeys2) => {
+  MetadataKeys2["TYPE"] = "adk_type";
+  MetadataKeys2["LONG_RUNNING"] = "adk_is_long_running";
+  MetadataKeys2["THOUGHT"] = "adk_thought";
+  return MetadataKeys2;
+})(MetadataKeys || {});
+var DataPartType = /* @__PURE__ */ ((DataPartType2) => {
+  DataPartType2["FUNCTION_CALL"] = "function_call";
+  DataPartType2["FUNCTION_RESPONSE"] = "function_response";
+  DataPartType2["CODE_EXEC_RESULT"] = "code_execution_result";
+  DataPartType2["CODE_EXECUTABLE_CODE"] = "executable_code";
+  return DataPartType2;
+})(DataPartType || {});
+function toA2AParts(parts, longRunningToolIDs = []) {
+  return parts.map((part) => toA2APart(part, longRunningToolIDs));
+}
+function toA2APart(part, longRunningToolIDs) {
+  if (part.text !== void 0 && part.text !== null) {
+    return toA2ATextPart(part);
+  }
+  if (part.inlineData || part.fileData) {
+    return toA2AFilePart(part);
+  }
+  return toA2ADataPart(part, longRunningToolIDs);
+}
+function toA2ATextPart(part) {
+  const a2aPart = { kind: "text", text: part.text || "" };
+  if ("thought" in part && part["thought"]) {
+    a2aPart.metadata = {
+      ["adk_thought" /* THOUGHT */]: true
+    };
+  }
+  return a2aPart;
+}
+function toA2AFilePart(part) {
+  if (part.fileData) {
+    return {
+      kind: "file",
+      file: {
+        uri: part.fileData.fileUri || "",
+        mimeType: part.fileData.mimeType
+      },
+      metadata: {}
+    };
+  }
+  if (part.inlineData) {
+    return {
+      kind: "file",
+      file: {
+        bytes: part.inlineData.data || "",
+        mimeType: part.inlineData.mimeType
+      },
+      metadata: {}
+    };
+  }
+  throw new Error("Not a file part: ".concat(JSON.stringify(part)));
+}
+function toA2ADataPart(part, longRunningToolIDs = []) {
+  let type;
+  let data;
+  if (part.functionCall) {
+    type = "function_call" /* FUNCTION_CALL */;
+    data = part.functionCall;
+  } else if (part.functionResponse) {
+    type = "function_response" /* FUNCTION_RESPONSE */;
+    data = part.functionResponse;
+  } else if (part.executableCode) {
+    type = "executable_code" /* CODE_EXECUTABLE_CODE */;
+    data = part.executableCode;
+  } else if (part.codeExecutionResult) {
+    type = "code_execution_result" /* CODE_EXEC_RESULT */;
+    data = part.codeExecutionResult;
+  } else {
+    throw new Error("Unknown part type: ".concat(JSON.stringify(part)));
+  }
+  const metadata = {
+    ["adk_type" /* TYPE */]: type
+  };
+  if (part.functionCall && part.functionCall.name && longRunningToolIDs.includes(part.functionCall.name)) {
+    metadata["adk_is_long_running" /* LONG_RUNNING */] = true;
+  }
+  if (part.functionResponse && part.functionResponse.name && longRunningToolIDs.includes(part.functionResponse.name)) {
+    metadata["adk_is_long_running" /* LONG_RUNNING */] = true;
+  }
+  return {
+    kind: "data",
+    data,
+    metadata
+  };
+}
+function toGenAIParts(a2aParts) {
+  return a2aParts.map((a2aPart) => toGenAIPart(a2aPart));
+}
+function toGenAIPart(a2aPart) {
+  if (a2aPart.kind === "text") {
+    return toGenAIPartText(a2aPart);
+  }
+  if (a2aPart.kind === "file") {
+    return toGenAIPartFile(a2aPart);
+  }
+  if (a2aPart.kind === "data") {
+    return toGenAIPartData(a2aPart);
+  }
+  throw new Error("Unknown part kind: ".concat(JSON.stringify(a2aPart)));
+}
+function toGenAIPartText(a2aPart) {
+  var _a;
+  return {
+    text: a2aPart.text,
+    thought: !!((_a = a2aPart.metadata) == null ? void 0 : _a["adk_thought" /* THOUGHT */])
+  };
+}
+function toGenAIPartFile(a2aPart) {
+  if ("bytes" in a2aPart.file) {
+    return {
+      inlineData: {
+        data: a2aPart.file.bytes,
+        mimeType: a2aPart.file.mimeType || ""
+      }
+    };
+  }
+  if ("uri" in a2aPart.file) {
+    return {
+      fileData: {
+        fileUri: a2aPart.file.uri,
+        mimeType: a2aPart.file.mimeType || ""
+      }
+    };
+  }
+  throw new Error("Not a file part: ".concat(JSON.stringify(a2aPart)));
+}
+function toGenAIPartData(a2aPart) {
+  var _a;
+  if (!a2aPart.data) {
+    throw new Error("No data in part: ".concat(JSON.stringify(a2aPart)));
+  }
+  const data = a2aPart.data;
+  const type = (_a = a2aPart.metadata) == null ? void 0 : _a["adk_type" /* TYPE */];
+  if (type === "function_call" /* FUNCTION_CALL */) {
+    return { functionCall: data };
+  }
+  if (type === "function_response" /* FUNCTION_RESPONSE */) {
+    return { functionResponse: data };
+  }
+  if (type === "executable_code" /* CODE_EXECUTABLE_CODE */) {
+    return { executableCode: data };
+  }
+  if (type === "code_execution_result" /* CODE_EXEC_RESULT */) {
+    return { codeExecutionResult: data };
+  }
+  return {
+    text: JSON.stringify(a2aPart.data)
+  };
+}
+export {
+  toA2ADataPart,
+  toA2AFilePart,
+  toA2APart,
+  toA2AParts,
+  toA2ATextPart,
+  toGenAIPart,
+  toGenAIPartData,
+  toGenAIPartFile,
+  toGenAIPartText,
+  toGenAIParts
+};

package/dist/web/agents/base_agent.js

@@ -311,7 +311,7 @@ class BaseAgent {
 function validateAgentName(name) {
   if (!isIdentifier(name)) {
     throw new Error(
-      'Found invalid agent name: "'.concat(name, '". Agent name must be a valid identifier. It should start with a letter (a-z, A-Z) or an underscore (_), and can only contain letters, digits (0-9), and underscores.')
+      'Found invalid agent name: "'.concat(name, '". Agent name must be a valid identifier. It should start with a letter (a-z, A-Z) or an underscore (_), and can only contain letters, digits (0-9), underscores, and hyphens.')
     );
   }
   if (name === "user") {
@@ -322,7 +322,7 @@ function validateAgentName(name) {
   return name;
 }
 function isIdentifier(str) {
-  return new RegExp("^[\\p{ID_Start}$_][\\p{ID_Continue}$_]*$", "u").test(str);
+  return new RegExp("^[\\p{ID_Start}$_][\\p{ID_Continue}$_-]*$", "u").test(str);
 }
 function getRootAgent(rootAgent) {
   while (rootAgent.parentAgent) {

package/dist/web/agents/functions.js

@@ -128,6 +128,7 @@ function generateRequestConfirmationEvent({
       parts,
       role: functionResponseEvent.content.role
     },
+    actions: functionResponseEvent.actions,
     longRunningToolIds: Array.from(longRunningToolIds)
   });
 }