웹 검색 도구
웹 검색 도구 (Web search tool)
웹 검색 도구는 Claude에게 실시간 웹 콘텐츠에 대한 직접 접근을 제공해서, 지식 컷오프를 넘어선 최신 정보로 질문에 답할 수 있게 해 줘요. 응답에는 검색 결과에서 가져온 출처에 대한 인용이 포함돼요. 선택적 동적 필터링과 도메인 제어도 지원해요. 이 기능에 ZDR(제로 데이터 보존)이 어떻게 적용되는지는 API와 데이터 보존을 참고하세요.
출처: 문서
본문
웹 검색 도구는 Claude에게 실시간 웹 콘텐츠에 대한 직접 접근을 제공해서, 지식 컷오프를 넘어선 최신 정보로 질문에 답할 수 있게 해 줘요. 응답에는 검색 결과에서 가져온 출처에 대한 인용이 포함돼요.
web_search_20260209 이상 버전에서는 Claude가 검색 결과가 컨텍스트 창에 도달하기 전에 필터링하는 코드를 작성·실행할 수 있어요(동적 필터링). 관련 정보만 남기는 거예요. 동적 필터링은 Claude 4.6 이상 모델과 Claude Mythos Preview에서 사용할 수 있어요.
웹 검색 도구의 세 가지 버전이 있어요:
web_search_20250305: 기본 웹 검색web_search_20260209: 동적 필터링 추가web_search_20260318: 에이전트 워크플로를 위한 응답 포함 제어 추가
이 페이지의 예시는 기본 검색에 web_search_20250305, 동적 필터링에 web_search_20260318을 사용해요.
참고: Claude Mythos Preview의 경우 웹 검색은 Claude API, Google Cloud, Microsoft Foundry에서 지원돼요. Mythos Preview의 Amazon Bedrock이나 Claude Platform on AWS에서는 웹 검색을 사용할 수 없어요.
웹 검색의 ZDR 자격과 관련 allowed_callers 구성은 서버 도구를 참고하세요.
모델 지원은 도구 레퍼런스를 참고하세요.
웹 검색이 동작하는 방식
API 요청에 웹 검색 도구를 추가하면:
- Claude가 프롬프트를 바탕으로 검색할 때를 결정해요.
- API가 검색을 실행하고 Claude에게 결과를 제공해요. 이 과정은 단일 요청 안에서 여러 번 반복될 수 있어요.
- 턴이 끝나면 Claude가 인용된 출처와 함께 최종 응답을 제공해요.
Claude가 언제 검색하는지
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 오류를 반환해요.
참고: 웹 검색 도구(동적 필터링 포함/미포함)는 Claude API, Claude Platform on AWS, Microsoft Foundry에서 사용할 수 있어요. Microsoft Foundry에서 Azure에 호스팅된 배포는 기본 웹 검색 도구만 지원해요(
web_search_20250305, 동적 필터링 없음). Anthropic에 호스팅된 배포는 모든 버전을 지원해요. Google Cloud에서는 기본 웹 검색 도구만(동적 필터링 없이) 사용할 수 있어요. 웹 검색은 Amazon Bedrock에서는 사용할 수 없어요.
다음 예시는 web_search_20260318을 사용해요:
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
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)
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);
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);
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)
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);
}
$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;
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에서 비활성화하지 않는 한 웹 검색은 조직에 대해 활성화되어 있어요. 관리자는 검색할 도메인도 제한할 수 있어요. 비활성화되어 있으면 이 도구를 포함한 요청은 검색 결과 안의 오류 코드 대신, 웹 검색이 활성화되지 않았다고 하는 400
invalid_request_error로 실패해요.
Claude Console의 이러한 조직 수준 설정은 Messages API 요청에만 적용돼요. Claude Managed Agents 세션은 에이전트 도구셋의 도구별 allowed_domains와 blocked_domains 목록만 사용해요. 웹 검색 및 웹 패치 도메인 제한하기를 참고하세요.
API 요청에 웹 검색 도구를 제공하세요:
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}'
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)
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);
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);
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)
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);
}
$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;
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
도구 정의
웹 검색 도구는 다음 매개변수를 지원해요:
{
"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)
max_uses 매개변수는 수행되는 검색 횟수를 제한해요. Claude가 허용된 횟수보다 더 검색을 시도하면 web_search_tool_result는 max_uses_exceeded 오류 코드를 가진 오류가 돼요.
단순한 사실 질의는 보통 1–3회 검색을 사용하고, 비교 또는 다개체 연구는 10회 이상을 사용할 수 있어요. 값을 고르는 지침은 서버 도구를 참고하세요.
도메인 필터링
allowed_domains 또는 blocked_domains를 제공하세요. 둘 다는 안 돼요. 요청에 둘 다 포함되면 API가 400 오류를 반환해요. 항목은 선택적 경로가 있는 베어 도메인입니다(예: example.com 또는 example.com/blog). 스킴은 없어요.
전체 도메인 필터링 규칙은 서버 도구 가이드의 도메인 필터링을 참고하세요.
Claude Managed Agents에서는 에이전트 도구셋의 web_search 항목에 이 필드를 설정하세요. 웹 검색 및 웹 패치 도메인 제한하기를 참고하세요.
지역화 (Localization)
user_location 매개변수로 사용자의 위치에 따라 검색 결과를 지역화할 수 있어요. city, region, country, timezone 중 최소 하나를 제공하세요.
type: 위치 유형(approximate여야 함)city: 도시 이름region: 지역 또는 주country: 두 글자 ISO 3166-1 alpha-2 국가 코드. 지원되지 않는 국가 코드는 API가 400 오류로 거부해요.timezone: IANA 타임존 ID.
Claude Managed Agents에서 에이전트 도구셋의 web_search 항목은 같은 필드를 가진 user_location 객체를 받아들여요. API는 에이전트를 만들거나 업데이트할 때, 또는 설정을 제공하는 세션을 만들거나 업데이트할 때 지원되지 않는 country 코드를 400 오류로 거부해요. 웹 검색 및 웹 패치 도메인 제한하기를 참고하세요.
응답 포함 (Response inclusion)
참고:
web_search_20260318이상이 필요해요.
response_inclusion 매개변수는 같은 턴에서 완료된 코드 실행 호출이 결과를 소비했을 때 검색 결과 블록이 API 응답에 어떻게 나타나는지 제어해요. "response_inclusion": "excluded"를 설정하면 이러한 중첩된 server_tool_use와 결과 블록 쌍을 응답에서 완전히 제거해서, 원시 검색 콘텐츠를 클라이언트에 다시 반향할 필요가 없는 에이전트 워크플로의 출력 토큰 비용을 줄여줘요. 기본값은 "full"이에요. 직접 호출의 결과나 완료 전에 일시 중지된 코드 실행 호출의 결과는 항상 전체로 반환되어 다음 턴에 다시 보낼 수 있어요.
{
"tools": [
{
"type": "web_search_20260318",
"name": "web_search",
"response_inclusion": "excluded"
}
]
}
응답 (Response)
응답 구조 예시예요:
{
"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 필드를 지녀요.
검색 결과 (Search results)
검색 결과는 다음을 포함해요:
url: 소스 페이지의 URLtitle: 소스 페이지의 제목page_age: 사이트가 마지막으로 업데이트된 시기encrypted_content: 다중 턴 대화에서 다시 전달해야 하는 암호화된 콘텐츠
검색 결과를 포함한 대화를 계속하려면 어시스턴트의 콘텐츠 블록을 받은 그대로 다시 보내세요. 각 결과의 encrypted_content를 포함해서요. API는 이후 턴에서 그 콘텐츠를 복호화해서 Claude의 컨텍스트에 검색 결과를 복원해요. encrypted_content가 없거나 수정되면 요청은 400 검증 오류로 실패해요.
인용 (Citations)
인용은 웹 검색에 항상 활성화되어 있고, 각 web_search_result_location은 다음을 포함해요:
url: 인용된 소스의 URLtitle: 인용된 소스의 제목encrypted_index: 다중 턴 대화를 위해 다시 전달해야 하는 참조cited_text: 인용된 콘텐츠의 최대 150자
웹 검색 인용 필드 cited_text, title, url은 입력 또는 출력 토큰 사용에 포함되지 않아요.
참고: API 출력을 최종 사용자에게 직접 표시할 때는 원본 소스에 대한 인용을 포함해야 해요. API 출력을 수정할 때(재처리하거나 당신의 자료와 결합해서 최종 사용자에게 표시하기 전에)는 법무팀과 상의한 대로 적절히 인용을 표시하세요.
오류 (Errors)
웹 검색 도구가 오류를 만나면(속도 제한에 걸리는 등) 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가 같은 병렬 도구 호출 그룹에서 웹 검색과 당신의 클라이언트 도구 중 하나를 호출하면, API는 stop_reason: "tool_use"를 반환하고 아직 검색을 실행하지 않아요. 계속하려면 클라이언트 도구 결과를 반환하면 API가 다음 요청에서 검색을 실행해요. 한 턴에서 서버 도구와 클라이언트 도구 혼합하기를 참고하세요.
서버 측 루프와 pause_turn 처리는 서버 도구 가이드의 서버 측 루프와 pause_turn을 참고하세요.
프롬프트 캐싱
여러 턴에 걸쳐 도구 정의를 캐시하려면 프롬프트 캐싱과 함께하는 도구 사용을 참고하세요.
스트리밍 (Streaming)
스트리밍을 활성화하면 검색 이벤트를 스트림의 일부로 받아요. 검색이 실행되는 동안 일시 정지가 있어요:
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)
배치 요청 (Batch requests)
Messages Batches API에 웹 검색 도구를 포함할 수 있어요. Messages Batches API를 통한 웹 검색 도구 호출은 일반 Messages API 요청과 동일하게 가격이 책정돼요.
공유 용량을 보호하기 위해 Batches API는 조직별로 웹 검색 요청을 제한하므로, 검색이 많은 대규모 배치는 완료하는 데 더 오래 걸릴 수 있어요. 조직의 웹 검색 속도 제한은 Claude Console의 속도 제한 페이지에서 볼 수 있어요. 더 높은 한도를 요청하려면 그 페이지에서 영업팀에 문의하세요.
사용 및 가격 (Usage and pricing)
웹 검색 사용은 토큰 사용에 더해 별도로 청구돼요:
{
"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, 그리고 검색 생성 콘텐츠에 대한 표준 토큰 비용으로 사용할 수 있어요. 대화 전반에 걸쳐 가져온 웹 검색 결과는 입력 토큰으로 계산돼요. 단일 턴 중에 실행된 검색 반복과 이후 대화 턴에서 말이에요.
각 웹 검색은 반환된 결과 수와 무관하게 한 번의 사용으로 계산돼요. 웹 검색 중 오류가 발생하면 웹 검색은 청구되지 않아요.