@ai-sdk/anthropic 4.0.78 → 4.0.79

package/docs/05-anthropic.mdx

@@ -1420,6 +1420,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.79",
   "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.59"
   },
   "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,
+      },
     };
   }
 
@@ -1253,31 +1255,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,
@@ -1926,6 +1942,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 +2363,7 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
                     });
 
                     for (const result of part.content) {
+                      hasWebSearchResults = true;
                       controller.enqueue({
                         type: 'source',
                         sourceType: 'url',
@@ -2587,11 +2606,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 +2850,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 +3121,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

@@ -515,8 +515,12 @@ 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({

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,
+  };
+}