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 the public API** — this is an internal implementation change. Users who pass `providerOptions` with tool choice types should note the types are now imported from `@anthropic-ai/sdk/resources/messages` instead of the beta namespace.

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

@@ -21,6 +21,7 @@ import type {
   DocumentBlockParam,
   ImageBlockParam,
   MessageParam,
+  RawMessageStreamEvent,
   TextBlockParam,
   URLImageSource,
   URLPDFSource,
@@ -121,7 +122,7 @@ export class AnthropicTextAdapter<
     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,10 +148,9 @@ 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 using Anthropic's native structured output API.
+   * Uses `output_config.format` with `json_schema` type to constrain
+   * the model's response to match the provided schema.
    */
   async structuredOutput(
     options: StructuredOutputOptions<AnthropicTextProviderOptions>,
@@ -159,63 +159,39 @@ export class AnthropicTextAdapter<
 
     const requestParams = this.mapCommonOptionsToAnthropic(chatOptions)
 
-    // Create a tool that will capture the structured output
-    // Anthropic's SDK requires input_schema with type: 'object' literal
-    const structuredOutputTool = {
-      name: 'structured_output',
-      description:
-        'Use this tool to provide your response in the required structured format.',
-      input_schema: {
-        type: 'object' as const,
-        properties: outputSchema.properties ?? {},
-        required: outputSchema.required ?? [],
+    const createParams = {
+      ...requestParams,
+      stream: false as const,
+      output_config: {
+        format: {
+          type: 'json_schema' as const,
+          schema: outputSchema,
+        },
       },
     }
 
     try {
-      // Make non-streaming request with tool_choice forced to our structured output tool
-      const response = await this.client.messages.create(
-        {
-          ...requestParams,
-          stream: false,
-          tools: [structuredOutputTool],
-          tool_choice: { type: 'tool', name: 'structured_output' },
-        },
-        {
-          signal: chatOptions.request?.signal,
-          headers: chatOptions.request?.headers,
-        },
-      )
-
-      // Extract the tool use content from the response
-      let parsed: unknown = null
-      let rawText = ''
+      const response = await this.client.messages.create(createParams, {
+        signal: chatOptions.request?.signal,
+        headers: chatOptions.request?.headers,
+      })
 
-      for (const block of response.content) {
-        if (block.type === 'tool_use' && block.name === 'structured_output') {
-          parsed = block.input
-          rawText = JSON.stringify(block.input)
-          break
-        }
-      }
+      const rawText = response.content
+        .map((b) => {
+          if (b.type === 'text') {
+            return b.text
+          }
+          return ''
+        })
+        .join('')
 
-      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 ? '...' : ''}`,
-          )
-        }
+      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 {
@@ -454,7 +430,7 @@ export class AnthropicTextAdapter<
   }
 
   private async *processAnthropicStream(
-    stream: AsyncIterable<Anthropic_SDK.Beta.BetaRawMessageStreamEvent>,
+    stream: AsyncIterable<RawMessageStreamEvent>,
     model: string,
     genId: () => string,
   ): AsyncIterable<StreamChunk> {

packages/typescript/ai-anthropic/src/text/text-provider-options.ts

@@ -1,13 +1,11 @@
-import type {
-  BetaContextManagementConfig,
-  BetaToolChoiceAny,
-  BetaToolChoiceAuto,
-  BetaToolChoiceTool,
-} from '@anthropic-ai/sdk/resources/beta/messages/messages'
-import type { AnthropicTool } from '../tools'
+import type { BetaContextManagementConfig } from '@anthropic-ai/sdk/resources/beta/messages/messages'
 import type {
   MessageParam,
   TextBlockParam,
+  ToolChoiceAny,
+  ToolChoiceAuto,
+  ToolChoiceTool,
+  ToolUnion,
 } from '@anthropic-ai/sdk/resources/messages'
 
 export interface AnthropicContainerOptions {
@@ -38,8 +36,8 @@ export interface AnthropicContainerOptions {
 export interface AnthropicContextManagementOptions {
   /**
    * Context management configuration.
-
-This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not.
+   *
+   * This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not.
    */
   context_management?: BetaContextManagementConfig | null
 }
@@ -62,26 +60,26 @@ export interface AnthropicServiceTierOptions {
 export interface AnthropicStopSequencesOptions {
   /**
    * Custom text sequences that will cause the model to stop generating.
-
-Anthropic models will normally stop when they have naturally completed their turn, which will result in a response stop_reason of "end_turn".
-
-If you want the model to stop generating when it encounters custom strings of text, you can use the stop_sequences parameter. If the model encounters one of the custom sequences, the response stop_reason value will be "stop_sequence" and the response stop_sequence value will contain the matched stop sequence.
+   *
+   * Anthropic models will normally stop when they have naturally completed their turn, which will result in a response stop_reason of "end_turn".
+   *
+   * If you want the model to stop generating when it encounters custom strings of text, you can use the stop_sequences parameter. If the model encounters one of the custom sequences, the response stop_reason value will be "stop_sequence" and the response stop_sequence value will contain the matched stop sequence.
    */
   stop_sequences?: Array<string>
 }
 
 export interface AnthropicThinkingOptions {
   /**
      * Configuration for enabling Claude's extended thinking.
-
-When enabled, responses include thinking content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your max_tokens limit.
+     *
+     * When enabled, responses include thinking content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your max_tokens limit.
      */
   thinking?:
     | {
         /**
 * Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality.
-
-Must be ≥1024 and less than max_tokens
+*
+* Must be ≥1024 and less than max_tokens
 */
         budget_tokens: number
 
@@ -93,17 +91,17 @@ Must be ≥1024 and less than max_tokens
 }
 
 export interface AnthropicToolChoiceOptions {
-  tool_choice?: BetaToolChoiceAny | BetaToolChoiceTool | BetaToolChoiceAuto
+  tool_choice?: ToolChoiceAny | ToolChoiceTool | ToolChoiceAuto
 }
 
 export interface AnthropicSamplingOptions {
   /**
    * Only sample from the top K options for each subsequent token.
-
-Used to remove "long tail" low probability responses.
-Recommended for advanced use cases only. You usually only need to use temperature.
-
-Required range: x >= 0
+   *
+   * Used to remove "long tail" low probability responses.
+   * Recommended for advanced use cases only. You usually only need to use temperature.
+   *
+   * Required range: x >= 0
    */
   top_k?: number
 }
@@ -132,8 +130,8 @@ export interface InternalTextProviderOptions extends ExternalTextProviderOptions
    */
   stream?: boolean
   /**
-    * stem prompt.
- 
+    * System prompt.
+
  A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role.
     */
   system?: string | Array<TextBlockParam>
@@ -145,12 +143,12 @@ export interface InternalTextProviderOptions extends ExternalTextProviderOptions
    */
   temperature?: number
 
-  tools?: Array<AnthropicTool>
+  tools?: Array<ToolUnion>
 
   /**
    * Use nucleus sampling.
-
-In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by top_p. You should either alter temperature or top_p, but not both.
+   *
+   * In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by top_p. You should either alter temperature or top_p, but not both.
    */
   top_p?: number
 }

packages/typescript/ai-anthropic/src/tools/bash-tool.ts

@@ -1,10 +1,7 @@
-import type {
-  BetaToolBash20241022,
-  BetaToolBash20250124,
-} from '@anthropic-ai/sdk/resources/beta'
+import type { ToolBash20250124 } from '@anthropic-ai/sdk/resources/messages'
 import type { Tool } from '@tanstack/ai'
 
-export type BashTool = BetaToolBash20241022 | BetaToolBash20250124
+export type BashTool = ToolBash20250124
 
 export function convertBashToolToAdapterFormat(tool: Tool): BashTool {
   const metadata = tool.metadata as BashTool

packages/typescript/ai-anthropic/src/tools/index.ts

@@ -1,3 +1,4 @@
+import type { ToolUnion } from '@anthropic-ai/sdk/resources/messages'
 import type { BashTool } from './bash-tool'
 import type { CodeExecutionTool } from './code-execution-tool'
 import type { ComputerUseTool } from './computer-use-tool'
@@ -7,7 +8,13 @@ import type { TextEditorTool } from './text-editor-tool'
 import type { WebFetchTool } from './web-fetch-tool'
 import type { WebSearchTool } from './web-search-tool'
 
+/**
+ * Union of all Anthropic tool types supported by this adapter.
+ * Includes GA tools (via ToolUnion) and beta-only tools that
+ * have no GA equivalent yet.
+ */
 export type AnthropicTool =
+  | ToolUnion
   | BashTool
   | CodeExecutionTool
   | ComputerUseTool

packages/typescript/ai-anthropic/src/tools/tool-converter.ts

@@ -6,11 +6,11 @@ import { convertMemoryToolToAdapterFormat } from './memory-tool'
 import { convertTextEditorToolToAdapterFormat } from './text-editor-tool'
 import { convertWebFetchToolToAdapterFormat } from './web-fetch-tool'
 import { convertWebSearchToolToAdapterFormat } from './web-search-tool'
-import type { AnthropicTool } from '.'
+import type { ToolUnion } from '@anthropic-ai/sdk/resources/messages'
 import type { Tool } from '@tanstack/ai'
 
 /**
- * Converts standard Tool format to Anthropic-specific tool format
+ * Converts standard Tool format to Anthropic-specific tool format.
  *
  * @param tools - Array of standard Tool objects
  * @returns Array of Anthropic-specific tool definitions
@@ -32,10 +32,14 @@ import type { Tool } from '@tanstack/ai'
  *
  * const anthropicTools = convertToolsToProviderFormat(tools);
  * ```
+ * 
+ * Returns Array<ToolUnion> for compatibility with the stable messages API.
+ * Beta-only tools (ComputerUse, CodeExecution, Memory, WebFetch) are
+ * structurally compatible at runtime but not part of the GA ToolUnion type.
  */
 export function convertToolsToProviderFormat<TTool extends Tool>(
   tools: Array<TTool>,
-): Array<AnthropicTool> {
+): Array<ToolUnion> {
   return tools.map((tool) => {
     const name = tool.name
 
@@ -57,5 +61,5 @@ export function convertToolsToProviderFormat<TTool extends Tool>(
       default:
         return convertCustomToolToAdapterFormat(tool)
     }
-  })
+  }) as Array<ToolUnion>
 }

packages/typescript/ai-anthropic/tests/anthropic-adapter.test.ts

@@ -77,7 +77,7 @@ describe('Anthropic adapter option mapping', () => {
       }
     })()
 
-    mocks.betaMessagesCreate.mockResolvedValueOnce(mockStream)
+    mocks.messagesCreate.mockResolvedValueOnce(mockStream)
 
     const providerOptions = {
       container: {
@@ -132,8 +132,8 @@ describe('Anthropic adapter option mapping', () => {
       chunks.push(chunk)
     }
 
-    expect(mocks.betaMessagesCreate).toHaveBeenCalledTimes(1)
-    const [payload] = mocks.betaMessagesCreate.mock.calls[0]
+    expect(mocks.messagesCreate).toHaveBeenCalledTimes(1)
+    const [payload] = mocks.messagesCreate.mock.calls[0]
 
     expect(payload).toMatchObject({
       model: 'claude-3-7-sonnet-20250219',