構造化された出力

構造化された出力は、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-7",
    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: client.messages.parse() を使用した Pydantic モデル
• TypeScript: zodOutputFormat() を使用した Zod スキーマ、または jsonSchemaOutputFormat() を使用した型付き JSON Schema リテラル
• Java: outputConfig(Class<T>) を使用した自動スキーマ導出を備えたプレーン Java クラス
• Ruby: output_config: {format: Model} を使用した Anthropic::BaseModel クラス
• PHP: outputConfig: ['format' => MyClass::class] を使用した StructuredOutputModel を実装するクラス
• CLI, C#, Go: 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-7",
    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 は、サポートされていない機能を持つスキーマを自動的に変換します：

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-7",
    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)

重要な考慮事項

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

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

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

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

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

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

JSONスキーマの制限

構造化出力は、いくつかの制限を伴う標準JSONスキーマをサポートしています。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を持つすべてのリクエストに適用されます：

追加の内部制限

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

これらの制限を超えた場合、「スキーマはコンパイルするには複雑すぎます」というメッセージの400エラーが表示されます。これらのエラーは、スキーマの組み合わせた複雑さが効率的にコンパイルできる範囲を超えていることを意味し、上記の個々の制限が満たされている場合でも同様です。最終的なストップギャップとして、APIは180秒のコンパイルタイムアウトも適用します。すべての明示的なチェックに合格しても、非常に大きなコンパイルされた文法を生成するスキーマはこのタイムアウトに達する可能性があります。

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

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

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

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

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

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

有効なスキーマの永続的な問題については、スキーマ定義を含めてサポートに連絡してください。

データ保持

構造化出力を使用する場合、プロンプトと応答は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出力と互換性がありません