@ai-sdk/anthropic 4.0.0-beta.2 → 4.0.0-beta.21

package/src/anthropic-messages-options.ts

@@ -112,6 +112,23 @@ export const anthropicLanguageModelOptions = z.object({
     })
     .optional(),
 
+  /**
+   * Metadata to include with the request.
+   *
+   * See https://platform.claude.com/docs/en/api/messages/create for details.
+   */
+  metadata: z
+    .object({
+      /**
+       * An external identifier for the user associated with the request.
+       *
+       * Should be a UUID, hash value, or other opaque identifier.
+       * Must not contain PII (name, email, phone number, etc.).
+       */
+      userId: z.string().optional(),
+    })
+    .optional(),
+
   /**
    * MCP servers to be utilized in this request.
    */
@@ -142,11 +159,18 @@ export const anthropicLanguageModelOptions = z.object({
       id: z.string().optional(),
       skills: z
         .array(
-          z.object({
-            type: z.union([z.literal('anthropic'), z.literal('custom')]),
-            skillId: z.string(),
-            version: z.string().optional(),
-          }),
+          z.discriminatedUnion('type', [
+            z.object({
+              type: z.literal('anthropic'),
+              skillId: z.string(),
+              version: z.string().optional(),
+            }),
+            z.object({
+              type: z.literal('custom'),
+              providerReference: z.record(z.string(), z.string()),
+              version: z.string().optional(),
+            }),
+          ]),
         )
         .optional(),
     })

package/src/anthropic-prepare-tools.ts

@@ -1,6 +1,6 @@
 import {
-  LanguageModelV3CallOptions,
-  SharedV3Warning,
+  LanguageModelV4CallOptions,
+  SharedV4Warning,
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
 import { AnthropicTool, AnthropicToolChoice } from './anthropic-messages-api';
@@ -26,26 +26,32 @@ export async function prepareTools({
   disableParallelToolUse,
   cacheControlValidator,
   supportsStructuredOutput,
+  supportsStrictTools,
 }: {
-  tools: LanguageModelV3CallOptions['tools'];
-  toolChoice: LanguageModelV3CallOptions['toolChoice'] | undefined;
+  tools: LanguageModelV4CallOptions['tools'];
+  toolChoice: LanguageModelV4CallOptions['toolChoice'] | undefined;
   disableParallelToolUse?: boolean;
   cacheControlValidator?: CacheControlValidator;
 
   /**
-   * Whether the model supports structured output.
+   * Whether the model supports native structured output response format.
    */
   supportsStructuredOutput: boolean;
+
+  /**
+   * Whether the model supports strict mode on tool definitions.
+   */
+  supportsStrictTools: boolean;
 }): Promise<{
   tools: Array<AnthropicTool> | undefined;
   toolChoice: AnthropicToolChoice | undefined;
-  toolWarnings: SharedV3Warning[];
+  toolWarnings: SharedV4Warning[];
   betas: Set<string>;
 }> {
   // when the tools array is empty, change it to undefined to prevent errors:
   tools = tools?.length ? tools : undefined;
 
-  const toolWarnings: SharedV3Warning[] = [];
+  const toolWarnings: SharedV4Warning[] = [];
   const betas = new Set<string>();
   const validator = cacheControlValidator || new CacheControlValidator();
 
@@ -72,13 +78,21 @@ export async function prepareTools({
         const deferLoading = anthropicOptions?.deferLoading;
         const allowedCallers = anthropicOptions?.allowedCallers;
 
+        if (!supportsStrictTools && tool.strict != null) {
+          toolWarnings.push({
+            type: 'unsupported',
+            feature: 'strict',
+            details: `Tool '${tool.name}' has strict: ${tool.strict}, but strict mode is not supported by this provider. The strict property will be ignored.`,
+          });
+        }
+
         anthropicTools.push({
           name: tool.name,
           description: tool.description,
           input_schema: tool.inputSchema,
           cache_control: cacheControl,
           ...(eagerInputStreaming ? { eager_input_streaming: true } : {}),
-          ...(supportsStructuredOutput === true && tool.strict != null
+          ...(supportsStrictTools === true && tool.strict != null
             ? { strict: tool.strict }
             : {}),
           ...(deferLoading != null ? { defer_loading: deferLoading } : {}),
@@ -308,7 +322,6 @@ export async function prepareTools({
           }
 
           case 'anthropic.tool_search_regex_20251119': {
-            betas.add('advanced-tool-use-2025-11-20');
             anthropicTools.push({
               type: 'tool_search_tool_regex_20251119',
               name: 'tool_search_tool_regex',
@@ -317,7 +330,6 @@ export async function prepareTools({
           }
 
           case 'anthropic.tool_search_bm25_20251119': {
-            betas.add('advanced-tool-use-2025-11-20');
             anthropicTools.push({
               type: 'tool_search_tool_bm25_20251119',
               name: 'tool_search_tool_bm25',

package/src/anthropic-provider.ts

@@ -1,8 +1,10 @@
 import {
+  FilesV4,
   InvalidArgumentError,
-  LanguageModelV3,
+  LanguageModelV4,
   NoSuchModelError,
-  ProviderV3,
+  ProviderV4,
+  SkillsV4,
 } from '@ai-sdk/provider';
 import {
   FetchFunction,
@@ -12,31 +14,40 @@ import {
   withoutTrailingSlash,
   withUserAgentSuffix,
 } from '@ai-sdk/provider-utils';
-import { VERSION } from './version';
+import { AnthropicFiles } from './anthropic-files';
 import { AnthropicMessagesLanguageModel } from './anthropic-messages-language-model';
 import { AnthropicMessagesModelId } from './anthropic-messages-options';
 import { anthropicTools } from './anthropic-tools';
+import { AnthropicSkills } from './skills/anthropic-skills';
+import { VERSION } from './version';
 
-export interface AnthropicProvider extends ProviderV3 {
+export interface AnthropicProvider extends ProviderV4 {
   /**
    * Creates a model for text generation.
    */
-  (modelId: AnthropicMessagesModelId): LanguageModelV3;
+  (modelId: AnthropicMessagesModelId): LanguageModelV4;
 
   /**
    * Creates a model for text generation.
    */
-  languageModel(modelId: AnthropicMessagesModelId): LanguageModelV3;
+  languageModel(modelId: AnthropicMessagesModelId): LanguageModelV4;
 
-  chat(modelId: AnthropicMessagesModelId): LanguageModelV3;
+  chat(modelId: AnthropicMessagesModelId): LanguageModelV4;
 
-  messages(modelId: AnthropicMessagesModelId): LanguageModelV3;
+  messages(modelId: AnthropicMessagesModelId): LanguageModelV4;
 
   /**
    * @deprecated Use `embeddingModel` instead.
    */
   textEmbeddingModel(modelId: string): never;
 
+  files(): FilesV4;
+
+  /**
+   * Returns a SkillsV4 interface for uploading skills to Anthropic.
+   */
+  skills(): SkillsV4;
+
   /**
    * Anthropic-specific computer use tool.
    */
@@ -143,6 +154,14 @@ export function createAnthropic(
       }),
     });
 
+  const createSkills = () =>
+    new AnthropicSkills({
+      provider: `${providerName.replace('.messages', '')}.skills`,
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
   const provider = function (modelId: AnthropicMessagesModelId) {
     if (new.target) {
       throw new Error(
@@ -153,7 +172,7 @@ export function createAnthropic(
     return createChatModel(modelId);
   };
 
-  provider.specificationVersion = 'v3' as const;
+  provider.specificationVersion = 'v4' as const;
   provider.languageModel = createChatModel;
   provider.chat = createChatModel;
   provider.messages = createChatModel;
@@ -166,6 +185,16 @@ export function createAnthropic(
     throw new NoSuchModelError({ modelId, modelType: 'imageModel' });
   };
 
+  provider.files = () =>
+    new AnthropicFiles({
+      provider: providerName,
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  provider.skills = createSkills;
+
   provider.tools = anthropicTools;
 
   return provider;

package/src/convert-anthropic-messages-usage.ts

@@ -1,4 +1,4 @@
-import { JSONObject, LanguageModelV3Usage } from '@ai-sdk/provider';
+import { JSONObject, LanguageModelV4Usage } from '@ai-sdk/provider';
 
 /**
  * Represents a single iteration in the usage breakdown.
@@ -31,7 +31,7 @@ export function convertAnthropicMessagesUsage({
 }: {
   usage: AnthropicMessagesUsage;
   rawUsage?: JSONObject;
-}): LanguageModelV3Usage {
+}): LanguageModelV4Usage {
   const cacheCreationTokens = usage.cache_creation_input_tokens ?? 0;
   const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
 

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

@@ -1,15 +1,17 @@
 import {
-  SharedV3Warning,
-  LanguageModelV3DataContent,
-  LanguageModelV3Message,
-  LanguageModelV3Prompt,
-  SharedV3ProviderMetadata,
+  SharedV4Warning,
+  LanguageModelV4DataContent,
+  LanguageModelV4Message,
+  LanguageModelV4Prompt,
+  SharedV4ProviderMetadata,
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
 import {
   convertBase64ToUint8Array,
   convertToBase64,
+  isProviderReference,
   parseProviderOptions,
+  resolveProviderReference,
   validateTypes,
   isNonNullable,
   ToolNameMapping,
@@ -31,7 +33,7 @@ import { toolSearchRegex_20251119OutputSchema as toolSearchOutputSchema } from '
 import { webFetch_20250910OutputSchema } from './tool/web-fetch-20250910';
 import { webSearch_20250305OutputSchema } from './tool/web-search_20250305';
 
-function convertToString(data: LanguageModelV3DataContent): string {
+function convertToString(data: LanguageModelV4DataContent): string {
   if (typeof data === 'string') {
     return new TextDecoder().decode(convertBase64ToUint8Array(data));
   }
@@ -55,16 +57,16 @@ function convertToString(data: LanguageModelV3DataContent): string {
  * Checks if data is a URL (either a URL object or a URL string).
  */
 function isUrlData(
-  data: LanguageModelV3DataContent,
+  data: LanguageModelV4DataContent,
 ): data is URL | (string & { __brand: 'url-string' }) {
   return data instanceof URL || isUrlString(data);
 }
 
-function isUrlString(data: LanguageModelV3DataContent): boolean {
+function isUrlString(data: LanguageModelV4DataContent): boolean {
   return typeof data === 'string' && /^https?:\/\//i.test(data);
 }
 
-function getUrlString(data: LanguageModelV3DataContent): string {
+function getUrlString(data: LanguageModelV4DataContent): string {
   return data instanceof URL ? data.toString() : (data as string);
 }
 
@@ -75,9 +77,9 @@ export async function convertToAnthropicMessagesPrompt({
   cacheControlValidator,
   toolNameMapping,
 }: {
-  prompt: LanguageModelV3Prompt;
+  prompt: LanguageModelV4Prompt;
   sendReasoning: boolean;
-  warnings: SharedV3Warning[];
+  warnings: SharedV4Warning[];
   cacheControlValidator?: CacheControlValidator;
   toolNameMapping: ToolNameMapping;
 }): Promise<{
@@ -92,7 +94,7 @@ export async function convertToAnthropicMessagesPrompt({
   const messages: AnthropicMessagesPrompt['messages'] = [];
 
   async function shouldEnableCitations(
-    providerMetadata: SharedV3ProviderMetadata | undefined,
+    providerMetadata: SharedV4ProviderMetadata | undefined,
   ): Promise<boolean> {
     const anthropicOptions = await parseProviderOptions({
       provider: 'anthropic',
@@ -104,7 +106,7 @@ export async function convertToAnthropicMessagesPrompt({
   }
 
   async function getDocumentMetadata(
-    providerMetadata: SharedV3ProviderMetadata | undefined,
+    providerMetadata: SharedV4ProviderMetadata | undefined,
   ): Promise<{ title?: string; context?: string }> {
     const anthropicOptions = await parseProviderOptions({
       provider: 'anthropic',
@@ -183,7 +185,27 @@ export async function convertToAnthropicMessagesPrompt({
                   }
 
                   case 'file': {
-                    if (part.mediaType.startsWith('image/')) {
+                    if (isProviderReference(part.data)) {
+                      const fileId = resolveProviderReference({
+                        reference: part.data,
+                        provider: 'anthropic',
+                      });
+                      betas.add('files-api-2025-04-14');
+
+                      if (part.mediaType.startsWith('image/')) {
+                        anthropicContent.push({
+                          type: 'image',
+                          source: { type: 'file', file_id: fileId },
+                          cache_control: cacheControl,
+                        });
+                      } else {
+                        anthropicContent.push({
+                          type: 'document',
+                          source: { type: 'file', file_id: fileId },
+                          cache_control: cacheControl,
+                        });
+                      }
+                    } else if (part.mediaType.startsWith('image/')) {
                       anthropicContent.push({
                         type: 'image',
                         source: isUrlData(part.data)
@@ -1051,19 +1073,19 @@ export async function convertToAnthropicMessagesPrompt({
 
 type SystemBlock = {
   type: 'system';
-  messages: Array<LanguageModelV3Message & { role: 'system' }>;
+  messages: Array<LanguageModelV4Message & { role: 'system' }>;
 };
 type AssistantBlock = {
   type: 'assistant';
-  messages: Array<LanguageModelV3Message & { role: 'assistant' }>;
+  messages: Array<LanguageModelV4Message & { role: 'assistant' }>;
 };
 type UserBlock = {
   type: 'user';
-  messages: Array<LanguageModelV3Message & { role: 'user' | 'tool' }>;
+  messages: Array<LanguageModelV4Message & { role: 'user' | 'tool' }>;
 };
 
 function groupIntoBlocks(
-  prompt: LanguageModelV3Prompt,
+  prompt: LanguageModelV4Prompt,
 ): Array<SystemBlock | AssistantBlock | UserBlock> {
   const blocks: Array<SystemBlock | AssistantBlock | UserBlock> = [];
   let currentBlock: SystemBlock | AssistantBlock | UserBlock | undefined =

package/src/get-cache-control.ts

@@ -1,4 +1,4 @@
-import { SharedV3Warning, SharedV3ProviderMetadata } from '@ai-sdk/provider';
+import { SharedV4Warning, SharedV4ProviderMetadata } from '@ai-sdk/provider';
 import { AnthropicCacheControl } from './anthropic-messages-api';
 
 // Anthropic allows a maximum of 4 cache breakpoints per request
@@ -7,7 +7,7 @@ const MAX_CACHE_BREAKPOINTS = 4;
 // Helper function to extract cache_control from provider metadata
 // Allows both cacheControl and cache_control for flexibility
 function getCacheControl(
-  providerMetadata: SharedV3ProviderMetadata | undefined,
+  providerMetadata: SharedV4ProviderMetadata | undefined,
 ): AnthropicCacheControl | undefined {
   const anthropic = providerMetadata?.anthropic;
 
@@ -21,10 +21,10 @@ function getCacheControl(
 
 export class CacheControlValidator {
   private breakpointCount = 0;
-  private warnings: SharedV3Warning[] = [];
+  private warnings: SharedV4Warning[] = [];
 
   getCacheControl(
-    providerMetadata: SharedV3ProviderMetadata | undefined,
+    providerMetadata: SharedV4ProviderMetadata | undefined,
     context: { type: string; canCache: boolean },
   ): AnthropicCacheControl | undefined {
     const cacheControlValue = getCacheControl(providerMetadata);
@@ -57,7 +57,7 @@ export class CacheControlValidator {
     return cacheControlValue;
   }
 
-  getWarnings(): SharedV3Warning[] {
+  getWarnings(): SharedV4Warning[] {
     return this.warnings;
   }
 }

package/src/internal/index.ts

@@ -1,4 +1,7 @@
-export { AnthropicMessagesLanguageModel } from '../anthropic-messages-language-model';
+export {
+  AnthropicMessagesLanguageModel,
+  getModelCapabilities,
+} from '../anthropic-messages-language-model';
 export { anthropicTools } from '../anthropic-tools';
 export type { AnthropicMessagesModelId } from '../anthropic-messages-options';
 export { prepareTools } from '../anthropic-prepare-tools';

package/src/map-anthropic-stop-reason.ts

@@ -1,4 +1,4 @@
-import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+import { LanguageModelV4FinishReason } from '@ai-sdk/provider';
 
 /**
  * @see https://docs.anthropic.com/en/api/messages#response-stop-reason
@@ -9,7 +9,7 @@ export function mapAnthropicStopReason({
 }: {
   finishReason: string | null | undefined;
   isJsonResponseFromTool?: boolean;
-}): LanguageModelV3FinishReason['unified'] {
+}): LanguageModelV4FinishReason['unified'] {
   switch (finishReason) {
     case 'pause_turn':
     case 'end_turn':

package/src/skills/anthropic-skills-api.ts

@@ -0,0 +1,44 @@
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const anthropicSkillResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      id: z.string(),
+      display_title: z.string().nullish(),
+      name: z.string().nullish(),
+      description: z.string().nullish(),
+      latest_version: z.string().nullish(),
+      source: z.string(),
+      created_at: z.string(),
+      updated_at: z.string(),
+    }),
+  ),
+);
+
+export type AnthropicSkillResponse = ReturnType<
+  typeof anthropicSkillResponseSchema
+>['_type'];
+
+export const anthropicSkillVersionListResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      data: z.array(
+        z.object({
+          version: z.string(),
+        }),
+      ),
+    }),
+  ),
+);
+
+export const anthropicSkillVersionResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      type: z.string(),
+      skill_id: z.string(),
+      name: z.string().nullish(),
+      description: z.string().nullish(),
+    }),
+  ),
+);

package/src/skills/anthropic-skills.ts

@@ -0,0 +1,136 @@
+import { SkillsV4, SharedV4Warning } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertBase64ToUint8Array,
+  createJsonResponseHandler,
+  FetchFunction,
+  getFromApi,
+  postFormDataToApi,
+  Resolvable,
+  resolve,
+} from '@ai-sdk/provider-utils';
+import { anthropicFailedResponseHandler } from '../anthropic-error';
+import {
+  anthropicSkillResponseSchema,
+  anthropicSkillVersionResponseSchema,
+} from './anthropic-skills-api';
+
+interface AnthropicSkillsConfig {
+  provider: string;
+  baseURL: string;
+  headers: Resolvable<Record<string, string | undefined>>;
+  fetch?: FetchFunction;
+}
+
+export class AnthropicSkills implements SkillsV4 {
+  readonly specificationVersion = 'v4';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(private readonly config: AnthropicSkillsConfig) {}
+
+  private async getHeaders(): Promise<Record<string, string | undefined>> {
+    return combineHeaders(await resolve(this.config.headers), {
+      'anthropic-beta': 'skills-2025-10-02',
+    });
+  }
+
+  private async fetchVersionMetadata({
+    skillId,
+    version,
+    headers,
+  }: {
+    skillId: string;
+    version: string;
+    headers: Record<string, string | undefined>;
+  }): Promise<{ name?: string; description?: string }> {
+    const { value: versionResponse } = await getFromApi({
+      url: `${this.config.baseURL}/skills/${skillId}/versions/${version}`,
+      headers,
+      failedResponseHandler: anthropicFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        anthropicSkillVersionResponseSchema,
+      ),
+      fetch: this.config.fetch,
+    });
+
+    return {
+      ...(versionResponse.name != null ? { name: versionResponse.name } : {}),
+      ...(versionResponse.description != null
+        ? { description: versionResponse.description }
+        : {}),
+    };
+  }
+
+  async upload(
+    params: Parameters<SkillsV4['upload']>[0],
+  ): Promise<Awaited<ReturnType<SkillsV4['upload']>>> {
+    const warnings: SharedV4Warning[] = [];
+
+    const formData = new FormData();
+
+    if (params.displayTitle != null) {
+      formData.append('display_title', params.displayTitle);
+    }
+
+    for (const file of params.files) {
+      const content =
+        typeof file.content === 'string'
+          ? convertBase64ToUint8Array(file.content)
+          : file.content;
+
+      formData.append('files[]', new Blob([content]), file.path);
+    }
+
+    const headers = await this.getHeaders();
+
+    const { value: response } = await postFormDataToApi({
+      url: `${this.config.baseURL}/skills`,
+      headers,
+      formData,
+      failedResponseHandler: anthropicFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        anthropicSkillResponseSchema,
+      ),
+      fetch: this.config.fetch,
+    });
+
+    const versionMetadata =
+      response.latest_version != null
+        ? await this.fetchVersionMetadata({
+            skillId: response.id,
+            version: response.latest_version,
+            headers,
+          })
+        : {};
+
+    const name = versionMetadata.name ?? response.name;
+    const description = versionMetadata.description ?? response.description;
+
+    return {
+      providerReference: { anthropic: response.id },
+      ...(response.display_title != null
+        ? { displayTitle: response.display_title }
+        : {}),
+      ...(name != null ? { name } : {}),
+      ...(description != null ? { description } : {}),
+      ...(response.latest_version != null
+        ? { latestVersion: response.latest_version }
+        : {}),
+      providerMetadata: {
+        anthropic: {
+          ...(response.source != null ? { source: response.source } : {}),
+          ...(response.created_at != null
+            ? { createdAt: response.created_at }
+            : {}),
+          ...(response.updated_at != null
+            ? { updatedAt: response.updated_at }
+            : {}),
+        },
+      },
+      warnings,
+    };
+  }
+}