構造化出力

「structured outputs」（構造化出力）は、Claudeの応答が特定のスキーマに従うように制約し、下流の処理のために有効で解析可能な出力を保証します。構造化出力は、相互に補完する2つの機能を提供します。

• 「JSON outputs」（JSON出力）（output_config.format）：Claudeの応答を特定のJSON形式で取得します。たとえば、画像やテキストからのデータ抽出、構造化レポートの生成、API応答のフォーマットなどに使用できます。このページではJSON出力について説明します。
• 「Strict tool use」（厳密なツール使用）（strict: true）：ツール名と入力に対するスキーマ検証を保証します。厳密なツール使用を参照してください。

これらの機能は個別に使用することも、同じリクエスト内で併用することもできます。

構造化出力を使用する理由

構造化出力がない場合、Claudeは不正な形式のJSON応答や無効なツール入力を生成し、アプリケーションを壊してしまう可能性があります。慎重にプロンプトを作成しても、次のような問題に遭遇することがあります。

• 無効なJSON構文による解析エラー
• 必須フィールドの欠落
• 一貫性のないデータ型
• エラー処理と再試行を必要とするスキーマ違反

構造化出力は、「constrained decoding」（制約付きデコーディング）によってスキーマに準拠した応答を保証します。

• 常に有効： JSON.parse()エラーはもう発生しません
• 型安全： フィールドの型と必須フィールドが保証されます
• 信頼性： スキーマ違反による再試行は不要です

仕組み

1. 1

   スキーマを定義する

   必要な構造をJSONスキーマとして、または使用する言語の型として記述します。スキーマはJSON Schemaに従いますが、いくつかの制限があります。

2. 2

   output_config.formatで送信する

   リクエストは、type: "json_schema"を指定したoutput_config.formatにスキーマを含めます。SDKヘルパーがこれを自動的に設定します。

3. 3

   応答を読み取る

   Claudeは、スキーマに一致する有効なJSONを応答のテキストコンテンツブロックで返します。SDKヘルパーはそれを指定した型にパースします。

使用方法

from pydantic import BaseModel
# ...


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


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True

SDKによる変換の仕組み

ほとんどのSDKヘルパーは、サポートされていない機能を使用するスキーマを変換します。変換の手順は次のとおりです。

1. サポートされていない制約を削除する（たとえば、minimum、maximum、minLength、maxLength）
2. 説明を更新する：サポートされていない各制約をフィールドの説明に追加します（たとえば、{minimum: 100}）
3. すべてのオブジェクトにadditionalProperties: falseを追加する
4. 文字列フォーマットをフィルタリングし、サポートされているもののみに絞り込む
5. ヘルパーが応答を検証する場合は、元のスキーマとそのすべての制約に対して応答を検証する

Claudeは簡略化されたスキーマを受け取りますが、応答を検証するヘルパーは、コード内のすべての制約を引き続き適用します。

例： minimum: 100を持つフィールドは、送信されるスキーマでは単純な整数になり、SDKはフィールドの説明に{minimum: 100}を追加します。応答を検証するヘルパーは、引き続きminimum: 100に対して応答をチェックします。

生のJSONスキーマの使用

ファイル、OpenAPI仕様、または実行時にスキーマを構築するコードから得たJSONスキーマを使用するには、それをoutput_config.formatで渡します。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)

{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}

一般的なユースケース

from pydantic import BaseModel


class Invoice(BaseModel):
    invoice_number: str
    date: str
    total_amount: float
    line_items: list[dict]
    customer_name: str


client = anthropic.Anthropic()
invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_format=Invoice,
    messages=[
        {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
    ],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Classification(BaseModel):
    category: str
    confidence: float
    tags: list[str]
    sentiment: str


feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=Classification,
    messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class APIResponse(BaseModel):
    status: str
    data: dict
    errors: list[dict] | None
    metadata: dict


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[{"role": "user", "content": "Process this request: ..."}],
)

print(response.parsed_output)

厳密なツール使用

文法制約付きサンプリングによってツール入力にJSON Schema準拠を強制するには、厳密なツール使用を参照してください。

両方の機能を併用する

JSON出力と厳密なツール使用は異なる問題を解決し、連携して動作します。

• JSON出力はClaudeの応答形式（Claudeが何を言うか）を制御します
• 厳密なツール使用はツールパラメータ（Claudeが関数をどのように呼び出すか）を検証します

組み合わせると、Claudeは有効性が保証されたパラメータでツールを呼び出し、かつ構造化されたJSON応答を返すことができます。これは、信頼性の高いツール呼び出しと構造化された最終出力の両方が必要なエージェントワークフローに役立ちます。

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # JSON出力：構造化されたレスポンス形式
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # 厳格なツール使用：ツールパラメータを保証
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)

重要な考慮事項

文法のコンパイルとキャッシング

構造化出力は、コンパイルされた文法アーティファクトによる制約付きサンプリングを使用します。これにより、注意すべきいくつかのパフォーマンス特性が生じます。

• 初回リクエストのレイテンシ： 特定のスキーマを初めて使用する際、文法のコンパイル中に追加の「latency」（レイテンシ）が発生します
• 自動キャッシング： コンパイルされた文法は最後の使用から24時間キャッシュされるため、後続のリクエストは大幅に高速になります
• キャッシュの無効化： 次のものを変更するとキャッシュが無効化されます。
  • JSONスキーマの構造
  • リクエスト内のツールのセット（構造化出力とツール使用の両方を使用している場合）
  • nameまたはdescriptionフィールドのみを変更してもキャッシュは無効化されません

プロンプトの変更とトークンコスト

構造化出力を使用する場合、Claudeは期待される出力形式を説明する追加のシステムプロンプトを自動的に受け取ります。これは次のことを意味します。

• 入力トークン数がわずかに増加します
• 挿入されたプロンプトは、他のシステムプロンプトと同様にトークンを消費します
• output_config.formatパラメータを変更すると、その会話スレッドのプロンプトキャッシングが無効化されます

JSON Schemaの制限

構造化出力は標準のJSON Schemaをサポートしますが、いくつかの制限があります。JSON出力と厳密なツール使用の両方がこれらの制限を共有します。

プロパティの順序

構造化出力を使用する場合、オブジェクト内のプロパティはスキーマで定義された順序を維持しますが、1つ重要な注意点があります。必須プロパティが最初に表示され、その後にオプションプロパティが続きます。

例えば、次のスキーマの場合：

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

出力ではプロパティが次の順序になります。

1. name（必須、スキーマ順）
2. email（必須、スキーマ順）
3. notes（オプション、スキーマ順）
4. age（オプション、スキーマ順）

つまり、出力は次のようになる可能性があります。

{
  "name": "John Smith",
  "email": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

出力内のプロパティの順序がアプリケーションにとって重要な場合は、すべてのプロパティを必須としてマークするか、解析ロジックでこの並べ替えを考慮してください。

無効な出力

構造化出力はほとんどの場合スキーマ準拠を保証しますが、出力がスキーマに一致しない可能性があるシナリオがあります。

拒否（stop_reason: "refusal"）

Claudeは構造化出力を使用している場合でも、安全性と有用性の特性を維持します。Claudeが安全上の理由でリクエストを拒否した場合：

• 応答はstop_reason: "refusal"になります
• 200ステータスコードが返されます
• 生成されたトークンに対して課金されます
• 拒否メッセージがスキーマ制約よりも優先されるため、出力がスキーマに一致しない可能性があります

モデルの思考やステップバイステップの推論を求めるプロパティは、reasoning_extractionによる拒否につながる可能性があります。代わりに短い説明を求めてください。推論を思考ブロック内に保つを参照してください。

トークン制限に到達（stop_reason: "max_tokens"）

max_tokens制限に達したために応答が途中で切れた場合：

• 応答はstop_reason: "max_tokens"になります
• 出力が不完全でスキーマに一致しない可能性があります
• 完全な構造化出力を得るには、より大きなmax_tokens値で再試行してください

enum値の大文字小文字

構造化出力は文字列のenumおよびconst値の大文字小文字を保証しません。Claudeは、スキーマと大文字小文字のみが異なる値を返すことがあり、通常はスペースに続く単語の最初の文字で発生します。例えば、次のスキーマの場合：

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

その正確な値がenumに含まれていなくても、出力に"Conversation Topic 3"（大文字の「T」）が含まれる可能性があります。応答はエラーも特別なstop_reasonもなく正常に完了します。これはJSON出力と厳密なツール使用の両方に当てはまります。enum値は大文字小文字を区別せずに比較し、大文字小文字のみが異なるenum値は避けてください。

スキーマの複雑さの制限

構造化出力は、JSONスキーマをClaudeの出力を制約する文法にコンパイルすることで機能します。より複雑なスキーマはより大きな文法を生成し、コンパイルに時間がかかります。過度なコンパイル時間を防ぐため、APIはいくつかの複雑さの制限を適用します。

明示的な制限

次の制限は、output_config.formatまたはstrict: trueを含むすべてのリクエストに適用されます。

追加の内部制限

前述の表の明示的な制限に加えて、コンパイルされた文法のサイズに関する追加の内部制限があります。これらの制限が存在するのは、スキーマの複雑さが単一の次元に還元できないためです。オプションパラメータ、ユニオン型、ネストされたオブジェクト、ツールの数などの機能は相互に作用し、コンパイルされた文法を不釣り合いに大きくする可能性があります。

これらの制限を超えると、「Schema is too complex for compilation.」というメッセージを含む400エラーが返されます。これらのエラーは、前述の表の個々の制限がすべて満たされていても、スキーマの合計の複雑さが効率的にコンパイルできる範囲を超えていることを意味します。最後の安全策として、APIは180秒のコンパイルタイムアウトも適用します。すべての明示的なチェックを通過しても非常に大きなコンパイル済み文法を生成するスキーマは、このタイムアウトに達する可能性があります。

スキーマの複雑さを軽減するためのヒント

複雑さの制限に達している場合は、次の戦略を順番に試してください。

1. 重要なツールのみを厳密としてマークする。 多くのツールがある場合は、スキーマ違反が実際に問題を引き起こすツールにのみ適用し、より単純なツールについてはClaudeの自然な準拠に頼ってください。

2. オプションパラメータを減らす。 可能な限りパラメータをrequiredにしてください。各オプションパラメータは文法の状態空間の一部をおおよそ2倍にします。パラメータに常に妥当なデフォルト値がある場合は、必須にしてClaudeにそのデフォルト値を明示的に提供させることを検討してください。

3. ネスト構造を簡素化する。 オプションフィールドを持つ深くネストされたオブジェクトは複雑さを増大させます。可能な限り構造をフラットにしてください。

4. 複数のリクエストに分割する。 多くの厳密なツールがある場合は、それらを別々のリクエストやサブエージェントに分割することを検討してください。

有効なスキーマで問題が解決しない場合は、スキーマ定義を添えてサポートにお問い合わせください。

ベータ版からの移行

output_formatパラメータはoutput_config.formatに移動し、ベータヘッダーは不要になりました。output_formatパラメータは非推奨であり、将来削除される予定です。それでも使用する場合は、structured-outputs-2025-11-13ベータヘッダーを追加してください。ヘッダーがない場合、APIは400エラーを返します。

Python SDK（v1.0以降）は、client.beta.messages.create()またはcount_tokens()でoutput_format={...}を受け付けず、TypeErrorを発生させます。代わりにoutput_configを使用してください。更新されたAPIの形式については、生のJSONスキーマの使用を参照してください。

データ保持

構造化出力を使用する場合、プロンプトと応答はZDRで処理されます。ただし、JSONスキーマ自体は最適化のために最後の使用から最大24時間一時的にキャッシュされます。プロンプトや応答のデータはAPI応答を超えて保持されません。

構造化出力はHIPAA適格ですが、PHIをJSONスキーマ定義に含めてはなりません。APIはJSONスキーマをメッセージコンテンツとは別にキャッシュされる文法にコンパイルし、これらのキャッシュされたスキーマはプロンプトや応答と同じPHI保護を受けません。スキーマのプロパティ名、enum値、const値、またはpattern正規表現にPHIを含めないでください。PHIは、HIPAAの保護措置の下で保護されるメッセージコンテンツ（プロンプトと応答）にのみ含めるべきです。

すべての機能にわたるZDRおよびHIPAAの適格性については、APIとデータ保持を参照してください。

機能の互換性

併用可能：

• バッチ処理： 50%割引で構造化出力を大規模に処理します
• トークンカウント： コンパイルなしでトークンをカウントします
• ストリーミング： 通常の応答と同様に構造化出力をストリーミングします
• 併用： JSON出力（output_config.format）と厳密なツール使用（strict: true）を同じリクエスト内で併用できます

互換性なし：

• 引用： 引用は引用ブロックをテキストと交互に配置する必要があり、これは厳密なJSONスキーマ制約と競合します。output_config.formatで引用が有効になっている場合は400エラーが返されます。
• メッセージのプリフィル： JSON出力と互換性がありません

次のステップ

Compatibility