@ai-sdk/anthropic 4.0.78 → 4.0.80

package/docs/05-anthropic.mdx

@@ -742,6 +742,13 @@ room for both, the provider adds `budgetTokens` to `maxOutputTokens` when
 setting `max_tokens`. For known models, the combined value is capped at the
 model's maximum output token limit.
 
+With manual thinking (`thinking.type: 'enabled'`), a `required` or named
+`toolChoice` falls back to `auto` with a warning. For a named tool choice, only
+the selected tool is sent. This also applies when the top-level `reasoning`
+option enables manual thinking, including when structured output uses the
+internal JSON response tool. Tool use is no longer guaranteed: instruct the
+model to use the tool in your prompt and verify that a tool call was made.
+
 See [AI SDK UI: Chatbot](/docs/ai-sdk-ui/chatbot#reasoning) for more details
 on how to integrate reasoning into your chatbot.
 
@@ -1420,6 +1427,40 @@ const result = await generateText({
   settings](https://console.anthropic.com/settings/privacy).
 </Note>
 
+#### Sources and Citations
+
+`result.sources` and source stream events expose web-search results. Inline
+references are attached separately to generated text as `part.citations`, and
+to streamed text as `text-end.citations`. This shared citation representation
+includes the referenced URL or document and its supporting passage. If web-search
+results are unavailable, web citations also provide source references for
+compatibility. Indexed document references retain their existing document source
+parts when the original prompt supplies document information.
+
+Raw citations remain available as
+`text.providerMetadata.anthropic.citations`, including on streamed `text-end`
+events. Import `AnthropicTextProviderMetadata` and `AnthropicCitation` for typed
+access. `AnthropicCitation` is a union of `web_search_result_location`,
+`search_result_location`, `page_location`, `char_location`, and
+`content_block_location`. Document page, character, and block locations refer to
+the source document, rather than the generated answer.
+
+```ts
+import type { AnthropicTextProviderMetadata } from '@ai-sdk/anthropic';
+
+for (const part of result.content) {
+  if (part.type === 'text') {
+    console.log(part.citations);
+    const metadata = part.providerMetadata as
+      | AnthropicTextProviderMetadata
+      | undefined;
+    for (const citation of metadata?.anthropic.citations ?? []) {
+      console.log(citation.type, citation.cited_text);
+    }
+  }
+}
+```
+
 #### Configuration Options
 
 Use `webSearch_20260318` for dynamic filtering and response inclusion control.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/anthropic",
-  "version": "4.0.78",
+  "version": "4.0.80",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,8 +35,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.26",
-    "@ai-sdk/provider-utils": "5.0.58"
+    "@ai-sdk/provider": "4.0.27",
+    "@ai-sdk/provider-utils": "5.0.60"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.4",

package/src/anthropic-api.ts

@@ -594,6 +594,7 @@ export type AnthropicSpeed = 'fast' | 'standard';
 
 export type AnthropicToolChoice =
   | { type: 'auto' | 'any'; disable_parallel_tool_use?: boolean }
+  | { type: 'none' }
   | { type: 'tool'; name: string; disable_parallel_tool_use?: boolean };
 
 export type AnthropicContainer = {

package/src/anthropic-batch.ts

@@ -1,3 +1,4 @@
+import { mapAnthropicCitation } from './map-anthropic-citation';
 import {
   InvalidArgumentError,
   InvalidResponseDataError,
@@ -44,8 +45,8 @@ import {
 } from './anthropic-api';
 import { anthropicFailedResponseHandler } from './anthropic-error';
 import {
-  AnthropicLanguageModel,
   createCitationSource,
+  AnthropicLanguageModel,
   type AnthropicLanguageModelConfig,
 } from './anthropic-language-model';
 import {
@@ -746,6 +747,12 @@ function convertAnthropicBatchResponse(
   > = {};
   const serverToolCalls: Record<string, string> = {};
 
+  const hasWebSearchResults = response.content.some(
+    part =>
+      part.type === 'web_search_tool_result' &&
+      Array.isArray(part.content) &&
+      part.content.length > 0,
+  );
   for (const part of response.content) {
     switch (part.type) {
       case 'text':
@@ -754,6 +761,12 @@ function convertAnthropicBatchResponse(
         content.push({
           type: 'text',
           text: part.text,
+          ...(citations != null &&
+            citations.length > 0 && {
+              citations: citations.map(citation =>
+                mapAnthropicCitation(citation, []),
+              ),
+            }),
           ...(citations != null &&
             citations.length > 0 && {
               providerMetadata: {
@@ -762,12 +775,12 @@ function convertAnthropicBatchResponse(
             }),
         });
         for (const citation of part.citations ?? []) {
-          // Batch result retrieval does not include the original prompt's
-          // document ordering, so indexed document citations cannot be
-          // normalized safely. Preserve them above as provider metadata.
-          const source = createCitationSource(citation, [], generateId);
-          if (source != null) {
-            content.push(source);
+          if (
+            citation.type === 'web_search_result_location' &&
+            !hasWebSearchResults
+          ) {
+            const source = createCitationSource(citation, [], generateId);
+            if (source) content.push(source);
           }
         }
         break;

package/src/anthropic-language-model.ts

@@ -46,6 +46,8 @@ import type {
   AnthropicMessageMetadata,
   AnthropicUsageIteration,
 } from './anthropic-message-metadata';
+import { mapAnthropicCitation } from './map-anthropic-citation';
+import type { AnthropicTextProviderMetadata } from './anthropic-provider-metadata';
 import {
   anthropicChunkSchema,
   anthropicResponseSchema,
@@ -130,8 +132,8 @@ export function createCitationSource(
 ): LanguageModelV4Source | undefined {
   if (citation.type === 'web_search_result_location') {
     return {
-      type: 'source' as const,
-      sourceType: 'url' as const,
+      type: 'source',
+      sourceType: 'url',
       id: generateId(),
       url: citation.url,
       title: citation.title ?? undefined,
@@ -140,7 +142,7 @@ export function createCitationSource(
           citedText: citation.cited_text,
           encryptedIndex: citation.encrypted_index,
         },
-      } satisfies SharedV4ProviderMetadata,
+      },
     };
   }
 
@@ -253,6 +255,12 @@ export type AnthropicLanguageModelConfig = {
     args: Record<string, any>,
     betas: Set<string>,
   ) => Record<string, any>;
+  transformRequestHeaders?: (
+    headers: Record<string, string | undefined>,
+    providerOptions: LanguageModelV4CallOptions['providerOptions'],
+  ) =>
+    | Record<string, string | undefined>
+    | PromiseLike<Record<string, string | undefined>>;
   supportedUrls?: () => LanguageModelV4['supportedUrls'];
   generateId?: () => string;
   supportsNativeStructuredOutput?: boolean;
@@ -1065,7 +1073,8 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
             supportsStructuredOutput: false,
             supportsStrictTools,
             defaultEagerInputStreaming,
-            rejectsForcedToolUse,
+            rejectsForcedToolUse:
+              rejectsForcedToolUse || thinkingType === 'enabled',
           }
         : {
             tools: tools ?? [],
@@ -1075,7 +1084,8 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
             supportsStructuredOutput,
             supportsStrictTools,
             defaultEagerInputStreaming,
-            rejectsForcedToolUse,
+            rejectsForcedToolUse:
+              rejectsForcedToolUse || thinkingType === 'enabled',
           },
     );
 
@@ -1119,15 +1129,21 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
   private async getHeaders({
     betas,
     headers,
+    providerOptions,
   }: {
     betas: Set<string>;
     headers: Record<string, string | undefined> | undefined;
+    providerOptions: LanguageModelV4CallOptions['providerOptions'];
   }) {
-    return combineHeaders(
+    const combinedHeaders = combineHeaders(
       this.config.headers ? await resolve(this.config.headers) : undefined,
       headers,
       betas.size > 0 ? { 'anthropic-beta': Array.from(betas).join(',') } : {},
     );
+
+    return this.config.transformRequestHeaders
+      ? this.config.transformRequestHeaders(combinedHeaders, providerOptions)
+      : combinedHeaders;
   }
 
   private async getBetasFromHeaders(
@@ -1238,7 +1254,11 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
       rawValue: rawResponse,
     } = await postJsonToApi({
       url: this.buildRequestUrl(false),
-      headers: await this.getHeaders({ betas, headers: options.headers }),
+      headers: await this.getHeaders({
+        betas,
+        headers: options.headers,
+        providerOptions: options.providerOptions,
+      }),
       body: this.transformRequestBody(args, betas),
       failedResponseHandler: anthropicFailedResponseHandler,
       successfulResponseHandler: createJsonResponseHandler(
@@ -1253,31 +1273,45 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
     const serverToolCalls: Record<string, string> = {}; // tool_use_id -> provider tool name
     let isJsonResponseFromTool = false;
 
+    const hasWebSearchResults = response.content.some(
+      part =>
+        part.type === 'web_search_tool_result' &&
+        Array.isArray(part.content) &&
+        part.content.length > 0,
+    );
     // map response content to content array
     for (const part of response.content) {
       switch (part.type) {
         case 'text': {
           if (!usesJsonResponseTool) {
-            const webSearchCitations = part.citations?.filter(
-              citation => citation.type === 'web_search_result_location',
-            );
+            const citations = part.citations ?? [];
 
             content.push({
               type: 'text',
               text: part.text,
-              ...(webSearchCitations != null &&
-                webSearchCitations.length > 0 && {
-                  providerMetadata: {
-                    anthropic: {
-                      citations: webSearchCitations,
-                    },
+              ...(citations.length > 0 && {
+                citations: citations.map(citation =>
+                  mapAnthropicCitation(citation, citationDocuments),
+                ),
+              }),
+              ...(citations.length > 0 && {
+                providerMetadata: {
+                  anthropic: {
+                    citations,
                   },
-                }),
+                } satisfies AnthropicTextProviderMetadata,
+              }),
             });
 
             // Process citations if present
             if (part.citations) {
               for (const citation of part.citations) {
+                if (
+                  citation.type === 'web_search_result_location' &&
+                  hasWebSearchResults
+                ) {
+                  continue;
+                }
                 const source = createCitationSource(
                   citation,
                   citationDocuments,
@@ -1864,7 +1898,11 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
     const url = this.buildRequestUrl(true);
     const { responseHeaders, value: response } = await postJsonToApi({
       url,
-      headers: await this.getHeaders({ betas, headers: options.headers }),
+      headers: await this.getHeaders({
+        betas,
+        headers: options.headers,
+        providerOptions: options.providerOptions,
+      }),
       body: this.transformRequestBody(body, betas),
       failedResponseHandler: anthropicFailedResponseHandler,
       successfulResponseHandler:
@@ -1926,6 +1964,8 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
     let safeguardResults: AnthropicMessageMetadata['safeguardResults'];
     let container: AnthropicMessageMetadata['container'] | null = null;
     let isJsonResponseFromTool = false;
+    let hasWebSearchResults = false;
+    const fallbackWebCitations: Citation[] = [];
     let isMessageOpen = false;
     let activeMessageId: string | null | undefined;
     let hasInvalidMessageSequence = false;
@@ -2345,6 +2385,7 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
                     });
 
                     for (const result of part.content) {
+                      hasWebSearchResults = true;
                       controller.enqueue({
                         type: 'source',
                         sourceType: 'url',
@@ -2587,11 +2628,14 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
                       type: 'text-end',
                       id: String(value.index),
                       ...(contentBlock.citations.length > 0 && {
+                        citations: contentBlock.citations.map(citation =>
+                          mapAnthropicCitation(citation, citationDocuments),
+                        ),
                         providerMetadata: {
                           anthropic: {
                             citations: contentBlock.citations,
                           },
-                        },
+                        } satisfies AnthropicTextProviderMetadata,
                       }),
                     });
                     break;
@@ -2828,21 +2872,19 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
                   const citation = value.delta.citation;
                   const contentBlock = contentBlocks[value.index];
 
-                  if (
-                    contentBlock?.type === 'text' &&
-                    citation.type === 'web_search_result_location'
-                  ) {
+                  if (contentBlock?.type === 'text') {
                     contentBlock.citations.push(citation);
                   }
 
-                  const source = createCitationSource(
-                    citation,
-                    citationDocuments,
-                    generateId,
-                  );
-
-                  if (source) {
-                    controller.enqueue(source);
+                  if (citation.type === 'web_search_result_location') {
+                    fallbackWebCitations.push(citation);
+                  } else {
+                    const source = createCitationSource(
+                      citation,
+                      citationDocuments,
+                      generateId,
+                    );
+                    if (source) controller.enqueue(source);
                   }
 
                   return;
@@ -3101,6 +3143,17 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
                 providerMetadata[providerOptionsName] = anthropicMetadata;
               }
 
+              if (!hasWebSearchResults) {
+                for (const citation of fallbackWebCitations) {
+                  const source = createCitationSource(
+                    citation,
+                    citationDocuments,
+                    generateId,
+                  );
+                  if (source) controller.enqueue(source);
+                }
+              }
+              fallbackWebCitations.length = 0;
               controller.enqueue({
                 type: 'finish',
                 finishReason,

package/src/anthropic-prepare-tools.ts

@@ -56,9 +56,9 @@ export async function prepareTools({
   defaultEagerInputStreaming?: boolean;
 
   /**
-   * Whether the model rejects forced tool use (`tool_choice` `any` or a
-   * named tool). When true, `required` and `tool` tool choices fall back to
-   * `auto` with a warning.
+   * Whether the model or thinking configuration rejects forced tool use
+   * (`tool_choice` `any` or a named tool). When true, `required` and `tool`
+   * tool choices fall back to `auto` with a warning.
    */
   rejectsForcedToolUse?: boolean;
 }): Promise<{
@@ -492,7 +492,7 @@ export async function prepareTools({
           type: 'unsupported',
           feature: 'toolChoice',
           details:
-            `toolChoice 'required' is not supported by this model because it rejects forced tool use. ` +
+            `toolChoice 'required' is not supported with this model or thinking configuration. ` +
             `Using 'auto' instead. Instruct the model to use a tool in the prompt and verify that a tool call was made.`,
         });
         return {
@@ -515,15 +515,19 @@ export async function prepareTools({
         betas,
       };
     case 'none':
-      // Anthropic does not support 'none' tool choice, so we remove the tools:
-      return { tools: undefined, toolChoice: undefined, toolWarnings, betas };
+      return {
+        tools: anthropicTools,
+        toolChoice: { type: 'none' },
+        toolWarnings,
+        betas,
+      };
     case 'tool':
       if (rejectsForcedToolUse) {
         toolWarnings.push({
           type: 'unsupported',
           feature: 'toolChoice',
           details:
-            `toolChoice 'tool' is not supported by this model because it rejects forced tool use. ` +
+            `toolChoice 'tool' is not supported with this model or thinking configuration. ` +
             `Only the '${toolChoice.toolName}' tool is sent with 'auto' tool choice. ` +
             `Instruct the model to use the tool in the prompt and verify that a tool call was made.`,
         });

package/src/anthropic-provider-metadata.ts

@@ -0,0 +1,16 @@
+import type { Citation } from './anthropic-api';
+
+/**
+ * Citation metadata returned by Anthropic for generated text.
+ */
+export type AnthropicCitation = Citation;
+
+/**
+ * Anthropic provider metadata attached to generated text that contains
+ * citations.
+ */
+export type AnthropicTextProviderMetadata = {
+  anthropic: {
+    citations: AnthropicCitation[];
+  };
+};

package/src/convert-to-anthropic-prompt.ts

@@ -1342,6 +1342,30 @@ export async function convertToAnthropicPrompt({
                 ) {
                   const output = part.output;
 
+                  if (
+                    output.type === 'error-json' ||
+                    (output.type === 'json' &&
+                      output.value != null &&
+                      typeof output.value === 'object' &&
+                      !Array.isArray(output.value) &&
+                      'type' in output.value &&
+                      output.value.type === 'tool_search_tool_result_error')
+                  ) {
+                    anthropicContent.push({
+                      type: 'tool_search_tool_result',
+                      tool_use_id: part.toolCallId,
+                      content: {
+                        type: 'tool_search_tool_result_error',
+                        error_code:
+                          extractErrorValue(output.value).errorCode ??
+                          'unavailable',
+                      },
+                      cache_control: cacheControl,
+                    });
+
+                    break;
+                  }
+
                   if (output.type !== 'json') {
                     warnings.push({
                       type: 'other',

package/src/index.ts

@@ -2,6 +2,10 @@ export type {
   AnthropicMessageMetadata,
   AnthropicUsageIteration,
 } from './anthropic-message-metadata';
+export type {
+  AnthropicCitation,
+  AnthropicTextProviderMetadata,
+} from './anthropic-provider-metadata';
 export type {
   AnthropicLanguageModelOptions,
   /** @deprecated Use `AnthropicLanguageModelOptions` instead. */

package/src/map-anthropic-citation.ts

@@ -0,0 +1,51 @@
+import type { LanguageModelV4Citation } from '@ai-sdk/provider';
+import type { Citation } from './anthropic-api';
+
+export type CitationDocument = {
+  title: string;
+  filename?: string;
+  mediaType: string;
+};
+
+export function mapAnthropicCitation(
+  citation: Citation,
+  documents: Array<CitationDocument>,
+): LanguageModelV4Citation {
+  if (
+    citation.type === 'web_search_result_location' ||
+    citation.type === 'search_result_location'
+  ) {
+    const url =
+      citation.type === 'web_search_result_location'
+        ? citation.url
+        : citation.source;
+    return {
+      source: {
+        type: 'source',
+        sourceType: 'url',
+        id: url,
+        url,
+        title: citation.title ?? undefined,
+        providerMetadata: { anthropic: { ...citation } },
+      },
+      citedText: citation.cited_text,
+    };
+  }
+
+  const document = documents[citation.document_index];
+  return {
+    source: {
+      type: 'source',
+      sourceType: 'document',
+      id: citation.file_id ?? String(citation.document_index),
+      mediaType: document?.mediaType ?? 'text/plain',
+      title:
+        citation.document_title ??
+        document?.title ??
+        `Document ${citation.document_index}`,
+      filename: document?.filename,
+      providerMetadata: { anthropic: { ...citation } },
+    },
+    citedText: citation.cited_text,
+  };
+}