@strands-agents/sdk 1.18.0 → 1.19.0

package/dist/src/models/anthropic.js

@@ -1,7 +1,7 @@
 import Anthropic, {} from '@anthropic-ai/sdk';
 import { Model, resolveConfigMetadata, resolveCacheSection, } from '../models/model.js';
 import { createEmptyUsage } from '../models/streaming.js';
-import { ContextWindowOverflowError, ModelThrottledError, normalizeError } from '../errors.js';
+import { ContextWindowOverflowError, ModelError, ModelThrottledError, normalizeError } from '../errors.js';
 import { encodeBase64 } from '../types/media.js';
 import { logger } from '../logging/logger.js';
 import { warnOnce } from '../logging/warn-once.js';
@@ -17,11 +17,52 @@ const CONTEXT_WINDOW_OVERFLOW_ERRORS = [
     'input length exceeds context window',
     'input and output tokens exceed your context limit',
 ];
+// Content blocks for tools Anthropic executes server side. They have no toolUse/toolResult equivalent
+// (the agent never runs them), so they are not streamed.
+const SERVER_TOOL_BLOCK_TYPES = new Set([
+    'bash_code_execution_tool_result',
+    'code_execution_tool_result',
+    'container_upload',
+    'mcp_tool_result',
+    'mcp_tool_use',
+    'server_tool_use',
+    'text_editor_code_execution_tool_result',
+    'tool_search_tool_result',
+    'web_fetch_tool_result',
+    'web_search_tool_result',
+]);
+// Anthropic pauses a long server-side tool turn with stop_reason=pause_turn and expects the paused
+// assistant message to be sent back as-is to resume it. Bounds how many times stream() does so.
+const MAX_PAUSE_TURN_CONTINUATIONS = 10;
 /**
  * `ephemeral` is the only cache type the Anthropic API supports.
  */
 const ANTHROPIC_CACHE_TYPE = 'ephemeral';
 const TEXT_FILE_FORMATS = ['txt', 'md', 'markdown', 'csv', 'json', 'xml', 'html', 'yml', 'yaml', 'js', 'ts', 'py'];
+/**
+ * Validates that `anthropicTools` does not contain function tool definitions.
+ *
+ * @param anthropicTools - The configured server-side tools
+ * @throws Error - When an entry carries an `input_schema`
+ */
+function validateAnthropicTools(anthropicTools) {
+    for (const tool of anthropicTools) {
+        if ('input_schema' in tool) {
+            throw new Error('anthropicTools should not contain function tool definitions. Use the standard tools interface for ' +
+                'function calling tools. anthropicTools is reserved for Anthropic server-side tools like web_search, ' +
+                'web_fetch, and code_execution.');
+        }
+    }
+}
+/**
+ * Copies the numeric fields of an Anthropic usage object; `null` fields leave the existing value in place.
+ */
+function mergeUsage(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        if (typeof value === 'number')
+            target[key] = value;
+    }
+}
 export class AnthropicModel extends Model {
     _config;
     _client;
@@ -33,6 +74,8 @@ export class AnthropicModel extends Model {
             maxTokens: MODEL_DEFAULTS.anthropic.maxTokens,
             ...modelConfig,
         };
+        if (modelConfig.anthropicTools)
+            validateAnthropicTools(modelConfig.anthropicTools);
         if (modelConfig.modelId === undefined) {
             warnOnce(logger, defaultModelWarningMessage(MODEL_DEFAULTS.anthropic.modelId));
         }
@@ -54,6 +97,8 @@ export class AnthropicModel extends Model {
         }
     }
     updateConfig(modelConfig) {
+        if (modelConfig.anthropicTools)
+            validateAnthropicTools(modelConfig.anthropicTools);
         this._config = { ...this._config, ...modelConfig };
     }
     getConfig() {
@@ -93,125 +138,181 @@ export class AnthropicModel extends Model {
             return super.countTokens(messages, options);
         }
     }
+    /**
+     * Streams a conversation with the Anthropic model.
+     *
+     * A server-side tool turn that Anthropic pauses is resumed with follow-up requests inside this call, so
+     * an error thrown by one of those requests can surface after earlier events were already yielded.
+     *
+     * @param messages - Array of conversation messages
+     * @param options - Optional streaming configuration
+     * @returns Async iterable of streaming events
+     */
     async *stream(messages, options) {
         try {
-            const request = this._formatRequest(messages, options);
+            let request = this._formatRequest(messages, options);
             const requestOptions = this._buildRequestOptions();
-            const stream = requestOptions
-                ? this._client.messages.stream(request, requestOptions)
-                : this._client.messages.stream(request);
             const usage = createEmptyUsage();
-            let stopReason = 'endTurn';
-            for await (const event of stream) {
-                switch (event.type) {
-                    case 'message_start': {
-                        usage.inputTokens = event.message.usage.input_tokens;
-                        const rawUsage = event.message.usage;
-                        if (rawUsage.cache_creation_input_tokens !== undefined) {
-                            usage.cacheWriteInputTokens = rawUsage.cache_creation_input_tokens;
-                        }
-                        if (rawUsage.cache_read_input_tokens !== undefined) {
-                            usage.cacheReadInputTokens = rawUsage.cache_read_input_tokens;
-                        }
-                        yield {
-                            type: 'modelMessageStartEvent',
-                            role: event.message.role,
-                        };
-                        break;
-                    }
-                    case 'content_block_start':
-                        if (event.content_block.type === 'tool_use') {
-                            yield {
-                                type: 'modelContentBlockStartEvent',
-                                start: {
-                                    type: 'toolUseStart',
-                                    name: event.content_block.name,
-                                    toolUseId: event.content_block.id,
-                                },
-                            };
+            let continuations = 0;
+            while (true) {
+                const stream = requestOptions
+                    ? this._client.messages.stream(request, requestOptions)
+                    : this._client.messages.stream(request);
+                let stopReason = 'endTurn';
+                let messageStopped = false;
+                const responseUsage = {};
+                const serverToolBlockIndexes = new Set();
+                for await (const event of stream) {
+                    switch (event.type) {
+                        case 'message_start': {
+                            mergeUsage(responseUsage, event.message.usage);
+                            if (continuations === 0) {
+                                yield {
+                                    type: 'modelMessageStartEvent',
+                                    role: event.message.role,
+                                };
+                            }
+                            break;
                         }
-                        else if (event.content_block.type === 'thinking') {
-                            yield { type: 'modelContentBlockStartEvent' };
-                            if (event.content_block.thinking) {
+                        case 'content_block_start':
+                            if (SERVER_TOOL_BLOCK_TYPES.has(event.content_block.type)) {
+                                serverToolBlockIndexes.add(event.index);
+                                this._logServerToolBlock(event.content_block);
+                                break;
+                            }
+                            if (event.content_block.type === 'tool_use') {
+                                yield {
+                                    type: 'modelContentBlockStartEvent',
+                                    start: {
+                                        type: 'toolUseStart',
+                                        name: event.content_block.name,
+                                        toolUseId: event.content_block.id,
+                                    },
+                                };
+                            }
+                            else if (event.content_block.type === 'thinking') {
+                                yield { type: 'modelContentBlockStartEvent' };
+                                if (event.content_block.thinking) {
+                                    yield {
+                                        type: 'modelContentBlockDeltaEvent',
+                                        delta: {
+                                            type: 'reasoningContentDelta',
+                                            text: event.content_block.thinking,
+                                            signature: event.content_block.signature,
+                                        },
+                                    };
+                                }
+                            }
+                            else if (event.content_block.type === 'redacted_thinking') {
+                                yield { type: 'modelContentBlockStartEvent' };
                                 yield {
                                     type: 'modelContentBlockDeltaEvent',
                                     delta: {
                                         type: 'reasoningContentDelta',
-                                        text: event.content_block.thinking,
-                                        signature: event.content_block.signature,
+                                        redactedContent: event.content_block.data,
                                     },
                                 };
                             }
-                        }
-                        else if (event.content_block.type === 'redacted_thinking') {
-                            yield { type: 'modelContentBlockStartEvent' };
-                            yield {
-                                type: 'modelContentBlockDeltaEvent',
-                                delta: {
-                                    type: 'reasoningContentDelta',
-                                    redactedContent: event.content_block.data,
-                                },
-                            };
-                        }
-                        else {
-                            yield { type: 'modelContentBlockStartEvent' };
-                            if (event.content_block.type === 'text' && event.content_block.text) {
+                            else {
+                                yield { type: 'modelContentBlockStartEvent' };
+                                if (event.content_block.type === 'text' && event.content_block.text) {
+                                    yield {
+                                        type: 'modelContentBlockDeltaEvent',
+                                        delta: { type: 'textDelta', text: event.content_block.text },
+                                    };
+                                }
+                            }
+                            break;
+                        case 'content_block_delta':
+                            if (serverToolBlockIndexes.has(event.index))
+                                break;
+                            if (event.delta.type === 'text_delta') {
                                 yield {
                                     type: 'modelContentBlockDeltaEvent',
-                                    delta: { type: 'textDelta', text: event.content_block.text },
+                                    delta: { type: 'textDelta', text: event.delta.text },
                                 };
                             }
-                        }
-                        break;
-                    case 'content_block_delta':
-                        if (event.delta.type === 'text_delta') {
-                            yield {
-                                type: 'modelContentBlockDeltaEvent',
-                                delta: { type: 'textDelta', text: event.delta.text },
-                            };
-                        }
-                        else if (event.delta.type === 'input_json_delta') {
-                            yield {
-                                type: 'modelContentBlockDeltaEvent',
-                                delta: { type: 'toolUseInputDelta', input: event.delta.partial_json },
-                            };
-                        }
-                        else if (event.delta.type === 'thinking_delta') {
-                            yield {
-                                type: 'modelContentBlockDeltaEvent',
-                                delta: { type: 'reasoningContentDelta', text: event.delta.thinking },
-                            };
-                        }
-                        else if (event.delta.type === 'signature_delta') {
-                            yield {
-                                type: 'modelContentBlockDeltaEvent',
-                                delta: { type: 'reasoningContentDelta', signature: event.delta.signature },
-                            };
-                        }
-                        break;
-                    case 'content_block_stop':
-                        yield { type: 'modelContentBlockStopEvent' };
-                        break;
-                    case 'message_delta':
-                        if (event.usage) {
-                            usage.outputTokens = event.usage.output_tokens;
-                        }
-                        if (event.delta.stop_reason) {
-                            stopReason = this._mapStopReason(event.delta.stop_reason);
-                        }
-                        break;
-                    case 'message_stop':
-                        usage.totalTokens = usage.inputTokens + usage.outputTokens;
-                        yield {
-                            type: 'modelMetadataEvent',
-                            usage,
-                        };
-                        yield {
-                            type: 'modelMessageStopEvent',
-                            stopReason,
-                        };
-                        break;
+                            else if (event.delta.type === 'citations_delta') {
+                                const citation = this._formatCitation(event.delta.citation);
+                                if (citation) {
+                                    yield {
+                                        type: 'modelContentBlockDeltaEvent',
+                                        delta: { type: 'citationsDelta', citations: [citation], content: [] },
+                                    };
+                                }
+                            }
+                            else if (event.delta.type === 'input_json_delta') {
+                                yield {
+                                    type: 'modelContentBlockDeltaEvent',
+                                    delta: { type: 'toolUseInputDelta', input: event.delta.partial_json },
+                                };
+                            }
+                            else if (event.delta.type === 'thinking_delta') {
+                                yield {
+                                    type: 'modelContentBlockDeltaEvent',
+                                    delta: { type: 'reasoningContentDelta', text: event.delta.thinking },
+                                };
+                            }
+                            else if (event.delta.type === 'signature_delta') {
+                                yield {
+                                    type: 'modelContentBlockDeltaEvent',
+                                    delta: { type: 'reasoningContentDelta', signature: event.delta.signature },
+                                };
+                            }
+                            break;
+                        case 'content_block_stop':
+                            if (serverToolBlockIndexes.delete(event.index))
+                                break;
+                            yield { type: 'modelContentBlockStopEvent' };
+                            break;
+                        case 'message_delta':
+                            if (event.usage) {
+                                // Cumulative within one response; fields Anthropic omits keep their message_start value.
+                                mergeUsage(responseUsage, event.usage);
+                            }
+                            if (event.delta.stop_reason) {
+                                stopReason = this._mapStopReason(event.delta.stop_reason);
+                            }
+                            break;
+                        case 'message_stop':
+                            messageStopped = true;
+                            break;
+                    }
+                }
+                // A stream that ends without message_stop is incomplete; emit no stop event so the caller can tell.
+                if (!messageStopped)
+                    return;
+                usage.inputTokens += responseUsage.input_tokens ?? 0;
+                usage.outputTokens += responseUsage.output_tokens ?? 0;
+                if (responseUsage.cache_creation_input_tokens !== undefined) {
+                    usage.cacheWriteInputTokens = (usage.cacheWriteInputTokens ?? 0) + responseUsage.cache_creation_input_tokens;
+                }
+                if (responseUsage.cache_read_input_tokens !== undefined) {
+                    usage.cacheReadInputTokens = (usage.cacheReadInputTokens ?? 0) + responseUsage.cache_read_input_tokens;
+                }
+                if (stopReason === 'pauseTurn') {
+                    if (continuations >= MAX_PAUSE_TURN_CONTINUATIONS) {
+                        throw new ModelError(`server-side tool turn did not complete after ${continuations} continuations`);
+                    }
+                    continuations++;
+                    const pausedMessage = await stream.finalMessage();
+                    request = {
+                        ...request,
+                        messages: [...request.messages, { role: 'assistant', content: pausedMessage.content }],
+                    };
+                    logger.debug(`continuation=<${continuations}> | resuming paused server-side tool turn`);
+                    continue;
                 }
+                usage.totalTokens = usage.inputTokens + usage.outputTokens;
+                yield {
+                    type: 'modelMetadataEvent',
+                    usage,
+                };
+                yield {
+                    type: 'modelMessageStopEvent',
+                    stopReason,
+                };
+                return;
             }
         }
         catch (unknownError) {
@@ -342,29 +443,38 @@ export class AnthropicModel extends Model {
             if (system !== undefined)
                 request.system = system;
         }
-        if (options?.toolSpecs?.length) {
-            const tools = options.toolSpecs.map((tool) => ({
-                name: tool.name,
-                description: tool.description,
-                input_schema: tool.inputSchema,
-            }));
-            // A cache_control on the last tool caches all of them, so one cache point suffices.
-            const toolsCache = this._cacheSection('toolsTTL');
-            const lastTool = tools[tools.length - 1];
-            if (toolsCache.enabled && lastTool) {
-                lastTool.cache_control = this._formatCacheControl(toolsCache.ttl);
+        const tools = (options?.toolSpecs ?? []).map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.inputSchema,
+        }));
+        const serverTools = [
+            ...(this._config.anthropicTools ?? []),
+            ...(this._config.params?.tools ?? []),
+        ];
+        // Forcing a tool means this turn must call a function tool, so server tools are left out.
+        if (!options?.toolChoice || 'auto' in options.toolChoice) {
+            // Copied so the cache_control below never lands on the caller's config.
+            tools.push(...serverTools.map((tool) => ({ ...tool })));
+        }
+        else if (serverTools.length > 0) {
+            logger.warn(`tool_choice=<${Object.keys(options.toolChoice)[0]}>, server_tools=<${serverTools.map((tool) => tool.name).join(',')}> | forced tool call, omitting server tools`);
+        }
+        // A cache_control on the last tool caches all of them, so one cache point suffices.
+        const toolsCache = this._cacheSection('toolsTTL');
+        const lastTool = tools[tools.length - 1];
+        if (toolsCache.enabled && lastTool) {
+            lastTool.cache_control = this._formatCacheControl(toolsCache.ttl);
+        }
+        if (tools.length > 0 && options?.toolChoice) {
+            if ('auto' in options.toolChoice) {
+                request.tool_choice = { type: 'auto' };
             }
-            request.tools = tools;
-            if (options.toolChoice) {
-                if ('auto' in options.toolChoice) {
-                    request.tool_choice = { type: 'auto' };
-                }
-                else if ('any' in options.toolChoice) {
-                    request.tool_choice = { type: 'any' };
-                }
-                else if ('tool' in options.toolChoice) {
-                    request.tool_choice = { type: 'tool', name: options.toolChoice.tool.name };
-                }
+            else if ('any' in options.toolChoice) {
+                request.tool_choice = { type: 'any' };
+            }
+            else if ('tool' in options.toolChoice) {
+                request.tool_choice = { type: 'tool', name: options.toolChoice.tool.name };
             }
         }
         if (this._config.temperature !== undefined)
@@ -375,6 +485,11 @@ export class AnthropicModel extends Model {
             request.stop_sequences = this._config.stopSequences;
         if (this._config.params)
             Object.assign(request, this._config.params);
+        // params.tools is already merged into tools above; never let it bypass the forced-turn rule.
+        if (tools.length > 0)
+            request.tools = tools;
+        else
+            delete request.tools;
         return request;
     }
     _formatMessages(messages, messagesCache = { enabled: false }, cacheTargetMessage = -1, dynamicTrailingBlocks = 0) {
@@ -433,7 +548,8 @@ export class AnthropicModel extends Model {
             logger.warn(`count=<${strippedCachePoints}> | stripped extra cache points, cacheConfig keeps the first cache ` +
                 `point in the last user message; unset cacheConfig to keep every cache point`);
         }
-        return formatted;
+        // The API rejects an empty message anywhere but the trailing assistant turn.
+        return formatted.filter((msg) => msg.content.length > 0);
     }
     _isCacheableBlock(block) {
         return ['text', 'image', 'tool_use', 'tool_result', 'document'].includes(block.type);
@@ -574,12 +690,108 @@ export class AnthropicModel extends Model {
                     };
                 }
                 return undefined;
+            case 'citationsBlock': {
+                const text = block.content.map((generated) => generated.text).join('');
+                return text ? { type: 'text', text } : undefined;
+            }
             case 'cachePointBlock':
                 return undefined;
             default:
                 return undefined;
         }
     }
+    /**
+     * Maps an Anthropic citation onto a Strands citation.
+     *
+     * @param citation - Citation from a `citations_delta` event
+     * @returns The mapped citation, or `undefined` when the location type has no Strands equivalent
+     */
+    _formatCitation(citation) {
+        const citedText = 'cited_text' in citation && citation.cited_text ? [{ text: citation.cited_text }] : [];
+        switch (citation.type) {
+            case 'web_search_result_location': {
+                const url = citation.url ?? '';
+                let domain;
+                try {
+                    domain = new URL(url).hostname;
+                }
+                catch {
+                    domain = undefined;
+                }
+                return {
+                    location: { type: 'web', url, ...(domain ? { domain } : {}) },
+                    source: url,
+                    sourceContent: citedText,
+                    title: citation.title ?? '',
+                };
+            }
+            case 'search_result_location':
+                return {
+                    location: {
+                        type: 'searchResult',
+                        searchResultIndex: citation.search_result_index,
+                        start: citation.start_block_index,
+                        end: citation.end_block_index,
+                    },
+                    source: citation.source,
+                    sourceContent: citedText,
+                    title: citation.title ?? '',
+                };
+            case 'char_location':
+                return {
+                    location: {
+                        type: 'documentChar',
+                        documentIndex: citation.document_index,
+                        start: citation.start_char_index,
+                        end: citation.end_char_index,
+                    },
+                    source: citation.file_id ?? '',
+                    sourceContent: citedText,
+                    title: citation.document_title ?? '',
+                };
+            case 'page_location':
+                return {
+                    location: {
+                        type: 'documentPage',
+                        documentIndex: citation.document_index,
+                        start: citation.start_page_number,
+                        end: citation.end_page_number,
+                    },
+                    source: citation.file_id ?? '',
+                    sourceContent: citedText,
+                    title: citation.document_title ?? '',
+                };
+            case 'content_block_location':
+                return {
+                    location: {
+                        type: 'documentChunk',
+                        documentIndex: citation.document_index,
+                        start: citation.start_block_index,
+                        end: citation.end_block_index,
+                    },
+                    source: citation.file_id ?? '',
+                    sourceContent: citedText,
+                    title: citation.document_title ?? '',
+                };
+            default:
+                logger.warn(`citation_type=<${citation.type}> | unsupported citation location | skipping`);
+                return undefined;
+        }
+    }
+    /**
+     * Logs a skipped server-side tool block, at warn level when the tool returned an error.
+     *
+     * @param contentBlock - The `content_block` of a `content_block_start` event
+     */
+    _logServerToolBlock(contentBlock) {
+        const errorCode = contentBlock.content?.error_code;
+        if (errorCode !== undefined) {
+            logger.warn(`block_type=<${contentBlock.type}>, error_code=<${errorCode}> | server-side tool failed`);
+        }
+        else {
+            logger.debug(`block_type=<${contentBlock.type}> | skipping server-side tool block`);
+        }
+    }
     _mapStopReason(anthropicReason) {
         switch (anthropicReason) {
             case 'end_turn':