構造化出力
エージェントワークフローから検証済みのJSON結果を取得する
「structured outputs」(構造化出力)は、Claudeの応答を特定のスキーマに従うよう制約し、後続の処理のために有効で解析可能な出力を保証します。構造化出力は、相互に補完し合う2つの機能を提供します。
- JSON出力(
output_config.format):Claudeの応答を特定のJSON形式で取得します。たとえば、画像やテキストからデータを抽出する、構造化されたレポートを生成する、API応答をフォーマットするといった用途に使用できます。このページではJSON出力について説明します。 - 厳格なツール使用(
strict: true):ツール名と入力に対するスキーマ検証を保証します。厳格なツール使用を参照してください。
これらの機能は個別に使用することも、同じリクエスト内で併用することもできます。
構造化出力を使用する理由
構造化出力を使用しない場合、Claudeはアプリケーションを壊す不正な形式のJSON応答や無効なツール入力を生成する可能性があります。慎重にプロンプトを作成しても、次のような問題に遭遇する場合があります。
- 無効なJSON構文による解析エラー
- 必須フィールドの欠落
- 一貫性のないデータ型
- エラー処理と再試行を必要とするスキーマ違反
構造化出力は、「constrained decoding」(制約付きデコーディング)によってスキーマに準拠した応答を保証します。
- 常に有効: JSONの解析エラーがなくなります
- 型安全: フィールドの型と必須フィールドが保証されます
- 信頼性: スキーマ違反による再試行が不要です
仕組み
スキーマを定義する
必要な構造をJSONスキーマとして、または使用する言語の型として記述します。スキーマはJSON Schemaに従いますが、いくつかの制限があります。
output_config.formatで送信する
リクエストは、
type: "json_schema"を指定したoutput_config.formatでスキーマを送信します。SDKヘルパーがこれを自動的に設定します。応答を読み取る
Claudeは、スキーマに一致する有効なJSONを応答のテキストコンテンツブロックで返します。SDKヘルパーはそれを指定した型に解析します。
使用方法
from pydantic import BaseModel
class ContactInfo(BaseModel):
name: str
email: str
plan_interest: str
demo_requested: bool
client = Anthropic()
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": (
"Extract the key information from this email: "
"John Smith (john@example.com) is interested in our Enterprise plan "
"and wants to schedule a demo for next Tuesday at 2pm."
),
}
],
output_format=ContactInfo,
)
print(response.parsed_output)推奨される方法であるclient.messages.parse()に、Pydanticモデルをoutput_formatとして渡します。SDKはモデルのスキーマを変換し、output_config.formatとして送信し、応答を検証して、解析済みのモデルをparsed_outputで返します。
前の例の出力は次のとおりです。
name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=Trueフィールドのキーがわかっている場合は、dictではなくネストされたPydanticモデルを使用してください。SDKはdictフィールドを空のpropertiesを持つオブジェクトとして送信するため、Claudeはそのフィールドに{}しか返せません。キーが事前にわからない場合は、任意のキーを持つオブジェクトを参照してください。
SDKによる変換の仕組み
ほとんどのSDKヘルパーは、サポートされていない機能を使用するスキーマを変換します。変換の手順は次のとおりです。
- サポートされていない制約を削除する(例:
minimum、maximum、minLength、maxLength) - 説明を更新する:サポートされていない各制約をフィールドの説明に追加します(例:
{minimum: 100}) - すべてのオブジェクトに
additionalProperties: falseを追加する - 文字列フォーマットをフィルタリングし、サポートされているもののみに絞り込む
- ヘルパーが応答を検証する場合、元のスキーマとそのすべての制約に対して応答を検証する
Claudeは簡略化されたスキーマを受け取りますが、応答を検証するヘルパーは、コード内ですべての制約を引き続き適用します。
例: minimum: 100を持つフィールドは、送信されるスキーマでは単純な整数になり、SDKはフィールドの説明に{minimum: 100}を追加します。応答を検証するヘルパーは、引き続きminimum: 100に対して応答をチェックします。
生のJSONスキーマの使用
ファイル、OpenAPI仕様、または実行時にスキーマを構築するコードからのJSONスキーマを使用するには、それをoutput_config.formatで渡します。
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": (
"Extract the key information from this email: "
"John Smith (john@example.com) 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,
},
}
},
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)前の例の出力は次のとおりです。
{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}APIでサポートされていない制約をフィールドの説明に移すには、送信前にanthropicパッケージのtransform_schema()にスキーマを通し、必要に応じて結果を編集してください。transform_schema()はPydanticモデルも受け付けます。client.messages.parse()とは異なり、スキーマを送信するのではなく、変換されたスキーマを返します。
一般的なユースケース
非構造化テキストから構造化データを抽出します。
from pydantic import BaseModel
class LineItem(BaseModel):
description: str
quantity: float
unit_price: float
class Invoice(BaseModel):
invoice_number: str
date: str
total_amount: float
line_items: list[LineItem]
customer_name: str
client = anthropic.Anthropic()
invoice_text = """
Invoice #12345
Date: 2024-01-15
Customer: Acme Corp
2 widgets at $150.00 each
1 setup fee at $200.00
Total: $500.00
"""
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=4096,
output_format=Invoice,
messages=[
{"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
],
)
print(response.parsed_output)構造化されたカテゴリでコンテンツを分類します。
from pydantic import BaseModel
client = Anthropic()
class Classification(BaseModel):
category: str
confidence: float
tags: list[str]
sentiment: str
feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=1024,
output_format=Classification,
messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)
print(response.parsed_output)APIですぐに使える応答を生成します。
from pydantic import BaseModel
client = Anthropic()
class Payload(BaseModel):
message: str
class APIError(BaseModel):
code: str
detail: str
class Metadata(BaseModel):
request_id: str
class APIResponse(BaseModel):
status: str
data: Payload
errors: list[APIError] | None = None
metadata: Metadata
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=1024,
output_format=APIResponse,
messages=[
{
"role": "user",
"content": "Write an API response: request req_2abc3def has an invalid email.",
}
],
)
print(response.parsed_output)厳格なツール使用
文法制約付きサンプリングによってツール入力にJSON Schemaへの準拠を強制するには、厳格なツール使用を参照してください。
両方の機能を併用する
JSON出力と厳格なツール使用は、異なる問題を解決するものであり、連携して動作します。
- JSON出力は、Claudeの応答形式(Claudeが何を言うか)を制御します。
- 厳格なツール使用は、ツールのパラメータ(Claudeが関数をどのように呼び出すか)を検証します。
組み合わせることで、Claudeは有効性が保証されたパラメータでツールを呼び出し、かつ構造化されたJSON応答を返すことができます。これは、信頼性の高いツール呼び出しと構造化された最終出力の両方が必要なエージェント型ワークフローに役立ちます。
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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)重要な考慮事項
文法のコンパイルとキャッシング
構造化出力は、コンパイルされた文法アーティファクトを用いた制約付きサンプリングを使用します。これにより、注意すべきいくつかのパフォーマンス特性が生じます。
- 最初のリクエストのレイテンシ: 特定のスキーマを初めて使用する際、文法のコンパイル中に追加の「latency」(レイテンシ)が発生します。
- 自動キャッシング: コンパイルされた文法は最後の使用から24時間キャッシュされるため、以降のリクエストは大幅に高速になります。
- キャッシュの無効化: JSONスキーマの構造を変更した場合、または構造化出力とツール使用の両方を使用しているときにリクエスト内のツールのセットを変更した場合、キャッシュは無効化されます。
nameまたはdescriptionフィールドのみを変更しても、キャッシュは無効化されません。
プロンプトの変更とトークンコスト
構造化出力を使用すると、Claudeは期待される出力形式を説明する追加のシステムプロンプトを自動的に受け取ります。これは次のことを意味します。
- 入力トークン数がわずかに増加します。
- 挿入されたプロンプトは、他のシステムプロンプトと同様にトークンのコストが発生します。
output_config.formatパラメータを変更すると、その会話スレッドのプロンプトキャッシングのキャッシュはすべて無効化されます。
JSON Schemaの制限
構造化出力は標準的なJSON Schemaをサポートしていますが、いくつかの制限があります。JSON出力と厳格なツール使用の両方がこれらの制限を共有します。
- すべての基本型:object、array、string、integer、number、boolean、null
enum(文字列、数値、ブール値、またはnullのみ。複合型は不可)。大文字・小文字に関する注意点については、無効な出力を参照してください。constanyOfとallOf(制限あり:$refを伴うallOfはサポートされていません)$ref、$def、およびdefinitions(外部$refはサポートされていません)- サポートされているすべての型に対する
defaultプロパティ requiredとadditionalProperties(オブジェクトではfalseに設定する必要があります)- 文字列フォーマット:
date-time、time、date、duration、email、hostname、uri、ipv4、ipv6、uuid - 配列の
minItems(値0と1のみサポート)
- 再帰的なスキーマ
- enum内の複合型
- 外部
$ref(例:'$ref': 'http://...') - 数値の制約(
minimum、maximum、multipleOfなど) - 文字列の制約(
minLength、maxLength) - 0または1の
minItems以外の配列の制約 false以外に設定されたadditionalProperties(任意のキーを持つオブジェクトを参照)
サポートされていない機能を使用すると、詳細を含む400エラーが返されます。
サポートされている正規表現機能:
- 完全一致(
^...$)と部分一致 - 量指定子:
*、+、?、単純な{n,m}のケース - 文字クラス:
[]、.、\d、\w、\s - グループ:
(...)
サポートされていないもの:
- グループへの後方参照(例:
\1、\2) - 先読み/後読みアサーション(例:
(?=...)、(?!...)) - 単語境界:
\b、\B - 範囲の大きい複雑な
{n,m}量指定子
単純な正規表現パターンは問題なく機能します。複雑なパターンは400エラーになる可能性があります。
任意のキーを持つオブジェクト
オブジェクトのすべてのキーを、properties内に、またはSDKに渡すクラスやスキーマのフィールドとして記載してください。additionalPropertiesはfalseである必要があるため、Claudeは記載したキーのみを返すことができます。
APIはpropertiesが空または存在しないオブジェクトを受け付けますが、Claudeはそのオブジェクトに対して{}しか返せません。マップ、辞書、またはレコード型はキーを記載しないため、PythonとTypeScriptのSDKはそれを空のpropertiesを持つオブジェクトとして送信します。JavaとRubyのSDKは代わりにエラーを発生させます。
キーが事前にわからない場合は、代わりに配列を使用してください。次のスキーマのように、各項目にkeyとvalueを持たせてください。
{
"type": "array",
"items": {
"type": "object",
"properties": {
"key": { "type": "string" },
"value": { "type": "string" }
},
"required": ["key", "value"],
"additionalProperties": false
}
}プロパティの順序
構造化出力を使用する場合、オブジェクト内のプロパティはスキーマで定義された順序を維持しますが、重要な注意点が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": "john@example.com",
"notes": "Interested in enterprise plan",
"age": 35
}出力のプロパティの順序がアプリケーションにとって重要な場合は、すべてのプロパティを必須としてマークするか、解析ロジックでこの並べ替えを考慮してください。
無効な出力
構造化出力はほとんどの場合スキーマへの準拠を保証しますが、出力がスキーマと一致しない可能性があるシナリオもあります。
拒否(stop_reason: "refusal")
Claudeは、構造化出力を使用している場合でも、安全性と有用性の特性を維持します。Claudeが安全上の理由でリクエストを拒否した場合:
- 応答は
stop_reason: "refusal"になります。 - 200ステータスコードが返されます。
- 生成されたトークンに対して課金されます。
- 拒否メッセージがスキーマの制約より優先されるため、出力がスキーマと一致しない可能性があります。
モデルの思考や段階的な推論を求めるプロパティは、reasoning_extractionによる拒否につながる可能性があります。代わりに短い説明を求めてください。推論を思考ブロック内に保持するを参照してください。
トークン制限に到達(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にそのデフォルト値を明示的に指定させることを検討してください。 -
ネストされた構造を単純化する。 オプションのフィールドを持つ深くネストされたオブジェクトは、複雑さを増大させます。可能な限り構造をフラットにしてください。
-
複数のリクエストに分割する。 厳格なツールが多い場合は、それらを別々のリクエストやサブエージェントに分割することを検討してください。
有効なスキーマで問題が解決しない場合は、スキーマ定義を添えてサポートにお問い合わせください。
ベータ版からの移行
output_formatパラメータはoutput_config.formatに移動し、ベータヘッダーは不要になりました。output_formatパラメータは非推奨です。それでも使用する場合は、structured-outputs-2025-11-13ベータヘッダーを追加してください。ヘッダーがない場合、APIは400エラーを返します。
Python SDK(v1.0以降)では、output_format={...}として渡されたスキーマ辞書はTypeErrorを発生させます。代わりにoutput_configを使用してください。parse()またはstream()にoutput_format=Modelとして渡されたPydanticモデルは、SDKがそれをoutput_configとして送信するため、変更もベータヘッダーも不要でそのまま動作します。更新されたAPIの形式については、生のJSONスキーマの使用を参照してください。
機能の互換性
併用可能:
- バッチ処理: 50パーセントの割引で構造化出力を大規模に処理できます
- トークンカウント: コンパイルせずにトークンをカウントできます
- ストリーミング: 通常の応答と同様に構造化出力をストリーミングできます
- 併用: 同じリクエスト内でJSON出力(
output_config.format)と厳格なツール使用(strict: true)を併用できます
互換性なし:
- 引用: 引用ではテキストに引用ブロックを交互に挿入する必要があり、これは厳格なJSONスキーマの制約と競合します。
output_config.formatとともに引用が有効になっている場合、APIは400エラーを返します。各値に引用を付けて構造化データを抽出するには、引用付きの構造化データを取得するを参照してください。 - メッセージのプリフィル: プリフィルはJSON出力と互換性がありません。
利用可能状況
Claude API
- API
- Messages API
- Managed Agents サポート対象外
- モデル
- すべてのモデル
Amazon Bedrock
- API
- Messages API
- モデル
- すべてのモデル
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- モデル
- すべてのモデル
Claude Platform on AWS
- API
- Messages API
- Managed Agents サポート対象外
- モデル
- すべてのモデル
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents サポート対象外
- モデル
- すべてのモデル
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- モデル
- すべてのモデル
Microsoft Foundry
- API
- Messages API
- モデル
- すべてのモデル
データの取り扱い
データの取り扱いの概要構造化出力を使用する場合、プロンプトと応答はZDRで処理されます。ただし、JSONスキーマ自体は、最適化の目的で最後の使用から最大24時間一時的にキャッシュされます。API応答を超えてプロンプトや応答のデータが保持されることはありません。
構造化出力はHIPAAの対象となりますが、JSONスキーマの定義にPHIを含めてはいけません。APIはJSONスキーマを文法にコンパイルし、それらはメッセージコンテンツとは別にキャッシュされます。これらのキャッシュされたスキーマは、プロンプトや応答と同じPHI保護を受けません。スキーマのプロパティ名、enum値、const値、またはpattern正規表現にPHIを含めないでください。PHIは、HIPAAの保護措置の下で保護されるメッセージコンテンツ(プロンプトと応答)にのみ含めるべきです。
次のステップ
提供されたドキュメントに関する質問に答える際に、Claudeに情報源を引用させます。
文法制約付きサンプリングによって、Claudeのツール入力にJSON Schemaへの準拠を強制します。
Claudeを外部ツールやAPIに接続します。ツールがどこで実行されるか、エージェントループがどのように機能するかを学びます。
モデルと機能に関するAnthropicの料金体系について学びます。
このページは役に立ちましたか?