@iqai/adk 0.5.9 → 0.6.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { Content, Part, GroundingMetadata, GenerateContentResponseUsageMetadata, Blob, SpeechConfig, AudioTranscriptionConfig, RealtimeInputConfig, ProactivityConfig, FunctionDeclaration, GenerateContentConfig, Schema, LiveConnectConfig, GoogleGenAI, FunctionCall } from '@google/genai';
 export { Blob, Content, FunctionDeclaration, Schema as JSONSchema } from '@google/genai';
+import { SpanContext, Tracer, Span } from '@opentelemetry/api';
 import * as z from 'zod';
 import { z as z$1, ZodSchema, ZodType } from 'zod';
 import { LanguageModel } from 'ai';
@@ -7,7 +8,6 @@ import { StorageOptions } from '@google-cloud/storage';
 import { Kysely, Generated } from 'kysely';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { CreateMessageRequest, CreateMessageResult, Tool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import { Tracer } from '@opentelemetry/api';
 
 interface LoggerOpts {
     name: string;
@@ -1122,6 +1122,22 @@ declare class TranscriptionEntry {
     });
 }
 
+/**
+ * Transfer context for multi-agent workflows
+ * Tracks the chain of agent transfers for telemetry
+ */
+interface TransferContext {
+    /** Array of agent names in transfer order */
+    transferChain: string[];
+    /** Current depth in transfer chain (0 = root) */
+    transferDepth: number;
+    /** Name of the root agent that started the chain */
+    rootAgentName: string;
+    /** Span context of the root agent for linking */
+    rootSpanContext?: SpanContext;
+    /** Span context of the previous agent in the chain */
+    previousSpanContext?: SpanContext;
+}
 /**
  * Error thrown when the number of LLM calls exceed the limit.
  */
@@ -1228,6 +1244,11 @@ declare class InvocationContext {
      * Configurations for live agents under this invocation.
      */
     runConfig?: RunConfig;
+    /**
+     * Transfer context for multi-agent workflows
+     * Tracks agent transfer chain for telemetry
+     */
+    transferContext?: TransferContext;
     /**
      * A container to keep track of different kinds of costs incurred as a part
      * of this invocation.
@@ -1251,6 +1272,7 @@ declare class InvocationContext {
         activeStreamingTools?: Record<string, ActiveStreamingTool>;
         transcriptionCache?: TranscriptionEntry[];
         runConfig?: RunConfig;
+        transferContext?: TransferContext;
     });
     /**
      * App name from the session
@@ -4740,11 +4762,12 @@ type index$4_SingleBeforeToolCallback = SingleBeforeToolCallback;
 type index$4_StreamingMode = StreamingMode;
 declare const index$4_StreamingMode: typeof StreamingMode;
 type index$4_ToolUnion = ToolUnion;
+type index$4_TransferContext = TransferContext;
 declare const index$4_createBranchContextForSubAgent: typeof createBranchContextForSubAgent;
 declare const index$4_mergeAgentRun: typeof mergeAgentRun;
 declare const index$4_newInvocationContextId: typeof newInvocationContextId;
 declare namespace index$4 {
-  export { type index$4_AfterAgentCallback as AfterAgentCallback, type index$4_AfterModelCallback as AfterModelCallback, type index$4_AfterToolCallback as AfterToolCallback, LlmAgent as Agent, index$4_AgentBuilder as AgentBuilder, type index$4_AgentBuilderConfig as AgentBuilderConfig, type index$4_AgentBuilderWithSchema as AgentBuilderWithSchema, type index$4_AgentType as AgentType, index$4_BaseAgent as BaseAgent, type index$4_BeforeAgentCallback as BeforeAgentCallback, type index$4_BeforeModelCallback as BeforeModelCallback, type index$4_BeforeToolCallback as BeforeToolCallback, type index$4_BuiltAgent as BuiltAgent, index$4_CallbackContext as CallbackContext, type index$4_EnhancedRunner as EnhancedRunner, type index$4_FullMessage as FullMessage, type index$4_InstructionProvider as InstructionProvider, index$4_InvocationContext as InvocationContext, index$4_LangGraphAgent as LangGraphAgent, type index$4_LangGraphAgentConfig as LangGraphAgentConfig, type index$4_LangGraphNode as LangGraphNode, index$4_LlmAgent as LlmAgent, type index$4_LlmAgentConfig as LlmAgentConfig, index$4_LlmCallsLimitExceededError as LlmCallsLimitExceededError, index$4_LoopAgent as LoopAgent, type index$4_LoopAgentConfig as LoopAgentConfig, type index$4_MessagePart as MessagePart, type index$4_MultiAgentResponse as MultiAgentResponse, index$4_ParallelAgent as ParallelAgent, type index$4_ParallelAgentConfig as ParallelAgentConfig, index$4_ReadonlyContext as ReadonlyContext, index$4_RunConfig as RunConfig, type index$4_RunnerAskReturn as RunnerAskReturn, index$4_SequentialAgent as SequentialAgent, type index$4_SequentialAgentConfig as SequentialAgentConfig, type index$4_SessionOptions as SessionOptions, type index$4_SingleAfterModelCallback as SingleAfterModelCallback, type index$4_SingleAfterToolCallback as SingleAfterToolCallback, type index$4_SingleAgentCallback as SingleAgentCallback, type index$4_SingleBeforeModelCallback as SingleBeforeModelCallback, type index$4_SingleBeforeToolCallback as SingleBeforeToolCallback, index$4_StreamingMode as StreamingMode, type index$4_ToolUnion as ToolUnion, index$4_createBranchContextForSubAgent as createBranchContextForSubAgent, index$4_mergeAgentRun as mergeAgentRun, index$4_newInvocationContextId as newInvocationContextId };
+  export { type index$4_AfterAgentCallback as AfterAgentCallback, type index$4_AfterModelCallback as AfterModelCallback, type index$4_AfterToolCallback as AfterToolCallback, LlmAgent as Agent, index$4_AgentBuilder as AgentBuilder, type index$4_AgentBuilderConfig as AgentBuilderConfig, type index$4_AgentBuilderWithSchema as AgentBuilderWithSchema, type index$4_AgentType as AgentType, index$4_BaseAgent as BaseAgent, type index$4_BeforeAgentCallback as BeforeAgentCallback, type index$4_BeforeModelCallback as BeforeModelCallback, type index$4_BeforeToolCallback as BeforeToolCallback, type index$4_BuiltAgent as BuiltAgent, index$4_CallbackContext as CallbackContext, type index$4_EnhancedRunner as EnhancedRunner, type index$4_FullMessage as FullMessage, type index$4_InstructionProvider as InstructionProvider, index$4_InvocationContext as InvocationContext, index$4_LangGraphAgent as LangGraphAgent, type index$4_LangGraphAgentConfig as LangGraphAgentConfig, type index$4_LangGraphNode as LangGraphNode, index$4_LlmAgent as LlmAgent, type index$4_LlmAgentConfig as LlmAgentConfig, index$4_LlmCallsLimitExceededError as LlmCallsLimitExceededError, index$4_LoopAgent as LoopAgent, type index$4_LoopAgentConfig as LoopAgentConfig, type index$4_MessagePart as MessagePart, type index$4_MultiAgentResponse as MultiAgentResponse, index$4_ParallelAgent as ParallelAgent, type index$4_ParallelAgentConfig as ParallelAgentConfig, index$4_ReadonlyContext as ReadonlyContext, index$4_RunConfig as RunConfig, type index$4_RunnerAskReturn as RunnerAskReturn, index$4_SequentialAgent as SequentialAgent, type index$4_SequentialAgentConfig as SequentialAgentConfig, type index$4_SessionOptions as SessionOptions, type index$4_SingleAfterModelCallback as SingleAfterModelCallback, type index$4_SingleAfterToolCallback as SingleAfterToolCallback, type index$4_SingleAgentCallback as SingleAgentCallback, type index$4_SingleBeforeModelCallback as SingleBeforeModelCallback, type index$4_SingleBeforeToolCallback as SingleBeforeToolCallback, index$4_StreamingMode as StreamingMode, type index$4_ToolUnion as ToolUnion, type index$4_TransferContext as TransferContext, index$4_createBranchContextForSubAgent as createBranchContextForSubAgent, index$4_mergeAgentRun as mergeAgentRun, index$4_newInvocationContextId as newInvocationContextId };
 }
 
 interface ParsedArtifactUri {
@@ -5575,7 +5598,7 @@ declare class LangfusePlugin extends BasePlugin {
     /**
      * Converts any data to plain text, handling various formats
      */
-    private toPlainText;
+    toPlainText(data: any): string;
     /**
      * Serializes Content to structured format for Langfuse
      */
@@ -6100,76 +6123,590 @@ declare class InMemoryRunner<T extends BaseAgent = BaseAgent> extends Runner<T>
     });
 }
 
+/**
+ * Configuration for the telemetry system
+ */
 interface TelemetryConfig {
+    /** Application name (used as service name) */
     appName: string;
+    /** Application version (optional) */
     appVersion?: string;
+    /** OTLP endpoint for traces (e.g., http://localhost:4318/v1/traces) */
     otlpEndpoint: string;
+    /** Custom headers for OTLP exporter */
     otlpHeaders?: Record<string, string>;
+    /** Deployment environment (e.g., development, staging, production) */
+    environment?: string;
+    /** Enable tracing (default: true) */
+    enableTracing?: boolean;
+    /** Enable metrics (default: true) */
+    enableMetrics?: boolean;
+    /** Enable auto-instrumentation for HTTP, databases, etc. (default: true) */
+    enableAutoInstrumentation?: boolean;
+    /** Capture message content in traces (default: true, set false for privacy) */
+    captureMessageContent?: boolean;
+    /** Sampling ratio for traces (0.0 to 1.0, default: 1.0 = 100%) */
+    samplingRatio?: number;
+    /** Metric export interval in milliseconds (default: 60000 = 1 minute) */
+    metricExportIntervalMs?: number;
+    /** Additional resource attributes */
+    resourceAttributes?: Record<string, string | number | boolean>;
+}
+/**
+ * Span attribute data for agent invocations
+ */
+interface AgentSpanAttributes {
+    agentName: string;
+    agentDescription?: string;
+    sessionId: string;
+    userId?: string;
+    invocationId: string;
     environment?: string;
+    input?: string | Record<string, any>;
+    output?: string | Record<string, any>;
 }
 /**
- * Telemetry service for the ADK
- * Handles OpenTelemetry initialization, tracing, and cleanup
+ * Span attribute data for tool executions
+ */
+interface ToolSpanAttributes {
+    toolName: string;
+    toolDescription?: string;
+    toolType: string;
+    toolCallId: string;
+    args: Record<string, any>;
+    response: any;
+    sessionId: string;
+    userId?: string;
+    eventId: string;
+}
+/**
+ * Span attribute data for LLM calls
+ */
+interface LlmSpanAttributes {
+    model: string;
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    finishReason?: string;
+    sessionId: string;
+    userId?: string;
+    invocationId: string;
+    eventId: string;
+}
+/**
+ * Metric dimensions for agent metrics
+ */
+interface AgentMetricDimensions {
+    agentName: string;
+    environment?: string;
+    status: "success" | "error";
+}
+/**
+ * Metric dimensions for tool metrics
+ */
+interface ToolMetricDimensions {
+    toolName: string;
+    agentName?: string;
+    environment?: string;
+    status: "success" | "error";
+}
+/**
+ * Metric dimensions for LLM metrics
+ */
+interface LlmMetricDimensions {
+    model: string;
+    agentName?: string;
+    environment?: string;
+    status: "success" | "error";
+}
+/**
+ * Parameters for tracing an agent invocation
+ */
+interface TraceAgentParams {
+    agent: {
+        name: string;
+        description?: string;
+    };
+    invocationContext: InvocationContext;
+}
+/**
+ * Parameters for tracing a tool call
+ */
+interface TraceToolParams {
+    tool: BaseTool;
+    args: Record<string, any>;
+    functionResponseEvent: Event;
+    llmRequest?: LlmRequest;
+    invocationContext?: InvocationContext;
+}
+/**
+ * Parameters for tracing an LLM call
+ */
+interface TraceLlmParams {
+    invocationContext: InvocationContext;
+    eventId: string;
+    llmRequest: LlmRequest;
+    llmResponse: LlmResponse;
+}
+/**
+ * Telemetry statistics
+ */
+interface TelemetryStats {
+    agentInvocations: number;
+    toolExecutions: number;
+    llmCalls: number;
+    totalTokens: number;
+    errors: number;
+}
+/**
+ * Parameters for tracing a callback execution
+ */
+interface TraceCallbackParams {
+    callbackType: "before_agent" | "after_agent" | "before_tool" | "after_tool" | "before_model" | "after_model";
+    callbackName?: string;
+    callbackIndex: number;
+    invocationContext?: InvocationContext;
+}
+/**
+ * Enhanced tool span attributes with execution tracking
+ */
+interface EnhancedToolSpanAttributes extends ToolSpanAttributes {
+    executionOrder?: number;
+    parallelGroup?: string;
+    retryCount?: number;
+    isCallbackOverride?: boolean;
+}
+/**
+ * Enhanced LLM span attributes with streaming metrics
+ */
+interface EnhancedLlmSpanAttributes extends LlmSpanAttributes {
+    streaming?: boolean;
+    timeToFirstTokenMs?: number;
+    chunkCount?: number;
+    cachedTokens?: number;
+    contextWindowUsedPct?: number;
+}
+/**
+ * Parameters for tracing an agent transfer
+ */
+interface TraceAgentTransferParams {
+    sourceAgent: string;
+    targetAgent: string;
+    reason?: string;
+    transferContext: TransferContext;
+    invocationContext?: InvocationContext;
+}
+/**
+ * Error span attributes
+ */
+interface ErrorSpanAttributes {
+    errorCategory: "tool_error" | "model_error" | "transfer_error" | "callback_error" | "memory_error" | "session_error" | "plugin_error" | "unknown_error";
+    errorRecoverable: boolean;
+    errorRetryRecommended: boolean;
+    errorMessage: string;
+    errorStack?: string;
+}
+/**
+ * Parameters for tracing memory operations
+ */
+interface TraceMemoryParams {
+    operation: "search" | "insert" | "delete";
+    query?: string;
+    resultsCount?: number;
+    sessionId: string;
+    invocationContext?: InvocationContext;
+}
+/**
+ * Parameters for tracing session operations
+ */
+interface TraceSessionParams {
+    operation: "create" | "get" | "update" | "delete";
+    sessionId: string;
+    userId?: string;
+    found?: boolean;
+}
+/**
+ * Parameters for tracing plugin hooks
+ */
+interface TracePluginParams {
+    pluginName: string;
+    hook: "before_agent" | "after_agent" | "before_model" | "after_model" | "on_event";
+    agentName?: string;
+    invocationContext?: InvocationContext;
+}
+
+/**
+ * Semantic Conventions and Constants
+ * OpenTelemetry semantic conventions for ADK telemetry
+ */
+/**
+ * Standard OpenTelemetry GenAI semantic conventions
+ * Reference: https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ * Version: v1.38.0 (development status)
+ */
+declare const SEMCONV: {
+    readonly GEN_AI_PROVIDER_NAME: "gen_ai.provider.name";
+    readonly GEN_AI_OPERATION_NAME: "gen_ai.operation.name";
+    readonly GEN_AI_AGENT_ID: "gen_ai.agent.id";
+    readonly GEN_AI_AGENT_NAME: "gen_ai.agent.name";
+    readonly GEN_AI_AGENT_DESCRIPTION: "gen_ai.agent.description";
+    readonly GEN_AI_CONVERSATION_ID: "gen_ai.conversation.id";
+    readonly GEN_AI_TOOL_NAME: "gen_ai.tool.name";
+    readonly GEN_AI_TOOL_DESCRIPTION: "gen_ai.tool.description";
+    readonly GEN_AI_TOOL_TYPE: "gen_ai.tool.type";
+    readonly GEN_AI_TOOL_CALL_ID: "gen_ai.tool.call.id";
+    readonly GEN_AI_TOOL_CALL_ARGUMENTS: "gen_ai.tool.call.arguments";
+    readonly GEN_AI_TOOL_CALL_RESULT: "gen_ai.tool.call.result";
+    readonly GEN_AI_TOOL_DEFINITIONS: "gen_ai.tool.definitions";
+    readonly GEN_AI_REQUEST_MODEL: "gen_ai.request.model";
+    readonly GEN_AI_REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens";
+    readonly GEN_AI_REQUEST_TEMPERATURE: "gen_ai.request.temperature";
+    readonly GEN_AI_REQUEST_TOP_P: "gen_ai.request.top_p";
+    readonly GEN_AI_REQUEST_TOP_K: "gen_ai.request.top_k";
+    readonly GEN_AI_REQUEST_FREQUENCY_PENALTY: "gen_ai.request.frequency_penalty";
+    readonly GEN_AI_REQUEST_PRESENCE_PENALTY: "gen_ai.request.presence_penalty";
+    readonly GEN_AI_REQUEST_STOP_SEQUENCES: "gen_ai.request.stop_sequences";
+    readonly GEN_AI_REQUEST_CHOICE_COUNT: "gen_ai.request.choice.count";
+    readonly GEN_AI_REQUEST_SEED: "gen_ai.request.seed";
+    readonly GEN_AI_RESPONSE_ID: "gen_ai.response.id";
+    readonly GEN_AI_RESPONSE_MODEL: "gen_ai.response.model";
+    readonly GEN_AI_RESPONSE_FINISH_REASONS: "gen_ai.response.finish_reasons";
+    readonly GEN_AI_OUTPUT_TYPE: "gen_ai.output.type";
+    readonly GEN_AI_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly GEN_AI_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+    readonly GEN_AI_SYSTEM_INSTRUCTIONS: "gen_ai.system_instructions";
+    readonly GEN_AI_INPUT_MESSAGES: "gen_ai.input.messages";
+    readonly GEN_AI_OUTPUT_MESSAGES: "gen_ai.output.messages";
+    readonly SERVER_ADDRESS: "server.address";
+    readonly SERVER_PORT: "server.port";
+    readonly ERROR_TYPE: "error.type";
+    readonly GEN_AI_DATA_SOURCE_ID: "gen_ai.data_source.id";
+    readonly GEN_AI_EMBEDDINGS_DIMENSION_COUNT: "gen_ai.embeddings.dimension.count";
+    readonly GEN_AI_REQUEST_ENCODING_FORMATS: "gen_ai.request.encoding_formats";
+    /**
+     * @deprecated Use GEN_AI_PROVIDER_NAME instead
+     */
+    readonly GEN_AI_SYSTEM: "gen_ai.system";
+    /**
+     * @deprecated Total tokens should be computed client-side from input + output
+     */
+    readonly GEN_AI_USAGE_TOTAL_TOKENS: "gen_ai.usage.total_tokens";
+    /**
+     * @deprecated Use GEN_AI_INPUT_MESSAGES or structured events instead
+     */
+    readonly GEN_AI_CONTENT_PROMPT: "gen_ai.content.prompt";
+    /**
+     * @deprecated Use GEN_AI_OUTPUT_MESSAGES or structured events instead
+     */
+    readonly GEN_AI_CONTENT_COMPLETION: "gen_ai.content.completion";
+};
+/**
+ * ADK-specific attribute namespace
+ * Custom attributes for IQAI ADK framework
+ */
+declare const ADK_ATTRS: {
+    readonly SYSTEM_NAME: "adk.system.name";
+    readonly SYSTEM_VERSION: "adk.system.version";
+    readonly SESSION_ID: "adk.session.id";
+    readonly USER_ID: "adk.user.id";
+    readonly INVOCATION_ID: "adk.invocation.id";
+    readonly EVENT_ID: "adk.event.id";
+    readonly ENVIRONMENT: "adk.environment";
+    readonly AGENT_NAME: "adk.agent.name";
+    readonly AGENT_DESCRIPTION: "adk.agent.description";
+    readonly TRANSFER_SOURCE_AGENT: "adk.transfer.source_agent";
+    readonly TRANSFER_TARGET_AGENT: "adk.transfer.target_agent";
+    readonly TRANSFER_CHAIN: "adk.transfer.chain";
+    readonly TRANSFER_DEPTH: "adk.transfer.depth";
+    readonly TRANSFER_ROOT_AGENT: "adk.transfer.root_agent";
+    readonly TRANSFER_REASON: "adk.transfer.reason";
+    readonly TOOL_NAME: "adk.tool.name";
+    readonly TOOL_ARGS: "adk.tool.args";
+    readonly TOOL_RESPONSE: "adk.tool.response";
+    readonly TOOL_EXECUTION_ORDER: "adk.tool.execution_order";
+    readonly TOOL_PARALLEL_GROUP: "adk.tool.parallel_group";
+    readonly TOOL_RETRY_COUNT: "adk.tool.retry_count";
+    readonly TOOL_IS_CALLBACK_OVERRIDE: "adk.tool.is_callback_override";
+    readonly LLM_MODEL: "adk.llm.model";
+    readonly LLM_REQUEST: "adk.llm.request";
+    readonly LLM_RESPONSE: "adk.llm.response";
+    readonly LLM_STREAMING: "adk.llm.streaming";
+    readonly LLM_TIME_TO_FIRST_TOKEN: "adk.llm.time_to_first_token_ms";
+    readonly LLM_CHUNK_COUNT: "adk.llm.chunk_count";
+    readonly LLM_CACHED_TOKENS: "adk.llm.cached_tokens";
+    readonly LLM_CONTEXT_WINDOW_USED_PCT: "adk.llm.context_window_used_pct";
+    readonly CALLBACK_TYPE: "adk.callback.type";
+    readonly CALLBACK_NAME: "adk.callback.name";
+    readonly CALLBACK_INDEX: "adk.callback.index";
+    readonly ERROR_CATEGORY: "adk.error.category";
+    readonly ERROR_RECOVERABLE: "adk.error.recoverable";
+    readonly ERROR_RETRY_RECOMMENDED: "adk.error.retry_recommended";
+    readonly MEMORY_QUERY: "adk.memory.query";
+    readonly MEMORY_RESULTS_COUNT: "adk.memory.results_count";
+    readonly PLUGIN_NAME: "adk.plugin.name";
+    readonly PLUGIN_HOOK: "adk.plugin.hook";
+};
+/**
+ * Operation names for different trace operations
+ * Reference: https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
+ */
+declare const OPERATIONS: {
+    readonly CHAT: "chat";
+    readonly TEXT_COMPLETION: "text_completion";
+    readonly GENERATE_CONTENT: "generate_content";
+    readonly INVOKE_AGENT: "invoke_agent";
+    readonly CREATE_AGENT: "create_agent";
+    readonly EXECUTE_TOOL: "execute_tool";
+    readonly TRANSFER_AGENT: "transfer_agent";
+    readonly EXECUTE_CALLBACK: "execute_callback";
+    readonly SEARCH_MEMORY: "search_memory";
+    readonly INSERT_MEMORY: "insert_memory";
+    readonly EXECUTE_PLUGIN: "execute_plugin";
+    /**
+     * @deprecated Use CHAT, TEXT_COMPLETION, or GENERATE_CONTENT instead
+     */
+    readonly CALL_LLM: "call_llm";
+};
+/**
+ * System identifier for IQAI ADK
+ */
+declare const ADK_SYSTEM_NAME = "iqai-adk";
+/**
+ * Environment variable names
+ */
+declare const ENV_VARS: {
+    readonly CAPTURE_MESSAGE_CONTENT: "ADK_CAPTURE_MESSAGE_CONTENT";
+    readonly OTEL_SERVICE_NAME: "OTEL_SERVICE_NAME";
+    readonly OTEL_RESOURCE_ATTRIBUTES: "OTEL_RESOURCE_ATTRIBUTES";
+    readonly OTEL_EXPORTER_OTLP_ENDPOINT: "OTEL_EXPORTER_OTLP_ENDPOINT";
+    readonly OTEL_EXPORTER_OTLP_HEADERS: "OTEL_EXPORTER_OTLP_HEADERS";
+    readonly NODE_ENV: "NODE_ENV";
+};
+/**
+ * Metric names
+ * Includes both standard OpenTelemetry GenAI metrics and ADK-specific metrics
+ */
+declare const METRICS: {
+    readonly GEN_AI_CLIENT_OPERATION_DURATION: "gen_ai.client.operation.duration";
+    readonly GEN_AI_CLIENT_TOKEN_USAGE: "gen_ai.client.token.usage";
+    readonly GEN_AI_SERVER_REQUEST_DURATION: "gen_ai.server.request.duration";
+    readonly GEN_AI_SERVER_TIME_TO_FIRST_TOKEN: "gen_ai.server.time_to_first_token";
+    readonly GEN_AI_SERVER_TIME_PER_OUTPUT_TOKEN: "gen_ai.server.time_per_output_token";
+    readonly AGENT_INVOCATIONS: "adk.agent.invocations";
+    readonly TOOL_EXECUTIONS: "adk.tool.executions";
+    readonly LLM_CALLS: "adk.llm.calls";
+    readonly ERRORS: "adk.errors";
+    readonly AGENT_DURATION: "adk.agent.duration";
+    readonly TOOL_DURATION: "adk.tool.duration";
+    readonly LLM_DURATION: "adk.llm.duration";
+    readonly LLM_TOKENS: "adk.llm.tokens";
+    readonly LLM_INPUT_TOKENS: "adk.llm.tokens.input";
+    readonly LLM_OUTPUT_TOKENS: "adk.llm.tokens.output";
+};
+/**
+ * Default configuration values
+ */
+declare const DEFAULTS: {
+    readonly SAMPLING_RATIO: 1;
+    readonly METRIC_EXPORT_INTERVAL_MS: 60000;
+    readonly SHUTDOWN_TIMEOUT_MS: 5000;
+    readonly CAPTURE_MESSAGE_CONTENT: true;
+    readonly ENABLE_TRACING: true;
+    readonly ENABLE_METRICS: true;
+    readonly ENABLE_AUTO_INSTRUMENTATION: true;
+};
+
+/**
+ * Telemetry Utilities
+ * Helper functions for telemetry operations
+ */
+
+/**
+ * Check if message content should be captured in traces
+ * Based on ADK_CAPTURE_MESSAGE_CONTENT environment variable
+ */
+declare function shouldCaptureContent(): boolean;
+/**
+ * Extract text content from a Content object or array of Parts
+ * Handles the common pattern of extracting readable text from message parts
+ */
+declare function extractTextFromContent(content: Content | {
+    parts?: Part[];
+} | undefined): string;
+/**
+ * Safely stringify an object to JSON
+ * Returns a placeholder string if serialization fails
+ */
+declare function safeJsonStringify(obj: any): string;
+/**
+ * Get environment name from NODE_ENV or custom environment variable
+ */
+declare function getEnvironment(): string | undefined;
+/**
+ * Build a sanitized LLM request object for tracing
+ * Excludes non-serializable fields and optionally excludes content
+ */
+declare function buildLlmRequestForTrace(llmRequest: any, includeContent?: boolean): Record<string, any>;
+/**
+ * Build a sanitized LLM response object for tracing
+ */
+declare function buildLlmResponseForTrace(llmResponse: any, includeContent?: boolean): Record<string, any>;
+/**
+ * Format attributes for OpenTelemetry span
+ * Ensures all values are compatible with OTel attribute types
+ */
+declare function formatSpanAttributes(attributes: Record<string, any>): Record<string, string | number | boolean | string[]>;
+
+/**
+ * Main telemetry service
+ * Unified interface for all telemetry operations
  */
 declare class TelemetryService {
-    private sdk;
-    private isInitialized;
-    private tracer;
-    private config;
-    constructor();
     /**
-     * Initialize telemetry with the provided configuration
+     * Initialize telemetry system
      */
-    initialize(config: TelemetryConfig): void;
-    /**
-     * Get the tracer instance
-     */
-    getTracer(): Tracer;
+    initialize(config: TelemetryConfig): Promise<void>;
     /**
      * Check if telemetry is initialized
      */
     get initialized(): boolean;
     /**
-     * Get the current configuration
+     * Get current configuration
      */
     getConfig(): TelemetryConfig | null;
     /**
-     * Shutdown telemetry with optional timeout
+     * Get tracer instance
      */
-    shutdown(timeoutMs?: number): Promise<void>;
+    getTracer(): Tracer;
+    /**
+     * Get currently active span
+     */
+    getActiveSpan(): Span | undefined;
+    /**
+     * Check if content capture is enabled
+     */
+    shouldCaptureContent(): boolean;
+    /**
+     * Trace an agent invocation
+     */
+    traceAgentInvocation(agent: {
+        name: string;
+        description?: string;
+    }, invocationContext: InvocationContext, input?: string | Record<string, any>, output?: string | Record<string, any>): void;
     /**
-     * Traces a tool call by adding detailed attributes to the current span.
+     * Trace a tool call
      */
     traceToolCall(tool: BaseTool, args: Record<string, any>, functionResponseEvent: Event, llmRequest?: LlmRequest, invocationContext?: InvocationContext): void;
     /**
-     * Traces a call to the LLM by adding detailed attributes to the current span.
+     * Trace an LLM call
      */
     traceLlmCall(invocationContext: InvocationContext, eventId: string, llmRequest: LlmRequest, llmResponse: LlmResponse): void;
     /**
-     * Wraps an async generator with tracing
+     * Wrap an async generator with tracing
      */
-    traceAsyncGenerator<T>(spanName: string, generator: AsyncGenerator<T, void, unknown>): AsyncGenerator<T, void, unknown>;
-    private _safeJsonStringify;
+    traceAsyncGenerator<T>(spanName: string, generator: AsyncGenerator<T, void, unknown>, attributes?: Record<string, any>): AsyncGenerator<T, void, unknown>;
     /**
-     * Builds a dictionary representation of the LLM request for tracing.
-     *
-     * This function prepares a dictionary representation of the LlmRequest
-     * object, suitable for inclusion in a trace. It excludes fields that cannot
-     * be serialized (e.g., function pointers) and avoids sending bytes data.
+     * Execute a function within a traced span
+     */
+    withSpan<T>(spanName: string, fn: (span: Span) => Promise<T>, attributes?: Record<string, any>): Promise<T>;
+    /**
+     * Set attributes on the active span
+     */
+    setActiveSpanAttributes(attributes: Record<string, any>): void;
+    /**
+     * Record an exception on the active span
+     */
+    recordException(error: Error, attributes?: Record<string, any>): void;
+    /**
+     * Add an event to the active span
+     */
+    addEvent(name: string, attributes?: Record<string, any>): void;
+    /**
+     * Trace a callback execution
+     */
+    traceCallback(callbackType: string, callbackName: string | undefined, callbackIndex: number, invocationContext?: InvocationContext): void;
+    /**
+     * Trace an agent transfer
+     */
+    traceAgentTransfer(sourceAgent: string, targetAgent: string, transferChain: string[], transferDepth: number, reason?: string, invocationContext?: InvocationContext): void;
+    /**
+     * Record enhanced tool execution attributes
+     */
+    traceEnhancedTool(executionOrder?: number, parallelGroup?: string, retryCount?: number, isCallbackOverride?: boolean): void;
+    /**
+     * Record enhanced LLM attributes
+     */
+    traceEnhancedLlm(streaming?: boolean, timeToFirstTokenMs?: number, chunkCount?: number, cachedTokens?: number, contextWindowUsedPct?: number): void;
+    /**
+     * Record standardized error information
+     */
+    traceError(error: Error, category: "tool_error" | "model_error" | "transfer_error" | "callback_error" | "memory_error" | "session_error" | "plugin_error" | "unknown_error", recoverable?: boolean, retryRecommended?: boolean): void;
+    /**
+     * Trace memory operations
+     */
+    traceMemoryOperation(operation: "search" | "insert" | "delete", sessionId: string, query?: string, resultsCount?: number, invocationContext?: InvocationContext): void;
+    /**
+     * Trace plugin hook execution
      */
-    private _buildLlmRequestForTrace;
+    tracePluginHook(pluginName: string, hook: string, agentName?: string, invocationContext?: InvocationContext): void;
     /**
-     * Excludes non-serializable fields from config, similar to Python's exclude logic
+     * Record an agent invocation
      */
-    private _excludeNonSerializableFromConfig;
+    recordAgentInvocation(dimensions: AgentMetricDimensions): void;
+    /**
+     * Record agent duration
+     */
+    recordAgentDuration(durationMs: number, dimensions: AgentMetricDimensions): void;
+    /**
+     * Record a tool execution
+     */
+    recordToolExecution(dimensions: ToolMetricDimensions): void;
+    /**
+     * Record tool duration
+     */
+    recordToolDuration(durationMs: number, dimensions: ToolMetricDimensions): void;
+    /**
+     * Record an LLM call
+     */
+    recordLlmCall(dimensions: LlmMetricDimensions): void;
+    /**
+     * Record LLM duration
+     */
+    recordLlmDuration(durationMs: number, dimensions: LlmMetricDimensions): void;
+    /**
+     * Record LLM token usage
+     */
+    recordLlmTokens(inputTokens: number, outputTokens: number, dimensions: LlmMetricDimensions): void;
+    /**
+     * Record an error
+     */
+    recordError(errorType: "agent" | "tool" | "llm", context: string): void;
+    /**
+     * Flush all pending telemetry data
+     */
+    flush(timeoutMs?: number): Promise<void>;
+    /**
+     * Shutdown telemetry system
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
 }
 declare const telemetryService: TelemetryService;
 declare const tracer: Tracer;
-declare const initializeTelemetry: (config: TelemetryConfig) => void;
+declare const initializeTelemetry: (config: TelemetryConfig) => Promise<void>;
 declare const shutdownTelemetry: (timeoutMs?: number) => Promise<void>;
+declare const traceAgentInvocation: (agent: {
+    name: string;
+    description?: string;
+}, invocationContext: InvocationContext, input?: string | Record<string, any>, output?: string | Record<string, any>) => void;
 declare const traceToolCall: (tool: BaseTool, args: Record<string, any>, functionResponseEvent: Event, llmRequest?: LlmRequest, invocationContext?: InvocationContext) => void;
 declare const traceLlmCall: (invocationContext: InvocationContext, eventId: string, llmRequest: LlmRequest, llmResponse: LlmResponse) => void;
+declare const recordAgentInvocation: (dimensions: AgentMetricDimensions) => void;
+declare const recordToolExecution: (dimensions: ToolMetricDimensions) => void;
+declare const recordLlmCall: (dimensions: LlmMetricDimensions) => void;
 
 declare const VERSION = "0.1.0";
 
-export { AF_FUNCTION_CALL_ID_PREFIX, type AfterAgentCallback, type AfterModelCallback, type AfterToolCallback, LlmAgent as Agent, AgentBuilder, type AgentBuilderConfig, type AgentBuilderWithSchema, AgentEvaluator, AgentTool, type AgentToolConfig, type AgentType, index$4 as Agents, AiSdkLlm, AnthropicLlm, ApiKeyCredential, ApiKeyScheme, AuthConfig, AuthCredential, AuthCredentialType, AuthHandler, AuthScheme, AuthSchemeType, AuthTool, type AuthToolArguments, AutoFlow, BaseAgent, type BaseAgentType, BaseCodeExecutor, type BaseCodeExecutorConfig, BaseLLMConnection, BaseLlm, BaseLlmFlow, BaseLlmRequestProcessor, BaseLlmResponseProcessor, type BaseMemoryService, BasePlanner, BasePlugin, BaseSessionService, BaseTool, BasicAuthCredential, BearerTokenCredential, type BeforeAgentCallback, type BeforeModelCallback, type BeforeToolCallback, type BuildFunctionDeclarationOptions, type BuiltAgent, BuiltInCodeExecutor, BuiltInPlanner, CallbackContext, type CodeExecutionInput, type CodeExecutionResult, CodeExecutionUtils, CodeExecutorContext, type CreateToolConfig, type CreateToolConfigWithSchema, type CreateToolConfigWithoutSchema, DatabaseSessionService, EnhancedAuthConfig, type EnhancedRunner, type EvalCase, type EvalCaseResult, type EvalMetric, type EvalMetricResult, type EvalMetricResultPerInvocation, EvalResult, type EvalSet, type EvalSetResult, EvalStatus, type EvaluateConfig, index$3 as Evaluation, type EvaluationResult, Evaluator, Event, EventActions, type EventCompaction, index$7 as Events, type EventsCompactionConfig, type EventsSummarizer, ExitLoopTool, type File, FileOperationsTool, FinalResponseMatchV2Evaluator, index$2 as Flows, type FullMessage, FunctionTool, GcsArtifactService, type GetSessionConfig, GetUserChoiceTool, GoogleLlm, GoogleSearch, HttpRequestTool, HttpScheme, InMemoryArtifactService, InMemoryMemoryService, InMemoryRunner, InMemorySessionService, type InstructionProvider, type IntermediateData, type Interval, type Invocation, InvocationContext, type JudgeModelOptions, LLMRegistry, LangGraphAgent, type LangGraphAgentConfig, type LangGraphNode, LangfusePlugin, type LangfusePluginOptions, type ListSessionsResponse, LlmAgent, type LlmAgentConfig, LlmCallsLimitExceededError, LlmEventSummarizer, type LlmModel, type LlmModelConfig, LlmRequest, LlmResponse, LoadArtifactsTool, LoadMemoryTool, LocalEvalService, LoopAgent, type LoopAgentConfig, McpAbi, McpAtp, McpBamm, McpCoinGecko, McpCoinGeckoPro, type McpConfig, McpDiscord, McpError, McpErrorType, McpFilesystem, McpFraxlend, McpGeneric, McpIqWiki, McpMemory, McpNearAgent, McpNearIntents, McpOdos, McpPolymarket, McpSamplingHandler, type McpSamplingRequest, type McpSamplingResponse, type McpServerConfig, McpTelegram, McpToolset, type McpTransportType, McpUpbit, index$1 as Memory, type MessagePart, type MetricInfo, type MetricValueInfo, index$5 as Models, type MultiAgentResponse, OAuth2Credential, OAuth2Scheme, type OAuthFlow, type OAuthFlows, OpenAiLlm, OpenIdConnectScheme, ParallelAgent, type ParallelAgentConfig, type ParsedArtifactUri, type PerInvocationResult, type PerToolFailuresCounter, PlanReActPlanner, type PluginCallbackName, PluginManager, PrebuiltMetrics, REFLECT_AND_RETRY_RESPONSE_TYPE, REQUEST_EUC_FUNCTION_CALL_NAME, ReadonlyContext, ReflectAndRetryToolPlugin, type ReflectAndRetryToolPluginOptions, RougeEvaluator, RunConfig, Runner, type RunnerAskReturn, SafetyEvaluatorV1, type SamplingHandler, type SearchMemoryResponse, SequentialAgent, type SequentialAgentConfig, type Session, type SessionInput, type SessionOptions, index as Sessions, type SingleAfterModelCallback, type SingleAfterToolCallback, type SingleAgentCallback, type SingleBeforeModelCallback, type SingleBeforeToolCallback, SingleFlow, State, StreamingMode, type TelemetryConfig, TelemetryService, type ThinkingConfig, type ToolConfig, ToolContext, type ToolFailureResponse, type ToolUnion, index$6 as Tools, TrackingScope, TrajectoryEvaluator, TransferToAgentTool, UserInteractionTool, VERSION, VertexAiRagMemoryService, VertexAiSessionService, _findFunctionCallEventIfLastEventIsFunctionResponse, adkToMcpToolType, requestProcessor$2 as agentTransferRequestProcessor, requestProcessor$6 as basicRequestProcessor, buildFunctionDeclaration, requestProcessor as codeExecutionRequestProcessor, responseProcessor as codeExecutionResponseProcessor, requestProcessor$3 as contentRequestProcessor, convertMcpToolToBaseTool, createAuthToolArguments, createBranchContextForSubAgent, createDatabaseSessionService, createFunctionTool, createMysqlSessionService, createPostgresSessionService, createSamplingHandler, createSqliteSessionService, createTool, generateAuthEvent, generateClientFunctionCallId, getArtifactUri, getLongRunningFunctionCalls, getMcpTools, handleFunctionCallsAsync, handleFunctionCallsLive, requestProcessor$5 as identityRequestProcessor, initializeTelemetry, injectSessionState, requestProcessor$4 as instructionsRequestProcessor, isArtifactRef, isEnhancedAuthConfig, jsonSchemaToDeclaration, mcpSchemaToParameters, mergeAgentRun, mergeParallelFunctionResponseEvents, newInvocationContextId, requestProcessor$1 as nlPlanningRequestProcessor, responseProcessor$1 as nlPlanningResponseProcessor, normalizeJsonSchema, parseArtifactUri, pluginCallbackNameSchema, populateClientFunctionCallId, registerProviders, removeClientFunctionCallId, requestProcessor$7 as requestProcessor, runCompactionForSlidingWindow, shutdownTelemetry, telemetryService, traceLlmCall, traceToolCall, tracer };
+export { ADK_ATTRS, ADK_SYSTEM_NAME, AF_FUNCTION_CALL_ID_PREFIX, type AfterAgentCallback, type AfterModelCallback, type AfterToolCallback, LlmAgent as Agent, AgentBuilder, type AgentBuilderConfig, type AgentBuilderWithSchema, AgentEvaluator, type AgentMetricDimensions, type AgentSpanAttributes, AgentTool, type AgentToolConfig, type AgentType, index$4 as Agents, AiSdkLlm, AnthropicLlm, ApiKeyCredential, ApiKeyScheme, AuthConfig, AuthCredential, AuthCredentialType, AuthHandler, AuthScheme, AuthSchemeType, AuthTool, type AuthToolArguments, AutoFlow, BaseAgent, type BaseAgentType, BaseCodeExecutor, type BaseCodeExecutorConfig, BaseLLMConnection, BaseLlm, BaseLlmFlow, BaseLlmRequestProcessor, BaseLlmResponseProcessor, type BaseMemoryService, BasePlanner, BasePlugin, BaseSessionService, BaseTool, BasicAuthCredential, BearerTokenCredential, type BeforeAgentCallback, type BeforeModelCallback, type BeforeToolCallback, type BuildFunctionDeclarationOptions, type BuiltAgent, BuiltInCodeExecutor, BuiltInPlanner, CallbackContext, type CodeExecutionInput, type CodeExecutionResult, CodeExecutionUtils, CodeExecutorContext, type CreateToolConfig, type CreateToolConfigWithSchema, type CreateToolConfigWithoutSchema, DEFAULTS, DatabaseSessionService, ENV_VARS, EnhancedAuthConfig, type EnhancedLlmSpanAttributes, type EnhancedRunner, type EnhancedToolSpanAttributes, type ErrorSpanAttributes, type EvalCase, type EvalCaseResult, type EvalMetric, type EvalMetricResult, type EvalMetricResultPerInvocation, EvalResult, type EvalSet, type EvalSetResult, EvalStatus, type EvaluateConfig, index$3 as Evaluation, type EvaluationResult, Evaluator, Event, EventActions, type EventCompaction, index$7 as Events, type EventsCompactionConfig, type EventsSummarizer, ExitLoopTool, type File, FileOperationsTool, FinalResponseMatchV2Evaluator, index$2 as Flows, type FullMessage, FunctionTool, GcsArtifactService, type GetSessionConfig, GetUserChoiceTool, GoogleLlm, GoogleSearch, HttpRequestTool, HttpScheme, InMemoryArtifactService, InMemoryMemoryService, InMemoryRunner, InMemorySessionService, type InstructionProvider, type IntermediateData, type Interval, type Invocation, InvocationContext, type JudgeModelOptions, LLMRegistry, LangGraphAgent, type LangGraphAgentConfig, type LangGraphNode, LangfusePlugin, type LangfusePluginOptions, type ListSessionsResponse, LlmAgent, type LlmAgentConfig, LlmCallsLimitExceededError, LlmEventSummarizer, type LlmMetricDimensions, type LlmModel, type LlmModelConfig, LlmRequest, LlmResponse, type LlmSpanAttributes, LoadArtifactsTool, LoadMemoryTool, LocalEvalService, LoopAgent, type LoopAgentConfig, METRICS, McpAbi, McpAtp, McpBamm, McpCoinGecko, McpCoinGeckoPro, type McpConfig, McpDiscord, McpError, McpErrorType, McpFilesystem, McpFraxlend, McpGeneric, McpIqWiki, McpMemory, McpNearAgent, McpNearIntents, McpOdos, McpPolymarket, McpSamplingHandler, type McpSamplingRequest, type McpSamplingResponse, type McpServerConfig, McpTelegram, McpToolset, type McpTransportType, McpUpbit, index$1 as Memory, type MessagePart, type MetricInfo, type MetricValueInfo, index$5 as Models, type MultiAgentResponse, OAuth2Credential, OAuth2Scheme, type OAuthFlow, type OAuthFlows, OPERATIONS, OpenAiLlm, OpenIdConnectScheme, ParallelAgent, type ParallelAgentConfig, type ParsedArtifactUri, type PerInvocationResult, type PerToolFailuresCounter, PlanReActPlanner, type PluginCallbackName, PluginManager, PrebuiltMetrics, REFLECT_AND_RETRY_RESPONSE_TYPE, REQUEST_EUC_FUNCTION_CALL_NAME, ReadonlyContext, ReflectAndRetryToolPlugin, type ReflectAndRetryToolPluginOptions, RougeEvaluator, RunConfig, Runner, type RunnerAskReturn, SEMCONV, SafetyEvaluatorV1, type SamplingHandler, type SearchMemoryResponse, SequentialAgent, type SequentialAgentConfig, type Session, type SessionInput, type SessionOptions, index as Sessions, type SingleAfterModelCallback, type SingleAfterToolCallback, type SingleAgentCallback, type SingleBeforeModelCallback, type SingleBeforeToolCallback, SingleFlow, State, StreamingMode, type TelemetryConfig, TelemetryService, type TelemetryStats, type ThinkingConfig, type ToolConfig, ToolContext, type ToolFailureResponse, type ToolMetricDimensions, type ToolSpanAttributes, type ToolUnion, index$6 as Tools, type TraceAgentParams, type TraceAgentTransferParams, type TraceCallbackParams, type TraceLlmParams, type TraceMemoryParams, type TracePluginParams, type TraceSessionParams, type TraceToolParams, TrackingScope, TrajectoryEvaluator, type TransferContext, TransferToAgentTool, UserInteractionTool, VERSION, VertexAiRagMemoryService, VertexAiSessionService, _findFunctionCallEventIfLastEventIsFunctionResponse, adkToMcpToolType, requestProcessor$2 as agentTransferRequestProcessor, requestProcessor$6 as basicRequestProcessor, buildFunctionDeclaration, buildLlmRequestForTrace, buildLlmResponseForTrace, requestProcessor as codeExecutionRequestProcessor, responseProcessor as codeExecutionResponseProcessor, requestProcessor$3 as contentRequestProcessor, convertMcpToolToBaseTool, createAuthToolArguments, createBranchContextForSubAgent, createDatabaseSessionService, createFunctionTool, createMysqlSessionService, createPostgresSessionService, createSamplingHandler, createSqliteSessionService, createTool, extractTextFromContent, formatSpanAttributes, generateAuthEvent, generateClientFunctionCallId, getArtifactUri, getEnvironment, getLongRunningFunctionCalls, getMcpTools, handleFunctionCallsAsync, handleFunctionCallsLive, requestProcessor$5 as identityRequestProcessor, initializeTelemetry, injectSessionState, requestProcessor$4 as instructionsRequestProcessor, isArtifactRef, isEnhancedAuthConfig, jsonSchemaToDeclaration, mcpSchemaToParameters, mergeAgentRun, mergeParallelFunctionResponseEvents, newInvocationContextId, requestProcessor$1 as nlPlanningRequestProcessor, responseProcessor$1 as nlPlanningResponseProcessor, normalizeJsonSchema, parseArtifactUri, pluginCallbackNameSchema, populateClientFunctionCallId, recordAgentInvocation, recordLlmCall, recordToolExecution, registerProviders, removeClientFunctionCallId, requestProcessor$7 as requestProcessor, runCompactionForSlidingWindow, safeJsonStringify, shouldCaptureContent, shutdownTelemetry, telemetryService, traceAgentInvocation, traceLlmCall, traceToolCall, tracer };