@softactivate/adk 1.1.0

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/processors/base_llm_processor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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';
+/**
+ * Base class for LLM request processor.
+ */
+export declare abstract class BaseLlmRequestProcessor {
+    /**
+     * Runs the processor.
+     */
+    abstract runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+}
+/**
+ * Base class for LLM response processor.
+ */
+export declare abstract class BaseLlmResponseProcessor {
+    /**
+     * Processes the LLM response.
+     */
+    abstract runAsync(invocationContext: InvocationContext, llmResponse: LlmResponse): AsyncGenerator<Event, void, void>;
+}

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_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/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/context_compactor_request_processor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseContextCompactor } from '../../context/base_context_compactor.js';
+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';
+/**
+ * A processor that evaluates a set of compactors to optionally compact
+ * the conversation history (events) prior to generating an LLM request.
+ *
+ * It evaluates each compactor in priority order. The first one that indicates
+ * it should compact will perform the compaction and iteration stops.
+ */
+export declare class ContextCompactorRequestProcessor implements BaseLlmRequestProcessor {
+    private compactors;
+    constructor(compactors: BaseContextCompactor[]);
+    runAsync(invocationContext: InvocationContext, _llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+}

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/processors/tool_filter_request_processor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @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 ToolFilterRequestProcessor extends BaseLlmRequestProcessor {
+    /** Filters the set of tools on the request based on plugins. */
+    runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+}
+export declare const TOOL_FILTER_REQUEST_PROCESSOR: ToolFilterRequestProcessor;

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

@@ -0,0 +1,39 @@
+/**
+ * @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 user ID of the current session.
+     */
+    get userId(): string;
+    /**
+     * The ID of the current session.
+     */
+    get sessionId(): string;
+    /**
+     * The current agent name.
+     */
+    get agentName(): string;
+    /**
+     * The state of the current session.
+     */
+    get state(): Readonly<State>;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2026 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';
+/**
+ * A unique symbol to identify ADK agent classes.
+ * Defined once and shared by all RoutedAgent instances.
+ */
+declare const ROUTED_AGENT_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of RoutedAgent.
+ * @param obj The object to check.
+ * @returns True if the object is an instance of RoutedAgent, false otherwise.
+ */
+export declare function isRoutedAgent(obj: unknown): obj is RoutedAgent;
+/**
+ * Type definition for a function that selects an agent based on the invocation context.
+ */
+export type AgentRouter = (agents: Readonly<Record<string, BaseAgent>>, context: InvocationContext, errorContext?: {
+    failedKeys: ReadonlySet<string>;
+    lastError: unknown;
+}) => Promise<string | undefined> | string | undefined;
+/**
+ * Configuration for the RoutingAgent.
+ */
+export interface RoutedAgentConfig extends BaseAgentConfig {
+    /**
+     * The set of agents to route to. Can be an array of agents or a Record of keys to agents.
+     * If an array is provided, the agent names will be used as keys.
+     */
+    agents: Readonly<Record<string, BaseAgent>> | BaseAgent[];
+    /**
+     * The function to select which agent to run.
+     */
+    router: AgentRouter;
+}
+/**
+ * A BaseAgent implementation that delegates to one of multiple agents based on a router function.
+ * Routing is strictly limited to the agents passed in the config.
+ */
+export declare class RoutedAgent extends BaseAgent {
+    readonly [ROUTED_AGENT_SIGNATURE_SYMBOL] = true;
+    private readonly agents;
+    private readonly router;
+    constructor(config: RoutedAgentConfig);
+    /**
+     * Runs the selected agent via text-based conversation.
+     */
+    protected runAsyncImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+    /**
+     * Runs the selected agent via video/audio-based conversation.
+     */
+    protected runLiveImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+}
+export {};

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

@@ -0,0 +1,94 @@
+/**
+ * @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 interface 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;
+    /**
+     * 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;
+    responseModalities?: Modality[] | undefined;
+    saveInputBlobsAsArtifacts: boolean;
+    supportCfc: boolean;
+    streamingMode: StreamingMode;
+    outputAudioTranscription?: AudioTranscriptionConfig | undefined;
+    inputAudioTranscription?: AudioTranscriptionConfig | undefined;
+    enableAffectiveDialog: boolean;
+    proactivity?: ProactivityConfig | undefined;
+    realtimeInputConfig?: RealtimeInputConfig | undefined;
+    maxLlmCalls: number;
+    pauseOnToolCalls: boolean;
+};

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

@@ -0,0 +1,42 @@
+/**
+ * @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 unique symbol to identify ADK agent classes.
+ * Defined once and shared by all SequentialAgent instances.
+ */
+declare const SEQUENTIAL_AGENT_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of SequentialAgent.
+ * @param obj The object to check.
+ * @returns True if the object is an instance of SequentialAgent, false otherwise.
+ */
+export declare function isSequentialAgent(obj: unknown): obj is SequentialAgent;
+/**
+ * A shell agent that runs its sub-agents in a sequential order.
+ */
+export declare class SequentialAgent extends BaseAgent {
+    /**
+     * A unique symbol to identify ADK sequential agent class.
+     */
+    readonly [SEQUENTIAL_AGENT_SIGNATURE_SYMBOL] = true;
+    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>;
+}
+export {};

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,158 @@
+/**
+ * @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;
+    /**
+     * Optional custom metadata to save with the artifact.
+     */
+    customMetadata?: Record<string, unknown>;
+}
+/**
+ * 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;
+}
+/**
+ * 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.
+ */
+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[]>;
+    /**
+     * 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>;
+}