웹 검색 도구

웹 검색 도구는 Claude에게 실시간 웹 콘텐츠에 대한 직접적인 접근 권한을 제공하여, 지식 컷오프 이후의 최신 정보로 질문에 답변할 수 있게 합니다. 응답에는 검색 결과에서 가져온 출처에 대한 인용이 포함됩니다.

web_search_20260209 및 이후 버전에서는 Claude가 검색 결과가 컨텍스트 윈도우에 도달하기 전에 이를 필터링하는 코드를 작성하고 실행하여(dynamic filtering, 동적 필터링) 관련 정보만 유지할 수 있습니다. 동적 필터링은 Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6에서 사용할 수 있습니다.

웹 검색 도구는 세 가지 버전으로 제공됩니다:

• web_search_20250305: 기본 웹 검색
• web_search_20260209: 동적 필터링 추가
• web_search_20260318: 에이전트 워크플로를 위한 응답 포함 제어 추가

이 페이지의 예제는 기본 검색에 web_search_20250305를, 동적 필터링에 web_search_20260318을 사용합니다.

웹 검색의 Zero Data Retention 적격성 및 관련 allowed_callers 구성에 대해서는 서버 도구를 참조하세요.

모델 지원에 대해서는 도구 참조를 참조하세요.



웹 검색 작동 방식

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

1. Claude가 프롬프트를 기반으로 언제 검색할지 결정합니다.
2. API가 검색을 실행하고 Claude에게 결과를 제공합니다. 이 과정은 단일 요청 내에서 여러 번 반복될 수 있습니다.
3. 턴이 끝날 때 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 오류를 반환합니다.

다음 예제는 web_search_20260318을 사용합니다:

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_20260318", "name": "web_search"}],
)
print(response)



웹 검색 사용 방법

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.
  // 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 매개변수는 수행되는 검색 횟수를 제한합니다. Claude가 허용된 것보다 더 많은 검색을 시도하면 web_search_tool_result는 max_uses_exceeded 오류 코드가 포함된 오류가 됩니다.

단순한 사실 확인 쿼리는 일반적으로 13회의 검색을 사용하며, 비교 또는 다중 엔터티 리서치는 10회 이상을 사용할 수 있습니다. 지연 시간에 민감한 조회의 경우 max_uses: 3은 거의 잘리지 않으면서 비용을 제한합니다. 리서치 에이전트의 경우 max_uses를 1520으로 설정하거나 아예 생략하세요.



도메인 필터링

allowed_domains 또는 blocked_domains 중 하나만 제공하세요. 요청에 둘 다 포함되면 API는 400 오류를 반환합니다. 항목은 스킴 없이 선택적 경로가 포함된 순수 도메인입니다(예: example.com 또는 example.com/blog).

전체 도메인 필터링 규칙은 서버 도구를 참조하세요.



현지화

user_location 매개변수를 사용하면 사용자의 위치를 기반으로 검색 결과를 현지화할 수 있습니다. city, region, country, timezone 중 하나 이상을 제공하세요.

• type: 위치 유형(approximate여야 함)
• city: 도시 이름
• region: 지역 또는 주
• country: 두 글자 ISO 3166-1 alpha-2 국가 코드. API는 지원되지 않는 국가 코드를 400 오류로 거부합니다.
• timezone: IANA 시간대 ID.



응답 포함

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"
}

이 예제는 직접 검색을 보여줍니다. 검색이 동적 필터링을 통해 실행되면 응답에는 코드 실행 도구의 결과 블록도 포함되며, 중첩된 각 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은 입력 또는 출력 토큰 사용량에 포함되지 않습니다.



오류

웹 검색 도구에서 오류가 발생하면(예: 속도 제한 도달) 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 처리에 대해서는 서버 도구를 참조하세요.



프롬프트 캐싱

턴 간 도구 정의 캐싱에 대해서는 프롬프트 캐싱과 함께 도구 사용을 참조하세요.



스트리밍

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

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회 사용으로 계산됩니다. 웹 검색 중 오류가 발생하면 해당 웹 검색에 대해서는 요금이 청구되지 않습니다.



다음 단계