@ai-sdk/anthropic 3.0.136 → 3.0.138

package/docs/05-anthropic.mdx

@@ -152,7 +152,7 @@ The following optional provider options are available for Anthropic models:
 
   - `"outputFormat"`: Use the `output_format` parameter to specify the structured output format.
   - `"jsonTool"`: Use a special `"json"` tool to specify the structured output format.
-  - `"auto"`: Use `"outputFormat"` when supported, otherwise fall back to `"jsonTool"` (default).
+  - `"auto"`: Use `"outputFormat"` when the model and schema support it, otherwise fall back to `"jsonTool"` (default). Schemas with recursive references, open objects, or more than ten optional properties use the JSON-tool fallback to avoid rejected requests or lost data.
 
 - `metadata` _object_
 
@@ -194,10 +194,27 @@ default `"auto"` mode uses native structured outputs through
 `output_config.format`. These models reject forced tool use, so the
 `"jsonTool"` mode cannot be used with them. If you
 request `"jsonTool"` anyway, the provider falls back to `"outputFormat"` and
-emits a warning. Likewise, a `required` or named `toolChoice` is downgraded to
+emits a warning. The same fallback applies when these models are served through
+providers that otherwise default to the JSON tool, such as the Amazon Bedrock
+Anthropic and Google Vertex Anthropic providers. On those providers, schemas
+that native structured outputs cannot represent keep the JSON tool:
+self-referencing schemas, schemas with more than 10 optional properties, and
+schemas with open objects such as maps (`additionalProperties` set to a schema
+or `true`), which native structured outputs would return as `{}`.
+Likewise, a `required` or named `toolChoice` is downgraded to
 `auto` with a warning; instruct the model to use the tool in your prompt and
 verify that a tool call was made.
 
+The JSON-tool fallback limits which application tools are available:
+`toolChoice: 'none'` sends only the internal JSON response tool, and a named tool
+choice sends only that application tool alongside the JSON response tool. The
+fallback can produce a JSON response without calling the named application tool;
+verify the selected call if your application requires it.
+
+When the JSON tool cannot be forced (for example with manual thinking) and the
+model answers in text without calling it, the text of its final answer is
+returned. Text before a tool call is still dropped.
+
 ### Effort
 
 Anthropic introduced an `effort` option with `claude-opus-4-5` that affects thinking, text responses, and function calls. Effort defaults to `high` and you can set it to `medium` or `low` to save tokens and to lower time-to-last-token latency (TTLT). `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-fable-5`, `claude-fable-5-1`, `claude-sonnet-5`, `claude-sonnet-5-5`, and `claude-haiku-5-5` additionally support `xhigh` for maximum reasoning effort.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/anthropic",
-  "version": "3.0.136",
+  "version": "3.0.138",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "3.0.19",
-    "@ai-sdk/provider-utils": "4.0.63"
+    "@ai-sdk/provider-utils": "4.0.64"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

package/src/anthropic-messages-language-model.ts

@@ -63,6 +63,7 @@ import {
 import { CacheControlValidator } from './get-cache-control';
 import { mapAnthropicStopReason } from './map-anthropic-stop-reason';
 import { sanitizeJsonSchema } from './sanitize-json-schema';
+import { supportsNativeStructuredOutputSchema } from './supports-native-structured-output-schema';
 
 function createCitationSource(
   citation: Citation,
@@ -216,6 +217,47 @@ type AnthropicMessagesConfig = {
   supportsStrictTools?: boolean;
 };
 
+const TEXT_OR_THINKING_BLOCK_TYPES = new Set<string>([
+  'redacted_thinking',
+  'text',
+  'thinking',
+]);
+
+function isContinuationStopReason(
+  stopReason: string | null | undefined,
+): boolean {
+  return stopReason === 'pause_turn' || stopReason === 'tool_use';
+}
+
+/**
+ * Text parts to return when the JSON response tool is in use: the text after
+ * the last tool call or result, and only if the tool was never called.
+ */
+function getJsonResponseToolFallbackText<
+  PART extends { type: string; name?: unknown },
+>(
+  content: ReadonlyArray<PART>,
+  stopReason: string | null | undefined,
+): Set<PART> {
+  const text = new Set<PART>();
+  if (isContinuationStopReason(stopReason)) {
+    return text;
+  }
+
+  for (const part of content) {
+    if (part.type === 'tool_use' && part.name === 'json') {
+      return new Set();
+    }
+    if (part.type === 'text') {
+      text.add(part);
+    } else if (!TEXT_OR_THINKING_BLOCK_TYPES.has(part.type)) {
+      text.clear();
+    }
+  }
+
+  return text;
+}
+
 export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
   readonly specificationVersion = 'v3';
 
@@ -407,6 +449,11 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
       (this.config.supportsNativeStructuredOutput ?? true) &&
       modelSupportsStructuredOutput;
 
+    const supportsResponseSchema =
+      responseFormat?.type !== 'json' ||
+      responseFormat.schema == null ||
+      supportsNativeStructuredOutputSchema(responseFormat.schema);
+
     const supportsStrictTools =
       (this.config.supportsStrictTools ?? true) &&
       modelSupportsStructuredOutput;
@@ -415,17 +462,21 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
       anthropicOptions?.structuredOutputMode ?? 'auto';
     let useStructuredOutput =
       structureOutputMode === 'outputFormat' ||
-      (structureOutputMode === 'auto' && supportsStructuredOutput);
+      (structureOutputMode === 'auto' &&
+        supportsStructuredOutput &&
+        supportsResponseSchema);
 
     // The JSON response tool relies on forced tool use, which some models
     // reject (e.g. Opus 5.5, Fable 5.1). Fall back to native structured
-    // outputs when the model supports them.
+    // outputs even when the provider disables them by default (Bedrock,
+    // Vertex), unless they would reject the schema or lose data from it.
     if (
       !useStructuredOutput &&
       rejectsForcedToolUse &&
-      supportsStructuredOutput &&
+      modelSupportsStructuredOutput &&
       responseFormat?.type === 'json' &&
-      responseFormat.schema != null
+      responseFormat.schema != null &&
+      supportsNativeStructuredOutputSchema(responseFormat.schema)
     ) {
       warnings.push({
         type: 'unsupported',
@@ -963,7 +1014,15 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
     } = await prepareTools(
       jsonResponseTool != null
         ? {
-            tools: [...(tools ?? []), jsonResponseTool],
+            tools: [
+              ...(tools ?? []).filter(
+                tool =>
+                  toolChoice?.type !== 'none' &&
+                  (toolChoice?.type !== 'tool' ||
+                    tool.name === toolChoice.toolName),
+              ),
+              jsonResponseTool,
+            ],
             toolChoice: { type: 'required' },
             disableParallelToolUse: true,
             cacheControlValidator,
@@ -1146,11 +1205,20 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
     const serverToolCalls: Record<string, string> = {}; // tool_use_id -> provider tool name
     let isJsonResponseFromTool = false;
 
+    // The JSON response tool call becomes the text, so other text is dropped,
+    // unless the model never called the tool and answered in text instead.
+    const jsonResponseToolFallbackText = usesJsonResponseTool
+      ? getJsonResponseToolFallbackText(response.content, response.stop_reason)
+      : undefined;
+
     // map response content to content array
     for (const part of response.content) {
       switch (part.type) {
         case 'text': {
-          if (!usesJsonResponseTool) {
+          if (
+            jsonResponseToolFallbackText == null ||
+            jsonResponseToolFallbackText.has(part)
+          ) {
             const webSearchCitations = part.citations?.filter(
               citation => citation.type === 'web_search_result_location',
             );
@@ -1793,6 +1861,21 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
     let safeguardResults: AnthropicMessageMetadata['safeguardResults'];
     let container: AnthropicMessageMetadata['container'] | null = null;
     let isJsonResponseFromTool = false;
+    // Text held back while the JSON response tool is in use: it is only the
+    // answer if no tool block follows it and the model never calls the tool.
+    type HeldBackText = { id: string; text: string; citations: Citation[] };
+    const heldBackText: HeldBackText[] = [];
+    const heldBackTextByIndex = new Map<number, HeldBackText>();
+    const createTextEnd = (
+      id: string,
+      citations: Citation[],
+    ): LanguageModelV3StreamPart => ({
+      type: 'text-end',
+      id,
+      ...(citations.length > 0 && {
+        providerMetadata: { anthropic: { citations } },
+      }),
+    });
     let isMessageOpen = false;
     let activeMessageId: string | null | undefined;
     let hasInvalidMessageSequence = false;
@@ -1860,11 +1943,23 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
 
               blockType = contentBlockType;
 
+              // text before a tool call or result is preamble, not the answer:
+              if (!TEXT_OR_THINKING_BLOCK_TYPES.has(contentBlockType)) {
+                heldBackText.length = 0;
+              }
+
               switch (contentBlockType) {
                 case 'text': {
                   // when a json response tool is used, the tool call is returned as text,
-                  // so we ignore the text content:
+                  // so the text content is held back until we know whether it was called:
                   if (usesJsonResponseTool) {
+                    const entry = {
+                      id: String(value.index),
+                      text: '',
+                      citations: [],
+                    };
+                    heldBackText.push(entry);
+                    heldBackTextByIndex.set(value.index, entry);
                     return;
                   }
 
@@ -2414,17 +2509,12 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
 
                 switch (contentBlock.type) {
                   case 'text': {
-                    controller.enqueue({
-                      type: 'text-end',
-                      id: String(value.index),
-                      ...(contentBlock.citations.length > 0 && {
-                        providerMetadata: {
-                          anthropic: {
-                            citations: contentBlock.citations,
-                          },
-                        },
-                      }),
-                    });
+                    controller.enqueue(
+                      createTextEnd(
+                        String(value.index),
+                        contentBlock.citations,
+                      ),
+                    );
                     break;
                   }
 
@@ -2547,8 +2637,12 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
               switch (deltaType) {
                 case 'text_delta': {
                   // when a json response tool is used, the tool call is returned as text,
-                  // so we ignore the text content:
+                  // so the text content is held back until we know whether it was called:
                   if (usesJsonResponseTool) {
+                    const entry = heldBackTextByIndex.get(value.index);
+                    if (entry != null) {
+                      entry.text += value.delta.text;
+                    }
                     return; // excluding the text-start will also exclude the text-end
                   }
 
@@ -2659,11 +2753,13 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
                   const citation = value.delta.citation;
                   const contentBlock = contentBlocks[value.index];
 
-                  if (
-                    contentBlock?.type === 'text' &&
-                    citation.type === 'web_search_result_location'
-                  ) {
-                    contentBlock.citations.push(citation);
+                  if (citation.type === 'web_search_result_location') {
+                    if (contentBlock?.type === 'text') {
+                      contentBlock.citations.push(citation);
+                    }
+                    heldBackTextByIndex
+                      .get(value.index)
+                      ?.citations.push(citation);
                   }
 
                   const source = createCitationSource(
@@ -2709,6 +2805,7 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
 
               isMessageOpen = true;
               activeMessageId = value.message.id;
+              heldBackTextByIndex.clear();
 
               usage.input_tokens = value.message.usage.input_tokens;
               usage.cache_read_input_tokens =
@@ -2926,6 +3023,21 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
                 providerMetadata[providerOptionsName] = anthropicMetadata;
               }
 
+              // a message that hands off to a tool or continuation is not the
+              // final answer, so its held-back text is discarded:
+              if (
+                !isJsonResponseFromTool &&
+                !isContinuationStopReason(finishReason.raw)
+              ) {
+                for (const { id, text, citations } of heldBackText) {
+                  if (text.length === 0) continue;
+                  controller.enqueue({ type: 'text-start', id });
+                  controller.enqueue({ type: 'text-delta', id, delta: text });
+                  controller.enqueue(createTextEnd(id, citations));
+                }
+              }
+              heldBackText.length = 0;
+
               controller.enqueue({
                 type: 'finish',
                 finishReason,

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

@@ -8,6 +8,7 @@ import {
   type SharedV3ProviderMetadata,
 } from '@ai-sdk/provider';
 import {
+  stringifyWithBigIntAndCycles,
   convertBase64ToUint8Array,
   convertToBase64,
   parseProviderOptions,
@@ -585,7 +586,7 @@ export async function convertToAnthropicMessagesPrompt({
                   case 'json':
                   case 'error-json':
                   default:
-                    contentValue = JSON.stringify(output.value);
+                    contentValue = stringifyWithBigIntAndCycles(output.value);
                     break;
                 }
 
@@ -899,7 +900,7 @@ export async function convertToAnthropicMessagesPrompt({
                   type: 'tool_use',
                   id: part.toolCallId,
                   name: part.toolName,
-                  input: part.input,
+                  input: parseToolCallInput(part.input),
                   ...(caller && { caller }),
                   cache_control: cacheControl,
                 });
@@ -1564,3 +1565,21 @@ function getAnthropicCaller(
 
   return caller?.type === 'direct' ? { type: 'direct' } : undefined;
 }
+
+function parseToolCallInput(input: unknown): unknown {
+  if (typeof input === 'string') {
+    try {
+      const parsed = secureJsonParse(input);
+      if (
+        typeof parsed === 'object' &&
+        parsed !== null &&
+        !Array.isArray(parsed)
+      ) {
+        return parsed;
+      }
+    } catch {
+      // Preserve malformed input for replay.
+    }
+  }
+  return input;
+}

package/src/has-circular-schema-reference.ts

@@ -0,0 +1,118 @@
+import type { JSONSchema7 } from '@ai-sdk/provider';
+
+// Keywords whose values are maps of name -> schema rather than a schema.
+const SCHEMA_MAP_KEYWORDS = new Set([
+  'dependentSchemas',
+  'patternProperties',
+  'properties',
+]);
+
+// Keywords holding instance data, which can contain a literal `$ref` key.
+const DATA_KEYWORDS = new Set(['const', 'default', 'enum', 'examples']);
+
+/**
+ * Whether a JSON schema contains a cycle of local `$ref`s, e.g. a tree node
+ * whose children reference the node itself.
+ *
+ * Anthropic's native structured outputs reject such schemas, while the JSON
+ * response tool accepts them.
+ */
+export function hasCircularSchemaReference(schema: JSONSchema7): boolean {
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+
+  const visit = (pointer: string): boolean => {
+    if (visiting.has(pointer)) {
+      return true;
+    }
+    if (visited.has(pointer)) {
+      return false;
+    }
+
+    const target = resolveSchemaPointer(schema, pointer);
+    if (target === undefined) {
+      return false;
+    }
+
+    visiting.add(pointer);
+    const isCircular = collectLocalRefs(target).some(visit);
+    visiting.delete(pointer);
+    visited.add(pointer);
+
+    return isCircular;
+  };
+
+  return visit('#');
+}
+
+function collectLocalRefs(node: unknown, refs: string[] = []): string[] {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectLocalRefs(item, refs);
+    }
+    return refs;
+  }
+
+  if (!isRecord(node)) {
+    return refs;
+  }
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key === '$ref') {
+      if (typeof value === 'string' && value.startsWith('#')) {
+        refs.push(value);
+      }
+    } else if (SCHEMA_MAP_KEYWORDS.has(key) && isRecord(value)) {
+      for (const subschema of Object.values(value)) {
+        collectLocalRefs(subschema, refs);
+      }
+    } else if (
+      // definitions are only reached through a `$ref`:
+      key !== '$defs' &&
+      key !== 'definitions' &&
+      !DATA_KEYWORDS.has(key)
+    ) {
+      collectLocalRefs(value, refs);
+    }
+  }
+
+  return refs;
+}
+
+export function resolveSchemaPointer(
+  schema: JSONSchema7,
+  pointer: string,
+): unknown {
+  if (pointer === '#') {
+    return schema;
+  }
+  if (!pointer.startsWith('#/')) {
+    return undefined;
+  }
+
+  let decodedPointer: string;
+  try {
+    decodedPointer = decodeURIComponent(pointer.slice(2));
+  } catch {
+    return undefined;
+  }
+
+  let current: unknown = schema;
+  for (const rawSegment of decodedPointer.split('/')) {
+    const segment = rawSegment.replace(/~1/g, '/').replace(/~0/g, '~');
+
+    if (Array.isArray(current)) {
+      current = current[Number(segment)];
+    } else if (isRecord(current)) {
+      current = current[segment];
+    } else {
+      return undefined;
+    }
+  }
+
+  return current;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/internal/index.ts

@@ -6,3 +6,4 @@ export { anthropicTools } from '../anthropic-tools';
 export type { AnthropicMessagesModelId } from '../anthropic-messages-options';
 export { prepareTools } from '../anthropic-prepare-tools';
 export { sanitizeJsonSchema } from '../sanitize-json-schema';
+export { supportsNativeStructuredOutputSchema } from '../supports-native-structured-output-schema';

package/src/sanitize-json-schema.ts

@@ -53,12 +53,11 @@ function sanitizeDefinition(
 
 function sanitizeSchema(schema: JSONSchema7): JSONSchema7 {
   const result: JSONSchema7 = {};
-  const schemaWithDefs = schema as JSONSchema7 & {
-    $defs?: Record<string, JSONSchema7Definition>;
-  };
 
+  // Keep the definitions next to a `$ref` so a top-level reference still
+  // resolves (e.g. `{ $ref: '#/definitions/Answer', definitions: {...} }`).
   if (schema.$ref != null) {
-    return { $ref: schema.$ref };
+    return { $ref: schema.$ref, ...sanitizeSchemaDefinitions(schema) };
   }
 
   if (schema.$schema != null) {
@@ -103,26 +102,7 @@ function sanitizeSchema(schema: JSONSchema7): JSONSchema7 {
     result.allOf = schema.allOf.map(sanitizeDefinition);
   }
 
-  if (schema.definitions != null) {
-    result.definitions = Object.fromEntries(
-      Object.entries(schema.definitions).map(([name, definition]) => [
-        name,
-        sanitizeDefinition(definition),
-      ]),
-    );
-  }
-
-  if (schemaWithDefs.$defs != null) {
-    const resultWithDefs = result as JSONSchema7 & {
-      $defs?: Record<string, JSONSchema7Definition>;
-    };
-    resultWithDefs.$defs = Object.fromEntries(
-      Object.entries(schemaWithDefs.$defs).map(([name, definition]) => [
-        name,
-        sanitizeDefinition(definition),
-      ]),
-    );
-  }
+  Object.assign(result, sanitizeSchemaDefinitions(schema));
 
   if (schema.type === 'object' || schema.properties != null) {
     if (schema.properties != null) {
@@ -165,6 +145,29 @@ function sanitizeSchema(schema: JSONSchema7): JSONSchema7 {
   return result;
 }
 
+function sanitizeSchemaDefinitions(schema: JSONSchema7): Pick<
+  JSONSchema7,
+  'definitions'
+> & {
+  $defs?: Record<string, JSONSchema7Definition>;
+} {
+  const { $defs } = schema as { $defs?: Record<string, JSONSchema7Definition> };
+  const sanitizeAll = (definitions: Record<string, JSONSchema7Definition>) =>
+    Object.fromEntries(
+      Object.entries(definitions).map(([name, definition]) => [
+        name,
+        sanitizeDefinition(definition),
+      ]),
+    );
+
+  return {
+    ...(schema.definitions != null && {
+      definitions: sanitizeAll(schema.definitions),
+    }),
+    ...($defs != null && { $defs: sanitizeAll($defs) }),
+  };
+}
+
 function getConstraintDescription(schema: JSONSchema7): string | undefined {
   const descriptions = DESCRIPTION_CONSTRAINT_KEYS.flatMap(key => {
     const value = schema[key];