@ai-sdk/anthropic 3.0.80 → 3.0.82

package/docs/05-anthropic.mdx

@@ -243,7 +243,7 @@ import { anthropic, AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
-  model: anthropic('claude-opus-4-7'),
+  model: anthropic('claude-opus-4-8'),
   prompt: 'Research the pros and cons of Rust vs Go for building CLI tools.',
   providerOptions: {
     anthropic: {
@@ -293,6 +293,63 @@ const { text } = await generateText({
 
 The `inferenceGeo` option accepts `'us'` (US-only infrastructure) or `'global'` (default, any available geography).
 
+### Safety Classifiers and Fallbacks
+
+Claude Fable 5 has safeguards that limit its performance in certain areas like cybersecurity, biology, and chemistry, and automated safety checks are run on every request.
+
+When one of these checks blocks a request, the API does not answer it. Instead it returns a classifier block: a `200` response with a `refusal` stop reason and an optional `stop_details` object describing the category that triggered the block. The AI SDK surfaces this as a `content-filter` finish reason, with the details available on `providerMetadata.anthropic.stopDetails`.
+
+A classifier block looks like this:
+
+```json
+{
+  "type": "message",
+  "model": "claude-fable-5",
+  "content": [],
+  "stop_reason": "refusal",
+  "stop_details": {
+    "type": "refusal",
+    "category": "cyber",
+    "explanation": "This request triggered restrictions on violative cyber content and was blocked under Anthropic's Usage Policy."
+  }
+}
+```
+
+Branch on the finish reason rather than on the presence of `stop_details` — the API may return a refusal with no details at all.
+
+To avoid receiving a classifier block, pass the `fallbacks` option. When the primary model's classifiers block a turn, the API automatically retries it server-side on the next model in the chain and returns that model's answer. The required beta header is added for you.
+
+```ts highlight="8-10"
+import { anthropic, AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: anthropic('claude-fable-5'),
+  prompt: 'Explain the history of cryptography.',
+  providerOptions: {
+    anthropic: {
+      fallbacks: [{ model: 'claude-fable-5' }],
+    } satisfies AnthropicLanguageModelOptions,
+  },
+});
+```
+
+Each fallback entry requires a `model` and may additionally override `max_tokens`, `thinking`, `output_config`, and `speed` for that attempt only.
+
+When a fallback serves the turn, it is recorded in the per-model usage breakdown (`usage.iterations`) as a `fallback_message` entry. The AI SDK exposes this breakdown on `providerMetadata.anthropic.iterations`, so you can detect whether a fallback ran:
+
+```ts
+// set up `result` with a `streamText` call passing `fallbacks` as shown
+// above, then consume the stream
+
+const { iterations } = (await result.providerMetadata)?.anthropic ?? {};
+const servedByFallback = iterations?.some(
+  iteration => iteration.type === 'fallback_message',
+);
+
+console.log('Served by fallback:', servedByFallback);
+```
+
 ### Reasoning
 
 Anthropic models support extended thinking, where Claude shows its reasoning process before providing a final answer.
@@ -342,7 +399,7 @@ Starting with `claude-opus-4-7`, thinking content is omitted from the response b
 
 ```ts highlight="5"
 const { text, reasoningText } = await generateText({
-  model: anthropic('claude-opus-4-7'),
+  model: anthropic('claude-opus-4-8'),
   providerOptions: {
     anthropic: {
       thinking: { type: 'adaptive', display: 'summarized' },
@@ -971,7 +1028,7 @@ const result = await generateText({
     'Build a concurrent worker pool in Go with graceful shutdown. Outline the design first.',
   tools: {
     advisor: anthropic.tools.advisor_20260301({
-      model: 'claude-opus-4-7',
+      model: 'claude-opus-4-8',
       maxUses: 3,
     }),
   },
@@ -989,7 +1046,7 @@ The advisor tool supports the following configuration options:
 
 - **model** _string_
 
-  Required. The advisor model ID, such as `claude-opus-4-7`. The advisor model must be at least as capable as the executor model.
+  Required. The advisor model ID, such as `claude-opus-4-8`. The advisor model must be at least as capable as the executor model.
 
 - **maxUses** _number_
 
@@ -1502,6 +1559,8 @@ and the `mediaType` should be set to `'application/pdf'`.
 
 | Model               | Image Input         | Object Generation   | Tool Usage          | Computer Use        | Web Search          | Tool Search         | Compaction          |
 | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| `claude-fable-5`    | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `claude-opus-4-8`   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | `claude-opus-4-7`   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | `claude-opus-4-6`   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | `claude-sonnet-4-6` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |                     |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/anthropic",
-  "version": "3.0.80",
+  "version": "3.0.82",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

package/src/anthropic-message-metadata.ts

@@ -8,66 +8,43 @@ import type { JSONObject } from '@ai-sdk/provider';
  * - `compaction`: a context compaction step (billed at executor rates).
  * - `message`: an executor sampling iteration (billed at executor rates).
  * - `advisor_message`: an advisor sub-inference (billed at the advisor
- *   model's rates; `model` carries the advisor model ID). Advisor token
- *   usage is NOT rolled into the top-level usage totals because it bills
- *   at a different rate; inspect this array directly for advisor billing.
+ *   model's rates). Advisor token usage is NOT rolled into the top-level
+ *   usage totals because it bills at a different rate; inspect this array
+ *   directly for advisor billing.
+ * - `fallback_message`: a server-side fallback attempt that served the turn.
+ *   Inspect this array for exact per-model attribution on a turn that fell
+ *   back.
  */
-export type AnthropicUsageIteration =
-  | {
-      type: 'compaction' | 'message';
+export type AnthropicUsageIteration = {
+  type: 'compaction' | 'message' | 'advisor_message' | 'fallback_message';
 
-      /**
-       * Number of input tokens consumed in this iteration.
-       */
-      inputTokens: number;
-
-      /**
-       * Number of output tokens generated in this iteration.
-       */
-      outputTokens: number;
-
-      /**
-       * Number of cache-creation input tokens consumed in this iteration.
-       */
-      cacheCreationInputTokens?: number;
-
-      /**
-       * Number of cache-read input tokens consumed in this iteration.
-       */
-      cacheReadInputTokens?: number;
-    }
-  | {
-      type: 'advisor_message';
-
-      /**
-       * The advisor model that produced this iteration.
-       */
-      model: string;
+  /**
+   * The model that produced this iteration. Populated for the per-model
+   * attribution cases (the fallback chain and advisor sub-inferences) and
+   * absent otherwise.
+   */
+  model?: string;
 
-      /**
-       * Number of input tokens consumed in this iteration.
-       */
-      inputTokens: number;
+  /**
+   * Number of input tokens consumed in this iteration.
+   */
+  inputTokens: number;
 
-      /**
-       * Number of output tokens generated in this iteration.
-       */
-      outputTokens: number;
+  /**
+   * Number of output tokens generated in this iteration.
+   */
+  outputTokens: number;
 
-      /**
-       * Number of cache-creation input tokens consumed by this advisor
-       * sub-inference. Nonzero when advisor-side caching is enabled and
-       * the advisor writes a fresh cache entry.
-       */
-      cacheCreationInputTokens?: number;
+  /**
+   * Number of cache-creation input tokens consumed in this iteration.
+   */
+  cacheCreationInputTokens?: number;
 
-      /**
-       * Number of cache-read input tokens consumed by this advisor
-       * sub-inference. Nonzero on the second and later advisor calls
-       * when advisor-side caching is enabled.
-       */
-      cacheReadInputTokens?: number;
-    };
+  /**
+   * Number of cache-read input tokens consumed in this iteration.
+   */
+  cacheReadInputTokens?: number;
+};
 
 export interface AnthropicMessageMetadata {
   usage: JSONObject;
@@ -76,6 +53,42 @@ export interface AnthropicMessageMetadata {
   cacheCreationInputTokens: number | null;
   stopSequence: string | null;
 
+  /**
+   * Details about why the request stopped. Present only when the API returns
+   * a `refusal` stop reason together with a `stop_details` object (a
+   * classifier block or a model refusal).
+   *
+   * Branch on the finish reason (`content-filter`), not on this object: the
+   * API may return a refusal with no details at all, so this field can be
+   * absent even on a refusal and should not be relied upon being present.
+   */
+  stopDetails?: {
+    /**
+     * The kind of stop detail. `'refusal'` for classifier blocks and model
+     * refusals.
+     */
+    type: string;
+
+    /**
+     * The classifier category that triggered the block, e.g. `'cyber'` or
+     * `'bio'`. Absent for model refusals and other cases.
+     */
+    category?: string;
+
+    /**
+     * Human-readable explanation of why the request was blocked. May be
+     * absent even on a refusal.
+     */
+    explanation?: string;
+
+    /**
+     * The canonical id of a model to retry directly. Populated only when the
+     * request included fallbacks and the fallback attempt could not be made
+     * (e.g. the fallback model was rate limited or overloaded).
+     */
+    recommendedModel?: string;
+  };
+
   /**
    * Usage breakdown by iteration when compaction is triggered.
    *

package/src/anthropic-messages-api.ts

@@ -11,13 +11,21 @@ export type AnthropicMessagesPrompt = {
   messages: AnthropicMessage[];
 };
 
-export type AnthropicMessage = AnthropicUserMessage | AnthropicAssistantMessage;
+export type AnthropicMessage =
+  | AnthropicUserMessage
+  | AnthropicAssistantMessage
+  | AnthropicSystemMessage;
 
 export type AnthropicCacheControl = {
   type: 'ephemeral';
   ttl?: '5m' | '1h';
 };
 
+export interface AnthropicSystemMessage {
+  role: 'system';
+  content: Array<AnthropicTextContent>;
+}
+
 export interface AnthropicUserMessage {
   role: 'user';
   content: Array<
@@ -593,6 +601,15 @@ export type AnthropicResponseContextManagement = {
   applied_edits: AnthropicResponseContextManagementEdit[];
 };
 
+const anthropicStopDetailsSchema = z.object({
+  type: z.string(),
+  category: z.string().nullish(),
+  explanation: z.string().nullish(),
+  recommended_model: z.string().nullish(),
+});
+
+export type AnthropicStopDetails = z.infer<typeof anthropicStopDetailsSchema>;
+
 // limited version of the schema, focussed on what is needed for the implementation
 // this approach limits breakages when the API changes and increases efficiency
 export const anthropicMessagesResponseSchema = lazySchema(() =>
@@ -893,10 +910,17 @@ export const anthropicMessagesResponseSchema = lazySchema(() =>
               }),
             ]),
           }),
+          // Server-side fallback marker. Parsed so the response validates, but
+          // dropped from the content output (the AI SDK has no model-hop
+          // primitive). The hop remains observable via usage.iterations.
+          z.object({
+            type: z.literal('fallback'),
+          }),
         ]),
       ),
       stop_reason: z.string().nullish(),
       stop_sequence: z.string().nullish(),
+      stop_details: anthropicStopDetailsSchema.nullish(),
       usage: z.looseObject({
         input_tokens: z.number(),
         output_tokens: z.number(),
@@ -904,23 +928,19 @@ export const anthropicMessagesResponseSchema = lazySchema(() =>
         cache_read_input_tokens: z.number().nullish(),
         iterations: z
           .array(
-            z.union([
-              z.object({
-                type: z.union([z.literal('compaction'), z.literal('message')]),
-                input_tokens: z.number(),
-                output_tokens: z.number(),
-                cache_creation_input_tokens: z.number().nullish(),
-                cache_read_input_tokens: z.number().nullish(),
-              }),
-              z.object({
-                type: z.literal('advisor_message'),
-                model: z.string(),
-                input_tokens: z.number(),
-                output_tokens: z.number(),
-                cache_creation_input_tokens: z.number().nullish(),
-                cache_read_input_tokens: z.number().nullish(),
-              }),
-            ]),
+            z.object({
+              type: z.union([
+                z.literal('compaction'),
+                z.literal('message'),
+                z.literal('advisor_message'),
+                z.literal('fallback_message'),
+              ]),
+              model: z.string().nullish(),
+              input_tokens: z.number(),
+              output_tokens: z.number(),
+              cache_creation_input_tokens: z.number().nullish(),
+              cache_read_input_tokens: z.number().nullish(),
+            }),
           )
           .nullish(),
       }),
@@ -1282,6 +1302,11 @@ export const anthropicMessagesChunkSchema = lazySchema(() =>
               }),
             ]),
           }),
+          // Server-side fallback marker; dropped from content output (see the
+          // response schema). The hop remains observable via usage.iterations.
+          z.object({
+            type: z.literal('fallback'),
+          }),
         ]),
       }),
       z.object({
@@ -1354,6 +1379,7 @@ export const anthropicMessagesChunkSchema = lazySchema(() =>
         delta: z.object({
           stop_reason: z.string().nullish(),
           stop_sequence: z.string().nullish(),
+          stop_details: anthropicStopDetailsSchema.nullish(),
           container: z
             .object({
               expires_at: z.string(),
@@ -1380,26 +1406,19 @@ export const anthropicMessagesChunkSchema = lazySchema(() =>
           cache_read_input_tokens: z.number().nullish(),
           iterations: z
             .array(
-              z.union([
-                z.object({
-                  type: z.union([
-                    z.literal('compaction'),
-                    z.literal('message'),
-                  ]),
-                  input_tokens: z.number(),
-                  output_tokens: z.number(),
-                  cache_creation_input_tokens: z.number().nullish(),
-                  cache_read_input_tokens: z.number().nullish(),
-                }),
-                z.object({
-                  type: z.literal('advisor_message'),
-                  model: z.string(),
-                  input_tokens: z.number(),
-                  output_tokens: z.number(),
-                  cache_creation_input_tokens: z.number().nullish(),
-                  cache_read_input_tokens: z.number().nullish(),
-                }),
-              ]),
+              z.object({
+                type: z.union([
+                  z.literal('compaction'),
+                  z.literal('message'),
+                  z.literal('advisor_message'),
+                  z.literal('fallback_message'),
+                ]),
+                model: z.string().nullish(),
+                input_tokens: z.number(),
+                output_tokens: z.number(),
+                cache_creation_input_tokens: z.number().nullish(),
+                cache_read_input_tokens: z.number().nullish(),
+              }),
             )
             .nullish(),
         }),

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

@@ -40,6 +40,7 @@ import {
   type AnthropicContainer,
   type AnthropicReasoningMetadata,
   type AnthropicResponseContextManagement,
+  type AnthropicStopDetails,
   type AnthropicTool,
   type Citation,
 } from './anthropic-messages-api';
@@ -438,6 +439,10 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
       ...(anthropicOptions?.inferenceGeo && {
         inference_geo: anthropicOptions.inferenceGeo,
       }),
+      ...(anthropicOptions?.fallbacks &&
+        anthropicOptions.fallbacks.length > 0 && {
+          fallbacks: anthropicOptions.fallbacks,
+        }),
       ...(anthropicOptions?.cacheControl && {
         cache_control: anthropicOptions.cacheControl,
       }),
@@ -664,6 +669,10 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
       betas.add('fast-mode-2026-02-01');
     }
 
+    if (anthropicOptions?.fallbacks && anthropicOptions.fallbacks.length > 0) {
+      betas.add('server-side-fallback-2026-06-01');
+    }
+
     const defaultEagerInputStreaming =
       stream && (anthropicOptions?.toolStreaming ?? true);
 
@@ -1281,6 +1290,13 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
           }
           break;
         }
+
+        // Server-side fallback marker: the AI SDK has no content primitive for
+        // a model hop, so drop it. The hop is still observable via
+        // usage.iterations.
+        case 'fallback': {
+          break;
+        }
       }
     }
 
@@ -1303,48 +1319,35 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
       },
       warnings,
       providerMetadata: (() => {
+        const stopDetails = mapAnthropicStopDetails(response.stop_details);
+
         const anthropicMetadata = {
           usage: response.usage as JSONObject,
           cacheCreationInputTokens:
             response.usage.cache_creation_input_tokens ?? null,
           stopSequence: response.stop_sequence ?? null,
+          ...(stopDetails != null ? { stopDetails } : {}),
 
           iterations: response.usage.iterations
-            ? response.usage.iterations.map(iter =>
-                iter.type === 'advisor_message'
-                  ? ({
-                      type: iter.type,
-                      model: iter.model,
-                      inputTokens: iter.input_tokens,
-                      outputTokens: iter.output_tokens,
-                      ...(iter.cache_creation_input_tokens
-                        ? {
-                            cacheCreationInputTokens:
-                              iter.cache_creation_input_tokens,
-                          }
-                        : {}),
-                      ...(iter.cache_read_input_tokens
-                        ? {
-                            cacheReadInputTokens: iter.cache_read_input_tokens,
-                          }
-                        : {}),
-                    } satisfies AnthropicUsageIteration)
-                  : ({
-                      type: iter.type,
-                      inputTokens: iter.input_tokens,
-                      outputTokens: iter.output_tokens,
-                      ...(iter.cache_creation_input_tokens
-                        ? {
-                            cacheCreationInputTokens:
-                              iter.cache_creation_input_tokens,
-                          }
-                        : {}),
-                      ...(iter.cache_read_input_tokens
-                        ? {
-                            cacheReadInputTokens: iter.cache_read_input_tokens,
-                          }
-                        : {}),
-                    } satisfies AnthropicUsageIteration),
+            ? response.usage.iterations.map(
+                iter =>
+                  ({
+                    type: iter.type,
+                    ...(iter.model != null ? { model: iter.model } : {}),
+                    inputTokens: iter.input_tokens,
+                    outputTokens: iter.output_tokens,
+                    ...(iter.cache_creation_input_tokens
+                      ? {
+                          cacheCreationInputTokens:
+                            iter.cache_creation_input_tokens,
+                        }
+                      : {}),
+                    ...(iter.cache_read_input_tokens
+                      ? {
+                          cacheReadInputTokens: iter.cache_read_input_tokens,
+                        }
+                      : {}),
+                  }) satisfies AnthropicUsageIteration,
               )
             : null,
           container: response.container
@@ -1458,6 +1461,7 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
     let rawUsage: JSONObject | undefined = undefined;
     let cacheCreationInputTokens: number | null = null;
     let stopSequence: string | null = null;
+    let stopDetails: AnthropicMessageMetadata['stopDetails'] = undefined;
     let container: AnthropicMessageMetadata['container'] | null = null;
     let isJsonResponseFromTool = false;
 
@@ -1510,6 +1514,14 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
             case 'content_block_start': {
               const part = value.content_block;
               const contentBlockType = part.type;
+
+              // Server-side fallback marker: the AI SDK has no content
+              // primitive for a model hop, so drop it. The hop is still
+              // observable via usage.iterations.
+              if (contentBlockType === 'fallback') {
+                return;
+              }
+
               blockType = contentBlockType;
 
               switch (contentBlockType) {
@@ -2362,6 +2374,7 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
               };
 
               stopSequence = value.delta.stop_sequence ?? null;
+              stopDetails = mapAnthropicStopDetails(value.delta.stop_details);
               container =
                 value.delta.container != null
                   ? {
@@ -2395,44 +2408,28 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
                 usage: (rawUsage as JSONObject) ?? null,
                 cacheCreationInputTokens,
                 stopSequence,
+                ...(stopDetails != null ? { stopDetails } : {}),
                 iterations: usage.iterations
-                  ? usage.iterations.map(iter =>
-                      iter.type === 'advisor_message'
-                        ? ({
-                            type: iter.type,
-                            model: iter.model,
-                            inputTokens: iter.input_tokens,
-                            outputTokens: iter.output_tokens,
-                            ...(iter.cache_creation_input_tokens
-                              ? {
-                                  cacheCreationInputTokens:
-                                    iter.cache_creation_input_tokens,
-                                }
-                              : {}),
-                            ...(iter.cache_read_input_tokens
-                              ? {
-                                  cacheReadInputTokens:
-                                    iter.cache_read_input_tokens,
-                                }
-                              : {}),
-                          } satisfies AnthropicUsageIteration)
-                        : ({
-                            type: iter.type,
-                            inputTokens: iter.input_tokens,
-                            outputTokens: iter.output_tokens,
-                            ...(iter.cache_creation_input_tokens
-                              ? {
-                                  cacheCreationInputTokens:
-                                    iter.cache_creation_input_tokens,
-                                }
-                              : {}),
-                            ...(iter.cache_read_input_tokens
-                              ? {
-                                  cacheReadInputTokens:
-                                    iter.cache_read_input_tokens,
-                                }
-                              : {}),
-                          } satisfies AnthropicUsageIteration),
+                  ? usage.iterations.map(
+                      iter =>
+                        ({
+                          type: iter.type,
+                          ...(iter.model != null ? { model: iter.model } : {}),
+                          inputTokens: iter.input_tokens,
+                          outputTokens: iter.output_tokens,
+                          ...(iter.cache_creation_input_tokens
+                            ? {
+                                cacheCreationInputTokens:
+                                  iter.cache_creation_input_tokens,
+                              }
+                            : {}),
+                          ...(iter.cache_read_input_tokens
+                            ? {
+                                cacheReadInputTokens:
+                                  iter.cache_read_input_tokens,
+                              }
+                            : {}),
+                        }) satisfies AnthropicUsageIteration,
                     )
                   : null,
                 container,
@@ -2528,7 +2525,11 @@ function getModelCapabilities(modelId: string): {
   rejectsSamplingParameters: boolean;
   isKnownModel: boolean;
 } {
-  if (modelId.includes('claude-opus-4-7')) {
+  if (
+    modelId.includes('claude-opus-4-8') ||
+    modelId.includes('claude-opus-4-7') ||
+    modelId.includes('claude-fable-5')
+  ) {
     return {
       maxOutputTokens: 128000,
       supportsStructuredOutput: true,
@@ -2653,3 +2654,22 @@ function mapAnthropicResponseContextManagement(
       }
     : null;
 }
+
+function mapAnthropicStopDetails(
+  stopDetails: AnthropicStopDetails | null | undefined,
+): AnthropicMessageMetadata['stopDetails'] | undefined {
+  if (stopDetails == null) {
+    return undefined;
+  }
+
+  return {
+    type: stopDetails.type,
+    ...(stopDetails.category != null ? { category: stopDetails.category } : {}),
+    ...(stopDetails.explanation != null
+      ? { explanation: stopDetails.explanation }
+      : {}),
+    ...(stopDetails.recommended_model != null
+      ? { recommendedModel: stopDetails.recommended_model }
+      : {}),
+  };
+}