@google/adk 0.1.0

package/dist/types/common.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export { BaseAgent } from './agents/base_agent.js';
+export { CallbackContext } from './agents/callback_context.js';
+export { functionsExportedForTestingOnly } from './agents/functions.js';
+export { InvocationContext } from './agents/invocation_context.js';
+export { LiveRequestQueue } from './agents/live_request_queue.js';
+export type { LiveRequest } from './agents/live_request_queue.js';
+export { LlmAgent } from './agents/llm_agent.js';
+export type { AfterModelCallback, AfterToolCallback, BeforeModelCallback, BeforeToolCallback, SingleAfterModelCallback, SingleAfterToolCallback, SingleBeforeModelCallback, SingleBeforeToolCallback } from './agents/llm_agent.js';
+export { LoopAgent } from './agents/loop_agent.js';
+export { ParallelAgent } from './agents/parallel_agent.js';
+export { RunConfig, StreamingMode } from './agents/run_config.js';
+export { SequentialAgent } from './agents/sequential_agent.js';
+export { InMemoryArtifactService } from './artifacts/in_memory_artifact_service.js';
+export type { BaseCredentialService } from './auth/credential_service/base_credential_service.js';
+export { createEvent, getFunctionCalls, getFunctionResponses, hasTrailingCodeExecutionResult, isFinalResponse } from './events/event.js';
+export type { Event } from './events/event.js';
+export type { EventActions } from './events/event_actions.js';
+export { InMemoryMemoryService } from './memory/in_memory_memory_service.js';
+export { BaseLlm } from './models/base_llm.js';
+export type { BaseLlmConnection } from './models/base_llm_connection.js';
+export type { LlmRequest } from './models/llm_request.js';
+export type { LlmResponse } from './models/llm_response.js';
+export { BasePlugin } from './plugins/base_plugin.js';
+export { LoggingPlugin } from './plugins/logging_plugin.js';
+export { PluginManager } from './plugins/plugin_manager.js';
+export { getAskUserConfirmationFunctionCalls, InMemoryPolicyEngine, PolicyOutcome, REQUEST_CONFIRMATION_FUNCTION_CALL_NAME, SecurityPlugin } from './plugins/security_plugin.js';
+export type { BasePolicyEngine, PolicyCheckResult, ToolCallPolicyContext } from './plugins/security_plugin.js';
+export { InMemoryRunner } from './runner/in_memory_runner.js';
+export { Runner } from './runner/runner.js';
+export { InMemorySessionService } from './sessions/in_memory_session_service.js';
+export { createSession } from './sessions/session.js';
+export type { Session } from './sessions/session.js';
+export { AgentTool } from './tools/agent_tool.js';
+export { BaseTool } from './tools/base_tool.js';
+export { BaseToolset } from './tools/base_toolset.js';
+export { FunctionTool } from './tools/function_tool.js';
+export { GOOGLE_SEARCH } from './tools/google_search_tool.js';
+export { LongRunningFunctionTool } from './tools/long_running_tool.js';
+export { ToolConfirmation } from './tools/tool_confirmation.js';
+export { ToolContext } from './tools/tool_context.js';
+export { LogLevel, setLogLevel } from './utils/logger.js';
+export { zodObjectToSchema } from './utils/simple_zod_to_json.js';
+export * from './artifacts/base_artifact_service.js';
+export * from './memory/base_memory_service.js';
+export * from './sessions/base_session_service.js';
+export * from './tools/base_tool.js';

package/dist/types/events/event.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionCall, FunctionResponse } from '@google/genai';
+import { LlmResponse } from '../models/llm_response.js';
+import { EventActions } from './event_actions.js';
+/**
+ * Represents an event in a conversation between agents and users.
+
+  It is used to store the content of the conversation, as well as the actions
+  taken by the agents like function calls, etc.
+ */
+export interface Event extends LlmResponse {
+    /**
+     * The unique identifier of the event.
+     * Do not assign the ID. It will be assigned by the session.
+     */
+    id: string;
+    /**
+     * The invocation ID of the event. Should be non-empty before appending to a
+     * session.
+     */
+    invocationId: string;
+    /**
+     * "user" or the name of the agent, indicating who appended the event to the
+     * session.
+     */
+    author?: string;
+    /**
+     * The actions taken by the agent.
+     */
+    actions: EventActions;
+    /**
+     * Set of ids of the long running function calls. Agent client will know from
+     * this field about which function call is long running. Only valid for
+     * function call event
+     */
+    longRunningToolIds?: string[];
+    /**
+     * The branch of the event.
+     * The format is like agent_1.agent_2.agent_3, where agent_1 is the parent of
+     * agent_2, and agent_2 is the parent of agent_3.
+     *
+     * Branch is used when multiple sub-agent shouldn't see their peer agents'
+     * conversation history.
+     */
+    branch?: string;
+    /**
+     * The timestamp of the event.
+     */
+    timestamp: number;
+}
+/**
+ * Creates an event from a partial event.
+ *
+ * @param params The partial event to create the event from.
+ * @returns The event.
+ */
+export declare function createEvent(params?: Partial<Event>): Event;
+/**
+ * Returns whether the event is the final response of the agent.
+ */
+export declare function isFinalResponse(event: Event): boolean;
+/**
+ * Returns the function calls in the event.
+ */
+export declare function getFunctionCalls(event: Event): FunctionCall[];
+/**
+ * Returns the function responses in the event.
+ */
+export declare function getFunctionResponses(event: Event): FunctionResponse[];
+/**
+ * Returns whether the event has a trailing code execution result.
+ */
+export declare function hasTrailingCodeExecutionResult(event: Event): boolean;
+/**
+ * Generates a new unique ID for the event.
+ */
+export declare function createNewEventId(): string;

package/dist/types/events/event_actions.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ToolConfirmation } from '../tools/tool_confirmation.js';
+type AuthConfig = any;
+/**
+ * Represents the actions attached to an event.
+ */
+export interface EventActions {
+    /**
+     * If true, it won't call model to summarize function response.
+     * Only used for function_response event.
+     */
+    skipSummarization?: boolean;
+    /**
+     * Indicates that the event is updating the state with the given delta.
+     */
+    stateDelta: {
+        [key: string]: unknown;
+    };
+    /**
+     * Indicates that the event is updating an artifact. key is the filename,
+     * value is the version.
+     */
+    artifactDelta: {
+        [key: string]: number;
+    };
+    /**
+     * If set, the event transfers to the specified agent.
+     */
+    transferToAgent?: string;
+    /**
+     * The agent is escalating to a higher level agent.
+     */
+    escalate?: boolean;
+    /**
+     * Authentication configurations requested by tool responses.
+     *
+     * This field will only be set by a tool response event indicating tool
+     * request auth credential.
+     * - Keys: The function call id. Since one function response event could
+     * contain multiple function responses that correspond to multiple function
+     * calls. Each function call could request different auth configs. This id is
+     * used to identify the function call.
+     * - Values: The requested auth config.
+     */
+    requestedAuthConfigs: {
+        [key: string]: AuthConfig;
+    };
+    /**
+     * A dict of tool confirmation requested by this event, keyed by the function
+     * call id.
+     */
+    requestedToolConfirmations: {
+        [key: string]: ToolConfirmation;
+    };
+}
+/**
+ * Creates an EventActions object.
+ */
+export declare function createEventActions(state?: Partial<EventActions>): EventActions;
+/**
+ * Merges a list of EventActions objects into a single EventActions object.
+ *
+ * 1. It merges dictionaries (stateDelta, artifactDelta, requestedAuthConfigs)
+ * by adding all the properties from each source.
+ *
+ * 2. For other properties (skipSummarization,transferToAgent, escalate), the
+ * last one wins.
+ */
+export declare function mergeEventActions(sources: Array<Partial<EventActions>>, target?: EventActions): EventActions;
+export {};

package/dist/types/examples/base_example_provider.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Example } from './example.js';
+/**
+ * Base class for example providers.
+ *
+ *  This class defines the interface for providing examples for a given query.
+ */
+export declare abstract class BaseExampleProvider {
+    /**
+     * Returns a list of examples for a given query.
+     *
+     * @param query The query to get examples for.
+     * @return A list of Example objects.
+     */
+    abstract getExamples(query: string): Example[];
+}

package/dist/types/examples/example.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+/**
+ * A few-shot example.
+ */
+export interface Example {
+    /**
+     * The input content for the example.
+     */
+    input: Content;
+    /**
+     * The expected output content for the example.
+     */
+    output: Content[];
+}

package/dist/types/examples/example_util.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseExampleProvider } from './base_example_provider.js';
+import { Example } from './example.js';
+/**
+ * Converts a list of examples to a string that can be used in a system
+ * instruction.
+ */
+export declare function convertExamplesToText(examples: Example[], model?: string): string;
+export declare function buildExampleSi(examples: Example[] | BaseExampleProvider, query: string, model?: string): string;

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from './common.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,47 @@
+/**
+ * @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 {
+    appName: string;
+    userId: string;
+    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,24 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+/**
+ * Represents one memory entry.
+ */
+export interface MemoryEntry {
+    /**
+     * The content of the memory entry.
+     */
+    content: Content;
+    /**
+     * The author of the memory.
+     */
+    author?: string;
+    /**
+     * The timestamp when the original content of this memory happened.
+     * This string will be forwarded to LLM. Preferred format is ISO 8601 format.
+     */
+    timestamp?: string;
+}

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

@@ -0,0 +1,46 @@
+/**
+ * @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';
+/**
+ * The BaseLLM class.
+ */
+export declare abstract class BaseLlm {
+    readonly model: string;
+    /**
+     * Creates an instance of BaseLLM.
+     *
+     * @param model The name of the LLM, e.g. gemini-1.5-flash or
+     *     gemini-1.5-flash-001.
+     */
+    constructor(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.
+     * For non-streaming call, it will only yield one Content.
+     * @return A generator of LlmResponse.
+     */
+    abstract generateContentAsync(llmRequest: LlmRequest): 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>;
+    /**
+     * 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;
+}

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 { Content, Blob } 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,88 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GoogleGenAI } 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?;
+    private readonly vertexai;
+    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): AsyncGenerator<LlmResponse, void>;
+    get apiClient(): GoogleGenAI;
+    get apiBackend(): GoogleLLMVariant;
+    get trackingHeaders(): Record<string, string>;
+    get liveApiVersion(): string;
+    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;
+}

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

@@ -0,0 +1,49 @@
+/**
+ * @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;
+    };
+}
+/**
+ * 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;