@ai-sdk/anthropic 4.0.19 → 4.0.21

package/docs/05-anthropic.mdx

@@ -175,7 +175,9 @@ const result = streamText({
 
 ### 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-fable-5`, and `claude-sonnet-5` additionally support `xhigh` for maximum reasoning 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-fable-5`, and `claude-sonnet-5` additionally support `xhigh` for maximum reasoning effort.
+
+On `claude-opus-5`, thinking can only be disabled at effort levels up to and including `high`. When you combine `thinking: { type: 'disabled' }` with `effort: 'xhigh'` or `effort: 'max'`, the AI SDK lowers the effort to `high` and emits a warning instead of sending a request that the API would reject.
 
 ```ts highlight="8-10"
 import { anthropic, AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';
@@ -301,7 +303,26 @@ A classifier block looks like this:
 
 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.
+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 a fallback model and returns that model's answer. The required beta header is added for you.
+
+The recommended configuration is `fallbacks: 'default'`, which lets the API route the retry to Anthropic's recommended fallback model based on the refusal category and removes the need to migrate when a fallback model is deprecated:
+
+```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: 'default',
+    } satisfies AnthropicLanguageModelOptions,
+  },
+});
+```
+
+You can also pin an explicit fallback chain:
 
 ```ts highlight="8-10"
 import { anthropic, AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';
@@ -1187,6 +1208,61 @@ const result = await generateText({
 
 This sends `tool_reference` blocks to Anthropic, which loads the corresponding deferred tool schemas into Claude's context.
 
+### Mid-Conversation Tool Changes
+
+With `claude-opus-4-8`, you can add or remove tools between turns of a conversation without invalidating the prompt cache. Attach `toolChanges` to a system message that appears mid-conversation (right before an assistant message or at the end of the messages). The required `mid-conversation-tool-changes-2026-07-01` beta header is added automatically.
+
+Tools referenced by a `tool_addition` must be declared in the `tools` option — typically with `deferLoading: true`, so they are not loaded into context until the addition surfaces them. A `tool_removal` removes a previously available tool from the conversation going forward.
+
+```ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { generateText, tool } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: anthropic('claude-opus-4-8'),
+  // required for system messages inside `messages`:
+  allowSystemInMessages: true,
+  tools: {
+    get_weather: tool({
+      description: 'Get weather',
+      inputSchema: z.object({ city: z.string() }),
+    }),
+    get_forecast: tool({
+      description: 'Get 5-day forecast',
+      inputSchema: z.object({ city: z.string() }),
+      providerOptions: {
+        // declared up front but not loaded until a tool_addition surfaces it
+        anthropic: { deferLoading: true },
+      },
+    }),
+  },
+  messages: [
+    { role: 'user', content: 'What tools do you have for weather in Paris?' },
+    {
+      role: 'system',
+      content: '',
+      providerOptions: {
+        anthropic: {
+          toolChanges: [
+            { type: 'tool_addition', toolName: 'get_forecast' },
+            { type: 'tool_removal', toolName: 'get_weather' },
+          ],
+        },
+      },
+    },
+  ],
+});
+```
+
+To change a tool's definition, remove the old definition at the end of one request, then carry the conversation forward with the updated definition in `tools` on the next request.
+
+<Note>
+  Tool changes are not supported on the initial system message. The AI SDK
+  ignores them there and emits a warning — configure the initial tool set via
+  the `tools` option instead.
+</Note>
+
 ### MCP Connectors
 
 Anthropic supports connecting to [MCP servers](https://docs.claude.com/en/docs/agents-and-tools/mcp-connector) as part of their execution.
@@ -1611,6 +1687,7 @@ and the `mediaType` should be set to `'application/pdf'`.
 
 | Model               | Image Input | Object Generation | Tool Usage | Computer Use | Web Search | Tool Search | Compaction |
 | ------------------- | ----------- | ----------------- | ---------- | ------------ | ---------- | ----------- | ---------- |
+| `claude-opus-5`     | <Check />   | <Check />         | <Check />  | <Check />    | <Check />  | <Check />   | <Check />  |
 | `claude-sonnet-5`   | <Check />   | <Check />         | <Check />  | <Check />    | <Check />  | <Check />   | <Check />  |
 | `claude-fable-5`    | <Check />   | <Check />         | <Check />  | <Check />    | <Check />  | <Check />   | <Check />  |
 | `claude-opus-4-8`   | <Check />   | <Check />         | <Check />  | <Check />    | <Check />  | <Check />   | <Check />  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/anthropic",
-  "version": "4.0.19",
+  "version": "4.0.21",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

package/src/anthropic-api.ts

@@ -23,7 +23,20 @@ export type AnthropicCacheControl = {
 
 export interface AnthropicSystemMessage {
   role: 'system';
-  content: Array<AnthropicTextContent>;
+  content: Array<AnthropicTextContent | AnthropicToolChangeContent>;
+}
+
+/**
+ * Mid-conversation tool change content block. Adds or removes a tool from the
+ * conversation's tool set without invalidating the prompt cache.
+ *
+ * Only valid inside system messages that appear in the `messages` array.
+ * Requires the `mid-conversation-tool-changes-2026-07-01` beta.
+ */
+export interface AnthropicToolChangeContent {
+  type: 'tool_addition' | 'tool_removal';
+  tool: { type: 'tool_reference'; name: string };
+  cache_control?: never;
 }
 
 export interface AnthropicUserMessage {
@@ -936,6 +949,11 @@ export const anthropicResponseSchema = lazySchema(() =>
       usage: z.looseObject({
         input_tokens: z.number(),
         output_tokens: z.number(),
+        output_tokens_details: z
+          .object({
+            thinking_tokens: z.number().nullish(),
+          })
+          .nullish(),
         cache_creation_input_tokens: z.number().nullish(),
         cache_read_input_tokens: z.number().nullish(),
         iterations: z
@@ -1414,6 +1432,11 @@ export const anthropicChunkSchema = lazySchema(() =>
         usage: z.looseObject({
           input_tokens: z.number().nullish(),
           output_tokens: z.number(),
+          output_tokens_details: z
+            .object({
+              thinking_tokens: z.number().nullish(),
+            })
+            .nullish(),
           cache_creation_input_tokens: z.number().nullish(),
           cache_read_input_tokens: z.number().nullish(),
           iterations: z

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

@@ -19,6 +19,7 @@ export type AnthropicModelId =
   | 'claude-opus-4-6'
   | 'claude-opus-4-7'
   | 'claude-opus-4-8'
+  | 'claude-opus-5'
   | 'claude-fable-5'
   | 'claude-sonnet-5'
   | (string & {});
@@ -65,6 +66,44 @@ export type AnthropicFilePartProviderOptions = z.infer<
   typeof anthropicFilePartProviderOptions
 >;
 
+/**
+ * Anthropic provider options for system messages.
+ */
+export const anthropicSystemMessageProviderOptions = z.object({
+  /**
+   * Mid-conversation tool changes. Adds or removes tools from the
+   * conversation's tool set between turns without invalidating the prompt
+   * cache.
+   *
+   * Only supported on system messages that appear mid-conversation (not the
+   * initial system prompt). A system message carrying tool changes must come
+   * right before an assistant message or at the end of the messages.
+   *
+   * Tools referenced by a `tool_addition` must be declared in the `tools`
+   * option (typically with `deferLoading: true` so they are not loaded until
+   * the addition surfaces them). The required
+   * `mid-conversation-tool-changes-2026-07-01` beta is added automatically.
+   */
+  toolChanges: z
+    .array(
+      z.discriminatedUnion('type', [
+        z.object({
+          type: z.literal('tool_addition'),
+          toolName: z.string(),
+        }),
+        z.object({
+          type: z.literal('tool_removal'),
+          toolName: z.string(),
+        }),
+      ]),
+    )
+    .optional(),
+});
+
+export type AnthropicSystemMessageProviderOptions = z.infer<
+  typeof anthropicSystemMessageProviderOptions
+>;
+
 export const anthropicLanguageModelOptions = z.object({
   /**
    * Whether to send reasoning to the model.
@@ -240,31 +279,36 @@ export const anthropicLanguageModelOptions = z.object({
   inferenceGeo: z.enum(['us', 'global']).optional(),
 
   /**
-   * Server-side fallback chain.
+   * Server-side fallback configuration.
    *
    * When the primary model's safety classifiers block a turn, the API
-   * automatically retries it on the next model in the chain, server-side. A
-   * `content-filter` finish reason means the entire chain refused.
+   * automatically retries it server-side on a fallback model. A
+   * `content-filter` finish reason means the fallback(s) refused as well.
    *
-   * Each entry is merged into the request as a direct request to that entry's
-   * model, so it must be formatted accordingly: `model` is required, and an
-   * entry may additionally override `max_tokens`, `thinking`, `output_config`,
-   * and `speed` for that attempt only (`speed` additionally requires the speed
-   * beta). The value is passed through to the API as-is.
-   *
-   * The required `server-side-fallback-2026-06-01` beta is added automatically
-   * when this option is set.
+   * - `'default'` (recommended): the API routes the retry to Anthropic's
+   *   recommended fallback model based on the refusal category. Requires the
+   *   `server-side-fallback-2026-07-01` beta, which is added automatically.
+   * - Array form: an explicit fallback chain. Each entry is merged into the
+   *   request as a direct request to that entry's model, so it must be
+   *   formatted accordingly: `model` is required, and an entry may
+   *   additionally override `max_tokens`, `thinking`, `output_config`, and
+   *   `speed` for that attempt only (`speed` additionally requires the speed
+   *   beta). The value is passed through to the API as-is, and the
+   *   `server-side-fallback-2026-06-01` beta is added automatically.
    */
   fallbacks: z
-    .array(
-      z.object({
-        model: z.string(),
-        max_tokens: z.number().int().optional(),
-        thinking: z.record(z.string(), z.unknown()).optional(),
-        output_config: z.record(z.string(), z.unknown()).optional(),
-        speed: z.enum(['fast', 'standard']).optional(),
-      }),
-    )
+    .union([
+      z.literal('default'),
+      z.array(
+        z.object({
+          model: z.string(),
+          max_tokens: z.number().int().optional(),
+          thinking: z.record(z.string(), z.unknown()).optional(),
+          output_config: z.record(z.string(), z.unknown()).optional(),
+          speed: z.enum(['fast', 'standard']).optional(),
+        }),
+      ),
+    ])
     .optional(),
 
   /**

package/src/anthropic-language-model.ts

@@ -298,6 +298,7 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
       supportsAdaptiveThinking,
       rejectsSamplingParameters,
       supportsXhighEffort,
+      rejectsThinkingDisabledAboveHighEffort,
       isKnownModel,
     } = getModelCapabilities(this.modelId);
 
@@ -443,6 +444,25 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
       }
     }
 
+    // Newer models only allow disabling thinking at effort levels up to and
+    // including `high`; at `xhigh` and `max` the API returns a 400. Lower
+    // the effort to `high` to preserve the explicit request to run without
+    // thinking.
+    if (
+      rejectsThinkingDisabledAboveHighEffort &&
+      anthropicOptions?.thinking?.type === 'disabled' &&
+      (anthropicOptions.effort === 'xhigh' || anthropicOptions.effort === 'max')
+    ) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'providerOptions.anthropic.effort',
+        details:
+          `effort '${anthropicOptions.effort}' is not supported by ${this.modelId} when thinking is disabled. ` +
+          `The effort has been lowered to 'high'.`,
+      });
+      anthropicOptions.effort = 'high';
+    }
+
     const thinkingType = anthropicOptions?.thinking?.type;
     const isThinking =
       thinkingType === 'enabled' || thinkingType === 'adaptive';
@@ -514,8 +534,9 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
       ...(anthropicOptions?.inferenceGeo && {
         inference_geo: anthropicOptions.inferenceGeo,
       }),
-      ...(anthropicOptions?.fallbacks &&
-        anthropicOptions.fallbacks.length > 0 && {
+      ...(anthropicOptions?.fallbacks != null &&
+        (anthropicOptions.fallbacks === 'default' ||
+          anthropicOptions.fallbacks.length > 0) && {
           fallbacks: anthropicOptions.fallbacks,
         }),
       ...(anthropicOptions?.cacheControl && {
@@ -750,7 +771,12 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
       betas.add('fast-mode-2026-02-01');
     }
 
-    if (anthropicOptions?.fallbacks && anthropicOptions.fallbacks.length > 0) {
+    if (anthropicOptions?.fallbacks === 'default') {
+      betas.add('server-side-fallback-2026-07-01');
+    } else if (
+      anthropicOptions?.fallbacks &&
+      anthropicOptions.fallbacks.length > 0
+    ) {
       betas.add('server-side-fallback-2026-06-01');
     }
 
@@ -2478,6 +2504,9 @@ export class AnthropicLanguageModel implements LanguageModelV4 {
                 usage.input_tokens = value.usage.input_tokens;
               }
               usage.output_tokens = value.usage.output_tokens;
+              if (value.usage.output_tokens_details != null) {
+                usage.output_tokens_details = value.usage.output_tokens_details;
+              }
 
               if (value.usage.cache_read_input_tokens != null) {
                 usage.cache_read_input_tokens =
@@ -2650,9 +2679,20 @@ export function getModelCapabilities(modelId: string): {
   supportsAdaptiveThinking: boolean;
   rejectsSamplingParameters: boolean;
   supportsXhighEffort: boolean;
+  rejectsThinkingDisabledAboveHighEffort: boolean;
   isKnownModel: boolean;
 } {
-  if (
+  if (modelId.includes('claude-opus-5')) {
+    return {
+      maxOutputTokens: 128000,
+      supportsStructuredOutput: true,
+      supportsAdaptiveThinking: true,
+      rejectsSamplingParameters: true,
+      supportsXhighEffort: true,
+      rejectsThinkingDisabledAboveHighEffort: true,
+      isKnownModel: true,
+    };
+  } else if (
     modelId.includes('claude-opus-4-8') ||
     modelId.includes('claude-opus-4-7') ||
     modelId.includes('claude-fable-5') ||
@@ -2664,6 +2704,7 @@ export function getModelCapabilities(modelId: string): {
       supportsAdaptiveThinking: true,
       rejectsSamplingParameters: true,
       supportsXhighEffort: true,
+      rejectsThinkingDisabledAboveHighEffort: false,
       isKnownModel: true,
     };
   } else if (
@@ -2676,6 +2717,7 @@ export function getModelCapabilities(modelId: string): {
       supportsAdaptiveThinking: true,
       rejectsSamplingParameters: false,
       supportsXhighEffort: false,
+      rejectsThinkingDisabledAboveHighEffort: false,
       isKnownModel: true,
     };
   } else if (
@@ -2689,6 +2731,7 @@ export function getModelCapabilities(modelId: string): {
       supportsAdaptiveThinking: false,
       rejectsSamplingParameters: false,
       supportsXhighEffort: false,
+      rejectsThinkingDisabledAboveHighEffort: false,
       isKnownModel: true,
     };
   } else if (modelId.includes('claude-opus-4-1')) {
@@ -2698,6 +2741,7 @@ export function getModelCapabilities(modelId: string): {
       supportsAdaptiveThinking: false,
       rejectsSamplingParameters: false,
       supportsXhighEffort: false,
+      rejectsThinkingDisabledAboveHighEffort: false,
       isKnownModel: true,
     };
   } else if (modelId.includes('claude-sonnet-4-')) {
@@ -2707,6 +2751,7 @@ export function getModelCapabilities(modelId: string): {
       supportsAdaptiveThinking: false,
       rejectsSamplingParameters: false,
       supportsXhighEffort: false,
+      rejectsThinkingDisabledAboveHighEffort: false,
       isKnownModel: true,
     };
   } else if (modelId.includes('claude-opus-4-')) {
@@ -2716,6 +2761,7 @@ export function getModelCapabilities(modelId: string): {
       supportsAdaptiveThinking: false,
       rejectsSamplingParameters: false,
       supportsXhighEffort: false,
+      rejectsThinkingDisabledAboveHighEffort: false,
       isKnownModel: true,
     };
   } else if (modelId.includes('claude-3-haiku')) {
@@ -2725,6 +2771,7 @@ export function getModelCapabilities(modelId: string): {
       supportsAdaptiveThinking: false,
       rejectsSamplingParameters: false,
       supportsXhighEffort: false,
+      rejectsThinkingDisabledAboveHighEffort: false,
       isKnownModel: true,
     };
   } else if (
@@ -2736,6 +2783,7 @@ export function getModelCapabilities(modelId: string): {
       supportsAdaptiveThinking: false,
       rejectsSamplingParameters: false,
       supportsXhighEffort: false,
+      rejectsThinkingDisabledAboveHighEffort: false,
       isKnownModel: false,
     };
   } else if (modelId.includes('claude-')) {
@@ -2748,15 +2796,19 @@ export function getModelCapabilities(modelId: string): {
       supportsAdaptiveThinking: true,
       rejectsSamplingParameters: true,
       supportsXhighEffort: true,
+      rejectsThinkingDisabledAboveHighEffort: true,
       isKnownModel: false,
     };
   } else {
+    // Non-Claude models (e.g. served through Anthropic-compatible APIs)
+    // keep conservative defaults.
     return {
       maxOutputTokens: 4096,
       supportsStructuredOutput: false,
       supportsAdaptiveThinking: false,
       rejectsSamplingParameters: false,
       supportsXhighEffort: false,
+      rejectsThinkingDisabledAboveHighEffort: false,
       isKnownModel: false,
     };
   }

package/src/convert-anthropic-usage.ts

@@ -28,6 +28,9 @@ export type AnthropicUsageIteration = {
 export type AnthropicUsage = {
   input_tokens: number;
   output_tokens: number;
+  output_tokens_details?: {
+    thinking_tokens?: number | null;
+  } | null;
   cache_creation_input_tokens?: number | null;
   cache_read_input_tokens?: number | null;
   /**
@@ -50,6 +53,8 @@ export function convertAnthropicUsage({
 }): LanguageModelV4Usage {
   const cacheCreationTokens = usage.cache_creation_input_tokens ?? 0;
   const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
+  const reasoningTokens =
+    usage.output_tokens_details?.thinking_tokens ?? undefined;
 
   // When iterations is present (compaction or advisor), sum across executor
   // iterations to get the true executor totals. The top-level input_tokens
@@ -101,8 +106,9 @@ export function convertAnthropicUsage({
     },
     outputTokens: {
       total: outputTokens,
-      text: undefined,
-      reasoning: undefined,
+      text:
+        reasoningTokens == null ? undefined : outputTokens - reasoningTokens,
+      reasoning: reasoningTokens,
     },
     raw: rawUsage ?? usage,
   };

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

@@ -23,12 +23,18 @@ import {
   anthropicReasoningMetadataSchema,
   type AnthropicAssistantMessage,
   type AnthropicPrompt,
+  type AnthropicSystemMessage,
+  type AnthropicTextContent,
+  type AnthropicToolChangeContent,
   type AnthropicToolResultContent,
   type AnthropicUserMessage,
   type AnthropicWebFetchToolResultContent,
   type Citation,
 } from './anthropic-api';
-import { anthropicFilePartProviderOptions } from './anthropic-language-model-options';
+import {
+  anthropicFilePartProviderOptions,
+  anthropicSystemMessageProviderOptions,
+} from './anthropic-language-model-options';
 import { CacheControlValidator } from './get-cache-control';
 import { advisor_20260301OutputSchema } from './tool/advisor_20260301';
 import { codeExecution_20250522OutputSchema } from './tool/code-execution_20250522';
@@ -137,20 +143,66 @@ export async function convertToAnthropicPrompt({
 
     switch (type) {
       case 'system': {
-        const content = block.messages.map(({ content, providerOptions }) => ({
-          type: 'text' as const,
-          text: content,
-          cache_control: validator.getCacheControl(providerOptions, {
-            type: 'system message',
-            canCache: true,
-          }),
-        }));
-
-        if (system == null) {
-          system = content;
+        const content: AnthropicSystemMessage['content'] = [];
+        let toolChangeCount = 0;
+
+        for (const { content: text, providerOptions } of block.messages) {
+          const systemMessageOptions = await parseProviderOptions({
+            provider: 'anthropic',
+            providerOptions,
+            schema: anthropicSystemMessageProviderOptions,
+          });
+          const toolChanges = systemMessageOptions?.toolChanges ?? [];
+
+          // A system message that only carries tool changes may have empty
+          // text; do not emit an empty text block for it.
+          if (text !== '' || toolChanges.length === 0) {
+            content.push({
+              type: 'text' as const,
+              text,
+              cache_control: validator.getCacheControl(providerOptions, {
+                type: 'system message',
+                canCache: true,
+              }),
+            });
+          }
+
+          for (const toolChange of toolChanges) {
+            toolChangeCount++;
+            content.push({
+              type: toolChange.type,
+              tool: {
+                type: 'tool_reference',
+                name: toolNameMapping.toProviderToolName(toolChange.toolName),
+              },
+            } satisfies AnthropicToolChangeContent);
+          }
+        }
+
+        // The first block becomes the top-level system prompt. Later system
+        // blocks are sent as inline system messages — always when they carry
+        // tool changes (which are only valid mid-conversation), and otherwise
+        // only when a top-level system prompt already exists (preserving the
+        // existing hoisting behavior for plain text).
+        if (i === 0 || (system == null && toolChangeCount === 0)) {
+          if (toolChangeCount > 0) {
+            warnings.push({
+              type: 'other',
+              message:
+                'tool changes on the initial system message are not supported by Anthropic. ' +
+                'Configure the initial tool set via the tools option instead. ' +
+                'The tool changes have been ignored.',
+            });
+          }
+          system = content.filter(
+            (part): part is AnthropicTextContent => part.type === 'text',
+          );
         } else {
           messages.push({ role: 'system', content });
           betas.add('mid-conversation-system-2026-04-07');
+          if (toolChangeCount > 0) {
+            betas.add('mid-conversation-tool-changes-2026-07-01');
+          }
         }
 
         break;

package/src/index.ts

@@ -6,6 +6,7 @@ export type {
   AnthropicLanguageModelOptions,
   /** @deprecated Use `AnthropicLanguageModelOptions` instead. */
   AnthropicLanguageModelOptions as AnthropicProviderOptions,
+  AnthropicSystemMessageProviderOptions,
 } from './anthropic-language-model-options';
 export type { AnthropicToolOptions } from './anthropic-prepare-tools';
 export { anthropic, createAnthropic } from './anthropic-provider';