---
title: 웹 검색 도구
url: https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool
description: 인용된 출처, 선택적 동적 필터링, 도메인 제어 기능과 함께 Claude에게 최신 웹 콘텐츠에 대한 액세스를 제공합니다.
---
"zero data retention"(제로 데이터 보존), 즉 ZDR이 이 기능에 어떻게 적용되는지 알아보려면 [API 및 데이터 보존](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention)을 참조하세요.
웹 검색 도구는 Claude에게 실시간 웹 콘텐츠에 대한 직접적인 액세스를 제공하여, 지식 마감일 이후의 최신 정보로 질문에 답변할 수 있게 합니다. 응답에는 검색 결과에서 가져온 출처에 대한 인용이 포함됩니다.
`web_search_20260209` 및 이후 버전에서는 Claude가 검색 결과가 "context window"(컨텍스트 윈도우)에 도달하기 전에 이를 필터링하는 코드를 작성하고 실행하여(**dynamic filtering**, 동적 필터링) 관련 정보만 유지할 수 있습니다. 동적 필터링은 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, Google Cloud, Microsoft Foundry에서 지원됩니다. Amazon Bedrock 또는 [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws)에서는 Mythos Preview에 대해 웹 검색을 사용할 수 없습니다.
웹 검색의 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`를 사용하여 각 요청의 검색 횟수를 제한하세요.
### 동적 필터링
기본 웹 검색에서는 모든 검색 결과가 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), [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에 호스팅된 배포는 모든 버전을 지원합니다. Google Cloud에서는 기본 웹 검색 도구(동적 필터링 없음)만 사용할 수 있습니다. Amazon Bedrock에서는 웹 검색을 사용할 수 없습니다.
다음 예제는 `web_search_20260318`을 사용합니다:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-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() { Role = Role.User, 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: '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: "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)에서 비활성화하지 않는 한 조직에서 웹 검색이 활성화되어 있으며, 관리자는 이곳에서 검색 대상 도메인을 제한할 수도 있습니다. 비활성화된 경우 도구를 포함한 요청은 검색 결과 내의 [오류 코드](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool#errors)가 아니라, 웹 검색이 활성화되지 않았다는 400 `invalid_request_error`와 함께 실패합니다.
Claude Console의 이러한 조직 수준 설정은 Messages API 요청에만 적용됩니다. [Claude Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview) 세션은 대신 에이전트 도구 세트의 도구별 `allowed_domains` 및 `blocked_domains` 목록을 사용합니다. [웹 검색 및 웹 가져오기 도메인 제한](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions)을 참조하세요. `limited` 네트워킹을 사용하는 클라우드 환경의 세션에서는 환경의 `allowed_hosts`도 `web_search` 및 `web_fetch`에 적용됩니다. [네트워킹](https://platform.claude.com/docs/ko/managed-agents/environments#networking)을 참조하세요. 도구별 목록은 `allowed_hosts`가 허용하는 호스트 범위 내에서 이러한 도구를 추가로 제한합니다.
API 요청에 웹 검색 도구를 제공하세요:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"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 1024 \
--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=1024,
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: 1024,
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 = 1024,
Messages = [new() { Role = Role.User, 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: 1024,
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(1024L)
.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: 1024,
messages: [
['role' => 'user', 'content' => "What's the weather in NYC?"],
],
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: "claude-opus-5-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
}]
)
puts message
```
## 도구 정의
웹 검색 도구는 다음 매개변수를 지원합니다:
```json JSON
{
"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가 웹 검색을 직접 호출할지 아니면 [동적 필터링](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool#dynamic-filtering)을 통해 코드 실행에서 호출할지를 제어합니다. `web_search_20260209` 이상에서는 기본값이 `["direct"]` 대신 `["code_execution_20260120"]`입니다. 구성 방법은 [서버 도구](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` 매개변수는 수행되는 검색 횟수를 제한합니다. Claude가 허용된 것보다 더 많은 검색을 시도하면 `web_search_tool_result`는 `max_uses_exceeded` 오류 코드를 가진 오류가 됩니다.
간단한 사실 쿼리는 일반적으로 1\~3회의 검색을 사용하며, 비교 또는 다중 엔티티 조사는 10회 이상을 사용할 수 있습니다. 값 선택에 대한 지침은 [서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools)를 참조하세요.
### 도메인 필터링
`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` 객체를 허용합니다. 에이전트를 생성하거나 업데이트할 때, 또는 이 설정을 제공하는 세션을 생성하거나 업데이트할 때 API는 지원되지 않는 `country` 코드를 400 오류와 함께 거부합니다. [웹 도구 설정](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` 및 결과 블록 쌍이 응답에서 완전히 제거되어, 원시 검색 콘텐츠를 클라이언트에 다시 전달할 필요가 없는 에이전트 워크플로의 출력 토큰 비용을 줄입니다. 기본값은 `"full"`입니다. 직접 호출의 결과 또는 완료 전에 일시 중지된 코드 실행 호출의 결과는 다음 턴에 다시 보낼 수 있도록 항상 전체로 반환됩니다.
```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 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](https://platform.claude.com/docs/ko/build-with-claude/batch-processing)에 웹 검색 도구를 포함할 수 있습니다. Messages 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**의 요금으로 이용할 수 있으며, 검색으로 생성된 콘텐츠에 대해서는 표준 토큰 비용이 추가됩니다. 대화 전반에 걸쳐 검색된 웹 검색 결과는 단일 턴 동안 실행된 검색 반복과 이후 대화 턴 모두에서 input tokens(입력 토큰)로 계산됩니다.
각 웹 검색은 반환된 결과 수에 관계없이 1회 사용으로 계산됩니다. 웹 검색 중 오류가 발생하면 해당 웹 검색에 대해서는 요금이 청구되지 않습니다.
## 다음 단계
특정 URL에서 콘텐츠를 가져와 읽어 실시간 웹 콘텐츠로 Claude의 컨텍스트를 보강합니다.
Anthropic이 실행하는 도구 작업: server\_tool\_use 블록, pause\_turn 계속, 도메인 필터링.
Anthropic 제공 도구 디렉터리 및 선택적 도구 정의 속성에 대한 레퍼런스.