@google/adk 0.1.2 → 0.2.0

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

@@ -0,0 +1,111 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * NOTE:
+ *
+ *    We expect that the underlying GenAI SDK will provide a certain
+ *    level of tracing and logging telemetry aligned with Open Telemetry
+ *    Semantic Conventions (such as logging prompts, responses,
+ *    request properties, etc.) and so the information that is recorded by the
+ *    Agent Development Kit should be focused on the higher-level
+ *    constructs of the framework that are not observable by the SDK.
+ */
+import { Content } from '@google/genai';
+import { Context } from '@opentelemetry/api';
+import { BaseAgent } from '../agents/base_agent.js';
+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';
+import { BaseTool } from '../tools/base_tool.js';
+export declare const tracer: import("@opentelemetry/api").Tracer;
+export interface TraceAgentInvocationParams {
+    agent: BaseAgent;
+    invocationContext: InvocationContext;
+}
+/**
+ * Sets span attributes immediately available on agent invocation according to OTEL semconv version 1.37.
+ *
+ * @param params The parameters object containing agent and invocation context.
+ *
+ * Inference related fields are not set, due to their planned removal from invoke_agent span:
+ * https://github.com/open-telemetry/semantic-conventions/issues/2632
+ *
+ * `gen_ai.agent.id` is not set because currently it's unclear what attributes this field should have, specifically:
+ * - In which scope should it be unique (globally, given project, given agentic flow, given deployment).
+ * - Should it be unchanging between deployments, and how this should this be achieved.
+ *
+ * `gen_ai.data_source.id` is not set because it's not available.
+ * Closest type which could contain this information is types.GroundingMetadata, which does not have an ID.
+ *
+ * `server.*` attributes are not set pending confirmation from aabmass.
+ */
+export declare function traceAgentInvocation({ agent, invocationContext, }: TraceAgentInvocationParams): void;
+export interface TraceToolCallParams {
+    tool: BaseTool;
+    args: Record<string, unknown>;
+    functionResponseEvent: Event;
+}
+/**
+ * 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 interface TraceMergedToolCallsParams {
+    responseEventId: string;
+    functionResponseEvent: Event;
+}
+/**
+ * Traces merged tool call events.
+ *
+ * Calling this function is not needed for telemetry purposes. This is provided
+ * for preventing /debug/trace requests (typically sent by web UI).
+ *
+ * @param params The parameters object containing response event ID and function response event.
+ */
+export declare function traceMergedToolCalls({ responseEventId, functionResponseEvent, }: TraceMergedToolCallsParams): void;
+export interface TraceCallLlmParams {
+    invocationContext: InvocationContext;
+    eventId: string;
+    llmRequest: LlmRequest;
+    llmResponse: LlmResponse;
+}
+/**
+ * Traces a call to the LLM.
+ *
+ * This function records details about the LLM request and response as
+ * attributes on the current OpenTelemetry span.
+ *
+ * @param params The parameters object containing invocationContext, eventId, llmRequest, and llmResponse.
+ */
+export declare function traceCallLlm({ invocationContext, eventId, llmRequest, llmResponse, }: TraceCallLlmParams): void;
+export interface TraceSendDataParams {
+    /** The invocation context for the current agent run. */
+    invocationContext: InvocationContext;
+    /** The ID of the event. */
+    eventId: string;
+    /** A list of content objects. */
+    data: Content[];
+}
+/**
+ * Traces the sending of data to the agent.
+ *
+ * This function records details about the data sent to the agent as
+ * attributes on the current OpenTelemetry span.
+ *
+ * @param params The parameters object containing invocationContext, eventId, and data.
+ */
+export declare function traceSendData({ invocationContext, eventId, data, }: TraceSendDataParams): void;
+/**
+ * Binds an async generator to OpenTelemetry context for trace propagation.
+ * This is a temporary solution.
+ * @param ctx - The OpenTelemetry context to bind the generator to
+ * @param generator - The async generator to be bound to the context
+ *
+ * @returns A new async generator that executes all operations within the provided context
+ */
+export declare function bindAsyncGenerator<T = unknown, TReturn = any, TNext = unknown>(ctx: Context, generator: AsyncGenerator<T, TReturn, TNext>): AsyncGenerator<T, TReturn, TNext>;

package/dist/types/utils/client_labels.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Returns the current list of client labels that can be added to HTTP Headers.
+ */
+export declare function getClientLabels(): string[];

package/dist/types/version.d.ts

@@ -3,4 +3,4 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-export declare const version = "0.1.0";
+export declare const version = "0.2.0";

package/dist/web/agents/content_processor_utils.js

@@ -73,8 +73,8 @@ function isEventFromAnotherAgent(agentName, event) {
   return !!agentName && event.author !== agentName && event.author !== "user";
 }
 function convertForeignEvent(event) {
-  var _a, _b, _c, _d, _e;
-  if (!((_a = event.content) == null ? void 0 : _a.parts)) {
+  var _a, _b, _c, _d, _e, _f;
+  if (!((_b = (_a = event.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.length)) {
     return event;
   }
   const content = {
@@ -85,19 +85,21 @@ function convertForeignEvent(event) {
   };
   for (const part of event.content.parts) {
     if (part.text && !part.thought) {
-      (_b = content.parts) == null ? void 0 : _b.push({
+      (_c = content.parts) == null ? void 0 : _c.push({
         text: "[".concat(event.author, "] said: ").concat(part.text)
       });
     } else if (part.functionCall) {
-      (_c = content.parts) == null ? void 0 : _c.push({
-        text: "[".concat(event.author, "] called tool `").concat(part.functionCall.name, "` with parameters: ").concat(part.functionCall.args)
+      const argsText = safeStringify(part.functionCall.args);
+      (_d = content.parts) == null ? void 0 : _d.push({
+        text: "[".concat(event.author, "] called tool `").concat(part.functionCall.name, "` with parameters: ").concat(argsText)
       });
     } else if (part.functionResponse) {
-      (_d = content.parts) == null ? void 0 : _d.push({
-        text: "[".concat(event.author, "] tool `").concat(part.functionResponse.name, "` returned result: ").concat(part.functionResponse.response)
+      const responseText = safeStringify(part.functionResponse.response);
+      (_e = content.parts) == null ? void 0 : _e.push({
+        text: "[".concat(event.author, "] tool `").concat(part.functionResponse.name, "` returned result: ").concat(responseText)
       });
     } else {
-      (_e = content.parts) == null ? void 0 : _e.push(part);
+      (_f = content.parts) == null ? void 0 : _f.push(part);
     }
   }
   return createEvent({
@@ -262,6 +264,16 @@ function rearrangeEventsForAsyncFunctionResponsesInHistory(events) {
   }
   return resultEvents;
 }
+function safeStringify(obj) {
+  if (typeof obj === "string") {
+    return obj;
+  }
+  try {
+    return JSON.stringify(obj);
+  } catch (e) {
+    return String(obj);
+  }
+}
 export {
   getContents,
   getCurrentTurnContents

package/dist/web/agents/functions.js

@@ -3,6 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { createUserContent } from "@google/genai";
 import { createEvent, getFunctionCalls } from "../events/event.js";
 import { mergeEventActions } from "../events/event_actions.js";
 import { ToolContext } from "../tools/tool_context.js";
@@ -126,30 +127,6 @@ async function callToolAsync(tool, args, toolContext) {
   logger.debug("callToolAsync ".concat(tool.name));
   return await tool.runAsync({ args, toolContext });
 }
-function buildResponseEvent(tool, functionResult, toolContext, invocationContext) {
-  let responseResult = functionResult;
-  if (typeof functionResult !== "object" || functionResult == null) {
-    responseResult = { result: functionResult };
-  }
-  const partFunctionResponse = {
-    functionResponse: {
-      name: tool.name,
-      response: responseResult,
-      id: toolContext.functionCallId
-    }
-  };
-  const content = {
-    role: "user",
-    parts: [partFunctionResponse]
-  };
-  return createEvent({
-    invocationId: invocationContext.invocationId,
-    author: invocationContext.agent.name,
-    content,
-    actions: toolContext.actions,
-    branch: invocationContext.branch
-  });
-}
 async function handleFunctionCallsAsync({
   invocationContext,
   functionCallEvent,
@@ -200,6 +177,7 @@ async function handleFunctionCallList({
     logger.debug("execute_tool ".concat(tool.name));
     const functionArgs = (_a = functionCall.args) != null ? _a : {};
     let functionResponse = null;
+    let functionResponseError;
     functionResponse = await invocationContext.pluginManager.runBeforeToolCallback({
       tool,
       toolArgs: functionArgs,
@@ -236,10 +214,11 @@ async function handleFunctionCallList({
           );
           if (onToolErrorResponse) {
             functionResponse = onToolErrorResponse;
+          } else {
+            functionResponseError = e.message;
           }
         } else {
-          logger.error("Unknown error on tool execution type", e);
-          throw e;
+          functionResponseError = e;
         }
       }
     }
@@ -268,12 +247,24 @@ async function handleFunctionCallList({
     if (tool.isLongRunning && !functionResponse) {
       continue;
     }
-    const functionResponseEvent = buildResponseEvent(
-      tool,
-      functionResponse,
-      toolContext,
-      invocationContext
-    );
+    if (functionResponseError) {
+      functionResponse = { error: functionResponseError };
+    } else if (typeof functionResponse !== "object" || functionResponse == null) {
+      functionResponse = { result: functionResponse };
+    }
+    const functionResponseEvent = createEvent({
+      invocationId: invocationContext.invocationId,
+      author: invocationContext.agent.name,
+      content: createUserContent({
+        functionResponse: {
+          id: toolContext.functionCallId,
+          name: tool.name,
+          response: functionResponse
+        }
+      }),
+      actions: toolContext.actions,
+      branch: invocationContext.branch
+    });
     logger.debug("traceToolCall", {
       tool: tool.name,
       args: functionArgs,

package/dist/web/agents/llm_agent.js

@@ -181,6 +181,7 @@ class AgentTransferLlmRequestProcessor extends BaseLlmRequestProcessor {
           throw new Error("toolContext is required.");
         }
         toolContext.actions.transferToAgent = args.agentName;
+        return "Transfer queued";
       }
     });
   }

package/dist/web/artifacts/gcs_artifact_service.js

@@ -0,0 +1,126 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Storage } from "@google-cloud/storage";
+import { createPartFromBase64, createPartFromText } from "@google/genai";
+class GcsArtifactService {
+  constructor(bucket) {
+    this.bucket = new Storage().bucket(bucket);
+  }
+  async saveArtifact(request) {
+    const versions = await this.listVersions(request);
+    const version = versions.length > 0 ? Math.max(...versions) + 1 : 0;
+    const file = this.bucket.file(getFileName(__spreadProps(__spreadValues({}, request), {
+      version
+    })));
+    if (request.artifact.inlineData) {
+      await file.save(JSON.stringify(request.artifact.inlineData.data), {
+        contentType: request.artifact.inlineData.mimeType
+      });
+      return version;
+    }
+    if (request.artifact.text) {
+      await file.save(request.artifact.text, {
+        contentType: "text/plain"
+      });
+      return version;
+    }
+    throw new Error("Artifact must have either inlineData or text.");
+  }
+  async loadArtifact(request) {
+    let version = request.version;
+    if (version === void 0) {
+      const versions = await this.listVersions(request);
+      if (versions.length === 0) {
+        return void 0;
+      }
+      version = Math.max(...versions);
+    }
+    const file = this.bucket.file(getFileName(__spreadProps(__spreadValues({}, request), {
+      version
+    })));
+    const [[metadata], [rawDataBuffer]] = await Promise.all([file.getMetadata(), file.download()]);
+    if (metadata.contentType === "text/plain") {
+      return createPartFromText(rawDataBuffer.toString("utf-8"));
+    }
+    return createPartFromBase64(
+      rawDataBuffer.toString("base64"),
+      metadata.contentType
+    );
+  }
+  async listArtifactKeys(request) {
+    const fileNames = [];
+    const sessionPrefix = "".concat(request.appName, "/").concat(request.userId, "/").concat(request.sessionId, "/");
+    const usernamePrefix = "".concat(request.appName, "/").concat(request.userId, "/user/");
+    const [
+      [sessionFiles],
+      [userSessionFiles]
+    ] = await Promise.all([
+      this.bucket.getFiles({ prefix: sessionPrefix }),
+      this.bucket.getFiles({ prefix: usernamePrefix })
+    ]);
+    for (const file of sessionFiles) {
+      fileNames.push(file.name.split("/").pop());
+    }
+    for (const file of userSessionFiles) {
+      fileNames.push(file.name.split("/").pop());
+    }
+    return fileNames.sort((a, b) => a.localeCompare(b));
+  }
+  async deleteArtifact(request) {
+    const versions = await this.listVersions(request);
+    await Promise.all(versions.map((version) => {
+      const file = this.bucket.file(getFileName(__spreadProps(__spreadValues({}, request), {
+        version
+      })));
+      return file.delete();
+    }));
+    return;
+  }
+  async listVersions(request) {
+    const prefix = getFileName(request);
+    const [files] = await this.bucket.getFiles({ prefix });
+    const versions = [];
+    for (const file of files) {
+      const version = file.name.split("/").pop();
+      versions.push(parseInt(version, 10));
+    }
+    return versions;
+  }
+}
+function getFileName({
+  appName,
+  userId,
+  sessionId,
+  filename,
+  version
+}) {
+  if (filename.startsWith("user:")) {
+    return "".concat(appName, "/").concat(userId, "/user/").concat(filename, "/").concat(version);
+  }
+  return "".concat(appName, "/").concat(userId, "/").concat(sessionId, "/").concat(filename, "/").concat(version);
+}
+export {
+  GcsArtifactService
+};

package/dist/web/common.js

@@ -15,9 +15,11 @@ import { StreamingMode } from "./agents/run_config.js";
 import { SequentialAgent } from "./agents/sequential_agent.js";
 import { InMemoryArtifactService } from "./artifacts/in_memory_artifact_service.js";
 import { createEvent, getFunctionCalls, getFunctionResponses, hasTrailingCodeExecutionResult, isFinalResponse, stringifyContent } from "./events/event.js";
+import { createEventActions } from "./events/event_actions.js";
 import { InMemoryMemoryService } from "./memory/in_memory_memory_service.js";
 import { BaseLlm } from "./models/base_llm.js";
 import { Gemini } from "./models/google_llm.js";
+import { LLMRegistry } from "./models/registry.js";
 import { BasePlugin } from "./plugins/base_plugin.js";
 import { LoggingPlugin } from "./plugins/logging_plugin.js";
 import { PluginManager } from "./plugins/plugin_manager.js";
@@ -26,6 +28,7 @@ import { InMemoryRunner } from "./runner/in_memory_runner.js";
 import { Runner } from "./runner/runner.js";
 import { InMemorySessionService } from "./sessions/in_memory_session_service.js";
 import { createSession } from "./sessions/session.js";
+import { State } from "./sessions/state.js";
 import { AgentTool } from "./tools/agent_tool.js";
 import { BaseTool } from "./tools/base_tool.js";
 import { BaseToolset } from "./tools/base_toolset.js";
@@ -36,6 +39,7 @@ import { ToolConfirmation } from "./tools/tool_confirmation.js";
 import { ToolContext } from "./tools/tool_context.js";
 import { LogLevel, setLogLevel } from "./utils/logger.js";
 import { zodObjectToSchema } from "./utils/simple_zod_to_json.js";
+import { version } from "./version.js";
 export * from "./artifacts/base_artifact_service.js";
 export * from "./memory/base_memory_service.js";
 export * from "./sessions/base_session_service.js";
@@ -57,6 +61,7 @@ export {
   InMemoryRunner,
   InMemorySessionService,
   InvocationContext,
+  LLMRegistry,
   LiveRequestQueue,
   LlmAgent,
   LogLevel,
@@ -70,10 +75,12 @@ export {
   Runner,
   SecurityPlugin,
   SequentialAgent,
+  State,
   StreamingMode,
   ToolConfirmation,
   ToolContext,
   createEvent,
+  createEventActions,
   createSession,
   functionsExportedForTestingOnly,
   getAskUserConfirmationFunctionCalls,
@@ -83,5 +90,6 @@ export {
   isFinalResponse,
   setLogLevel,
   stringifyContent,
+  version,
   zodObjectToSchema
 };