@strands-agents/sdk 0.5.0 → 0.7.0

package/dist/src/models/bedrock.js

@@ -6,7 +6,7 @@
  *
  * @see https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html
  */
-import { BedrockRuntimeClient, ConverseCommand, ConverseStreamCommand, DocumentFormat, ImageFormat, } from '@aws-sdk/client-bedrock-runtime';
+import { BedrockRuntimeClient, ConverseCommand, ConverseStreamCommand, DocumentFormat, ImageFormat, VideoFormat, } from '@aws-sdk/client-bedrock-runtime';
 import { Model } from '../models/model.js';
 import { ContextWindowOverflowError, ModelThrottledError, normalizeError } from '../errors.js';
 import { ensureDefined } from '../types/validation.js';
@@ -24,6 +24,12 @@ const DEFAULT_BEDROCK_REGION_SUPPORTS_FIP = false;
  * @see https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultBlock.html
  */
 const MODELS_INCLUDE_STATUS = ['anthropic.claude'];
+/**
+ * Models that support the Anthropic-style prompt caching strategy.
+ * Used to auto-detect when `cacheConfig.strategy` is `'auto'`.
+ * @see https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
+ */
+const MODELS_SUPPORTING_ANTHROPIC_CACHING = ['anthropic', 'claude'];
 /**
  * Error messages that indicate context window overflow.
  * Used to detect when input exceeds the model's context window.
@@ -44,6 +50,14 @@ const STOP_REASON_MAP = {
     content_filtered: 'contentFiltered',
     guardrail_intervened: 'guardrailIntervened',
 };
+/**
+ * Default message for redacted input.
+ */
+const DEFAULT_REDACT_INPUT_MESSAGE = '[User input redacted.]';
+/**
+ * Default message for redacted output.
+ */
+const DEFAULT_REDACT_OUTPUT_MESSAGE = '[Assistant output redacted.]';
 /**
  * Converts a snake_case string to camelCase.
  * Used for mapping unknown stop reasons from Bedrock to SDK format.
@@ -105,7 +119,7 @@ export class BedrockModel extends Model {
      *   modelId: 'global.anthropic.claude-sonnet-4-5-20250929-v1:0',
      *   maxTokens: 2048,
      *   temperature: 0.8,
-     *   cachePrompt: 'ephemeral'
+     *   cacheConfig: { strategy: 'auto' }
      * })
      *
      * // With client configuration
@@ -141,6 +155,41 @@ export class BedrockModel extends Model {
         }
         applyDefaultRegion(this._client.config);
     }
+    /**
+     * Returns the cache strategy for this model based on its model ID.
+     * Returns the appropriate cache strategy name, or null if automatic caching is not supported.
+     *
+     * @returns Cache strategy name or null
+     */
+    _getCacheStrategy() {
+        return MODELS_SUPPORTING_ANTHROPIC_CACHING.some((pattern) => this._config.modelId?.includes(pattern))
+            ? 'anthropic'
+            : null;
+    }
+    /**
+     * Determines if caching should be enabled.
+     * Returns true when:
+     * - strategy is 'anthropic' (explicit enable)
+     * - strategy is 'auto' and model supports caching (auto-detect)
+     *
+     * @returns True if caching should be enabled
+     */
+    _shouldEnableCaching() {
+        const cacheConfig = this._config.cacheConfig;
+        if (!cacheConfig) {
+            return false;
+        }
+        let strategy = cacheConfig.strategy;
+        if (strategy === 'auto') {
+            const detectedStrategy = this._getCacheStrategy();
+            if (!detectedStrategy) {
+                logger.warn(`model_id=<${this._config.modelId}> | cache_config is enabled but this model does not support automatic caching`);
+                return false;
+            }
+            strategy = detectedStrategy;
+        }
+        return strategy === 'anthropic';
+    }
     /**
      * Updates the model configuration.
      * Merges the provided configuration with existing settings.
@@ -212,10 +261,12 @@ export class BedrockModel extends Model {
                 const response = await this._client.send(command);
                 // Stream the response
                 if (response.stream) {
+                    let lastStopReason;
                     for await (const chunk of response.stream) {
                         // Map Bedrock events to SDK events
-                        const events = this._mapStreamedBedrockEventToSDKEvent(chunk);
-                        for (const event of events) {
+                        const result = this._mapStreamedBedrockEventToSDKEvent(chunk, lastStopReason);
+                        lastStopReason = result.stopReason;
+                        for (const event of result.events) {
                             yield event;
                         }
                     }
@@ -251,21 +302,12 @@ export class BedrockModel extends Model {
             modelId: this._config.modelId,
             messages: this._formatMessages(messages),
         };
-        // Add system prompt with optional caching
+        // Add system prompt
         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;
+                request.system = [{ text: options.systemPrompt }];
             }
             else if (options.systemPrompt.length > 0) {
-                // Array path: use as-is, but warn if cachePrompt config is also set
-                if (this._config.cachePrompt) {
-                    logger.warn('cachePrompt config is ignored when systemPrompt is an array, use explicit cache points instead');
-                }
                 request.system = options.systemPrompt.map((block) => this._formatContentBlock(block));
             }
         }
@@ -278,10 +320,8 @@ export class BedrockModel extends Model {
                     inputSchema: { json: spec.inputSchema },
                 },
             }));
-            if (this._config.cacheTools) {
-                tools.push({
-                    cachePoint: { type: this._config.cacheTools },
-                });
+            if (this._shouldEnableCaching()) {
+                tools.push({ cachePoint: { type: 'default' } });
             }
             const toolConfig = {
                 tools: tools,
@@ -316,6 +356,17 @@ export class BedrockModel extends Model {
         if (this._config.additionalArgs) {
             Object.assign(request, this._config.additionalArgs);
         }
+        // Add guardrail configuration
+        if (this._config.guardrailConfig) {
+            request.guardrailConfig = {
+                guardrailIdentifier: this._config.guardrailConfig.guardrailIdentifier,
+                guardrailVersion: this._config.guardrailConfig.guardrailVersion,
+                trace: this._config.guardrailConfig.trace ?? 'enabled',
+                ...(this._config.guardrailConfig.streamProcessingMode && {
+                    streamProcessingMode: this._config.guardrailConfig.streamProcessingMode,
+                }),
+            };
+        }
         return request;
     }
     /**
@@ -325,15 +376,140 @@ export class BedrockModel extends Model {
      * @returns Bedrock-formatted messages
      */
     _formatMessages(messages) {
-        return messages.reduce((acc, message) => {
+        // Pre-compute the index of the last user message containing text/image content
+        // This ensures guardContent wrapping is maintained across tool execution cycles
+        const lastUserTextIdx = this._config.guardrailConfig?.guardLatestUserMessage
+            ? this._findLastUserTextMessageIndex(messages)
+            : undefined;
+        const formattedMessages = messages.reduce((acc, message, idx) => {
+            const shouldApplyGuardBlocks = idx === lastUserTextIdx;
             const content = message.content
-                .map((block) => this._formatContentBlock(block))
+                .map((block) => {
+                const formattedBlock = this._formatContentBlock(block);
+                return shouldApplyGuardBlocks ? this._applyGuardBlocks(formattedBlock) : formattedBlock;
+            })
                 .filter((block) => block !== undefined);
             if (content.length > 0) {
                 acc.push({ role: message.role, content });
             }
             return acc;
         }, []);
+        // Inject cache point if caching is enabled
+        if (this._shouldEnableCaching()) {
+            this._injectCachePoint(formattedMessages);
+        }
+        return formattedMessages;
+    }
+    /**
+     * Inject a cache point at the end of the last user message.
+     * Strips any existing cache points from all messages first.
+     *
+     * @param messages - List of messages to inject cache point into (modified in place)
+     */
+    _injectCachePoint(messages) {
+        if (messages.length === 0) {
+            return;
+        }
+        let lastUserIdx = null;
+        // Strip existing cache points and find last user message
+        for (let msgIdx = 0; msgIdx < messages.length; msgIdx++) {
+            const msg = messages[msgIdx];
+            if (!msg)
+                continue;
+            const content = msg.content ?? [];
+            for (let blockIdx = content.length - 1; blockIdx >= 0; blockIdx--) {
+                const block = content[blockIdx];
+                if (block && 'cachePoint' in block) {
+                    content.splice(blockIdx, 1);
+                    logger.warn(`msg_idx=<${msgIdx}>, block_idx=<${blockIdx}> | stripped existing cache point (auto mode manages cache points)`);
+                }
+            }
+            if (msg.role === 'user') {
+                lastUserIdx = msgIdx;
+            }
+        }
+        // Add cache point to last user message
+        if (lastUserIdx !== null) {
+            const lastMsg = messages[lastUserIdx];
+            if (lastMsg && lastMsg.content) {
+                lastMsg.content.push({ cachePoint: { type: 'default' } });
+                logger.debug(`msg_idx=<${lastUserIdx}> | added cache point to last user message`);
+            }
+        }
+    }
+    /**
+     * Wraps a formatted content block in guardContent for guardrail evaluation.
+     *
+     * When guardLatestUserMessage is enabled, this method wraps text and image blocks
+     * in guardContent blocks to signal to Bedrock's guardrails to evaluate only that content.
+     * Other content types (toolUse, toolResult, etc.) pass through unchanged.
+     *
+     * @param formattedBlock - The formatted content block to potentially wrap
+     * @returns The block wrapped in guardContent if applicable, or the original block
+     */
+    _applyGuardBlocks(formattedBlock) {
+        if (formattedBlock === undefined) {
+            return undefined;
+        }
+        if ('text' in formattedBlock) {
+            return {
+                guardContent: {
+                    text: {
+                        text: formattedBlock.text,
+                    },
+                },
+            };
+        }
+        if ('image' in formattedBlock) {
+            // Extract image data and validate for guardContent compatibility
+            const imageBlock = formattedBlock.image;
+            if (!imageBlock?.format || !imageBlock?.source) {
+                return formattedBlock;
+            }
+            const format = imageBlock.format;
+            // Bedrock guardrails only support png/jpeg formats
+            if (format !== 'png' && format !== 'jpeg') {
+                console.warn(`Image format '${format}' not supported by Bedrock guardrails, skipping guardContent wrap`);
+                return formattedBlock;
+            }
+            // Bedrock guardrails only support bytes source (not S3 or URL)
+            if (!('bytes' in imageBlock.source)) {
+                console.warn('Image source must be bytes for Bedrock guardrails, skipping guardContent wrap');
+                return formattedBlock;
+            }
+            return {
+                guardContent: {
+                    image: {
+                        format: format,
+                        source: imageBlock.source,
+                    },
+                },
+            };
+        }
+        // Other content types (toolUse, toolResult, etc.) pass through unchanged
+        return formattedBlock;
+    }
+    /**
+     * Find the index of the last user message containing text or image content.
+     *
+     * This is used for guardLatestUserMessage guardrail evaluation to ensure that guardContent
+     * wrapping targets the correct message even when toolResult messages (role='user') follow
+     * the actual user text/image input during tool execution cycles.
+     *
+     * @param messages - Array of messages to search
+     * @returns Index of the last user message with text/image content, or undefined if not found
+     */
+    _findLastUserTextMessageIndex(messages) {
+        for (let idx = messages.length - 1; idx >= 0; idx--) {
+            const msg = messages[idx];
+            if (msg === undefined)
+                continue;
+            if (msg.role === 'user' &&
+                msg.content.some((block) => block.type === 'textBlock' || block.type === 'imageBlock')) {
+                return idx;
+            }
+        }
+        return undefined;
     }
     /**
      * Determines whether to include the status field in tool results.
@@ -382,6 +558,30 @@ export class BedrockModel extends Model {
                             return { text: content.text };
                         case 'jsonBlock':
                             return { json: content.json };
+                        case 'imageBlock':
+                            return {
+                                image: {
+                                    format: content.format,
+                                    source: this._formatMediaSource(content.source),
+                                },
+                            };
+                        case 'videoBlock':
+                            return {
+                                video: {
+                                    format: content.format === '3gp' ? 'three_gp' : content.format,
+                                    source: this._formatMediaSource(content.source),
+                                },
+                            };
+                        case 'documentBlock':
+                            return {
+                                document: {
+                                    name: content.name,
+                                    format: content.format,
+                                    source: this._formatDocumentSource(content.source),
+                                    ...(content.citations && { citations: content.citations }),
+                                    ...(content.context && { context: content.context }),
+                                },
+                            };
                     }
                 });
                 return {
@@ -440,6 +640,13 @@ export class BedrockModel extends Model {
                         ...(block.context && { context: block.context }),
                     },
                 };
+            case 'citationsBlock':
+                return {
+                    citationsContent: {
+                        citations: block.citations.map((c) => this._mapCitationToBedrock(c)),
+                        content: block.content,
+                    },
+                };
             case 'guardContentBlock': {
                 if (block.text) {
                     return {
@@ -494,8 +701,8 @@ export class BedrockModel extends Model {
             case 'videoSourceS3Location':
                 return {
                     s3Location: {
-                        uri: source.s3Location.uri,
-                        ...(source.s3Location.bucketOwner && { bucketOwner: source.s3Location.bucketOwner }),
+                        uri: source.location.uri,
+                        ...(source.location.bucketOwner && { bucketOwner: source.location.bucketOwner }),
                     },
                 };
             default:
@@ -530,8 +737,8 @@ export class BedrockModel extends Model {
             case 'documentSourceS3Location':
                 return {
                     s3Location: {
-                        uri: source.s3Location.uri,
-                        ...(source.s3Location.bucketOwner && { bucketOwner: source.s3Location.bucketOwner }),
+                        uri: source.location.uri,
+                        ...(source.location.bucketOwner && { bucketOwner: source.location.bucketOwner }),
                     },
                 };
             default:
@@ -591,6 +798,19 @@ export class BedrockModel extends Model {
                 }
                 events.push({ type: 'modelContentBlockStopEvent' });
             },
+            citationsContent: (block) => {
+                if (!block)
+                    return;
+                events.push({ type: 'modelContentBlockStartEvent' });
+                const mapped = this._mapBedrockCitationsData(block);
+                const delta = {
+                    type: 'citationsDelta',
+                    citations: mapped.citations,
+                    content: mapped.content,
+                };
+                events.push({ type: 'modelContentBlockDeltaEvent', delta });
+                events.push({ type: 'modelContentBlockStopEvent' });
+            },
         };
         const content = ensureDefined(message.content, 'message.content');
         content.forEach((block) => {
@@ -624,6 +844,16 @@ export class BedrockModel extends Model {
                 latencyMs: ensureDefined(event.metrics.latencyMs, 'metrics.latencyMs'),
             };
         }
+        // Handle trace and guardrail check for non-streaming responses
+        if (event.trace) {
+            metadataEvent.trace = event.trace;
+            // Check for blocked guardrails and emit redaction events
+            if (this._config.guardrailConfig && event.trace.guardrail && stopReasonRaw === 'guardrail_intervened') {
+                for (const redactionEvent of this._generateRedactionEvents(event.trace.guardrail)) {
+                    events.push(redactionEvent);
+                }
+            }
+        }
         events.push(metadataEvent);
         return events;
     }
@@ -631,10 +861,12 @@ export class BedrockModel extends Model {
      * Maps a Bedrock event to SDK streaming events.
      *
      * @param chunk - Bedrock event chunk
-     * @returns Array of SDK streaming events
+     * @param lastStopReason - Stop reason from previous messageStop event
+     * @returns Object containing events array and optional stopReason
      */
-    _mapStreamedBedrockEventToSDKEvent(chunk) {
+    _mapStreamedBedrockEventToSDKEvent(chunk, lastStopReason) {
         const events = [];
+        let stopReason = lastStopReason;
         // Extract the event type key
         const eventType = ensureDefined(Object.keys(chunk)[0], 'eventType');
         const eventData = chunk[eventType];
@@ -695,6 +927,17 @@ export class BedrockModel extends Model {
                             events.push({ type: 'modelContentBlockDeltaEvent', delta: reasoningDelta });
                         }
                     },
+                    citationsContent: (block) => {
+                        if (!block)
+                            return;
+                        const mapped = this._mapBedrockCitationsData(block);
+                        const delta = {
+                            type: 'citationsDelta',
+                            citations: mapped.citations,
+                            content: mapped.content,
+                        };
+                        events.push({ type: 'modelContentBlockDeltaEvent', delta });
+                    },
                 };
                 for (const key in delta) {
                     if (key in deltaHandlers) {
@@ -717,6 +960,7 @@ export class BedrockModel extends Model {
             case 'messageStop': {
                 const data = eventData;
                 const stopReasonRaw = ensureDefined(data.stopReason, 'messageStop.stopReason');
+                stopReason = stopReasonRaw;
                 const event = {
                     type: 'modelMessageStopEvent',
                     stopReason: this._transformStopReason(stopReasonRaw, data),
@@ -754,6 +998,12 @@ export class BedrockModel extends Model {
                 }
                 if (data.trace) {
                     event.trace = data.trace;
+                    // Check for blocked guardrails in trace and emit redaction events
+                    if (this._config.guardrailConfig && data.trace.guardrail && lastStopReason === 'guardrail_intervened') {
+                        for (const redactionEvent of this._generateRedactionEvents(data.trace.guardrail)) {
+                            events.push(redactionEvent);
+                        }
+                    }
                 }
                 events.push(event);
                 break;
@@ -774,7 +1024,7 @@ export class BedrockModel extends Model {
                 logger.warn(`event_type=<${eventType}> | unsupported bedrock event type`);
                 break;
         }
-        return events;
+        return stopReason !== undefined ? { events, stopReason } : { events };
     }
     /**
      * Transforms a Bedrock stop reason into the SDK's format.
@@ -803,6 +1053,144 @@ export class BedrockModel extends Model {
         }
         return mappedStopReason;
     }
+    /**
+     * Maps a Bedrock object-key citation location to the SDK's type-field format.
+     *
+     * Bedrock uses object-key discrimination (`{ documentChar: { ... } }`) while the SDK uses
+     * type-field discrimination (`{ type: 'documentChar', ... }`). Also normalizes Bedrock's
+     * `searchResultLocation` key to the shorter `searchResult`.
+     *
+     * @param bedrockLocation - Bedrock citation location with object-key discrimination
+     * @returns SDK CitationLocation with type field discrimination
+     */
+    _mapBedrockCitationLocation(bedrockLocation) {
+        if (bedrockLocation.documentChar) {
+            const loc = bedrockLocation.documentChar;
+            return { type: 'documentChar', documentIndex: loc.documentIndex, start: loc.start, end: loc.end };
+        }
+        if (bedrockLocation.documentPage) {
+            const loc = bedrockLocation.documentPage;
+            return { type: 'documentPage', documentIndex: loc.documentIndex, start: loc.start, end: loc.end };
+        }
+        if (bedrockLocation.documentChunk) {
+            const loc = bedrockLocation.documentChunk;
+            return { type: 'documentChunk', documentIndex: loc.documentIndex, start: loc.start, end: loc.end };
+        }
+        if (bedrockLocation.searchResultLocation) {
+            const loc = bedrockLocation.searchResultLocation;
+            return { type: 'searchResult', searchResultIndex: loc.searchResultIndex, start: loc.start, end: loc.end };
+        }
+        if (bedrockLocation.web) {
+            const loc = bedrockLocation.web;
+            return { type: 'web', url: loc.url, ...(loc.domain && { domain: loc.domain }) };
+        }
+        logger.warn(`citation_location=<${JSON.stringify(bedrockLocation)}> | unknown citation location type`);
+        return undefined;
+    }
+    /**
+     * Maps a Bedrock CitationsContentBlock to SDK CitationsBlockData.
+     *
+     * @param bedrockData - Bedrock CitationsContentBlock
+     * @returns SDK CitationsBlockData with type-field CitationLocations
+     */
+    _mapBedrockCitationsData(bedrockData) {
+        return {
+            citations: (bedrockData.citations ?? [])
+                .map((citation) => {
+                const location = citation.location ? this._mapBedrockCitationLocation(citation.location) : undefined;
+                if (!location)
+                    return undefined;
+                return {
+                    source: citation.source ?? '',
+                    title: citation.title ?? '',
+                    sourceContent: (citation.sourceContent ?? []).map((sc) => ({ text: sc.text })),
+                    location,
+                };
+            })
+                .filter((c) => c !== undefined),
+            content: (bedrockData.content ?? []).map((gc) => ({ text: gc.text })),
+        };
+    }
+    /**
+     * Maps an SDK Citation to Bedrock's Citation format.
+     *
+     * @param citation - SDK Citation with type-field location
+     * @returns Bedrock Citation with object-key location
+     */
+    _mapCitationToBedrock(citation) {
+        return {
+            location: this._mapCitationLocationToBedrock(citation.location),
+            sourceContent: citation.sourceContent.map((sc) => ({ text: sc.text })),
+            source: citation.source,
+            title: citation.title,
+        };
+    }
+    /**
+     * Maps an SDK CitationLocation to Bedrock's object-key format.
+     *
+     * @param location - SDK CitationLocation with type field
+     * @returns Bedrock CitationLocation with object-key discrimination
+     */
+    _mapCitationLocationToBedrock(location) {
+        switch (location.type) {
+            case 'documentChar': {
+                const { type: _, ...fields } = location;
+                return { documentChar: fields };
+            }
+            case 'documentPage': {
+                const { type: _, ...fields } = location;
+                return { documentPage: fields };
+            }
+            case 'documentChunk': {
+                const { type: _, ...fields } = location;
+                return { documentChunk: fields };
+            }
+            case 'searchResult': {
+                const { type: _, ...fields } = location;
+                return { searchResultLocation: fields };
+            }
+            case 'web':
+                return { web: { url: location.url, ...(location.domain && { domain: location.domain }) } };
+            default:
+                return location;
+        }
+    }
+    /**
+     * Generate redaction events based on guardrail configuration.
+     *
+     * @param guardrailData - The guardrail trace assessment data
+     * @returns Array of redaction events to emit
+     */
+    _generateRedactionEvents(guardrailData) {
+        const events = [];
+        const redaction = this._config.guardrailConfig?.redaction;
+        // Default: redact input is true unless explicitly set to false
+        if (redaction?.input !== false) {
+            logger.debug('redacting input due to guardrail');
+            events.push({
+                type: 'modelRedactionEvent',
+                inputRedaction: {
+                    replaceContent: redaction?.inputMessage ?? DEFAULT_REDACT_INPUT_MESSAGE,
+                },
+            });
+        }
+        // Only redact output if explicitly enabled
+        if (redaction?.output) {
+            logger.debug('redacting output due to guardrail');
+            const outputRedactionEvent = {
+                type: 'modelRedactionEvent',
+                outputRedaction: {
+                    replaceContent: redaction?.outputMessage ?? DEFAULT_REDACT_OUTPUT_MESSAGE,
+                },
+            };
+            // Include the original model output if available
+            if (guardrailData.modelOutput && guardrailData.modelOutput.length > 0) {
+                outputRedactionEvent.outputRedaction.redactedContent = guardrailData.modelOutput.join('');
+            }
+            events.push(outputRedactionEvent);
+        }
+        return events;
+    }
 }
 /**
  * Adds middleware to override the Authorization header with a Bearer token.