@google/adk 2.2.1 → 2.3.0

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

@@ -65,6 +65,17 @@ export interface RunnerConfig {
      * An optional resumability configuration applied to the runner.
      */
     resumabilityConfig?: ResumabilityConfig;
+    /**
+     * Whether to create the session when `runAsync` is given a session id that
+     * does not exist. Defaults to `false`, which reports the missing session as
+     * an error instead.
+     *
+     * Enabling this trades a loud failure for a silent one: a caller that
+     * mistypes a session id gets a new empty conversation rather than an error.
+     * Turn it on only where the session id is a key the caller owns and a first
+     * use is expected to create it.
+     */
+    autoCreateSession?: boolean;
 }
 /**
  * A unique symbol to identify ADK agent classes.
@@ -116,12 +127,20 @@ export declare class Runner {
     readonly memoryService?: BaseMemoryService;
     readonly credentialService?: BaseCredentialService;
     readonly resumabilityConfig?: ResumabilityConfig;
+    readonly autoCreateSession: boolean;
     /**
      * Creates a new Runner instance.
      *
      * @param input The configuration for the runner.
      */
     constructor(input: RunnerConfig);
+    /**
+     * Looks the session up, creating it first when `autoCreateSession` is set.
+     *
+     * A runner with no `appName` cannot address a session, so it falls through to
+     * the plain lookup rather than creating one under an undefined app name.
+     */
+    private resolveSession;
     /**
      * Runs the agent with a new, ephemeral session.
      *
@@ -171,6 +190,21 @@ export declare class Runner {
      * plugins; there is nothing to lack if there is only one loop.
      */
     private runRoot;
+    /**
+     * Runs the on_event plugin callbacks on an event and appends the result to
+     * the session unless it is partial.
+     *
+     * @returns The event as streamed to the caller.
+     */
+    private processAndAppendEvent;
+    /**
+     * Seals an aborted invocation in session history: answers its dangling
+     * function calls with error responses, or records a plain abort event when
+     * there is nothing to answer.
+     *
+     * @returns The synthetic events after plugin processing and persistence.
+     */
+    private synthesizeAbortEvents;
     /**
      * Saves artifacts from the message parts and replaces the inline data with
      * a file name placeholder and optional file reference.

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

@@ -56,6 +56,9 @@ export declare class State {
     /**
      * Returns the value of the state dict for the given key.
      *
+     * Only keys the state holds itself are found. Names inherited from
+     * `Object.prototype`, such as `toString`, are treated as missing.
+     *
      * @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
@@ -70,7 +73,8 @@ export declare class State {
      */
     set(key: string, value: unknown): void;
     /**
-     * Whether the state has pending delta.
+     * Whether the state holds the given key, either as a stored value or as a
+     * pending delta. Names inherited from `Object.prototype` are not keys.
      */
     has(key: string): boolean;
     /**

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

@@ -20,7 +20,15 @@ export declare function isVertexAiConnectionString(uri?: string): boolean;
  */
 export declare function quoteFilterLiteral(value: string): string;
 export interface VertexAiSessionServiceOptions {
+    /**
+     * Google Cloud project ID. Defaults to `process.env.GOOGLE_CLOUD_PROJECT`
+     * unless `expressModeApiKey` is passed.
+     */
     projectId?: string;
+    /**
+     * Google Cloud location. Defaults to `process.env.GOOGLE_CLOUD_LOCATION`
+     * unless `expressModeApiKey` is passed.
+     */
     location?: string;
     agentEngineId?: string;
     expressModeApiKey?: string;

package/dist/types/skills/skill.d.ts

@@ -15,7 +15,7 @@ export declare const FrontmatterSchema: z.ZodPreprocess<z.ZodObject<{
     compatibility: z.ZodOptional<z.ZodString>;
     'allowed-tools': z.ZodOptional<z.ZodString>;
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
-}, z.core.$loose>>;
+}, z.core.$loose>, unknown>;
 export interface Frontmatter {
     name: string;
     description: string;

package/dist/types/telemetry/tracing.d.ts

@@ -63,16 +63,18 @@ export interface TraceToolCallParams {
     tool: BaseTool;
     args: Record<string, unknown>;
     functionResponseEvent: Event;
+    invocationContext: InvocationContext;
 }
 /**
  * Traces tool call.
  *
  * @param params The parameters object containing tool, args, and function response event.
  */
-export declare function traceToolCall({ tool, args, functionResponseEvent, }: TraceToolCallParams): void;
+export declare function traceToolCall({ tool, args, functionResponseEvent, invocationContext, }: TraceToolCallParams): void;
 export interface TraceMergedToolCallsParams {
     responseEventId: string;
     functionResponseEvent: Event;
+    invocationContext: InvocationContext;
 }
 /**
  * Traces merged tool call events.
@@ -82,7 +84,7 @@ export interface TraceMergedToolCallsParams {
  *
  * @param params The parameters object containing response event ID and function response event.
  */
-export declare function traceMergedToolCalls({ responseEventId, functionResponseEvent, }: TraceMergedToolCallsParams): void;
+export declare function traceMergedToolCalls({ responseEventId, functionResponseEvent, invocationContext, }: TraceMergedToolCallsParams): void;
 export interface TraceCallLlmParams {
     invocationContext: InvocationContext;
     eventId: string;

package/dist/types/tools/apihub_tool/apihub_toolset.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { OpenAPIV3 } from 'openapi-types';
+import { ReadonlyContext } from '../../agents/readonly_context.js';
+import { AuthCredential } from '../../auth/auth_credential.js';
+import { BaseTool } from '../base_tool.js';
+import { BaseToolset } from '../base_toolset.js';
+import { RestApiTool } from '../openapi_tool/rest_api_tool.js';
+import { BaseAPIHubClient } from './clients/apihub_client.js';
+/** Options for {@link APIHubToolset}. */
+export interface APIHubToolsetOptions {
+    /**
+     * The API Hub resource to build tools from. It must name an API, and may
+     * also name a version and a spec, for example
+     * `projects/my-project/locations/us-central1/apis/my-api`. An API Hub
+     * console URL is also accepted.
+     *
+     * When it names a spec, that spec is used. Otherwise the first spec of the
+     * named version, or of the first version of the named API, is used.
+     */
+    apihubResourceName: string;
+    /**
+     * An OAuth access token for API Hub, for example the output of
+     * `gcloud auth print-access-token`. Ignored when `apihubClient` is set.
+     */
+    accessToken?: string;
+    /**
+     * The content of a service account key file, as a JSON string, used to
+     * authenticate to API Hub when `accessToken` is not set. Ignored when
+     * `apihubClient` is set.
+     */
+    serviceAccountJson?: string;
+    /**
+     * The toolset name. When empty, it is set from the spec's `info.title` in
+     * snake_case, or `unnamed` when the spec has no title.
+     */
+    name?: string;
+    /**
+     * The toolset description. When empty, it is set from the spec's
+     * `info.description`.
+     */
+    description?: string;
+    /**
+     * When true, the spec is fetched on the first call to `getTools` or
+     * `getTool` instead of when the toolset is constructed.
+     */
+    lazyLoadSpec?: boolean;
+    /** Auth scheme applied to every tool the spec produces. */
+    authScheme?: OpenAPIV3.SecuritySchemeObject;
+    /** Auth credential applied to every tool the spec produces. */
+    authCredential?: AuthCredential;
+    /**
+     * The client that fetches the spec. Defaults to an {@link APIHubClient}
+     * built from `accessToken` and `serviceAccountJson`.
+     */
+    apihubClient?: BaseAPIHubClient;
+}
+/**
+ * Builds one tool per operation of an API registered in API Hub.
+ *
+ * The toolset fetches an OpenAPI spec from API Hub, parses it as YAML or JSON,
+ * and hands it to an {@link OpenAPIToolset}, which produces a
+ * {@link RestApiTool} for each operation.
+ *
+ * ```ts
+ * const toolset = new APIHubToolset({
+ *   apihubResourceName:
+ *     'projects/my-project/locations/us-central1/apis/my-api',
+ * });
+ * const agent = new LlmAgent({
+ *   name: 'api_agent',
+ *   model: 'gemini-flash-latest',
+ *   tools: [toolset],
+ * });
+ * ```
+ *
+ * By default the spec is fetched when the toolset is constructed. A
+ * constructor cannot wait for the request, so a failure is reported by the
+ * first call to `getTools` or `getTool`, and every later call reports the same
+ * failure.
+ *
+ * With `lazyLoadSpec`, the spec is fetched on the first call to `getTools` or
+ * `getTool`. A successful result is kept, including a spec that produced no
+ * tools. A failed fetch is not kept, so the next call fetches again.
+ */
+export declare class APIHubToolset extends BaseToolset {
+    /** The toolset name, filled in from the spec when empty. */
+    name: string;
+    /** The toolset description, filled in from the spec when empty. */
+    description: string;
+    readonly apihubResourceName: string;
+    readonly lazyLoadSpec: boolean;
+    private readonly apihubClient;
+    private readonly authScheme?;
+    private readonly authCredential?;
+    private toolsetPromise?;
+    constructor(options: APIHubToolsetOptions);
+    /**
+     * Returns one tool per operation in the spec, or an empty array when the
+     * spec is empty.
+     *
+     * @throws When the spec cannot be fetched or is not valid YAML or JSON.
+     */
+    getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
+    /**
+     * Returns the tool with the given name, or `undefined` when the spec
+     * produced no such tool.
+     *
+     * Unlike `OpenAPIToolset.getTool`, the result is a Promise, because the spec
+     * may still be loading.
+     *
+     * @param name The tool name, which is the operation ID in snake_case.
+     * @throws When the spec cannot be fetched or is not valid YAML or JSON.
+     */
+    getTool(name: string): Promise<RestApiTool | undefined>;
+    close(): Promise<void>;
+    private loadToolset;
+    private prepareTools;
+}

package/dist/types/tools/apihub_tool/clients/apihub_client.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Fetches the content of an API specification registered in API Hub.
+ *
+ * Implement this interface to give an `APIHubToolset` a different source of
+ * specs, such as a cache, a local file, or a test double.
+ */
+export interface BaseAPIHubClient {
+    /**
+     * Returns the content of the spec that `path` resolves to.
+     *
+     * @param path An API, API version or API spec resource name, or an API Hub
+     *     console URL.
+     */
+    getSpecContent(path: string): Promise<string>;
+}
+/** Options for {@link APIHubClient}. */
+export interface APIHubClientOptions {
+    /**
+     * An OAuth access token sent as the bearer token on every request, for
+     * example the output of `gcloud auth print-access-token`. Takes precedence
+     * over `serviceAccountJson`.
+     */
+    accessToken?: string;
+    /**
+     * The content of a service account key file, as a JSON string. Used to mint
+     * access tokens when `accessToken` is not set. When neither is set, the
+     * client uses application default credentials.
+     */
+    serviceAccountJson?: string;
+}
+/** An API resource as API Hub returns it. */
+export interface APIHubApi {
+    /** Resource name, `projects/{p}/locations/{l}/apis/{a}`. */
+    name: string;
+    /** Resource names of the versions of this API. */
+    versions?: string[];
+}
+/** An API version resource as API Hub returns it. */
+export interface APIHubApiVersion {
+    /** Resource name, `projects/{p}/locations/{l}/apis/{a}/versions/{v}`. */
+    name: string;
+    /** Resource names of the specs attached to this version. */
+    specs?: string[];
+}
+/** The resource names parsed out of an API Hub path or URL. */
+export interface APIHubResourceNames {
+    /** `projects/{p}/locations/{l}/apis/{a}`. */
+    apiResourceName: string;
+    /** `.../apis/{a}/versions/{v}`, when the input names a version. */
+    apiVersionResourceName?: string;
+    /** `.../versions/{v}/specs/{s}`, when the input names a version and a spec. */
+    apiSpecResourceName?: string;
+}
+/**
+ * Client for the API Hub REST API.
+ *
+ * Each request sends a bearer token. The token is `accessToken` when it is
+ * set; otherwise the client mints one from `serviceAccountJson`, or from
+ * application default credentials when that is not set either. Minted tokens
+ * are cached and refreshed by `google-auth-library`.
+ */
+export declare class APIHubClient implements BaseAPIHubClient {
+    private readonly accessToken?;
+    private readonly serviceAccountJson?;
+    private auth?;
+    constructor(options?: APIHubClientOptions);
+    /**
+     * Returns the content of the first spec that `path` resolves to.
+     *
+     * - A path naming an API resolves to the first spec of its first version.
+     * - A path naming an API version resolves to the first spec of that version.
+     * - A path naming an API spec resolves to that spec.
+     *
+     * `path` may be a resource name such as
+     * `projects/my-project/locations/us-central1/apis/my-api`, or a console URL
+     * such as
+     * `https://console.cloud.google.com/apigee/api-hub/locations/us-central1/apis/my-api?project=my-project`.
+     *
+     * @param path The API, API version or API spec to read.
+     * @return The decoded spec content, or `''` when the spec is empty.
+     * @throws When the path cannot be parsed, when the API has no versions, when
+     *     the version has no specs, or when a request fails.
+     */
+    getSpecContent(path: string): Promise<string>;
+    /**
+     * Lists the APIs registered in a project and location.
+     *
+     * @param project The Google Cloud project ID.
+     * @param location The API Hub location, for example `us-central1`.
+     * @return The APIs, or an empty array when there are none.
+     */
+    listApis(project: string, location: string): Promise<APIHubApi[]>;
+    /**
+     * Gets an API by resource name.
+     *
+     * @param apiResourceName `projects/{p}/locations/{l}/apis/{a}`.
+     */
+    getApi(apiResourceName: string): Promise<APIHubApi>;
+    /**
+     * Gets an API version by resource name.
+     *
+     * @param apiVersionName `projects/{p}/locations/{l}/apis/{a}/versions/{v}`.
+     */
+    getApiVersion(apiVersionName: string): Promise<APIHubApiVersion>;
+    /** Reads the base64-encoded contents of a spec and decodes them as UTF-8. */
+    private fetchSpec;
+    /** Sends an authenticated GET request and parses the JSON response. */
+    private get;
+    /**
+     * Returns the bearer token for the next request.
+     *
+     * `GoogleAuth` is created once and reused, so that it can cache the token
+     * and refresh it when it expires.
+     */
+    private getAccessToken;
+    /**
+     * Builds the error for a token that could not be obtained.
+     *
+     * Without a service account, the likely fix is to supply a credential. With
+     * one, the key itself was rejected, so the error says so and gives the
+     * reason.
+     */
+    private tokenError;
+    private createAuth;
+}
+/**
+ * Extracts the API, API version and API spec resource names from an API Hub
+ * resource path or console URL.
+ *
+ * The project comes from a `projects/{p}` segment, or from a `project` query
+ * parameter when the path has none. The location and the API are required.
+ * The spec name is returned only when both a version and a spec are present.
+ *
+ * @param urlOrPath A resource name, or a console URL under `api-hub/`.
+ * @throws When the project, the location or the API cannot be found.
+ */
+export declare function extractResourceName(urlOrPath: string): APIHubResourceNames;

package/dist/types/tools/apihub_tool/clients/secret_client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Options for {@link SecretManagerClient}. */
+export interface SecretManagerClientOptions {
+    /**
+     * The content of a service account key file, as a JSON string, not a path.
+     * Takes precedence over `authToken`.
+     */
+    serviceAccountJson?: string;
+    /** An existing OAuth access token. */
+    authToken?: string;
+}
+/**
+ * Reads secrets from Google Cloud Secret Manager.
+ *
+ * The client authenticates with `serviceAccountJson` when it is set, then with
+ * `authToken`, and otherwise with application default credentials.
+ *
+ * `@google-cloud/secret-manager` is an optional peer dependency. It is loaded
+ * on the first call to {@link SecretManagerClient.getSecret}, so constructing
+ * the client does not require it.
+ */
+export declare class SecretManagerClient {
+    private readonly credentials?;
+    private readonly authToken?;
+    private clientPromise?;
+    /**
+     * @throws `Invalid service account JSON: ...` when `serviceAccountJson`
+     *     does not parse.
+     */
+    constructor(options?: SecretManagerClientOptions);
+    /**
+     * Returns the payload of a secret version as a UTF-8 string.
+     *
+     * @param resourceName The secret version, in the form
+     *     `projects/{project}/secrets/{secret}/versions/{version}`. Use
+     *     `latest` as the version to read the newest one.
+     * @throws When default credentials are needed and cannot be resolved, or
+     *     when Secret Manager returns an error, such as a missing secret or a
+     *     denied permission.
+     */
+    getSecret(resourceName: string): Promise<string>;
+    /**
+     * Resolves the Secret Manager client, loading the optional peer and the
+     * credentials on first use.
+     *
+     * A created client is kept. A failure is not kept, so the next call tries
+     * again, for example once default credentials become available.
+     */
+    private getClient;
+    private createClient;
+}

package/dist/types/tools/apihub_tool/clients/service_account.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Parses a service account key from its JSON text.
+ *
+ * @throws `Invalid service account JSON: ...` when `json` does not parse.
+ */
+export declare function parseServiceAccountJson(json: string): Record<string, string>;

package/dist/types/tools/application_integration_tool/application_integration_toolset.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseTool } from '../base_tool.js';
+import { BaseToolset } from '../base_toolset.js';
+/** Options of {@link ApplicationIntegrationToolset}. */
+export interface ApplicationIntegrationToolsetOptions {
+    /** The Google Cloud project ID. */
+    project: string;
+    /** The Google Cloud location, such as `us-central1`. */
+    location: string;
+    /** The integration name. Set it together with `trigger`. */
+    integration?: string;
+    /** The API trigger ID of the integration, such as `api_trigger/my_trigger`. */
+    trigger?: string;
+    /**
+     * The Integration Connectors connection name. Set it together with
+     * `entityOperations`, `actions`, or both.
+     */
+    connection?: string;
+    /**
+     * Operations to expose, keyed by entity name, such as
+     * `{Issues: ['LIST', 'GET']}`. An empty list exposes every operation the
+     * entity supports.
+     */
+    entityOperations?: Record<string, string[]>;
+    /** Connection actions to expose, such as `['ExecuteCustomQuery']`. */
+    actions?: string[];
+    /** Prefix of every generated tool name. Defaults to `''`. */
+    toolName?: string;
+    /** Text appended to every generated tool description. Defaults to `''`. */
+    toolInstructions?: string;
+    /**
+     * A service-account key, as a JSON string. It authenticates both the spec
+     * requests and the generated tools. When omitted, both use Application
+     * Default Credentials.
+     */
+    serviceAccountJson?: string;
+}
+/**
+ * A toolset generated from a Google Cloud Application Integration API trigger,
+ * or from the entity operations and actions of an Integration Connectors
+ * connection.
+ *
+ * The constructor only validates the options. The first `getTools` call
+ * fetches the spec and builds the tools, and later calls reuse them.
+ *
+ * @example
+ * // Every operation of an integration API trigger.
+ * const integrationToolset = new ApplicationIntegrationToolset({
+ *   project: 'my-project',
+ *   location: 'us-central1',
+ *   integration: 'my-integration',
+ *   trigger: 'api_trigger/my_trigger',
+ * });
+ *
+ * @example
+ * // Entity operations and actions of a connection.
+ * const connectionToolset = new ApplicationIntegrationToolset({
+ *   project: 'my-project',
+ *   location: 'us-central1',
+ *   connection: 'my-connection',
+ *   entityOperations: {Issues: ['LIST', 'GET'], Projects: []},
+ *   actions: ['ExecuteCustomQuery'],
+ * });
+ */
+export declare class ApplicationIntegrationToolset extends BaseToolset {
+    private readonly options;
+    private toolsPromise?;
+    /**
+     * @throws Error Unless the options name either an integration and a trigger,
+     *   or a connection with at least one entity operation or action.
+     */
+    constructor(options: ApplicationIntegrationToolsetOptions);
+    /**
+     * Returns the generated tools.
+     *
+     * The first call fetches the spec and builds the tools. Concurrent calls
+     * share that load. When it fails, the next call tries again.
+     */
+    getTools(): Promise<BaseTool[]>;
+    close(): Promise<void>;
+    private loadTools;
+}

package/dist/types/tools/application_integration_tool/clients/cloud_request.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** OAuth scope every Integration Connectors and Application Integration call needs. */
+export declare const CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+/** Wraps a failure as `An unexpected error occurred: …`. */
+export declare function unexpectedError(e: unknown): Error;
+/**
+ * Supplies cloud-platform access tokens from a service-account key, or from
+ * Application Default Credentials when no key is given.
+ *
+ * One instance holds one `GoogleAuth`, which caches the token and refreshes it
+ * before it expires.
+ */
+export declare class CloudPlatformTokenSource {
+    private readonly serviceAccountJson?;
+    private auth?;
+    constructor(serviceAccountJson?: string | undefined);
+    /**
+     * Returns an access token.
+     *
+     * @throws Error When no key is given and Application Default Credentials are
+     *   unavailable, or when no token is issued.
+     */
+    getAccessToken(): Promise<string>;
+    private getAuth;
+}
+/** Options for {@link sendCloudRequest}. */
+export interface SendCloudRequestOptions {
+    /** The request URL. */
+    url: string;
+    /** The HTTP method. */
+    method: 'GET' | 'POST';
+    /** The JSON request body for a POST request. */
+    body?: unknown;
+    /** Supplies the bearer token. */
+    tokenSource: CloudPlatformTokenSource;
+    /** The message for an HTTP 400 or 404 response. */
+    invalidRequestMessage: string;
+}
+/**
+ * Sends an authenticated JSON request to a Google Cloud API and returns the
+ * parsed response body.
+ *
+ * @param options The request URL, method, body, token source, and 400/404 message.
+ * @throws Error `invalidRequestMessage` for HTTP 400 and 404,
+ *   `Request error: …` for any other non-2xx status or a failed fetch, and
+ *   `An unexpected error occurred: …` for anything else, such as a missing
+ *   credential or a body that is not JSON.
+ */
+export declare function sendCloudRequest(options: SendCloudRequestOptions): Promise<unknown>;