@google/adk 0.1.0

package/dist/esm/utils/env_aware_utils.js

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function isBrowser() {
+  return typeof window !== "undefined";
+}
+const UUID_MASK = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx";
+function randomUUID() {
+  let uuid = "";
+  for (let i = 0; i < UUID_MASK.length; i++) {
+    const randomValue = Math.random() * 16 | 0;
+    if (UUID_MASK[i] === "x") {
+      uuid += randomValue.toString(16);
+    } else if (UUID_MASK[i] === "y") {
+      uuid += (randomValue & 3 | 8).toString(16);
+    } else {
+      uuid += UUID_MASK[i];
+    }
+  }
+  return uuid;
+}
+function base64Encode(data) {
+  if (isBrowser()) {
+    return window.btoa(data);
+  }
+  return Buffer.from(data).toString("base64");
+}
+function base64Decode(data) {
+  if (isBrowser()) {
+    return window.atob(data);
+  }
+  return Buffer.from(data, "base64").toString();
+}
+function isBase64Encoded(data) {
+  try {
+    return base64Encode(base64Decode(data)) === data;
+  } catch (e) {
+    return false;
+  }
+}
+export {
+  base64Decode,
+  base64Encode,
+  isBase64Encoded,
+  isBrowser,
+  randomUUID
+};

package/dist/esm/utils/gemini_schema_util.js

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Type } from "@google/genai";
+import { z } from "zod";
+const MCPToolSchema = z.object({
+  type: z.literal("object"),
+  properties: z.record(z.unknown()).optional(),
+  required: z.string().array().optional()
+});
+function toGeminiType(mcpType) {
+  switch (mcpType.toLowerCase()) {
+    case "text":
+    case "string":
+      return Type.STRING;
+    case "number":
+      return Type.NUMBER;
+    case "boolean":
+      return Type.BOOLEAN;
+    case "integer":
+      return Type.INTEGER;
+    case "array":
+      return Type.ARRAY;
+    case "object":
+      return Type.OBJECT;
+    default:
+      return Type.TYPE_UNSPECIFIED;
+  }
+}
+function toGeminiSchema(mcpSchema) {
+  if (!mcpSchema) {
+    return void 0;
+  }
+  function recursiveConvert(mcp) {
+    const geminiType = toGeminiType(mcp.type);
+    const geminiSchema = { type: geminiType, description: mcp.description };
+    if (geminiType === Type.OBJECT) {
+      geminiSchema.properties = {};
+      if (mcp.properties) {
+        for (const name in mcp.properties) {
+          geminiSchema.properties[name] = recursiveConvert(mcp.properties[name]);
+        }
+      }
+      geminiSchema.required = mcp.required;
+    } else if (geminiType === Type.ARRAY) {
+      if (mcp.items) {
+        geminiSchema.items = recursiveConvert(mcp.items);
+      }
+    }
+    return geminiSchema;
+  }
+  return recursiveConvert(mcpSchema);
+}
+export {
+  toGeminiSchema
+};

package/dist/esm/utils/logger.js

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["DEBUG"] = 0] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 1] = "INFO";
+  LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
+  LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
+  return LogLevel2;
+})(LogLevel || {});
+let logLevel = 1 /* INFO */;
+function setLogLevel(level) {
+  logLevel = level;
+}
+class SimpleLogger {
+  log(level, ...args) {
+    if (level < logLevel) {
+      return;
+    }
+    switch (level) {
+      case 0 /* DEBUG */:
+        this.debug(...args);
+        break;
+      case 1 /* INFO */:
+        this.info(...args);
+        break;
+      case 2 /* WARN */:
+        this.warn(...args);
+        break;
+      case 3 /* ERROR */:
+        this.error(...args);
+        break;
+      default:
+        throw new Error(`Unsupported log level: ${level}`);
+    }
+  }
+  debug(...args) {
+    if (logLevel > 0 /* DEBUG */) {
+      return;
+    }
+    console.debug(getColoredPrefix(0 /* DEBUG */), ...args);
+  }
+  info(...args) {
+    if (logLevel > 1 /* INFO */) {
+      return;
+    }
+    console.info(getColoredPrefix(1 /* INFO */), ...args);
+  }
+  warn(...args) {
+    if (logLevel > 2 /* WARN */) {
+      return;
+    }
+    console.warn(getColoredPrefix(2 /* WARN */), ...args);
+  }
+  error(...args) {
+    if (logLevel > 3 /* ERROR */) {
+      return;
+    }
+    console.error(getColoredPrefix(3 /* ERROR */), ...args);
+  }
+}
+const LOG_LEVEL_STR = {
+  [0 /* DEBUG */]: "DEBUG",
+  [1 /* INFO */]: "INFO",
+  [2 /* WARN */]: "WARN",
+  [3 /* ERROR */]: "ERROR"
+};
+const CONSOLE_COLOR_MAP = {
+  [0 /* DEBUG */]: "\x1B[34m",
+  // Blue
+  [1 /* INFO */]: "\x1B[32m",
+  // Green
+  [2 /* WARN */]: "\x1B[33m",
+  // Yellow
+  [3 /* ERROR */]: "\x1B[31m"
+  // Red
+};
+const RESET_COLOR = "\x1B[0m";
+function getColoredPrefix(level) {
+  return `${CONSOLE_COLOR_MAP[level]}[ADK ${LOG_LEVEL_STR[level]}]:${RESET_COLOR}`;
+}
+const logger = new SimpleLogger();
+export {
+  LogLevel,
+  logger,
+  setLogLevel
+};

package/dist/esm/utils/model_name.js

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const MODEL_NAME_PATTERN = "^projects/[^/]+/locations/[^/]+/publishers/[^/]+/models/(.+)$";
+function extractModelName(modelString) {
+  const match = modelString.match(MODEL_NAME_PATTERN);
+  if (match) {
+    return match[1];
+  }
+  return modelString;
+}
+function isGeminiModel(modelString) {
+  const modelName = extractModelName(modelString);
+  return modelName.startsWith("gemini-");
+}
+function isGemini1Model(modelString) {
+  const modelName = extractModelName(modelString);
+  return modelName.startsWith("gemini-1");
+}
+function isGemini2Model(modelString) {
+  const modelName = extractModelName(modelString);
+  return modelName.startsWith("gemini-2");
+}
+export {
+  extractModelName,
+  isGemini1Model,
+  isGemini2Model,
+  isGeminiModel
+};

package/dist/esm/utils/simple_zod_to_json.js

@@ -0,0 +1,160 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Type } from "@google/genai";
+import { z } from "zod";
+function isZodObject(obj) {
+  var _a;
+  return obj !== null && typeof obj === "object" && ((_a = obj._def) == null ? void 0 : _a.typeName) === "ZodObject";
+}
+function parseZodType(zodType) {
+  const def = zodType._def;
+  if (!def) {
+    return {};
+  }
+  const description = def.description;
+  const result = {};
+  if (description) result.description = description;
+  const returnResult = (result2) => {
+    if (result2.description === void 0) {
+      delete result2.description;
+    }
+    return result2;
+  };
+  switch (def.typeName) {
+    case z.ZodFirstPartyTypeKind.ZodString:
+      result.type = Type.STRING;
+      for (const check of def.checks || []) {
+        if (check.kind === "min")
+          result.minLength = check.value.toString();
+        else if (check.kind === "max")
+          result.maxLength = check.value.toString();
+        else if (check.kind === "email")
+          result.format = "email";
+        else if (check.kind === "uuid")
+          result.format = "uuid";
+        else if (check.kind === "url")
+          result.format = "uri";
+        else if (check.kind === "regex")
+          result.pattern = check.regex.source;
+      }
+      return returnResult(result);
+    case z.ZodFirstPartyTypeKind.ZodNumber:
+      result.type = Type.NUMBER;
+      for (const check of def.checks || []) {
+        if (check.kind === "min")
+          result.minimum = check.value;
+        else if (check.kind === "max")
+          result.maximum = check.value;
+        else if (check.kind === "int")
+          result.type = Type.INTEGER;
+      }
+      return returnResult(result);
+    case z.ZodFirstPartyTypeKind.ZodBoolean:
+      result.type = Type.BOOLEAN;
+      return returnResult(result);
+    case z.ZodFirstPartyTypeKind.ZodArray:
+      result.type = Type.ARRAY;
+      result.items = parseZodType(def.type);
+      if (def.minLength) result.minItems = def.minLength.value.toString();
+      if (def.maxLength) result.maxItems = def.maxLength.value.toString();
+      return returnResult(result);
+    case z.ZodFirstPartyTypeKind.ZodObject: {
+      const nestedSchema = zodObjectToSchema(zodType);
+      return nestedSchema;
+    }
+    case z.ZodFirstPartyTypeKind.ZodLiteral:
+      const literalType = typeof def.value;
+      result.enum = [def.value.toString()];
+      if (literalType === "string") {
+        result.type = Type.STRING;
+      } else if (literalType === "number") {
+        result.type = Type.NUMBER;
+      } else if (literalType === "boolean") {
+        result.type = Type.BOOLEAN;
+      } else if (def.value === null) {
+        result.type = Type.NULL;
+      } else {
+        throw new Error(`Unsupported ZodLiteral value type: ${literalType}`);
+      }
+      return returnResult(result);
+    case z.ZodFirstPartyTypeKind.ZodEnum:
+      result.type = Type.STRING;
+      result.enum = def.values;
+      return returnResult(result);
+    case z.ZodFirstPartyTypeKind.ZodNativeEnum:
+      result.type = Type.STRING;
+      result.enum = Object.values(def.values);
+      return returnResult(result);
+    case z.ZodFirstPartyTypeKind.ZodUnion:
+      result.anyOf = def.options.map(parseZodType);
+      return returnResult(result);
+    case z.ZodFirstPartyTypeKind.ZodOptional:
+      return parseZodType(def.innerType);
+    case z.ZodFirstPartyTypeKind.ZodNullable:
+      const nullableInner = parseZodType(def.innerType);
+      return nullableInner ? returnResult({
+        anyOf: [nullableInner, { type: Type.NULL }],
+        ...description && { description }
+      }) : returnResult({ type: Type.NULL, ...description && { description } });
+    case z.ZodFirstPartyTypeKind.ZodDefault:
+      const defaultInner = parseZodType(def.innerType);
+      if (defaultInner) defaultInner.default = def.defaultValue();
+      return defaultInner;
+    case z.ZodFirstPartyTypeKind.ZodBranded:
+      return parseZodType(def.type);
+    case z.ZodFirstPartyTypeKind.ZodReadonly:
+      return parseZodType(def.innerType);
+    case z.ZodFirstPartyTypeKind.ZodNull:
+      result.type = Type.NULL;
+      return returnResult(result);
+    case z.ZodFirstPartyTypeKind.ZodAny:
+    case z.ZodFirstPartyTypeKind.ZodUnknown:
+      return returnResult({ ...description && { description } });
+    default:
+      throw new Error(`Unsupported Zod type: ${def.typeName}`);
+  }
+}
+function zodObjectToSchema(schema) {
+  if (schema._def.typeName !== z.ZodFirstPartyTypeKind.ZodObject) {
+    throw new Error("Expected a ZodObject");
+  }
+  const shape = schema.shape;
+  const properties = {};
+  const required = [];
+  for (const key in shape) {
+    const fieldSchema = shape[key];
+    const parsedField = parseZodType(fieldSchema);
+    if (parsedField) {
+      properties[key] = parsedField;
+    }
+    let currentSchema = fieldSchema;
+    let isOptional = false;
+    while (currentSchema._def.typeName === z.ZodFirstPartyTypeKind.ZodOptional || currentSchema._def.typeName === z.ZodFirstPartyTypeKind.ZodDefault) {
+      isOptional = true;
+      currentSchema = currentSchema._def.innerType;
+    }
+    if (!isOptional) {
+      required.push(key);
+    }
+  }
+  const catchall = schema._def.catchall;
+  let additionalProperties = false;
+  if (catchall && catchall._def.typeName !== z.ZodFirstPartyTypeKind.ZodNever) {
+    additionalProperties = parseZodType(catchall) || true;
+  } else {
+    additionalProperties = schema._def.unknownKeys === "passthrough";
+  }
+  return {
+    type: Type.OBJECT,
+    properties,
+    required: required.length > 0 ? required : [],
+    ...schema._def.description ? { description: schema._def.description } : {}
+  };
+}
+export {
+  isZodObject,
+  zodObjectToSchema
+};

package/dist/esm/utils/variant_utils.js

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var GoogleLLMVariant = /* @__PURE__ */ ((GoogleLLMVariant2) => {
+  GoogleLLMVariant2["VERTEX_AI"] = "VERTEX_AI";
+  GoogleLLMVariant2["GEMINI_API"] = "GEMINI_API";
+  return GoogleLLMVariant2;
+})(GoogleLLMVariant || {});
+function getGoogleLlmVariant() {
+  return getBooleanEnvVar("GOOGLE_GENAI_USE_VERTEXAI") ? "VERTEX_AI" /* VERTEX_AI */ : "GEMINI_API" /* GEMINI_API */;
+}
+function getBooleanEnvVar(envVar) {
+  if (!process.env) {
+    return false;
+  }
+  const envVarValue = (process.env[envVar] || "").toLowerCase();
+  return ["true", "1"].includes(envVar.toLowerCase());
+}
+export {
+  GoogleLLMVariant,
+  getGoogleLlmVariant
+};

package/dist/esm/version.js

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const version = "0.1.0";
+export {
+  version
+};

package/dist/types/agents/active_streaming_tool.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LiveRequestQueue } from './live_request_queue.js';
+/**
+ * The parameters for creating an ActiveStreamingTool.
+ */
+export interface ActiveStreamingToolParams {
+    task?: Promise<void>;
+    stream?: LiveRequestQueue;
+}
+/**
+ * Manages streaming tool related resources during invocation.
+ */
+export declare class ActiveStreamingTool {
+    /**
+     * The active task of this streaming tool.
+     * TODO: Replace 'Promise<void>' with a proper Task type if available in this
+     * env.
+     */
+    task?: Promise<void>;
+    /**
+     * The active (input) streams of this streaming tool.
+     */
+    stream?: LiveRequestQueue;
+    constructor(params?: ActiveStreamingToolParams);
+}

package/dist/types/agents/base_agent.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import { Event } from '../events/event.js';
+import { CallbackContext } from './callback_context.js';
+import { InvocationContext } from './invocation_context.js';
+type SingleAgentCallback = (context: CallbackContext) => Promise<Content | undefined> | (Content | undefined);
+type BeforeAgentCallback = SingleAgentCallback | SingleAgentCallback[];
+type AfterAgentCallback = SingleAgentCallback | SingleAgentCallback[];
+/**
+ * The config of a base agent.
+ */
+export interface BaseAgentConfig {
+    name: string;
+    description?: string;
+    parentAgent?: BaseAgent;
+    subAgents?: BaseAgent[];
+    beforeAgentCallback?: BeforeAgentCallback;
+    afterAgentCallback?: AfterAgentCallback;
+}
+/**
+ * Base class for all agents in Agent Development Kit.
+ */
+export declare abstract class BaseAgent {
+    /**
+     * The agent's name.
+     * Agent name must be a JS identifier and unique within the agent tree.
+     * Agent name cannot be "user", since it's reserved for end-user's input.
+     */
+    readonly name: string;
+    /**
+     * Description about the agent's capability.
+     *
+     * The model uses this to determine whether to delegate control to the agent.
+     * One-line description is enough and preferred.
+     */
+    readonly description?: string;
+    /**
+     * Root agent of this agent.
+     */
+    readonly rootAgent: BaseAgent;
+    /**
+     * The parent agent of this agent.
+     *
+     * Note that an agent can ONLY be added as sub-agent once.
+     *
+     * If you want to add one agent twice as sub-agent, consider to create two
+     * agent instances with identical config, but with different name and add them
+     * to the agent tree.
+     *
+     * The parent agent is the agent that created this agent.
+     */
+    parentAgent?: BaseAgent;
+    /**
+     * The sub-agents of this agent.
+     */
+    readonly subAgents: BaseAgent[];
+    /**
+     * Callback or list of callbacks to be invoked before the agent run.
+     *
+     * When a list of callbacks is provided, the callbacks will be called in the
+     * order they are listed until a callback does not return undefined.
+     *
+     * @param callbackContext: MUST be named 'callbackContext' (enforced).
+     *
+     * @return Content: The content to return to the user. When the content is
+     *     present, the agent run will be skipped and the provided content will be
+     *     returned to user.
+     */
+    readonly beforeAgentCallback: SingleAgentCallback[];
+    /**
+     * Callback or list of callbacks to be invoked after the agent run.
+     *
+     * When a list of callbacks is provided, the callbacks will be called in the
+     * order they are listed until a callback does not return undefined.
+     *
+     * @param callbackContext: MUST be named 'callbackContext' (enforced).
+     *
+     * @return Content: The content to return to the user. When the content is
+     *     present, the provided content will be used as agent response and
+     *     appended to event history as agent response.
+     */
+    readonly afterAgentCallback: SingleAgentCallback[];
+    constructor(config: BaseAgentConfig);
+    /**
+     * Entry method to run an agent via text-based conversation.
+     *
+     * @param parentContext The invocation context of the parent agent.
+     * @yields The events generated by the agent.
+     * @returns An AsyncGenerator that yields the events generated by the agent.
+     */
+    runAsync(parentContext: InvocationContext): AsyncGenerator<Event, void, void>;
+    /**
+     * Entry method to run an agent via video/audio-based conversation.
+     *
+     * @param parentContext The invocation context of the parent agent.
+     * @yields The events generated by the agent.
+     * @returns An AsyncGenerator that yields the events generated by the agent.
+     */
+    runLive(parentContext: InvocationContext): AsyncGenerator<Event, void, void>;
+    /**
+     * Core logic to run this agent via text-based conversation.
+     *
+     * @param context The invocation context of the agent.
+     * @yields The events generated by the agent.
+     * @returns An AsyncGenerator that yields the events generated by the agent.
+     */
+    protected abstract runAsyncImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+    /**
+     * Core logic to run this agent via video/audio-based conversation.
+     *
+     * @param context The invocation context of the agent.
+     * @yields The events generated by the agent.
+     * @returns An AsyncGenerator that yields the events generated by the agent.
+     */
+    protected abstract runLiveImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
+    /**
+     * Finds the agent with the given name in this agent and its descendants.
+     *
+     * @param name The name of the agent to find.
+     * @return The agent with the given name, or undefined if not found.
+     */
+    findAgent(name: string): BaseAgent | undefined;
+    /**
+     * Finds the agent with the given name in this agent's descendants.
+     *
+     * @param name The name of the agent to find.
+     * @return The agent with the given name, or undefined if not found.
+     */
+    findSubAgent(name: string): BaseAgent | undefined;
+    /**
+     * Creates an invocation context for this agent.
+     *
+     * @param parentContext The invocation context of the parent agent.
+     * @return The invocation context for this agent.
+     */
+    protected createInvocationContext(parentContext: InvocationContext): InvocationContext;
+    /**
+     * Runs the before agent callback if it exists.
+     *
+     * @param invocationContext The invocation context of the agent.
+     * @return The event to return to the user, or undefined if no event is
+     *     generated.
+     */
+    protected handleBeforeAgentCallback(invocationContext: InvocationContext): Promise<Event | undefined>;
+    /**
+     * Runs the after agent callback if it exists.
+     *
+     * @param invocationContext The invocation context of the agent.
+     * @return The event to return to the user, or undefined if no event is
+     *     generated.
+     */
+    protected handleAfterAgentCallback(invocationContext: InvocationContext): Promise<Event | undefined>;
+    private setParentAgentForSubAgents;
+}
+/**
+ * Gets the canonical callback from the given callback.
+ *
+ * @param callbacks The callback or list of callbacks to get the canonical
+ *     callback from.
+ * @return The canonical callback.
+ */
+export declare function getCannonicalCallback<T>(callbacks?: T | T[]): T[];
+export {};

package/dist/types/agents/base_llm_processor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { InvocationContext } from '../agents/invocation_context.js';
+import { Event } from '../events/event.js';
+import { LlmRequest } from '../models/llm_request.js';
+import { LlmResponse } from '../models/llm_response.js';
+/**
+ * Base class for LLM request processor.
+ */
+export declare abstract class BaseLlmRequestProcessor {
+    /**
+     * Runs the processor.
+     */
+    abstract runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
+}
+/**
+ * Base class for LLM response processor.
+ */
+export declare abstract class BaseLlmResponseProcessor {
+    /**
+     * Processes the LLM response.
+     */
+    abstract runAsync(invocationContext: InvocationContext, llmResponse: LlmResponse): AsyncGenerator<Event, void, void>;
+}

package/dist/types/agents/callback_context.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Part } from '@google/genai';
+import { EventActions } from '../events/event_actions.js';
+import { State } from '../sessions/state.js';
+import { InvocationContext } from './invocation_context.js';
+import { ReadonlyContext } from './readonly_context.js';
+/**
+ * The context of various callbacks within an agent run.
+ */
+export declare class CallbackContext extends ReadonlyContext {
+    private readonly _state;
+    readonly eventActions: EventActions;
+    constructor({ invocationContext, eventActions }: {
+        invocationContext: InvocationContext;
+        eventActions?: EventActions;
+    });
+    /**
+     * The delta-aware state of the current session.
+     */
+    get state(): State;
+    /**
+     * Loads an artifact attached to the current session.
+     *
+     * @param filename The filename of the artifact.
+     * @param version The version of the artifact. If not provided, the latest
+     *     version will be used.
+     * @return A promise that resolves to the loaded artifact.
+     */
+    loadArtifact(filename: string, version?: number): Promise<Part | undefined>;
+    /**
+     * Saves an artifact attached to the current session.
+     *
+     * @param filename The filename of the artifact.
+     * @param artifact The artifact to save.
+     * @return A promise that resolves to the version of the saved artifact.
+     */
+    saveArtifact(filename: string, artifact: Part): Promise<number>;
+}