@google/adk 2.2.1 → 2.4.0

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

@@ -0,0 +1,223 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+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;
+};
+var integration_client_exports = {};
+__export(integration_client_exports, {
+  IntegrationClient: () => IntegrationClient
+});
+module.exports = __toCommonJS(integration_client_exports);
+var import_experimental = require("../../../utils/experimental.js");
+var import_json_utils = require("../../../utils/json_utils.js");
+var import_cloud_request = require("./cloud_request.js");
+var import_connections_client = require("./connections_client.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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 import_cloud_request.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 (0, import_cloud_request.sendCloudRequest)({
+      url,
+      method: "POST",
+      body: {
+        apiTriggerResources: [
+          {
+            integrationResource: this.integration,
+            triggerId
+          }
+        ],
+        fileFormat: "JSON"
+      },
+      tokenSource: this.tokenSource,
+      invalidRequestMessage
+    });
+    try {
+      const spec = (0, import_json_utils.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 (!(0, import_json_utils.isJsonObject)(parsed)) {
+        throw new Error("The openApiSpec is not a JSON object.");
+      }
+      return parsed;
+    } catch (e) {
+      throw (0, import_cloud_request.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 import_connections_client.ConnectionsClient({
+      project: this.project,
+      location: this.location,
+      connection: (_a = this.connection) != null ? _a : "",
+      serviceAccountJson: this.serviceAccountJson
+    });
+    const connectorSpec = structuredClone(import_connections_client.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}`] = (0, import_connections_client.connectorPayload)(schema);
+      for (const operation of operations) {
+        const operationLower = operation.toLowerCase();
+        const path = `${pathPrefix}#${operationLower}_${entity}`;
+        switch (operationLower) {
+          case "create":
+            connectorSpec.paths[path] = (0, import_connections_client.createOperation)({
+              entity,
+              toolName,
+              toolInstructions
+            });
+            schemas[`create_${entity}_Request`] = (0, import_connections_client.createOperationRequest)(entity);
+            break;
+          case "update":
+            connectorSpec.paths[path] = (0, import_connections_client.updateOperation)({
+              entity,
+              toolName,
+              toolInstructions
+            });
+            schemas[`update_${entity}_Request`] = (0, import_connections_client.updateOperationRequest)(entity);
+            break;
+          case "delete":
+            connectorSpec.paths[path] = (0, import_connections_client.deleteOperation)({
+              entity,
+              toolName,
+              toolInstructions
+            });
+            schemas[`delete_${entity}_Request`] = (0, import_connections_client.deleteOperationRequest)();
+            break;
+          case "list":
+            connectorSpec.paths[path] = (0, import_connections_client.listOperation)({
+              entity,
+              schemaAsString,
+              toolName,
+              toolInstructions
+            });
+            schemas[`list_${entity}_Request`] = (0, import_connections_client.listOperationRequest)();
+            break;
+          case "get":
+            connectorSpec.paths[path] = (0, import_connections_client.getOperation)({
+              entity,
+              schemaAsString,
+              toolName,
+              toolInstructions
+            });
+            schemas[`get_${entity}_Request`] = (0, import_connections_client.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`] = (0, import_connections_client.executeCustomQueryRequest)();
+        operation = "EXECUTE_QUERY";
+      } else {
+        schemas[`${actionDisplayName}_Request`] = (0, import_connections_client.actionRequest)(actionDisplayName);
+        schemas[`connectorInputPayload_${actionDisplayName}`] = (0, import_connections_client.connectorPayload)(inputSchema);
+      }
+      schemas[`connectorOutputPayload_${actionDisplayName}`] = (0, import_connections_client.connectorPayload)(outputSchema);
+      schemas[`${actionDisplayName}_Response`] = (0, import_connections_client.actionResponse)(actionDisplayName);
+      connectorSpec.paths[`${pathPrefix}#${action}`] = (0, import_connections_client.getActionOperation)({
+        action,
+        operation,
+        actionDisplayName,
+        toolName,
+        toolInstructions
+      });
+    }
+    return connectorSpec;
+  }
+};
+__name(IntegrationClient, "IntegrationClient");
+IntegrationClient = __decorateClass([
+  import_experimental.experimental
+], IntegrationClient);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IntegrationClient
+});

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

@@ -0,0 +1,184 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+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;
+};
+var integration_connector_tool_exports = {};
+__export(integration_connector_tool_exports, {
+  IntegrationConnectorTool: () => IntegrationConnectorTool
+});
+module.exports = __toCommonJS(integration_connector_tool_exports);
+var import_experimental = require("../../utils/experimental.js");
+var import_logger = require("../../utils/logger.js");
+var import_base_tool = require("../base_tool.js");
+var import_tool_auth_handler = require("../openapi_tool/openapi_spec_parser/tool_auth_handler.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const DYNAMIC_AUTH_EXCLUDE_FIELDS = Object.freeze([
+  "dynamic_auth_config",
+  "dynamicAuthConfig"
+]);
+let IntegrationConnectorTool = class extends import_base_tool.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 = import_tool_auth_handler.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;
+    }
+    import_logger.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([
+  import_experimental.experimental
+], IntegrationConnectorTool.prototype, "_getDeclaration", 1);
+__decorateClass([
+  import_experimental.experimental
+], IntegrationConnectorTool.prototype, "runAsync", 1);
+IntegrationConnectorTool = __decorateClass([
+  import_experimental.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");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IntegrationConnectorTool
+});

package/dist/cjs/tools/example_tool.js

@@ -28,6 +28,7 @@ __export(example_tool_exports, {
   ExampleTool: () => ExampleTool
 });
 module.exports = __toCommonJS(example_tool_exports);
+var import_base_example_provider = require("../examples/base_example_provider.js");
 var import_example_util = require("../examples/example_util.js");
 var import_llm_request = require("../models/llm_request.js");
 var import_base_tool = require("./base_tool.js");
@@ -37,6 +38,12 @@ var import_base_tool = require("./base_tool.js");
  * SPDX-License-Identifier: Apache-2.0
  */
 const _ExampleTool = class _ExampleTool extends import_base_tool.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
@@ -44,6 +51,9 @@ const _ExampleTool = class _ExampleTool extends import_base_tool.BaseTool {
       name: "example_tool",
       description: "example tool"
     });
+    if (!(0, import_base_example_provider.isBaseExampleProvider)(examples)) {
+      (0, import_example_util.validateExamples)(examples);
+    }
     this.examples = examples;
   }
   async runAsync(_request) {