構造化出力

構造化出力は、Claudeの応答を特定のスキーマに従うよう制約し、ダウンストリーム処理のための有効でパース可能な出力を保証します。2つの補完的な機能が利用可能です：

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

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

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

構造化出力がない場合、Claudeはアプリケーションを壊す不正なJSON応答や無効なツール入力を生成する可能性があります。慎重なプロンプト設計を行っても、以下のような問題が発生する可能性があります：

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

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

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

JSON出力

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

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

クイックスタート

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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
        }
      }
    }
  }'

レスポンス形式： 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スキーマ
• Java: outputFormat(Class<T>)による自動スキーマ導出を使用したプレーンJavaクラス
• Ruby: output_config: {format: Model}を使用したAnthropic::BaseModelクラス
• C#、Go、PHP: 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-6",
    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のSDKは、サポートされていない機能を持つスキーマを自動的に変換します：

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

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

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

一般的なユースケース

厳格なツール使用

厳格なツール使用はツールパラメータを検証し、Claudeが正しく型付けされた引数で関数を呼び出すことを保証します。以下の場合に厳格なツール使用を使用してください：

• ツールパラメータを検証する
• エージェントワークフローを構築する
• 型安全な関数呼び出しを保証する
• ネストされたプロパティを持つ複雑なツールを処理する

エージェントにとって厳格なツール使用が重要な理由

信頼性の高いエージェントシステムを構築するには、スキーマへの準拠が保証される必要があります。厳格モードがない場合、Claudeは互換性のない型（2の代わりに"2"）や必須フィールドの欠落を返す可能性があり、関数が壊れてランタイムエラーが発生します。

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

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

例えば、予約システムがpassengers: intを必要とするとします。厳格モードがない場合、Claudeはpassengers: "two"やpassengers: "2"を提供する可能性があります。strict: trueを使用すると、レスポンスには常にpassengers: 2が含まれます。

クイックスタート

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }]
  }'

レスポンス形式： response.content[x].inputに検証済み入力を持つツール使用ブロック

{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

保証事項：

• ツールのinputはinput_schemaに厳密に従う
• ツールのnameは常に有効（提供されたツールまたはサーバーツールから）

仕組み

一般的なユースケース

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

JSON出力とストリクトツールユースは異なる問題を解決するものであり、組み合わせて使用できます：

• JSON出力はClaudeのレスポンス形式を制御します（Claudeが何を言うか）
• ストリクトツールユースはツールパラメータを検証します（ClaudeがどのようにあなたのFunctionを呼び出すか）

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

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Help me plan a trip to Paris for next month"}
    ],
    # 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,
            },
        }
    ],
)

重要な考慮事項

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

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

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

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

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

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

JSONスキーマの制限

構造化出力は標準のJSONスキーマをサポートしていますが、いくつかの制限があります。JSON出力とストリクトツールユースの両方がこれらの制限を共有します。

プロパティの順序

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

例えば、このスキーマが与えられた場合：

{
  "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レスポンスを超えて保持されません。

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

機能の互換性

動作する機能：

• バッチ処理：50%割引でスケールで構造化出力を処理
• トークンカウント：コンパイルなしでトークンをカウント
• ストリーミング：通常のレスポンスと同様に構造化出力をストリーム
• 組み合わせ使用：同じリクエストでJSON出力（output_config.format）とストリクトツールユース（strict: true）を一緒に使用

互換性のない機能：

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