feat(api): add support for structured outputs beta

https://docs.claude.com/en/docs/build-with-claude/structured-outputs

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 34
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/anthropic%2Fanthropic-5e665f72d2774cd751988ccc94f623f264d9358aa073289779de5815d36e89a3.yml
-openapi_spec_hash: c5f969a677c73796d192cf09dbb047f9
-config_hash: bbb07992b537724667f4589012714eb7
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/anthropic%2Fanthropic-2f35b2ff9174d526a6d35796d2703490bfa5692312af67cbdfa4500283dabe31.yml
+openapi_spec_hash: dc52b25c487e97d355ef645644aa13e7
+config_hash: 239752fc0713a82e121ea45f7e2ebbf6

api.md

@@ -246,8 +246,10 @@ Types:
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaFileImageSource</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaImageBlockParam</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaInputJSONDelta</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaJSONOutputFormat</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaInputTokensClearAtLeast</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaInputTokensTrigger</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaJSONOutputFormat</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaMCPToolResultBlock</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaMCPToolUseBlock</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaMCPToolUseBlockParam</a></code>

examples/parsing-json-schema.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env -S npm run tsn -T
+
+import Anthropic from '@anthropic-ai/sdk';
+import { betaJSONSchemaOutputFormat } from '@anthropic-ai/sdk/helpers/beta/json-schema';
+
+const NumbersResponse = {
+  type: 'object',
+  properties: {
+    primes: {
+      type: 'array',
+      items: {
+        type: 'number',
+      },
+    },
+  },
+  required: ['primes'],
+} as const;
+
+async function main() {
+  const client = new Anthropic();
+
+  const message = await client.beta.messages.parse({
+    model: 'claude-sonnet-4-5-20250929-structured-outputs',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: 'What are the first 3 prime numbers?' }],
+    output_format: betaJSONSchemaOutputFormat(NumbersResponse),
+  });
+
+  console.log('=== Full Message ===');
+  console.log(JSON.stringify(message, null, 2));
+  console.log('=== Parsed Output ===');
+  console.log('\nPrime numbers:', message.parsed_output?.primes);
+}
+
+main().catch(console.error);

examples/parsing-raw.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env -S npm run tsn -T
+
+import Anthropic from '@anthropic-ai/sdk';
+
+async function main() {
+  const client = new Anthropic();
+
+  const message = await client.beta.messages.parse({
+    model: 'claude-sonnet-4-5-20250929-structured-outputs',
+    max_tokens: 100,
+    output_format: {
+      type: 'json_schema',
+      schema: {
+        type: 'object',
+        properties: {
+          answer: { type: 'string', description: 'The final answer' },
+        },
+        required: ['answer'],
+        additionalProperties: false,
+      },
+    },
+    messages: [
+      {
+        role: 'user',
+        content: 'What is bigger: 738 * 5678 or 98123 - 2711?',
+      },
+    ],
+  });
+  console.log(JSON.stringify(message.parsed_output, null, 2));
+}
+
+main().catch(console.error);

examples/parsing-streaming.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env -S npm run tsn -T
+
+import { betaZodOutputFormat } from '@anthropic-ai/sdk/helpers/beta/zod';
+import Anthropic from '@anthropic-ai/sdk';
+import { z } from 'zod';
+
+const WeatherResponse = z.object({
+  city: z.string(),
+  temperature: z.number(),
+  conditions: z.array(z.string()),
+  forecast: z.array(
+    z.object({
+      day: z.string(),
+      high: z.number(),
+      low: z.number(),
+      condition: z.string(),
+    }),
+  ),
+});
+
+async function main() {
+  const client = new Anthropic();
+
+  const stream = client.beta.messages.stream({
+    model: 'claude-sonnet-4-5-20250929-structured-outputs',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: 'Provide a weather report for San Francisco.' }],
+    output_format: betaZodOutputFormat(WeatherResponse),
+  });
+
+  for await (const event of stream) {
+    if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
+      process.stdout.write(event.delta.text);
+    }
+  }
+
+  // Get the final parsed result
+  const finalMessage = await stream.finalMessage();
+
+  console.log('\n\n=== Final Parsed Results ===');
+  console.log('City:', finalMessage.parsed_output?.city);
+  console.log('Temperature:', finalMessage.parsed_output?.temperature);
+  console.log('Conditions:', finalMessage.parsed_output?.conditions);
+  console.log('Forecast:', finalMessage.parsed_output?.forecast);
+}
+
+main().catch(console.error);

examples/parsing-zod.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env -S npm run tsn -T
+
+import { betaZodOutputFormat } from '@anthropic-ai/sdk/helpers/beta/zod';
+import Anthropic from '@anthropic-ai/sdk';
+import { z } from 'zod';
+
+const NumbersResponse = z.object({
+  primes: z.array(z.number()),
+});
+
+async function main() {
+  const client = new Anthropic();
+
+  const message = await client.beta.messages.parse({
+    model: 'claude-sonnet-4-5-20250929-structured-outputs',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: 'What are the first 3 prime numbers?' }],
+    output_format: betaZodOutputFormat(NumbersResponse),
+  });
+
+  console.log('=== Full Message ===');
+  console.log(JSON.stringify(message, null, 2));
+  console.log('=== Parsed Output ===');
+  console.log('\nPrime numbers:', message.parsed_output!.primes);
+}
+
+main().catch(console.error);

jest.config.ts

@@ -18,6 +18,7 @@ const config: JestConfigWithTsJest = {
     '<rootDir>/packages/',
   ],
   testPathIgnorePatterns: ['scripts'],
+  prettierPath: null,
 };
 
 export default config;

package.json

@@ -45,6 +45,7 @@
     "@types/node": "^20.17.6",
     "@typescript-eslint/eslint-plugin": "8.31.1",
     "@typescript-eslint/parser": "8.31.1",
+    "deep-object-diff": "^1.1.9",
     "eslint": "^9.20.1",
     "eslint-plugin-prettier": "^5.4.1",
     "eslint-plugin-unused-imports": "^4.1.4",

packages/bedrock-sdk/yarn.lock

@@ -16,7 +16,7 @@
     "@jridgewell/trace-mapping" "^0.3.9"
 
 "@anthropic-ai/sdk@file:../../dist":
-  version "0.60.0"
+  version "0.63.0"
   dependencies:
     json-schema-to-ts "^3.1.1"
 

src/helpers/beta/json-schema.ts

@@ -1,6 +1,9 @@
 import { FromSchema, JSONSchema } from 'json-schema-to-ts';
 import { Promisable, BetaRunnableTool } from '../../lib/tools/BetaRunnableTool';
 import { BetaToolResultContentBlockParam } from '../../resources/beta';
+import { AutoParseableBetaOutputFormat } from '../../lib/beta-parser';
+import { AnthropicError } from '../..';
+import { transformJSONSchema } from '../../lib/transform-json-schema';
 
 type NoInfer<T> = T extends infer R ? R : never;
 
@@ -30,3 +33,43 @@ export function betaTool<const Schema extends Exclude<JSONSchema, boolean> & { t
     parse: (content: unknown) => content as FromSchema<Schema>,
   } as any;
 }
+
+/**
+ * Creates a JSON schema output format object from the given JSON schema.
+ * If this is passed to the `.parse()` method then the response message will contain a
+ * `.parsed` property that is the result of parsing the content with the given JSON schema.
+ *
+ */
+export function betaJSONSchemaOutputFormat<
+  const Schema extends Exclude<JSONSchema, boolean> & { type: 'object' },
+>(
+  jsonSchema: Schema,
+  options?: {
+    transform?: boolean;
+  },
+): AutoParseableBetaOutputFormat<NoInfer<FromSchema<Schema>>> {
+  if (jsonSchema.type !== 'object') {
+    throw new Error(`JSON schema for tool must be an object, but got ${jsonSchema.type}`);
+  }
+
+  const transform = options?.transform ?? true;
+  if (transform) {
+    // todo: doing this is arguably necessary, but it does change the schema the user passed in
+    // so I'm not sure how we should handle that
+    jsonSchema = transformJSONSchema(jsonSchema) as Schema;
+  }
+
+  return {
+    type: 'json_schema',
+    schema: {
+      ...jsonSchema,
+    },
+    parse: (content) => {
+      try {
+        return JSON.parse(content);
+      } catch (error) {
+        throw new AnthropicError(`Failed to parse structured output: ${error}`);
+      }
+    },
+  };
+}