--- title: 웹 검색 도구 url: https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool description: 인용된 출처, 선택적 동적 필터링, 도메인 제어 기능과 함께 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-2 - claude-mythos-5-2 - 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`은 지원되지 않습니다. 웹 검색 도구는 Claude에게 실시간 웹 콘텐츠에 대한 직접적인 접근 권한을 제공하여, 지식 컷오프 이후의 최신 정보로 질문에 답변할 수 있게 합니다. 응답에는 검색 결과에서 가져온 출처에 대한 인용이 포함됩니다. `web_search_20260209` 이상 버전에서는 Claude가 검색 결과가 “context window”(컨텍스트 윈도우)에 도달하기 전에 이를 필터링하는 코드를 작성하고 실행할 수 있으며(**동적 필터링**), 관련 있는 정보만 유지합니다. 동적 필터링은 Claude 4.6 이상 모델과 [Claude Mythos Preview](https://anthropic.com/glasswing)에서 사용할 수 있습니다. 웹 검색 도구는 세 가지 버전으로 제공됩니다: * `web_search_20250305`: 기본 웹 검색 * `web_search_20260209`: [동적 필터링](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool#dynamic-filtering) 추가 * `web_search_20260318`: 에이전트 워크플로를 위한 [응답 포함](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool#response-inclusion) 제어 추가 이 페이지의 예제는 기본 검색에 `web_search_20250305`를, 동적 필터링에 `web_search_20260318`을 사용합니다. [Claude Mythos Preview](https://anthropic.com/glasswing)의 경우, 웹 검색은 Claude API, Claude Models on Google Cloud (Google managed), Microsoft Foundry에서 지원됩니다. 웹 검색의 “Zero Data Retention”(제로 데이터 보존) 적격성 및 관련 `allowed_callers` 구성에 대해서는 [서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers)를 참조하세요. 모델 지원에 대해서는 [도구 레퍼런스](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference)를 참조하세요. 요청을 보내기 전에 모델이 웹 검색을 허용하는지 확인하려면 Models API에서 해당 모델의 `capabilities.server_tools.web_search.supported` 값을 읽으세요. [Models API 사용하기](https://platform.claude.com/docs/ko/models/overview#using-the-models-api)에서 이 필드를 설명합니다. ## 웹 검색 작동 방식 API 요청에 웹 검색 도구를 추가하면: 1. Claude가 프롬프트를 기반으로 언제 검색할지 결정합니다. 2. API가 검색을 실행하고 Claude에게 결과를 제공합니다. 이 과정은 단일 요청 내에서 여러 번 반복될 수 있습니다. 3. 턴이 끝나면 Claude가 인용된 출처와 함께 최종 응답을 제공합니다. ### Claude가 검색하는 경우 Claude는 요청이 최신이거나, 변화하거나, 학습 데이터 외부에 있는 정보에 의존할 때 검색합니다: * 최근 사건, 뉴스 또는 발표 * 현재 가격, 요율, 점수 또는 통계 * 변경되었을 수 있는 특정 조직, 인물 또는 제품에 대한 정보 * 검색하거나 무언가를 찾아보라는 명시적인 요청 Claude는 요청이 안정적인 지식에 기반할 때 검색하지 않고 직접 답변합니다: * 확립된 사실, 수학, 과학 기초 또는 코딩 개념 * 창작 글쓰기 또는 브레인스토밍 * 대화에서 이미 제공된 콘텐츠의 분석 * 대화형 턴과 인사 검색 실행 여부는 “system prompt”(시스템 프롬프트)를 통해 조정할 수 있습니다: Claude가 더 적극적으로 검색하도록 하거나 직접 답변하는 것을 선호하도록 유도할 수 있습니다. 한도를 강제하려면 [`max_uses`](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool#max-uses)를 사용하여 한 턴의 검색 횟수를 제한하세요. ### 동적 필터링 기본 웹 검색에서는 모든 검색 결과가 Claude의 컨텍스트 윈도우에 로드되며, 그 중 상당 부분은 요청과 관련이 없을 수 있습니다. `web_search_20260209` 이상에서는 대신 Claude가 먼저 결과를 필터링하는 코드를 작성하고 실행하므로, 관련 있는 콘텐츠만 컨텍스트 윈도우에 도달합니다. 이를 통해 검색이 많은 요청에서 토큰 사용량이 줄어듭니다. 동적 필터링은 [코드 실행](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool) 내부에서 웹 검색을 실행합니다: `web_search_20260209` 이상에서는 도구의 `allowed_callers` 필드가 기본적으로 `["code_execution_20260120"]`으로 설정되며, 동적 필터링이 실행될 때 API가 요청에 필요한 코드 실행을 자동으로 프로비저닝합니다. 코드 실행 도구를 직접 `tools`에 추가할 필요가 없습니다. 이 방식으로 이루어지는 코드 실행 호출에는 표준 토큰 비용 외에 추가 요금이 없습니다. 동적 필터링 없이 웹 검색을 직접 호출하려면 `allowed_callers: ["direct"]`를 설정하세요. 프로그래매틱 도구 호출을 지원하지 않는 모델에는 이 설정이 필요합니다. 이 설정이 없으면 API는 이를 설정하라고 알려주는 400 오류를 반환합니다. 웹 검색 도구(동적 필터링 포함 및 미포함)는 Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry)에서 사용할 수 있습니다. Microsoft Foundry에서 [Azure에 호스팅된](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure) 배포는 기본 웹 검색 도구(`web_search_20250305`, 동적 필터링 없음)만 지원합니다. Anthropic에 호스팅된 배포는 모든 버전을 지원합니다. Claude Models on Google Cloud (Google managed)에서는 기본 웹 검색 도구(동적 필터링 없음)만 사용할 수 있습니다. 다음 예제는 `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 ``` ## 웹 검색 사용 방법 관리자가 [Claude Console](https://platform.claude.com/settings/capabilities)에서 비활성화하지 않는 한 조직에 웹 검색이 활성화되어 있으며, 관리자는 해당 위치에서 검색 대상 도메인을 제한할 수도 있습니다. 비활성화된 경우, 도구를 포함하는 Messages API 요청은 검색 결과 내부의 [오류 코드](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool#errors)가 아니라 웹 검색이 활성화되지 않았다는 400 `invalid_request_error`로 실패합니다. Claude Managed Agents 세션에서 조직의 웹 검색 설정이 어떻게 적용되는지는 [웹 검색 및 웹 가져오기 도메인 제한](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions)을 참조하세요. API 요청에 웹 검색 도구를 제공하세요: ```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 ``` ## 도구 정의 웹 검색 도구는 다음 매개변수를 지원합니다: ```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" } } ``` 모든 웹 검색 도구 버전은 `allowed_callers`를 허용하며, 이는 Claude가 웹 검색을 직접 호출할지 아니면 [동적 필터링](https://platform.claude.com/docs/ko/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/ko/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers)를 참조하세요. `web_search_20260318` 이상은 [`response_inclusion`](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool#response-inclusion)도 허용합니다. ### 최대 사용 횟수 `max_uses` 매개변수는 단일 턴에서 수행되는 검색 횟수를 제한합니다. 단일 사실 쿼리는 일반적으로 1\~3회의 검색을 사용하며, 비교 조사나 여러 개체에 대한 조사는 10회 이상을 사용할 수 있습니다. 실패한 검색도 한도에 포함됩니다. Claude가 허용된 횟수보다 더 많이 웹 검색을 직접 호출하면 `web_search_tool_result`는 `max_uses_exceeded` 오류 코드를 가진 오류가 됩니다. Claude가 허용된 횟수보다 더 많이 코드 실행에서 웹 검색을 호출하면 코드 실행이 오류와 함께 종료됩니다. 한 턴은 여러 요청에 걸쳐 이어질 수 있습니다. 요청이 [`pause_turn`](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn) 이후 재개되거나 마지막 메시지에 `tool_result` 블록만 포함된 경우, 해당 요청은 턴을 이어갑니다. 해당 턴의 이전 요청에서 수행된 검색은 한도에 포함되지만, Claude가 [동적 필터링](https://platform.claude.com/docs/ko/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/ko/agents-and-tools/tool-use/server-tools#domain-filtering)을 참조하세요. [Claude Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview)에서는 에이전트 도구 세트의 `web_search` 항목에 이러한 필드를 설정하세요. [웹 검색 및 웹 가져오기 도메인 제한](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions)을 참조하세요. ### 현지화 `user_location` 매개변수를 사용하면 사용자의 위치를 기반으로 검색 결과를 현지화할 수 있습니다. `city`, `region`, `country`, `timezone` 중 최소 하나를 제공하세요. * `type`: 위치 유형(반드시 `approximate`여야 함) * `city`: 도시 이름 * `region`: 지역 또는 주 * `country`: 두 글자 [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`을 허용합니다. [웹 도구 설정](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions#settings)을 참조하세요. ### 응답 포함 `web_search_20260318` 이상이 필요합니다. `response_inclusion` 매개변수는 같은 응답에서 완료된 [코드 실행](https://platform.claude.com/docs/ko/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/ko/agents-and-tools/tool-use/web-search-tool#dynamic-filtering)을 통해 실행되면 응답에는 [코드 실행 도구](https://platform.claude.com/docs/ko/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_search_result_location`에는 다음이 포함됩니다: * `url`: 인용된 출처의 URL * `title`: 인용된 출처의 제목 * `encrypted_index`: 멀티턴 대화를 위해 다시 전달해야 하는 참조 * `cited_text`: 인용된 콘텐츠의 최대 150자 웹 검색 인용 필드인 `cited_text`, `title`, `url`은 입력 또는 출력 토큰 사용량에 포함되지 않습니다. API 출력을 최종 사용자에게 직접 표시할 때는 원본 출처에 대한 인용이 반드시 포함되어야 합니다. 최종 사용자에게 표시하기 전에 API 출력을 재처리하거나 자체 자료와 결합하는 등 수정하는 경우, 법무팀과의 협의를 바탕으로 적절하게 인용을 표시하세요. ### 오류 웹 검색 도구에 오류(예: “rate limit”(속도 제한) 도달)가 발생해도 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`: 최대 웹 검색 도구 사용 횟수 초과 * `query_too_long`: 쿼리가 최대 길이를 초과함 * `request_too_large`: 검색 요청이 너무 큼(일반적으로 긴 도메인 필터 목록 때문) * `unavailable`: 내부 오류 발생 ### `pause_turn` 중지 사유 API는 오래 실행되는 검색 턴을 일시 중지하고 `stop_reason: "pause_turn"`을 반환할 수 있습니다. 계속하려면 일시 중지된 어시스턴트 메시지를 변경 없이 새 요청으로 다시 전송하세요. Claude가 같은 병렬 도구 호출 그룹에서 웹 검색과 클라이언트 도구 중 하나를 함께 호출하면, API는 대신 `stop_reason: "tool_use"`를 반환하고 아직 검색을 실행하지 않습니다. 계속하려면 클라이언트 도구 결과를 반환하세요. 그러면 API가 다음 요청에서 검색을 실행합니다. [한 턴에서 서버 도구와 클라이언트 도구 혼합하기](https://platform.claude.com/docs/ko/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/ko/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn)을 참조하세요. ## 프롬프트 캐싱 턴 간에 도구 정의를 캐시하려면 [프롬프트 캐싱을 사용한 도구 사용](https://platform.claude.com/docs/ko/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) ``` ## 배치 요청 [Message Batches API](https://platform.claude.com/docs/ko/build-with-claude/batch-processing)에 웹 검색 도구를 포함할 수 있습니다. Message Batches API를 통한 웹 검색 도구 호출은 일반 Messages API 요청의 호출과 동일한 가격이 책정됩니다. 공유 용량을 보호하기 위해 Batches API는 조직별로 웹 검색 요청을 제한하므로, 검색이 많은 대규모 배치는 완료하는 데 더 오래 걸릴 수 있습니다. 조직의 웹 검색 속도 제한은 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 USD**에 이용할 수 있으며, 검색으로 생성된 콘텐츠에 대해서는 표준 토큰 비용이 추가로 부과됩니다. 대화 전반에 걸쳐 검색된 웹 검색 결과는 단일 턴 동안 실행되는 검색 반복과 이후의 대화 턴 모두에서 입력 토큰으로 계산됩니다. 각 웹 검색은 반환된 결과 수에 관계없이 1회 사용으로 계산됩니다. 오류로 실패한 웹 검색에 대해서는 요금이 청구되지 않습니다. ## 다음 단계 특정 URL에서 콘텐츠를 가져와 읽어 실시간 웹 콘텐츠로 Claude의 컨텍스트를 보강합니다. Anthropic이 실행하는 도구로 작업합니다: `server_tool_use` 블록, `pause_turn` 연속 처리, 도메인 필터링. Anthropic 제공 도구 디렉터리 및 선택적 도구 정의 속성에 대한 레퍼런스입니다. ## 제공 여부 웹 검색 도구은(는) 모든 모델에서 사용 가능 상태이며 제로 데이터 보존 및 HIPAA 대비에 적격합니다. ### API 지원 #### [Messages API](https://platform.claude.com/docs/ko/build-with-claude/working-with-messages) * 제공 여부: 사용 가능 * 사용법: 요청의 `tools`에 `web_search` 도구를 추가하세요. `max_uses`, 도메인 목록, `user_location` 같은 설정은 해당 도구에 지정합니다. | 상태 | 클라우드 플랫폼 | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 사용 가능 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry) | | 사용 가능1 | [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry (hosted on Azure)](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry) | 1. 동적 필터링이 없는 기본 웹 검색 도구(`web_search_20250305`)만 지원합니다. #### [Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview) * 제공 여부: 사용 가능 * 사용법: 에이전트 도구 세트의 일부이며, 도구 세트를 추가하면 기본적으로 켜집니다. 도메인 목록과 `user_location`은 도구 세트의 `web_search` 항목에 지정하며, `max_uses`, `citations`, `cache_control`은 사용할 수 없습니다. | 상태 | 클라우드 플랫폼 | | ----- | ------------------------------------------------------------------------------------------------------------------ | | 사용 가능 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws) | ### 데이터 처리 [데이터 처리 개요](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#feature-eligibility) | 항목 | 제로 데이터 보존 | HIPAA | | ----- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | 상태 | 적격([적용 모델](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#model-specific-data-retention-requirements) 제외) | 적격 | | 세부 정보 | 실시간 웹 검색 결과가 API 응답으로 반환됩니다. 웹 검색의 동적 필터링은 ZDR 또는 HIPAA 적격 대상이 아닙니다. | 웹 검색의 동적 필터링은 ZDR 또는 HIPAA 적격 대상이 아닙니다. | 적용 엔드포인트: * `/v1/messages` `web_search` 도구 사용 시