構造化出力

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

• JSON出力（output_config.format）：Claudeの応答を特定のJSON形式で取得
• 厳密なツール使用（strict: true）：ツール名と入力のスキーマバリデーションを保証

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

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

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

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

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

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

JSON出力

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

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()

# .create()の場合 - transform_schema()が必要
response = client.messages.create(
    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": transform_schema(ContactInfo),
        }
    }
)

print(response.content[0].text)

# .parse()の場合 - Pydanticモデルを直接渡せる
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固有のメソッド

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

parse()メソッドは、Pydanticモデルを自動的に変換し、応答をバリデーションし、parsed_output属性を返します。

Python: transform_schema()ヘルパー

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

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がどのように関数を呼び出すか）

組み合わせると、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 Schemaをサポートしていますが、いくつかの制限があります。JSON出力と厳密なツール使用の両方がこれらの制限を共有しています。

無効な出力

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

拒否（stop_reason: "refusal"）

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

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

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

max_tokens制限に到達して応答が切り捨てられた場合：

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

スキーマバリデーションエラー

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

"Too many recursive definitions in schema"

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

"Schema is too complex"

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

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

機能の互換性

互換性あり：

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

互換性なし：

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