@google/adk 0.2.4 → 0.3.0

package/dist/esm/runner/runner.js

@@ -4,14 +4,24 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { createPartFromText } from "@google/genai";
-import { trace } from "@opentelemetry/api";
-import { InvocationContext, newInvocationContextId } from "../agents/invocation_context.js";
-import { LlmAgent } from "../agents/llm_agent.js";
+import { context, trace } from "@opentelemetry/api";
+import {
+  InvocationContext,
+  newInvocationContextId
+} from "../agents/invocation_context.js";
+import { isLlmAgent } from "../agents/llm_agent.js";
 import { createRunConfig } from "../agents/run_config.js";
-import { BuiltInCodeExecutor } from "../code_executors/built_in_code_executor.js";
+import {
+  BuiltInCodeExecutor,
+  isBuiltInCodeExecutor
+} from "../code_executors/built_in_code_executor.js";
 import { createEvent, getFunctionCalls } from "../events/event.js";
 import { createEventActions } from "../events/event_actions.js";
 import { PluginManager } from "../plugins/plugin_manager.js";
+import {
+  runAsyncGeneratorWithOtelContext,
+  tracer
+} from "../telemetry/tracing.js";
 import { logger } from "../utils/logger.js";
 import { isGemini2OrAbove } from "../utils/model_name.js";
 class Runner {
@@ -29,112 +39,132 @@ class Runner {
    * Runs the agent with the given message, and returns an async generator of
    * events.
    *
-   * @param userId The user ID of the session.
-   * @param sessionId The session ID of the session.
-   * @param newMessage A new message to append to the session.
-   * @param stateDelta An optional state delta to apply to the session.
-   * @param runConfig The run config for the agent.
+   * @param params.userId The user ID of the session.
+   * @param params.sessionId The session ID of the session.
+   * @param params.newMessage A new message to append to the session.
+   * @param params.stateDelta An optional state delta to apply to the session.
+   * @param params.runConfig The run config for the agent.
    * @yields The events generated by the agent.
    */
   // TODO - b/425992518: user, sessionId, and runConfig can be internalized.
-  async *runAsync({
-    userId,
-    sessionId,
-    newMessage,
-    stateDelta,
-    runConfig
-  }) {
-    var _a;
-    runConfig = createRunConfig(runConfig);
-    const span = trace.getTracer("gcp.vertex.agent").startSpan("invocation");
+  async *runAsync(params) {
+    const { userId, sessionId, stateDelta } = params;
+    const runConfig = createRunConfig(params.runConfig);
+    let newMessage = params.newMessage;
+    const span = tracer.startSpan("invocation");
+    const ctx = trace.setSpan(context.active(), span);
     try {
-      const session = await this.sessionService.getSession({ appName: this.appName, userId, sessionId });
-      if (!session) {
-        if (!this.appName) {
-          throw new Error(
-            `Session lookup failed: appName must be provided in runner constructor`
-          );
-        }
-        throw new Error(`Session not found: ${sessionId}`);
-      }
-      if (runConfig.supportCfc && this.agent instanceof LlmAgent) {
-        const modelName = this.agent.canonicalModel.model;
-        if (!isGemini2OrAbove(modelName)) {
-          throw new Error(`CFC is not supported for model: ${modelName} in agent: ${this.agent.name}`);
-        }
-        if (!(this.agent.codeExecutor instanceof BuiltInCodeExecutor)) {
-          this.agent.codeExecutor = new BuiltInCodeExecutor();
-        }
-      }
-      const invocationContext = new InvocationContext({
-        artifactService: this.artifactService,
-        sessionService: this.sessionService,
-        memoryService: this.memoryService,
-        credentialService: this.credentialService,
-        invocationId: newInvocationContextId(),
-        agent: this.agent,
-        session,
-        userContent: newMessage,
-        runConfig,
-        pluginManager: this.pluginManager
-      });
-      const pluginUserMessage = await this.pluginManager.runOnUserMessageCallback({
-        userMessage: newMessage,
-        invocationContext
-      });
-      if (pluginUserMessage) {
-        newMessage = pluginUserMessage;
-      }
-      if (newMessage) {
-        if (!((_a = newMessage.parts) == null ? void 0 : _a.length)) {
-          throw new Error("No parts in the newMessage.");
-        }
-        if (runConfig.saveInputBlobsAsArtifacts) {
-          await this.saveArtifacts(
-            invocationContext.invocationId,
-            session.userId,
-            session.id,
-            newMessage
-          );
-        }
-        await this.sessionService.appendEvent({
-          session,
-          event: createEvent({
-            invocationId: invocationContext.invocationId,
-            author: "user",
-            actions: stateDelta ? createEventActions({ stateDelta }) : void 0,
-            content: newMessage
-          })
-        });
-      }
-      invocationContext.agent = this.determineAgentForResumption(session, this.agent);
-      const beforeRunCallbackResponse = await this.pluginManager.runBeforeRunCallback({ invocationContext });
-      if (beforeRunCallbackResponse) {
-        const earlyExitEvent = createEvent({
-          invocationId: invocationContext.invocationId,
-          author: "model",
-          content: beforeRunCallbackResponse
-        });
-        await this.sessionService.appendEvent({ session, event: earlyExitEvent });
-        yield earlyExitEvent;
-      } else {
-        for await (const event of invocationContext.agent.runAsync(
-          invocationContext
-        )) {
-          if (!event.partial) {
-            await this.sessionService.appendEvent({ session, event });
+      yield* runAsyncGeneratorWithOtelContext(
+        ctx,
+        this,
+        async function* () {
+          var _a;
+          const session = await this.sessionService.getSession({
+            appName: this.appName,
+            userId,
+            sessionId
+          });
+          if (!session) {
+            if (!this.appName) {
+              throw new Error(
+                `Session lookup failed: appName must be provided in runner constructor`
+              );
+            }
+            throw new Error(`Session not found: ${sessionId}`);
           }
-          const modifiedEvent = await this.pluginManager.runOnEventCallback(
-            { invocationContext, event }
+          if (runConfig.supportCfc && isLlmAgent(this.agent)) {
+            const modelName = this.agent.canonicalModel.model;
+            if (!isGemini2OrAbove(modelName)) {
+              throw new Error(
+                `CFC is not supported for model: ${modelName} in agent: ${this.agent.name}`
+              );
+            }
+            if (!isBuiltInCodeExecutor(this.agent.codeExecutor)) {
+              this.agent.codeExecutor = new BuiltInCodeExecutor();
+            }
+          }
+          const invocationContext = new InvocationContext({
+            artifactService: this.artifactService,
+            sessionService: this.sessionService,
+            memoryService: this.memoryService,
+            credentialService: this.credentialService,
+            invocationId: newInvocationContextId(),
+            agent: this.agent,
+            session,
+            userContent: newMessage,
+            runConfig,
+            pluginManager: this.pluginManager
+          });
+          const pluginUserMessage = await this.pluginManager.runOnUserMessageCallback({
+            userMessage: newMessage,
+            invocationContext
+          });
+          if (pluginUserMessage) {
+            newMessage = pluginUserMessage;
+          }
+          if (newMessage) {
+            if (!((_a = newMessage.parts) == null ? void 0 : _a.length)) {
+              throw new Error("No parts in the newMessage.");
+            }
+            if (runConfig.saveInputBlobsAsArtifacts) {
+              await this.saveArtifacts(
+                invocationContext.invocationId,
+                session.userId,
+                session.id,
+                newMessage
+              );
+            }
+            await this.sessionService.appendEvent({
+              session,
+              event: createEvent({
+                invocationId: invocationContext.invocationId,
+                author: "user",
+                actions: stateDelta ? createEventActions({ stateDelta }) : void 0,
+                content: newMessage
+              })
+            });
+          }
+          invocationContext.agent = this.determineAgentForResumption(
+            session,
+            this.agent
           );
-          if (modifiedEvent) {
-            yield modifiedEvent;
-          } else {
-            yield event;
+          if (newMessage) {
+            const beforeRunCallbackResponse = await this.pluginManager.runBeforeRunCallback({
+              invocationContext
+            });
+            if (beforeRunCallbackResponse) {
+              const earlyExitEvent = createEvent({
+                invocationId: invocationContext.invocationId,
+                author: "model",
+                content: beforeRunCallbackResponse
+              });
+              await this.sessionService.appendEvent({
+                session,
+                event: earlyExitEvent
+              });
+              yield earlyExitEvent;
+            } else {
+              for await (const event of invocationContext.agent.runAsync(
+                invocationContext
+              )) {
+                if (!event.partial) {
+                  await this.sessionService.appendEvent({ session, event });
+                }
+                const modifiedEvent = await this.pluginManager.runOnEventCallback({
+                  invocationContext,
+                  event
+                });
+                if (modifiedEvent) {
+                  yield modifiedEvent;
+                } else {
+                  yield event;
+                }
+              }
+              await this.pluginManager.runAfterRunCallback({ invocationContext });
+            }
           }
         }
-      }
-      await this.pluginManager.runAfterRunCallback({ invocationContext });
+      );
     } finally {
       span.end();
     }
@@ -193,7 +223,9 @@ class Runner {
       }
       const agent = rootAgent.findSubAgent(event2.author);
       if (!agent) {
-        logger.warn(`Event from an unknown agent: ${event2.author}, event id: ${event2.id}`);
+        logger.warn(
+          `Event from an unknown agent: ${event2.author}, event id: ${event2.id}`
+        );
         continue;
       }
       if (this.isRoutableLlmAgent(agent)) {
@@ -216,7 +248,7 @@ class Runner {
   isRoutableLlmAgent(agentToRun) {
     let agent = agentToRun;
     while (agent) {
-      if (!(agent instanceof LlmAgent)) {
+      if (!isLlmAgent(agent)) {
         return false;
       }
       if (agent.disallowTransferToParent) {
@@ -234,7 +266,9 @@ function findEventByLastFunctionResponseId(events) {
     return null;
   }
   const lastEvent = events[events.length - 1];
-  const functionCallId = (_d = (_c = (_b = (_a = lastEvent.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.find((part) => part.functionResponse)) == null ? void 0 : _c.functionResponse) == null ? void 0 : _d.id;
+  const functionCallId = (_d = (_c = (_b = (_a = lastEvent.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.find(
+    (part) => part.functionResponse
+  )) == null ? void 0 : _c.functionResponse) == null ? void 0 : _d.id;
   if (!functionCallId) {
     return null;
   }

package/dist/esm/sessions/in_memory_session_service.js

@@ -6,7 +6,9 @@
 import { cloneDeep } from "lodash-es";
 import { randomUUID } from "../utils/env_aware_utils.js";
 import { logger } from "../utils/logger.js";
-import { BaseSessionService } from "./base_session_service.js";
+import {
+  BaseSessionService
+} from "./base_session_service.js";
 import { createSession } from "./session.js";
 import { State } from "./state.js";
 class InMemorySessionService extends BaseSessionService {
@@ -26,7 +28,12 @@ class InMemorySessionService extends BaseSessionService {
      */
     this.appState = {};
   }
-  createSession({ appName, userId, state, sessionId }) {
+  createSession({
+    appName,
+    userId,
+    state,
+    sessionId
+  }) {
     const session = createSession({
       id: sessionId || randomUUID(),
       appName,
@@ -46,7 +53,12 @@ class InMemorySessionService extends BaseSessionService {
       this.mergeState(appName, userId, cloneDeep(session))
     );
   }
-  getSession({ appName, userId, sessionId, config }) {
+  getSession({
+    appName,
+    userId,
+    sessionId,
+    config
+  }) {
     if (!this.sessions[appName] || !this.sessions[appName][userId] || !this.sessions[appName][userId][sessionId]) {
       return Promise.resolve(void 0);
     }
@@ -54,7 +66,9 @@ class InMemorySessionService extends BaseSessionService {
     const copiedSession = cloneDeep(session);
     if (config) {
       if (config.numRecentEvents) {
-        copiedSession.events = copiedSession.events.slice(-config.numRecentEvents);
+        copiedSession.events = copiedSession.events.slice(
+          -config.numRecentEvents
+        );
       }
       if (config.afterTimestamp) {
         let i = copiedSession.events.length - 1;
@@ -71,31 +85,43 @@ class InMemorySessionService extends BaseSessionService {
     }
     return Promise.resolve(this.mergeState(appName, userId, copiedSession));
   }
-  listSessions({ appName, userId }) {
+  listSessions({
+    appName,
+    userId
+  }) {
     if (!this.sessions[appName] || !this.sessions[appName][userId]) {
       return Promise.resolve({ sessions: [] });
     }
     const sessionsWithoutEvents = [];
     for (const session of Object.values(this.sessions[appName][userId])) {
-      sessionsWithoutEvents.push(createSession({
-        id: session.id,
-        appName: session.appName,
-        userId: session.userId,
-        state: {},
-        events: [],
-        lastUpdateTime: session.lastUpdateTime
-      }));
+      sessionsWithoutEvents.push(
+        createSession({
+          id: session.id,
+          appName: session.appName,
+          userId: session.userId,
+          state: {},
+          events: [],
+          lastUpdateTime: session.lastUpdateTime
+        })
+      );
     }
     return Promise.resolve({ sessions: sessionsWithoutEvents });
   }
-  async deleteSession({ appName, userId, sessionId }) {
+  async deleteSession({
+    appName,
+    userId,
+    sessionId
+  }) {
     const session = await this.getSession({ appName, userId, sessionId });
     if (!session) {
       return;
     }
     delete this.sessions[appName][userId][sessionId];
   }
-  async appendEvent({ session, event }) {
+  async appendEvent({
+    session,
+    event
+  }) {
     await super.appendEvent({ session, event });
     session.lastUpdateTime = event.timestamp;
     const appName = session.appName;

package/dist/esm/telemetry/google_cloud.js

@@ -3,13 +3,13 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { GoogleAuth } from "google-auth-library";
-import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
-import { detectResources } from "@opentelemetry/resources";
-import { gcpDetector } from "@opentelemetry/resource-detector-gcp";
+import { MetricExporter } from "@google-cloud/opentelemetry-cloud-monitoring-exporter";
 import { TraceExporter } from "@google-cloud/opentelemetry-cloud-trace-exporter";
+import { gcpDetector } from "@opentelemetry/resource-detector-gcp";
+import { detectResources } from "@opentelemetry/resources";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { MetricExporter } from "@google-cloud/opentelemetry-cloud-monitoring-exporter";
+import { GoogleAuth } from "google-auth-library";
 import { logger } from "../utils/logger.js";
 const GCP_PROJECT_ERROR_MESSAGE = "Cannot determine GCP Project. OTel GCP Exporters cannot be set up. Please make sure to log into correct GCP Project.";
 async function getGcpProjectId() {
@@ -17,7 +17,7 @@ async function getGcpProjectId() {
     const auth = new GoogleAuth();
     const projectId = await auth.getProjectId();
     return projectId || void 0;
-  } catch (error) {
+  } catch (_e) {
     return void 0;
   }
 }
@@ -33,9 +33,7 @@ async function getGcpExporters(config = {}) {
     return {};
   }
   return {
-    spanProcessors: enableTracing ? [
-      new BatchSpanProcessor(new TraceExporter({ projectId }))
-    ] : [],
+    spanProcessors: enableTracing ? [new BatchSpanProcessor(new TraceExporter({ projectId }))] : [],
     metricReaders: enableMetrics ? [
       new PeriodicExportingMetricReader({
         exporter: new MetricExporter({ projectId }),

package/dist/esm/telemetry/setup.js

@@ -3,22 +3,32 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { trace, metrics } from "@opentelemetry/api";
+import { metrics, trace } from "@opentelemetry/api";
 import { logs } from "@opentelemetry/api-logs";
-import { LoggerProvider, BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
-import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { detectResources } from "@opentelemetry/resources";
+import {
+  BatchLogRecordProcessor,
+  LoggerProvider
+} from "@opentelemetry/sdk-logs";
+import {
+  MeterProvider,
+  PeriodicExportingMetricReader
+} from "@opentelemetry/sdk-metrics";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
 function maybeSetOtelProviders(otelHooksToSetup = [], otelResource) {
   const resource = otelResource || getOtelResource();
   const allHooks = [...otelHooksToSetup, getOtelExporters()];
-  const spanProcessors = allHooks.flatMap((hooks) => hooks.spanProcessors || []);
+  const spanProcessors = allHooks.flatMap(
+    (hooks) => hooks.spanProcessors || []
+  );
   const metricReaders = allHooks.flatMap((hooks) => hooks.metricReaders || []);
-  const logRecordProcessors = allHooks.flatMap((hooks) => hooks.logRecordProcessors || []);
+  const logRecordProcessors = allHooks.flatMap(
+    (hooks) => hooks.logRecordProcessors || []
+  );
   if (spanProcessors.length > 0) {
     const tracerProvider = new NodeTracerProvider({
       resource,
@@ -58,7 +68,11 @@ function getOtelExporters(config = getOtelExportersConfig()) {
   const { enableTracing, enableMetrics, enableLogging } = config;
   return {
     spanProcessors: enableTracing ? [new BatchSpanProcessor(new OTLPTraceExporter())] : [],
-    metricReaders: enableMetrics ? [new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() })] : [],
+    metricReaders: enableMetrics ? [
+      new PeriodicExportingMetricReader({
+        exporter: new OTLPMetricExporter()
+      })
+    ] : [],
     logRecordProcessors: enableLogging ? [new BatchLogRecordProcessor(new OTLPLogExporter())] : []
   };
 }

package/dist/esm/telemetry/tracing.js

@@ -3,7 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { trace, context } from "@opentelemetry/api";
+import { context, trace } from "@opentelemetry/api";
 import { version } from "../version.js";
 const GEN_AI_AGENT_DESCRIPTION = "gen_ai.agent.description";
 const GEN_AI_AGENT_NAME = "gen_ai.agent.name";
@@ -13,14 +13,11 @@ const GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id";
 const GEN_AI_TOOL_DESCRIPTION = "gen_ai.tool.description";
 const GEN_AI_TOOL_NAME = "gen_ai.tool.name";
 const GEN_AI_TOOL_TYPE = "gen_ai.tool.type";
-const tracer = trace.getTracer(
-  "gcp.vertex.agent",
-  version
-);
+const tracer = trace.getTracer("gcp.vertex.agent", version);
 function safeJsonSerialize(obj) {
   try {
     return JSON.stringify(obj);
-  } catch (error) {
+  } catch (_e) {
     return "<not serializable>";
   }
 }
@@ -97,7 +94,10 @@ function traceMergedToolCalls({
     "gcp.vertex.agent.llm_request": "{}",
     "gcp.vertex.agent.llm_response": "{}"
   });
-  span.setAttribute("gcp.vertex.agent.tool_response", shouldAddRequestResponseToSpans() ? safeJsonSerialize(functionResponseEvent) : "{}");
+  span.setAttribute(
+    "gcp.vertex.agent.tool_response",
+    shouldAddRequestResponseToSpans() ? safeJsonSerialize(functionResponseEvent) : "{}"
+  );
 }
 function traceCallLlm({
   invocationContext,
@@ -121,14 +121,26 @@ function traceCallLlm({
     span.setAttribute("gen_ai.request.top_p", llmRequest.config.topP);
   }
   if (((_b = llmRequest.config) == null ? void 0 : _b.maxOutputTokens) !== void 0) {
-    span.setAttribute("gen_ai.request.max_tokens", llmRequest.config.maxOutputTokens);
+    span.setAttribute(
+      "gen_ai.request.max_tokens",
+      llmRequest.config.maxOutputTokens
+    );
   }
-  span.setAttribute("gcp.vertex.agent.llm_response", shouldAddRequestResponseToSpans() ? safeJsonSerialize(llmResponse) : "{}");
+  span.setAttribute(
+    "gcp.vertex.agent.llm_response",
+    shouldAddRequestResponseToSpans() ? safeJsonSerialize(llmResponse) : "{}"
+  );
   if (llmResponse.usageMetadata) {
-    span.setAttribute("gen_ai.usage.input_tokens", llmResponse.usageMetadata.promptTokenCount || 0);
+    span.setAttribute(
+      "gen_ai.usage.input_tokens",
+      llmResponse.usageMetadata.promptTokenCount || 0
+    );
   }
   if ((_c = llmResponse.usageMetadata) == null ? void 0 : _c.candidatesTokenCount) {
-    span.setAttribute("gen_ai.usage.output_tokens", llmResponse.usageMetadata.candidatesTokenCount);
+    span.setAttribute(
+      "gen_ai.usage.output_tokens",
+      llmResponse.usageMetadata.candidatesTokenCount
+    );
   }
   if (llmResponse.finishReason) {
     const finishReasonValue = typeof llmResponse.finishReason === "string" ? llmResponse.finishReason.toLowerCase() : String(llmResponse.finishReason).toLowerCase();
@@ -146,7 +158,10 @@ function traceSendData({
     "gcp.vertex.agent.invocation_id": invocationContext.invocationId,
     "gcp.vertex.agent.event_id": eventId
   });
-  span.setAttribute("gcp.vertex.agent.data", shouldAddRequestResponseToSpans() ? safeJsonSerialize(data) : "{}");
+  span.setAttribute(
+    "gcp.vertex.agent.data",
+    shouldAddRequestResponseToSpans() ? safeJsonSerialize(data) : "{}"
+  );
 }
 function buildLlmRequestForTrace(llmRequest) {
   const result = {
@@ -166,7 +181,7 @@ function buildLlmRequestForTrace(llmRequest) {
   });
   return result;
 }
-function bindAsyncGenerator(ctx, generator) {
+function bindOtelContextToAsyncGenerator(ctx, generator) {
   return {
     // Bind the next() method to execute within the provided context
     next: context.bind(ctx, generator.next.bind(generator)),
@@ -176,16 +191,23 @@ function bindAsyncGenerator(ctx, generator) {
     throw: context.bind(ctx, generator.throw.bind(generator)),
     // Ensure the async iterator symbol also returns a context-bound generator
     [Symbol.asyncIterator]() {
-      return bindAsyncGenerator(ctx, generator[Symbol.asyncIterator]());
+      return bindOtelContextToAsyncGenerator(
+        ctx,
+        generator[Symbol.asyncIterator]()
+      );
     }
   };
 }
+function runAsyncGeneratorWithOtelContext(otelContext, generatorFnContext, generatorFn) {
+  const generator = generatorFn.call(generatorFnContext);
+  return bindOtelContextToAsyncGenerator(otelContext, generator);
+}
 function shouldAddRequestResponseToSpans() {
   const envValue = process.env.ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS || "true";
   return envValue === "true" || envValue === "1";
 }
 export {
-  bindAsyncGenerator,
+  runAsyncGeneratorWithOtelContext,
   traceAgentInvocation,
   traceCallLlm,
   traceMergedToolCalls,