@google/adk 0.1.0

package/dist/types/plugins/security_plugin.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionCall } from '@google/genai';
+import { Event } from '../events/event.js';
+import { BasePlugin } from '../plugins/base_plugin.js';
+import { BaseTool } from '../tools/base_tool.js';
+import { ToolContext } from '../tools/tool_context.js';
+export declare const REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation";
+/**
+ * The outcome of a policy check.
+ */
+export declare enum PolicyOutcome {
+    DENY = "DENY",
+    CONFIRM = "CONFIRM",
+    ALLOW = "ALLOW"
+}
+export interface PolicyCheckResult {
+    outcome: string;
+    reason?: string;
+}
+export interface ToolCallPolicyContext {
+    tool: BaseTool;
+    toolArgs: Record<string, unknown>;
+}
+export interface BasePolicyEngine {
+    evaluate(context: ToolCallPolicyContext): Promise<PolicyCheckResult>;
+}
+export declare class InMemoryPolicyEngine implements BasePolicyEngine {
+    evaluate(context: ToolCallPolicyContext): Promise<PolicyCheckResult>;
+}
+/**
+ *  Security Plugin for running Orcas agents.
+ */
+export declare class SecurityPlugin extends BasePlugin {
+    private readonly policyEngine;
+    constructor(params?: {
+        policyEngine?: BasePolicyEngine;
+    });
+    beforeToolCallback({ tool, toolArgs, toolContext, }: {
+        tool: BaseTool;
+        toolArgs: {
+            [key: string]: unknown;
+        };
+        toolContext: ToolContext;
+    }): Promise<{
+        [key: string]: unknown;
+    } | undefined>;
+    private getToolCallCheckState;
+    private setToolCallCheckState;
+    private checkToolCallPolicy;
+}
+/**
+ * Gets the ask user confirmation function calls from the event.
+ * @param event The event to get the function calls from.
+ * @returns The ask user confirmation function calls.
+ */
+export declare function getAskUserConfirmationFunctionCalls(event: Event): FunctionCall[];

package/dist/types/runner/in_memory_runner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseAgent } from '../agents/base_agent.js';
+import { BasePlugin } from '../plugins/base_plugin.js';
+import { Runner } from './runner.js';
+export declare class InMemoryRunner extends Runner {
+    constructor({ agent, appName, plugins, }: {
+        agent: BaseAgent;
+        appName?: string;
+        plugins?: BasePlugin[];
+    });
+}

package/dist/types/runner/runner.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import { BaseAgent } from '../agents/base_agent.js';
+import { RunConfig } from '../agents/run_config.js';
+import { BaseArtifactService } from '../artifacts/base_artifact_service.js';
+import { BaseCredentialService } from '../auth/credential_service/base_credential_service.js';
+import { Event } from '../events/event.js';
+import { BaseMemoryService } from '../memory/base_memory_service.js';
+import { BasePlugin } from '../plugins/base_plugin.js';
+import { PluginManager } from '../plugins/plugin_manager.js';
+import { BaseSessionService } from '../sessions/base_session_service.js';
+interface RunnerInput {
+    appName: string;
+    agent: BaseAgent;
+    plugins?: BasePlugin[];
+    artifactService?: BaseArtifactService;
+    sessionService: BaseSessionService;
+    memoryService?: BaseMemoryService;
+    credentialService?: BaseCredentialService;
+}
+export declare class Runner {
+    readonly appName: string;
+    readonly agent: BaseAgent;
+    readonly pluginManager: PluginManager;
+    readonly artifactService?: BaseArtifactService;
+    readonly sessionService: BaseSessionService;
+    readonly memoryService?: BaseMemoryService;
+    readonly credentialService?: BaseCredentialService;
+    constructor(input: RunnerInput);
+    /**
+     * Runs the agent with the given message, and returns an async generator of
+     * events.
+     *
+     * @param userId The user ID of the session.
+     * @param sessionId The session ID of the session.
+     * @param newMessage A new message to append to the session.
+     * @param stateDelta An optional state delta to apply to the session.
+     * @param runConfig The run config for the agent.
+     * @yields The events generated by the agent.
+     */
+    runAsync({ userId, sessionId, newMessage, stateDelta, runConfig, }: {
+        userId: string;
+        sessionId: string;
+        newMessage: Content;
+        stateDelta?: Record<string, any>;
+        runConfig?: RunConfig;
+    }): AsyncGenerator<Event, void, undefined>;
+    /**
+     * Saves artifacts from the message parts and replaces the inline data with
+     * a file name placeholder.
+     *
+     * @param invocationId The current invocation ID.
+     * @param userId The user ID of the session.
+     * @param sessionId The session ID of the session.
+     * @param message The message containing parts to process.
+     */
+    private saveArtifacts;
+    /**
+     * Determines the next agent to run to continue the session. This is primarily
+     * used for session resumption.
+     */
+    private determineAgentForResumption;
+    /**
+     * Whether the agent to run can transfer to any other agent in the agent tree.
+     *
+     * An agent is transferable if:
+     *  - It is an instance of `LlmAgent`.
+     *  - All its ancestors are also transferable (i.e., they have
+     *    `disallowTransferToParent` set to false).
+     *
+     * @param agentToRun The agent to check for transferability.
+     * @returns True if the agent can transfer, False otherwise.
+     */
+    private isRoutableLlmAgent;
+}
+export {};

package/dist/types/sessions/base_session_service.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../events/event.js';
+import { Session } from './session.js';
+/**
+ * The configuration of getting a session.
+ */
+export interface GetSessionConfig {
+    /** The number of recent events to retrieve. */
+    numRecentEvents?: number;
+    /** Retrieve events after this timestamp. */
+    afterTimestamp?: number;
+}
+/**
+ * The parameters for `createSession`.
+ */
+export interface CreateSessionRequest {
+    /** The name of the application. */
+    appName: string;
+    /** The ID of the user. */
+    userId: string;
+    /** The initial state of the session. */
+    state?: Record<string, unknown>;
+    /** The ID of the session. A new ID will be generated if not provided. */
+    sessionId?: string;
+}
+/**
+ * The parameters for `getSession`.
+ */
+export interface GetSessionRequest {
+    /** The name of the application. */
+    appName: string;
+    /** The ID of the user. */
+    userId: string;
+    /** The ID of the session. */
+    sessionId: string;
+    /** The configurations for getting the session. */
+    config?: GetSessionConfig;
+}
+/**
+ * The parameters for `listSessions`.
+ */
+export interface ListSessionsRequest {
+    /** The name of the application. */
+    appName: string;
+    /** The ID of the user. */
+    userId: string;
+}
+/**
+ * The parameters for `deleteSession`.
+ */
+export interface DeleteSessionRequest {
+    /** The name of the application. */
+    appName: string;
+    /** The ID of the user. */
+    userId: string;
+    /** The ID of the session. */
+    sessionId: string;
+}
+/**
+ * The parameters for `appendEvent`.
+ */
+export interface AppendEventRequest {
+    /** The session to append the event to. */
+    session: Session;
+    /** The event to append. */
+    event: Event;
+}
+/**
+ * The response of listing sessions.
+ *
+ * The events and states are not set within each Session object.
+ */
+export interface ListSessionsResponse {
+    /** A list of sessions. */
+    sessions: Session[];
+}
+/**
+ * Base class for session services.
+ *
+ * The service provides a set of methods for managing sessions and events.
+ */
+export declare abstract class BaseSessionService {
+    /**
+     * Creates a new session.
+     *
+     * @param request The request to create a session.
+     * @return A promise that resolves to the newly created session instance.
+     */
+    abstract createSession(request: CreateSessionRequest): Promise<Session>;
+    /**
+     * Gets a session.
+     *
+     * @param request The request to get a session.
+     * @return A promise that resolves to the session instance or undefined if not
+     *     found.
+     */
+    abstract getSession(request: GetSessionRequest): Promise<Session | undefined>;
+    /**
+     * Lists sessions for a user.
+     *
+     * @param request The request to list sessions.
+     * @return A promise that resolves to a list of sessions for the user.
+     */
+    abstract listSessions(request: ListSessionsRequest): Promise<ListSessionsResponse>;
+    /**
+     * Deletes a session.
+     *
+     * @param request The request to delete a session.
+     * @return A promise that resolves when the session is deleted.
+     */
+    abstract deleteSession(request: DeleteSessionRequest): Promise<void>;
+    /**
+     * Appends an event to a session.
+     *
+     * @param request The request to append an event.
+     * @return A promise that resolves to the event that was appended.
+     */
+    appendEvent({ session, event }: AppendEventRequest): Promise<Event>;
+    /**
+     * Updates the session state based on the event.
+     *
+     * @param request The request to update the session state.
+     */
+    private updateSessionState;
+}

package/dist/types/sessions/in_memory_session_service.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../events/event.js';
+import { AppendEventRequest, BaseSessionService, CreateSessionRequest, DeleteSessionRequest, GetSessionRequest, ListSessionsRequest, ListSessionsResponse } from './base_session_service.js';
+import { Session } from './session.js';
+/**
+ * An in-memory implementation of the session service.
+ */
+export declare class InMemorySessionService extends BaseSessionService {
+    /**
+     * A map from app name to a map from user ID to a map from session ID to
+     * session.
+     */
+    private sessions;
+    /**
+     * A map from app name to a map from user ID to a map from key to the value.
+     */
+    private userState;
+    /**
+     * A map from app name to a map from key to the value.
+     */
+    private appState;
+    createSession({ appName, userId, state, sessionId }: CreateSessionRequest): Promise<Session>;
+    getSession({ appName, userId, sessionId, config }: GetSessionRequest): Promise<Session | undefined>;
+    listSessions({ appName, userId }: ListSessionsRequest): Promise<ListSessionsResponse>;
+    deleteSession({ appName, userId, sessionId }: DeleteSessionRequest): Promise<void>;
+    appendEvent({ session, event }: AppendEventRequest): Promise<Event>;
+    private mergeState;
+}

package/dist/types/sessions/session.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../events/event.js';
+/**
+ * Represents a session in a conversation between agents and users.
+ */
+export interface Session {
+    /**
+     * The unique identifier of the session.
+     */
+    id: string;
+    /**
+     * The name of the app.
+     */
+    appName: string;
+    /**
+     * The id of the user.
+     */
+    userId: string;
+    /**
+     * The state of the session.
+     */
+    state: Record<string, unknown>;
+    /**
+     * The events of the session, e.g. user input, model response, function
+     * call/response, etc.
+     */
+    events: Event[];
+    /**
+     * The last update time of the session.
+     */
+    lastUpdateTime: number;
+}
+/**
+ * Creates a session from a partial session.
+ *
+ * @param params The partial session to create the session from.
+ * @returns The session.
+ */
+export declare function createSession(params: Partial<Session> & {
+    id: string;
+    appName: string;
+}): Session;

package/dist/types/sessions/state.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A state mapping that maintains the current value and the pending-commit
+ * delta.
+ */
+export declare class State {
+    /** The current value of the state. */
+    private value;
+    /** The delta change to the current value that hasn't been committed. */
+    private delta;
+    static readonly APP_PREFIX = "app:";
+    static readonly USER_PREFIX = "user:";
+    static readonly TEMP_PREFIX = "temp:";
+    constructor(
+    /** The current value of the state. */
+    value: Record<string, unknown>, 
+    /** The delta change to the current value that hasn't been committed. */
+    delta: Record<string, unknown>);
+    /**
+     * Returns the value of the state dict for the given key.
+     *
+     * @param key The key to get the value for.
+     * @param defaultValue The default value to return if the key is not found.
+     * @return The value of the state for the given key, or the default value if
+     *     not found.
+     */
+    get<T>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Sets the value of the state dict for the given key.
+     *
+     * @param key The key to set the value for.
+     * @param value The value to set.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Whether the state has pending delta.
+     */
+    has(key: string): boolean;
+    /**
+     * Whether the state has pending delta.
+     */
+    hasDelta(): boolean;
+    /**
+     * Updates the state dict with the given delta.
+     *
+     * @param delta The delta to update the state with.
+     */
+    update(delta: Record<string, unknown>): void;
+    /**
+     * Returns the state as a plain JSON object.
+     */
+    toRecord(): Record<string, unknown>;
+}

package/dist/types/tools/agent_tool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration } from '@google/genai';
+import { BaseAgent } from '../agents/base_agent.js';
+import { BaseTool, RunAsyncToolRequest } from './base_tool.js';
+/**
+ * The configuration of the agent tool.
+ */
+export interface AgentToolConfig {
+    /**
+     * The reference to the agent instance.
+     */
+    agent: BaseAgent;
+    /**
+     * Whether to skip summarization of the agent output.
+     */
+    skipSummarization?: boolean;
+}
+/**
+ * A tool that wraps an agent.
+ *
+ * This tool allows an agent to be called as a tool within a larger
+ * application. The agent's input schema is used to define the tool's input
+ * parameters, and the agent's output is returned as the tool's result.
+ *
+ *  @param config: The configuration of the agent tool.
+ */
+export declare class AgentTool extends BaseTool {
+    private readonly agent;
+    private readonly skipSummarization;
+    constructor(config: AgentToolConfig);
+    _getDeclaration(): FunctionDeclaration;
+    runAsync({ args, toolContext }: RunAsyncToolRequest): Promise<unknown>;
+}

package/dist/types/tools/base_tool.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration } from '@google/genai';
+import { LlmRequest } from '../models/llm_request.js';
+import { ToolContext } from './tool_context.js';
+/**
+ * The parameters for `runAsync`.
+ */
+export interface RunAsyncToolRequest {
+    args: Record<string, unknown>;
+    toolContext: ToolContext;
+}
+/**
+ * The parameters for `processLlmRequest`.
+ */
+export interface ToolProcessLlmRequest {
+    toolContext: ToolContext;
+    llmRequest: LlmRequest;
+}
+/**
+ * Parameters for the BaseTool constructor.
+ */
+export interface BaseToolParams {
+    name: string;
+    description: string;
+    isLongRunning?: boolean;
+}
+/**
+ * The base class for all tools.
+ */
+export declare abstract class BaseTool {
+    readonly name: string;
+    readonly description: string;
+    readonly isLongRunning: boolean;
+    /**
+     * Base constructor for a tool.
+     *
+     * @param params The parameters for `BaseTool`.
+     */
+    constructor(params: BaseToolParams);
+    /**
+     * Gets the OpenAPI specification of this tool in the form of a
+     * FunctionDeclaration.
+     *
+     * NOTE
+     * - Required if subclass uses the default implementation of
+     *   `processLlmRequest` to add function declaration to LLM request.
+     * - Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
+     *   Gemini.
+     *
+     * @return The FunctionDeclaration of this tool, or undefined if it doesn't
+     *     need to be added to LlmRequest.config.
+     */
+    _getDeclaration(): FunctionDeclaration | undefined;
+    /**
+     * Runs the tool with the given arguments and context.
+     *
+     * NOTE
+     * - Required if this tool needs to run at the client side.
+     * - Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
+     *   Gemini.
+     *
+     * @param request The request to run the tool.
+     * @return A promise that resolves to the tool response.
+     */
+    abstract runAsync(request: RunAsyncToolRequest): Promise<unknown>;
+    /**
+     * Processes the outgoing LLM request for this tool.
+     *
+     * Use cases:
+     * - Most common use case is adding this tool to the LLM request.
+     * - Some tools may just preprocess the LLM request before it's sent out.
+     *
+     * @param request The request to process the LLM request.
+     */
+    processLlmRequest({ toolContext, llmRequest }: ToolProcessLlmRequest): Promise<void>;
+    /**
+     * The Google API LLM variant to use.
+     */
+    get apiVariant(): import("../utils/variant_utils.js").GoogleLLMVariant;
+}

package/dist/types/tools/base_toolset.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ReadonlyContext } from '../agents/readonly_context.js';
+import { LlmRequest } from '../models/llm_request.js';
+import { BaseTool } from './base_tool.js';
+import { ToolContext } from './tool_context.js';
+/**
+ * Function to decide whether a tool should be exposed to LLM. Toolset
+ * implementer could consider whether to accept such instance in the toolset's
+ * constructor and apply the predicate in getTools method.
+ */
+export type ToolPredicate = (tool: BaseTool, readonlyContext: ReadonlyContext) => boolean;
+/**
+ * Base class for toolset.
+ *
+ * A toolset is a collection of tools that can be used by an agent.
+ */
+export declare abstract class BaseToolset {
+    readonly toolFilter: ToolPredicate | string[];
+    constructor(toolFilter: ToolPredicate | string[]);
+    /**
+     * Returns the tools that should be exposed to LLM.
+     *
+     * @param context Context used to filter tools available to the agent. If
+     *     not defined, all tools in the toolset are returned.
+     * @return A Promise that resolves to the list of tools.
+     */
+    abstract getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
+    /**
+     * Closes the toolset.
+     *
+     * NOTE: This method is invoked, for example, at the end of an agent server's
+     * lifecycle or when the toolset is no longer needed. Implementations
+     * should ensure that any open connections, files, or other managed
+     * resources are properly released to prevent leaks.
+     *
+     * @return A Promise that resolves when the toolset is closed.
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Returns whether the tool should be exposed to LLM.
+     *
+     * @param tool The tool to check.
+     * @param context Context used to filter tools available to the agent.
+     * @return Whether the tool should be exposed to LLM.
+     */
+    protected isToolSelected(tool: BaseTool, context: ReadonlyContext): boolean;
+    /**
+     * Processes the outgoing LLM request for this toolset. This method will be
+     * called before each tool processes the llm request.
+     *
+     * Use cases:
+     * - Instead of let each tool process the llm request, we can let the toolset
+     *   process the llm request. e.g. ComputerUseToolset can add computer use
+     *   tool to the llm request.
+     *
+     * @param toolContext The context of the tool.
+     * @param llmRequest The outgoing LLM request, mutable this method.
+     */
+    processLlmRequest(toolContext: ToolContext, llmRequest: LlmRequest): Promise<void>;
+}

package/dist/types/tools/forwarding_artifact_service.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Part } from '@google/genai';
+import { BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from '../artifacts/base_artifact_service.js';
+import { ToolContext } from './tool_context.js';
+/**
+ * Artifact service that forwards to the parent tool context.
+ */
+export declare class ForwardingArtifactService implements BaseArtifactService {
+    private readonly toolContext;
+    private readonly invocationContext;
+    constructor(toolContext: ToolContext);
+    saveArtifact(request: SaveArtifactRequest): Promise<number>;
+    loadArtifact(request: LoadArtifactRequest): Promise<Part | undefined>;
+    listArtifactKeys(request: ListArtifactKeysRequest): Promise<string[]>;
+    deleteArtifact(request: DeleteArtifactRequest): Promise<void>;
+    listVersions(request: ListVersionsRequest): Promise<number[]>;
+}

package/dist/types/tools/function_tool.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration, Schema } from '@google/genai';
+import { type infer as zInfer, ZodObject } from 'zod';
+import { BaseTool, RunAsyncToolRequest } from './base_tool.js';
+import { ToolContext } from './tool_context.js';
+/**
+ * Input parameters of the function tool.
+ */
+export type ToolInputParameters = undefined | ZodObject<any> | Schema;
+export type ToolExecuteArgument<TParameters extends ToolInputParameters> = TParameters extends ZodObject<any> ? zInfer<TParameters> : TParameters extends Schema ? unknown : string;
+type ToolExecuteFunction<TParameters extends ToolInputParameters> = (input: ToolExecuteArgument<TParameters>, tool_context?: ToolContext) => Promise<unknown> | unknown;
+/**
+ * The configuration options for creating a function-based tool.
+ * The `name`, `description` and `parameters` fields are used to generate the
+ * tool definition that is passed to the LLM prompt.
+ *
+ * Note: Unlike Python's ADK, JSDoc on the `execute` function is ignored
+ * for tool definition generation.
+ */
+export type ToolOptions<TParameters extends ToolInputParameters> = {
+    name?: string;
+    description: string;
+    parameters?: TParameters;
+    execute: ToolExecuteFunction<TParameters>;
+    isLongRunning?: boolean;
+};
+export declare class FunctionTool<TParameters extends ToolInputParameters = undefined> extends BaseTool {
+    private readonly execute;
+    private readonly parameters?;
+    /**
+     * The constructor acts as the user-friendly factory.
+     * @param options The configuration for the tool.
+     */
+    constructor(options: ToolOptions<TParameters>);
+    /**
+     * Provide a schema for the function.
+     */
+    _getDeclaration(): FunctionDeclaration;
+    /**
+     * Logic for running the tool.
+     */
+    runAsync(req: RunAsyncToolRequest): Promise<unknown>;
+}
+export {};