@google/adk 0.3.0 → 0.5.0

package/dist/types/plugins/security_plugin.d.ts

@@ -4,10 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { FunctionCall } from '@google/genai';
+import { Context } from '../agents/context.js';
 import { Event } from '../events/event.js';
 import { BasePlugin } from '../plugins/base_plugin.js';
 import { BaseTool } from '../tools/base_tool.js';
-import { ToolContext } from '../tools/tool_context.js';
 export declare const REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation";
 /**
  * The outcome of a policy check.
@@ -44,7 +44,7 @@ export declare class SecurityPlugin extends BasePlugin {
         toolArgs: {
             [key: string]: unknown;
         };
-        toolContext: ToolContext;
+        toolContext: Context;
     }): Promise<{
         [key: string]: unknown;
     } | undefined>;

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,32 @@
+/**
+ * @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?;
+    private connectionString?;
+    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): Promise<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/base_tool.d.ts

@@ -5,19 +5,19 @@
  */
 import { FunctionDeclaration } from '@google/genai';
 import { LlmRequest } from '../models/llm_request.js';
-import { ToolContext } from './tool_context.js';
+import { Context } from '../agents/context.js';
 /**
  * The parameters for `runAsync`.
  */
 export interface RunAsyncToolRequest {
     args: Record<string, unknown>;
-    toolContext: ToolContext;
+    toolContext: Context;
 }
 /**
  * The parameters for `processLlmRequest`.
  */
 export interface ToolProcessLlmRequest {
-    toolContext: ToolContext;
+    toolContext: Context;
     llmRequest: LlmRequest;
 }
 /**

package/dist/types/tools/base_toolset.d.ts

@@ -5,14 +5,20 @@
  */
 import { ReadonlyContext } from '../agents/readonly_context.js';
 import { LlmRequest } from '../models/llm_request.js';
+import { Context } from '../agents/context.js';
 import { BaseTool } from './base_tool.js';
-import { ToolContext } from './tool_context.js';
 /**
  * Function to decide whether a tool should be exposed to LLM. Toolset
  * implementer could consider whether to accept such instance in the toolset's
  * constructor and apply the predicate in getTools method.
  */
 export type ToolPredicate = (tool: BaseTool, readonlyContext: ReadonlyContext) => boolean;
+/**
+ * A unique symbol to identify ADK agent classes.
+ * Defined once and shared by all BaseTool instances.
+ */
+declare const BASE_TOOLSET_SIGNATURE_SYMBOL: unique symbol;
+export declare function isBaseToolset(obj: unknown): obj is BaseToolset;
 /**
  * Base class for toolset.
  *
@@ -20,7 +26,9 @@ export type ToolPredicate = (tool: BaseTool, readonlyContext: ReadonlyContext) =
  */
 export declare abstract class BaseToolset {
     readonly toolFilter: ToolPredicate | string[];
-    constructor(toolFilter: ToolPredicate | string[]);
+    readonly prefix?: string | undefined;
+    readonly [BASE_TOOLSET_SIGNATURE_SYMBOL] = true;
+    constructor(toolFilter: ToolPredicate | string[], prefix?: string | undefined);
     /**
      * Returns the tools that should be exposed to LLM.
      *
@@ -60,6 +68,7 @@ export declare abstract class BaseToolset {
      * @param toolContext The context of the tool.
      * @param llmRequest The outgoing LLM request, mutable this method.
      */
-    processLlmRequest(toolContext: ToolContext, // eslint-disable-line @typescript-eslint/no-unused-vars
+    processLlmRequest(toolContext: Context, // eslint-disable-line @typescript-eslint/no-unused-vars
     llmRequest: LlmRequest): Promise<void>;
 }
+export {};

package/dist/types/tools/exit_loop_tool.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration } from '@google/genai';
+import { BaseTool, RunAsyncToolRequest } from './base_tool.js';
+/**
+ * Tool for exiting execution of a {@link LoopAgent}.
+ *
+ * When called by an LLM agent inside a LoopAgent, this tool sets the
+ * `escalate` and `skipSummarization` flags on the event actions,
+ * causing the LoopAgent to stop iterating and exit the loop.
+ *
+ */
+export declare class ExitLoopTool extends BaseTool {
+    constructor();
+    _getDeclaration(): FunctionDeclaration;
+    runAsync({ toolContext, }: RunAsyncToolRequest): Promise<unknown>;
+}
+/**
+ * A global instance of {@link ExitLoopTool}.
+ */
+export declare const EXIT_LOOP: ExitLoopTool;

package/dist/types/tools/forwarding_artifact_service.d.ts

@@ -4,18 +4,20 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Part } from '@google/genai';
-import { BaseArtifactService, DeleteArtifactRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from '../artifacts/base_artifact_service.js';
-import { ToolContext } from './tool_context.js';
+import { ArtifactVersion, BaseArtifactService, DeleteArtifactRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from '../artifacts/base_artifact_service.js';
+import { Context } from '../agents/context.js';
 /**
  * Artifact service that forwards to the parent tool context.
  */
 export declare class ForwardingArtifactService implements BaseArtifactService {
     private readonly toolContext;
     private readonly invocationContext;
-    constructor(toolContext: ToolContext);
+    constructor(toolContext: Context);
     saveArtifact(request: SaveArtifactRequest): Promise<number>;
     loadArtifact(request: LoadArtifactRequest): Promise<Part | undefined>;
     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/tools/function_tool.d.ts

@@ -6,14 +6,14 @@
 import { FunctionDeclaration, Schema } from '@google/genai';
 import { z as z3 } from 'zod/v3';
 import { z as z4 } from 'zod/v4';
+import { Context } from '../agents/context.js';
 import { BaseTool, RunAsyncToolRequest } from './base_tool.js';
-import { ToolContext } from './tool_context.js';
 /**
  * Input parameters of the function tool.
  */
 export type ToolInputParameters = z3.ZodObject<z3.ZodRawShape> | z4.ZodObject<z4.ZodRawShape> | Schema | undefined;
 export type ToolExecuteArgument<TParameters extends ToolInputParameters> = TParameters extends z3.ZodObject<infer T, infer U, infer V> ? z3.infer<z3.ZodObject<T, U, V>> : TParameters extends z4.ZodObject<infer T> ? z4.infer<z4.ZodObject<T>> : TParameters extends Schema ? unknown : string;
-export type ToolExecuteFunction<TParameters extends ToolInputParameters> = (input: ToolExecuteArgument<TParameters>, tool_context?: ToolContext) => Promise<unknown> | unknown;
+export type ToolExecuteFunction<TParameters extends ToolInputParameters> = (input: ToolExecuteArgument<TParameters>, tool_context?: Context) => Promise<unknown> | unknown;
 /**
  * The configuration options for creating a function-based tool.
  * The `name`, `description` and `parameters` fields are used to generate the

package/dist/types/tools/mcp/mcp_toolset.d.ts

@@ -32,7 +32,7 @@ import { MCPConnectionParams } from './mcp_session_manager.js';
  */
 export declare class MCPToolset extends BaseToolset {
     private readonly mcpSessionManager;
-    constructor(connectionParams: MCPConnectionParams, toolFilter?: ToolPredicate | string[]);
+    constructor(connectionParams: MCPConnectionParams, toolFilter?: ToolPredicate | string[], prefix?: string);
     getTools(): Promise<BaseTool[]>;
     close(): Promise<void>;
 }

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

@@ -1,8 +1,3 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
 /** Log levels for the logger. */
 export declare enum LogLevel {
     DEBUG = 0,
@@ -19,11 +14,8 @@ export interface Logger {
     info(...args: unknown[]): void;
     warn(...args: unknown[]): void;
     error(...args: unknown[]): void;
+    setLogLevel(level: LogLevel): void;
 }
-/**
- * Sets the log level for the logger.
- */
-export declare function setLogLevel(level: LogLevel): void;
 /**
  * Sets a custom logger for ADK, or null to disable logging.
  */
@@ -36,6 +28,10 @@ export declare function getLogger(): Logger;
  * Resets the logger to the default SimpleLogger.
  */
 export declare function resetLogger(): void;
+/**
+ * Sets the log level for the logger.
+ */
+export declare function setLogLevel(level: LogLevel): void;
 /**
  * The logger instance for ADK.
  */

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.5.0";

package/dist/web/a2a/a2a_event.js

@@ -0,0 +1,243 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from "../utils/env_aware_utils.js";
+var MessageRole = /* @__PURE__ */ ((MessageRole2) => {
+  MessageRole2["USER"] = "user";
+  MessageRole2["AGENT"] = "agent";
+  return MessageRole2;
+})(MessageRole || {});
+function isTaskStatusUpdateEvent(event) {
+  return (event == null ? void 0 : event.kind) === "status-update";
+}
+function isTaskArtifactUpdateEvent(event) {
+  return (event == null ? void 0 : event.kind) === "artifact-update";
+}
+function isMessage(event) {
+  return (event == null ? void 0 : event.kind) === "message";
+}
+function isTask(event) {
+  return (event == null ? void 0 : event.kind) === "task";
+}
+function getEventMetadata(event) {
+  if (isTaskArtifactUpdateEvent(event)) {
+    return event.artifact.metadata || {};
+  }
+  if (isTaskStatusUpdateEvent(event) || isTask(event) || isMessage(event)) {
+    return event.metadata || {};
+  }
+  return {};
+}
+function isFailedTaskStatusUpdateEvent(event) {
+  return (isTaskStatusUpdateEvent(event) || isTask(event)) && event.status.state === "failed";
+}
+function isTerminalTaskStatusUpdateEvent(event) {
+  return (isTaskStatusUpdateEvent(event) || isTask(event)) && ["completed", "failed", "canceled", "rejected"].includes(event.status.state);
+}
+function isInputRequiredTaskStatusUpdateEvent(event) {
+  return (isTaskStatusUpdateEvent(event) || isTask(event)) && event.status.state === "input-required";
+}
+function getFailedTaskStatusUpdateEventError(event) {
+  var _a;
+  if (!isFailedTaskStatusUpdateEvent(event)) {
+    return void 0;
+  }
+  const parts = ((_a = event.status.message) == null ? void 0 : _a.parts) || [];
+  if (parts.length === 0) {
+    return void 0;
+  }
+  if (parts[0].kind !== "text") {
+    return void 0;
+  }
+  return parts[0].text;
+}
+function createTaskSubmittedEvent({
+  taskId,
+  contextId,
+  message
+}) {
+  return {
+    kind: "status-update",
+    taskId,
+    contextId,
+    final: false,
+    status: {
+      state: "submitted",
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function createTask({
+  contextId,
+  message,
+  taskId
+}) {
+  return {
+    kind: "task",
+    id: taskId || randomUUID(),
+    contextId,
+    history: [message],
+    status: {
+      state: "submitted",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function createTaskWorkingEvent({
+  taskId,
+  contextId,
+  message
+}) {
+  return {
+    kind: "status-update",
+    taskId,
+    contextId,
+    final: false,
+    status: {
+      state: "working",
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function createTaskCompletedEvent({
+  taskId,
+  contextId,
+  metadata = {}
+}) {
+  return {
+    kind: "status-update",
+    taskId,
+    contextId,
+    final: true,
+    status: {
+      state: "completed",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    metadata
+  };
+}
+function createTaskArtifactUpdateEvent({
+  taskId,
+  contextId,
+  artifactId,
+  parts = [],
+  metadata,
+  append,
+  lastChunk
+}) {
+  return {
+    kind: "artifact-update",
+    taskId,
+    contextId,
+    append,
+    lastChunk,
+    artifact: {
+      artifactId: artifactId || randomUUID(),
+      parts,
+      metadata
+    }
+  };
+}
+function createTaskFailedEvent({
+  taskId,
+  contextId,
+  error,
+  metadata
+}) {
+  return {
+    kind: "status-update",
+    taskId,
+    contextId,
+    status: {
+      state: "failed",
+      message: {
+        kind: "message",
+        messageId: randomUUID(),
+        role: "agent",
+        taskId,
+        contextId,
+        parts: [
+          {
+            kind: "text",
+            text: error.message
+          }
+        ]
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    metadata,
+    final: true
+  };
+}
+function createTaskInputRequiredEvent({
+  taskId,
+  contextId,
+  parts
+}) {
+  return {
+    kind: "status-update",
+    taskId,
+    contextId,
+    final: true,
+    status: {
+      state: "input-required",
+      message: {
+        kind: "message",
+        messageId: randomUUID(),
+        role: "agent",
+        taskId,
+        contextId,
+        parts
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function createInputMissingErrorEvent({
+  taskId,
+  contextId,
+  parts
+}) {
+  return {
+    kind: "status-update",
+    taskId,
+    contextId,
+    final: true,
+    status: {
+      state: "input-required",
+      message: {
+        kind: "message",
+        messageId: randomUUID(),
+        role: "agent",
+        taskId,
+        contextId,
+        parts
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+export {
+  MessageRole,
+  createInputMissingErrorEvent,
+  createTask,
+  createTaskArtifactUpdateEvent,
+  createTaskCompletedEvent,
+  createTaskFailedEvent,
+  createTaskInputRequiredEvent,
+  createTaskSubmittedEvent,
+  createTaskWorkingEvent,
+  getEventMetadata,
+  getFailedTaskStatusUpdateEventError,
+  isFailedTaskStatusUpdateEvent,
+  isInputRequiredTaskStatusUpdateEvent,
+  isMessage,
+  isTask,
+  isTaskArtifactUpdateEvent,
+  isTaskStatusUpdateEvent,
+  isTerminalTaskStatusUpdateEvent
+};