Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
「structured outputs」（構造化出力）は、Claudeのレスポンスを特定のスキーマに従うように制約し、下流の処理のために有効で解析可能な出力を保証します。構造化出力は、2つの補完的な機能を提供します。
output_config.format）：Claudeのレスポンスを特定のJSON形式で取得しますstrict: true）：ツール名と入力に対するスキーマ検証を保証しますこれらの機能は、独立して使用することも、同じリクエスト内で組み合わせて使用することもできます。
構造化出力を使用しない場合、Claudeは不正な形式のJSONレスポンスや無効なツール入力を生成し、アプリケーションを破壊する可能性があります。慎重にプロンプトを作成しても、次のような問題が発生することがあります。
構造化出力は、制約付きデコーディングによってスキーマに準拠したレスポンスを保証します。
JSON.parse()エラーが発生しませんJSON出力はClaudeのレスポンス形式を制御し、Claudeがスキーマに一致する有効なJSONを返すことを保証します。次のような場合にJSON出力を使用します。
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
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(next(block.text for block in response.content if block.type == "text"))レスポンス形式： レスポンスのテキストコンテンツブロック内に、スキーマに一致する有効なJSONが含まれます
{
"name": "John Smith",
"email": "[email protected]",
"plan_interest": "Enterprise",
"demo_requested": true
}JSONスキーマを定義する
Claudeに従わせたい構造を記述するJSONスキーマを作成します。スキーマは標準のJSON Schema形式を使用しますが、いくつかの制限があります（JSON Schemaの制限を参照）。
output_config.formatパラメータを追加する
APIリクエストにoutput_config.formatパラメータを含め、type: "json_schema"とスキーマ定義を指定します。
レスポンスを解析する
Claudeのレスポンスは、スキーマに一致する有効なJSONであり、レスポンスのテキストコンテンツブロックで返されます。
SDKは、スキーマ変換、自動検証、一般的なスキーマライブラリとの統合など、JSON出力の操作を容易にするヘルパーを提供します。
生のJSONスキーマを記述する代わりに、各言語で使い慣れたスキーマ定義ツールを使用できます。
client.messages.parse()zodOutputFormat()、または型付きJSON SchemaリテラルとjsonSchemaOutputFormat()outputConfig(Class<T>)による自動スキーマ導出を使用したプレーンなJavaクラスAnthropic::BaseModelクラスとoutput_config: {format: Model}StructuredOutputModelを実装するクラスとoutputConfig: ['format' => MyClass::class]Create<T>()オーバーロードを使用したプレーンなC#クラス（スキーマを自動的に導出）output_configを通じた生のJSONスキーマ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-5",
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のページを参照してください。
client.messages.parse()（推奨）
parse()メソッドは、Pydanticモデルを自動的に変換し、レスポンスを検証して、parsed_output属性を返します。
from pydantic import BaseModel
class ContactInfo(BaseModel):
name: str
email: str
plan_interest: str
response = client.messages.parse(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Extract contact info: John Smith, [email protected], interested in the Pro plan",
}
],
output_format=ContactInfo,
)
# パース済みの出力に直接アクセス
contact = response.parsed_output
print(contact.name, contact.email)transform_schema()ヘルパー
送信前にスキーマを手動で変換する必要がある場合や、Pydanticで生成されたスキーマを変更したい場合に使用します。提供されたスキーマを自動的に変換するclient.messages.parse()とは異なり、これは変換されたスキーマを返すため、さらにカスタマイズできます。
from anthropic import transform_schema
from pydantic import TypeAdapter
# まずPydanticモデルをJSONスキーマに変換し、その後変換処理を行います
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# 必要に応じてスキーマを修正します
schema["properties"]["custom_field"] = {"type": "string"}
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "..."}],
output_config={
"format": {"type": "json_schema", "schema": schema},
},
)Python、TypeScript、Ruby、PHPのSDKは、サポートされていない機能を持つスキーマを自動的に変換します。C#とGoのSDKは、スキーマがネイティブ型から導出される場合（C#ではCreate<T>()、Goでは構造体リフレクションまたはベータAPIのBetaJSONSchemaOutputFormat()）に同じ変換を適用します。変換手順は次のとおりです。
minimum、maximum、minLength、maxLength）additionalProperties: falseを追加**つまり、Claudeは簡略化されたスキーマを受け取りますが、コードは検証を通じてすべての制約を引き続き強制します。
例： minimum: 100を持つPydanticフィールドは、送信されるスキーマではプレーンな整数になりますが、SDKは説明を「Must be at least 100」に更新し、元の制約に対してレスポンスを検証します。
文法制約付きサンプリングによってツール入力にJSON Schema準拠を強制する方法については、厳密なツール使用を参照してください。
JSON出力と厳密なツール使用は異なる問題を解決し、連携して動作します。
組み合わせると、Claudeは保証された有効なパラメータでツールを呼び出し、かつ構造化されたJSONレスポンスを返すことができます。これは、信頼性の高いツール呼び出しと構造化された最終出力の両方が必要なエージェントワークフローに役立ちます。
response = client.messages.create(
model="claude-opus-5",
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)構造化出力は、コンパイルされた文法アーティファクトを使用した制約付きサンプリングを使用します。これにより、注意すべきいくつかのパフォーマンス特性が生じます。
nameまたはdescriptionフィールドのみを変更してもキャッシュは無効化されません構造化出力を使用する場合、Claudeは期待される出力形式を説明する追加のシステムプロンプトを自動的に受け取ります。これは次のことを意味します。
output_config.formatパラメータを変更すると、その会話スレッドのプロンプトキャッシュが無効化されます構造化出力は、いくつかの制限付きで標準のJSON Schemaをサポートします。JSON出力と厳密なツール使用の両方がこれらの制限を共有します。
構造化出力を使用する場合、オブジェクト内のプロパティはスキーマで定義された順序を維持しますが、1つの重要な注意点があります。必須プロパティが最初に表示され、その後にオプションプロパティが続きます。
例えば、次のスキーマの場合：
{
"type": "object",
"properties": {
"notes": { "type": "string" },
"name": { "type": "string" },
"email": { "type": "string" },
"age": { "type": "integer" }
},
"required": ["name", "email"],
"additionalProperties": false
}出力のプロパティ順序は次のようになります。
name（必須、スキーマ順）email（必須、スキーマ順）notes（オプション、スキーマ順）age（オプション、スキーマ順）つまり、出力は次のようになる可能性があります。
{
"name": "John Smith",
"email": "[email protected]",
"notes": "Interested in enterprise plan",
"age": 35
}出力のプロパティ順序がアプリケーションにとって重要な場合は、すべてのプロパティを必須としてマークするか、解析ロジックでこの並べ替えを考慮してください。
構造化出力はほとんどの場合スキーマ準拠を保証しますが、出力がスキーマと一致しないシナリオがあります。
拒否（stop_reason: "refusal"）
Claudeは、構造化出力を使用している場合でも、安全性と有用性の特性を維持します。Claudeが安全上の理由でリクエストを拒否した場合：
stop_reason: "refusal"が含まれますトークン制限に到達（stop_reason: "max_tokens"）
max_tokens制限に達してレスポンスが途中で切れた場合：
stop_reason: "max_tokens"が含まれますmax_tokens値でリトライしてくださいenum値の大文字小文字
構造化出力は、文字列のenumおよびconst値の大文字小文字を保証しません。Claudeは、スキーマと大文字小文字のみが異なる値を返すことがあります。通常は、スペースに続く単語の最初の文字で発生します。例えば、次のスキーマの場合：
{
"type": "string",
"enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}出力には、その正確な値がenumにないにもかかわらず、"Conversation Topic 3"（大文字の「T」）が含まれる可能性があります。レスポンスは正常に完了し、エラーも特別なstop_reasonもありません。これはJSON出力と厳密なツール使用の両方に適用されます。enum値は大文字小文字を区別せずに比較し、大文字小文字のみが異なるenum値は避けてください。
構造化出力は、JSONスキーマをClaudeの出力を制約する文法にコンパイルすることで動作します。より複雑なスキーマは、コンパイルに時間がかかるより大きな文法を生成します。過度なコンパイル時間を防ぐため、APIはいくつかの複雑さの制限を強制します。
次の制限は、output_config.formatまたはstrict: trueを含むすべてのリクエストに適用されます。
| 制限 | 値 | 説明 |
|---|---|---|
| リクエストあたりの厳密なツール数 | 20 | strict: trueを持つツールの最大数。非厳密なツールはこの制限にカウントされません。 |
| オプションパラメータ | 24 | すべての厳密なツールスキーマとJSON出力スキーマにわたるオプションパラメータの合計。requiredにリストされていない各パラメータがこの制限にカウントされます。 |
| ユニオン型を持つパラメータ | 16 | すべての厳密なスキーマにわたってanyOfまたは型配列（例えば、"type": ["string", "null"]）を使用するパラメータの合計。これらは指数関数的なコンパイルコストを生じさせるため、特にコストが高くなります。 |
前述の表の明示的な制限に加えて、コンパイルされた文法サイズに対する追加の内部制限があります。これらの制限が存在するのは、スキーマの複雑さが単一の次元に還元されないためです。オプションパラメータ、ユニオン型、ネストされたオブジェクト、ツール数などの機能は、コンパイルされた文法を不釣り合いに大きくする方法で相互に作用します。
これらの制限を超えると、「Schema is too complex for compilation.」というメッセージを含む400エラーが返されます。これらのエラーは、前述の表の各個別の制限が満たされていても、スキーマの複雑さの合計が効率的にコンパイルできる範囲を超えていることを意味します。最終的な安全策として、APIは180秒のコンパイルタイムアウトも強制します。すべての明示的なチェックを通過しても非常に大きなコンパイル済み文法を生成するスキーマは、このタイムアウトに達する可能性があります。
複雑さの制限に達している場合は、次の戦略を順番に試してください。
重要なツールのみを厳密としてマークする。 多くのツールがある場合、スキーマ違反が実際の問題を引き起こすツールにのみ予約し、より単純なツールについてはClaudeの自然な準拠に依存します。
オプションパラメータを減らす。 可能な限りパラメータをrequiredにします。各オプションパラメータは、文法の状態空間の一部をおおよそ2倍にします。パラメータに常に妥当なデフォルト値がある場合は、必須にしてClaudeにそのデフォルト値を明示的に提供させることを検討してください。
ネストされた構造を簡素化する。 オプションフィールドを持つ深くネストされたオブジェクトは複雑さを増大させます。可能な限り構造をフラット化してください。
複数のリクエストに分割する。 多くの厳密なツールがある場合は、それらを別々のリクエストまたはサブエージェントに分割することを検討してください。
有効なスキーマで問題が解決しない場合は、スキーマ定義を添えてサポートにお問い合わせください。
構造化出力を使用する場合、プロンプトとレスポンスはZDRで処理されます。ただし、JSONスキーマ自体は最適化のために最終使用から最大24時間一時的にキャッシュされます。APIレスポンス以降、プロンプトやレスポンスのデータは保持されません。
構造化出力はHIPAA対象ですが、PHIをJSONスキーマ定義に含めてはいけません。APIはJSONスキーマをメッセージコンテンツとは別にキャッシュされる文法にコンパイルし、これらのキャッシュされたスキーマはプロンプトやレスポンスと同じPHI保護を受けません。スキーマのプロパティ名、enum値、const値、またはpattern正規表現にPHIを含めないでください。PHIは、HIPAAセーフガードの下で保護されるメッセージコンテンツ（プロンプトとレスポンス）にのみ含めるべきです。
すべての機能にわたるZDRおよびHIPAA対象については、APIとデータ保持を参照してください。
互換性あり：
output_config.format）と厳密なツール使用（strict: true）を併用互換性なし：
output_config.formatで引用が有効になっている場合、400エラーを返します。提供されたドキュメントに関する質問に答える際に、Claudeに出典を引用させます。
文法制約付きサンプリングでClaudeのツール入力にJSON Schema準拠を強制します。
Claudeを外部ツールやAPIに接続します。ツールがどこで実行されるか、エージェントループがどのように動作するかを学びます。
モデルと機能に関するAnthropicの料金体系について学びます。
| Supported models |
|
|---|---|
| Supported platforms |
Was this page helpful?