構造化出力

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

• JSON出力（output_config.format）：Claudeの応答を特定のJSON形式で取得します
• 厳密なツール使用（strict: true）：ツール名と入力に対するスキーマ検証を保証します

これらの機能は、独立して使用することも、同じリクエスト内で組み合わせて使用することもできます。



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

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

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

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

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



JSON出力

JSON出力はClaudeの応答形式を制御し、Claudeがスキーマに一致する有効なJSONを返すことを保証します。次のような場合にJSON出力を使用します。

• Claudeの応答形式を制御する
• 画像やテキストからデータを抽出する
• 構造化されたレポートを生成する
• API応答をフォーマットする



クイックスタート

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) 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,
            },
        }
    },
)
print(response.content[0].text)

応答形式： response.content[0].textにスキーマに一致する有効なJSONが含まれます

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}



仕組み



SDKでのJSON出力の操作

SDKは、スキーマ変換、自動検証、一般的なスキーマライブラリとの統合など、JSON出力の操作を容易にするヘルパーを提供します。



ネイティブスキーマ定義の使用

生のJSONスキーマを記述する代わりに、各言語で馴染みのあるスキーマ定義ツールを使用できます。

• Python： Pydanticモデルとclient.messages.parse()
• TypeScript： ZodスキーマとzodOutputFormat()、または型付きJSON SchemaリテラルとjsonSchemaOutputFormat()
• Java： outputConfig(Class<T>)による自動スキーマ導出を使用したプレーンなJavaクラス
• Ruby： Anthropic::BaseModelクラスとoutput_config: {format: Model}
• PHP： StructuredOutputModelを実装したクラスとoutputConfig: ['format' => MyClass::class]
• C#： ジェネリックなCreate<T>()オーバーロードを使用したプレーンなC#クラス（スキーマを自動的に導出）
• Go： ベータAPIで自動的にJSONスキーマにリフレクトされるGo構造体、またはoutput_configを通じた生のJSONスキーマ
• CLI： output_configを通じて渡される生のJSONスキーマ

from pydantic import BaseModel
from anthropic import Anthropic


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


client = Anthropic()

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

print(response.parsed_output)



SDK固有のメソッド

各SDKは、構造化出力の操作を容易にするヘルパーを提供します。詳細については、各SDKのページを参照してください。



SDK変換の仕組み

Python、TypeScript、Ruby、PHPのSDKは、サポートされていない機能を持つスキーマを自動的に変換します。C#とGoのSDKは、スキーマがネイティブ型から導出される場合（C#ではCreate<T>()、Goベータ APIでは構造体リフレクションまたはBetaJSONSchemaOutputFormat()）に同じ変換を適用します。変換ステップは次のとおりです。

1. サポートされていない制約を削除（例：minimum、maximum、minLength、maxLength）
2. 制約が構造化出力で直接サポートされていない場合、制約情報で説明を更新（例：「100以上である必要があります」）
3. すべてのオブジェクトに**additionalProperties: falseを追加**
4. 文字列フォーマットをフィルタリングしてサポートされているリストのみにする
5. 元のスキーマ（すべての制約を含む）に対して応答を検証

これは、Claudeが簡略化されたスキーマを受け取る一方で、コードは検証を通じてすべての制約を引き続き強制することを意味します。

例： minimum: 100を持つPydanticフィールドは、送信されるスキーマではプレーンな整数になりますが、SDKは説明を「100以上である必要があります」に更新し、元の制約に対して応答を検証します。



一般的なユースケース



厳密なツール使用

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



両方の機能を組み合わせて使用する

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

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

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

response = client.messages.create(
    model="claude-opus-4-8",
    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": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

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



無効な出力

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

拒否（stop_reason: "refusal"）

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

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

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

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

• 応答にはstop_reason: "max_tokens"が含まれます
• 出力が不完全でスキーマと一致しない可能性があります
• 完全な構造化出力を取得するには、より高いmax_tokens値でリトライしてください



スキーマの複雑さの制限

構造化出力は、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. 複数のリクエストに分割する。 多くの厳密なツールがある場合は、それらを別々のリクエストまたはサブエージェントに分割することを検討してください。

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



データ保持

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

構造化出力はHIPAA適格ですが、JSONスキーマ定義にPHIを含めてはいけません。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出力と互換性がありません