@google/adk 0.3.0 → 0.5.0

package/dist/types/a2a/metadata_converter_utils.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event as AdkEvent } from '../events/event.js';
+import { EventActions as AdkEventActions } from '../events/event_actions.js';
+import { A2AEvent } from './a2a_event.js';
+/**
+ * Keys for metadata that will be stored in A2A message metadata and related to ADK events.
+ */
+export declare enum A2AMetadataKeys {
+    APP_NAME = "adk_app_name",
+    USER_ID = "adk_user_id",
+    SESSION_ID = "adk_session_id",
+    INVOCATION_ID = "adk_invocation_id",
+    AUTHOR = "adk_author",
+    BRANCH = "adk_branch",
+    DATA_PART_TYPE = "adk_type",
+    PARTIAL = "adk_partial",
+    ESCALATE = "adk_escalate",
+    TRANSFER_TO_AGENT = "adk_transfer_to_agent",
+    IS_LONG_RUNNING = "adk_is_long_running",
+    THOUGHT = "adk_thought",
+    ERROR_CODE = "adk_error_code",
+    ERROR_MESSAGE = "adk_error_message",
+    CITATION_METADATA = "adk_citation_metadata",
+    GROUNDING_METADATA = "adk_grounding_metadata",
+    USAGE_METADATA = "adk_usage_metadata",
+    CUSTOM_METADATA = "adk_custom_metadata"
+}
+/**
+ * Keys for metadata that will be stored in ADK event metadata and related to A2A messages.
+ */
+export declare enum AdkMetadataKeys {
+    TASK_ID = "a2a:task_id",
+    CONTEXT_ID = "a2a:context_id"
+}
+/**
+ * Creates ADK Event metadata from an A2A Event.
+ */
+export declare function getAdkEventMetadata(a2aEvent: A2AEvent): Record<string, unknown>;
+/**
+ * Creates A2A Event metadata from an ADK Event.
+ */
+export declare function getA2AEventMetadata(adkEvent: AdkEvent, { appName, userId, sessionId, }: {
+    appName: string;
+    userId: string;
+    sessionId: string;
+}): Record<string, unknown>;
+/**
+ * Creates A2A Session metadata from ADK Event invocation metadata.
+ */
+export declare function getA2ASessionMetadata({ appName, userId, sessionId, }: {
+    appName: string;
+    userId: string;
+    sessionId: string;
+}): Record<string, unknown>;
+/**
+ * Creates A2A Event metadata from ADK Event actions.
+ */
+export declare function getA2AEventMetadataFromActions(actions: AdkEventActions): Record<string, unknown>;

package/dist/types/a2a/part_converter_utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DataPart as A2ADataPart, FilePart as A2AFilePart, Part as A2APart, TextPart as A2ATextPart, Message } from '@a2a-js/sdk';
+import { Content as GenAIContent, Part as GenAIPart } from '@google/genai';
+/**
+ * Converts GenAI Parts to A2A Parts.
+ */
+export declare function toA2AParts(parts?: GenAIPart[], longRunningToolIDs?: string[]): A2APart[];
+/**
+ * Converts a GenAI Part to an A2A Part.
+ */
+export declare function toA2APart(part: GenAIPart, longRunningToolIDs?: string[]): A2APart;
+/**
+ * Converts a GenAI Text Part to an A2A Text Part.
+ */
+export declare function toA2ATextPart(part: GenAIPart): A2APart;
+/**
+ * Converts a GenAI File Part to an A2A File Part.
+ */
+export declare function toA2AFilePart(part: GenAIPart): A2APart;
+/**
+ * Converts a GenAI Data Part to an A2A Data Part.
+ */
+export declare function toA2ADataPart(part: GenAIPart, longRunningToolIDs?: string[]): A2APart;
+export declare function toGenAIContent(a2aMessage: Message): GenAIContent;
+/**
+ * Converts an A2A Part to a GenAI Part.
+ */
+export declare function toGenAIParts(a2aParts: A2APart[]): GenAIPart[];
+/**
+ * Converts an A2A Part to a GenAI Part.
+ */
+export declare function toGenAIPart(a2aPart: A2APart): GenAIPart;
+/**
+ * Converts an A2A Text Part to a GenAI Part.
+ */
+export declare function toGenAIPartText(a2aPart: A2ATextPart): GenAIPart;
+/**
+ * Converts an A2A File Part to a GenAI Part.
+ */
+export declare function toGenAIPartFile(a2aPart: A2AFilePart): GenAIPart;
+/**
+ * Converts an A2A Data Part to a GenAI Part.
+ */
+export declare function toGenAIPartData(a2aPart: A2ADataPart): GenAIPart;

package/dist/types/agents/base_agent.d.ts

@@ -5,12 +5,12 @@
  */
 import { Content } from '@google/genai';
 import { Event } from '../events/event.js';
-import { CallbackContext } from './callback_context.js';
+import { Context } from './context.js';
 import { InvocationContext } from './invocation_context.js';
 /**
  * A single callback function for an agent.
  */
-export type SingleAgentCallback = (context: CallbackContext) => Promise<Content | undefined> | (Content | undefined);
+export type SingleAgentCallback = (context: Context) => Promise<Content | undefined> | (Content | undefined);
 /**
  * Type for before agent callbacks, which can be a single callback or
  * an array of callbacks.

package/dist/types/{tools/tool_context.d.ts → agents/context.d.ts}

@@ -3,34 +3,69 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { CallbackContext } from '../agents/callback_context.js';
-import { InvocationContext } from '../agents/invocation_context.js';
+import { Part } from '@google/genai';
 import { AuthCredential } from '../auth/auth_credential.js';
 import { AuthConfig } from '../auth/auth_tool.js';
 import { EventActions } from '../events/event_actions.js';
 import { SearchMemoryResponse } from '../memory/base_memory_service.js';
+import { State } from '../sessions/state.js';
 import { ToolConfirmation } from '../tools/tool_confirmation.js';
-export declare class ToolContext extends CallbackContext {
+import { InvocationContext } from './invocation_context.js';
+import { ReadonlyContext } from './readonly_context.js';
+/**
+ * The context of various callbacks within an agent run.
+ *
+ * This class provides the context for callbacks and tool invocations, including
+ * access to the invocation context, function call ID, event actions, and
+ * authentication response. It also provides methods for requesting credentials,
+ * retrieving authentication responses, loading and saving artifacts, and
+ * searching memory.
+ */
+export declare class Context extends ReadonlyContext {
+    private readonly _state;
+    readonly eventActions: EventActions;
     readonly functionCallId?: string;
     toolConfirmation?: ToolConfirmation;
     /**
-     * @param params.invocationContext The invocation context of the tool.
-     * @param params.eventActions The event actions of the current tool call.
-     * @param params.functionCallId The function call id of the current tool call.
+     * @param options The configuration options for the Context.
+     * @param options.invocationContext The invocation context.
+     * @param options.eventActions The event actions of the current call.
+     * @param options.functionCallId The function call id of the current tool call.
      *     This id was returned in the function call event from LLM to identify a
      *     function call. If LLM didn't return this id, ADK will assign one to it.
      *     This id is used to map function call response to the original function
      *     call.
-     * @param params.toolConfirmation The tool confirmation of the current tool
+     * @param options.toolConfirmation The tool confirmation of the current tool
      *     call.
      */
-    constructor(params: {
+    constructor(options: {
         invocationContext: InvocationContext;
         eventActions?: EventActions;
         functionCallId?: string;
         toolConfirmation?: ToolConfirmation;
     });
+    /**
+     * The delta-aware state of the current session.
+     */
+    get state(): State;
     get actions(): EventActions;
+    /**
+     * Loads an artifact attached to the current session.
+     *
+     * @param filename The filename of the artifact.
+     * @param version The version of the artifact. If not provided, the latest
+     *     version will be used.
+     * @return A promise that resolves to the loaded artifact.
+     */
+    loadArtifact(filename: string, version?: number): Promise<Part | undefined>;
+    /**
+     * Saves an artifact attached to the current session.
+     *
+     * @param filename The filename of the artifact.
+     * @param artifact The artifact to save.
+     * @return A promise that resolves to the version of the saved artifact.
+     */
+    saveArtifact(filename: string, artifact: Part): Promise<number>;
     requestCredential(authConfig: AuthConfig): void;
     /**
      * Gets the auth credential for the given auth config.

package/dist/types/agents/llm_agent.d.ts

@@ -4,6 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { GenerateContentConfig, Schema } from '@google/genai';
+import { z as z3 } from 'zod/v3';
+import { z as z4 } from 'zod/v4';
 import { BaseCodeExecutor } from '../code_executors/base_code_executor.js';
 import { Event } from '../events/event.js';
 import { BaseExampleProvider } from '../examples/base_example_provider.js';
@@ -13,12 +15,15 @@ import { LlmRequest } from '../models/llm_request.js';
 import { LlmResponse } from '../models/llm_response.js';
 import { BaseTool } from '../tools/base_tool.js';
 import { BaseToolset } from '../tools/base_toolset.js';
-import { ToolContext } from '../tools/tool_context.js';
+import { Context } from './context.js';
 import { BaseAgent, BaseAgentConfig } from './base_agent.js';
-import { BaseLlmRequestProcessor, BaseLlmResponseProcessor } from './base_llm_processor.js';
-import { CallbackContext } from './callback_context.js';
+import { BaseLlmRequestProcessor, BaseLlmResponseProcessor } from './processors/base_llm_processor.js';
 import { InvocationContext } from './invocation_context.js';
 import { ReadonlyContext } from './readonly_context.js';
+/**
+ * Input/output schema type for agent.
+ */
+export type LlmAgentSchema = z3.ZodObject<z3.ZodRawShape> | z4.ZodObject<z4.ZodRawShape> | Schema;
 /** An object that can provide an instruction string. */
 export type InstructionProvider = (context: ReadonlyContext) => string | Promise<string>;
 /**
@@ -30,7 +35,7 @@ export type InstructionProvider = (context: ReadonlyContext) => string | Promise
  *     will be skipped and the provided content will be returned to user.
  */
 export type SingleBeforeModelCallback = (params: {
-    context: CallbackContext;
+    context: Context;
     request: LlmRequest;
 }) => LlmResponse | undefined | Promise<LlmResponse | undefined>;
 /**
@@ -50,7 +55,7 @@ export type BeforeModelCallback = SingleBeforeModelCallback | SingleBeforeModelC
  *     user.
  */
 export type SingleAfterModelCallback = (params: {
-    context: CallbackContext;
+    context: Context;
     response: LlmResponse;
 }) => LlmResponse | undefined | Promise<LlmResponse | undefined>;
 /**
@@ -65,14 +70,14 @@ export type AfterModelCallback = SingleAfterModelCallback | SingleAfterModelCall
  *
  * @param params.tool The tool to be called.
  * @param params.args The arguments to the tool.
- * @param params.context ToolContext for the tool call.
+ * @param params.context Context for the tool call.
  * @returns The tool response. When present, the returned tool response will
  *     be used and the framework will skip calling the actual tool.
  */
 export type SingleBeforeToolCallback = (params: {
     tool: BaseTool;
     args: Record<string, unknown>;
-    context: ToolContext;
+    context: Context;
 }) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
 /**
  * A single callback or a list of callbacks.
@@ -86,14 +91,14 @@ export type BeforeToolCallback = SingleBeforeToolCallback | SingleBeforeToolCall
  *
  * @param params.tool The tool to be called.
  * @param params.args The arguments to the tool.
- * @param params.context ToolContext for the tool call.
+ * @param params.context Context for the tool call.
  * @param params.response The response from the tool.
  * @returns When present, the returned record will be used as tool result.
  */
 export type SingleAfterToolCallback = (params: {
     tool: BaseTool;
     args: Record<string, unknown>;
-    context: ToolContext;
+    context: Context;
     response: Record<string, unknown>;
 }) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
 /**
@@ -159,15 +164,9 @@ export interface LlmAgentConfig extends BaseAgentConfig {
      */
     includeContents?: 'default' | 'none';
     /** The input schema when agent is used as a tool. */
-    inputSchema?: Schema;
-    /**
-     * The output schema when agent replies.
-     *
-     * NOTE:
-     *   When this is set, agent can ONLY reply and CANNOT use any tools, such as
-     *   function tools, RAGs, agent transfer, etc.
-     */
-    outputSchema?: Schema;
+    inputSchema?: LlmAgentSchema;
+    /** The output schema when agent replies. */
+    outputSchema?: LlmAgentSchema;
     /**
      * The key in session state to store the output of the agent.
      *
@@ -205,28 +204,6 @@ export interface LlmAgentConfig extends BaseAgentConfig {
      */
     codeExecutor?: BaseCodeExecutor;
 }
-declare class RequestConfirmationLlmRequestProcessor extends BaseLlmRequestProcessor {
-    /** Handles tool confirmation information to build the LLM request. */
-    runAsync(invocationContext: InvocationContext): AsyncGenerator<Event, void, void>;
-}
-export declare const REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR: RequestConfirmationLlmRequestProcessor;
-/**
- * Processor for code execution responses.
- */
-declare class CodeExecutionResponseProcessor implements BaseLlmResponseProcessor {
-    /**
-     * Processes the LLM response asynchronously.
-     *
-     * @param invocationContext The invocation context
-     * @param llmResponse The LLM response to process
-     * @returns An async generator yielding events
-     */
-    runAsync(invocationContext: InvocationContext, llmResponse: LlmResponse): AsyncGenerator<Event, void, unknown>;
-}
-/**
- * The exported response processor instance.
- */
-export declare const responseProcessor: CodeExecutionResponseProcessor;
 /**
  * A unique symbol to identify ADK agent classes.
  * Defined once and shared by all LlmAgent instances.
@@ -360,9 +337,9 @@ export declare class LlmAgent extends BaseAgent {
      * @throws Error if the agent is not found.
      */
     private getAgentByName;
-    private callLlmAsync;
+    protected callLlmAsync(invocationContext: InvocationContext, llmRequest: LlmRequest, modelResponseEvent: Event): AsyncGenerator<LlmResponse, void, void>;
     private handleBeforeModelCallback;
     private handleAfterModelCallback;
-    private runAndHandleError;
+    protected runAndHandleError<T extends LlmResponse | Event>(responseGenerator: AsyncGenerator<T, void, void>, invocationContext: InvocationContext, llmRequest: LlmRequest, modelResponseEvent: Event): AsyncGenerator<T, void, void>;
 }
 export {};

package/dist/types/agents/processors/agent_transfer_llm_request_processor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { LlmRequest } from '../../models/llm_request.js';
+import { InvocationContext } from '../invocation_context.js';
+import { BaseLlmRequestProcessor } from './base_llm_processor.js';
+export declare class AgentTransferLlmRequestProcessor extends BaseLlmRequestProcessor {
+    private readonly toolName;
+    private readonly tool;
+    runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+    private buildTargetAgentsInfo;
+    private buildTargetAgentsInstructions;
+    private getTransferTargets;
+}
+export declare const AGENT_TRANSFER_LLM_REQUEST_PROCESSOR: AgentTransferLlmRequestProcessor;

package/dist/types/agents/{base_llm_processor.d.ts → processors/base_llm_processor.d.ts}

@@ -3,10 +3,10 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { InvocationContext } from '../agents/invocation_context.js';
-import { Event } from '../events/event.js';
-import { LlmRequest } from '../models/llm_request.js';
-import { LlmResponse } from '../models/llm_response.js';
+import { Event } from '../../events/event.js';
+import { LlmRequest } from '../../models/llm_request.js';
+import { LlmResponse } from '../../models/llm_response.js';
+import { InvocationContext } from '../invocation_context.js';
 /**
  * Base class for LLM request processor.
  */

package/dist/types/agents/processors/basic_llm_request_processor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { LlmRequest } from '../../models/llm_request.js';
+import { InvocationContext } from '../invocation_context.js';
+import { BaseLlmRequestProcessor } from './base_llm_processor.js';
+export declare class BasicLlmRequestProcessor extends BaseLlmRequestProcessor {
+    runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+}
+export declare const BASIC_LLM_REQUEST_PROCESSOR: BasicLlmRequestProcessor;

package/dist/types/agents/processors/code_execution_request_processor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { LlmRequest } from '../../models/llm_request.js';
+import { LlmResponse } from '../../models/llm_response.js';
+import { InvocationContext } from '../invocation_context.js';
+import { BaseLlmRequestProcessor, BaseLlmResponseProcessor } from './base_llm_processor.js';
+/**
+ * Processes code execution requests.
+ */
+export declare class CodeExecutionRequestProcessor extends BaseLlmRequestProcessor {
+    runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+}
+/**
+ * Processor for code execution responses.
+ */
+export declare class CodeExecutionResponseProcessor implements BaseLlmResponseProcessor {
+    /**
+     * Processes the LLM response asynchronously.
+     *
+     * @param invocationContext The invocation context
+     * @param llmResponse The LLM response to process
+     * @returns An async generator yielding events
+     */
+    runAsync(invocationContext: InvocationContext, llmResponse: LlmResponse): AsyncGenerator<Event, void, unknown>;
+}
+/**
+ * The exported response processor instance.
+ */
+export declare const responseProcessor: CodeExecutionResponseProcessor;
+export declare const CODE_EXECUTION_REQUEST_PROCESSOR: CodeExecutionRequestProcessor;

package/dist/types/agents/processors/content_request_processor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { LlmRequest } from '../../models/llm_request.js';
+import { InvocationContext } from '../invocation_context.js';
+import { BaseLlmRequestProcessor } from './base_llm_processor.js';
+export declare class ContentRequestProcessor implements BaseLlmRequestProcessor {
+    runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+}
+export declare const CONTENT_REQUEST_PROCESSOR: ContentRequestProcessor;

package/dist/types/agents/processors/identity_llm_request_processor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { LlmRequest } from '../../models/llm_request.js';
+import { InvocationContext } from '../invocation_context.js';
+import { BaseLlmRequestProcessor } from './base_llm_processor.js';
+export declare class IdentityLlmRequestProcessor extends BaseLlmRequestProcessor {
+    runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, undefined>;
+}
+export declare const IDENTITY_LLM_REQUEST_PROCESSOR: IdentityLlmRequestProcessor;

package/dist/types/agents/processors/instructions_llm_request_processor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { LlmRequest } from '../../models/llm_request.js';
+import { InvocationContext } from '../invocation_context.js';
+import { BaseLlmRequestProcessor } from './base_llm_processor.js';
+export declare class InstructionsLlmRequestProcessor extends BaseLlmRequestProcessor {
+    /**
+     * Handles instructions and global instructions for LLM flow.
+     */
+    runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+}
+export declare const INSTRUCTIONS_LLM_REQUEST_PROCESSOR: InstructionsLlmRequestProcessor;

package/dist/types/agents/processors/request_confirmation_llm_request_processor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { InvocationContext } from '../invocation_context.js';
+import { BaseLlmRequestProcessor } from './base_llm_processor.js';
+export declare class RequestConfirmationLlmRequestProcessor extends BaseLlmRequestProcessor {
+    /** Handles tool confirmation information to build the LLM request. */
+    runAsync(invocationContext: InvocationContext): AsyncGenerator<Event, void, void>;
+}
+export declare const REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR: RequestConfirmationLlmRequestProcessor;

package/dist/types/agents/readonly_context.d.ts

@@ -20,6 +20,14 @@ export declare class ReadonlyContext {
      * The current invocation id.
      */
     get invocationId(): string;
+    /**
+     * The user ID of the current session.
+     */
+    get userId(): string;
+    /**
+     * The ID of the current session.
+     */
+    get sessionId(): string;
     /**
      * The current agent name.
      */

package/dist/types/agents/run_config.d.ts

@@ -72,6 +72,11 @@ export interface RunConfig {
      *   - Less than or equal to 0: This allows for unbounded number of llm calls.
      */
     maxLlmCalls?: number;
+    /**
+     * If true, the agent loop will suspend on ANY tool call, allowing the client
+     * to intercept and execute tools (Client-Side Tool Execution).
+     */
+    pauseOnToolCalls?: boolean;
 }
 export declare function createRunConfig(params?: Partial<RunConfig>): {
     speechConfig?: SpeechConfig | undefined;
@@ -85,4 +90,5 @@ export declare function createRunConfig(params?: Partial<RunConfig>): {
     proactivity?: ProactivityConfig | undefined;
     realtimeInputConfig?: RealtimeInputConfig | undefined;
     maxLlmCalls: number;
+    pauseOnToolCalls: boolean;
 };

package/dist/types/artifacts/base_artifact_service.d.ts

@@ -18,6 +18,10 @@ export interface SaveArtifactRequest {
     filename: string;
     /** The artifact to save. */
     artifact: Part;
+    /**
+     * Optional custom metadata to save with the artifact.
+     */
+    customMetadata?: Record<string, unknown>;
 }
 /**
  * The parameters for `loadArtifact`.
@@ -74,6 +78,19 @@ export interface ListVersionsRequest {
     /** The filename of the artifact. */
     filename: string;
 }
+/**
+ * Metadata for a file artifact version.
+ */
+export interface ArtifactVersion {
+    /** The version number. */
+    version: number;
+    /** The canonical URI of the artifact. */
+    canonicalUri?: string;
+    /** Custom metadata associated with the artifact. */
+    customMetadata?: Record<string, unknown>;
+    /** The MIME type of the artifact. */
+    mimeType?: string;
+}
 /**
  *  Interface for artifact services.
  */
@@ -124,4 +141,18 @@ export interface BaseArtifactService {
      *     artifact.
      */
     listVersions(request: ListVersionsRequest): Promise<number[]>;
+    /**
+     * Lists metadata for each artifact version.
+     *
+     * @param request The request to list artifact versions.
+     * @return A promise that resolves to a list of artifact version metadata.
+     */
+    listArtifactVersions(request: ListVersionsRequest): Promise<ArtifactVersion[]>;
+    /**
+     * Gets metadata for a specific artifact version.
+     *
+     * @param request The request to get an artifact version.
+     * @return A promise that resolves to the artifact version metadata or undefined.
+     */
+    getArtifactVersion(request: LoadArtifactRequest): Promise<ArtifactVersion | undefined>;
 }

package/dist/types/artifacts/file_artifact_service.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Part } from '@google/genai';
+import { ArtifactVersion, BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from './base_artifact_service.js';
+/**
+ * Service for managing artifacts stored on the local filesystem.
+ *
+ * Stores filesystem-backed artifacts beneath a configurable root directory.
+ *
+ * Storage layout matches the cloud and in-memory services:
+ * root/
+ * └── users/
+ *     └── {userId}/
+ *         ├── sessions/
+ *         │   └── {sessionId}/
+ *         │       └── artifacts/
+ *         │           └── {artifactPath}/  // derived from filename
+ *         │               └── versions/
+ *         │                   └── {version}/
+ *         │                       ├── {originalFilename}
+ *         │                       └── metadata.json
+ *         └── artifacts/
+ *             └── {artifactPath}/...
+ *
+ * Artifact paths are derived from the provided filenames: separators create
+ * nested directories, and path traversal is rejected to keep the layout
+ * portable across filesystems. `{artifactPath}` therefore mirrors the
+ * sanitized, scope-relative path derived from each filename.
+ */
+export declare class FileArtifactService implements BaseArtifactService {
+    private readonly rootDir;
+    constructor(rootDirOrUri: string);
+    saveArtifact({ userId, sessionId, filename, artifact, customMetadata, }: SaveArtifactRequest): Promise<number>;
+    loadArtifact({ userId, sessionId, filename, version, }: LoadArtifactRequest): Promise<Part | undefined>;
+    listArtifactKeys({ userId, sessionId, }: ListArtifactKeysRequest): Promise<string[]>;
+    deleteArtifact({ userId, sessionId, filename, }: DeleteArtifactRequest): Promise<void>;
+    listVersions({ userId, sessionId, filename, }: ListVersionsRequest): Promise<number[]>;
+    listArtifactVersions({ userId, sessionId, filename, }: ListVersionsRequest): Promise<ArtifactVersion[]>;
+    getArtifactVersion({ userId, sessionId, filename, version, }: LoadArtifactRequest): Promise<ArtifactVersion | undefined>;
+}

package/dist/types/artifacts/gcs_artifact_service.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Part } from '@google/genai';
-import { BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from './base_artifact_service.js';
+import { ArtifactVersion, BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from './base_artifact_service.js';
 export declare class GcsArtifactService implements BaseArtifactService {
     private readonly bucket;
     constructor(bucket: string);
@@ -13,4 +13,6 @@ export declare class GcsArtifactService implements BaseArtifactService {
     listArtifactKeys(request: ListArtifactKeysRequest): 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/artifacts/in_memory_artifact_service.d.ts

@@ -4,15 +4,18 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Part } from '@google/genai';
-import { BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from './base_artifact_service.js';
+import { ArtifactVersion, BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from './base_artifact_service.js';
+export declare function isInMemoryConnectionString(uri: string): boolean;
 /**
  * An in-memory implementation of the ArtifactService.
  */
 export declare class InMemoryArtifactService implements BaseArtifactService {
     private readonly artifacts;
-    saveArtifact({ appName, userId, sessionId, filename, artifact, }: SaveArtifactRequest): Promise<number>;
+    saveArtifact({ appName, userId, sessionId, filename, artifact, customMetadata, }: SaveArtifactRequest): Promise<number>;
     loadArtifact({ appName, userId, sessionId, filename, version, }: LoadArtifactRequest): Promise<Part | undefined>;
     listArtifactKeys({ appName, userId, sessionId, }: ListArtifactKeysRequest): Promise<string[]>;
     deleteArtifact({ appName, userId, sessionId, filename, }: DeleteArtifactRequest): Promise<void>;
     listVersions({ appName, userId, sessionId, filename, }: ListVersionsRequest): Promise<number[]>;
+    listArtifactVersions({ appName, userId, sessionId, filename, }: ListVersionsRequest): Promise<ArtifactVersion[]>;
+    getArtifactVersion({ appName, userId, sessionId, filename, version, }: LoadArtifactRequest): Promise<ArtifactVersion | undefined>;
 }