--- title: ウェブ検索ツール url: https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool description: 引用元付きの最新のWebコンテンツへのアクセス、オプションの動的フィルタリング、ドメイン制御をClaudeに提供します。 featureMetadata: status: stable zdr: eligibility: eligible note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). リアルタイムのウェブ検索結果がAPIレスポンスで返されます。ウェブ検索の動的フィルタリングは、ZDRまたはHIPAAの適格対象ではありません。 supportedModels: - claude-fable-5-1 - claude-mythos-5-1 - claude-fable-5 - claude-mythos-5 - claude-mythos-preview - claude-opus-5-5 - claude-opus-5 - claude-sonnet-5-5 - claude-sonnet-5 - claude-haiku-5-5 - claude-haiku-4-5-20251001 - claude-opus-4-8 - claude-opus-4-7 - claude-opus-4-6 - claude-sonnet-4-6 - claude-opus-4-5-20251101 - claude-sonnet-4-5-20250929 supportedPlatforms: Claude API: stable Claude Platform on AWS: stable Claude Models on Google Cloud (Anthropic managed): stable Claude Models on Google Cloud (Google managed): availability: stable note: 動的フィルタリングなしの基本的なウェブ検索ツール（`web_search_20250305`）のみです。 Microsoft Foundry: availability: stable note: 動的フィルタリングなしの基本的なウェブ検索ツール（`web_search_20250305`）のみです。 --- **APIサポート**：使用方法は製品によって異なります。 * **Messages API**：リクエストの`tools`に`web_search`ツールを追加します。`max_uses`、ドメインリスト、`user_location`などの設定はそのツールに指定します。 * **Managed Agents**：エージェントのツールセットでデフォルトで有効です。`max_uses`、`citations`、`cache_control`は使用できません。 Web検索ツールは、Claudeにリアルタイムのwebコンテンツへの直接アクセスを提供し、知識のカットオフを超えた最新の情報で質問に答えられるようにします。レスポンスには、検索結果から引用されたソースの引用情報が含まれます。 `web_search_20260209`以降のバージョンでは、Claudeは検索結果がコンテキストウィンドウに到達する前にフィルタリングするコードを記述して実行でき（**dynamic filtering**（動的フィルタリング））、関連する情報のみを保持します。動的フィルタリングは、Claude 4.6以降のモデルおよび[Claude Mythos Preview](https://anthropic.com/glasswing)で利用できます。 Web検索ツールには3つのバージョンがあります。 * `web_search_20250305`：基本的なWeb検索 * `web_search_20260209`：[動的フィルタリング](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool#dynamic-filtering)を追加 * `web_search_20260318`：エージェント型ワークフロー向けの[レスポンスへの包含](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool#response-inclusion)制御を追加 このページの例では、基本的な検索には`web_search_20250305`を、動的フィルタリングには`web_search_20260318`を使用しています。 [Claude Mythos Preview](https://anthropic.com/glasswing)では、Web検索はClaude API、Claude Models on Google Cloud (Google managed)、およびMicrosoft Foundryでサポートされています。 Web検索の「Zero Data Retention」（ゼロデータ保持）の適格性と関連する`allowed_callers`の設定については、[サーバーツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers)を参照してください。 モデルのサポートについては、[ツールリファレンス](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference)を参照してください。 リクエストを送信する前にモデルがWeb検索を受け付けるかどうかを確認するには、Models APIからそのモデルの`capabilities.server_tools.web_search.supported`の値を読み取ります。このフィールドについては[Models APIの使用](https://platform.claude.com/docs/ja/models/overview#using-the-models-api)で説明しています。 ## Web検索の仕組み APIリクエストにWeb検索ツールを追加すると、次のように動作します。 1. Claudeはプロンプトに基づいて、いつ検索するかを判断します。 2. APIが検索を実行し、その結果をClaudeに提供します。このプロセスは、1つのリクエストの中で複数回繰り返されることがあります。 3. ターンの終わりに、Claudeは引用元付きの最終レスポンスを提供します。 ### Claudeが検索するタイミング Claudeは、リクエストが最新の情報、変化する情報、またはトレーニングデータの範囲外の情報に依存する場合に検索します。 * 最近の出来事、ニュース、または発表 * 現在の価格、レート、スコア、または統計 * 変化している可能性のある特定の組織、人物、または製品に関する情報 * 検索や調べものを明示的に求めるリクエスト リクエストが安定した知識に基づく場合、Claudeは検索せずに直接回答します。 * 確立された事実、数学、科学の基礎、またはコーディングの概念 * 創作や「brainstorming」（ブレインストーミング） * 会話内ですでに提供されたコンテンツの分析 * 会話上のやり取りや挨拶 検索のトリガーはシステムプロンプトで調整できます。Claudeがより積極的に検索するよう促すことも、直接回答することを優先させることもできます。制限を強制するには、[`max_uses`](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool#max-uses)を使用して1ターンあたりの検索回数に上限を設けてください。 ### 動的フィルタリング 基本的なWeb検索では、すべての検索結果がClaudeのコンテキストウィンドウに読み込まれ、その内容の多くはリクエストと無関係な場合があります。`web_search_20260209`以降では、Claudeが代わりにまず結果をフィルタリングするコードを記述して実行するため、関連するコンテンツのみがコンテキストウィンドウに到達します。これにより、検索の多いリクエストでのトークン使用量が削減されます。 動的フィルタリングは、[コード実行](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/code-execution-tool)の内部からWeb検索を実行します。`web_search_20260209`以降では、ツールの`allowed_callers`フィールドはデフォルトで`["code_execution_20260120"]`となり、動的フィルタリングが実行されると、APIはリクエストに必要なコード実行を自動的にプロビジョニングします。コード実行ツールを自分で`tools`に追加する必要はありません。この方法で行われるコード実行呼び出しには、標準のトークンコスト以外の追加料金はかかりません。 動的フィルタリングを使用せずにWeb検索を直接呼び出すには、`allowed_callers: ["direct"]`を設定します。プログラムによるツール呼び出しをサポートしていないモデルでは、この設定が必要です。設定しない場合、APIはこの設定を行うよう指示する400エラーを返します。 Web検索ツール（動的フィルタリングあり・なしの両方）は、Claude API、[Claude Platform on AWS](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws)、[Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ja/build-with-claude/claude-models-on-google-cloud/anthropic-managed)、および[Microsoft Foundry](https://platform.claude.com/docs/ja/build-with-claude/claude-in-microsoft-foundry)で利用できます。Microsoft Foundryでは、[Azureでホストされている](https://platform.claude.com/docs/ja/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure)デプロイメントは基本的なWeb検索ツール（`web_search_20250305`、動的フィルタリングなし）のみをサポートします。Anthropicでホストされているデプロイメントはすべてのバージョンをサポートします。Claude Models on Google Cloud (Google managed)では、基本的なWeb検索ツール（動的フィルタリングなし）のみが利用できます。 以下の例では`web_search_20260318`を使用しています。 ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2026-10-21" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-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" }] }' ``` ```bash CLI ant messages create <<'YAML' model: claude-opus-5-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 YAML ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-5-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) ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-5-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" }] }); console.log(response); ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = [new UserMessageParam { Content = "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." }], Tools = [new ToolUnion(new WebSearchTool20260318())] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.")), }, Tools: []anthropic.ToolUnionParam{ {OfWebSearchTool20260318: &anthropic.WebSearchTool20260318Param{}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```java Java import com.anthropic.models.messages.WebSearchTool20260318; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addUserMessage("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.") .addTool(WebSearchTool20260318.builder().build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP $client = new Client(); $message = $client->messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => 'Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.'], ], model: Model::CLAUDE_OPUS_5_5, tools: [ [ 'type' => 'web_search_20260318', 'name' => 'web_search', ], ], ); echo $message; ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: Anthropic::Model::CLAUDE_OPUS_5_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" }] ) puts message ``` ## Web検索の使い方 Web検索は、管理者が[Claude Console](https://platform.claude.com/settings/capabilities)で無効にしていない限り、組織で有効になっています。管理者はそこで検索対象のドメインを制限することもできます。無効になっている場合、このツールを含むMessages APIリクエストは、検索結果内の[エラーコード](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool#errors)ではなく、Web検索が有効になっていないことを示す400 `invalid_request_error`で失敗します。 Claude Managed Agentsのセッションで組織のWeb検索設定がどのように適用されるかについては、[Web検索とWebフェッチのドメインを制限する](https://platform.claude.com/docs/ja/managed-agents/tools-web-restrictions)を参照してください。 APIリクエストでWeb検索ツールを指定します。 ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2026-10-21" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "What is the weather in NYC?" } ], "tools": [{ "type": "web_search_20250305", "name": "web_search", "max_uses": 5 }] }' ``` ```bash CLI ant messages create \ --model claude-opus-5-5 \ --max-tokens 4096 \ --message '{role: user, content: What is the weather in NYC?}' \ --tool '{type: web_search_20250305, name: web_search, max_uses: 5}' ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-5-5", max_tokens=4096, messages=[{"role": "user", "content": "What's the weather in NYC?"}], tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}], ) print(response) ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 4096, messages: [ { role: "user", content: "What's the weather in NYC?" } ], tools: [ { type: "web_search_20250305", name: "web_search", max_uses: 5 } ] }); console.log(response); ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = [new UserMessageParam { Content = "What's the weather in NYC?" }], Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 5 })] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in NYC?")), }, Tools: []anthropic.ToolUnionParam{ {OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{ MaxUses: anthropic.Int(5), }}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```java Java import com.anthropic.models.messages.WebSearchTool20250305; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addUserMessage("What's the weather in NYC?") .addTool(WebSearchTool20250305.builder() .maxUses(5L) .build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP $client = new Client(); $message = $client->messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => "What's the weather in NYC?"], ], model: Model::CLAUDE_OPUS_5_5, tools: [ [ 'type' => 'web_search_20250305', 'name' => 'web_search', 'max_uses' => 5, ], ], ); echo $message; ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: Anthropic::Model::CLAUDE_OPUS_5_5, max_tokens: 4096, messages: [ { role: "user", content: "What's the weather in NYC?" } ], tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 5 }] ) puts message ``` ## ツール定義 Web検索ツールは以下のパラメータをサポートしています。 ```json JSON { "type": "web_search_20250305", "name": "web_search", // Optional: Limit the number of searches "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" } } ``` すべてのWeb検索ツールのバージョンは`allowed_callers`を受け付けます。これは、ClaudeがWeb検索を直接呼び出すか、[動的フィルタリング](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool#dynamic-filtering)を通じてコード実行から呼び出すかを制御します。`web_search_20260209`以降では、デフォルト値は`["direct"]`ではなく`["code_execution_20260120"]`です。設定方法については[ZDRとallowed\_callers](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers)を参照してください。`web_search_20260318`以降では、[`response_inclusion`](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool#response-inclusion)も受け付けます。 ### 最大使用回数 `max_uses`パラメータは、1つのターン内の検索回数を制限します。単一の事実に関するクエリでは通常1〜3回の検索が使用されますが、比較調査や複数エンティティの調査では10回以上使用されることがあります。 失敗した検索も上限にカウントされます。ClaudeがWeb検索を直接、許可された回数を超えて呼び出すと、`web_search_tool_result`は`max_uses_exceeded`エラーコードを伴うエラーになります。Claudeがコード実行からWeb検索を許可された回数を超えて呼び出すと、コード実行の実行はエラーで終了します。 1つのターンは複数のリクエストにまたがることがあります。リクエストが[`pause_turn`](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn)の後に再開する場合、または最後のメッセージに`tool_result`ブロックのみが含まれる場合、そのリクエストはターンを継続します。そのターン内の以前のリクエストで行われた検索は上限にカウントされます。ただし、Claudeが[動的フィルタリング](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool#dynamic-filtering)を通じてコード実行から実行した検索は除きます。 ### ドメインフィルタリング `allowed_domains`または`blocked_domains`のいずれか一方を指定し、両方は指定しないでください。リクエストに両方が含まれている場合、APIは400エラーを返します。エントリはスキームを含まない、オプションのパス付きのドメインです（例：`example.com`や`example.com/blog`）。 ドメインフィルタリングの完全なルールについては、サーバーツールガイドの[ドメインフィルタリング](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools#domain-filtering)を参照してください。 [Claude Managed Agents](https://platform.claude.com/docs/ja/managed-agents/overview)では、エージェントのツールセットの`web_search`エントリにこれらのフィールドを設定します。[Web検索とWebフェッチのドメインを制限する](https://platform.claude.com/docs/ja/managed-agents/tools-web-restrictions)を参照してください。 ### ローカライゼーション `user_location`パラメータを使用すると、ユーザーの所在地に基づいて検索結果をローカライズできます。`city`、`region`、`country`、`timezone`のうち少なくとも1つを指定してください。 * `type`：所在地の種類（`approximate`である必要があります） * `city`：都市名 * `region`：地域または州 * `country`：2文字の[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)国コード（サポートされていないコードの場合、APIは400エラーで拒否します） * `timezone`：[IANAタイムゾーンID](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) Claude Managed Agentsでは、エージェントのツールセットの`web_search`エントリも`user_location`を受け付けます。[Webツールの設定](https://platform.claude.com/docs/ja/managed-agents/tools-web-restrictions#settings)を参照してください。 ### レスポンスへの包含 `web_search_20260318`以降が必要です。 `response_inclusion`パラメータは、同じレスポンス内で完了した[コード実行](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/code-execution-tool)呼び出しによって結果が消費された場合に、検索結果ブロックがAPIレスポンスにどのように表示されるかを制御します。生の検索コンテンツを必要としないエージェント型ワークフローでは、`"response_inclusion": "excluded"`を設定すると、ネストされた`server_tool_use`と結果ブロックのペアがレスポンスから完全に除外されます。Claudeはこれらのブロックではなくコードの出力を読み取るため、トークン使用量には影響しません。デフォルトは`"full"`です。直接呼び出しの結果、または完了前に一時停止したコード実行呼び出しの結果は、次のリクエストで送り返せるよう、APIは常に完全な形で返します。 ```json JSON { "tools": [ { "type": "web_search_20260318", "name": "web_search", "response_inclusion": "excluded" } ] } ``` ## レスポンス レスポンス構造の例を次に示します。 ```json Output { "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" } ``` この例は直接検索を示しています。検索が[動的フィルタリング](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool#dynamic-filtering)を通じて実行される場合、レスポンスには[コード実行ツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/code-execution-tool)の結果ブロックも含まれ、ネストされた各`server_tool_use`と`web_search_tool_result`のペアには、それを実行したコード実行呼び出しを識別する`caller`フィールドが含まれます。 ### 検索結果 検索結果には以下が含まれます。 * `url`：ソースページのURL * `title`：ソースページのタイトル * `page_age`：サイトが最後に更新された日時 * `encrypted_content`：マルチターンの会話で送り返す必要がある暗号化されたコンテンツ 検索結果を含む会話を続けるには、アシスタントのコンテンツブロックを、各結果の`encrypted_content`を含めて、受け取ったとおりに正確に送り返してください。APIは後続のリクエストでそのコンテンツを復号し、Claudeのコンテキスト内の検索結果を復元します。`encrypted_content`が欠落しているか変更されている場合、リクエストは400検証エラーで失敗します。 ### 引用 Web検索では引用が常に有効になっており、各`web_search_result_location`には以下が含まれます。 * `url`：引用されたソースのURL * `title`：引用されたソースのタイトル * `encrypted_index`：マルチターンの会話で送り返す必要がある参照 * `cited_text`：引用されたコンテンツの最大150文字 Web検索の引用フィールドである`cited_text`、`title`、`url`は、入力トークンまたは出力トークンの使用量にカウントされません。 APIの出力をエンドユーザーに直接表示する場合は、元のソースへの引用を含める必要があります。エンドユーザーに表示する前に、再処理や独自の素材との組み合わせなど、APIの出力に変更を加える場合は、法務チームと相談のうえ、適切に引用を表示してください。 ### エラー Web検索ツールでエラー（レート制限に達した場合など）が発生しても、Claude APIは200（成功）レスポンスを返します。エラーは、次の構造を使用してレスポンス本文内で表現されます。 ```json Output { "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`：Web検索ツールの最大使用回数を超過しました * `query_too_long`：クエリが最大長を超えています * `request_too_large`：検索リクエストが大きすぎます（通常はドメインフィルターのリストが長いことが原因です） * `unavailable`：内部エラーが発生しました ### `pause_turn`停止理由 APIは長時間実行される検索ターンを一時停止し、`stop_reason: "pause_turn"`を返すことがあります。続行するには、一時停止したアシスタントメッセージを変更せずに新しいリクエストで送り返してください。 Claudeが並列ツール呼び出しの同じグループ内でWeb検索といずれかのクライアントツールの両方を呼び出した場合、APIは代わりに`stop_reason: "tool_use"`を返し、その時点では検索を実行しません。続行するには、クライアントツールの結果を返してください。APIは次のリクエストで検索を実行します。[1つのターンでサーバーツールとクライアントツールを組み合わせる](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn)を参照してください。 サーバー側のループと`pause_turn`の処理については、サーバーツールガイドの[サーバー側のループとpause\_turn](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn)を参照してください。 ## プロンプトキャッシング ターン間でツール定義をキャッシュするには、[プロンプトキャッシングを使用したツール使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-use-with-prompt-caching)を参照してください。 ## ストリーミング ストリーミングを有効にすると、ストリームの一部として検索イベントを受け取ります。検索の実行中には一時停止があります。 ```sse Output 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 runs // 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) ``` ## バッチリクエスト Web検索ツールは[Message Batches API](https://platform.claude.com/docs/ja/build-with-claude/batch-processing)に含めることができます。Message Batches APIを通じたWeb検索ツールの呼び出しは、通常のMessages APIリクエストでの呼び出しと同じ価格設定です。 共有キャパシティを保護するため、Batches APIは組織ごとにWeb検索リクエストをスロットリングします。そのため、多数の検索を含む大規模なバッチは完了までに時間がかかる場合があります。組織のWeb検索のレート制限は、Claude Consoleの[レート制限](https://platform.claude.com/usage/limits)ページで確認できます。より高い制限をリクエストするには、そのページから営業担当にお問い合わせください。 ## 使用量と料金 ウェブ検索の使用は、トークン使用量に加えて課金されます： ```json { "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からコンテンツを取得して読み込み、ライブのWebコンテンツでClaudeのコンテキストを拡張します。 Anthropicが実行するツールを扱います：`server_tool_use`ブロック、`pause_turn`による継続、ドメインフィルタリング。 Anthropicが提供するツールのディレクトリと、オプションのツール定義プロパティのリファレンス。 ## 利用可能状況 ウェブ検索ツールはすべてのモデルで利用可能であり、ゼロデータ保持とHIPAAレディネスの対象です。 ### APIサポート #### [Messages API](https://platform.claude.com/docs/ja/build-with-claude/working-with-messages) * 利用可能状況：利用可能 * 使用方法：リクエストの`tools`に`web_search`ツールを追加します。`max_uses`、ドメインリスト、`user_location`などの設定はそのツールに指定します。 | ステータス | クラウドプラットフォーム | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 利用可能 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ja/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/ja/build-with-claude/claude-in-microsoft-foundry) | | 利用可能1 | [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ja/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry (hosted on Azure)](https://platform.claude.com/docs/ja/build-with-claude/claude-in-microsoft-foundry) | 1. 動的フィルタリングなしの基本的なウェブ検索ツール（`web_search_20250305`）のみです。 #### [Managed Agents](https://platform.claude.com/docs/ja/managed-agents/overview) * 利用可能状況：利用可能 * 使用方法：エージェントのツールセットの一部で、ツールセットを追加するとデフォルトで有効になります。ドメインリストと`user_location`はツールセットの`web_search`エントリに指定します。`max_uses`、`citations`、`cache_control`は使用できません。 | ステータス | クラウドプラットフォーム | | ----- | ------------------------------------------------------------------------------------------------------------------ | | 利用可能 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws) | ### データの取り扱い [データの取り扱いの概要](https://platform.claude.com/docs/ja/manage-claude/api-and-data-retention#feature-eligibility) | 項目 | ゼロデータ保持 | HIPAA | | ----- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | ステータス | 対象（[対象モデル](https://platform.claude.com/docs/ja/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)を除く） | 対象 | | 詳細 | リアルタイムのウェブ検索結果がAPIレスポンスで返されます。ウェブ検索の動的フィルタリングは、ZDRまたはHIPAAの適格対象ではありません。 | ウェブ検索の動的フィルタリングは、ZDRまたはHIPAAの適格対象ではありません。 | 対象エンドポイント： * `/v1/messages` `web_search`ツールを使用する場合