웹 검색 도구

웹 검색 도구는 Claude에 실시간 웹 콘텐츠에 대한 직접 접근을 제공하여 지식 기한을 넘어선 최신 정보로 질문에 답할 수 있게 합니다. 응답에는 검색 결과에서 도출된 출처에 대한 인용이 포함됩니다.

최신 웹 검색 도구 버전(web_search_20260209)은 Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6에서 동적 필터링을 지원합니다. Claude는 검색 결과가 컨텍스트 윈도우에 도달하기 전에 필터링하기 위해 코드를 작성하고 실행할 수 있으며, 관련 정보만 유지하고 나머지는 버립니다. 이는 토큰 소비를 줄이면서 더 정확한 응답으로 이어집니다. 이전 도구 버전(web_search_20250305)은 동적 필터링 없이 계속 사용 가능합니다.

Claude Mythos Preview의 경우, 웹 검색은 Claude API, Microsoft Foundry, Google Vertex AI에서 지원됩니다. 웹 검색은 Amazon Bedrock의 Mythos Preview에서 사용할 수 없습니다.

Zero Data Retention 적격성 및 allowed_callers 해결 방법은 Server tools를 참조하세요.

모델 지원은 Tool reference를 참조하세요.

웹 검색 작동 방식

API 요청에 웹 검색 도구를 추가하면:

Claude는 프롬프트를 기반으로 검색 시기를 결정합니다.
API가 검색을 실행하고 Claude에 결과를 제공합니다. 이 프로세스는 단일 요청 전체에서 여러 번 반복될 수 있습니다.
턴의 끝에서 Claude는 인용된 출처와 함께 최종 응답을 제공합니다.

동적 필터링

웹 검색은 토큰 집약적인 작업입니다. 기본 웹 검색을 사용하면 Claude는 검색 결과를 컨텍스트로 가져오고, 여러 웹사이트에서 전체 HTML을 가져오고, 답에 도달하기 전에 모든 것을 추론해야 합니다. 종종 이 콘텐츠의 대부분은 관련이 없어서 응답 품질을 저하시킬 수 있습니다.

web_search_20260209 도구 버전을 사용하면 Claude는 쿼리 결과를 후처리하기 위해 코드를 작성하고 실행할 수 있습니다. 전체 HTML 파일을 추론하는 대신 Claude는 검색 결과를 동적으로 필터링하여 컨텍스트에 로드하기 전에 관련된 것만 유지하고 나머지는 버립니다.

동적 필터링은 특히 다음에 효과적입니다:

기술 문서 검색
문헌 검토 및 인용 검증
기술 연구
응답 근거 및 검증

동적 필터링을 사용하려면 code execution tool을 활성화해야 합니다. 개선된 웹 검색 도구는 Claude API 및 Microsoft Azure에서 사용 가능합니다. Google Vertex AI에서는 기본 웹 검색 도구(동적 필터링 없음)를 사용할 수 있습니다.

동적 필터링을 활성화하려면 web_search_20260209 도구 버전을 사용하세요:

웹 검색 사용 방법

조직의 관리자가 Claude Console에서 웹 검색을 활성화해야 합니다.

API 요청에 웹 검색 도구를 제공하세요:

도구 정의

웹 검색 도구는 다음 매개변수를 지원합니다:

JSON

{
  "type": "web_search_20250305",
  "name": "web_search",

  // 선택사항: 요청당 검색 수 제한
  "max_uses": 5,

  // 선택사항: 이 도메인의 결과만 포함
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // 선택사항: 이 도메인의 결과는 절대 포함하지 않음
  "blocked_domains": ["untrustedsource.com"],

  // 선택사항: 검색 결과 지역화
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

Max uses

max_uses 매개변수는 수행된 검색 수를 제한합니다. Claude가 허용된 것보다 더 많은 검색을 시도하면 web_search_tool_result는 max_uses_exceeded 오류 코드가 있는 오류입니다.

도메인 필터링

allowed_domains 및 blocked_domains를 사용한 도메인 필터링은 Server tools를 참조하세요.

지역화

user_location 매개변수를 사용하면 사용자의 위치를 기반으로 검색 결과를 지역화할 수 있습니다.

type: 위치 유형(반드시 approximate이어야 함)
city: 도시 이름
region: 지역 또는 주
country: 국가
timezone: IANA timezone ID.

응답

다음은 응답 구조의 예입니다:

Output

{
  "role": "assistant",
  "content": [
    // 1. Claude의 검색 결정
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. 사용된 검색 쿼리
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. 검색 결과
    {
      "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의 응답
    {
      "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: 소스 페이지의 URL
title: 소스 페이지의 제목
page_age: 사이트가 마지막으로 업데이트된 시간
encrypted_content: 다중 턴 대화에서 인용을 위해 다시 전달해야 하는 암호화된 콘텐츠

인용

인용은 웹 검색에 대해 항상 활성화되며, 각 web_search_result_location에는 다음이 포함됩니다:

url: 인용된 출처의 URL
title: 인용된 출처의 제목
encrypted_index: 다중 턴 대화를 위해 다시 전달해야 하는 참조입니다.
cited_text: 인용된 콘텐츠의 최대 150자

웹 검색 인용 필드 cited_text, title, url은 입력 또는 출력 토큰 사용량에 포함되지 않습니다.

API 출력을 최종 사용자에게 직접 표시할 때는 원본 출처에 대한 인용을 포함해야 합니다. API 출력을 수정하는 경우, 재처리 및/또는 자신의 자료와 결합하여 최종 사용자에게 표시하기 전에 법률 팀과 상담하여 적절하게 인용을 표시하세요.

오류

웹 검색 도구가 오류(예: 속도 제한 도달)를 만나면 Claude API는 여전히 200(성공) 응답을 반환합니다. 오류는 다음 구조를 사용하여 응답 본문 내에서 표현됩니다:

Output

{
  "type": "web_search_tool_result",
  "tool_use_id": "servertoolu_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 중지 이유 후 계속하려면 Server tools를 참조하세요.

프롬프트 캐싱

턴 전체에서 도구 정의를 캐싱하려면 Tool use with prompt caching을 참조하세요.

스트리밍

스트리밍이 활성화되면 스트림의 일부로 검색 이벤트를 받게 됩니다. 검색이 실행되는 동안 일시 중지가 있습니다:

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의 검색 결정

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}

// 검색 쿼리 스트리밍됨
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// 검색 실행 중 일시 중지

// 검색 결과 스트리밍됨
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의 응답(이 예에서는 생략됨)

배치 요청

Messages Batches API에 웹 검색 도구를 포함할 수 있습니다. Messages Batches API를 통한 웹 검색 도구 호출은 일반 Messages API 요청과 동일하게 가격이 책정됩니다.

사용량 및 가격

Web search usage is charged in addition to token usage:

"usage": {
  "input_tokens": 105,
  "output_tokens": 6039,
  "cache_read_input_tokens": 7123,
  "cache_creation_input_tokens": 7345,
  "server_tool_use": {
    "web_search_requests": 1
  }
}

Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

다음 단계

Server tools

Anthropic 실행 도구의 공유 메커니즘입니다.

Tool reference

모든 Anthropic 제공 도구의 디렉토리입니다.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

웹 검색 작동 방식

동적 필터링

웹 검색 사용 방법

도구 정의

Max uses

도메인 필터링

지역화

응답

검색 결과

인용

오류

pause_turn 중지 이유

프롬프트 캐싱

스트리밍

배치 요청

사용량 및 가격

다음 단계

`pause_turn` 중지 이유