@ai-sdk/anthropic 4.0.0-beta.4 → 4.0.0-beta.41

package/docs/05-anthropic.mdx

@@ -122,14 +122,22 @@ The following optional provider options are available for Anthropic models:
   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` _"high" | "medium" | "low"_
+- `effort` _"low" | "medium" | "high" | "xhigh" | "max"_
 
   Optional. See [Effort section](#effort) for more details.
 
+- `taskBudget` _object_
+
+  Optional. See [Task Budgets section](#task-budgets) for more details.
+
 - `speed` _"fast" | "standard"_
 
   Optional. See [Fast Mode section](#fast-mode) for more details.
 
+- `inferenceGeo` _"us" | "global"_
+
+  Optional. See [Data Residency section](#data-residency) for more details.
+
 - `thinking` _object_
 
   Optional. See [Reasoning section](#reasoning) for more details.
@@ -146,6 +154,12 @@ The following optional provider options are available for Anthropic models:
   - `"jsonTool"`: Use a special `"json"` tool to specify the structured output format.
   - `"auto"`: Use `"outputFormat"` when supported, otherwise fall back to `"jsonTool"` (default).
 
+- `metadata` _object_
+
+  Optional. Metadata to include with the request. See the [Anthropic API documentation](https://platform.claude.com/docs/en/api/messages/create) 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
 
 Tool call streaming is enabled by default. You can opt out by setting the
@@ -177,7 +191,7 @@ 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).
+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` additionally supports `xhigh` for maximum reasoning effort.
 
 ```ts highlight="8-10"
 import { anthropic, AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';
@@ -218,6 +232,67 @@ const { text } = await generateText({
 
 The `speed` option accepts `'fast'` or `'standard'` (default behavior).
 
+### 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.
+
+```ts highlight="8-13"
+import { anthropic, AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: anthropic('claude-opus-4-7'),
+  prompt: 'Research the pros and cons of Rust vs Go for building CLI tools.',
+  providerOptions: {
+    anthropic: {
+      taskBudget: {
+        type: 'tokens',
+        total: 400000,
+      },
+    } satisfies AnthropicLanguageModelOptions,
+  },
+});
+```
+
+For long-running agents that compact and restart context, you can carry the remaining budget forward using the `remaining` field:
+
+```ts
+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.
+
+### Data Residency
+
+Anthropic supports an [`inferenceGeo` option](https://platform.claude.com/docs/en/build-with-claude/data-residency) that controls where model inference runs for a request.
+
+```ts highlight="8-10"
+import { anthropic, AnthropicLanguageModelOptions } 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 AnthropicLanguageModelOptions,
+  },
+});
+```
+
+The `inferenceGeo` option accepts `'us'` (US-only infrastructure) or `'global'` (default, any available geography).
+
 ### Reasoning
 
 Anthropic models support extended thinking, where Claude shows its reasoning process before providing a final answer.
@@ -261,6 +336,31 @@ const { text } = await generateText({
 });
 ```
 
+##### 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'`:
+
+```ts highlight="5"
+const { text, reasoningText } = await generateText({
+  model: anthropic('claude-opus-4-7'),
+  providerOptions: {
+    anthropic: {
+      thinking: { type: 'adaptive', display: 'summarized' },
+    } satisfies AnthropicLanguageModelOptions,
+  },
+  prompt: 'How many people will live in the world in 2040?',
+});
+
+console.log(reasoningText); // reasoning text (empty without display: 'summarized')
+console.log(text);
+```
+
+<Note>
+  If you stream reasoning to users with `claude-opus-4-7`, the default `"omitted"` display will
+  cause a long pause before output begins. Set `display: "summarized"` to restore visible
+  progress during thinking.
+</Note>
+
 #### Budget-Based Thinking
 
 For earlier models (`claude-opus-4-20250514`, `claude-sonnet-4-20250514`, `claude-sonnet-4-5-20250929`),
@@ -484,13 +584,12 @@ For more details, see [Anthropic's Context Management documentation](https://doc
 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`, again under the `anthropic` property.
-When you use `streamText`, the response contains a promise
-that resolves to the metadata. Alternatively you can receive it in the
-`onFinish` callback.
+Cache read and cache write (creation) token counts are returned on the standard
+`usage` object for both `generateText` and `streamText`. You can access them at
+`result.usage.inputTokenDetails.cacheReadTokens` and
+`result.usage.inputTokenDetails.cacheWriteTokens`.
 
-```ts highlight="8,18-20,29-30"
+```ts highlight="8,18-20,29-32"
 import { anthropic } from '@ai-sdk/anthropic';
 import { generateText } from 'ai';
 
@@ -517,8 +616,11 @@ const result = await generateText({
 });
 
 console.log(result.text);
-console.log(result.providerMetadata?.anthropic);
-// e.g. { cacheCreationInputTokens: 2118 }
+console.log('Cache read tokens:', result.usage.inputTokenDetails.cacheReadTokens);
+console.log(
+  'Cache write tokens:',
+  result.usage.inputTokenDetails.cacheWriteTokens,
+);
 ```
 
 You can also use cache control on system messages by providing multiple system messages at the head of your messages array:
@@ -741,7 +843,7 @@ const computerTool = anthropic.tools.computer_20251124({
   toModelOutput({ output }) {
     return typeof output === 'string'
       ? [{ type: 'text', text: output }]
-      : [{ type: 'image', data: output.data, mediaType: 'image/png' }];
+      : [{ type: 'file-data', data: output.data, mediaType: 'image/png' }];
   },
 });
 ```
@@ -1155,12 +1257,12 @@ import {
   anthropic,
   forwardAnthropicContainerIdFromLastStep,
 } from '@ai-sdk/anthropic';
-import { generateText, tool, stepCountIs } from 'ai';
+import { generateText, tool, isStepCount } from 'ai';
 import { z } from 'zod';
 
 const result = await generateText({
   model: anthropic('claude-sonnet-4-5'),
-  stopWhen: stepCountIs(10),
+  stopWhen: isStepCount(10),
   prompt:
     'Get the weather for Tokyo, Sydney, and London, then calculate the average temperature.',
   tools: {
@@ -1345,6 +1447,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-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} /> |                     |
 | `claude-opus-4-5`   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |                     |

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@ai-sdk/anthropic",
-  "version": "4.0.0-beta.4",
+  "version": "4.0.0-beta.41",
+  "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
@@ -25,27 +25,26 @@
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./internal": {
       "types": "./dist/internal/index.d.ts",
-      "import": "./dist/internal/index.mjs",
-      "module": "./dist/internal/index.mjs",
-      "require": "./dist/internal/index.js"
+      "import": "./dist/internal/index.js",
+      "default": "./dist/internal/index.js"
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.0-beta.0",
-    "@ai-sdk/provider-utils": "5.0.0-beta.1"
+    "@ai-sdk/provider": "4.0.0-beta.14",
+    "@ai-sdk/provider-utils": "5.0.0-beta.29"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
     "tsup": "^8",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@vercel/ai-tsconfig": "0.0.0",
-    "@ai-sdk/test-server": "2.0.0-beta.0"
+    "@ai-sdk/test-server": "2.0.0-beta.3",
+    "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"
@@ -54,12 +53,14 @@
     "node": ">=18"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "homepage": "https://ai-sdk.dev/docs",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vercel/ai.git"
+    "url": "https://github.com/vercel/ai",
+    "directory": "packages/anthropic"
   },
   "bugs": {
     "url": "https://github.com/vercel/ai/issues"
@@ -71,9 +72,7 @@
     "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
     "build:watch": "pnpm clean && tsup --watch --tsconfig tsconfig.build.json",
     "clean": "del-cli dist docs *.tsbuildinfo",
-    "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --build",
-    "prettier-check": "prettier --check \"./**/*.ts*\"",
     "test": "pnpm test:node && pnpm test:edge",
     "test:update": "pnpm test:node -u",
     "test:watch": "vitest --config vitest.node.config.js",

package/src/{anthropic-messages-api.ts → anthropic-api.ts}

@@ -1,8 +1,12 @@
-import { JSONSchema7 } from '@ai-sdk/provider';
-import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import type { JSONSchema7 } from '@ai-sdk/provider';
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
-export type AnthropicMessagesPrompt = {
+export type AnthropicPrompt = {
   system: Array<AnthropicTextContent> | undefined;
   messages: AnthropicMessage[];
 };
@@ -87,6 +91,10 @@ type AnthropicContentSource =
       type: 'text';
       media_type: 'text/plain';
       data: string;
+    }
+  | {
+      type: 'file';
+      file_id: string;
     };
 
 export interface AnthropicImageContent {
@@ -549,7 +557,7 @@ export type AnthropicResponseContextManagement = {
 
 // 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(() =>
+export const anthropicResponseSchema = lazySchema(() =>
   zodSchema(
     z.object({
       type: z.literal('message'),
@@ -889,7 +897,7 @@ export const anthropicMessagesResponseSchema = lazySchema(() =>
 
 // limited version of the schema, focused on what is needed for the implementation
 // this approach limits breakages when the API changes and increases efficiency
-export const anthropicMessagesChunkSchema = lazySchema(() =>
+export const anthropicChunkSchema = lazySchema(() =>
   zodSchema(
     z.discriminatedUnion('type', [
       z.object({
@@ -1338,7 +1346,7 @@ export type AnthropicReasoningMetadata = InferSchema<
 >;
 
 export type Citation = NonNullable<
-  (InferSchema<typeof anthropicMessagesResponseSchema>['content'][number] & {
+  (InferSchema<typeof anthropicResponseSchema>['content'][number] & {
     type: 'text';
   })['citations']
 >[number];

package/src/anthropic-error.ts

@@ -1,8 +1,8 @@
 import {
   createJsonErrorResponseHandler,
-  InferSchema,
   lazySchema,
   zodSchema,
+  type InferSchema,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 

package/src/anthropic-files.ts

@@ -0,0 +1,95 @@
+import type {
+  FilesV4,
+  FilesV4UploadFileCallOptions,
+  FilesV4UploadFileResult,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertInlineFileDataToUint8Array,
+  createJsonResponseHandler,
+  lazySchema,
+  postFormDataToApi,
+  zodSchema,
+  type FetchFunction,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { anthropicFailedResponseHandler } from './anthropic-error';
+
+const anthropicUploadFileResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      id: z.string(),
+      type: z.literal('file'),
+      filename: z.string(),
+      mime_type: z.string(),
+      size_bytes: z.number(),
+      created_at: z.string(),
+      downloadable: z.boolean().nullish(),
+    }),
+  ),
+);
+
+interface AnthropicFilesConfig {
+  provider: string;
+  baseURL: string;
+  headers: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+}
+
+export class AnthropicFiles implements FilesV4 {
+  readonly specificationVersion = 'v4';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(private readonly config: AnthropicFilesConfig) {}
+
+  async uploadFile({
+    data,
+    mediaType,
+    filename,
+  }: FilesV4UploadFileCallOptions): Promise<FilesV4UploadFileResult> {
+    const fileBytes = convertInlineFileDataToUint8Array(data);
+
+    const blob = new Blob([fileBytes], { type: mediaType });
+
+    const formData = new FormData();
+    if (filename != null) {
+      formData.append('file', blob, filename);
+    } else {
+      formData.append('file', blob);
+    }
+
+    const { value: response } = await postFormDataToApi({
+      url: `${this.config.baseURL}/files`,
+      headers: combineHeaders(this.config.headers(), {
+        'anthropic-beta': 'files-api-2025-04-14',
+      }),
+      formData,
+      failedResponseHandler: anthropicFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        anthropicUploadFileResponseSchema,
+      ),
+      fetch: this.config.fetch,
+    });
+
+    return {
+      warnings: [],
+      providerReference: { anthropic: response.id },
+      mediaType: response.mime_type ?? mediaType,
+      filename: response.filename ?? filename,
+      providerMetadata: {
+        anthropic: {
+          filename: response.filename,
+          mimeType: response.mime_type,
+          sizeBytes: response.size_bytes,
+          createdAt: response.created_at,
+          ...(response.downloadable != null
+            ? { downloadable: response.downloadable }
+            : {}),
+        },
+      },
+    };
+  }
+}