웹 검색 도구는 Claude에게 실시간 웹 콘텐츠에 대한 직접 액세스를 제공하여, 지식 컷오프 이후의 최신 정보로 질문에 답변할 수 있게 합니다. 응답에는 검색 결과에서 가져온 출처에 대한 인용이 포함됩니다.
최신 웹 검색 도구 버전(web_search_20260318)은 Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6에서 동적 필터링을 지원합니다. Claude는 검색 결과가 컨텍스트 윈도우에 도달하기 전에 코드를 작성하고 실행하여 결과를 필터링할 수 있으며, 관련 정보만 유지하고 나머지는 폐기합니다. 이를 통해 토큰 소비를 줄이면서 더 정확한 응답을 얻을 수 있습니다. web_search_20260318은 또한 에이전트 워크플로를 위한 응답 포함 제어 기능을 추가합니다. 이전 버전(동적 필터링만 지원하는 web_search_20260209, 기본 검색용 web_search_20250305)도 계속 사용할 수 있습니다.
Claude Mythos Preview의 경우, 웹 검색은 Claude API, Microsoft Foundry, Vertex AI에서 지원됩니다. Amazon Bedrock 또는 Claude Platform on AWS에서는 Mythos Preview에 대한 웹 검색을 사용할 수 없습니다.
Zero Data Retention 적격성 및 allowed_callers 해결 방법에 대해서는 서버 도구를 참조하세요.
모델 지원에 대해서는 도구 참조를 참조하세요.
API 요청에 웹 검색 도구를 추가하면:
Claude는 요청이 최신 정보, 변경되는 정보 또는 학습 데이터 외부의 정보에 의존할 때 검색합니다:
Claude는 요청이 안정적인 지식에 기반할 때 검색 없이 직접 답변합니다:
트리거링은 시스템 프롬프트를 통해 조정할 수 있습니다. Claude가 더 적극적으로 검색하도록 유도하거나 직접 답변하는 것을 선호하도록 할 수 있습니다. 엄격한 제약이 필요한 경우 max_uses를 사용하여 각 요청의 검색 횟수를 제한하세요.
웹 검색은 토큰을 많이 사용하는 작업입니다. 기본 웹 검색에서는 Claude가 검색 결과를 컨텍스트로 가져오고, 여러 웹사이트에서 전체 HTML을 가져온 다음, 답변에 도달하기 전에 이 모든 것을 추론해야 합니다. 이 콘텐츠의 상당 부분이 관련이 없는 경우가 많으며, 이는 응답 품질을 저하시킬 수 있습니다.
web_search_20260209 이상 버전에서는 Claude가 코드를 작성하고 실행하여 쿼리 결과를 후처리할 수 있습니다. 전체 HTML 파일을 추론하는 대신, Claude는 검색 결과를 컨텍스트에 로드하기 전에 동적으로 필터링하여 관련 있는 것만 유지하고 나머지는 폐기합니다.
동적 필터링은 다음과 같은 경우에 특히 효과적입니다:
동적 필터링을 사용하려면 코드 실행 도구가 활성화되어 있어야 합니다. 웹 검색 도구(동적 필터링 포함 및 미포함)는 Claude API, Claude Platform on AWS, Microsoft Foundry에서 사용할 수 있습니다. Vertex AI에서는 기본 웹 검색 도구(동적 필터링 미포함)만 사용할 수 있습니다. Amazon Bedrock에서는 웹 검색을 사용할 수 없습니다.
동적 필터링을 활성화하려면 web_search_20260209 또는 이후 버전을 사용하세요. 다음 예제는 web_search_20260209를 사용합니다:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
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_20260209", "name": "web_search"}],
)
print(response)조직의 관리자가 Claude Console에서 웹 검색을 활성화해야 합니다.
API 요청에 웹 검색 도구를 제공하세요:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
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
"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"
}
}max_uses 매개변수는 수행되는 검색 횟수를 제한합니다. Claude가 허용된 것보다 더 많은 검색을 시도하면 web_search_tool_result는 max_uses_exceeded 오류 코드와 함께 오류가 됩니다.
간단한 사실 쿼리는 일반적으로 13회 검색을 사용하며, 비교 또는 다중 엔터티 연구는 10회 이상을 사용할 수 있습니다. 지연 시간에 민감한 조회의 경우 20으로 설정하거나 완전히 생략하세요.max_uses: 3은 비용을 제한하면서도 거의 잘리지 않습니다. 연구 에이전트의 경우 max_uses를 15
allowed_domains 및 blocked_domains를 사용한 도메인 필터링에 대해서는 서버 도구를 참조하세요.
user_location 매개변수를 사용하면 사용자의 위치를 기반으로 검색 결과를 지역화할 수 있습니다.
type: 위치 유형(approximate여야 함)city: 도시 이름region: 지역 또는 주country: 국가timezone: IANA 시간대 IDweb_search_20260318 이상이 필요합니다.
response_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"
}검색 결과에는 다음이 포함됩니다:
url: 소스 페이지의 URLtitle: 소스 페이지의 제목page_age: 사이트가 마지막으로 업데이트된 시점encrypted_content: 인용을 위해 멀티턴 대화에서 다시 전달해야 하는 암호화된 콘텐츠웹 검색에서는 인용이 항상 활성화되며, 각 web_search_result_location에는 다음이 포함됩니다:
url: 인용된 소스의 URLtitle: 인용된 소스의 제목encrypted_index: 멀티턴 대화를 위해 다시 전달해야 하는 참조cited_text: 인용된 콘텐츠의 최대 150자웹 검색 인용 필드인 cited_text, title, url은 입력 또는 출력 토큰 사용량에 포함되지 않습니다.
API 출력을 최종 사용자에게 직접 표시할 때는 원본 소스에 대한 인용을 포함해야 합니다. API 출력을 수정하는 경우(최종 사용자에게 표시하기 전에 재처리하거나 자체 자료와 결합하는 경우 포함), 법무팀과의 상담을 바탕으로 적절하게 인용을 표시하세요.
웹 검색 도구에서 오류가 발생하면(예: 속도 제한 도달), 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"
}
}가능한 오류 코드는 다음과 같습니다:
too_many_requests: 속도 제한 초과invalid_input: 잘못된 검색 쿼리 매개변수max_uses_exceeded: 최대 웹 검색 도구 사용 횟수 초과query_too_long: 쿼리가 최대 길이를 초과함unavailable: 내부 오류 발생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의 Limits 페이지에서 조직의 웹 검색 속도 제한을 확인할 수 있으며, 해당 페이지에서 영업팀에 문의하여 더 높은 제한을 요청할 수 있습니다. 일반적인 배치 웹 검색 워크로드에는 현재 웹 데이터로 레코드 보강, 대규모 엔터티 목록 조사, 실시간 소스를 기준으로 콘텐츠 코퍼스의 근거 제공 또는 확인 등이 포함됩니다.
웹 검색 사용량은 토큰 사용량에 추가로 요금이 부과됩니다:
{
"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회 사용으로 계산됩니다. 웹 검색 중 오류가 발생하면 해당 웹 검색에 대해서는 요금이 청구되지 않습니다.
Was this page helpful?