Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
ウェブ検索ツールは、Claudeにリアルタイムのウェブコンテンツへの直接アクセスを提供し、知識のカットオフを超えた最新情報で質問に回答できるようにします。レスポンスには、検索結果から引用されたソースの引用情報が含まれます。
web_search_20260209以降のバージョンでは、Claudeは検索結果がコンテキストウィンドウに到達する前にフィルタリングするコードを記述・実行でき（動的フィルタリング）、関連情報のみを保持します。動的フィルタリングは、Claude 4.6以降のモデルおよびClaude Mythos Previewで利用可能です。
ウェブ検索ツールには3つのバージョンがあります。
web_search_20250305：基本的なウェブ検索web_search_20260209：動的フィルタリングを追加web_search_20260318：エージェントワークフロー向けのレスポンス包含制御を追加このページの例では、基本的な検索にはweb_search_20250305を、動的フィルタリングにはweb_search_20260318を使用しています。
ウェブ検索のゼロデータ保持（Zero Data Retention）の適格性および関連するallowed_callers設定については、サーバーツールを参照してください。
モデルのサポートについては、ツールリファレンスを参照してください。
APIリクエストにウェブ検索ツールを追加すると、次のように動作します。
Claudeは、リクエストが最新の情報、変化する情報、またはトレーニングデータ外の情報に依存している場合に検索します。
Claudeは、リクエストが安定した知識に基づいている場合は検索せずに直接回答します。
検索のトリガーはシステムプロンプトで調整可能です。Claudeがより積極的に検索するように促したり、直接回答することを優先させたりできます。厳密な制約を設けるには、max_usesを使用して各リクエストの検索回数に上限を設定します。
基本的なウェブ検索では、すべての検索結果がClaudeのコンテキストウィンドウに読み込まれ、そのコンテンツの多くがリクエストに無関係な場合があります。web_search_20260209以降では、Claudeは代わりに結果を最初にフィルタリングするコードを記述・実行するため、関連するコンテンツのみがコンテキストウィンドウに到達します。これにより、検索を多用するリクエストでのトークン使用量が削減されます。
動的フィルタリングは、コード実行内からウェブ検索を実行します。web_search_20260209以降では、ツールのallowed_callersフィールドはデフォルトで["code_execution_20260120"]に設定され、動的フィルタリングが実行されると、APIはリクエストに必要なコード実行を自動的にプロビジョニングします。コード実行ツールを自分でtoolsに追加する必要はありません。この方法で行われるコード実行呼び出しには、標準のトークンコスト以外の追加料金はかかりません。
動的フィルタリングを使用せずにウェブ検索を直接呼び出すには、allowed_callers: ["direct"]を設定します。プログラムによるツール呼び出しをサポートしていないモデルでは、この設定が必要です。設定しない場合、APIは設定を求める400エラーを返します。
以下の例ではweb_search_20260318を使用しています。
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
}
],
tools=[{"type": "web_search_20260318", "name": "web_search"}],
)
print(response)APIリクエストでウェブ検索ツールを指定します。
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "What's the weather in NYC?"}],
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)ウェブ検索ツールは以下のパラメータをサポートしています。
{
"type": "web_search_20250305",
"name": "web_search",
// Optional: Limit the number of searches per request
"max_uses": 5,
// Optional: Only include results from these domains.
// Use allowed_domains or blocked_domains, not both.
"allowed_domains": ["example.com", "trusteddomain.org"],
// Optional: Never include results from these domains
"blocked_domains": ["untrustedsource.com"],
// Optional: Localize search results
"user_location": {
"type": "approximate",
"city": "San Francisco",
"region": "California",
"country": "US",
"timezone": "America/Los_Angeles"
}
}すべてのウェブ検索ツールバージョンはallowed_callersを受け付けます。これは、Claudeがウェブ検索を直接呼び出すか、動的フィルタリングを通じてコード実行から呼び出すかを制御します。web_search_20260209以降では、デフォルトは["direct"]ではなく["code_execution_20260120"]です。設定方法についてはサーバーツールを参照してください。web_search_20260318以降はresponse_inclusionも受け付けます。
max_usesパラメータは、実行される検索の回数を制限します。Claudeが許可された回数を超えて検索を試みると、web_search_tool_resultはmax_uses_exceededエラーコードを含むエラーになります。
単純な事実確認のクエリは通常1〜3回の検索を使用し、比較や複数エンティティの調査では10回以上使用する場合があります。値の選択に関するガイダンスについては、サーバーツールを参照してください。
allowed_domainsまたはblocked_domainsのいずれかを指定し、両方は指定しないでください。リクエストに両方が含まれている場合、APIは400エラーを返します。エントリは、スキームを含まない、オプションのパス付きのドメイン名です（例：example.comまたはexample.com/blog）。
ドメインフィルタリングの完全なルールについては、サーバーツールガイドのドメインフィルタリングを参照してください。
user_locationパラメータを使用すると、ユーザーの位置情報に基づいて検索結果をローカライズできます。city、region、country、timezoneのうち少なくとも1つを指定してください。
type：位置情報のタイプ（approximateである必要があります）city：都市名region：地域または州country：2文字のISO 3166-1 alpha-2国コード。サポートされていない国コードは400エラーで拒否されます。timezone：IANAタイムゾーンIDresponse_inclusionパラメータは、同じターン内で完了したコード実行呼び出しによって結果が消費された場合に、検索結果ブロックがAPIレスポンスにどのように表示されるかを制御します。"response_inclusion": "excluded"を設定すると、ネストされたserver_tool_useと結果ブロックのペアがレスポンスから完全に削除され、生の検索コンテンツをクライアントにエコーバックする必要のないエージェントワークフローの出力トークンコストが削減されます。デフォルトは"full"です。直接呼び出しからの結果、または完了前に一時停止したコード実行呼び出しからの結果は、次のターンで送り返せるように常に完全な形で返されます。
{
"tools": [
{
"type": "web_search_20260318",
"name": "web_search",
"response_inclusion": "excluded"
}
]
}レスポンス構造の例を以下に示します。
{
"role": "assistant",
"content": [
// 1. Claude's decision to search
{
"type": "text",
"text": "I'll search for when Claude Shannon was born."
},
// 2. The search query used
{
"type": "server_tool_use",
"id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
"name": "web_search",
"input": {
"query": "claude shannon birth date"
}
},
// 3. Search results
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
"content": [
{
"type": "web_search_result",
"url": "https://en.wikipedia.org/wiki/Claude_Shannon",
"title": "Claude Shannon - Wikipedia",
"encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
"page_age": "April 30, 2025"
}
]
},
{
"text": "Based on the search results, ",
"type": "text"
},
// 4. Claude's response with citations
{
"text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
"type": "text",
"citations": [
{
"type": "web_search_result_location",
"url": "https://en.wikipedia.org/wiki/Claude_Shannon",
"title": "Claude Shannon - Wikipedia",
"encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
"cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
}
]
}
],
"id": "msg_a930390d3a",
"usage": {
"input_tokens": 6039,
"output_tokens": 931,
"server_tool_use": {
"web_search_requests": 1
}
},
"stop_reason": "end_turn"
}この例は直接検索を示しています。検索が動的フィルタリングを通じて実行される場合、レスポンスにはコード実行ツールの結果ブロックも含まれ、ネストされた各server_tool_useとweb_search_tool_resultのペアには、それを実行したコード実行呼び出しを識別するcallerフィールドが含まれます。
検索結果には以下が含まれます。
url：ソースページのURLtitle：ソースページのタイトルpage_age：サイトが最後に更新された日時encrypted_content：マルチターン会話で送り返す必要がある暗号化されたコンテンツ検索結果を含む会話を継続するには、アシスタントのコンテンツブロックを、各結果のencrypted_contentを含めて受信したとおりに正確に送り返してください。APIは後続のターンでそのコンテンツを復号化し、Claudeのコンテキスト内の検索結果を復元します。encrypted_contentが欠落しているか変更されている場合、リクエストは400検証エラーで失敗します。
ウェブ検索では引用が常に有効になっており、各web_search_result_locationには以下が含まれます。
url：引用元のURLtitle：引用元のタイトルencrypted_index：マルチターン会話で送り返す必要がある参照cited_text：引用されたコンテンツの最大150文字ウェブ検索の引用フィールドcited_text、title、urlは、入力または出力トークンの使用量にカウントされません。
ウェブ検索ツールがエラー（レート制限への到達など）に遭遇した場合でも、Claude APIは200（成功）レスポンスを返します。エラーは、以下の構造を使用してレスポンスボディ内で表現されます。
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_a93jad",
"content": {
"type": "web_search_tool_result_error",
"error_code": "max_uses_exceeded"
}
}エラーの場合、contentは結果ブロックのリストではなく、単一のエラーオブジェクトになります。検索が成功したが結果が一致しなかった場合は、エラーではなく空のcontentリストが返されます。
考えられるエラーコードは以下のとおりです。
too_many_requests：レート制限を超過しましたinvalid_tool_input：無効な検索クエリパラメータmax_uses_exceeded：ウェブ検索ツールの最大使用回数を超過しましたquery_too_long：クエリが最大長を超えていますrequest_too_large：検索リクエストが大きすぎます。通常は長いドメインフィルタリストが原因ですunavailable：内部エラーが発生しましたpause_turn停止理由APIは、長時間実行される検索ターンを一時停止し、stop_reason: "pause_turn"を返すことがあります。継続するには、一時停止したアシスタントメッセージを変更せずに新しいリクエストで送り返してください。
Claudeが同じ並列ツール呼び出しグループ内でウェブ検索とクライアントツールの1つを呼び出す場合、APIは代わりにstop_reason: "tool_use"を返し、検索はまだ実行されません。継続するには、クライアントツールの結果を返すと、APIは次のリクエストで検索を実行します。1つのターンでのサーバーツールとクライアントツールの混在を参照してください。
サーバー側ループとpause_turnの処理については、サーバーツールガイドのサーバー側ループとpause_turnを参照してください。
ターン間でツール定義をキャッシュする方法については、プロンプトキャッシングを使用したツール使用を参照してください。
ストリーミングを有効にすると、ストリームの一部として検索イベントを受信します。検索の実行中は一時停止が発生します。
event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
// Claude's decision to search
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}
// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}
// Pause while search executes
// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}
// Claude's response with citations (omitted in this example)ウェブ検索ツールはMessages Batches APIに含めることができます。Messages Batches APIを通じたウェブ検索ツール呼び出しは、通常のMessages APIリクエストと同じ料金で課金されます。
共有キャパシティを保護するため、Batches APIは組織ごとにウェブ検索リクエストをスロットリングするため、多数の検索を含む大規模なバッチは完了までに時間がかかる場合があります。組織のウェブ検索レート制限は、Claude Consoleのレート制限ページで確認できます。より高い制限をリクエストするには、そのページから営業担当にお問い合わせください。
ウェブ検索の使用料は、トークン使用料に加えて課金されます。
{
"usage": {
"input_tokens": 105,
"output_tokens": 6039,
"cache_read_input_tokens": 7123,
"cache_creation_input_tokens": 7345,
"server_tool_use": {
"web_search_requests": 1
}
}
}ウェブ検索はClaude APIで1,000回の検索あたり10ドルで利用でき、これに加えて検索で生成されたコンテンツに対する標準のトークン料金がかかります。会話全体を通じて取得されたウェブ検索結果は、単一のターン中に実行された検索の反復処理においても、その後の会話ターンにおいても、入力トークンとしてカウントされます。
各ウェブ検索は、返される結果の数に関係なく、1回の使用としてカウントされます。ウェブ検索中にエラーが発生した場合、そのウェブ検索は課金されません。
特定のURLからコンテンツを取得して読み込み、ライブウェブコンテンツでClaudeのコンテキストを拡張します。
Anthropicが実行するツールの操作：server_tool_useブロック、pause_turnの継続、ドメインフィルタリング。
Anthropic提供ツールのディレクトリと、オプションのツール定義プロパティのリファレンス。
Was this page helpful?