@softactivate/adk 1.1.0

package/dist/types/features/feature_registry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Feature names.
+ */
+export declare enum FeatureName {
+    PROGRESSIVE_SSE_STREAMING = "PROGRESSIVE_SSE_STREAMING"
+}
+/**
+ * Feature lifecycle stages.
+ */
+export declare enum FeatureStage {
+    WIP = "wip",
+    EXPERIMENTAL = "experimental",
+    STABLE = "stable"
+}
+/**
+ * Feature configuration.
+ */
+export interface FeatureConfig {
+    stage: FeatureStage;
+    defaultOn: boolean;
+}
+/**
+ * Get the configuration of a feature from the registry.
+ *
+ * @param featureName The feature name.
+ * @returns The feature config from the registry, or undefined if not found.
+ */
+export declare function getFeatureConfig(featureName: FeatureName): FeatureConfig | undefined;
+/**
+ * Register a feature with a specific config.
+ *
+ * @param featureName The feature name.
+ * @param config The feature config to register.
+ */
+export declare function registerFeature(featureName: FeatureName, config: FeatureConfig): void;
+/**
+ * Programmatically override a feature's enabled state.
+ *
+ * This override takes highest priority, superseding environment variables
+ * and registry defaults.
+ *
+ * @param featureName The feature name to override.
+ * @param enabled Whether the feature should be enabled.
+ */
+export declare function overrideFeatureEnabled(featureName: FeatureName, enabled: boolean | undefined): void;
+/**
+ * Check if a feature is enabled at runtime.
+ *
+ * Priority order (highest to lowest):
+ * 1. Programmatic overrides
+ * 2. Environment variables (ADK_ENABLE_* / ADK_DISABLE_*)
+ * 3. Registry defaults
+ *
+ * @param featureName The feature name.
+ * @returns True if the feature is enabled, false otherwise.
+ */
+export declare function isFeatureEnabled(featureName: FeatureName): boolean;
+/**
+ * Temporarily overrides a feature for the duration of a callback.
+ */
+export declare function withTemporaryFeatureOverride<T>(featureName: FeatureName, enabled: boolean, callback: () => Promise<T> | T): Promise<T>;

package/dist/types/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export { AGENT_CARD_PATH, RemoteA2AAgent } from './a2a/a2a_remote_agent.js';
+export type { A2AStreamEventData, AfterA2ARequestCallback, BeforeA2ARequestCallback, RemoteA2AAgentConfig, } from './a2a/a2a_remote_agent.js';
+export { getA2AAgentCard } from './a2a/agent_card.js';
+export { A2AAgentExecutor } from './a2a/agent_executor.js';
+export type { AfterEventCallback, AfterExecuteCallback, AgentExecutorConfig, BeforeExecuteCallback, RunnerOrRunnerConfig, } from './a2a/agent_executor.js';
+export { toA2a } from './a2a/agent_to_a2a.js';
+export type { ToA2aOptions } from './a2a/agent_to_a2a.js';
+export type { ExecutorContext } from './a2a/executor_context.js';
+export { FileArtifactService } from './artifacts/file_artifact_service.js';
+export { GcsArtifactService } from './artifacts/gcs_artifact_service.js';
+export { getArtifactServiceFromUri } from './artifacts/registry.js';
+export { UnsafeLocalCodeExecutor, type UnsafeLocalCodeExecutorOptions, } from './code_executors/unsafe_local_code_executor.js';
+export * from './common.js';
+export { DatabaseSessionService } from './sessions/database_session_service.js';
+export { getSessionServiceFromUri } from './sessions/registry.js';
+export { loadAllSkillsInDir, loadSkillFromDir, validateSkillDir, } from './skills/loader.js';
+export { RunSkillInlineScriptTool } from './tools/skill/run_skill_inline_script_tool.js';
+export { RunSkillScriptTool } from './tools/skill/run_skill_script_tool.js';
+export * from './telemetry/google_cloud.js';
+export * from './telemetry/setup.js';
+export * from './tools/mcp/mcp_session_manager.js';
+export * from './tools/mcp/mcp_tool.js';
+export * from './tools/mcp/mcp_toolset.js';

package/dist/types/index_web.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from './common.js';

package/dist/types/memory/base_memory_service.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Session } from '../sessions/session.js';
+import { MemoryEntry } from './memory_entry.js';
+/**
+ * Represents the response from a memory search.
+ */
+export interface SearchMemoryResponse {
+    /**
+     * A list of memory entries that are related to the search query.
+     */
+    memories: MemoryEntry[];
+}
+/**
+ * The parameters for `searchMemory`.
+ */
+export interface SearchMemoryRequest {
+    /** The app name associated with the memory to search. */
+    appName: string;
+    /** The user ID whose memory is being searched. */
+    userId: string;
+    /**
+     * The natural language query used to retrieve relevant memories.
+     * Implementations may use keyword matching or semantic search.
+     */
+    query: string;
+}
+/**
+ * Base interface for memory services.
+ *
+ * The service provides functionalities to ingest sessions into memory so that
+ * the memory can be used for user queries.
+ */
+export interface BaseMemoryService {
+    /**
+     * Adds a session to the memory.
+     *
+     * @param session The session to add to the memory.
+     * @return A promise that resolves when the session is added to the memory.
+     */
+    addSessionToMemory(session: Session): Promise<void>;
+    /**
+     * Searches for sessions that match the query.
+     *
+     * @param request The request to search memory.
+     * @return A promise that resolves to SearchMemoryResponse containing the
+     *     matching memories.
+     */
+    searchMemory(request: SearchMemoryRequest): Promise<SearchMemoryResponse>;
+}

package/dist/types/memory/in_memory_memory_service.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Session } from '../sessions/session.js';
+import { BaseMemoryService, SearchMemoryRequest, SearchMemoryResponse } from './base_memory_service.js';
+/**
+ * An in-memory memory service for prototyping purpose only.
+ *
+ * Uses keyword matching instead of semantic search.
+ */
+export declare class InMemoryMemoryService implements BaseMemoryService {
+    private readonly memories;
+    private readonly sessionEvents;
+    addSessionToMemory(session: Session): Promise<void>;
+    searchMemory(req: SearchMemoryRequest): Promise<SearchMemoryResponse>;
+}

package/dist/types/memory/memory_entry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+/**
+ * Represents one memory entry retrieved from a memory service.
+ *
+ * Memory entries are created from session events and surfaced to the agent
+ * to provide relevant context from past interactions.
+ */
+export interface MemoryEntry {
+    /**
+     * The content of the memory entry, as originally produced during a session.
+     */
+    content: Content;
+    /**
+     * The author of the memory. Common values are `'user'` and `'model'`, but
+     * this can also be the name of an agent when the content was produced by a
+     * named sub-agent.
+     */
+    author?: string;
+    /**
+     * The time when the original content was produced.
+     * Forwarded to the LLM as part of the memory context.
+     * Preferred format is ISO 8601 (e.g. `'2024-01-15T10:30:00.000Z'`).
+     */
+    timestamp?: string;
+}

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, abortSignal?: AbortSignal): AsyncGenerator<LlmResponse, void>;
+    connect(llmRequest: LlmRequest): Promise<BaseLlmConnection>;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseLlmConnection } from './base_llm_connection.js';
+import { LlmRequest } from './llm_request.js';
+import { LlmResponse } from './llm_response.js';
+/**
+ * A unique symbol to identify BaseLlm classes.
+ * Defined once and shared by all BaseLlm instances.
+ */
+declare const BASE_MODEL_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of BaseLlm.
+ * @param obj The object to check.
+ * @returns True if the object is an instance of BaseLlm, false otherwise.
+ */
+export declare function isBaseLlm(obj: unknown): obj is BaseLlm;
+/**
+ * The BaseLLM class.
+ */
+export declare abstract class BaseLlm {
+    /**
+     * A unique symbol to identify BaseLlm classes.
+     */
+    readonly [BASE_MODEL_SYMBOL] = true;
+    readonly model: string;
+    /**
+     * Creates an instance of BaseLLM.
+     * @param params The parameters for creating a BaseLlm instance.
+     * @param params.model The name of the LLM, e.g. gemini-1.5-flash or
+     *     gemini-1.5-flash-001.
+     */
+    constructor({ model }: {
+        model: string;
+    });
+    /**
+     * List of supported models in regex for LlmRegistry.
+     */
+    static readonly supportedModels: Array<string | RegExp>;
+    /**
+     * Generates one content from the given contents and tools.
+     *
+     * @param llmRequest  LlmRequest, the request to send to the LLM.
+     * @param stream whether to do streaming call.
+     * For non-streaming call, it will only yield one Content.
+     * @return A generator of LlmResponse.
+     */
+    abstract generateContentAsync(llmRequest: LlmRequest, stream?: boolean, abortSignal?: AbortSignal): AsyncGenerator<LlmResponse, void>;
+    /**
+     * Creates a live connection to the LLM.
+     *
+     * @param llmRequest LlmRequest, the request to send to the LLM.
+     * @return A live connection to the LLM.
+     */
+    abstract connect(llmRequest: LlmRequest): Promise<BaseLlmConnection>;
+    protected get trackingHeaders(): Record<string, string>;
+    /**
+     * Appends a user content, so that model can continue to output.
+     *
+     * @param llmRequest LlmRequest, the request to send to the LLM.
+     */
+    maybeAppendUserContent(llmRequest: LlmRequest): void;
+}
+export {};

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

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Blob, Content } from '@google/genai';
+import { LlmResponse } from './llm_response.js';
+/**
+ * The base class for a live model connection.
+ */
+export interface BaseLlmConnection {
+    /**
+     * Sends the conversation history to the model.
+     *
+     * You call this method right after setting up the model connection.
+     * The model will respond if the last content is from user, otherwise it will
+     * wait for new user input before responding.
+     *
+     * @param history The conversation history to send to the model.
+     */
+    sendHistory(history: Content[]): Promise<void>;
+    /**
+     * Sends the content to the model.
+     *
+     * The model will respond immediately upon receiving the content.
+     * If you send function responses, all parts in the content should be function
+     * responses.
+     *
+     * @param content The content to send to the model.
+     */
+    sendContent(content: Content): Promise<void>;
+    /**
+     * Sends a chunk of audio or a frame of video to the model in realtime.
+     *
+     * The model may not respond immediately upon receiving the blob. It will do
+     * voice activity detection and decide when to respond.
+     *
+     * @param blob The blob to send to the model.
+     */
+    sendRealtime(blob: Blob): Promise<void>;
+    /**
+     * Receives the model response using the llm server connection.
+     *
+     * @return A generator of LlmResponse.
+     */
+    receive(): AsyncGenerator<LlmResponse, void, void>;
+    /**
+     * Closes the llm server connection.
+     */
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Blob, Content, Session } from '@google/genai';
+import { BaseLlmConnection } from './base_llm_connection.js';
+import { LlmResponse } from './llm_response.js';
+/** The Gemini model connection. */
+export declare class GeminiLlmConnection implements BaseLlmConnection {
+    private readonly geminiSession;
+    constructor(geminiSession: Session);
+    /**
+     * Sends the conversation history to the gemini model.
+     *
+     * You call this method right after setting up the model connection.
+     * The model will respond if the last content is from user, otherwise it will
+     * wait for new user input before responding.
+     *
+     * @param history The conversation history to send to the model.
+     */
+    sendHistory(history: Content[]): Promise<void>;
+    /**
+     * Sends a user content to the gemini model.
+     *
+     * The model will respond immediately upon receiving the content.
+     * If you send function responses, all parts in the content should be function
+     * responses.
+     *
+     * @param content The content to send to the model.
+     */
+    sendContent(content: Content): Promise<void>;
+    /**
+     * Sends a chunk of audio or a frame of video to the model in realtime.
+     *
+     * @param blob The blob to send to the model.
+     */
+    sendRealtime(blob: Blob): Promise<void>;
+    /**
+     * Builds a full text response.
+     *
+     * The text should not be partial and the returned LlmResponse is not be
+     * partial.
+     *
+     * @param text The text to be included in the response.
+     * @returns An LlmResponse containing the full text.
+     */
+    private buildFullTextResponse;
+    receive(): AsyncGenerator<LlmResponse, void, void>;
+    /**
+     * Closes the llm server connection.
+     */
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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';
+import { LlmRequest } from './llm_request.js';
+import { LlmResponse } from './llm_response.js';
+/**
+ * The parameters for creating a Gemini instance.
+ */
+export interface GeminiParams {
+    /**
+     * The name of the model to use. Defaults to 'gemini-2.5-flash'.
+     */
+    model?: string;
+    /**
+     * The API key to use for the Gemini API. If not provided, it will look for
+     * the GOOGLE_GENAI_API_KEY or GEMINI_API_KEY environment variable.
+     */
+    apiKey?: string;
+    /**
+     * Whether to use Vertex AI. If true, `project`, `location`
+     * should be provided.
+     */
+    vertexai?: boolean;
+    /**
+     * The Vertex AI project ID. Required if `vertexai` is true.
+     */
+    project?: string;
+    /**
+     * The Vertex AI location. Required if `vertexai` is true.
+     */
+    location?: string;
+    /**
+     * Headers to merge with internally crafted headers.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Integration for Gemini models.
+ */
+export declare class Gemini extends BaseLlm {
+    private readonly apiKey?;
+    protected readonly vertexai: boolean;
+    private readonly project?;
+    private readonly location?;
+    private readonly headers?;
+    /**
+     * @param params The parameters for creating a Gemini instance.
+     */
+    constructor({ model, apiKey, vertexai, project, location, headers, }: GeminiParams);
+    /**
+     * A list of model name patterns that are supported by this LLM.
+     *
+     * @returns A list of supported models.
+     */
+    static readonly supportedModels: Array<string | RegExp>;
+    private _apiClient?;
+    private _apiBackend?;
+    private _trackingHeaders?;
+    private _liveApiVersion?;
+    private _liveApiClient?;
+    /**
+     * Sends a request to the Gemini model.
+     *
+     * @param llmRequest LlmRequest, the request to send to the Gemini model.
+     * @param stream bool = false, whether to do streaming call.
+     * @yields LlmResponse: The model response.
+     */
+    generateContentAsync(llmRequest: LlmRequest, stream?: boolean, abortSignal?: AbortSignal): 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.
+     *
+     * @param llmRequest LlmRequest, the request to send to the Gemini model.
+     * @returns BaseLlmConnection, the connection to the Gemini model.
+     */
+    connect(llmRequest: LlmRequest): Promise<BaseLlmConnection>;
+    private preprocessRequest;
+}
+export declare function geminiInitParams({ model, vertexai, project, location, apiKey, }: GeminiParams): GeminiParams;

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

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content, GenerateContentConfig, LiveConnectConfig, SchemaUnion } from '@google/genai';
+import { BaseTool } from '../tools/base_tool.js';
+/**
+ * LLM request class that allows passing in tools, output schema and system
+ * instructions to the model.
+ */
+export interface LlmRequest {
+    /**
+     * The model name.
+     */
+    model?: string;
+    /**
+     * The contents to send to the model.
+     */
+    contents: Content[];
+    /**
+     * Additional config for the generate content request.
+     * Tools in generateContentConfig should not be set directly; use appendTools.
+     */
+    config?: GenerateContentConfig;
+    liveConnectConfig: LiveConnectConfig;
+    /**
+     * The tools dictionary. Excluded from JSON serialization.
+     */
+    toolsDict: {
+        [key: string]: BaseTool;
+    };
+    /**
+     * The set of allowed tools, populated by request processors.
+     */
+    allowedTools?: string[];
+}
+/**
+ * Appends instructions to the system instruction.
+ * @param instructions The instructions to append.
+ */
+export declare function appendInstructions(llmRequest: LlmRequest, instructions: string[]): void;
+/**
+ * Appends tools to the request.
+ * @param tools The tools to append.
+ */
+export declare function appendTools(llmRequest: LlmRequest, tools: BaseTool[]): void;
+/**
+ * Sets the output schema for the request.
+ *
+ * @param schema The JSON Schema object to set as the output schema.
+ */
+export declare function setOutputSchema(llmRequest: LlmRequest, schema: SchemaUnion): void;

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

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CitationMetadata, Content, FinishReason, GenerateContentResponse, GenerateContentResponseUsageMetadata, GroundingMetadata, LiveServerSessionResumptionUpdate, Transcription } from '@google/genai';
+/**
+ * LLM response class that provides the first candidate response from the
+ * model if available. Otherwise, returns error code and message.
+ */
+export interface LlmResponse {
+    /**
+     * The content of the response.
+     */
+    content?: Content;
+    /**
+     * The grounding metadata of the response.
+     */
+    groundingMetadata?: GroundingMetadata;
+    /**
+     * The citation metadata of the response.
+     */
+    citationMetadata?: CitationMetadata;
+    /**
+     * Indicates whether the text content is part of a unfinished text stream.
+     * Only used for streaming mode and when the content is plain text.
+     */
+    partial?: boolean;
+    /**
+     * Indicates whether the response from the model is complete.
+     * Only used for streaming mode.
+     */
+    turnComplete?: boolean;
+    /**
+     * Error code if the response is an error. Code varies by model.
+     */
+    errorCode?: string;
+    /**
+     * Error message if the response is an error.
+     */
+    errorMessage?: string;
+    /**
+     * Flag indicating that LLM was interrupted when generating the content.
+     * Usually it's due to user interruption during a bidi streaming.
+     */
+    interrupted?: boolean;
+    /**
+     * The custom metadata of the LlmResponse.
+     * An optional key-value pair to label an LlmResponse.
+     * NOTE: the entire object must be JSON serializable.
+     */
+    customMetadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * The usage metadata of the LlmResponse.
+     */
+    usageMetadata?: GenerateContentResponseUsageMetadata;
+    /**
+     * The finish reason of the response.
+     */
+    finishReason?: FinishReason;
+    /**
+     * The session resumption update of the LlmResponse
+     */
+    liveSessionResumptionUpdate?: LiveServerSessionResumptionUpdate;
+    /**
+     * Audio transcription of user input.
+     */
+    inputTranscription?: Transcription;
+    /**
+     * Audio transcription of model output.
+     */
+    outputTranscription?: Transcription;
+}
+/**
+ * Creates an LlmResponse from a GenerateContentResponse.
+ *
+ * @param response The GenerateContentResponse to create the
+ *   LlmResponse from.
+ * @returns The LlmResponse.
+ */
+export declare function createLlmResponse(response: GenerateContentResponse): LlmResponse;