Anthropic

The Anthropic provider contains language model support for the Anthropic Messages API.

Setup

The Anthropic provider is available in the @ai-sdk/anthropic module. You can install it with

$ pnpm add @ai-sdk/anthropic

$ npm install @ai-sdk/anthropic

$ yarn add @ai-sdk/anthropic

$ bun add @ai-sdk/anthropic

Provider Instance

You can import the default provider instance anthropic from @ai-sdk/anthropic:

import { anthropic } from '@ai-sdk/anthropic';

If you need a customized setup, you can import createAnthropic from @ai-sdk/anthropic and create a provider instance with your settings:

import { createAnthropic } from '@ai-sdk/anthropic';

const anthropic = createAnthropic({
  // custom settings
});

You can use the following optional settings to customize the Anthropic provider instance:

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is https://api.anthropic.com/v1.

• apiKey string

  API key that is being sent using the x-api-key header. It defaults to the ANTHROPIC_API_KEY environment variable.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. Defaults to the global fetch function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

Language Models

You can create models that call the Anthropic Messages API using the provider instance. The first argument is the model id, e.g. claude-3-haiku-20240307. Some models have multi-modal capabilities.

const model = anthropic('claude-3-haiku-20240307');

You can use Anthropic language models to generate text with the generateText function:

import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const { text } = await generateText({
  model: anthropic('claude-3-haiku-20240307'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

Anthropic language models can also be used in the streamText, generateObject, and streamObject functions (see AI SDK Core).

The following optional provider options are available for Anthropic models:

• disableParallelToolUse boolean

  Optional. Disables the use of parallel tool calls. Defaults to false.

  When set to true, the model will only call one tool at a time instead of potentially calling multiple tools in parallel.

• sendReasoning boolean

  Optional. Include reasoning content in requests sent to the model. Defaults to true.

  If you are experiencing issues with the model handling requests involving reasoning content, you can set this to false to omit them from the request.

• effort "low" | "medium" | "high" | "xhigh" | "max"

  Optional. See Effort section for more details.

• taskBudget object

  Optional. See Task Budgets section for more details.

• speed "fast" | "standard"

  Optional. See Fast Mode section for more details.

• inferenceGeo "us" | "global"

  Optional. See Data Residency section for more details.

• thinking object

  Optional. See Reasoning section for more details.

• effort "high" | "medium" | "low"

  Optional. See Effort section for more details.

• toolStreaming boolean

  Whether to enable tool streaming (and structured output streaming). Default to true.

• structuredOutputMode "outputFormat" | "jsonTool" | "auto"

  Determines how structured outputs are generated. Optional.

  • "outputFormat": Use the output_format parameter to specify the structured output format.
  • "jsonTool": Use a special "json" tool to specify the structured output format (default).
  • "auto": Use "outputFormat" when supported, otherwise fall back to "jsonTool".

• metadata object

  Optional. Metadata to include with the request. See the Anthropic API documentation for details.

  • userId string - An external identifier for the end-user. Should be a UUID, hash, or other opaque identifier. Must not contain PII.

Structured Outputs and Tool Input Streaming

By default, the Anthropic API returns streaming tool calls and structured outputs all at once after a delay. To enable incremental streaming of tool inputs (when using streamText with tools) and structured outputs (when using streamObject), you need to set the anthropic-beta header to fine-grained-tool-streaming-2025-05-14.

For structured outputs with streamObject

import { anthropic } from '@ai-sdk/anthropic';
import { streamObject } from 'ai';
import { z } from 'zod';

const result = streamObject({
  model: anthropic('claude-sonnet-4-20250514'),
  schema: z.object({
    characters: z.array(
      z.object({
        name: z.string(),
        class: z.string(),
        description: z.string(),
      }),
    ),
  }),
  prompt: 'Generate 3 character descriptions for a fantasy role playing game.',
  headers: {
    'anthropic-beta': 'fine-grained-tool-streaming-2025-05-14',
  },
});

for await (const partialObject of result.partialObjectStream) {
  console.log(partialObject);
}

For tool input streaming with streamText

import { anthropic } from '@ai-sdk/anthropic';
import { streamText, tool } from 'ai';
import { z } from 'zod';

const result = streamText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: {
    writeFile: tool({
      description: 'Write content to a file',
      inputSchema: z.object({
        path: z.string(),
        content: z.string(),
      }),
      execute: async ({ path, content }) => {
        // Implementation
        return { success: true };
      },
    }),
  },
  prompt: 'Write a short story to story.txt',
  headers: {
    'anthropic-beta': 'fine-grained-tool-streaming-2025-05-14',
  },
});

Without this header, tool inputs and structured outputs may arrive all at once after a delay instead of streaming incrementally.

For claude-opus-5-5 and claude-fable-5-1, the default mode is "auto", which 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 auto with a warning; instruct the model to use the tool in your prompt and verify that a tool call was made.

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, 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.

On claude-opus-5-5, thinking is always adaptive and cannot be disabled, so effort is the main control for latency and cost. The API default effort for claude-opus-5-5 is medium. Start there and test other levels rather than carrying over the setting you used on claude-opus-5. Set maxOutputTokens with room for thinking as well as the reply; thinking counts toward the limit even when its content is not returned.

import { anthropic, AnthropicProviderOptions } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const { text, usage } = await generateText({
  model: anthropic('claude-opus-4-20250514'),
  prompt: 'How many people will live in the world in 2040?',
  providerOptions: {
    anthropic: {
      effort: 'low',
    } satisfies AnthropicProviderOptions,
  },
});

console.log(text); // resulting text
console.log(usage); // token usage

Fast Mode

Anthropic supports a speed option for claude-opus-4-6 that enables faster inference with approximately 2.5x faster output token speeds.

import { anthropic, AnthropicProviderOptions } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const { text } = await generateText({
  model: anthropic('claude-opus-4-6'),
  prompt: 'Write a short poem about the sea.',
  providerOptions: {
    anthropic: {
      speed: 'fast',
    } satisfies AnthropicProviderOptions,
  },
});

The speed option accepts 'fast' or 'standard' (default behavior).

Data Residency

Anthropic supports an inferenceGeo option that controls where model inference runs for a request.

import { anthropic, AnthropicProviderOptions } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const { text } = await generateText({
  model: anthropic('claude-opus-4-6'),
  prompt: 'Summarize the key points of this document.',
  providerOptions: {
    anthropic: {
      inferenceGeo: 'us',
    } satisfies AnthropicProviderOptions,
  },
});

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:

{
  "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 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:

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:

import { anthropic, AnthropicProviderOptions } 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 AnthropicProviderOptions,
  },
});

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:

// 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);

Task Budgets

claude-opus-4-7 supports a taskBudget option that informs the model of the total token budget available for an agentic turn. The model uses this information to prioritize work, plan ahead, and wind down gracefully as the budget is consumed.

Task budgets are advisory — they do not enforce a hard token limit. The model will attempt to stay within budget, but actual usage may vary.

import { anthropic, AnthropicProviderOptions } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const { text } = await generateText({
  model: anthropic('claude-opus-4-8'),
  prompt: 'Research the pros and cons of Rust vs Go for building CLI tools.',
  providerOptions: {
    anthropic: {
      taskBudget: {
        type: 'tokens',
        total: 400000,
      },
    } satisfies AnthropicProviderOptions,
  },
});

For long-running agents that compact and restart context, you can carry the remaining budget forward using the remaining field:

taskBudget: {
  type: 'tokens',
  total: 400000,
  remaining: 215000, // budget left after prior compacted-away contexts
}

The taskBudget object accepts:

• type "tokens" - Budget type. Currently only "tokens" is supported.
• total number - Total task budget for the agentic turn. Minimum 20,000.
• remaining number - Budget left after prior compacted-away contexts. Must be between 0 and total. Defaults to total if omitted.

Reasoning

Anthropic has reasoning support for claude-opus-4-20250514, claude-sonnet-4-20250514, and claude-3-7-sonnet-20250219 models.

You can enable it using the thinking provider option and specifying a thinking budget in tokens.

import { anthropic, AnthropicProviderOptions } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const { text, reasoningText, reasoning } = await generateText({
  model: anthropic('claude-opus-4-6'),
  prompt: 'How many people will live in the world in 2040?',
  providerOptions: {
    anthropic: {
      thinking: { type: 'adaptive' },
    } satisfies AnthropicProviderOptions,
  },
});

console.log(reasoningText); // reasoning text
console.log(reasoning); // reasoning details including redacted reasoning
console.log(text); // text response

You can combine adaptive thinking with the effort option to control how much reasoning Claude uses:

const { text } = await generateText({
  model: anthropic('claude-opus-4-6'),
  prompt: 'Invent a new holiday and describe its traditions.',
  providerOptions: {
    anthropic: {
      thinking: { type: 'adaptive' },
      effort: 'max', // 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    } satisfies AnthropicProviderOptions,
  },
});

Adaptive-Only Models

claude-opus-5-5, claude-fable-5, and claude-fable-5-1 always run adaptive thinking. The API rejects thinking: { type: 'disabled' } and budget-based thinking: { type: 'enabled' } for these models. To keep existing code working, the provider:

• removes thinking: { type: 'disabled' } and emits a warning,
• converts thinking: { type: 'enabled', budgetTokens } to { type: 'adaptive' } and emits a warning.

Use effort to control how much these models think. On claude-opus-5-5, set effort: 'low' when time to first token matters, and move to medium if quality drops:

const { text } = await generateText({
  model: anthropic('claude-opus-5-5'),
  prompt: 'Summarize this ticket in one sentence.',
  providerOptions: {
    anthropic: {
      // thinking stays adaptive; effort controls how much the model thinks
      effort: 'low',
    } satisfies AnthropicProviderOptions,
  },
});

Thinking Display (Opus 4.7+)

Starting with claude-opus-4-7, thinking content is omitted from the response by default — thinking blocks are present in the stream but their text is empty. To receive reasoning output, set display: 'summarized':

const { text, reasoningText } = await generateText({
  model: anthropic('claude-opus-4-8'),
  providerOptions: {
    anthropic: {
      thinking: { type: 'adaptive', display: 'summarized' },
    } satisfies AnthropicProviderOptions,
  },
  prompt: 'How many people will live in the world in 2040?',
});

console.log(reasoningText); // reasoning text (empty without display: 'summarized')
console.log(text);

Thinking Updates

Use display: 'updates' with claude-opus-5-5 or claude-fable-5-1 to stream thinking summaries between tool calls. These models return progress notes between tool calls as thinking blocks rather than text, so without this setting a long tool-calling turn can look silent. The provider adds the required thinking-display-updates-2026-08-18 beta header automatically:

import { anthropic, AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';
import { streamText, tool } from 'ai';
import { z } from 'zod';

const result = streamText({
  model: anthropic('claude-fable-5-1'),
  tools: {
    weather: tool({
      inputSchema: z.object({ city: z.string() }),
    }),
  },
  providerOptions: {
    anthropic: {
      thinking: { type: 'adaptive', display: 'updates' },
    } satisfies AnthropicLanguageModelOptions,
  },
  prompt: 'Compare the weather in San Francisco and New York.',
});

Thinking Block Binding

Fable 5.1 can recover from a thinking-block prefix mismatch by dropping the mismatched block. Set blockBinding.prefixMismatchBehavior to drop_block. You can provide block binding by itself to preserve the model's default thinking mode, or combine it with adaptive thinking.

const { text } = await generateText({
  model: anthropic('claude-fable-5-1'),
  prompt: 'Continue from this conversation.',
  providerOptions: {
    anthropic: {
      thinking: {
        blockBinding: {
          prefixMismatchBehavior: 'drop_block',
        },
      },
    } satisfies AnthropicLanguageModelOptions,
  },
});

Budget-Based Thinking

For earlier models (claude-opus-4-20250514, claude-sonnet-4-20250514, claude-sonnet-4-5-20250929), use type: 'enabled' with an explicit token budget:

import { anthropic, AnthropicProviderOptions } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const { text, reasoningText, reasoning } = await generateText({
  model: anthropic('claude-sonnet-4-5-20250929'),
  prompt: 'How many people will live in the world in 2040?',
  providerOptions: {
    anthropic: {
      thinking: { type: 'enabled', budgetTokens: 12000 },
    } satisfies AnthropicProviderOptions,
  },
});

console.log(reasoningText); // reasoning text
console.log(reasoning); // reasoning details including redacted reasoning
console.log(text); // text response

Anthropic's max_tokens limit includes both thinking and final text. To reserve room for both, the provider adds budgetTokens to maxOutputTokens when setting max_tokens. For known models, the combined value is capped at the model's maximum output token limit.

See AI SDK UI: Chatbot for more details on how to integrate reasoning into your chatbot.

Cache Control

In the messages and message parts, you can use the providerOptions property to set cache control breakpoints. You need to set the anthropic property in the providerOptions object to { cacheControl: { type: 'ephemeral' } } to set a cache control breakpoint.

The cache creation input tokens are then returned in the providerMetadata object for generateText and generateObject, again under the anthropic property. When you use streamText or streamObject, the response contains a promise that resolves to the metadata. Alternatively you can receive it in the onFinish callback.

import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const errorMessage = '... long error message ...';

const result = await generateText({
  model: anthropic('claude-3-5-sonnet-20240620'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'You are a JavaScript expert.' },
        {
          type: 'text',
          text: `Error message: ${errorMessage}`,
          providerOptions: {
            anthropic: { cacheControl: { type: 'ephemeral' } },
          },
        },
        { type: 'text', text: 'Explain the error message.' },
      ],
    },
  ],
});

console.log(result.text);
console.log(result.providerMetadata?.anthropic);
// e.g. { cacheCreationInputTokens: 2118 }

You can also use cache control on system messages by providing multiple system messages at the head of your messages array:

const result = await generateText({
  model: anthropic('claude-3-5-sonnet-20240620'),
  messages: [
    {
      role: 'system',
      content: 'Cached system message part',
      providerOptions: {
        anthropic: { cacheControl: { type: 'ephemeral' } },
      },
    },
    {
      role: 'system',
      content: 'Uncached system message part',
    },
    {
      role: 'user',
      content: 'User prompt',
    },
  ],
});

Cache control for tools:

const result = await generateText({
  model: anthropic('claude-3-5-haiku-latest'),
  tools: {
    cityAttractions: tool({
      inputSchema: z.object({ city: z.string() }),
      providerOptions: {
        anthropic: {
          cacheControl: { type: 'ephemeral' },
        },
      },
    }),
  },
  messages: [
    {
      role: 'user',
      content: 'User prompt',
    },
  ],
});

Longer cache TTL

Anthropic also supports a longer 1-hour cache duration.

Here's an example:

const result = await generateText({
  model: anthropic('claude-3-5-haiku-latest'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Long cached message',
          providerOptions: {
            anthropic: {
              cacheControl: { type: 'ephemeral', ttl: '1h' },
            },
          },
        },
      ],
    },
  ],
});

Limitations

The minimum cacheable prompt length is:

• 1024 tokens for Claude 3.7 Sonnet, Claude 3.5 Sonnet and Claude 3 Opus
• 2048 tokens for Claude 3.5 Haiku and Claude 3 Haiku

Shorter prompts cannot be cached, even if marked with cacheControl. Any requests to cache fewer than this number of tokens will be processed without caching.

For more on prompt caching with Anthropic, see Anthropic's Cache Control documentation.

Bash Tool

The Bash Tool allows running bash commands. Here's how to create and use it:

const bashTool = anthropic.tools.bash_20241022({
  execute: async ({ command, restart }) => {
    // Implement your bash command execution logic here
    // Return the result of the command execution
  },
});

Parameters:

• command (string): The bash command to run. Required unless the tool is being restarted.
• restart (boolean, optional): Specifying true will restart this tool.

Memory Tool

The Memory Tool allows Claude to use a local memory, e.g. in the filesystem. Here's how to create it:

const memory = anthropic.tools.memory_20250818({
  execute: async action => {
    // Implement your memory command execution logic here
    // Return the result of the command execution
  },
});

Text Editor Tool

The Text Editor Tool provides functionality for viewing and editing text files.

const tools = {
  // tool name must be str_replace_based_edit_tool
  str_replace_based_edit_tool: anthropic.tools.textEditor_20250728({
    maxCharacters: 10000, // optional
    async execute({ command, path, old_str, new_str }) {
      // ...
    },
  }),
} satisfies ToolSet;

Parameters:

• command ('view' | 'create' | 'str_replace' | 'insert' | 'undo_edit'): The command to run. Note: undo_edit is only available in Claude 3.5 Sonnet and earlier models.
• path (string): Absolute path to file or directory, e.g. /repo/file.py or /repo.
• file_text (string, optional): Required for create command, with the content of the file to be created.
• insert_line (number, optional): Required for insert command. The line number after which to insert the new string.
• new_str (string, optional): New string for str_replace or insert commands.
• old_str (string, optional): Required for str_replace command, containing the string to replace.
• view_range (number[], optional): Optional for view command to specify line range to show.

Computer Tool

The Computer Tool enables control of keyboard and mouse actions on a computer:

const computerTool = anthropic.tools.computer_20241022({
  displayWidthPx: 1920,
  displayHeightPx: 1080,
  displayNumber: 0, // Optional, for X11 environments

  execute: async ({ action, coordinate, text }) => {
    // Implement your computer control logic here
    // Return the result of the action

    // Example code:
    switch (action) {
      case 'screenshot': {
        // multipart result:
        return {
          type: 'image',
          data: fs
            .readFileSync('./data/screenshot-editor.png')
            .toString('base64'),
        };
      }
      default: {
        console.log('Action:', action);
        console.log('Coordinate:', coordinate);
        console.log('Text:', text);
        return `executed ${action}`;
      }
    }
  },

  // map to tool result content for LLM consumption:
  toModelOutput(result) {
    return typeof result === 'string'
      ? [{ type: 'text', text: result }]
      : [{ type: 'image', data: result.data, mediaType: 'image/png' }];
  },
});

Parameters:

• action ('key' | 'type' | 'mouse_move' | 'left_click' | 'left_click_drag' | 'right_click' | 'middle_click' | 'double_click' | 'screenshot' | 'cursor_position'): The action to perform.
• coordinate (number[], optional): Required for mouse_move and left_click_drag actions. Specifies the (x, y) coordinates.
• text (string, optional): Required for type and key actions.

These tools can be used in conjunction with the sonnet-3-5-sonnet-20240620 model to enable more complex interactions and tasks.

Computer Toolset

Newer models use the computer toolset instead of a versioned computer tool. claude-opus-5-5 accepts computer use only through the toolset and rejects the older computer_* tool types with a 400. The toolset does not require a beta header and has no display size parameters: coordinates are always in the pixel space of the screenshots you return. Zoom is enabled by default, and Claude can return several actions in one turn, each as its own tool call.

The API returns each action as a separate tool_use block with toolset_name: 'computer'. The AI SDK maps every action to the toolset tool and passes the action name as action, so execute receives the same input shape as the older computer tools. The tool name must be computer:

const computerTool = anthropic.tools.computerToolset_20260801({
  // optional: turn individual actions on or off
  configs: {
    zoom: { enabled: false },
  },

  execute: async ({ action, coordinate, text, region }) => {
    switch (action) {
      case 'screenshot': {
        return {
          type: 'image',
          data: fs.readFileSync('./data/screenshot.png').toString('base64'),
        };
      }
      default: {
        console.log('Action:', action, coordinate, text, region);
        return `executed ${action}`;
      }
    }
  },

  toModelOutput({ output }) {
    return {
      type: 'content',
      value: [
        typeof output === 'string'
          ? { type: 'text', text: output }
          : { type: 'media', data: output.data, mediaType: 'image/png' },
      ],
    };
  },
});

Parameters:

• action ('screenshot' | 'zoom' | 'left_click' | 'right_click' | 'middle_click' | 'double_click' | 'triple_click' | 'left_click_drag' | 'mouse_move' | 'left_mouse_down' | 'left_mouse_up' | 'cursor_position' | 'scroll' | 'type' | 'key' | 'hold_key' | 'wait'): The member tool that Claude invoked.
• coordinate (number[], optional): The (x, y) pixel coordinates for click, move, and scroll actions.
• start_coordinate (number[], optional): Where a left_click_drag starts.
• region (number[], optional): [x1, y1, x2, y2] for the zoom action.
• text (string, optional): Text to type, the key combination for key and hold_key, or modifier keys to hold during click and scroll actions.
• repeat (number, optional): How many times to press the key for key.
• duration (number, optional): Seconds for hold_key and wait.
• scroll_direction ('up' | 'down' | 'left' | 'right', optional) and scroll_amount (number, optional): For the scroll action.
• configs (object, optional): Per-action settings keyed by action name. Each entry accepts enabled (default true) and deferLoading (default false, for tool search).

Tool calls and results of the toolset are serialized with toolset_name when you pass the message history back. Keep the toolset tool in tools on follow-up requests, or the provider falls back to the toolsetName provider metadata on the tool calls of previous responses. Do not declare the toolset together with an older computer_* tool.

Web Search Tool

Anthropic provides a provider-defined web search tool that gives Claude direct access to real-time web content, allowing it to answer questions with up-to-date information beyond its knowledge cutoff.

You can enable web search using the provider-defined web search tool:

import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const webSearchTool = anthropic.tools.webSearch_20250305({
  maxUses: 5,
});

const result = await generateText({
  model: anthropic('claude-opus-4-20250514'),
  prompt: 'What are the latest developments in AI?',
  tools: {
    web_search: webSearchTool,
  },
});

Configuration Options

The web search tool supports several configuration options:

• maxUses number

  Maximum number of web searches Claude can perform during the conversation.

• allowedDomains string[]

  Optional list of domains that Claude is allowed to search. If provided, searches will be restricted to these domains.

• blockedDomains string[]

  Optional list of domains that Claude should avoid when searching.

• userLocation object

  Optional user location information to provide geographically relevant search results.

const webSearchTool = anthropic.tools.webSearch_20250305({
  maxUses: 3,
  allowedDomains: ['techcrunch.com', 'wired.com'],
  blockedDomains: ['example-spam-site.com'],
  userLocation: {
    type: 'approximate',
    country: 'US',
    region: 'California',
    city: 'San Francisco',
    timezone: 'America/Los_Angeles',
  },
});

const result = await generateText({
  model: anthropic('claude-opus-4-20250514'),
  prompt: 'Find local news about technology',
  tools: {
    web_search: webSearchTool,
  },
});

Web Fetch Tool

Anthropic provides a provider-defined web fetch tool that allows Claude to retrieve content from specific URLs. This is useful when you want Claude to analyze or reference content from a particular webpage or document.

You can enable web fetch using the provider-defined web fetch tool:

import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const result = await generateText({
  model: anthropic('claude-sonnet-4-0'),
  prompt:
    'What is this page about? https://en.wikipedia.org/wiki/Maglemosian_culture',
  tools: {
    web_fetch: anthropic.tools.webFetch_20250910({ maxUses: 1 }),
  },
});

Configuration Options

The web fetch tool supports several configuration options:

• maxUses number

  The maxUses parameter limits the number of web fetches performed.

• allowedDomains string[]

  Only fetch from these domains.

• blockedDomains string[]

  Never fetch from these domains.

• citations object

  Unlike web search where citations are always enabled, citations are optional for web fetch. Set "citations": {"enabled": true} to enable Claude to cite specific passages from fetched documents.

• maxContentTokens number

  The maxContentTokens parameter limits the amount of content that will be included in the context.

Error Handling

Web search errors are handled differently depending on whether you're using streaming or non-streaming:

Non-streaming (generateText, generateObject): Web search errors throw exceptions that you can catch:

try {
  const result = await generateText({
    model: anthropic('claude-opus-4-20250514'),
    prompt: 'Search for something',
    tools: {
      web_search: webSearchTool,
    },
  });
} catch (error) {
  if (error.message.includes('Web search failed')) {
    console.log('Search error:', error.message);
    // Handle search error appropriately
  }
}

Streaming (streamText, streamObject): Web search errors are delivered as error parts in the stream:

const result = await streamText({
  model: anthropic('claude-opus-4-20250514'),
  prompt: 'Search for something',
  tools: {
    web_search: webSearchTool,
  },
});

for await (const part of result.textStream) {
  if (part.type === 'error') {
    console.log('Search error:', part.error);
    // Handle search error appropriately
  }
}

Mid-Conversation System Controls

With claude-opus-5-5 and claude-fable-5-1, a mid-conversation system message can be cleared before the next user message with clearAt: 'next_user_message', or set the effort for the next turn without invalidating the prompt cache. The provider adds the required mid-conversation-system-clear-at-2026-08-21 and mid-conversation-output-config-2026-07-01 beta headers automatically.

import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const result = await generateText({
  model: anthropic('claude-fable-5-1'),
  allowSystemInMessages: true,
  messages: [
    {
      role: 'user',
      content: 'Draft a migration plan.',
    },
    {
      role: 'assistant',
      content: 'First, inventory the public API.',
    },
    {
      role: 'system',
      content: 'For the next turn, verify every compatibility claim.',
      providerOptions: {
        anthropic: {
          clearAt: 'next_user_message',
          effort: 'high',
        },
      },
    },
    {
      role: 'user',
      content: 'Complete the plan.',
    },
  ],
});

An effort-only system message can use an empty content array at the API level; in an AI SDK prompt, set content: ''. The provider serializes it as content: [].

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.

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.

Code Execution

Anthropic provides a provider-defined code execution tool that gives Claude direct access to a real Python environment allowing it to execute code to inform its responses.

You can enable code execution using the provider-defined code execution tool:

import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const codeExecutionTool = anthropic.tools.codeExecution_20260120();

const result = await generateText({
  model: anthropic('claude-opus-4-20250514'),
  prompt:
    'Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]',
  tools: {
    code_execution: codeExecutionTool,
  },
});

Error Handling

Code execution errors are handled differently depending on whether you're using streaming or non-streaming:

Non-streaming (generateText, generateObject): Code execution errors are delivered as tool result parts in the response:

const result = await generateText({
  model: anthropic('claude-opus-4-20250514'),
  prompt: 'Execute some Python script',
  tools: {
    code_execution: codeExecutionTool,
  },
});

const toolErrors = result.content?.filter(
  content => content.type === 'tool-error',
);

toolErrors?.forEach(error => {
  console.error('Tool execution error:', {
    toolName: error.toolName,
    toolCallId: error.toolCallId,
    error: error.error,
  });
});

Streaming (streamText, streamObject): Code execution errors are delivered as error parts in the stream:

const result = await streamText({
  model: anthropic('claude-opus-4-20250514'),
  prompt: 'Execute some Python script',
  tools: {
    code_execution: codeExecutionTool,
  },
});
for await (const part of result.textStream) {
  if (part.type === 'error') {
    console.log('Code execution error:', part.error);
    // Handle code execution error appropriately
  }
}

Agent Skills

Anthropic Agent Skills enable Claude to perform specialized tasks like document processing (PPTX, DOCX, PDF, XLSX) and data analysis. Skills run in a sandboxed container and require the code execution tool to be enabled.

Using Built-in Skills

Anthropic provides several built-in skills:

• pptx - Create and edit PowerPoint presentations
• docx - Create and edit Word documents
• pdf - Process and analyze PDF files
• xlsx - Work with Excel spreadsheets

To use skills, you need to:

1. Enable the code execution tool
2. Specify the container with skills in providerOptions

import { anthropic, AnthropicProviderOptions } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const result = await generateText({
  model: anthropic('claude-sonnet-4-5'),
  tools: {
    code_execution: anthropic.tools.codeExecution_20260120(),
  },
  prompt: 'Create a presentation about renewable energy with 5 slides',
  providerOptions: {
    anthropic: {
      container: {
        skills: [
          {
            type: 'anthropic',
            skillId: 'pptx',
            version: 'latest', // optional
          },
        ],
      },
    } satisfies AnthropicProviderOptions,
  },
});

Custom Skills

You can also use custom skills by specifying type: 'custom':

const result = await generateText({
  model: anthropic('claude-sonnet-4-5'),
  tools: {
    code_execution: anthropic.tools.codeExecution_20260120(),
  },
  prompt: 'Use my custom skill to process this data',
  providerOptions: {
    anthropic: {
      container: {
        skills: [
          {
            type: 'custom',
            skillId: 'my-custom-skill-id',
            version: '1.0', // optional
          },
        ],
      },
    } satisfies AnthropicProviderOptions,
  },
});

Compaction

The compact_20260112 edit type automatically summarizes earlier conversation context when token limits are reached. This is useful for long-running conversations where you want to preserve the essence of earlier exchanges while staying within token limits.

import { anthropic, AnthropicProviderOptions } from '@ai-sdk/anthropic';
import { streamText } from 'ai';

const result = streamText({
  model: anthropic('claude-opus-4-6'),
  messages: conversationHistory,
  providerOptions: {
    anthropic: {
      contextManagement: {
        edits: [
          {
            type: 'compact_20260112',
            trigger: {
              type: 'input_tokens',
              value: 50000, // trigger compaction when input exceeds 50k tokens
            },
            instructions:
              'Summarize the conversation concisely, preserving key decisions and context.',
            pauseAfterCompaction: false,
          },
        ],
      },
    } satisfies AnthropicProviderOptions,
  },
});

Configuration:

• trigger - Condition that triggers compaction (e.g., { type: 'input_tokens', value: 50000 })
• instructions - Custom instructions for how the model should summarize the conversation. Use this to guide the compaction summary towards specific aspects of the conversation you want to preserve.
• pauseAfterCompaction - When true, the model will pause after generating the compaction summary, allowing you to inspect or process it before continuing. Defaults to false.

When compaction occurs, the model generates a summary of the earlier context. This summary appears as a text block with special provider metadata.

Detecting Compaction in Streams

When using streamText, you can detect compaction summaries by checking the providerMetadata on text-start events:

for await (const part of result.fullStream) {
  switch (part.type) {
    case 'text-start': {
      const isCompaction =
        part.providerMetadata?.anthropic?.type === 'compaction';
      if (isCompaction) {
        console.log('[COMPACTION SUMMARY START]');
      }
      break;
    }
    case 'text-delta': {
      process.stdout.write(part.text);
      break;
    }
  }
}

Compaction in UI Applications

When using useChat or other UI hooks, compaction summaries appear as regular text parts with providerMetadata. You can style them differently in your UI:

{
  message.parts.map((part, index) => {
    if (part.type === 'text') {
      const isCompaction =
        (part.providerMetadata?.anthropic as { type?: string } | undefined)
          ?.type === 'compaction';

      if (isCompaction) {
        return (
          <div
            key={index}
            className="bg-yellow-100 border-l-4 border-yellow-500 p-2"
          >
            <span className="font-bold">[Compaction Summary]</span>
            <div>{part.text}</div>
          </div>
        );
      }
      return <div key={index}>{part.text}</div>;
    }
  });
}

PDF support

Anthropic Sonnet claude-3-5-sonnet-20241022 supports reading PDF files. You can pass PDF files as part of the message content using the file type:

Option 1: URL-based PDF document

const result = await generateText({
  model: anthropic('claude-3-5-sonnet-20241022'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'What is an embedding model according to this document?',
        },
        {
          type: 'file',
          data: new URL(
            'https://github.com/vercel/ai/blob/main/examples/ai-core/data/ai.pdf?raw=true',
          ),
          mimeType: 'application/pdf',
        },
      ],
    },
  ],
});

Option 2: Base64-encoded PDF document

const result = await generateText({
  model: anthropic('claude-3-5-sonnet-20241022'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'What is an embedding model according to this document?',
        },
        {
          type: 'file',
          data: fs.readFileSync('./data/ai.pdf'),
          mediaType: 'application/pdf',
        },
      ],
    },
  ],
});

The model will have access to the contents of the PDF file and respond to questions about it. The PDF file should be passed using the data field, and the mediaType should be set to 'application/pdf'.

Model Capabilities