@strands-agents/sdk 0.5.0 → 0.6.0

package/dist/src/telemetry/config.js

@@ -1,14 +1,30 @@
 /**
  * OpenTelemetry configuration and setup utilities for Strands agents.
  *
- * This module provides centralized configuration and initialization functionality
- * for OpenTelemetry components and other telemetry infrastructure shared across Strands applications.
+ * Uses NodeTracerProvider when available for async context propagation
+ * across MCP server boundaries. Falls back to BasicTracerProvider in
+ * environments without async_hooks support.
+ *
+ * @see https://github.com/strands-agents/sdk-typescript/issues/447
  */
+import { trace } from '@opentelemetry/api';
 import { Resource, envDetectorSync } from '@opentelemetry/resources';
-import { NodeTracerProvider, ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
-import { SimpleSpanProcessor, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { BasicTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor, BatchSpanProcessor, } from '@opentelemetry/sdk-trace-base';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 import { logger } from '../logging/index.js';
+let DefaultTracerProvider = BasicTracerProvider;
+if (typeof globalThis.process?.getBuiltinModule === 'function') {
+    try {
+        const nodeModule = globalThis.process.getBuiltinModule('node:module');
+        if (nodeModule) {
+            const req = nodeModule.createRequire(import.meta.url);
+            DefaultTracerProvider = req('@opentelemetry/sdk-trace-node').NodeTracerProvider;
+        }
+    }
+    catch {
+        logger.info('sdk-trace-node not available; using BasicTracerProvider without async context propagation');
+    }
+}
 const DEFAULT_SERVICE_NAME = 'strands-agents';
 const DEFAULT_SERVICE_NAMESPACE = 'strands';
 const DEFAULT_DEPLOYMENT_ENVIRONMENT = 'development';
@@ -20,27 +36,46 @@ const DEFAULT_DEPLOYMENT_ENVIRONMENT = 'development';
 export function getServiceName() {
     return globalThis?.process?.env?.OTEL_SERVICE_NAME || DEFAULT_SERVICE_NAME;
 }
+/**
+ * Get an OpenTelemetry Tracer instance.
+ *
+ * Wraps the OTel trace API to provide a consistent tracer scoped to the
+ * configured service name.
+ *
+ * @returns An OTel Tracer instance from the global tracer provider
+ *
+ * @example
+ * ```typescript
+ * import { telemetry } from '@strands-agents/sdk'
+ *
+ * // Set up telemetry first (or register your own NodeTracerProvider)
+ * telemetry.setupTracer({ exporters: { otlp: true } })
+ *
+ * // Get a tracer and create custom spans
+ * const tracer = telemetry.getTracer()
+ * const span = tracer.startSpan('my-custom-operation')
+ * span.setAttribute('custom.key', 'value')
+ *
+ * // ........
+ *
+ * span.end()
+ * ```
+ */
+export function getTracer() {
+    return trace.getTracer(getServiceName());
+}
 let _provider = null;
 /**
  * Set up the tracer provider with the given configuration.
  *
  * @param config - Tracer configuration options
- * @returns The configured NodeTracerProvider
+ * @returns The configured tracer provider
  *
  * @example
  * ```typescript
- * import { telemetry } from '@strands-agents/sdk'
- *
- * // Simple setup with defaults
- * const provider = telemetry.setupTracer({
- *   exporters: { otlp: true }
- * })
+ * import { telemetry } from '\@strands-agents/sdk'
  *
- * // Custom provider
- * telemetry.setupTracer({
- *   provider: new NodeTracerProvider({ resource: myResource }),
- *   exporters: { otlp: true, console: true }
- * })
+ * telemetry.setupTracer({ exporters: { otlp: true } })
  * ```
  */
 export function setupTracer(config = {}) {
@@ -48,23 +83,21 @@ export function setupTracer(config = {}) {
         logger.warn('tracer provider already initialized, returning existing provider');
         return _provider;
     }
-    // Use provided provider or create default
-    _provider = config.provider ?? new NodeTracerProvider({ resource: getOtelResource() });
-    // Add exporters if requested
+    _provider = config.provider ?? new DefaultTracerProvider({ resource: getOtelResource() });
     if (config.exporters?.otlp)
         addOtlpExporter(_provider);
     if (config.exporters?.console)
         addConsoleExporter(_provider);
-    // register() sets up global tracer provider, context manager, and propagators
     _provider.register();
-    // Flush pending spans on exit for short-lived scripts using BatchSpanProcessor
-    process.once('beforeExit', () => {
-        if (_provider) {
-            _provider.forceFlush().catch((err) => {
-                logger.warn(`error=<${err}> | failed to flush tracer provider on exit`);
-            });
-        }
-    });
+    if (typeof globalThis?.process?.once === 'function') {
+        globalThis.process.once('beforeExit', () => {
+            if (_provider) {
+                _provider.forceFlush().catch((err) => {
+                    logger.warn(`error=<${err}> | failed to flush tracer provider on exit`);
+                });
+            }
+        });
+    }
     return _provider;
 }
 function addOtlpExporter(provider) {
@@ -85,8 +118,8 @@ function addConsoleExporter(provider) {
 }
 function getOtelResource() {
     const serviceName = getServiceName();
-    const serviceNamespace = process.env.OTEL_SERVICE_NAMESPACE || DEFAULT_SERVICE_NAMESPACE;
-    const deploymentEnvironment = process.env.OTEL_DEPLOYMENT_ENVIRONMENT || DEFAULT_DEPLOYMENT_ENVIRONMENT;
+    const serviceNamespace = globalThis?.process?.env?.OTEL_SERVICE_NAMESPACE || DEFAULT_SERVICE_NAMESPACE;
+    const deploymentEnvironment = globalThis?.process?.env?.OTEL_DEPLOYMENT_ENVIRONMENT || DEFAULT_DEPLOYMENT_ENVIRONMENT;
     const defaultResource = new Resource({
         'service.name': serviceName,
         'service.namespace': serviceNamespace,
@@ -94,7 +127,6 @@ function getOtelResource() {
         'telemetry.sdk.name': 'opentelemetry',
         'telemetry.sdk.language': 'typescript',
     });
-    // Merge with OTEL_RESOURCE_ATTRIBUTES env var (env attrs take precedence)
     const envResource = envDetectorSync.detect();
     return defaultResource.merge(envResource);
 }

package/dist/src/telemetry/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/telemetry/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/telemetry/config.ts"],"names":[],"mappings":"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"}

package/dist/src/telemetry/index.d.ts

@@ -29,6 +29,6 @@
  * const agent = new Agent()
  * ```
  */
-export { setupTracer } from './config.js';
+export { setupTracer, getTracer } from './config.js';
 export type { TracerConfig } from './config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/telemetry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA"}

package/dist/src/telemetry/index.js

@@ -29,5 +29,5 @@
  * const agent = new Agent()
  * ```
  */
-export { setupTracer } from './config.js';
+export { setupTracer, getTracer } from './config.js';
 //# sourceMappingURL=index.js.map

package/dist/src/telemetry/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA"}

package/dist/src/telemetry/meter.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Agent loop metrics tracking.
+ *
+ * The {@link Meter} accumulates local metrics during agent invocation and
+ * provides them as a read-only {@link AgentMetrics} snapshot via the
+ * {@link Meter.metrics} getter for inclusion in {@link AgentResult}.
+ */
+import type { Usage, Metrics, ModelMetadataEventData } from '../models/streaming.js';
+import type { ToolUse } from '../tools/types.js';
+import type { JSONSerializable } from '../types/json.js';
+/**
+ * Per-tool execution metrics.
+ */
+export interface ToolMetricsData {
+    /**
+     * Total number of calls to this tool.
+     */
+    callCount: number;
+    /**
+     * Number of successful calls.
+     */
+    successCount: number;
+    /**
+     * Number of failed calls.
+     */
+    errorCount: number;
+    /**
+     * Total execution time in milliseconds.
+     */
+    totalTime: number;
+}
+/**
+ * Per-cycle usage tracking.
+ */
+export interface AgentLoopMetricsData {
+    /**
+     * Unique identifier for this cycle.
+     */
+    cycleId: string;
+    /**
+     * Duration of this cycle in milliseconds.
+     */
+    duration: number;
+    /**
+     * Token usage for this cycle.
+     */
+    usage: Usage;
+}
+/**
+ * Per-invocation metrics tracking.
+ */
+export interface InvocationMetricsData {
+    /**
+     * Cycle metrics for this invocation.
+     */
+    cycles: AgentLoopMetricsData[];
+    /**
+     * Accumulated token usage for this invocation.
+     */
+    usage: Usage;
+}
+/**
+ * JSON-serializable representation of AgentMetrics.
+ */
+export interface AgentMetricsData {
+    /**
+     * Number of agent loop cycles executed.
+     */
+    cycleCount: number;
+    /**
+     * Accumulated token usage across all model invocations.
+     */
+    accumulatedUsage: Usage;
+    /**
+     * Accumulated performance metrics across all model invocations.
+     */
+    accumulatedMetrics: Metrics;
+    /**
+     * Per-invocation metrics.
+     */
+    agentInvocations: InvocationMetricsData[];
+    /**
+     * Per-tool execution metrics keyed by tool name.
+     */
+    toolMetrics: Record<string, ToolMetricsData>;
+}
+/**
+ * Options for recording tool usage.
+ */
+interface ToolUsageOptions {
+    /**
+     * The tool that was used.
+     */
+    tool: ToolUse;
+    /**
+     * Execution duration in milliseconds.
+     */
+    duration: number;
+    /**
+     * Whether the tool call succeeded.
+     */
+    success: boolean;
+}
+/**
+ * Read-only snapshot of aggregated agent metrics.
+ *
+ * Returned by {@link Meter.metrics} and stored on {@link AgentResult}.
+ * Provides access to cycle counts, tool usage, token consumption,
+ * and per-invocation breakdowns. Supports serialization via {@link toJSON}.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.invoke('Hello')
+ * console.log(result.metrics.cycleCount)
+ * console.log(result.metrics.totalDuration)
+ * console.log(result.metrics.accumulatedData)
+ * console.log(result.metrics.toolMetrics)
+ * console.log(JSON.stringify(result.metrics))
+ * ```
+ */
+export declare class AgentMetrics implements JSONSerializable<AgentMetricsData> {
+    /**
+     * Number of agent loop cycles executed.
+     */
+    readonly cycleCount: number;
+    /**
+     * Accumulated token usage across all model invocations.
+     */
+    readonly accumulatedUsage: Usage;
+    /**
+     * Accumulated performance metrics across all model invocations.
+     */
+    readonly accumulatedMetrics: Metrics;
+    /**
+     * Per-invocation metrics.
+     */
+    readonly agentInvocations: InvocationMetricsData[];
+    /**
+     * Per-tool execution metrics keyed by tool name.
+     */
+    readonly toolMetrics: Record<string, ToolMetricsData>;
+    constructor(data?: Partial<AgentMetricsData>);
+    /**
+     * The most recent agent invocation, or undefined if none exist.
+     */
+    get latestAgentInvocation(): InvocationMetricsData | undefined;
+    /**
+     * Accumulated usage and performance metrics across all model invocations.
+     */
+    get accumulatedData(): {
+        usage: Usage;
+        metrics: Metrics;
+    };
+    /**
+     * Total duration of all cycles in milliseconds.
+     */
+    get totalDuration(): number;
+    /**
+     * Average cycle duration in milliseconds, or 0 if no cycles exist.
+     */
+    get averageCycleTime(): number;
+    /**
+     * Per-tool execution statistics with computed averages and rates.
+     */
+    get toolUsage(): Record<string, ToolMetricsData & {
+        averageTime: number;
+        successRate: number;
+    }>;
+    /**
+     * Returns a JSON-serializable representation of all collected metrics.
+     * Called automatically by JSON.stringify().
+     *
+     * @returns A plain object suitable for round-trip serialization
+     */
+    toJSON(): AgentMetricsData;
+}
+/**
+ * Accumulates local metrics during agent invocation.
+ *
+ * Tracks cycle counts, token usage, tool execution stats, and model latency.
+ * Use the {@link metrics} getter to obtain a read-only {@link AgentMetrics}
+ * snapshot for inclusion in {@link AgentResult}.
+ *
+ */
+export declare class Meter {
+    /**
+     * Number of agent loop cycles executed.
+     */
+    private _cycleCount;
+    /**
+     * Accumulated token usage across all model invocations.
+     */
+    private readonly _accumulatedUsage;
+    /**
+     * Accumulated performance metrics across all model invocations.
+     */
+    private readonly _accumulatedMetrics;
+    /**
+     * Per-invocation metrics.
+     */
+    private readonly _agentInvocations;
+    /**
+     * Per-tool execution metrics keyed by tool name.
+     */
+    private readonly _toolMetrics;
+    /**
+     * Begin tracking a new agent invocation.
+     * Creates a new InvocationMetricsData entry for per-invocation metrics.
+     */
+    startNewInvocation(): void;
+    /**
+     * Start a new agent loop cycle.
+     *
+     * @returns The cycle id and start time
+     */
+    startCycle(): {
+        cycleId: string;
+        startTime: number;
+    };
+    /**
+     * End the current agent loop cycle and record its duration.
+     *
+     * @param startTime - The timestamp when the cycle started (milliseconds since epoch)
+     */
+    endCycle(startTime: number): void;
+    /**
+     * Record metrics for a completed tool invocation.
+     *
+     * @param options - Tool usage recording options
+     */
+    endToolCall(options: ToolUsageOptions): void;
+    /**
+     * Update loop-level metrics from a model response.
+     *
+     * Call this after each model invocation within a cycle to
+     * accumulate usage and latency.
+     *
+     * @param metadata - The metadata event from a model invocation, or undefined if unavailable
+     */
+    updateCycle(metadata?: ModelMetadataEventData): void;
+    /**
+     * Read-only snapshot of the accumulated metrics.
+     * Returns an AgentMetrics instance suitable for inclusion in AgentResult.
+     */
+    get metrics(): AgentMetrics;
+    /**
+     * The most recent agent invocation, or undefined if none exist.
+     */
+    private get _latestAgentInvocation();
+    /**
+     * Update accumulated usage and metrics from a model metadata event.
+     *
+     * @param metadata - The metadata event from a model invocation
+     */
+    private _updateFromMetadata;
+    /**
+     * Update the accumulated token usage with new usage data.
+     *
+     * @param usage - The usage data to accumulate
+     */
+    private _updateUsage;
+    /**
+     * Creates an empty Usage object with all counters set to zero.
+     *
+     * @returns A Usage object with zeroed counters
+     */
+    private static _createEmptyUsage;
+    /**
+     * Accumulates token usage from a source into a target Usage object.
+     *
+     * @param target - The Usage object to accumulate into (mutated in place)
+     * @param source - The Usage object to accumulate from
+     */
+    private static _accumulateUsage;
+}
+export {};
+//# sourceMappingURL=meter.d.ts.map

package/dist/src/telemetry/meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.d.ts","sourceRoot":"","sources":["../../../src/telemetry/meter.ts"],"names":[],"mappings":"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"}