@strands-agents/sdk 0.4.0 → 0.5.0

package/dist/src/agent/agent.d.ts

@@ -1,11 +1,13 @@
 import { AgentResult, type AgentStreamEvent, type ContentBlock, type ContentBlockData, type JSONValue, McpClient, Message, type MessageData, type SystemPrompt, type SystemPromptData, type Tool } from '../index.js';
-import type { BaseModelConfig, Model } from '../models/model.js';
+import { Model } from '../models/model.js';
+import type { BaseModelConfig } from '../models/model.js';
 import { ToolRegistry } from '../registry/tool-registry.js';
-import { AgentState } from './state.js';
+import { AppState } from '../app-state.js';
 import type { AgentData } from '../types/agent.js';
 import type { HookProvider } from '../hooks/types.js';
 import { HookRegistryImplementation } from '../hooks/registry.js';
 import type { z } from 'zod';
+import type { AttributeValue } from '@opentelemetry/api';
 /**
  * Recursive type definition for nested tool arrays.
  * Allows tools to be organized in nested arrays of any depth.
@@ -71,6 +73,20 @@ export type AgentConfig = {
      * Zod schema for structured output validation.
      */
     structuredOutputSchema?: z.ZodSchema;
+    /**
+     * Custom trace attributes to include in all spans.
+     * These attributes are merged with standard attributes in telemetry spans.
+     * Telemetry must be enabled globally via telemetry.setupTracer() for these to take effect.
+     */
+    traceAttributes?: Record<string, AttributeValue>;
+    /**
+     * Optional name for the agent. Defaults to "Strands Agent".
+     */
+    name?: string;
+    /**
+     * Optional unique identifier for the agent. Defaults to "default".
+     */
+    agentId?: string;
 };
 /**
  * Arguments for invoking an agent.
@@ -81,6 +97,15 @@ export type AgentConfig = {
  * - `Message[]` | `MessageData[]` - Array of messages (appends all to conversation)
  */
 export type InvokeArgs = string | ContentBlock[] | ContentBlockData[] | Message[] | MessageData[];
+/**
+ * Options for a single agent invocation.
+ */
+export interface InvokeOptions {
+    /**
+     * Zod schema for structured output validation, overriding the constructor-provided schema for this invocation only.
+     */
+    structuredOutputSchema?: z.ZodSchema;
+}
 /**
  * Orchestrates the interaction between a model, a set of tools, and MCP clients.
  * The Agent is responsible for managing the lifecycle of tools and clients
@@ -92,10 +117,10 @@ export declare class Agent implements AgentData {
      */
     readonly messages: Message[];
     /**
-     * Agent state storage accessible to tools and application logic.
+     * App state storage accessible to tools and application logic.
      * State is not passed to the model during inference.
      */
-    readonly state: AgentState;
+    readonly state: AppState;
     /**
      * Conversation manager for handling message history and context overflow.
      */
@@ -113,12 +138,24 @@ export declare class Agent implements AgentData {
      * The system prompt to pass to the model provider.
      */
     systemPrompt?: SystemPrompt;
+    /**
+     * The name of the agent.
+     */
+    readonly name: string;
+    /**
+     * The unique identifier of the agent instance.
+     */
+    readonly agentId: string;
     private _toolRegistry;
     private _mcpClients;
     private _initialized;
     private _isInvoking;
     private _printer?;
     private _structuredOutputSchema?;
+    /** Tracer instance for creating and managing OpenTelemetry spans. */
+    private _tracer;
+    /** Running total of token usage across all model invocations in the current invocation. */
+    private _accumulatedTokenUsage;
     /**
      * Creates an instance of the Agent.
      * @param config - The configuration for the agent.
@@ -146,6 +183,7 @@ export declare class Agent implements AgentData {
      * streaming events.
      *
      * @param args - Arguments for invoking the agent
+     * @param options - Optional per-invocation options
      * @returns Promise that resolves to the final AgentResult
      *
      * @example
@@ -155,7 +193,7 @@ export declare class Agent implements AgentData {
      * console.log(result.lastMessage) // Agent's response
      * ```
      */
-    invoke(args: InvokeArgs): Promise<AgentResult>;
+    invoke(args: InvokeArgs, options?: InvokeOptions): Promise<AgentResult>;
     /**
      * Streams the agent execution, yielding events and returning the final result.
      *
@@ -173,6 +211,7 @@ export declare class Agent implements AgentData {
      * with valid toolResponses
      *
      * @param args - Arguments for invoking the agent
+     * @param options - Optional per-invocation options
      * @returns Async generator that yields AgentStreamEvent objects and returns AgentResult
      *
      * @example
@@ -185,12 +224,13 @@ export declare class Agent implements AgentData {
      * // Messages array is mutated in place and contains the full conversation
      * ```
      */
-    stream(args: InvokeArgs): AsyncGenerator<AgentStreamEvent, AgentResult, undefined>;
+    stream(args: InvokeArgs, options?: InvokeOptions): AsyncGenerator<AgentStreamEvent, AgentResult, undefined>;
     /**
      * Internal implementation of the agent streaming logic.
      * Separated to centralize printer event processing in the public stream method.
      *
      * @param args - Arguments for invoking the agent
+     * @param options - Optional per-invocation options
      * @returns Async generator that yields AgentStreamEvent objects and returns AgentResult
      */
     private _stream;
@@ -252,5 +292,18 @@ export declare class Agent implements AgentData {
      * @returns MessageAddedEvent to be yielded
      */
     private _appendMessage;
+    /**
+     * 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;
 }
 //# sourceMappingURL=agent.d.ts.map

package/dist/src/agent/agent.d.ts.map

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

package/dist/src/agent/agent.js

@@ -53,15 +53,21 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 import { AgentResult, BedrockModel, contentBlockFromData, McpClient, Message, TextBlock, ToolResultBlock, ToolUseBlock, } from '../index.js';
 import { systemPromptFromData } from '../types/messages.js';
 import { normalizeError, ConcurrentInvocationError, MaxTokensError } from '../errors.js';
+import { Model } from '../models/model.js';
 import { isModelStreamEvent } from '../models/streaming.js';
 import { ToolRegistry } from '../registry/tool-registry.js';
-import { AgentState } from './state.js';
+import { AppState } from '../app-state.js';
 import { AgentPrinter, getDefaultAppender } from './printer.js';
 import { SlidingWindowConversationManager } from '../conversation-manager/sliding-window-conversation-manager.js';
 import { HookRegistryImplementation } from '../hooks/registry.js';
 import { InitializedEvent, AfterInvocationEvent, AfterModelCallEvent, AfterToolCallEvent, AfterToolsEvent, BeforeInvocationEvent, BeforeModelCallEvent, BeforeToolCallEvent, BeforeToolsEvent, HookableEvent, MessageAddedEvent, ModelStreamUpdateEvent, ContentBlockEvent, ModelMessageEvent, ToolResultEvent, AgentResultEvent, ToolStreamUpdateEvent, } from '../hooks/events.js';
 import { createStructuredOutputContext } from '../structured-output/context.js';
 import { StructuredOutputException } from '../structured-output/exceptions.js';
+import { Tracer } from '../telemetry/tracer.js';
+/** Fallback name used when no agent name is provided in the config. */
+const DEFAULT_AGENT_NAME = 'Strands Agent';
+/** Fallback agent ID used when no agent ID is provided in the config. */
+const DEFAULT_AGENT_ID = 'default';
 /**
  * Orchestrates the interaction between a model, a set of tools, and MCP clients.
  * The Agent is responsible for managing the lifecycle of tools and clients
@@ -73,7 +79,7 @@ export class Agent {
      */
     messages;
     /**
-     * Agent state storage accessible to tools and application logic.
+     * App state storage accessible to tools and application logic.
      * State is not passed to the model during inference.
      */
     state;
@@ -94,12 +100,24 @@ export class Agent {
      * The system prompt to pass to the model provider.
      */
     systemPrompt;
+    /**
+     * The name of the agent.
+     */
+    name;
+    /**
+     * The unique identifier of the agent instance.
+     */
+    agentId;
     _toolRegistry;
     _mcpClients;
     _initialized;
     _isInvoking = false;
     _printer;
     _structuredOutputSchema;
+    /** Tracer instance for creating and managing OpenTelemetry spans. */
+    _tracer;
+    /** Running total of token usage across all model invocations in the current invocation. */
+    _accumulatedTokenUsage = Agent._createEmptyUsage();
     /**
      * Creates an instance of the Agent.
      * @param config - The configuration for the agent.
@@ -107,8 +125,10 @@ export class Agent {
     constructor(config) {
         // Initialize public fields
         this.messages = (config?.messages ?? []).map((msg) => (msg instanceof Message ? msg : Message.fromMessageData(msg)));
-        this.state = new AgentState(config?.state);
+        this.state = new AppState(config?.state);
         this.conversationManager = config?.conversationManager ?? new SlidingWindowConversationManager({ windowSize: 40 });
+        this.name = config?.name ?? DEFAULT_AGENT_NAME;
+        this.agentId = config?.agentId ?? DEFAULT_AGENT_ID;
         // Initialize hooks and register conversation manager hooks
         this.hooks = new HookRegistryImplementation();
         this.hooks.addHook(this.conversationManager);
@@ -132,6 +152,8 @@ export class Agent {
         }
         // Store structured output schema
         this._structuredOutputSchema = config?.structuredOutputSchema;
+        // Initialize tracer - OTEL returns no-op tracer if not configured
+        this._tracer = new Tracer(config?.traceAttributes);
         this._initialized = false;
     }
     async initialize() {
@@ -180,6 +202,7 @@ export class Agent {
      * streaming events.
      *
      * @param args - Arguments for invoking the agent
+     * @param options - Optional per-invocation options
      * @returns Promise that resolves to the final AgentResult
      *
      * @example
@@ -189,8 +212,8 @@ export class Agent {
      * console.log(result.lastMessage) // Agent's response
      * ```
      */
-    async invoke(args) {
-        const gen = this.stream(args);
+    async invoke(args, options) {
+        const gen = this.stream(args, options);
         let result = await gen.next();
         while (!result.done) {
             result = await gen.next();
@@ -214,6 +237,7 @@ export class Agent {
      * with valid toolResponses
      *
      * @param args - Arguments for invoking the agent
+     * @param options - Optional per-invocation options
      * @returns Async generator that yields AgentStreamEvent objects and returns AgentResult
      *
      * @example
@@ -226,13 +250,13 @@ export class Agent {
      * // Messages array is mutated in place and contains the full conversation
      * ```
      */
-    async *stream(args) {
+    async *stream(args, options) {
         const env_1 = { stack: [], error: void 0, hasError: false };
         try {
             const _lock = __addDisposableResource(env_1, this.acquireLock(), false);
             await this.initialize();
             // Delegate to _stream and process events through printer and hooks
-            const streamGenerator = this._stream(args);
+            const streamGenerator = this._stream(args, options);
             let result = await streamGenerator.next();
             while (!result.done) {
                 const event = result.value;
@@ -265,71 +289,119 @@ export class Agent {
      * Separated to centralize printer event processing in the public stream method.
      *
      * @param args - Arguments for invoking the agent
+     * @param options - Optional per-invocation options
      * @returns Async generator that yields AgentStreamEvent objects and returns AgentResult
      */
-    async *_stream(args) {
+    async *_stream(args, options) {
         let currentArgs = args;
         let forcedToolChoice = undefined;
+        let result;
         // Create structured output context (uses null object pattern when no schema)
-        const schema = this._structuredOutputSchema;
+        const schema = options?.structuredOutputSchema ?? this._structuredOutputSchema;
         const context = createStructuredOutputContext(schema);
         // Emit event before the try block
         yield new BeforeInvocationEvent({ agent: this });
+        // Normalize input to get the user messages for telemetry
+        const inputMessages = this._normalizeInput(args);
+        // Start agent trace span
+        this._accumulatedTokenUsage = Agent._createEmptyUsage();
+        const agentModelId = this.model.modelId;
+        const agentSpanOptions = {
+            messages: inputMessages,
+            agentName: this.name,
+            agentId: this.agentId,
+            tools: this.tools,
+        };
+        if (agentModelId)
+            agentSpanOptions.modelId = agentModelId;
+        if (this.systemPrompt)
+            agentSpanOptions.systemPrompt = this.systemPrompt;
+        const agentSpan = this._tracer.startAgentSpan(agentSpanOptions);
+        let caughtError;
         try {
             // Register structured output tool
             context.registerTool(this._toolRegistry);
             // Main agent loop - continues until model stops without requesting tools
-            while (true) {
-                const modelResult = yield* this.invokeModel(currentArgs, forcedToolChoice);
-                currentArgs = undefined; // Only pass args on first invocation
-                const wasForced = forcedToolChoice !== undefined;
-                forcedToolChoice = undefined; // Clear after use
-                if (modelResult.stopReason !== 'toolUse') {
-                    // Special handling for maxTokens - always fail regardless of whether we have structured output
-                    if (modelResult.stopReason === 'maxTokens') {
-                        throw new MaxTokensError('The model reached maxTokens before producing structured output. Consider increasing maxTokens in your model configuration.', modelResult.message);
-                    }
-                    // Check if we need to force structured output tool
-                    if (!context.hasResult()) {
-                        if (wasForced) {
-                            // Already tried forcing - LLM refused to use the tool
-                            throw new StructuredOutputException('The model failed to invoke the structured output tool even after it was forced.');
+            for (let cycleCount = 1;; cycleCount++) {
+                // Create agent loop cycle span within agent span context
+                const cycleSpan = this._tracer.startAgentLoopSpan({
+                    cycleId: `cycle-${cycleCount}`,
+                    messages: this.messages,
+                });
+                try {
+                    const modelResult = yield* this.invokeModel(currentArgs, forcedToolChoice);
+                    currentArgs = undefined; // Only pass args on first invocation
+                    const wasForced = forcedToolChoice !== undefined;
+                    forcedToolChoice = undefined; // Clear after use
+                    if (modelResult.stopReason !== 'toolUse') {
+                        // Special handling for maxTokens - always fail regardless of whether we have structured output
+                        if (modelResult.stopReason === 'maxTokens') {
+                            throw new MaxTokensError('The model reached maxTokens before producing structured output. Consider increasing maxTokens in your model configuration.', modelResult.message);
                         }
-                        // Force the model to use the structured output tool
-                        const toolName = context.getToolName();
-                        forcedToolChoice = { tool: { name: toolName } };
-                        continue;
+                        // Check if we need to force structured output tool
+                        if (!context.hasResult()) {
+                            if (wasForced) {
+                                // Already tried forcing - LLM refused to use the tool
+                                throw new StructuredOutputException('The model failed to invoke the structured output tool even after it was forced.');
+                            }
+                            // Force the model to use the structured output tool
+                            const toolName = context.getToolName();
+                            forcedToolChoice = { tool: { name: toolName } };
+                            this._tracer.endAgentLoopSpan(cycleSpan);
+                            continue;
+                        }
+                        // Loop terminates - no tool use requested (and structured output satisfied if needed)
+                        yield this._appendMessage(modelResult.message);
+                        // End cycle span
+                        this._tracer.endAgentLoopSpan(cycleSpan);
+                        const structuredOutput = context.getResult();
+                        result = new AgentResult({
+                            stopReason: modelResult.stopReason,
+                            lastMessage: modelResult.message,
+                            structuredOutput,
+                        });
+                        return result;
                     }
-                    // Loop terminates - no tool use requested (and structured output satisfied if needed)
+                    // Execute tools sequentially
+                    const toolResultMessage = yield* this.executeTools(modelResult.message, this._toolRegistry);
+                    /**
+                     * Deferred append: both messages are added AFTER tool execution completes.
+                     * This keeps agent.messages in a valid, reinvokable state at all times:
+                     *
+                     * - If interrupted during tool execution, messages has no dangling toolUse
+                     *   without a matching toolResult, so the agent can be reinvoked cleanly.
+                     * - The Python SDK appends the assistant message BEFORE tool execution,
+                     *   requiring recovery logic (generate_missing_tool_result_content) on
+                     *   interrupts. We avoid that by deferring.
+                     * - Trade-off: MessageAddedEvent for the assistant message fires after tools
+                     *   complete (not before as in Python), and agent.messages is incomplete
+                     *   during tool execution. Events like BeforeToolsEvent.message and
+                     *   BeforeToolCallEvent.toolUse provide the data directly.
+                     */
                     yield this._appendMessage(modelResult.message);
-                    const structuredOutput = context.getResult();
-                    return new AgentResult({
-                        stopReason: modelResult.stopReason,
-                        lastMessage: modelResult.message,
-                        structuredOutput,
-                    });
+                    yield this._appendMessage(toolResultMessage);
+                    // End cycle span
+                    this._tracer.endAgentLoopSpan(cycleSpan);
+                    // Continue loop
+                }
+                catch (error) {
+                    // End cycle span with error
+                    this._tracer.endAgentLoopSpan(cycleSpan, { error: error });
+                    throw error;
                 }
-                // Execute tools sequentially
-                const toolResultMessage = yield* this.executeTools(modelResult.message, this._toolRegistry);
-                /**
-                 * Deferred append: both messages are added AFTER tool execution completes.
-                 * This keeps agent.messages in a valid, reinvokable state at all times:
-                 *
-                 * - If interrupted during tool execution, messages has no dangling toolUse
-                 *   without a matching toolResult, so the agent can be reinvoked cleanly.
-                 * - The Python SDK appends the assistant message BEFORE tool execution,
-                 *   requiring recovery logic (generate_missing_tool_result_content) on
-                 *   interrupts. We avoid that by deferring.
-                 * - Trade-off: MessageAddedEvent for the assistant message fires after tools
-                 *   complete (not before as in Python), and agent.messages is incomplete
-                 *   during tool execution. Events like BeforeToolsEvent.message and
-                 *   BeforeToolCallEvent.toolUse provide the data directly.
-                 */
-                yield this._appendMessage(modelResult.message);
-                yield this._appendMessage(toolResultMessage);
             }
         }
+        catch (error) {
+            caughtError = error;
+            throw error;
+        }
         finally {
+            this._tracer.endAgentSpan(agentSpan, {
+                ...(caughtError && { error: caughtError }),
+                ...(result?.lastMessage && { response: result.lastMessage }),
+                accumulatedUsage: this._accumulatedTokenUsage,
+                ...(result?.stopReason && { stopReason: result.stopReason }),
+            });
             // Cleanup structured output context
             context.cleanup(this._toolRegistry);
             // Always emit final event
@@ -414,8 +486,20 @@ export class Agent {
             streamOptions.toolChoice = forcedToolChoice;
         }
         yield new BeforeModelCallEvent({ agent: this });
+        // Start model span within loop span context
+        const modelId = this.model.modelId;
+        const modelSpan = this._tracer.startModelInvokeSpan({
+            messages: this.messages,
+            ...(modelId && { modelId }),
+        });
         try {
-            const { message, stopReason } = yield* this._streamFromModel(this.messages, streamOptions);
+            const { message, stopReason, usage } = yield* this._streamFromModel(this.messages, streamOptions);
+            // Accumulate token usage
+            if (usage) {
+                Agent._accumulateUsage(this._accumulatedTokenUsage, usage);
+            }
+            // End model span with usage
+            this._tracer.endModelInvokeSpan(modelSpan, { output: message, stopReason, ...(usage && { usage }) });
             yield new ModelMessageEvent({ agent: this, message, stopReason });
             const afterModelCallEvent = new AfterModelCallEvent({ agent: this, stopData: { message, stopReason } });
             yield afterModelCallEvent;
@@ -426,6 +510,8 @@ export class Agent {
         }
         catch (error) {
             const modelError = normalizeError(error);
+            // End model span with error
+            this._tracer.endModelInvokeSpan(modelSpan, { error: modelError });
             // Create error event
             const errorEvent = new AfterModelCallEvent({ agent: this, error: modelError });
             // Yield error event - stream will invoke hooks
@@ -470,7 +556,11 @@ export class Agent {
             result = await streamGenerator.next();
         }
         // result.done is true, result.value contains the return value
-        return result.value;
+        const { message, stopReason, metadata } = result.value;
+        const returnValue = { message, stopReason };
+        if (metadata?.usage)
+            returnValue.usage = metadata.usage;
+        return returnValue;
     }
     /**
      * Executes tools sequentially and streams all tool events.
@@ -514,7 +604,7 @@ export class Agent {
      */
     async *executeTool(toolUseBlock, toolRegistry) {
         const tool = toolRegistry.find((t) => t.name === toolUseBlock.name);
-        // Create toolUse object for hook events
+        // Create toolUse object for hook events and telemetry
         const toolUse = {
             name: toolUseBlock.name,
             toolUseId: toolUseBlock.toolUseId,
@@ -523,6 +613,10 @@ export class Agent {
         // Retry loop for tool execution
         while (true) {
             yield new BeforeToolCallEvent({ agent: this, toolUse, tool });
+            // Start tool span within loop span context
+            const toolSpan = this._tracer.startToolCallSpan({
+                tool: toolUse,
+            });
             let toolResult;
             let error;
             if (!tool) {
@@ -534,7 +628,7 @@ export class Agent {
                 });
             }
             else {
-                // Execute tool and collect result
+                // Execute tool within the tool span context
                 const toolContext = {
                     toolUse: {
                         name: toolUseBlock.name,
@@ -547,11 +641,13 @@ export class Agent {
                     // Manually iterate tool stream to wrap each ToolStreamEvent in ToolStreamUpdateEvent.
                     // This keeps the tool authoring interface unchanged — tools construct ToolStreamEvent
                     // without knowledge of agents or hooks, and we wrap at the boundary.
-                    const toolGenerator = tool.stream(toolContext);
-                    let toolNext = await toolGenerator.next();
+                    // Tool execution is ran within the tool span's context so that
+                    // downstream calls (e.g., MCP clients) can propagate trace context
+                    const toolGenerator = this._tracer.withSpanContext(toolSpan, () => tool.stream(toolContext));
+                    let toolNext = await this._tracer.withSpanContext(toolSpan, () => toolGenerator.next());
                     while (!toolNext.done) {
                         yield new ToolStreamUpdateEvent({ agent: this, event: toolNext.value });
-                        toolNext = await toolGenerator.next();
+                        toolNext = await this._tracer.withSpanContext(toolSpan, () => toolGenerator.next());
                     }
                     const result = toolNext.value;
                     if (!result) {
@@ -578,6 +674,8 @@ export class Agent {
                     });
                 }
             }
+            // End tool span
+            this._tracer.endToolCallSpan(toolSpan, { toolResult, ...(error && { error }) });
             // Single point for AfterToolCallEvent
             const afterToolCallEvent = new AfterToolCallEvent({
                 agent: this,
@@ -603,6 +701,35 @@ export class Agent {
         this.messages.push(message);
         return new MessageAddedEvent({ agent: this, message });
     }
+    /**
+     * Creates an empty Usage object with all counters set to zero.
+     *
+     * @returns A Usage object with zeroed counters
+     */
+    static _createEmptyUsage() {
+        return {
+            inputTokens: 0,
+            outputTokens: 0,
+            totalTokens: 0,
+        };
+    }
+    /**
+     * 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
+     */
+    static _accumulateUsage(target, source) {
+        target.inputTokens += source.inputTokens;
+        target.outputTokens += source.outputTokens;
+        target.totalTokens += source.totalTokens;
+        if (source.cacheReadInputTokens !== undefined) {
+            target.cacheReadInputTokens = (target.cacheReadInputTokens ?? 0) + source.cacheReadInputTokens;
+        }
+        if (source.cacheWriteInputTokens !== undefined) {
+            target.cacheWriteInputTokens = (target.cacheWriteInputTokens ?? 0) + source.cacheWriteInputTokens;
+        }
+    }
 }
 /**
  * Recursively flattens nested arrays of tools into a single flat array.