構造化出力

構造化出力は、Claudeの応答を特定のスキーマに従うように制限し、ダウンストリーム処理のための有効で解析可能な出力を確保します。構造化データレスポンスにはJSON出力（output_format）を使用するか、ツール名と入力の保証されたスキーマ検証には厳密なツール使用（strict: true）を使用します。

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

構造化出力がなければ、Claudeは不正な形式のJSON応答または無効なツール入力を生成し、アプリケーションを破壊する可能性があります。注意深いプロンプティングでも、以下の問題が発生する可能性があります：

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

構造化出力は、制約付きデコーディングを通じてスキーマ準拠の応答を保証します：

• 常に有効：JSON.parse()エラーはもうありません
• 型安全：保証されたフィールド型と必須フィールド
• 信頼性：スキーマ違反のための再試行は不要
• 2つのモード：データ抽出などのタスク用JSON、複雑なツールとエージェントワークフロー用の厳密なツール

クイックスタート

JSON出力と厳密なツール使用の使い分け

ユースケースに適したモードを選択してください：

エージェント向けの厳密なツール使用が重要な理由

信頼性の高いエージェントシステムの構築には、保証されたスキーマ準拠が必要です。無効なツールパラメータは関数とワークフローを破壊します。Claudeは互換性のない型（"2"の代わりに2）または欠落フィールドを返す可能性があり、ランタイムエラーが発生します。

厳密なツール使用は型安全なパラメータを保証します：

• 関数は毎回正しく型付けされた引数を受け取る
• ツール呼び出しを検証して再試行する必要がない
• スケールで一貫して機能する本番対応エージェント

例えば、予約システムがpassengers: intを必要とするとします。厳密モードなしでは、Claudeはpassengers: "two"またはpassengers: "2"を提供する可能性があります。strict: trueを使用すると、passengers: 2が保証されます。

構造化出力の仕組み

SDKでJSON出力を操作する

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

PydanticとZodの使用

PythonおよびTypeScript開発者は、生のJSONスキーマを記述する代わりに、PydanticやZodなどの使い慣れたスキーマ定義ツールを使用できます。

from pydantic import BaseModel
from anthropic import Anthropic, transform_schema

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

client = Anthropic()

# With .create() - requires transform_schema()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    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={
        "type": "json_schema",
        "schema": transform_schema(ContactInfo),
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    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固有のメソッド

Python: client.beta.messages.parse()（推奨）

parse()メソッドは自動的にPydanticモデルを変換し、応答を検証し、parsed_output属性を返します。

Python: transform_schema()ヘルパー

スキーマを送信する前に手動で変換する必要がある場合、またはPydantic生成スキーマを変更したい場合に使用します。client.beta.messages.parse()は提供されたスキーマを自動的に変換するのとは異なり、これは変換されたスキーマを提供するため、さらにカスタマイズできます。

SDKの変換の仕組み

PythonおよびTypeScript SDKは、サポートされていない機能を持つスキーマを自動的に変換します：

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

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

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

一般的なユースケース

重要な考慮事項

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

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

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

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

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

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

JSONスキーマの制限

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

無効な出力

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

拒否（stop_reason: "refusal"）

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

• 応答はstop_reason: "refusal"を持ちます
• 200ステータスコードを受け取ります
• 生成されたトークンに対して課金されます
• 出力はスキーマと一致しない可能性があります（拒否が優先されます）

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

max_tokens制限に達したため応答が切断された場合：

• 応答はstop_reason: "max_tokens"を持ちます
• 出力は不完全でスキーマと一致しない可能性があります
• より高いmax_tokens値で再試行して、完全な構造化出力を取得します

スキーマ検証エラー

スキーマがサポートされていない機能を使用しているか、複雑すぎる場合、400エラーが表示されます：

「スキーマ内の再帰定義が多すぎます」

• 原因：スキーマに過度な、または循環的な再帰定義がある
• 解決策：スキーマ構造を簡素化し、ネストの深さを減らす

「スキーマが複雑すぎます」

• 原因：スキーマが複雑さの制限を超えている
• 解決策：より小さなスキーマに分割し、構造を簡素化するか、strict: trueとしてマークされたツールの数を減らす

有効なスキーマで問題が続く場合は、スキーマ定義を含めてサポートに連絡してください。

機能の互換性

以下と連携：

• バッチ処理：50%割引で大規模に構造化出力を処理
• トークンカウント：コンパイルなしでトークンをカウント
• ストリーミング：通常の応答のように構造化出力をストリーム
• 組み合わせ使用：同じリクエストでJSON出力（output_format）と厳密なツール使用（strict: true）を一緒に使用

以下と互換性がない：

• 引用：引用はテキストと引用ブロックをインターリーブする必要があり、これは厳密なJSONスキーマ制約と競合します。output_formatで引用が有効な場合、400エラーを返します。
• メッセージプリフィリング：JSON出力と互換性がない