Claude Platform Docs
Messages도구

웹 검색 도구

인용된 출처, 선택적 동적 필터링, 도메인 제어 기능과 함께 Claude가 최신 웹 콘텐츠에 접근할 수 있도록 합니다.

제품별로 사용법이 다릅니다

Messages API
요청의 tools에 web_search 도구를 추가하세요. max_uses, 도메인 목록, user_location 같은 설정은 해당 도구에 지정합니다.
Managed Agents
에이전트 도구 세트에서 기본적으로 켜져 있으며, max_uses, citations, cache_control은 지원되지 않습니다.

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

web_search_20260209 이상 버전에서는 Claude가 검색 결과가 “context window”(컨텍스트 윈도우)에 도달하기 전에 이를 필터링하는 코드를 작성하고 실행할 수 있으며(동적 필터링), 관련 있는 정보만 유지합니다. 동적 필터링은 Claude 4.6 이상 모델과 Claude Mythos Preview에서 사용할 수 있습니다.

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

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

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

웹 검색의 “Zero Data Retention”(제로 데이터 보존) 적격성 및 관련 allowed_callers 구성에 대해서는 서버 도구를 참조하세요.

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

요청을 보내기 전에 모델이 웹 검색을 허용하는지 확인하려면 Models API에서 해당 모델의 capabilities.server_tools.web_search.supported 값을 읽으세요. Models API 사용하기에서 이 필드를 설명합니다.

웹 검색 작동 방식

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

  1. Claude가 프롬프트를 기반으로 언제 검색할지 결정합니다.
  2. API가 검색을 실행하고 Claude에게 결과를 제공합니다. 이 과정은 단일 요청 내에서 여러 번 반복될 수 있습니다.
  3. 턴이 끝나면 Claude가 인용된 출처와 함께 최종 응답을 제공합니다.

Claude가 검색하는 경우

Claude는 요청이 최신이거나, 변화하거나, 학습 데이터 외부에 있는 정보에 의존할 때 검색합니다:

  • 최근 사건, 뉴스 또는 발표
  • 현재 가격, 요율, 점수 또는 통계
  • 변경되었을 수 있는 특정 조직, 인물 또는 제품에 대한 정보
  • 검색하거나 무언가를 찾아보라는 명시적인 요청

Claude는 요청이 안정적인 지식에 기반할 때 검색하지 않고 직접 답변합니다:

  • 확립된 사실, 수학, 과학 기초 또는 코딩 개념
  • 창작 글쓰기 또는 브레인스토밍
  • 대화에서 이미 제공된 콘텐츠의 분석
  • 대화형 턴과 인사

검색 실행 여부는 “system prompt”(시스템 프롬프트)를 통해 조정할 수 있습니다: 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-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)

Claude Managed Agents 세션에서 조직의 웹 검색 설정이 어떻게 적용되는지는 웹 검색 및 웹 가져오기 도메인 제한을 참조하세요.

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)

도구 정의

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

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

  // Optional: Limit the number of searches
  "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"]입니다. 구성 방법은 ZDR 및 allowed_callers를 참조하세요. web_search_20260318 이상은 response_inclusion도 허용합니다.

최대 사용 횟수

max_uses 매개변수는 단일 턴에서 수행되는 검색 횟수를 제한합니다. 단일 사실 쿼리는 일반적으로 1~3회의 검색을 사용하며, 비교 조사나 여러 개체에 대한 조사는 10회 이상을 사용할 수 있습니다.

실패한 검색도 한도에 포함됩니다. Claude가 허용된 횟수보다 더 많이 웹 검색을 직접 호출하면 web_search_tool_result는 max_uses_exceeded 오류 코드를 가진 오류가 됩니다. Claude가 허용된 횟수보다 더 많이 코드 실행에서 웹 검색을 호출하면 코드 실행이 오류와 함께 종료됩니다.

한 턴은 여러 요청에 걸쳐 이어질 수 있습니다. 요청이 pause_turn 이후 재개되거나 마지막 메시지에 tool_result 블록만 포함된 경우, 해당 요청은 턴을 이어갑니다. 해당 턴의 이전 요청에서 수행된 검색은 한도에 포함되지만, Claude가 동적 필터링을 통해 코드 실행에서 실행한 검색은 예외입니다.

도메인 필터링

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

전체 도메인 필터링 규칙은 서버 도구 가이드의 도메인 필터링을 참조하세요.

Claude Managed Agents에서는 에이전트 도구 세트의 web_search 항목에 이러한 필드를 설정하세요. 웹 검색 및 웹 가져오기 도메인 제한을 참조하세요.

현지화

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을 허용합니다. 웹 도구 설정을 참조하세요.

응답 포함

response_inclusion 매개변수는 같은 응답에서 완료된 코드 실행 호출이 결과를 소비한 경우, 검색 결과 블록이 API 응답에 어떻게 나타나는지를 제어합니다. 원시 검색 콘텐츠가 필요 없는 에이전트 워크플로의 경우 "response_inclusion": "excluded"를 설정하면 중첩된 server_tool_use 및 결과 블록 쌍이 응답에서 완전히 제거됩니다. Claude는 이러한 블록이 아니라 코드의 출력을 읽으므로 토큰 사용량에는 영향이 없습니다. 기본값은 "full"입니다. 직접 호출의 결과나 완료되기 전에 일시 중지된 코드 실행 호출의 결과는 다음 요청에서 다시 전송할 수 있도록 API가 항상 전체를 반환합니다.

JSON
{
  "tools": [
    {
      "type": "web_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}

응답

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

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

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

오류

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

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가 다음 요청에서 검색을 실행합니다. 한 턴에서 서버 도구와 클라이언트 도구 혼합하기를 참조하세요.

서버 측 루프와 pause_turn 처리에 대해서는 서버 도구 가이드의 서버 측 루프와 pause_turn을 참조하세요.

프롬프트 캐싱

턴 간에 도구 정의를 캐시하려면 프롬프트 캐싱을 사용한 도구 사용을 참조하세요.

스트리밍

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

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 runs

// 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)

배치 요청

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

공유 용량을 보호하기 위해 Batches API는 조직별로 웹 검색 요청을 제한하므로, 검색이 많은 대규모 배치는 완료하는 데 더 오래 걸릴 수 있습니다. 조직의 웹 검색 속도 제한은 Claude Console의 속도 제한 페이지에서 확인할 수 있습니다. 더 높은 한도를 요청하려면 해당 페이지에서 영업팀에 문의하세요.

사용량 및 가격

웹 검색 사용량은 토큰 사용량에 추가로 청구됩니다:

{
  "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 USD에 이용할 수 있으며, 검색으로 생성된 콘텐츠에 대해서는 표준 토큰 비용이 추가로 부과됩니다. 대화 전반에 걸쳐 검색된 웹 검색 결과는 단일 턴 동안 실행되는 검색 반복과 이후의 대화 턴 모두에서 입력 토큰으로 계산됩니다.

각 웹 검색은 반환된 결과 수에 관계없이 1회 사용으로 계산됩니다. 오류로 실패한 웹 검색에 대해서는 요금이 청구되지 않습니다.

다음 단계

웹 가져오기 도구

특정 URL에서 콘텐츠를 가져와 읽어 실시간 웹 콘텐츠로 Claude의 컨텍스트를 보강합니다.

서버 도구

Anthropic이 실행하는 도구로 작업합니다: server_tool_use 블록, pause_turn 연속 처리, 도메인 필터링.

도구 레퍼런스

Anthropic 제공 도구 디렉터리 및 선택적 도구 정의 속성에 대한 레퍼런스입니다.

제공 여부

웹 검색 도구
API
  • Messages API
  • Managed Agents
모델
  • 모든 모델

데이터 처리

데이터 처리 개요

적용 엔드포인트

  • /v1/messages web_search 도구 사용 시
제로 데이터 보존적격

적용 모델 제외

실시간 웹 검색 결과가 API 응답으로 반환됩니다. 웹 검색의 동적 필터링은 ZDR 또는 HIPAA 적격 대상이 아닙니다.

HIPAA적격

웹 검색의 동적 필터링은 ZDR 또는 HIPAA 적격 대상이 아닙니다.

이 페이지가 도움이 되었나요?