feat: update @anthropic-ai/sdk to version 0.74.0 and use real structured output

Author: Leftwitch

.changeset/real-structured-output.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/ai-anthropic': minor
+---
+
+Use Anthropic's native structured output API instead of the tool-use workaround
+
+Upgrades `@anthropic-ai/sdk` from ^0.71.2 to ^0.74.0 and migrates structured output to use the GA `output_config.format` with `json_schema` type. Previously, structured output was emulated by forcing a tool call and extracting the input — this now uses Anthropic's first-class structured output support for more reliable schema-constrained responses.
+
+Also migrates streaming and tool types from `client.beta.messages` to the stable `client.messages` API, replacing beta type imports (`BetaToolChoiceAuto`, `BetaToolBash20241022`, `BetaRawMessageStreamEvent`, etc.) with their GA equivalents.
+
+**No breaking changes to runtime behavior.** However, this is a **type-level breaking change** for TypeScript consumers who import tool choice or streaming types directly: the beta type exports (`BetaToolChoiceAuto`, `BetaToolChoiceTool`, `BetaRawMessageStreamEvent`, etc.) have been replaced with their GA equivalents (`ToolChoiceAuto`, `ToolChoiceTool`, `RawMessageStreamEvent`, etc.) from `@anthropic-ai/sdk/resources/messages`. Consumers referencing these types will need to update both the import paths and the type names accordingly.

packages/typescript/ai-anthropic/package.json

@@ -40,7 +40,7 @@
     "test:types": "tsc"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.71.2"
+    "@anthropic-ai/sdk": "^0.74.0"
   },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",

packages/typescript/ai-anthropic/src/adapters/text.ts

@@ -6,6 +6,7 @@ import {
   generateId,
   getAnthropicApiKeyFromEnv,
 } from '../utils'
+import { ANTHROPIC_STRUCTURED_OUTPUT_MODELS } from '../model-meta'
 import type {
   ANTHROPIC_MODELS,
   AnthropicChatModelProviderOptionsByName,
@@ -21,6 +22,7 @@ import type {
   DocumentBlockParam,
   ImageBlockParam,
   MessageParam,
+  RawMessageStreamEvent,
   TextBlockParam,
   URLImageSource,
   URLPDFSource,
@@ -115,13 +117,16 @@ export class AnthropicTextAdapter<
     this.client = createAnthropicClient(config)
   }
 
+  /**
+   * Stream chat completions from Anthropic, yielding AG-UI lifecycle chunks.
+   */
   async *chatStream(
     options: TextOptions<AnthropicTextProviderOptions>,
   ): AsyncIterable<StreamChunk> {
     try {
       const requestParams = this.mapCommonOptionsToAnthropic(options)
 
-      const stream = await this.client.beta.messages.create(
+      const stream = await this.client.messages.create(
         { ...requestParams, stream: true },
         {
           signal: options.request?.signal,
@@ -147,20 +152,87 @@ export class AnthropicTextAdapter<
   }
 
   /**
-   * Generate structured output using Anthropic's tool-based approach.
-   * Anthropic doesn't have native structured output, so we use a tool with the schema
-   * and force the model to call it.
-   * The outputSchema is already JSON Schema (converted in the ai layer).
+   * Generate structured output.
+   * Uses Anthropic's native `output_config` with `json_schema` for Claude 4+ models.
+   * Falls back to a tool-use workaround for older models that lack native support.
    */
   async structuredOutput(
     options: StructuredOutputOptions<AnthropicTextProviderOptions>,
   ): Promise<StructuredOutputResult<unknown>> {
     const { chatOptions, outputSchema } = options
-
     const requestParams = this.mapCommonOptionsToAnthropic(chatOptions)
 
-    // Create a tool that will capture the structured output
-    // Anthropic's SDK requires input_schema with type: 'object' literal
+    if (ANTHROPIC_STRUCTURED_OUTPUT_MODELS.has(chatOptions.model)) {
+      return this.nativeStructuredOutput(requestParams, chatOptions, outputSchema)
+    }
+
+    return this.toolBasedStructuredOutput(requestParams, chatOptions, outputSchema)
+  }
+
+  /**
+   * Native structured output using `output_config.format` with `json_schema`.
+   * Supported by Claude 4+ models.
+   */
+  private async nativeStructuredOutput(
+    requestParams: InternalTextProviderOptions,
+    chatOptions: StructuredOutputOptions<AnthropicTextProviderOptions>['chatOptions'],
+    outputSchema: StructuredOutputOptions<AnthropicTextProviderOptions>['outputSchema'],
+  ): Promise<StructuredOutputResult<unknown>> {
+    const createParams = {
+      ...requestParams,
+      stream: false as const,
+      output_config: {
+        format: {
+          type: 'json_schema' as const,
+          name: 'structured_output',
+          schema: outputSchema,
+        },
+      },
+    }
+
+    let response: Awaited<ReturnType<typeof this.client.messages.create>>
+    try {
+      response = await this.client.messages.create(createParams, {
+        signal: chatOptions.request?.signal,
+        headers: chatOptions.request?.headers,
+      })
+    } catch (error: unknown) {
+      const err = error as Error
+      throw new Error(
+        `Structured output generation failed: ${err.message || 'Unknown error occurred'}`,
+      )
+    }
+
+    const rawText = response.content
+      .map((b) => {
+        if (b.type === 'text') {
+          return b.text
+        }
+        return ''
+      })
+      .join('')
+
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(rawText)
+    } catch {
+      throw new Error(
+        `Failed to parse structured output JSON. Content: ${rawText.slice(0, 200)}${rawText.length > 200 ? '...' : ''}`,
+      )
+    }
+
+    return { data: parsed, rawText }
+  }
+
+  /**
+   * Tool-based structured output fallback for older models (Claude 3.x).
+   * Creates a tool with the output schema and forces the model to call it.
+   */
+  private async toolBasedStructuredOutput(
+    requestParams: InternalTextProviderOptions,
+    chatOptions: StructuredOutputOptions<AnthropicTextProviderOptions>['chatOptions'],
+    outputSchema: StructuredOutputOptions<AnthropicTextProviderOptions>['outputSchema'],
+  ): Promise<StructuredOutputResult<unknown>> {
     const structuredOutputTool = {
       name: 'structured_output',
       description:
@@ -172,9 +244,9 @@ export class AnthropicTextAdapter<
       },
     }
 
+    let response: Awaited<ReturnType<typeof this.client.messages.create>>
     try {
-      // Make non-streaming request with tool_choice forced to our structured output tool
-      const response = await this.client.messages.create(
+      response = await this.client.messages.create(
         {
           ...requestParams,
           stream: false,
@@ -186,50 +258,48 @@ export class AnthropicTextAdapter<
           headers: chatOptions.request?.headers,
         },
       )
-
-      // Extract the tool use content from the response
-      let parsed: unknown = null
-      let rawText = ''
-
-      for (const block of response.content) {
-        if (block.type === 'tool_use' && block.name === 'structured_output') {
-          parsed = block.input
-          rawText = JSON.stringify(block.input)
-          break
-        }
-      }
-
-      if (parsed === null) {
-        // Fallback: try to extract text content and parse as JSON
-        rawText = response.content
-          .map((b) => {
-            if (b.type === 'text') {
-              return b.text
-            }
-            return ''
-          })
-          .join('')
-        try {
-          parsed = JSON.parse(rawText)
-        } catch {
-          throw new Error(
-            `Failed to extract structured output from response. Content: ${rawText.slice(0, 200)}${rawText.length > 200 ? '...' : ''}`,
-          )
-        }
-      }
-
-      return {
-        data: parsed,
-        rawText,
-      }
     } catch (error: unknown) {
       const err = error as Error
       throw new Error(
         `Structured output generation failed: ${err.message || 'Unknown error occurred'}`,
       )
     }
+
+    let parsed: unknown = null
+    let rawText = ''
+
+    for (const block of response.content) {
+      if (block.type === 'tool_use' && block.name === 'structured_output') {
+        parsed = block.input
+        rawText = JSON.stringify(block.input)
+        break
+      }
+    }
+
+    if (parsed === null) {
+      rawText = response.content
+        .map((b) => {
+          if (b.type === 'text') {
+            return b.text
+          }
+          return ''
+        })
+        .join('')
+      try {
+        parsed = JSON.parse(rawText)
+      } catch {
+        throw new Error(
+          `Failed to extract structured output from response. Content: ${rawText.slice(0, 200)}${rawText.length > 200 ? '...' : ''}`,
+        )
+      }
+    }
+
+    return { data: parsed, rawText }
   }
 
+  /**
+   * Map framework-agnostic text options to the Anthropic request format.
+   */
   private mapCommonOptionsToAnthropic(
     options: TextOptions<AnthropicTextProviderOptions>,
   ) {
@@ -293,6 +363,9 @@ export class AnthropicTextAdapter<
     return requestParams
   }
 
+  /**
+   * Convert a framework-agnostic content part to an Anthropic content block.
+   */
   private convertContentPartToAnthropic(
     part: ContentPart,
   ): TextBlockParam | ImageBlockParam | DocumentBlockParam {
@@ -362,6 +435,9 @@ export class AnthropicTextAdapter<
     }
   }
 
+  /**
+   * Convert framework-agnostic messages to Anthropic's message format.
+   */
   private formatMessages(
     messages: Array<ModelMessage>,
   ): InternalTextProviderOptions['messages'] {
@@ -453,8 +529,11 @@ export class AnthropicTextAdapter<
     return formattedMessages
   }
 
+  /**
+   * Process a raw Anthropic SSE stream into AG-UI lifecycle chunks.
+   */
   private async *processAnthropicStream(
-    stream: AsyncIterable<Anthropic_SDK.Beta.BetaRawMessageStreamEvent>,
+    stream: AsyncIterable<RawMessageStreamEvent>,
     model: string,
     genId: () => string,
   ): AsyncIterable<StreamChunk> {

packages/typescript/ai-anthropic/src/model-meta.ts

@@ -20,6 +20,7 @@ interface ModelMeta<
     input: Array<'text' | 'image' | 'audio' | 'video' | 'document'>
     extended_thinking?: boolean
     priority_tier?: boolean
+    structured_output?: boolean
   }
   context_window?: number
   max_output_tokens?: number
@@ -65,6 +66,7 @@ const CLAUDE_OPUS_4_6 = {
     input: ['text', 'image', 'document'],
     extended_thinking: true,
     priority_tier: true,
+    structured_output: true,
   },
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
@@ -95,6 +97,7 @@ const CLAUDE_OPUS_4_5 = {
     input: ['text', 'image', 'document'],
     extended_thinking: true,
     priority_tier: true,
+    structured_output: true,
   },
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
@@ -125,6 +128,7 @@ const CLAUDE_SONNET_4_5 = {
     input: ['text', 'image', 'document'],
     extended_thinking: true,
     priority_tier: true,
+    structured_output: true,
   },
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
@@ -155,6 +159,7 @@ const CLAUDE_HAIKU_4_5 = {
     input: ['text', 'image', 'document'],
     extended_thinking: true,
     priority_tier: true,
+    structured_output: true,
   },
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
@@ -185,6 +190,7 @@ const CLAUDE_OPUS_4_1 = {
     input: ['text', 'image', 'document'],
     extended_thinking: true,
     priority_tier: true,
+    structured_output: true,
   },
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
@@ -215,6 +221,7 @@ const CLAUDE_SONNET_4 = {
     input: ['text', 'image', 'document'],
     extended_thinking: true,
     priority_tier: true,
+    structured_output: true,
   },
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
@@ -244,6 +251,7 @@ const CLAUDE_SONNET_3_7 = {
     input: ['text', 'image', 'document'],
     extended_thinking: true,
     priority_tier: true,
+    structured_output: false,
   },
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
@@ -274,6 +282,7 @@ const CLAUDE_OPUS_4 = {
     input: ['text', 'image', 'document'],
     extended_thinking: true,
     priority_tier: true,
+    structured_output: true,
   },
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
@@ -304,6 +313,7 @@ const CLAUDE_HAIKU_3_5 = {
     input: ['text', 'image', 'document'],
     extended_thinking: false,
     priority_tier: true,
+    structured_output: false,
   },
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
@@ -334,6 +344,7 @@ const CLAUDE_HAIKU_3 = {
     input: ['text', 'image', 'document'],
     extended_thinking: false,
     priority_tier: false,
+    structured_output: false,
   },
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
@@ -404,6 +415,20 @@ export const ANTHROPIC_MODELS = [
   CLAUDE_HAIKU_3.id,
 ] as const
 
+/**
+ * Models that support Anthropic's native structured output API (output_config with json_schema).
+ * Only Claude 4+ models support this feature.
+ */
+export const ANTHROPIC_STRUCTURED_OUTPUT_MODELS: ReadonlySet<string> = new Set([
+  CLAUDE_OPUS_4_6.id,
+  CLAUDE_OPUS_4_5.id,
+  CLAUDE_SONNET_4_5.id,
+  CLAUDE_HAIKU_4_5.id,
+  CLAUDE_OPUS_4_1.id,
+  CLAUDE_SONNET_4.id,
+  CLAUDE_OPUS_4.id,
+])
+
 // const ANTHROPIC_IMAGE_MODELS = [] as const
 // const ANTHROPIC_EMBEDDING_MODELS = [] as const
 // const ANTHROPIC_AUDIO_MODELS = [] as const