@google/adk 0.1.3 → 0.2.0

package/dist/esm/models/base_llm.js

@@ -3,16 +3,25 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { getClientLabels } from "../utils/client_labels.js";
 class BaseLlm {
   /**
    * Creates an instance of BaseLLM.
-   *
-   * @param model The name of the LLM, e.g. gemini-1.5-flash or
+   * @param params The parameters for creating a BaseLlm instance.
+   * @param params.model The name of the LLM, e.g. gemini-1.5-flash or
    *     gemini-1.5-flash-001.
    */
-  constructor(model) {
+  constructor({ model }) {
     this.model = model;
   }
+  get trackingHeaders() {
+    const labels = getClientLabels();
+    const headerValue = labels.join(" ");
+    return {
+      "x-goog-api-client": headerValue,
+      "user-agent": headerValue
+    };
+  }
   /**
    * Appends a user content, so that model can continue to output.
    *

package/dist/esm/models/google_llm.js

@@ -4,10 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { createPartFromText, FinishReason, GoogleGenAI } from "@google/genai";
-import { isBrowser } from "../utils/env_aware_utils.js";
 import { logger } from "../utils/logger.js";
 import { GoogleLLMVariant } from "../utils/variant_utils.js";
-import { version } from "../version.js";
 import { BaseLlm } from "./base_llm.js";
 import { GeminiLlmConnection } from "./gemini_llm_connection.js";
 import { createLlmResponse } from "./llm_response.js";
@@ -18,14 +16,17 @@ class Gemini extends BaseLlm {
    * @param params The parameters for creating a Gemini instance.
    */
   constructor({
-    model = "gemini-2.5-flash",
+    model,
     apiKey,
     vertexai,
     project,
     location,
     headers
-  } = {}) {
-    super(model);
+  }) {
+    if (!model) {
+      model = "gemini-2.5-flash";
+    }
+    super({ model });
     this.project = project;
     this.location = location;
     this.apiKey = apiKey;
@@ -182,21 +183,6 @@ class Gemini extends BaseLlm {
     }
     return this._apiBackend;
   }
-  get trackingHeaders() {
-    if (!this._trackingHeaders) {
-      let frameworkLabel = `google-adk/${version}`;
-      if (!isBrowser() && process.env[AGENT_ENGINE_TELEMETRY_ENV_VARIABLE_NAME]) {
-        frameworkLabel = `${frameworkLabel}+${AGENT_ENGINE_TELEMETRY_TAG}`;
-      }
-      const languageLabel = `gl-typescript/${isBrowser() ? window.navigator.userAgent : process.version}`;
-      const versionHeaderValue = `${frameworkLabel} ${languageLabel}`;
-      this._trackingHeaders = {
-        "x-goog-api-client": versionHeaderValue,
-        "user-agent": versionHeaderValue
-      };
-    }
-    return this._trackingHeaders;
-  }
   get liveApiVersion() {
     if (!this._liveApiVersion) {
       this._liveApiVersion = this.apiBackend === GoogleLLMVariant.VERTEX_AI ? "v1beta1" : "v1alpha";

package/dist/esm/models/registry.js

@@ -35,7 +35,7 @@ const _LLMRegistry = class _LLMRegistry {
    * @returns The LLM instance.
    */
   static newLlm(model) {
-    return new (_LLMRegistry.resolve(model))(model);
+    return new (_LLMRegistry.resolve(model))({ model });
   }
   static _register(modelNameRegex, llmCls) {
     if (_LLMRegistry.llmRegistryDict.has(modelNameRegex)) {

package/dist/esm/telemetry/google_cloud.js

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * 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 { TraceExporter } from "@google-cloud/opentelemetry-cloud-trace-exporter";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { MetricExporter } from "@google-cloud/opentelemetry-cloud-monitoring-exporter";
+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() {
+  try {
+    const auth = new GoogleAuth();
+    const projectId = await auth.getProjectId();
+    return projectId || void 0;
+  } catch (error) {
+    return void 0;
+  }
+}
+async function getGcpExporters(config = {}) {
+  const {
+    enableTracing = false,
+    enableMetrics = false
+    // enableCloudLogging = false,
+  } = config;
+  const projectId = await getGcpProjectId();
+  if (!projectId) {
+    logger.warn(GCP_PROJECT_ERROR_MESSAGE);
+    return {};
+  }
+  return {
+    spanProcessors: enableTracing ? [
+      new BatchSpanProcessor(new TraceExporter({ projectId }))
+    ] : [],
+    metricReaders: enableMetrics ? [
+      new PeriodicExportingMetricReader({
+        exporter: new MetricExporter({ projectId }),
+        exportIntervalMillis: 5e3
+      })
+    ] : [],
+    logRecordProcessors: []
+  };
+}
+function getGcpResource() {
+  return detectResources({ detectors: [gcpDetector] });
+}
+export {
+  getGcpExporters,
+  getGcpResource
+};

package/dist/esm/telemetry/setup.js

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { trace, metrics } from "@opentelemetry/api";
+import { logs } from "@opentelemetry/api-logs";
+import { LoggerProvider, BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { detectResources } from "@opentelemetry/resources";
+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 metricReaders = allHooks.flatMap((hooks) => hooks.metricReaders || []);
+  const logRecordProcessors = allHooks.flatMap((hooks) => hooks.logRecordProcessors || []);
+  if (spanProcessors.length > 0) {
+    const tracerProvider = new NodeTracerProvider({
+      resource,
+      spanProcessors
+    });
+    tracerProvider.register();
+    trace.setGlobalTracerProvider(tracerProvider);
+  }
+  if (metricReaders.length > 0) {
+    const meterProvider = new MeterProvider({
+      readers: metricReaders,
+      resource
+    });
+    metrics.setGlobalMeterProvider(meterProvider);
+  }
+  if (logRecordProcessors.length > 0) {
+    const loggerProvider = new LoggerProvider({
+      resource,
+      processors: logRecordProcessors
+    });
+    logs.setGlobalLoggerProvider(loggerProvider);
+  }
+}
+function getOtelResource() {
+  return detectResources({
+    detectors: []
+  });
+}
+function getOtelExportersConfig() {
+  return {
+    enableTracing: !!(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT),
+    enableMetrics: !!(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT),
+    enableLogging: !!(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT)
+  };
+}
+function getOtelExporters(config = getOtelExportersConfig()) {
+  const { enableTracing, enableMetrics, enableLogging } = config;
+  return {
+    spanProcessors: enableTracing ? [new BatchSpanProcessor(new OTLPTraceExporter())] : [],
+    metricReaders: enableMetrics ? [new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() })] : [],
+    logRecordProcessors: enableLogging ? [new BatchLogRecordProcessor(new OTLPLogExporter())] : []
+  };
+}
+export {
+  maybeSetOtelProviders
+};

package/dist/esm/telemetry/tracing.js

@@ -0,0 +1,195 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { trace, context } 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";
+const GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id";
+const GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
+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
+);
+function safeJsonSerialize(obj) {
+  try {
+    return JSON.stringify(obj);
+  } catch (error) {
+    return "<not serializable>";
+  }
+}
+function traceAgentInvocation({
+  agent,
+  invocationContext
+}) {
+  const span = trace.getActiveSpan();
+  if (!span) return;
+  span.setAttributes({
+    [GEN_AI_OPERATION_NAME]: "invoke_agent",
+    // Conditionally Required
+    [GEN_AI_AGENT_DESCRIPTION]: agent.description,
+    [GEN_AI_AGENT_NAME]: agent.name,
+    [GEN_AI_CONVERSATION_ID]: invocationContext.session.id
+  });
+}
+function traceToolCall({
+  tool,
+  args,
+  functionResponseEvent
+}) {
+  var _a, _b;
+  const span = trace.getActiveSpan();
+  if (!span) return;
+  span.setAttributes({
+    [GEN_AI_OPERATION_NAME]: "execute_tool",
+    [GEN_AI_TOOL_DESCRIPTION]: tool.description || "",
+    [GEN_AI_TOOL_NAME]: tool.name,
+    // e.g. FunctionTool
+    [GEN_AI_TOOL_TYPE]: tool.constructor.name,
+    // Setting empty llm request and response (as UI expect these) while not
+    // applicable for tool_response.
+    "gcp.vertex.agent.llm_request": "{}",
+    "gcp.vertex.agent.llm_response": "{}",
+    "gcp.vertex.agent.tool_call_args": shouldAddRequestResponseToSpans() ? safeJsonSerialize(args) : "{}"
+  });
+  let toolCallId = "<not specified>";
+  let toolResponse = "<not specified>";
+  if ((_a = functionResponseEvent.content) == null ? void 0 : _a.parts) {
+    const responseParts = functionResponseEvent.content.parts;
+    const functionResponse = (_b = responseParts[0]) == null ? void 0 : _b.functionResponse;
+    if (functionResponse == null ? void 0 : functionResponse.id) {
+      toolCallId = functionResponse.id;
+    }
+    if (functionResponse == null ? void 0 : functionResponse.response) {
+      toolResponse = functionResponse.response;
+    }
+  }
+  if (typeof toolResponse !== "object" || toolResponse === null) {
+    toolResponse = { result: toolResponse };
+  }
+  span.setAttributes({
+    [GEN_AI_TOOL_CALL_ID]: toolCallId,
+    "gcp.vertex.agent.event_id": functionResponseEvent.id,
+    "gcp.vertex.agent.tool_response": shouldAddRequestResponseToSpans() ? safeJsonSerialize(toolResponse) : "{}"
+  });
+}
+function traceMergedToolCalls({
+  responseEventId,
+  functionResponseEvent
+}) {
+  const span = trace.getActiveSpan();
+  if (!span) return;
+  span.setAttributes({
+    [GEN_AI_OPERATION_NAME]: "execute_tool",
+    [GEN_AI_TOOL_NAME]: "(merged tools)",
+    [GEN_AI_TOOL_DESCRIPTION]: "(merged tools)",
+    [GEN_AI_TOOL_CALL_ID]: responseEventId,
+    "gcp.vertex.agent.tool_call_args": "N/A",
+    "gcp.vertex.agent.event_id": responseEventId,
+    // Setting empty llm request and response (as UI expect these) while not
+    // applicable for tool_response.
+    "gcp.vertex.agent.llm_request": "{}",
+    "gcp.vertex.agent.llm_response": "{}"
+  });
+  span.setAttribute("gcp.vertex.agent.tool_response", shouldAddRequestResponseToSpans() ? safeJsonSerialize(functionResponseEvent) : "{}");
+}
+function traceCallLlm({
+  invocationContext,
+  eventId,
+  llmRequest,
+  llmResponse
+}) {
+  var _a, _b, _c;
+  const span = trace.getActiveSpan();
+  if (!span) return;
+  span.setAttributes({
+    "gen_ai.system": "gcp.vertex.agent",
+    "gen_ai.request.model": llmRequest.model,
+    "gcp.vertex.agent.invocation_id": invocationContext.invocationId,
+    "gcp.vertex.agent.session_id": invocationContext.session.id,
+    "gcp.vertex.agent.event_id": eventId,
+    // Consider removing once GenAI SDK provides a way to record this info.
+    "gcp.vertex.agent.llm_request": shouldAddRequestResponseToSpans() ? safeJsonSerialize(buildLlmRequestForTrace(llmRequest)) : "{}"
+  });
+  if ((_a = llmRequest.config) == null ? void 0 : _a.topP) {
+    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("gcp.vertex.agent.llm_response", shouldAddRequestResponseToSpans() ? safeJsonSerialize(llmResponse) : "{}");
+  if (llmResponse.usageMetadata) {
+    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);
+  }
+  if (llmResponse.finishReason) {
+    const finishReasonValue = typeof llmResponse.finishReason === "string" ? llmResponse.finishReason.toLowerCase() : String(llmResponse.finishReason).toLowerCase();
+    span.setAttribute("gen_ai.response.finish_reasons", [finishReasonValue]);
+  }
+}
+function traceSendData({
+  invocationContext,
+  eventId,
+  data
+}) {
+  const span = trace.getActiveSpan();
+  if (!span) return;
+  span.setAttributes({
+    "gcp.vertex.agent.invocation_id": invocationContext.invocationId,
+    "gcp.vertex.agent.event_id": eventId
+  });
+  span.setAttribute("gcp.vertex.agent.data", shouldAddRequestResponseToSpans() ? safeJsonSerialize(data) : "{}");
+}
+function buildLlmRequestForTrace(llmRequest) {
+  const result = {
+    model: llmRequest.model,
+    contents: []
+  };
+  if (llmRequest.config) {
+    const { responseSchema, ...cleanConfig } = llmRequest.config;
+    result.config = cleanConfig;
+  }
+  result.contents = llmRequest.contents.map((content) => {
+    var _a;
+    return {
+      role: content.role,
+      parts: ((_a = content.parts) == null ? void 0 : _a.filter((part) => !part.inlineData)) || []
+    };
+  });
+  return result;
+}
+function bindAsyncGenerator(ctx, generator) {
+  return {
+    // Bind the next() method to execute within the provided context
+    next: context.bind(ctx, generator.next.bind(generator)),
+    // Bind the return() method to execute within the provided context
+    return: context.bind(ctx, generator.return.bind(generator)),
+    // Bind the throw() method to execute within the provided context
+    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]());
+    }
+  };
+}
+function shouldAddRequestResponseToSpans() {
+  const envValue = process.env.ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS || "true";
+  return envValue === "true" || envValue === "1";
+}
+export {
+  bindAsyncGenerator,
+  traceAgentInvocation,
+  traceCallLlm,
+  traceMergedToolCalls,
+  traceSendData,
+  traceToolCall,
+  tracer
+};

package/dist/esm/utils/client_labels.js

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { version } from "../version.js";
+import { isBrowser } from "./env_aware_utils.js";
+const ADK_LABEL = "google-adk";
+const LANGUAGE_LABEL = "gl-typescript";
+const AGENT_ENGINE_TELEMETRY_TAG = "remote_reasoning_engine";
+const AGENT_ENGINE_TELEMETRY_ENV_VARIABLE_NAME = "GOOGLE_CLOUD_AGENT_ENGINE_ID";
+function _getDefaultLabels() {
+  let frameworkLabel = `${ADK_LABEL}/${version}`;
+  if (!isBrowser() && process.env[AGENT_ENGINE_TELEMETRY_ENV_VARIABLE_NAME]) {
+    frameworkLabel = `${frameworkLabel}+${AGENT_ENGINE_TELEMETRY_TAG}`;
+  }
+  const languageLabel = `${LANGUAGE_LABEL}/${isBrowser() ? window.navigator.userAgent : process.version}`;
+  return [frameworkLabel, languageLabel];
+}
+function getClientLabels() {
+  const labels = _getDefaultLabels();
+  return labels;
+}
+export {
+  getClientLabels
+};

package/dist/esm/version.js

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

package/dist/types/common.d.ts

@@ -40,6 +40,7 @@ export { Runner } from './runner/runner.js';
 export { InMemorySessionService } from './sessions/in_memory_session_service.js';
 export { createSession } from './sessions/session.js';
 export type { Session } from './sessions/session.js';
+export { State } from './sessions/state.js';
 export { AgentTool } from './tools/agent_tool.js';
 export { BaseTool } from './tools/base_tool.js';
 export { BaseToolset } from './tools/base_toolset.js';
@@ -50,6 +51,7 @@ export { ToolConfirmation } from './tools/tool_confirmation.js';
 export { ToolContext } from './tools/tool_context.js';
 export { LogLevel, setLogLevel } from './utils/logger.js';
 export { zodObjectToSchema } from './utils/simple_zod_to_json.js';
+export { 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';

package/dist/types/index.d.ts

@@ -8,3 +8,5 @@ export * from './tools/mcp/mcp_session_manager.js';
 export * from './tools/mcp/mcp_tool.js';
 export * from './tools/mcp/mcp_toolset.js';
 export * from './artifacts/gcs_artifact_service.js';
+export * from './telemetry/setup.js';
+export * from './telemetry/google_cloud.js';

package/dist/types/models/base_llm.d.ts

@@ -40,6 +40,7 @@ export declare abstract class BaseLlm {
      * @return A live connection to the LLM.
      */
     abstract connect(llmRequest: LlmRequest): Promise<BaseLlmConnection>;
+    protected get trackingHeaders(): Record<string, string>;
     /**
      * Appends a user content, so that model can continue to output.
      *

package/dist/types/models/google_llm.d.ts

@@ -74,7 +74,6 @@ export declare class Gemini extends BaseLlm {
     generateContentAsync(llmRequest: LlmRequest, stream?: boolean): AsyncGenerator<LlmResponse, void>;
     get apiClient(): GoogleGenAI;
     get apiBackend(): GoogleLLMVariant;
-    get trackingHeaders(): Record<string, string>;
     get liveApiVersion(): string;
     get liveApiClient(): GoogleGenAI;
     /**

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

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Resource } from '@opentelemetry/resources';
+import { OtelExportersConfig, OTelHooks } from './setup.js';
+export declare function getGcpExporters(config?: OtelExportersConfig): Promise<OTelHooks>;
+export declare function getGcpResource(): Resource;

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

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LogRecordProcessor } from '@opentelemetry/sdk-logs';
+import { MetricReader } from '@opentelemetry/sdk-metrics';
+import { Resource } from '@opentelemetry/resources';
+import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+export interface OtelExportersConfig {
+    enableTracing?: boolean;
+    enableMetrics?: boolean;
+    enableLogging?: boolean;
+}
+/**
+ * Configuration hooks for OpenTelemetry setup.
+ *
+ * This interface defines the structure for configuring OpenTelemetry
+ * components including span processors, metric readers, and log record processors.
+ */
+export interface OTelHooks {
+    spanProcessors?: SpanProcessor[];
+    metricReaders?: MetricReader[];
+    logRecordProcessors?: LogRecordProcessor[];
+}
+/**
+ * Sets up OTel providers if hooks for a given telemetry type were passed.
+ *
+ * Additionally adds generic OTLP exporters based on following env variables:
+ * OTEL_EXPORTER_OTLP_ENDPOINT
+ * OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
+ * OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
+ * OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
+ * See https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/
+ * for how they are used.
+ *
+ * If a provider for a specific telemetry type was already globally set -
+ * this function will not override it or register more exporters.
+ *
+ * @experimental (Experimental, subject to change)
+ *
+ * @param otelHooksToSetup per-telemetry-type processors and readers to be added
+ * to OTel providers. If no hooks for a specific telemetry type are passed -
+ * provider will not be set.
+ * @param otelResource OTel resource to use in providers.
+ * If empty - default OTel resource detection will be used.
+ */
+export declare function maybeSetOtelProviders(otelHooksToSetup?: OTelHooks[], otelResource?: Resource): void;

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";