@google/adk 0.1.0

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

@@ -0,0 +1,333 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GenerateContentConfig, Schema } from '@google/genai';
+import { Event } from '../events/event.js';
+import { BaseExampleProvider } from '../examples/base_example_provider.js';
+import { Example } from '../examples/example.js';
+import { BaseLlm } from '../models/base_llm.js';
+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 { BaseAgent, BaseAgentConfig } from './base_agent.js';
+import { BaseLlmRequestProcessor, BaseLlmResponseProcessor } from './base_llm_processor.js';
+import { CallbackContext } from './callback_context.js';
+import { InvocationContext } from './invocation_context.js';
+import { ReadonlyContext } from './readonly_context.js';
+/** An object that can provide an instruction string. */
+export type InstructionProvider = (context: ReadonlyContext) => string | Promise<string>;
+/**
+ * A callback that runs before a request is sent to the model.
+ *
+ * @param context The current callback context.
+ * @param request The raw model request. Callback can mutate the request.
+ * @returns The content to return to the user. When present, the model call
+ *     will be skipped and the provided content will be returned to user.
+ */
+export type SingleBeforeModelCallback = (params: {
+    context: CallbackContext;
+    request: LlmRequest;
+}) => LlmResponse | undefined | Promise<LlmResponse | undefined>;
+/**
+ * A single callback or a list of callbacks.
+ *
+ * When a list of callbacks is provided, the callbacks will be called in the
+ * order they are listed until a callback does not return None.
+ */
+export type BeforeModelCallback = SingleBeforeModelCallback | SingleBeforeModelCallback[];
+/**
+ * A callback that runs after a response is received from the model.
+ *
+ * @param context The current callback context.
+ * @param response The actual model response.
+ * @returns The content to return to the user. When present, the actual model
+ *     response will be ignored and the provided content will be returned to
+ *     user.
+ */
+export type SingleAfterModelCallback = (params: {
+    context: CallbackContext;
+    response: LlmResponse;
+}) => LlmResponse | undefined | Promise<LlmResponse | undefined>;
+/**
+ * A single callback or a list of callbacks.
+ *
+ * When a list of callbacks is provided, the callbacks will be called in the
+ order they are listed until a callback does not return None.
+ */
+export type AfterModelCallback = SingleAfterModelCallback | SingleAfterModelCallback[];
+/** A generic dictionary type. */
+export type Dict = {
+    [key: string]: unknown;
+};
+/**
+ * A callback that runs before a tool is called.
+ *
+ * @param tool The tool to be called.
+ * @param args The arguments to the tool.
+ * @param tool_context: ToolContext,
+ * @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: Dict;
+    context: ToolContext;
+}) => Dict | undefined | Promise<Dict | undefined>;
+/**
+ * A single callback or a list of callbacks.
+ *
+ * When a list of callbacks is provided, the callbacks will be called in the
+ * order they are listed until a callback does not return None.
+ */
+export type BeforeToolCallback = SingleBeforeToolCallback | SingleBeforeToolCallback[];
+/**
+ * A callback that runs after a tool is called.
+ *
+ * @param tool The tool to be called.
+ * @param args The arguments to the tool.
+ * @param tool_context: ToolContext,
+ * @param tool_response: The response from the tool.
+ * @returns When present, the returned dict will be used as tool result.
+ */
+export type SingleAfterToolCallback = (params: {
+    tool: BaseTool;
+    args: Dict;
+    context: ToolContext;
+    response: Dict;
+}) => Dict | undefined | Promise<Dict | undefined>;
+/**
+ * A single callback or a list of callbacks.
+ *
+ * When a list of callbacks is provided, the callbacks will be called in the
+ * order they are listed until acallback does not return None.
+ */
+export type AfterToolCallback = SingleAfterToolCallback | SingleAfterToolCallback[];
+/** A list of examples or an example provider. */
+export type ExamplesUnion = Example[] | BaseExampleProvider;
+/** A union of tool types that can be provided to an agent. */
+export type ToolUnion = BaseTool | BaseToolset;
+export interface LlmAgentConfig extends BaseAgentConfig {
+    /**
+     * The model to use for the agent.
+     */
+    model?: string | BaseLlm;
+    /** Instructions for the LLM model, guiding the agent's behavior. */
+    instruction?: string | InstructionProvider;
+    /**
+     * Instructions for all the agents in the entire agent tree.
+     *
+     * ONLY the globalInstruction in root agent will take effect.
+     *
+     * For example: use globalInstruction to make all agents have a stable
+     * identity or personality.
+     */
+    globalInstruction?: string | InstructionProvider;
+    /** Tools available to this agent. */
+    tools?: ToolUnion[];
+    /**
+     * The additional content generation configurations.
+     *
+     * NOTE: not all fields are usable, e.g. tools must be configured via
+     * `tools`, thinking_config must be configured via `planner` in LlmAgent.
+     *
+     * For example: use this config to adjust model temperature, configure safety
+     * settings, etc.
+     */
+    generateContentConfig?: GenerateContentConfig;
+    /**
+     * Disallows LLM-controlled transferring to the parent agent.
+     *
+     * NOTE: Setting this as True also prevents this agent to continue reply to
+     * the end-user. This behavior prevents one-way transfer, in which end-user
+     * may be stuck with one agent that cannot transfer to other agents in the
+     * agent tree.
+     */
+    disallowTransferToParent?: boolean;
+    /** Disallows LLM-controlled transferring to the peer agents. */
+    disallowTransferToPeers?: boolean;
+    /**
+     * Controls content inclusion in model requests.
+     *
+     * Options:
+     *   default: Model receives relevant conversation history
+     *   none: Model receives no prior history, operates solely on current
+     *   instruction and input
+     */
+    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;
+    /**
+     * The key in session state to store the output of the agent.
+     *
+     * Typically use cases:
+     * - Extracts agent reply for later use, such as in tools, callbacks, etc.
+     * - Connects agents to coordinate with each other.
+     */
+    outputKey?: string;
+    /**
+     * Callbacks to be called before calling the LLM.
+     */
+    beforeModelCallback?: BeforeModelCallback;
+    /**
+     * Callbacks to be called after calling the LLM.
+     */
+    afterModelCallback?: AfterModelCallback;
+    /**
+     * Callbacks to be called before calling the tool.
+     */
+    beforeToolCallback?: BeforeToolCallback;
+    /**
+     * Callbacks to be called after calling the tool.
+     */
+    afterToolCallback?: AfterToolCallback;
+    /**
+     * Processors to run before the LLM request is sent.
+     */
+    requestProcessors?: BaseLlmRequestProcessor[];
+    /**
+     * Processors to run after the LLM response is received.
+     */
+    responseProcessors?: BaseLlmResponseProcessor[];
+}
+declare class RequestConfirmationLlmRequestProcessor extends BaseLlmRequestProcessor {
+    /** Handles tool confirmation information to build the LLM request. */
+    runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+}
+export declare const REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR: RequestConfirmationLlmRequestProcessor;
+/**
+ * An agent that uses a large language model to generate responses.
+ */
+export declare class LlmAgent extends BaseAgent {
+    model?: string | BaseLlm;
+    instruction: string | InstructionProvider;
+    globalInstruction: string | InstructionProvider;
+    tools: ToolUnion[];
+    generateContentConfig?: GenerateContentConfig;
+    disallowTransferToParent: boolean;
+    disallowTransferToPeers: boolean;
+    includeContents: 'default' | 'none';
+    inputSchema?: Schema;
+    outputSchema?: Schema;
+    outputKey?: string;
+    beforeModelCallback?: BeforeModelCallback;
+    afterModelCallback?: AfterModelCallback;
+    beforeToolCallback?: BeforeToolCallback;
+    afterToolCallback?: AfterToolCallback;
+    requestProcessors: BaseLlmRequestProcessor[];
+    responseProcessors: BaseLlmResponseProcessor[];
+    constructor(config: LlmAgentConfig);
+    /**
+     * The resolved BaseLlm instance.
+     *
+     * When not set, the agent will inherit the model from its ancestor.
+     */
+    get canonicalModel(): BaseLlm;
+    /**
+     * The resolved self.instruction field to construct instruction for this
+     * agent.
+     *
+     * This method is only for use by Agent Development Kit.
+     * @param context The context to retrieve the session state.
+     * @returns The resolved self.instruction field.
+     */
+    canonicalInstruction(context: ReadonlyContext): Promise<{
+        instruction: string;
+        requireStateInjection: boolean;
+    }>;
+    /**
+     * The resolved self.instruction field to construct global instruction.
+     *
+     * This method is only for use by Agent Development Kit.
+     * @param context The context to retrieve the session state.
+     * @returns The resolved self.global_instruction field.
+     */
+    canonicalGlobalInstruction(context: ReadonlyContext): Promise<{
+        instruction: string;
+        requireStateInjection: boolean;
+    }>;
+    /**
+     * The resolved self.tools field as a list of BaseTool based on the context.
+     *
+     * This method is only for use by Agent Development Kit.
+     */
+    canonicalTools(context?: ReadonlyContext): Promise<BaseTool[]>;
+    /**
+     * Normalizes a callback or an array of callbacks into an array of callbacks.
+     *
+     * @param callback The callback or an array of callbacks.
+     * @returns An array of callbacks.
+     */
+    private static normalizeCallbackArray;
+    /**
+     * The resolved self.before_model_callback field as a list of
+     * SingleBeforeModelCallback.
+     *
+     * This method is only for use by Agent Development Kit.
+     */
+    get canonicalBeforeModelCallbacks(): SingleBeforeModelCallback[];
+    /**
+     * The resolved self.after_model_callback field as a list of
+     * SingleAfterModelCallback.
+     *
+     * This method is only for use by Agent Development Kit.
+     */
+    get canonicalAfterModelCallbacks(): SingleAfterModelCallback[];
+    /**
+     * The resolved self.before_tool_callback field as a list of
+     * BeforeToolCallback.
+     *
+     * This method is only for use by Agent Development Kit.
+     */
+    get canonicalBeforeToolCallbacks(): SingleBeforeToolCallback[];
+    /**
+     * The resolved self.after_tool_callback field as a list of AfterToolCallback.
+     *
+     * This method is only for use by Agent Development Kit.
+     */
+    get canonicalAfterToolCallbacks(): SingleAfterToolCallback[];
+    /**
+     * Saves the agent's final response to the session state if configured.
+     *
+     * It extracts the text content from the final response event, optionally
+     * parses it as JSON based on the output schema, and stores the result in the
+     * session state using the specified output key.
+     *
+     * @param event The event to process.
+     */
+    private maybeSaveOutputToState;
+    protected runAsyncImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+    protected runLiveImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+    private runLiveFlow;
+    private runOneStepAsync;
+    private postprocess;
+    /**
+     * Retrieves an agent from the agent tree by its name.
+     *
+     * Performing a depth-first search to locate the agent with the given name.
+     * - Starts searching from the root agent of the current invocation context.
+     * - Traverses down the agent tree to find the specified agent.
+     *
+     * @param invocationContext The current invocation context.
+     * @param agentName The name of the agent to retrieve.
+     * @returns The agent with the given name.
+     * @throws Error if the agent is not found.
+     */
+    private getAgentByName;
+    private callLlmAsync;
+    private handleBeforeModelCallback;
+    private handleAfterModelCallback;
+    private runAndHandleError;
+}
+export {};

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

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../events/event.js';
+import { BaseAgent, BaseAgentConfig } from './base_agent.js';
+import { InvocationContext } from './invocation_context.js';
+/**
+ * The configuration options for creating a loop agent.
+ */
+export interface LoopAgentConfig extends BaseAgentConfig {
+    /**
+     * The maximum number of iterations the loop agent will run.
+     *
+     * If not provided, the loop agent will run indefinitely.
+     */
+    maxIterations?: number;
+}
+/**
+ * A shell agent that run its sub-agents in a loop.
+ *
+ * When sub-agent generates an event with escalate or max_iterations are
+ * reached, the loop agent will stop.
+ */
+export declare class LoopAgent extends BaseAgent {
+    private readonly maxIterations;
+    constructor(config: LoopAgentConfig);
+    protected runAsyncImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+    protected runLiveImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../events/event.js';
+import { BaseAgent } from './base_agent.js';
+import { InvocationContext } from './invocation_context.js';
+/**
+ * A shell agent that run its sub-agents in parallel in isolated manner.
+ *
+ * This approach is beneficial for scenarios requiring multiple perspectives or
+ * attempts on a single task, such as:
+ *
+ *  - Running different algorithms simultaneously.
+ *  - Generating multiple responses for review by a subsequent evaluation agent.
+ */
+export declare class ParallelAgent extends BaseAgent {
+    protected runAsyncImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+    protected runLiveImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import { State } from '../sessions/state.js';
+import { InvocationContext } from './invocation_context.js';
+/**
+ * A readonly context represents the data of a single invocation of an agent.
+ */
+export declare class ReadonlyContext {
+    readonly invocationContext: InvocationContext;
+    constructor(invocationContext: InvocationContext);
+    /**
+     * The user content that started this invocation.
+     */
+    get userContent(): Content | undefined;
+    /**
+     * The current invocation id.
+     */
+    get invocationId(): string;
+    /**
+     * The current agent name.
+     */
+    get agentName(): string;
+    /**
+     * The state of the current session.
+     */
+    get state(): Readonly<State>;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AudioTranscriptionConfig, Modality, ProactivityConfig, RealtimeInputConfig, SpeechConfig } from '@google/genai';
+/**
+ * The streaming mode for the run config.
+ */
+export declare enum StreamingMode {
+    NONE = "none",
+    SSE = "sse",
+    BIDI = "bidi"
+}
+/**
+ * Configs for runtime behavior of agents.
+ */
+export declare class RunConfig {
+    /**
+     * Speech configuration for the live agent.
+     */
+    speechConfig?: SpeechConfig;
+    /**
+     * The output modalities. If not set, it's default to AUDIO.
+     */
+    responseModalities?: Modality[];
+    /**
+     * Whether or not to save the input blobs as artifacts.
+     */
+    saveInputBlobsAsArtifacts: boolean;
+    /**
+     * Whether to support CFC (Compositional Function Calling). Only applicable
+     * for StreamingMode.SSE. If it's true. the LIVE API will be invoked. Since
+     * only LIVE API supports CFC
+     *
+     * WARNING: This feature is **experimental** and its API or behavior may
+     * change in future releases.
+     */
+    supportCfc: boolean;
+    /**
+     * Streaming mode, None or StreamingMode.SSE or StreamingMode.BIDI.
+     */
+    streamingMode: StreamingMode;
+    /**
+     * Output audio transcription config.
+     */
+    outputAudioTranscription?: AudioTranscriptionConfig;
+    /**
+     * Input transcription for live agents with audio input from user.
+     */
+    inputAudioTranscription?: AudioTranscriptionConfig;
+    /**
+     * If enabled, the model will detect emotions and adapt its responses
+     * accordingly.
+     */
+    enableAffectiveDialog: boolean;
+    /**
+     * Configures the proactivity of the model. This allows the model to respond
+     * proactively to the input and to ignore irrelevant input.
+     */
+    proactivity?: ProactivityConfig;
+    /**
+     * Realtime input config for live agents with audio input from user.
+     */
+    realtimeInputConfig?: RealtimeInputConfig;
+    /**
+     * A limit on the total number of llm calls for a given run.
+     *
+     * Valid Values:
+     *   - More than 0 and less than sys.maxsize: The bound on the number of llm
+     *     calls is enforced, if the value is set in this range.
+     *   - Less than or equal to 0: This allows for unbounded number of llm calls.
+     */
+    maxLlmCalls: number;
+    constructor(params?: Partial<RunConfig>);
+}

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

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../events/event.js';
+import { BaseAgent } from './base_agent.js';
+import { InvocationContext } from './invocation_context.js';
+/**
+ * A shell agent that runs its sub-agents in a sequential order.
+ */
+export declare class SequentialAgent extends BaseAgent {
+    protected runAsyncImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+    /**
+     * Implementation for live SequentialAgent.
+     *
+     * Compared to the non-live case, live agents process a continuous stream of
+     * audio or video, so there is no way to tell if it's finished and should pass
+     * to the next agent or not. So we introduce a task_completed() function so
+     * the model can call this function to signal that it's finished the task and
+     * we can move on to the next agent.
+     *
+     * @param context: The invocation context of the agent.
+     */
+    protected runLiveImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Blob, Content } from '@google/genai';
+/**
+ * Store the data that can be used for transcription.
+ */
+export interface TranscriptionEntry {
+    /**
+     * The role that created this data, typically "user" or "model". For function
+     * call, this is undefined.
+     */
+    role?: string;
+    data: Blob | Content;
+}

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

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Part } from '@google/genai';
+/**
+ * The parameters for `saveArtifact`.
+ */
+export interface SaveArtifactRequest {
+    /** The app name. */
+    appName: string;
+    /** The user ID. */
+    userId: string;
+    /** The session ID. */
+    sessionId: string;
+    /** The filename of the artifact. */
+    filename: string;
+    /** The artifact to save. */
+    artifact: Part;
+}
+/**
+ * The parameters for `loadArtifact`.
+ */
+export interface LoadArtifactRequest {
+    /** The app name. */
+    appName: string;
+    /** The user ID. */
+    userId: string;
+    /** The session ID. */
+    sessionId: string;
+    /** The filename of the artifact. */
+    filename: string;
+    /**
+     * The version of the artifact to load. If not provided, the latest version
+     * of the artifact is loaded.
+     */
+    version?: number;
+}
+/**
+ * The parameters for `listArtifactKeys`.
+ */
+export interface ListArtifactKeysRequest {
+    /** The app name. */
+    appName: string;
+    /** The user ID. */
+    userId: string;
+    /** The session ID. */
+    sessionId: string;
+}
+/**
+ * The parameters for `deleteArtifact`.
+ */
+export interface DeleteArtifactRequest {
+    /** The app name. */
+    appName: string;
+    /** The user ID. */
+    userId: string;
+    /** The session ID. */
+    sessionId: string;
+    /** The filename of the artifact. */
+    filename: string;
+}
+/**
+ * The parameters for `listVersions`.
+ */
+export interface ListVersionsRequest {
+    /** The app name. */
+    appName: string;
+    /** The user ID. */
+    userId: string;
+    /** The session ID. */
+    sessionId: string;
+    /** The filename of the artifact. */
+    filename: string;
+}
+/**
+ *  Interface for artifact services.
+ */
+export interface BaseArtifactService {
+    /**
+     * Saves an artifact to the artifact service storage.
+     *
+     * The artifact is a file identified by the app name, user ID, session ID, and
+     * filename. After saving the artifact, a revision ID is returned to identify
+     * the artifact version.
+     *
+     * @param request The request to save an artifact.
+     * @return A promise that resolves to The revision ID. The first version of
+     * the artifact has a revision ID of 0. This is incremented by 1 after each
+     * successful save.
+     */
+    saveArtifact(request: SaveArtifactRequest): Promise<number>;
+    /**
+     * Gets an artifact from the artifact service storage.
+     *
+     * The artifact is a file identified by the app name, user ID, session ID, and
+     * filename.
+     *
+     * @param request The request to load an artifact.
+     * @return A promise that resolves to the artifact or undefined if not found.
+     */
+    loadArtifact(request: LoadArtifactRequest): Promise<Part | undefined>;
+    /**
+     * Lists all the artifact filenames within a session.
+     *
+     * @param request The request to list artifact keys.
+     * @return A promise that resolves to a list of all artifact filenames within
+     *     a session.
+     */
+    listArtifactKeys(request: ListArtifactKeysRequest): Promise<string[]>;
+    /**
+     * Deletes an artifact.
+     *
+     * @param request The request to delete an artifact.
+     * @return A promise that resolves when the artifact is deleted.
+     */
+    deleteArtifact(request: DeleteArtifactRequest): Promise<void>;
+    /**
+     * Lists all versions of an artifact.
+     *
+     * @param request The request to list versions.
+     * @return A promise that resolves to a list of all available versions of the
+     *     artifact.
+     */
+    listVersions(request: ListVersionsRequest): Promise<number[]>;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Part } from '@google/genai';
+import { BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from './base_artifact_service.js';
+/**
+ * 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>;
+    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[]>;
+}