feat(toolbox-adk): add protocol

packages/toolbox-adk/integration.cloudbuild.yaml

@@ -0,0 +1,49 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+steps:
+  - id: Install dependencies
+    name: 'node:${_VERSION}'
+    entrypoint: /bin/bash
+    args:
+      - -c
+      - corepack enable && pnpm install --frozen-lockfile
+
+  - id: Run unit tests
+    name: 'node:${_VERSION}'
+    entrypoint: /bin/bash
+    waitFor: ['Install dependencies']
+    args:
+      - '-c'
+      - corepack enable && pnpm --filter @toolbox-sdk/adk run test:unit
+
+  # - id: Run integration tests
+  #   name: 'node:${_VERSION}'
+  #   entrypoint: /bin/bash
+  #   waitFor: ['Install dependencies']
+  #   env:
+  #     - TOOLBOX_URL=$_TOOLBOX_URL
+  #     - TOOLBOX_VERSION=$_TOOLBOX_VERSION
+  #     - GOOGLE_CLOUD_PROJECT=$PROJECT_ID
+  #     - TOOLBOX_MANIFEST_VERSION=$_TOOLBOX_MANIFEST_VERSION
+  #   args:
+  #     - '-c'
+  #     - corepack enable && pnpm --filter @toolbox-sdk/adk run test:e2e
+
+options:
+  logging: CLOUD_LOGGING_ONLY
+substitutions:
+  _VERSION: '22.16.0'
+  _TOOLBOX_VERSION: '0.17.0'
+  _TOOLBOX_MANIFEST_VERSION: '34'

packages/toolbox-adk/package.json

@@ -45,6 +45,8 @@
         "coverage": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --config jest.config.json --coverage"
     },
     "dependencies": {
-        "@toolbox-sdk/core": "workspace:*"
+        "@google/genai": "^1.14.0",
+        "@toolbox-sdk/core": "workspace:*",
+        "zod": "^3.24.4"
     }
 }

packages/toolbox-adk/src/toolbox_adk/protocol.ts

@@ -0,0 +1,102 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type {FunctionDeclaration, Schema} from '@google/genai';
+import {Type} from '@google/genai';
+import {z, ZodObject, ZodRawShape, ZodTypeAny} from 'zod';
+
+/**
+ * Safely determines the JSON Schema type enum from a Zod type object.
+ *
+ * @param zodType The Zod type instance to inspect.
+ * @returns A value from the `Type` enum.
+ */
+function getJsonSchemaTypeFromZod(zodType: ZodTypeAny): Type {
+  // Handle optional and nullable types by recursively unwrapping them
+  if (zodType instanceof z.ZodOptional || zodType instanceof z.ZodNullable) {
+    return getJsonSchemaTypeFromZod(zodType.unwrap());
+  }
+
+  // Handle specific base types
+  if (zodType instanceof z.ZodNull) {
+    return Type.NULL;
+  }
+
+  if (zodType instanceof z.ZodString || zodType instanceof z.ZodEnum) {
+    return Type.STRING;
+  }
+
+  if (zodType instanceof z.ZodNumber) {
+    const isInteger = zodType._def.checks.some(check => check.kind === 'int');
+    return isInteger ? Type.INTEGER : Type.NUMBER;
+  }
+
+  if (zodType instanceof z.ZodBoolean) {
+    return Type.BOOLEAN;
+  }
+  if (zodType instanceof z.ZodArray) {
+    return Type.ARRAY;
+  }
+  if (zodType instanceof z.ZodObject) {
+    return Type.OBJECT;
+  }
+  // Fallback for unhandled types
+  return Type.TYPE_UNSPECIFIED;
+}
+
+/**
+ * Converts a ZodObject schema into a FunctionDeclaration for the Google ADK.
+ *
+ * @param name The name of the function/tool.
+ * @param description The description of the function/tool.
+ * @param zodSchema The Zod schema for the tool's parameters.
+ * @returns A FunctionDeclaration object for the Google Genai API.
+ */
+export function ConvertZodToFunctionDeclaration(
+  name: string,
+  description: string,
+  zodSchema: ZodObject<ZodRawShape>,
+): FunctionDeclaration {
+  const properties: Record<string, Schema> = {};
+  const required: string[] = [];
+
+  if (!zodSchema?.shape) {
+    return {
+      name,
+      description,
+      parameters: {type: Type.OBJECT, properties, required},
+    };
+  }
+
+  for (const [key, zodType] of Object.entries(zodSchema.shape)) {
+    properties[key] = {
+      type: getJsonSchemaTypeFromZod(zodType),
+      description: zodType.description || '',
+    };
+
+    if (!zodType.isOptional()) {
+      required.push(key);
+    }
+  }
+
+  return {
+    name,
+    description,
+    parameters: {
+      type: Type.OBJECT,
+      properties,
+      required,
+    },
+  };
+}