@google/adk 2.2.1 → 2.4.0

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

@@ -14,7 +14,7 @@
  *    constructs of the framework that are not observable by the SDK.
  */
 import { Content } from '@google/genai';
-import { Context } from '@opentelemetry/api';
+import { Context, Span } from '@opentelemetry/api';
 import { BaseAgent } from '../agents/base_agent.js';
 import { InvocationContext } from '../agents/invocation_context.js';
 import { Event } from '../events/event.js';
@@ -62,17 +62,33 @@ export declare function traceNodeExecution({ nodePath, runId, attempt, status, i
 export interface TraceToolCallParams {
     tool: BaseTool;
     args: Record<string, unknown>;
-    functionResponseEvent: Event;
+    functionResponseEvent?: Event;
+    /** The exception raised while executing the tool, if any. */
+    error?: unknown;
+    /** An error type reported by a tool response instead of a thrown error. */
+    errorType?: string;
+    /** The tool execution span. Defaults to the active span when omitted. */
+    span?: Span;
+    invocationContext: InvocationContext;
 }
+/**
+ * Resolves a stable error classification suitable for the OpenTelemetry
+ * `error.type` attribute without using the potentially sensitive error message.
+ *
+ * @param error The thrown value.
+ * @returns The explicit ADK error type, GenAI API status, or error class name.
+ */
+export declare function resolveErrorType(error: unknown): string;
 /**
  * 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(params: TraceToolCallParams): void;
 export interface TraceMergedToolCallsParams {
     responseEventId: string;
     functionResponseEvent: Event;
+    invocationContext: InvocationContext;
 }
 /**
  * Traces merged tool call events.
@@ -82,7 +98,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,115 @@
+/**
+ * @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, ToolPredicate } from '../base_toolset.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`
+     * 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;
+    /**
+     * Filter selecting which tools from the spec are exposed by `getTools`.
+     * Accepts a list of tool names or a {@link ToolPredicate} function.
+     */
+    toolFilter?: ToolPredicate | string[];
+}
+/**
+ * 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
+ * `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`, and every later call reports the same
+ * failure.
+ *
+ * With `lazyLoadSpec`, the spec is fetched on the first call to `getTools`.
+ * 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;
+    private readonly apihubResourceName;
+    private readonly lazyLoadSpec;
+    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[]>;
+    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,109 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ReadonlyContext } from '../../agents/readonly_context.js';
+import { AuthCredential } from '../../auth/auth_credential.js';
+import { AuthScheme } from '../../auth/auth_schemes.js';
+import { BaseTool } from '../base_tool.js';
+import { BaseToolset, ToolPredicate } from '../base_toolset.js';
+import { IntegrationConnectorTool, type IntegrationConnectorToolOptions } from './integration_connector_tool.js';
+export { IntegrationConnectorTool, type IntegrationConnectorToolOptions };
+/** 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 `triggers` or alone for all triggers. */
+    integration?: string;
+    /**
+     * The API trigger IDs of the integration, such as
+     * `['api_trigger/my_trigger']`.
+     */
+    triggers?: 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 `''`. */
+    toolNamePrefix?: 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;
+    /**
+     * Authentication scheme for dynamic end-user credentials on connection tools,
+     * when `authOverrideEnabled` is enabled on the connection.
+     */
+    authScheme?: AuthScheme;
+    /**
+     * Authentication credential for dynamic end-user credentials on connection
+     * tools, when `authOverrideEnabled` is enabled on the connection.
+     */
+    authCredential?: AuthCredential;
+    /**
+     * Filter used to select which generated tools are exposed by `getTools`.
+     */
+    toolFilter?: ToolPredicate | 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',
+ *   triggers: ['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?;
+    private openApiToolsets;
+    /**
+     * @throws Error Unless the options name either an integration, 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(context?: ReadonlyContext): 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>;