@ai-sdk/anthropic 3.0.136 → 3.0.137

package/docs/05-anthropic.mdx

@@ -194,10 +194,21 @@ 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.
 
+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.137",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

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';
 
@@ -419,13 +461,15 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
 
     // 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',
@@ -1146,11 +1190,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 +1846,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 +1928,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 +2494,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 +2622,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 +2738,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 +2790,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 +3008,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/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/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];

package/src/supports-native-structured-output-schema.ts

@@ -0,0 +1,138 @@
+import type { JSONSchema7 } from '@ai-sdk/provider';
+import {
+  hasCircularSchemaReference,
+  isRecord,
+  resolveSchemaPointer,
+} from './has-circular-schema-reference';
+
+// Anthropic rejects schemas with more than 24 optional properties in total,
+// and grammar compilation fails earlier as optional properties add up: from 13
+// on Bedrock and the Anthropic API, from 11 on Vertex (compilation timeout).
+const MAX_OPTIONAL_PROPERTIES = 10;
+
+const SUBSCHEMA_KEYWORDS = [
+  'additionalProperties',
+  'contains',
+  'else',
+  'if',
+  'items',
+  'not',
+  'then',
+];
+const SUBSCHEMA_LIST_KEYWORDS = ['allOf', 'anyOf', 'oneOf', 'prefixItems'];
+const SUBSCHEMA_MAP_KEYWORDS = [
+  'dependentSchemas',
+  'patternProperties',
+  'properties',
+];
+
+type SchemaStats = { optionalProperties: number; hasOpenObject: boolean };
+
+/**
+ * Whether Anthropic's native structured outputs (`output_config.format`) can
+ * represent a schema without rejecting it or losing data.
+ *
+ * Rejected: self-referencing schemas, and schemas with too many optional
+ * properties. Lossy: open objects (maps, free-form objects), which native
+ * structured outputs close with `additionalProperties: false`, so the model
+ * can only return `{}` for them.
+ */
+export function supportsNativeStructuredOutputSchema(
+  schema: JSONSchema7,
+): boolean {
+  if (hasCircularSchemaReference(schema)) {
+    return false;
+  }
+
+  const { optionalProperties, hasOpenObject } = getSchemaStats(
+    schema,
+    schema,
+    new Map(),
+  );
+
+  return !hasOpenObject && optionalProperties <= MAX_OPTIONAL_PROPERTIES;
+}
+
+function getSchemaStats(
+  node: unknown,
+  root: JSONSchema7,
+  refStats: Map<string, SchemaStats>,
+): SchemaStats {
+  const stats: SchemaStats = { optionalProperties: 0, hasOpenObject: false };
+  if (!isRecord(node)) {
+    return stats;
+  }
+
+  const add = (child: unknown) => {
+    const childStats = getSchemaStats(child, root, refStats);
+    stats.optionalProperties += childStats.optionalProperties;
+    stats.hasOpenObject ||= childStats.hasOpenObject;
+  };
+
+  // references are counted at every use; the schema has no cycles here:
+  if (typeof node.$ref === 'string' && node.$ref.startsWith('#')) {
+    let resolved = refStats.get(node.$ref);
+    if (resolved == null) {
+      resolved = getSchemaStats(
+        resolveSchemaPointer(root, node.$ref),
+        root,
+        refStats,
+      );
+      refStats.set(node.$ref, resolved);
+    }
+    stats.optionalProperties += resolved.optionalProperties;
+    stats.hasOpenObject ||= resolved.hasOpenObject;
+  }
+
+  if (isOpenObject(node)) {
+    stats.hasOpenObject = true;
+  }
+
+  if (isRecord(node.properties)) {
+    const required = new Set(Array.isArray(node.required) ? node.required : []);
+    stats.optionalProperties += Object.keys(node.properties).filter(
+      name => !required.has(name),
+    ).length;
+  }
+
+  for (const keyword of SUBSCHEMA_KEYWORDS) {
+    const value = node[keyword];
+    if (Array.isArray(value)) {
+      value.forEach(add);
+    } else {
+      add(value);
+    }
+  }
+  for (const keyword of SUBSCHEMA_LIST_KEYWORDS) {
+    const value = node[keyword];
+    if (Array.isArray(value)) {
+      value.forEach(add);
+    }
+  }
+  for (const keyword of SUBSCHEMA_MAP_KEYWORDS) {
+    const value = node[keyword];
+    if (isRecord(value)) {
+      Object.values(value).forEach(add);
+    }
+  }
+
+  return stats;
+}
+
+function isOpenObject(node: Record<string, unknown>): boolean {
+  const { additionalProperties, patternProperties, properties, type } = node;
+
+  if (additionalProperties === true || isRecord(additionalProperties)) {
+    return true;
+  }
+  if (
+    isRecord(patternProperties) &&
+    Object.keys(patternProperties).length > 0
+  ) {
+    return true;
+  }
+
+  const isObjectType =
+    type === 'object' || (Array.isArray(type) && type.includes('object'));
+  return isObjectType && properties == null && additionalProperties !== false;
+}