@google/adk 2.2.1 → 2.4.0

package/dist/esm/tools/application_integration_tool/clients/integration_client.js

@@ -0,0 +1,219 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { experimental } from "../../../utils/experimental.js";
+import { isJsonObject } from "../../../utils/json_utils.js";
+import {
+  CloudPlatformTokenSource,
+  sendCloudRequest,
+  unexpectedError
+} from "./cloud_request.js";
+import {
+  actionRequest,
+  actionResponse,
+  ConnectionsClient,
+  CONNECTOR_BASE_SPEC,
+  connectorPayload,
+  createOperation,
+  createOperationRequest,
+  deleteOperation,
+  deleteOperationRequest,
+  executeCustomQueryRequest,
+  getActionOperation,
+  getOperation,
+  getOperationRequest,
+  listOperation,
+  listOperationRequest,
+  updateOperation,
+  updateOperationRequest
+} from "./connections_client.js";
+const EXECUTE_CONNECTION_INTEGRATION = "ExecuteConnection";
+const EXECUTE_CUSTOM_QUERY_ACTION = "ExecuteCustomQuery";
+let IntegrationClient = class {
+  constructor(options) {
+    var _a, _b;
+    this.project = options.project;
+    this.location = options.location;
+    this.integration = options.integration;
+    this.triggers = options.triggers;
+    this.connection = options.connection;
+    this.entityOperations = (_a = options.entityOperations) != null ? _a : {};
+    this.actions = (_b = options.actions) != null ? _b : [];
+    this.serviceAccountJson = options.serviceAccountJson;
+    this.tokenSource = new CloudPlatformTokenSource(options.serviceAccountJson);
+  }
+  /**
+   * Fetches the OpenAPI spec Application Integration generates for the API
+   * trigger of the integration.
+   *
+   * @throws Error For a rejected request, a missing credential, or a response
+   *   that carries no parseable spec.
+   */
+  async getOpenApiSpecForIntegration() {
+    var _a;
+    const url = `https://${this.location}-integrations.googleapis.com/v1/projects/${this.project}/locations/${this.location}:generateOpenApiSpec`;
+    const triggerId = (_a = this.triggers) != null ? _a : null;
+    const invalidRequestMessage = `Invalid request. Please check the provided values of project(${this.project}), location(${this.location}), integration(${this.integration}).`;
+    const body = await sendCloudRequest({
+      url,
+      method: "POST",
+      body: {
+        apiTriggerResources: [
+          {
+            integrationResource: this.integration,
+            triggerId
+          }
+        ],
+        fileFormat: "JSON"
+      },
+      tokenSource: this.tokenSource,
+      invalidRequestMessage
+    });
+    try {
+      const spec = isJsonObject(body) ? body["openApiSpec"] : void 0;
+      if (typeof spec !== "string") {
+        throw new Error("The response carries no openApiSpec string.");
+      }
+      const parsed = JSON.parse(spec);
+      if (!isJsonObject(parsed)) {
+        throw new Error("The openApiSpec is not a JSON object.");
+      }
+      return parsed;
+    } catch (e) {
+      throw unexpectedError(e);
+    }
+  }
+  /**
+   * Builds an OpenAPI spec for the entity operations and actions of the
+   * connection.
+   *
+   * Every operation becomes a POST to the `ExecuteConnection` integration,
+   * with a path fragment that keeps the paths distinct.
+   *
+   * @param toolName Prefix of every generated `operationId`.
+   * @param toolInstructions Text appended to every operation description.
+   * @throws Error When neither entity operations nor actions are configured,
+   *   or an operation is not one of create, update, delete, list or get.
+   */
+  async getOpenApiSpecForConnection(toolName = "", toolInstructions = "") {
+    var _a;
+    if (Object.keys(this.entityOperations).length === 0 && this.actions.length === 0) {
+      throw new Error(
+        "No entity operations or actions provided. Please provide at least one of them."
+      );
+    }
+    const connectionsClient = new ConnectionsClient({
+      project: this.project,
+      location: this.location,
+      connection: (_a = this.connection) != null ? _a : "",
+      serviceAccountJson: this.serviceAccountJson
+    });
+    const connectorSpec = structuredClone(CONNECTOR_BASE_SPEC);
+    const schemas = connectorSpec.components.schemas;
+    const pathPrefix = `/v2/projects/${this.project}/locations/${this.location}/integrations/${EXECUTE_CONNECTION_INTEGRATION}:execute?triggerId=api_trigger/${EXECUTE_CONNECTION_INTEGRATION}`;
+    for (const [entity, requestedOperations] of Object.entries(
+      this.entityOperations
+    )) {
+      const { schema, operations: supportedOperations } = await connectionsClient.getEntitySchemaAndOperations(entity);
+      const operations = requestedOperations.length > 0 ? requestedOperations : supportedOperations;
+      const schemaAsString = JSON.stringify(schema);
+      schemas[`connectorInputPayload_${entity}`] = connectorPayload(schema);
+      for (const operation of operations) {
+        const operationLower = operation.toLowerCase();
+        const path = `${pathPrefix}#${operationLower}_${entity}`;
+        switch (operationLower) {
+          case "create":
+            connectorSpec.paths[path] = createOperation({
+              entity,
+              toolName,
+              toolInstructions
+            });
+            schemas[`create_${entity}_Request`] = createOperationRequest(entity);
+            break;
+          case "update":
+            connectorSpec.paths[path] = updateOperation({
+              entity,
+              toolName,
+              toolInstructions
+            });
+            schemas[`update_${entity}_Request`] = updateOperationRequest(entity);
+            break;
+          case "delete":
+            connectorSpec.paths[path] = deleteOperation({
+              entity,
+              toolName,
+              toolInstructions
+            });
+            schemas[`delete_${entity}_Request`] = deleteOperationRequest();
+            break;
+          case "list":
+            connectorSpec.paths[path] = listOperation({
+              entity,
+              schemaAsString,
+              toolName,
+              toolInstructions
+            });
+            schemas[`list_${entity}_Request`] = listOperationRequest();
+            break;
+          case "get":
+            connectorSpec.paths[path] = getOperation({
+              entity,
+              schemaAsString,
+              toolName,
+              toolInstructions
+            });
+            schemas[`get_${entity}_Request`] = getOperationRequest();
+            break;
+          default:
+            throw new Error(
+              `Invalid operation: ${operation} for entity: ${entity}`
+            );
+        }
+      }
+    }
+    for (const action of this.actions) {
+      const { inputSchema, outputSchema, displayName } = await connectionsClient.getActionSchema(action);
+      const actionDisplayName = displayName.replace(/ /g, "");
+      let operation = "EXECUTE_ACTION";
+      if (action === EXECUTE_CUSTOM_QUERY_ACTION) {
+        schemas[`${actionDisplayName}_Request`] = executeCustomQueryRequest();
+        operation = "EXECUTE_QUERY";
+      } else {
+        schemas[`${actionDisplayName}_Request`] = actionRequest(actionDisplayName);
+        schemas[`connectorInputPayload_${actionDisplayName}`] = connectorPayload(inputSchema);
+      }
+      schemas[`connectorOutputPayload_${actionDisplayName}`] = connectorPayload(outputSchema);
+      schemas[`${actionDisplayName}_Response`] = actionResponse(actionDisplayName);
+      connectorSpec.paths[`${pathPrefix}#${action}`] = getActionOperation({
+        action,
+        operation,
+        actionDisplayName,
+        toolName,
+        toolInstructions
+      });
+    }
+    return connectorSpec;
+  }
+};
+__name(IntegrationClient, "IntegrationClient");
+IntegrationClient = __decorateClass([
+  experimental
+], IntegrationClient);
+export {
+  IntegrationClient
+};

package/dist/esm/tools/application_integration_tool/integration_connector_tool.js

@@ -0,0 +1,158 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { experimental } from "../../utils/experimental.js";
+import { logger } from "../../utils/logger.js";
+import { BaseTool } from "../base_tool.js";
+import { ToolAuthHandler } from "../openapi_tool/openapi_spec_parser/tool_auth_handler.js";
+const DYNAMIC_AUTH_EXCLUDE_FIELDS = Object.freeze([
+  "dynamic_auth_config",
+  "dynamicAuthConfig"
+]);
+let IntegrationConnectorTool = class extends BaseTool {
+  constructor(options) {
+    var _a, _b, _c;
+    super(options);
+    this.connectionName = options.connectionName;
+    this.connectionHost = options.connectionHost;
+    this.connectionServiceName = options.connectionServiceName;
+    this.entity = (_a = options.entity) != null ? _a : "";
+    this.operation = (_b = options.operation) != null ? _b : "";
+    this.action = (_c = options.action) != null ? _c : "";
+    this.restApiTool = options.restApiTool;
+    this.authScheme = options.authScheme;
+    this.authCredential = options.authCredential;
+  }
+  _getDeclaration() {
+    const declaration = this.restApiTool._getDeclaration();
+    const rawParameters = declaration == null ? void 0 : declaration.parameters;
+    let parameters;
+    if (rawParameters) {
+      parameters = { ...rawParameters };
+      if (rawParameters.properties) {
+        const properties = { ...rawParameters.properties };
+        for (const field of [
+          ...IntegrationConnectorTool.EXCLUDE_FIELDS,
+          ...DYNAMIC_AUTH_EXCLUDE_FIELDS
+        ]) {
+          delete properties[field];
+        }
+        parameters.properties = properties;
+      }
+      if (rawParameters.required) {
+        parameters.required = rawParameters.required.filter(
+          (field) => !IntegrationConnectorTool.EXCLUDE_FIELDS.includes(field) && !DYNAMIC_AUTH_EXCLUDE_FIELDS.includes(field) && !IntegrationConnectorTool.OPTIONAL_FIELDS.includes(field)
+        );
+      }
+    }
+    return {
+      name: this.name,
+      description: this.description,
+      parameters
+    };
+  }
+  async runAsync(request) {
+    const toolAuthHandler = ToolAuthHandler.fromToolContext(
+      request.toolContext,
+      this.authScheme,
+      this.authCredential
+    );
+    const authResult = await toolAuthHandler.prepareAuthCredentials();
+    if (authResult.state === "pending") {
+      return {
+        pending: true,
+        message: "Needs your authorization to access your data."
+      };
+    }
+    const updatedArgs = {
+      ...request.args,
+      connection_name: this.connectionName,
+      connectionName: this.connectionName,
+      service_name: this.connectionServiceName,
+      serviceName: this.connectionServiceName,
+      host: this.connectionHost
+    };
+    if (this.entity) {
+      updatedArgs["entity"] = this.entity;
+    }
+    if (this.operation) {
+      updatedArgs["operation"] = this.operation;
+    }
+    if (this.action) {
+      updatedArgs["action"] = this.action;
+    }
+    if (authResult.authCredential) {
+      const token = prepareDynamicEuc(authResult.authCredential);
+      const dynamicAuthPayload = {
+        "oauth2_auth_code_flow.access_token": token != null ? token : {}
+      };
+      updatedArgs["dynamic_auth_config"] = dynamicAuthPayload;
+      updatedArgs["dynamicAuthConfig"] = dynamicAuthPayload;
+    }
+    logger.debug(`Running tool: ${this.name}`);
+    return this.restApiTool.runAsync({
+      args: updatedArgs,
+      toolContext: request.toolContext
+    });
+  }
+};
+__name(IntegrationConnectorTool, "IntegrationConnectorTool");
+/**
+ * Request fields that {@link IntegrationConnectorTool} injects at runtime and
+ * excludes from the function declaration shown to the model.
+ */
+IntegrationConnectorTool.EXCLUDE_FIELDS = Object.freeze([
+  "connection_name",
+  "connectionName",
+  "service_name",
+  "serviceName",
+  "host",
+  "entity",
+  "operation",
+  "action"
+]);
+/**
+ * Request fields that {@link IntegrationConnectorTool} removes from the
+ * `required` list in the function declaration shown to the model.
+ */
+IntegrationConnectorTool.OPTIONAL_FIELDS = Object.freeze([
+  "page_size",
+  "pageSize",
+  "page_token",
+  "pageToken",
+  "filter",
+  "filter_clause",
+  "filterClause"
+]);
+__decorateClass([
+  experimental
+], IntegrationConnectorTool.prototype, "_getDeclaration", 1);
+__decorateClass([
+  experimental
+], IntegrationConnectorTool.prototype, "runAsync", 1);
+IntegrationConnectorTool = __decorateClass([
+  experimental
+], IntegrationConnectorTool);
+function prepareDynamicEuc(authCredential) {
+  var _a, _b;
+  return ((_b = (_a = authCredential.http) == null ? void 0 : _a.credentials) == null ? void 0 : _b.token) || void 0;
+}
+__name(prepareDynamicEuc, "prepareDynamicEuc");
+export {
+  IntegrationConnectorTool
+};

package/dist/esm/tools/example_tool.js

@@ -7,12 +7,21 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { buildExampleSi } from "../examples/example_util.js";
+import {
+  isBaseExampleProvider
+} from "../examples/base_example_provider.js";
+import { buildExampleSi, validateExamples } from "../examples/example_util.js";
 import { appendInstructions } from "../models/llm_request.js";
 import {
   BaseTool
 } from "./base_tool.js";
 const _ExampleTool = class _ExampleTool extends BaseTool {
+  /**
+   * @param examples - A list of {@link Example}s, or a
+   *   {@link BaseExampleProvider} that returns them for a query.
+   * @throws {InputValidationError} When `examples` is neither a
+   *   {@link BaseExampleProvider} nor a list of well-formed examples.
+   */
   constructor(examples) {
     super({
       // Name and description are not used because this tool only changes
@@ -20,6 +29,9 @@ const _ExampleTool = class _ExampleTool extends BaseTool {
       name: "example_tool",
       description: "example tool"
     });
+    if (!isBaseExampleProvider(examples)) {
+      validateExamples(examples);
+    }
     this.examples = examples;
   }
   async runAsync(_request) {