结构化输出

client.messages.parse()（推荐）

parse() 方法自动转换您的 Pydantic 模型，验证响应，并返回 parsed_output 属性。

from pydantic import BaseModel
import anthropic


class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str


client = anthropic.Anthropic()

response = client.messages.parse(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, john@example.com, interested in the Pro plan",
        }
    ],
    output_format=ContactInfo,
)

# Access the parsed output directly
contact = response.parsed_output
print(contact.name, contact.email)

transform_schema() 辅助工具

当您需要在发送前手动转换模式，或者想要修改 Pydantic 生成的模式时使用。与自动转换提供的模式的 client.messages.parse() 不同，此工具为您提供转换后的模式，以便您可以进一步自定义。

from anthropic import transform_schema
from pydantic import TypeAdapter

# First convert Pydantic model to JSON schema, then transform
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# Modify schema if needed
schema["properties"]["custom_field"] = {"type": "string"}

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
    output_config={
        "format": {"type": "json_schema", "schema": schema},
    },
)

client.messages.parse() 配合 zodOutputFormat()

parse() 方法接受 Zod 模式，验证响应，并返回带有与模式匹配的推断 TypeScript 类型的 parsed_output 属性。

import Anthropic from "@anthropic-ai/sdk";
import { z } from "zod";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";

const ContactInfo = z.object({
  name: z.string(),
  email: z.string(),
  planInterest: z.string()
});

const client = new Anthropic();

const response = await client.messages.parse({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: "Extract contact info: John Smith, john@example.com, interested in the Pro plan"
    }
  ],
  output_config: { format: zodOutputFormat(ContactInfo) }
});

// Guaranteed type-safe
console.log(response.parsed_output!.email);

client.messages.parse() 配合 jsonSchemaOutputFormat()

jsonSchemaOutputFormat() 辅助工具接受 JSON Schema 对象，并将其与 parse() 集成，无需 Zod。Zod 是您单独安装的可选对等依赖；jsonSchemaOutputFormat() 开箱即用，因为 SDK 直接捆绑了 json-schema-to-ts。

对于内联模式字面量（在源代码中使用 as const 声明），您还可以获得编译时类型推断：parsed_output 的类型与模式结构匹配。对于导入或生成的模式（来自 JSON 文件或 OpenAPI 代码生成），辅助工具仍然发送模式并解析响应，但推断类型为 unknown，因为 as const 只能应用于字面量表达式。

import Anthropic from "@anthropic-ai/sdk";
import { jsonSchemaOutputFormat } from "@anthropic-ai/sdk/helpers/json-schema";

const client = new Anthropic();

const response = await client.messages.parse({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: "Extract contact info: John Smith, john@example.com, interested in the Pro plan"
    }
  ],
  output_config: {
    format: jsonSchemaOutputFormat({
      type: "object",
      properties: {
        name: { type: "string" },
        email: { type: "string" },
        planInterest: { type: "string" }
      },
      required: ["name", "email", "planInterest"],
      additionalProperties: false
    } as const)
  }
});

// response.parsed_output is typed as { name: string; email: string; planInterest: string } | null
console.log(response.parsed_output!.email);

类型推断需要 as const。 使用带有 const 断言的字面量对象表达式，以便 TypeScript 可以缩小属性类型。没有 as const，推断类型会退化为 unknown。

模式转换。 默认情况下，辅助工具以与 zodOutputFormat() 相同的方式转换模式：删除不支持的约束，向对象添加 additionalProperties: false，并过滤字符串格式。传递 jsonSchemaOutputFormat(schema, { transform: false }) 可将您的模式原样发送到 API。请参阅 SDK 转换工作原理。

通过 OutputConfig 传递原始 JSON 模式

C# SDK 使用通过 JsonSerializer.SerializeToElement 以编程方式构建的原始 JSON 模式。使用 JsonSerializer.Deserialize 反序列化响应 JSON。

using System.Text.Json;
using Anthropic;
using Anthropic.Models.Messages;

var client = new AnthropicClient();

var response = await client.Messages.Create(new MessageCreateParams
{
    Model = Model.ClaudeOpus4_7,
    MaxTokens = 1024,
    Messages = [new() {
        Role = Role.User,
        Content = "Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan."
    }],
    OutputConfig = new OutputConfig
    {
        Format = new JsonOutputFormat
        {
            Schema = new Dictionary<string, JsonElement>
            {
                ["type"] = JsonSerializer.SerializeToElement("object"),
                ["properties"] = JsonSerializer.SerializeToElement(new
                {
                    name = new { type = "string" },
                    email = new { type = "string" },
                    plan_interest = new { type = "string" },
                }),
                ["required"] = JsonSerializer.SerializeToElement(
                    new[] { "name", "email", "plan_interest" }),
                ["additionalProperties"] = JsonSerializer.SerializeToElement(false),
            },
        },
    },
});

if (response.Content[0].TryPickText(out var textBlock))
{
    // JSON is guaranteed to match the schema
    var contact = JsonSerializer.Deserialize<Dictionary<string, object>>(textBlock.Text)!;
    Console.WriteLine({{CONTENT}}quot;{contact["name"]} ({contact["email"]})");
}

通过 OutputConfigParam 传递原始 JSON 模式

Go SDK 使用原始 JSON 模式。定义带有 json 标签的 Go 结构体，生成 JSON 模式（例如使用 invopop/jsonschema），并将响应文本反序列化为您的结构体。

package main

import (
	"context"
	"encoding/json"
	"fmt"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/invopop/jsonschema"
)

type ContactInfo struct {
	Name         string `json:"name" jsonschema:"description=Full name"`
	Email        string `json:"email" jsonschema:"description=Email address"`
	PlanInterest string `json:"plan_interest" jsonschema:"description=Plan type"`
}

func generateSchema(v any) map[string]any {
	r := jsonschema.Reflector{AllowAdditionalProperties: false, DoNotReference: true}
	s := r.Reflect(v)
	b, _ := json.Marshal(s)
	var m map[string]any
	json.Unmarshal(b, &m)
	return m
}

func main() {
	client := anthropic.NewClient()
	schema := generateSchema(&ContactInfo{})

	message, _ := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock(
				"Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan.",
			)),
		},
		OutputConfig: anthropic.OutputConfigParam{
			Format: anthropic.JSONOutputFormatParam{
				Schema: schema,
			},
		},
	})

	for _, block := range message.Content {
		switch variant := block.AsAny().(type) {
		case anthropic.TextBlock:
			var contact ContactInfo
			json.Unmarshal([]byte(variant.Text), &contact)
			fmt.Printf("%s (%s)\n", contact.Name, contact.Email)
		}
	}
}

此页面上的 Java 示例使用 JDK 25 紧凑源文件语法；有关早期 JDK 的替代方案，请参阅 Java SDK 要求。

outputConfig(Class<T>) 方法

将 Java 类传递给 outputConfig()，SDK 自动推导 JSON 模式，验证它，并返回 StructuredMessageCreateParams<T>。通过 response.content().stream().flatMap(block -> block.text().stream()).findFirst().orElseThrow().text() 访问解析结果。

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.StructuredMessage;
import com.anthropic.models.messages.StructuredMessageCreateParams;
import com.anthropic.models.messages.Model;

static class ContactInfo {
    public String name;
    public String email;
    public String planInterest;
}

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    StructuredMessageCreateParams<ContactInfo> createParams = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_7)
        .maxTokens(1024)
        .outputConfig(ContactInfo.class)
        .addUserMessage("Extract contact info: John Smith, john@example.com, interested in the Pro plan")
        .build();

    StructuredMessage<ContactInfo> response = client.messages().create(createParams);
    ContactInfo contact = response.content().stream()
        .flatMap(block -> block.text().stream())
        .findFirst().orElseThrow().text();
    IO.println(contact.name + " (" + contact.email + ")");
}

泛型类型擦除

Java 在类的元数据中保留字段的泛型类型信息，但泛型类型擦除适用于其他作用域。虽然可以从具有 List<Book> 类型的 BookList.books 字段派生 JSON 模式，但无法从相同类型的局部变量派生有效的 JSON 模式。

如果将 JSON 响应转换为 Java 类实例时发生错误，错误消息包含 JSON 响应以协助诊断。如果您的 JSON 响应可能包含敏感信息，请避免直接记录它，或确保在错误消息中编辑掉任何敏感细节。

本地模式验证

结构化输出支持 JSON Schema 语言的子集。SDK 自动从类生成模式以与此子集对齐。outputConfig(Class<T>) 方法对从指定类派生的模式执行验证检查。

要点：

• 本地验证无需向远程 AI 模型发送请求即可发生。
• 远程验证也由 AI 模式在收到 JSON 模式时执行。
• 版本兼容性： 如果 SDK 版本过时，本地验证可能失败而远程验证成功。
• 禁用本地验证： 如果遇到兼容性问题，请传递 JsonSchemaLocalValidation.NO：

import com.anthropic.core.JsonSchemaLocalValidation;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.StructuredMessageCreateParams;
import com.anthropic.models.messages.Model;

static class BookList {
    public List<String> books;
}

void main() {
    StructuredMessageCreateParams<BookList> createParams = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_7)
        .maxTokens(2048)
        .outputConfig(BookList.class, JsonSchemaLocalValidation.NO)
        .addUserMessage("List some famous late twentieth century novels.")
        .build();
}

流式传输

结构化输出也适用于流式传输。当响应以流事件到达时，您需要在反序列化 JSON 之前累积完整响应。

使用 MessageAccumulator 从流中收集 JSON 字符串。累积后，调用 MessageAccumulator.message(Class<T>) 将累积的 Message 转换为 StructuredMessage，这会自动将 JSON 反序列化为您的 Java 类。

JSON 模式属性

当 SDK 从您的 Java 类派生 JSON 模式时，默认情况下包含由 public 字段或 public getter 方法表示的所有属性，并排除非 public 字段和 getter 方法。

您可以使用注解控制可见性：

• @JsonIgnore 排除 public 字段或 getter 方法
• @JsonProperty 包含非 public 字段或 getter 方法

如果您定义了带有 public getter 方法的 private 字段，SDK 从 getter 派生属性名（例如，带有 public 方法 getMyValue() 的 private 字段 myValue 产生 "myValue" 属性）。要使用非常规 getter 名称，请用 @JsonProperty 注解该方法。

每个类必须至少为 JSON 模式定义一个属性。如果没有字段或 getter 方法可以产生模式属性，则会发生验证错误，例如：

• 类中没有字段或 getter 方法
• 所有 public 成员都用 @JsonIgnore 注解
• 所有非 public 成员缺少 @JsonProperty 注解
• 字段使用 Map 类型，这会产生空的 "properties" 字段

组合和继承

您的 Java 类可以使用组合和继承在定义 JSON 模式时共享结构。每种模式对输出结构的影响不同。

组合产生嵌套 JSON 输出。从组合 A 和 B 的类 Composed 派生模式：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.StructuredMessage;
import com.anthropic.models.messages.StructuredMessageCreateParams;

static class A {
    public String a;
}

static class B {
    public String b;
}

static class Composed {
    public A composedA;
    public B composedB;
}

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();
    StructuredMessageCreateParams<Composed> params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_7)
        .maxTokens(1024)
        .outputConfig(Composed.class)
        .addUserMessage("Populate field a with 'hello' and field b with 'world'.")
        .build();
    StructuredMessage<Composed> response = client.messages().create(params);
    Composed result = response.content().stream()
        .flatMap(block -> block.text().stream())
        .findFirst().orElseThrow().text();
    IO.println("composedA.a=" + result.composedA.a);
    IO.println("composedB.b=" + result.composedB.b);
}

JSON 输出具有此嵌套结构：

{
  "composedA": { "a": "hello" },
  "composedB": { "b": "world" }
}

继承产生扁平 JSON 输出。从扩展 Base 的类 Derived 派生模式：

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.StructuredMessage;
import com.anthropic.models.messages.StructuredMessageCreateParams;

static class Base {
    public String a;
}

static class Derived extends Base {
    public String b;
}

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();
    StructuredMessageCreateParams<Derived> params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_7)
        .maxTokens(1024)
        .outputConfig(Derived.class)
        .addUserMessage("Populate field a with 'hello' and field b with 'world'.")
        .build();
    StructuredMessage<Derived> response = client.messages().create(params);
    Derived result = response.content().stream()
        .flatMap(block -> block.text().stream())
        .findFirst().orElseThrow().text();
    IO.println("a=" + result.a);
    IO.println("b=" + result.b);
}

JSON 输出具有此扁平结构：

{
  "a": "hello",
  "b": "world"
}

注解（Jackson 和 Swagger）

您可以使用 Jackson Databind 注解来丰富从 Java 类派生的 JSON 模式：

import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;

static class Person {

  @JsonPropertyDescription("The first name and surname of the person")
  public String name;

  public int birthYear;

  @JsonPropertyDescription("The year the person died, or 'present' if the person is living.")
  public String deathYear;
}

@JsonClassDescription("The details of one published book")
static class Book {

  public String title;
  public Person author;

  @JsonPropertyDescription("The year in which the book was first published.")
  public int publicationYear;

  @JsonIgnore
  public String genre;
}

static class BookList {
  public List<Book> books;
}

void main() {}

注解摘要：

• @JsonClassDescription：为类添加描述
• @JsonPropertyDescription：为字段或 getter 方法添加描述
• @JsonIgnore：从模式中排除 public 字段或 getter
• @JsonProperty：在模式中包含非 public 字段或 getter

如果您使用 @JsonProperty(required = false)，SDK 会忽略 false 值。类派生的模式始终将所有属性标记为必需。

您还可以使用 Swagger Core (OpenAPI 3) @Schema 和 @ArraySchema 注解来设置特定类型的约束：

import io.swagger.v3.oas.annotations.media.ArraySchema;
import io.swagger.v3.oas.annotations.media.Schema;

static class Article {

  @ArraySchema(minItems = 1)
  public List<String> authors;

  public String title;

  @Schema(format = "date")
  public String publicationDate;

  public int pageCount;
}

void main() {}

本地验证会检查您是否使用了任何不支持的约束关键字，但约束值不会在本地验证。例如，不支持的 "format" 值可能通过本地验证但导致远程错误。

如果您同时使用 Jackson 和 Swagger 注解设置相同的模式字段，Jackson 注解优先。

不使用 Java 类定义模式

基于类的模式推导是最方便的路径，但要直接控制模式结构，您可以手动构建 JsonOutputFormat.Schema 并将其包装在 OutputConfig 中。

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.JsonOutputFormat;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.OutputConfig;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    JsonOutputFormat.Schema schema = JsonOutputFormat.Schema.builder()
        .putAdditionalProperty("type", JsonValue.from("object"))
        .putAdditionalProperty("properties", JsonValue.from(Map.of(
            "name", Map.of("type", "string"),
            "email", Map.of("type", "string"),
            "plan_interest", Map.of("type", "string"))))
        .putAdditionalProperty("required", JsonValue.from(
            List.of("name", "email", "plan_interest")))
        .putAdditionalProperty("additionalProperties", JsonValue.from(false))
        .build();

    OutputConfig outputConfig = OutputConfig.builder()
        .format(JsonOutputFormat.builder().schema(schema).build())
        .build();

    MessageCreateParams createParams = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_7)
        .maxTokens(1024)
        .outputConfig(outputConfig)
        .addUserMessage(
            "John Smith (john@example.com) is interested in our Enterprise plan.")
        .build();

    client.messages().create(createParams).content().stream()
        .flatMap(contentBlock -> contentBlock.text().stream())
        .forEach(textBlock -> IO.println(textBlock.text()));
}

有关构建带有数组和描述的嵌套模式的更广泛示例，请参阅 SDK 存储库中的 StructuredOutputsRawExample.java。

通过 StructuredOutputModel 接口使用类

定义一个实现 StructuredOutputModel 的 PHP 类（使用 StructuredOutputModelTrait），并将类名传递给 outputConfig: ['format' => MyClass::class]。SDK 从您的原生 PHP 8 属性类型派生 JSON 模式，并通过 $message->parsedOutput() 返回类型化实例。

parsedOutput() 在成功时返回您的模型实例，如果解析失败则返回 null（或错误数组）。使用 instanceof 在访问字段之前缩小类型。

<?php

use Anthropic\Client;
use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
use Anthropic\Lib\Contracts\StructuredOutputModel;

$client = new Client();

class ContactInfo implements StructuredOutputModel
{
    use StructuredOutputModelTrait;

    public string $name;
    public string $email;
    public string $plan_interest;
}

$message = $client->messages->create(
    maxTokens: 1024,
    messages: [
        ['role' => 'user', 'content' => 'Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan.'],
    ],
    model: 'claude-opus-4-7',
    outputConfig: ['format' => ContactInfo::class],
);

$contact = $message->parsedOutput();
if ($contact instanceof ContactInfo) {
    echo "{$contact->name} ({$contact->email})\n";
}

类型推断

SDK 将原生 PHP 8 属性类型映射到 JSON Schema：

对于 array 属性，仅当元素类型是嵌套的 StructuredOutputModel 时，SDK 才添加 items 模式，使用 #[Constrained(itemClass: MyModel::class)] 或 /** @var MyModel[] */ 文档块声明。标量数组（string[]、int[]）发出无约束的 {"type":"array"}。

所有非可空属性都成为必需字段。

使用 #[Constrained] 属性添加约束

使用 #[Constrained] 属性添加约束：

<?php

use Anthropic\Lib\Attributes\Constrained;
use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
use Anthropic\Lib\Contracts\StructuredOutputModel;

class Address implements StructuredOutputModel { use StructuredOutputModelTrait; public string $street; }

class Profile implements StructuredOutputModel
{
    use StructuredOutputModelTrait;

    #[Constrained(description: 'Age in years', minimum: 0, maximum: 150)]
    public int $age;

    #[Constrained(format: 'email')]
    public string $email;

    #[Constrained(itemClass: Address::class, minItems: 1)]
    public array $addresses;
}

API 强制约束（在模式中发送）：description、format、const、itemClass、minItems（仅 0 或 1）。

SDK 验证约束（从线上模式中剥离，附加到描述中，并针对响应验证）：minimum、maximum、multipleOf、minLength、maxLength。

原始 JSON 模式回退

对于 PHP 类型提示无法表达的模式，通过 OutputConfig::with() 传递原始关联数组。此路径跳过 parsedOutput() 辅助工具；使用 json_decode() 解码响应：

<?php

use Anthropic\Client;
use Anthropic\Messages\OutputConfig;
use Anthropic\Messages\JSONOutputFormat;

$client = new Client();

$message = $client->messages->create(
    maxTokens: 1024,
    messages: [
        ['role' => 'user', 'content' => 'Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan.'],
    ],
    model: 'claude-opus-4-7',
    outputConfig: OutputConfig::with(format: JSONOutputFormat::with(schema: [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string'],
            'email' => ['type' => 'string'],
            'plan_interest' => ['type' => 'string'],
        ],
        'required' => ['name', 'email', 'plan_interest'],
        'additionalProperties' => false,
    ])),
);

$contact = json_decode($message->content[0]->text, associative: true);
echo "{$contact['name']} ({$contact['email']})\n";

output_config: {format: Model} 配合 parsed_output

定义一个扩展 Anthropic::BaseModel 的模型类，并将其作为格式传递给 messages.create()。响应包含一个带有类型化 Ruby 对象的 parsed_output 属性。

require "anthropic"

class ContactInfo < Anthropic::BaseModel
  required :name, String
  required :email, String
  required :plan_interest, String
end

client = Anthropic::Client.new

message = client.messages.create(
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: "Extract contact info: John Smith, john@example.com, interested in the Pro plan"
    }
  ],
  output_config: {format: ContactInfo}
)

contact = message.parsed_output
puts "#{contact.name} (#{contact.email})"

高级模型功能

Ruby SDK 支持额外的模型定义功能以实现更丰富的模式：

• doc: 关键字： 为字段添加描述以获得更具信息性的模式输出
• Anthropic::ArrayOf[T]： 类型化数组。将数组级约束（min_items:、max_items:）作为 required/optional 上的关键字传递，而不是在 ArrayOf 本身上
• Anthropic::EnumOf[:a, :b]： 具有约束值的枚举字段
• Anthropic::UnionOf[T1, T2]： 映射到 anyOf 的联合类型

class FamousNumber < Anthropic::BaseModel
  required :value, Float
  optional :reason, String, doc: "why is this number mathematically significant?"
end

class Output < Anthropic::BaseModel
  required :numbers, Anthropic::ArrayOf[FamousNumber], min_items: 3, max_items: 5
end

message = client.messages.create(
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [{role: "user", content: "give me some famous numbers"}],
  output_config: {format: Output}
)

message.parsed_output
# => #<Output numbers=[#<FamousNumber value=3.14159... reason="Pi is...">...]>