@strands-agents/sdk 0.0.1

package/dist/models/bedrock.js

@@ -0,0 +1,679 @@
+/**
+ * AWS Bedrock model provider implementation.
+ *
+ * This module provides integration with AWS Bedrock's Converse API,
+ * supporting streaming responses, tool use, and prompt caching.
+ *
+ * @see https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html
+ */
+import { BedrockRuntimeClient, ConverseStreamCommand, ContentBlock as BedrockContentBlock, ConverseCommand, ReasoningContentBlockDelta, ReasoningContentBlock, } from '@aws-sdk/client-bedrock-runtime';
+import { Model } from '../models/model';
+import { ContextWindowOverflowError } from '../errors';
+import { ensureDefined } from '../types/validation';
+/**
+ * Default Bedrock model ID.
+ * Uses Claude Sonnet 4.5 with global inference profile for cross-region availability.
+ */
+const DEFAULT_BEDROCK_MODEL_ID = 'global.anthropic.claude-sonnet-4-5-20250929-v1:0';
+/**
+ * Models that require the status field in tool results.
+ * According to AWS Bedrock API documentation, the status field is only supported by Anthropic Claude models.
+ * @see https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultBlock.html
+ */
+const MODELS_INCLUDE_STATUS = ['anthropic.claude'];
+/**
+ * Error messages that indicate context window overflow.
+ * Used to detect when input exceeds the model's context window.
+ */
+const BEDROCK_CONTEXT_WINDOW_OVERFLOW_MESSAGES = [
+    'Input is too long for requested model',
+    'input length and `max_tokens` exceed context limit',
+    'too many total text bytes',
+];
+/**
+ * Mapping of Bedrock stop reasons to SDK stop reasons.
+ */
+const STOP_REASON_MAP = {
+    end_turn: 'endTurn',
+    tool_use: 'toolUse',
+    max_tokens: 'maxTokens',
+    stop_sequence: 'stopSequence',
+    content_filtered: 'contentFiltered',
+    guardrail_intervened: 'guardrailIntervened',
+};
+/**
+ * Converts a snake_case string to camelCase.
+ * Used for mapping unknown stop reasons from Bedrock to SDK format.
+ *
+ * @param str - Snake case string
+ * @returns Camel case string
+ */
+function snakeToCamel(str) {
+    return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+/**
+ * AWS Bedrock model provider implementation.
+ *
+ * Implements the Model interface for AWS Bedrock using the Converse Stream API.
+ * Supports streaming responses, tool use, prompt caching, and comprehensive error handling.
+ *
+ * @example
+ * ```typescript
+ * const provider = new BedrockModel({
+ *   modelConfig: {
+ *     modelId: 'global.anthropic.claude-sonnet-4-5-20250929-v1:0',
+ *     maxTokens: 1024,
+ *     temperature: 0.7
+ *   },
+ *   clientConfig: {
+ *     region: 'us-west-2'
+ *   }
+ * })
+ *
+ * const messages: Message[] = [
+ *   { type: 'message', role: 'user', content: [{ type: 'textBlock', text: 'Hello!' }] }
+ * ]
+ *
+ * for await (const event of provider.stream(messages)) {
+ *   if (event.type === 'modelContentBlockDeltaEvent' && event.delta.type === 'textDelta') {
+ *     process.stdout.write(event.delta.text)
+ *   }
+ * }
+ * ```
+ */
+export class BedrockModel extends Model {
+    _config;
+    _client;
+    /**
+     * Creates a new BedrockModel instance.
+     *
+     * @param options - Optional configuration for model and client
+     *
+     * @example
+     * ```typescript
+     * // Minimal configuration with defaults
+     * const provider = new BedrockModel({
+     *   region: 'us-west-2'
+     * })
+     *
+     * // With model configuration
+     * const provider = new BedrockModel({
+     *   region: 'us-west-2',
+     *   modelId: 'global.anthropic.claude-sonnet-4-5-20250929-v1:0',
+     *   maxTokens: 2048,
+     *   temperature: 0.8,
+     *   cachePrompt: 'ephemeral'
+     * })
+     *
+     * // With client configuration
+     * const provider = new BedrockModel({
+     *   region: 'us-east-1',
+     *   clientConfig: {
+     *     credentials: myCredentials
+     *   }
+     * })
+     * ```
+     */
+    constructor(options) {
+        super();
+        const { region, clientConfig, ...modelConfig } = options ?? {};
+        // Initialize model config with default model ID if not provided
+        this._config = {
+            modelId: DEFAULT_BEDROCK_MODEL_ID,
+            ...modelConfig,
+        };
+        // Build user agent string (extend if provided, otherwise use SDK identifier)
+        const customUserAgent = clientConfig?.customUserAgent
+            ? `${clientConfig.customUserAgent} strands-agents-ts-sdk`
+            : 'strands-agents-ts-sdk';
+        // Initialize Bedrock Runtime client with custom user agent
+        this._client = new BedrockRuntimeClient({
+            ...(clientConfig ?? {}),
+            // region takes precedence over clientConfig
+            ...(region ? { region: region } : {}),
+            customUserAgent,
+        });
+    }
+    /**
+     * Updates the model configuration.
+     * Merges the provided configuration with existing settings.
+     *
+     * @param modelConfig - Configuration object with model-specific settings to update
+     *
+     * @example
+     * ```typescript
+     * // Update temperature and maxTokens
+     * provider.updateConfig({
+     *   temperature: 0.9,
+     *   maxTokens: 2048
+     * })
+     * ```
+     */
+    updateConfig(modelConfig) {
+        this._config = { ...this._config, ...modelConfig };
+    }
+    /**
+     * Retrieves the current model configuration.
+     *
+     * @returns The current configuration object
+     *
+     * @example
+     * ```typescript
+     * const config = provider.getConfig()
+     * console.log(config.modelId)
+     * ```
+     */
+    getConfig() {
+        return this._config;
+    }
+    /**
+     * Streams a conversation with the Bedrock model.
+     * Returns an async iterable that yields streaming events as they occur.
+     *
+     * @param messages - Array of conversation messages
+     * @param options - Optional streaming configuration
+     * @returns Async iterable of streaming events
+     *
+     * @throws \{ContextWindowOverflowError\} When input exceeds the model's context window
+     * @throws \{ModelThrottledError\} When Bedrock service throttles requests
+     *
+     * @example
+     * ```typescript
+     * const messages: Message[] = [
+     *   { type: 'message', role: $1, content: [{ type: 'textBlock', text: 'What is 2+2?' }] }
+     * ]
+     *
+     * const options: StreamOptions = {
+     *   systemPrompt: 'You are a helpful math assistant.',
+     *   toolSpecs: [calculatorTool]
+     * }
+     *
+     * for await (const event of provider.stream(messages, options)) {
+     *   if (event.type === 'modelContentBlockDeltaEvent') {
+     *     console.log(event.delta)
+     *   }
+     * }
+     * ```
+     */
+    async *stream(messages, options) {
+        try {
+            // Format the request for Bedrock
+            const request = this._formatRequest(messages, options);
+            if (this._config.stream !== false) {
+                // Create and send the command
+                const command = new ConverseStreamCommand(request);
+                const response = await this._client.send(command);
+                // Stream the response
+                if (response.stream) {
+                    for await (const chunk of response.stream) {
+                        // Map Bedrock events to SDK events
+                        const events = this._mapStreamedBedrockEventToSDKEvent(chunk);
+                        for (const event of events) {
+                            yield event;
+                        }
+                    }
+                }
+            }
+            else {
+                const command = new ConverseCommand(request);
+                const response = await this._client.send(command);
+                for (const event of this._mapBedrockEventToSDKEvent(response)) {
+                    yield event;
+                }
+            }
+        }
+        catch (error) {
+            const err = error;
+            // Check for context window overflow
+            if (BEDROCK_CONTEXT_WINDOW_OVERFLOW_MESSAGES.some((msg) => err.message.includes(msg))) {
+                throw new ContextWindowOverflowError(err.message);
+            }
+            // Re-throw other errors as-is
+            throw err;
+        }
+    }
+    /**
+     * Formats a request for the Bedrock Converse Stream API.
+     *
+     * @param messages - Conversation messages
+     * @param options - Stream options
+     * @returns Formatted Bedrock request
+     */
+    _formatRequest(messages, options) {
+        const request = {
+            modelId: this._config.modelId,
+            messages: this._formatMessages(messages),
+        };
+        // Add system prompt with optional caching
+        if (options?.systemPrompt !== undefined) {
+            if (typeof options.systemPrompt === 'string') {
+                // String path: apply cachePrompt config if set
+                const system = [{ text: options.systemPrompt }];
+                if (this._config.cachePrompt) {
+                    system.push({ cachePoint: { type: this._config.cachePrompt } });
+                }
+                request.system = system;
+            }
+            else if (options.systemPrompt.length > 0) {
+                // Array path: use as-is, but warn if cachePrompt config is also set
+                if (this._config.cachePrompt) {
+                    console.warn('cachePrompt config is ignored when systemPrompt is an array. Use explicit cache points in the array instead.');
+                }
+                request.system = options.systemPrompt.map((block) => this._formatContentBlock(block));
+            }
+        }
+        // Add tool configuration
+        if (options?.toolSpecs && options.toolSpecs.length > 0) {
+            const tools = options.toolSpecs.map((spec) => ({
+                toolSpec: {
+                    name: spec.name,
+                    description: spec.description,
+                    inputSchema: { json: spec.inputSchema },
+                },
+            }));
+            if (this._config.cacheTools) {
+                tools.push({
+                    cachePoint: { type: this._config.cacheTools },
+                });
+            }
+            const toolConfig = {
+                tools: tools,
+            };
+            if (options.toolChoice) {
+                toolConfig.toolChoice = options.toolChoice;
+            }
+            request.toolConfig = toolConfig;
+        }
+        // Add inference configuration
+        const inferenceConfig = {};
+        if (this._config.maxTokens !== undefined)
+            inferenceConfig.maxTokens = this._config.maxTokens;
+        if (this._config.temperature !== undefined)
+            inferenceConfig.temperature = this._config.temperature;
+        if (this._config.topP !== undefined)
+            inferenceConfig.topP = this._config.topP;
+        if (this._config.stopSequences !== undefined)
+            inferenceConfig.stopSequences = this._config.stopSequences;
+        if (Object.keys(inferenceConfig).length > 0) {
+            request.inferenceConfig = inferenceConfig;
+        }
+        // Add additional request fields
+        if (this._config.additionalRequestFields) {
+            request.additionalModelRequestFields = this._config.additionalRequestFields;
+        }
+        // Add additional response field paths
+        if (this._config.additionalResponseFieldPaths) {
+            request.additionalModelResponseFieldPaths = this._config.additionalResponseFieldPaths;
+        }
+        // Add additional args (spread them into the request for forward compatibility)
+        if (this._config.additionalArgs) {
+            Object.assign(request, this._config.additionalArgs);
+        }
+        return request;
+    }
+    /**
+     * Formats messages for Bedrock API.
+     *
+     * @param messages - SDK messages
+     * @returns Bedrock-formatted messages
+     */
+    _formatMessages(messages) {
+        return messages.map((message) => ({
+            role: message.role,
+            content: message.content.map((block) => this._formatContentBlock(block)),
+        }));
+    }
+    /**
+     * Determines whether to include the status field in tool results.
+     *
+     * Uses the includeToolResultStatus config option:
+     * - If explicitly true, always include status
+     * - If explicitly false, never include status
+     * - If 'auto' (default), check if model ID matches known patterns
+     *
+     * @returns True if status field should be included, false otherwise
+     */
+    _shouldIncludeToolResultStatus() {
+        const includeStatus = this._config.includeToolResultStatus ?? 'auto';
+        if (includeStatus === true)
+            return true;
+        if (includeStatus === false)
+            return false;
+        // Auto-detection mode: check if modelId contains any pattern
+        const shouldInclude = MODELS_INCLUDE_STATUS.some((pattern) => this._config.modelId?.includes(pattern));
+        // Log debug message for auto-detection
+        console.debug(`Auto-detected includeToolResultStatus=${shouldInclude} for model: ${this._config.modelId}`);
+        return shouldInclude;
+    }
+    /**
+     * Formats a content block for Bedrock API.
+     *
+     * @param block - SDK content block
+     * @returns Bedrock-formatted content block
+     */
+    _formatContentBlock(block) {
+        switch (block.type) {
+            case 'textBlock':
+                return { text: block.text };
+            case 'toolUseBlock':
+                return {
+                    toolUse: {
+                        toolUseId: block.toolUseId,
+                        name: block.name,
+                        input: block.input,
+                    },
+                };
+            case 'toolResultBlock': {
+                const content = block.content.map((content) => {
+                    switch (content.type) {
+                        case 'toolResultTextContent':
+                            return { text: content.text };
+                        case 'toolResultJsonContent':
+                            return { json: content.json };
+                    }
+                });
+                return {
+                    toolResult: {
+                        toolUseId: block.toolUseId,
+                        content,
+                        ...(this._shouldIncludeToolResultStatus() && { status: block.status }),
+                    },
+                };
+            }
+            case 'reasoningBlock': {
+                if (block.text) {
+                    return {
+                        reasoningContent: {
+                            reasoningText: {
+                                text: block.text,
+                                signature: block.signature,
+                            },
+                        },
+                    };
+                }
+                else if (block.redactedContent) {
+                    return {
+                        reasoningContent: {
+                            redactedContent: block.redactedContent,
+                        },
+                    };
+                }
+                else {
+                    throw Error("reasoning content format incorrect. Either 'text' or 'redactedContent' must be set.");
+                }
+            }
+            case 'cachePointBlock':
+                return { cachePoint: { type: block.cacheType } };
+        }
+    }
+    _mapBedrockEventToSDKEvent(event) {
+        const events = [];
+        // Message start
+        const output = ensureDefined(event.output, 'event.output');
+        const message = ensureDefined(output.message, 'output.message');
+        const role = ensureDefined(message.role, 'message.role');
+        events.push({
+            type: 'modelMessageStartEvent',
+            role,
+        });
+        // Match on content blocks
+        const blockHandlers = {
+            text: (textBlock, index) => {
+                events.push({ type: 'modelContentBlockStartEvent', contentBlockIndex: index });
+                events.push({
+                    type: 'modelContentBlockDeltaEvent',
+                    contentBlockIndex: index,
+                    delta: { type: 'textDelta', text: textBlock },
+                });
+                events.push({ type: 'modelContentBlockStopEvent', contentBlockIndex: index });
+            },
+            toolUse: (block, index) => {
+                events.push({
+                    type: 'modelContentBlockStartEvent',
+                    contentBlockIndex: index,
+                    start: {
+                        type: 'toolUseStart',
+                        name: ensureDefined(block.name, 'toolUse.name'),
+                        toolUseId: ensureDefined(block.toolUseId, 'toolUse.toolUseId'),
+                    },
+                });
+                events.push({
+                    type: 'modelContentBlockDeltaEvent',
+                    contentBlockIndex: index,
+                    delta: { type: 'toolUseInputDelta', input: JSON.stringify(ensureDefined(block.input, 'toolUse.input')) },
+                });
+                events.push({ type: 'modelContentBlockStopEvent', contentBlockIndex: index });
+            },
+            reasoningContent: (block, index) => {
+                if (!block)
+                    return;
+                events.push({ type: 'modelContentBlockStartEvent', contentBlockIndex: index });
+                const delta = { type: 'reasoningContentDelta' };
+                if (block.reasoningText) {
+                    delta.text = ensureDefined(block.reasoningText.text, 'reasoningText.text');
+                    if (block.reasoningText.signature)
+                        delta.signature = block.reasoningText.signature;
+                }
+                else if (block.redactedContent) {
+                    delta.redactedContent = block.redactedContent;
+                }
+                if (Object.keys(delta).length > 1) {
+                    events.push({ type: 'modelContentBlockDeltaEvent', contentBlockIndex: index, delta });
+                }
+                events.push({ type: 'modelContentBlockStopEvent', contentBlockIndex: index });
+            },
+        };
+        const content = ensureDefined(message.content, 'message.content');
+        content.forEach((block, index) => {
+            for (const key in block) {
+                if (key in blockHandlers) {
+                    const handlerKey = key;
+                    // @ts-expect-error - We know the value type corresponds to the handler key.
+                    blockHandlers[handlerKey](block[handlerKey], index);
+                }
+                else {
+                    console.warn(`Skipping unsupported block key: ${key}`);
+                }
+            }
+        });
+        const stopReasonRaw = ensureDefined(event.stopReason, 'event.stopReason');
+        events.push({
+            type: 'modelMessageStopEvent',
+            stopReason: this._transformStopReason(stopReasonRaw, event),
+        });
+        const usage = ensureDefined(event.usage, 'output.usage');
+        const metadataEvent = {
+            type: 'modelMetadataEvent',
+            usage: {
+                inputTokens: ensureDefined(usage.inputTokens, 'usage.inputTokens'),
+                outputTokens: ensureDefined(usage.outputTokens, 'usage.outputTokens'),
+                totalTokens: ensureDefined(usage.totalTokens, 'usage.totalTokens'),
+            },
+        };
+        if (event.metrics) {
+            metadataEvent.metrics = {
+                latencyMs: ensureDefined(event.metrics.latencyMs, 'metrics.latencyMs'),
+            };
+        }
+        events.push(metadataEvent);
+        return events;
+    }
+    /**
+     * Maps a Bedrock event to SDK streaming events.
+     *
+     * @param chunk - Bedrock event chunk
+     * @returns Array of SDK streaming events
+     */
+    _mapStreamedBedrockEventToSDKEvent(chunk) {
+        const events = [];
+        // Extract the event type key
+        const eventType = ensureDefined(Object.keys(chunk)[0], 'eventType');
+        const eventData = chunk[eventType];
+        switch (eventType) {
+            case 'messageStart': {
+                const data = eventData;
+                events.push({
+                    type: 'modelMessageStartEvent',
+                    role: ensureDefined(data.role, 'messageStart.role'),
+                });
+                break;
+            }
+            case 'contentBlockStart': {
+                const data = eventData;
+                const event = {
+                    type: 'modelContentBlockStartEvent',
+                    contentBlockIndex: ensureDefined(data.contentBlockIndex, 'contentBlockStart.contentBlockIndex'),
+                };
+                if (data.start?.toolUse) {
+                    const toolUse = data.start.toolUse;
+                    event.start = {
+                        type: 'toolUseStart',
+                        name: ensureDefined(toolUse.name, 'toolUse.name'),
+                        toolUseId: ensureDefined(toolUse.toolUseId, 'toolUse.toolUseId'),
+                    };
+                }
+                events.push(event);
+                break;
+            }
+            case 'contentBlockDelta': {
+                const data = eventData;
+                const contentBlockIndex = ensureDefined(data.contentBlockIndex, 'contentBlockDelta.contentBlockIndex');
+                const delta = ensureDefined(data.delta, 'contentBlockDelta.delta');
+                const deltaHandlers = {
+                    text: (textValue) => {
+                        events.push({
+                            type: 'modelContentBlockDeltaEvent',
+                            contentBlockIndex,
+                            delta: { type: 'textDelta', text: textValue },
+                        });
+                    },
+                    toolUse: (toolUse) => {
+                        if (!toolUse?.input)
+                            return;
+                        events.push({
+                            type: 'modelContentBlockDeltaEvent',
+                            contentBlockIndex,
+                            delta: { type: 'toolUseInputDelta', input: toolUse.input },
+                        });
+                    },
+                    reasoningContent: (reasoning) => {
+                        if (!reasoning)
+                            return;
+                        const reasoningDelta = { type: 'reasoningContentDelta' };
+                        if (reasoning.text)
+                            reasoningDelta.text = reasoning.text;
+                        if (reasoning.signature)
+                            reasoningDelta.signature = reasoning.signature;
+                        if (reasoning.redactedContent)
+                            reasoningDelta.redactedContent = reasoning.redactedContent;
+                        if (Object.keys(reasoningDelta).length > 1) {
+                            events.push({ type: 'modelContentBlockDeltaEvent', contentBlockIndex, delta: reasoningDelta });
+                        }
+                    },
+                };
+                for (const key in delta) {
+                    if (key in deltaHandlers) {
+                        const handlerKey = key;
+                        // @ts-expect-error - We know the value type corresponds to the handler key.
+                        deltaHandlers[handlerKey](delta[handlerKey]);
+                    }
+                    else {
+                        console.warn(`Skipping unsupported delta key: ${key}`);
+                    }
+                }
+                break;
+            }
+            case 'contentBlockStop': {
+                const data = eventData;
+                events.push({
+                    type: 'modelContentBlockStopEvent',
+                    contentBlockIndex: ensureDefined(data.contentBlockIndex, 'contentBlockStop.contentBlockIndex'),
+                });
+                break;
+            }
+            case 'messageStop': {
+                const data = eventData;
+                const event = {
+                    type: 'modelMessageStopEvent',
+                };
+                const stopReasonRaw = ensureDefined(data.stopReason, 'messageStop.stopReason');
+                event.stopReason = this._transformStopReason(stopReasonRaw, data);
+                if (data.additionalModelResponseFields) {
+                    event.additionalModelResponseFields = data.additionalModelResponseFields;
+                }
+                events.push(event);
+                break;
+            }
+            case 'metadata': {
+                const data = eventData;
+                const event = {
+                    type: 'modelMetadataEvent',
+                };
+                if (data.usage) {
+                    const usage = data.usage;
+                    const usageInfo = {
+                        inputTokens: ensureDefined(usage.inputTokens, 'usage.inputTokens'),
+                        outputTokens: ensureDefined(usage.outputTokens, 'usage.outputTokens'),
+                        totalTokens: ensureDefined(usage.totalTokens, 'usage.totalTokens'),
+                    };
+                    if (usage.cacheReadInputTokens !== undefined) {
+                        usageInfo.cacheReadInputTokens = usage.cacheReadInputTokens;
+                    }
+                    if (usage.cacheWriteInputTokens !== undefined) {
+                        usageInfo.cacheWriteInputTokens = usage.cacheWriteInputTokens;
+                    }
+                    event.usage = usageInfo;
+                }
+                if (data.metrics) {
+                    event.metrics = {
+                        latencyMs: ensureDefined(data.metrics.latencyMs, 'metrics.latencyMs'),
+                    };
+                }
+                if (data.trace) {
+                    event.trace = data.trace;
+                }
+                events.push(event);
+                break;
+            }
+            case 'internalServerException':
+            case 'modelStreamErrorException':
+            case 'serviceUnavailableException':
+            case 'validationException':
+            case 'throttlingException': {
+                throw eventData;
+            }
+            default:
+                // Log warning for unsupported event types (for forward compatibility)
+                console.warn(`Unsupported Bedrock event type: ${eventType}`);
+                break;
+        }
+        return events;
+    }
+    /**
+     * Transforms a Bedrock stop reason into the SDK's format.
+     *
+     * @param stopReasonRaw - The raw stop reason string from Bedrock.
+     * @param event - The full event output, used to check for tool_use adjustments.
+     * @returns The transformed stop reason string.
+     */
+    _transformStopReason(stopReasonRaw, event) {
+        let mappedStopReason;
+        if (stopReasonRaw in STOP_REASON_MAP) {
+            mappedStopReason = STOP_REASON_MAP[stopReasonRaw];
+        }
+        else {
+            console.warn(`Unknown stop reason: "${stopReasonRaw}". Converting to camelCase: "${snakeToCamel(stopReasonRaw)}"`);
+            mappedStopReason = snakeToCamel(stopReasonRaw);
+        }
+        // Adjust for tool_use, which is sometimes incorrectly reported as end_turn
+        if (mappedStopReason === 'endTurn' &&
+            event &&
+            'output' in event &&
+            event.output?.message?.content?.some((block) => 'toolUse' in block)) {
+            mappedStopReason = 'toolUse';
+            console.warn(`Adjusting stop reason from 'end_turn' to 'tool_use' due to tool use in content blocks.`);
+        }
+        return mappedStopReason;
+    }
+}
+//# sourceMappingURL=bedrock.js.map