構造化された出力

クイックスタート

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 などの使い慣れたスキーマ定義ツールを使用できます。

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 Schema の制限

構造化された出力は標準 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 出力と互換性がありません