@google/adk 0.1.0

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

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import { Event } from '../events/event.js';
+/**
+ * Get the contents for the LLM request.
+ *
+ * @param events: A list of all session events.
+ * @param agentName: The name of the agent.
+ * @param currentBranch: The current branch of the agent.
+ *
+ * @returns A list of processed contents.
+ */
+export declare function getContents(events: Event[], agentName: string, currentBranch?: string): Content[];
+/**
+ * Get contents for the current turn only (no conversation history).
+ *
+ * When include_contents='none', we want to include:
+ * - The current user input
+ * - Tool calls and responses from the current turn
+ * But exclude conversation history from previous turns.
+ *
+ * In multi-agent scenarios, the "current turn" for an agent starts from an
+ * actual user or from another agent.
+ *
+ * @param events: A list of all session events.
+ * @param agentName: The name of the agent.
+ * @param currentBranch: The current branch of the agent.
+ *
+ * @returns A list of contents for the current turn only, preserving context
+ *     needed for proper tool execution while excluding conversation history.
+ */
+export declare function getCurrentTurnContents(events: Event[], agentName: string, currentBranch?: string): Content[];

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

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content, FunctionCall } from '@google/genai';
+import { InvocationContext } from '../agents/invocation_context.js';
+import { Event } from '../events/event.js';
+import { BaseTool } from '../tools/base_tool.js';
+import { ToolConfirmation } from '../tools/tool_confirmation.js';
+import { SingleAfterToolCallback, SingleBeforeToolCallback } from './llm_agent.js';
+export declare const REQUEST_EUC_FUNCTION_CALL_NAME = "adk_request_credential";
+export declare const REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation";
+export declare const functionsExportedForTestingOnly: {
+    handleFunctionCallList: typeof handleFunctionCallList;
+};
+export declare function generateClientFunctionCallId(): string;
+/**
+ * Populates client-side function call IDs.
+ *
+ * It iterates through all function calls in the event and assigns a
+ * unique client-side ID to each one that doesn't already have an ID.
+ */
+export declare function populateClientFunctionCallId(modelResponseEvent: Event): void;
+/**
+ * Removes the client-generated function call IDs from a given content object.
+ *
+ * When sending content back to the server, these IDs are
+ * specific to the client-side and should not be included in requests to the
+ * model.
+ */
+export declare function removeClientFunctionCallId(content: Content): void;
+/**
+ * Returns a set of function call ids of the long running tools.
+ */
+export declare function getLongRunningFunctionCalls(functionCalls: FunctionCall[], toolsDict: Record<string, BaseTool>): Set<string>;
+/**
+ * Generates an authentication event.
+ *
+ * It iterates through requested auth configurations in a function response
+ * event and creates a new function call for each.
+ */
+export declare function generateAuthEvent(invocationContext: InvocationContext, functionResponseEvent: Event): Event | undefined;
+/**
+ * Generates a request confirmation event from a function response event.
+ */
+export declare function generateRequestConfirmationEvent({ invocationContext, functionCallEvent, functionResponseEvent, }: {
+    invocationContext: InvocationContext;
+    functionCallEvent: Event;
+    functionResponseEvent: Event;
+}): Event | undefined;
+/**
+ * Handles function calls.
+ * Runtime behavior to pay attention to:
+ * - Iterate through each function call in the `functionCallEvent`:
+ *   - Execute before tool callbacks !!if a callback provides a response, short
+ *     circuit the rest.
+ *   - Execute the tool.
+ *   - Execute after tool callbacks !!if a callback provides a response, short
+ *     circuit the rest.
+ *   - If the tool is long-running and the response is null, continue. !!state
+ * - Merge all function response events into a single event.
+ */
+export declare function handleFunctionCallsAsync({ invocationContext, functionCallEvent, toolsDict, beforeToolCallbacks, afterToolCallbacks, filters, toolConfirmationDict, }: {
+    invocationContext: InvocationContext;
+    functionCallEvent: Event;
+    toolsDict: Record<string, BaseTool>;
+    beforeToolCallbacks: SingleBeforeToolCallback[];
+    afterToolCallbacks: SingleAfterToolCallback[];
+    filters?: Set<string>;
+    toolConfirmationDict?: Record<string, ToolConfirmation>;
+}): Promise<Event | null>;
+/**
+ * The underlying implementation of handleFunctionCalls, but takes a list of
+ * function calls instead of an event.
+ * This is also used by llm_agent execution flow in preprocessing.
+ */
+export declare function handleFunctionCallList({ invocationContext, functionCalls, toolsDict, beforeToolCallbacks, afterToolCallbacks, filters, toolConfirmationDict, }: {
+    invocationContext: InvocationContext;
+    functionCalls: FunctionCall[];
+    toolsDict: Record<string, BaseTool>;
+    beforeToolCallbacks: SingleBeforeToolCallback[];
+    afterToolCallbacks: SingleAfterToolCallback[];
+    filters?: Set<string>;
+    toolConfirmationDict?: Record<string, ToolConfirmation>;
+}): Promise<Event | null>;
+/**
+ * Merges a list of function response events into a single event.
+ */
+export declare function mergeParallelFunctionResponseEvents(functionResponseEvents: Event[]): Event;

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

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ReadonlyContext } from './readonly_context.js';
+/**
+ * Populates values in the instruction template, e.g. state, artifact, etc.
+ *
+ * ```
+ * async function buildInstruction(
+ *     readonlyContext: ReadonlyContext,
+ * ): Promise<string> {
+ *   return await injectSessionState(
+ *       'You can inject a state variable like {var_name} or an artifact ' +
+ *       '{artifact.file_name} into the instruction template.',
+ *       readonlyContext,
+ *   );
+ * }
+ *
+ * const agent = new LlmAgent({
+ *     model: 'gemini-1.5-flash',
+ *     name: 'agent',
+ *     instruction: buildInstruction,
+ * });
+ * ```
+ *
+ * @param template The instruction template.
+ * @param readonlyContext The read-only context
+ * @returns The instruction template with values populated.
+ */
+export declare function injectSessionState(template: string, readonlyContext: ReadonlyContext): Promise<string>;

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

@@ -0,0 +1,155 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import { BaseArtifactService } from '../artifacts/base_artifact_service.js';
+import { BaseCredentialService } from '../auth/credential_service/base_credential_service.js';
+import { BaseMemoryService } from '../memory/base_memory_service.js';
+import { PluginManager } from '../plugins/plugin_manager.js';
+import { BaseSessionService } from '../sessions/base_session_service.js';
+import { Session } from '../sessions/session.js';
+import { ActiveStreamingTool } from './active_streaming_tool.js';
+import { BaseAgent } from './base_agent.js';
+import { LiveRequestQueue } from './live_request_queue.js';
+import { RunConfig } from './run_config.js';
+import { TranscriptionEntry } from './transcription_entry.js';
+interface InvocationContextParams {
+    artifactService?: BaseArtifactService;
+    sessionService?: BaseSessionService;
+    memoryService?: BaseMemoryService;
+    credentialService?: BaseCredentialService;
+    invocationId: string;
+    branch?: string;
+    agent: BaseAgent;
+    userContent?: Content;
+    session: Session;
+    endInvocation?: boolean;
+    transcriptionCache?: TranscriptionEntry[];
+    runConfig?: RunConfig;
+    liveRequestQueue?: LiveRequestQueue;
+    activeStreamingTools?: Record<string, ActiveStreamingTool>;
+    pluginManager: PluginManager;
+}
+/**
+ * An invocation context represents the data of a single invocation of an agent.
+ *
+ * An invocation:
+ *     1. Starts with a user message and ends with a final response.
+ *     2. Can contain one or multiple agent calls.
+ *     3. Is handled by runner.runAsync().
+ *
+ *   An invocation runs an agent until it does not request to transfer to
+ * another agent.
+ *
+ *   An agent call:
+ *     1. Is handled by agent.runAsync().
+ *     2. Ends when agent.runAsync() ends.
+ *
+ *   An LLM agent call is an agent with a BaseLLMFlow.
+ *  An LLM agent call can contain one or multiple steps.
+ *
+ *  An LLM agent runs steps in a loop until:
+ *    1. A final response is generated.
+ *    2. The agent transfers to another agent.
+ *    3. The end_invocation is set to true by any callbacks or tools.
+ *
+ *  A step:
+ *    1. Calls the LLM only once and yields its response.
+ *   2. Calls the tools and yields their responses if requested.
+ *
+ *  The summarization of the function response is considered another step, since
+ *  it is another llm call.
+ *  A step ends when it's done calling llm and tools, or if the end_invocation
+ *  is set to true at any time.
+ *
+ *  ```
+ *     ┌─────────────────────── invocation ──────────────────────────┐
+ *     ┌──────────── llm_agent_call_1 ────────────┐ ┌─ agent_call_2 ─┐
+ *     ┌──── step_1 ────────┐ ┌───── step_2 ──────┐
+ *     [call_llm] [call_tool] [call_llm] [transfer]
+ *  ```
+ */
+export declare class InvocationContext {
+    readonly artifactService?: BaseArtifactService;
+    readonly sessionService?: BaseSessionService;
+    readonly memoryService?: BaseMemoryService;
+    readonly credentialService?: BaseCredentialService;
+    /**
+     * The id of this invocation context.
+     */
+    readonly invocationId: string;
+    /**
+     * The branch of the invocation context.
+     *
+     * 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-agents shouldn't see their peer agents'
+     * conversation history.
+     */
+    branch?: string;
+    /**
+     * The current agent of this invocation context.
+     */
+    agent: BaseAgent;
+    /**
+     * The user content that started this invocation.
+     */
+    readonly userContent?: Content;
+    /**
+     * The current session of this invocation context.
+     */
+    readonly session: Session;
+    /**
+     * Whether to end this invocation.
+     * Set to True in callbacks or tools to terminate this invocation.
+     */
+    endInvocation: boolean;
+    /**
+     * Caches necessary, data audio or contents, that are needed by transcription.
+     */
+    transcriptionCache?: TranscriptionEntry[];
+    /**
+     * Configurations for live agents under this invocation.
+     */
+    runConfig?: RunConfig;
+    /**
+     * A container to keep track of different kinds of costs incurred as a part of
+     * this invocation.
+     */
+    private readonly invocationCostManager;
+    /**
+     * The queue to receive live requests.
+     */
+    liveRequestQueue?: LiveRequestQueue;
+    /**
+     * The running streaming tools of this invocation.
+     */
+    activeStreamingTools?: Record<string, ActiveStreamingTool>;
+    /**
+     * The manager for keeping track of plugins in this invocation.
+     */
+    pluginManager: PluginManager;
+    /**
+     * @param params The parameters for creating an invocation context.
+     */
+    constructor(params: InvocationContextParams);
+    /**
+     * The app name of the current session.
+     */
+    get appName(): string;
+    /**
+     * The user ID of the current session.
+     */
+    get userId(): string;
+    /**
+     * Tracks number of llm calls made.
+     *
+     * @throws If number of llm calls made exceed the set threshold.
+     */
+    incrementLlmCallCount(): void;
+}
+export declare function newInvocationContextId(): string;
+export {};

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

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ActivityEnd, ActivityStart, Blob, Content } from '@google/genai';
+/**
+ * Request sent to live agents.
+ */
+export interface LiveRequest {
+    /** If set, send the content to the model in turn-by-turn mode. */
+    content?: Content;
+    /** If set, send the blob to the model in realtime mode. */
+    blob?: Blob;
+    /** If set, signal the start of user activity to the model. */
+    activityStart?: ActivityStart;
+    /** If set, signal the end of user activity to the model. */
+    activityEnd?: ActivityEnd;
+    /** If set, close the queue. */
+    close?: boolean;
+}
+/**
+ * Queue used to send LiveRequest in a live (bidirectional streaming) way.
+ */
+export declare class LiveRequestQueue {
+    private readonly queue;
+    private readonly resolveFnFifoQueue;
+    private isClosed;
+    /**
+     * Adds a request to the queue. If there is a pending `get()` call, it
+     * will be resolved with the given request.
+     * @param req The request to send.
+     */
+    send(req: LiveRequest): void;
+    /**
+     * Retrieves a request from the queue. If the queue is empty, it will
+     * wait until a request is available.
+     * @returns A promise that resolves with the next available request.
+     */
+    get(): Promise<LiveRequest>;
+    /**
+     * Sends a close signal to the queue.
+     */
+    close(): void;
+    /**
+     * Sends a content object to the queue.
+     * @param content The content to send.
+     */
+    sendContent(content: Content): void;
+    /**
+     * Sends a blob to the model in realtime mode.
+     * @param blob The blob to send.
+     */
+    sendRealtime(blob: Blob): void;
+    /**
+     * Sends an activity start signal to mark the beginning of user input.
+     */
+    sendActivityStart(): void;
+    /**
+     * Sends an activity end signal to mark the end of user input.
+     */
+    sendActivityEnd(): void;
+    /**
+     * Implements the async iterator protocol.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<LiveRequest, void, undefined>;
+}