웹 검색 도구는 Claude에게 실시간 웹 콘텐츠에 대한 직접적인 접근을 제공하여, 지식 컷오프를 넘어선 최신 정보로 질문에 답할 수 있게 합니다. Claude는 답변의 일부로 검색 결과의 출처를 자동으로 인용합니다.

웹 검색 도구에 대한 경험을 공유하려면 피드백 양식을 통해 연락해 주세요.

​
지원되는 모델

웹 검색은 다음에서 사용할 수 있습니다:

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (new) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
웹 검색 작동 방식

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

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

​
웹 검색 사용 방법

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

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "웹 앱을 TypeScript 5.5로 업데이트하는 방법은?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

​
도구 정의

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

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

​
도메인 필터링

도메인 필터를 사용할 때:

  • 도메인에는 HTTP/HTTPS 스키마를 포함하지 않아야 합니다 (https://example.com 대신 example.com 사용)
  • 하위 도메인이 자동으로 포함됩니다 (example.com은 docs.example.com을 포함)
  • 하위 경로가 지원됩니다 (example.com/blog)
  • 동일한 요청에서 allowed_domains 또는 blocked_domains 중 하나만 사용할 수 있습니다.

​
지역화

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

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

​
응답

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

{
  "role": "assistant",
  "content": [
    // 1. Claude의 검색 결정
    {
      "type": "text",
      "text": "Claude Shannon이 언제 태어났는지 검색해보겠습니다."
    },
    // 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": "검색 결과를 바탕으로, ",
      "type": "text"
    },
    // 4. 인용과 함께한 Claude의 응답
    {
      "text": "Claude Shannon은 1916년 4월 30일 미시간주 페토스키에서 태어났습니다",
      "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은 입력 또는 출력 토큰 사용량에 포함되지 않습니다.

최종 사용자에게 웹 결과나 웹 결과에 포함된 정보를 표시할 때, 인라인 인용은 사용자 인터페이스에서 명확하게 보이고 클릭 가능해야 합니다.

​
오류

웹 검색 중 오류가 발생하면 다음 형태의 응답을 받게 됩니다:

{
  "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 중지 이유가 포함될 수 있으며, 이는 API가 장시간 실행되는 턴을 일시 중지했음을 나타냅니다. Claude가 턴을 계속하도록 하려면 응답을 그대로 후속 요청에 제공하거나, 대화를 중단하려면 콘텐츠를 수정할 수 있습니다.

​
프롬프트 캐싱

웹 검색은 프롬프트 캐싱과 함께 작동합니다. 프롬프트 캐싱을 활성화하려면 요청에 최소 하나의 cache_control 중단점을 추가하세요. 시스템은 도구를 실행할 때 마지막 web_search_tool_result 블록까지 자동으로 캐시합니다.

다중 턴 대화의 경우, 캐시된 콘텐츠를 재사용하려면 마지막 web_search_tool_result 블록에 또는 그 이후에 cache_control 중단점을 설정하세요.

예를 들어, 다중 턴 대화에서 웹 검색과 함께 프롬프트 캐싱을 사용하려면:

import anthropic

client = anthropic.Anthropic()

# 웹 검색과 캐시 중단점이 있는 첫 번째 요청
messages = [
    {
        "role": "user",
        "content": "오늘 샌프란시스코의 현재 날씨는 어떤가요?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)

# Claude의 응답을 대화에 추가
messages.append({
    "role": "assistant",
    "content": response1.content
})

# 검색 결과 이후 캐시 중단점이 있는 두 번째 요청
messages.append({
    "role": "user",
    "content": "이번 주 후반에 비가 올 것으로 예상해야 하나요?",
    "cache_control": {"type": "ephemeral"}  # 이 지점까지 캐시
})

response2 = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)
# 두 번째 응답은 캐시된 검색 결과의 혜택을 받으면서도
# 필요한 경우 새로운 검색을 수행할 수 있습니다
print(f"캐시 읽기 토큰: {response2.usage.get('cache_read_input_tokens', 0)}")

​
스트리밍

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

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 Anthropic 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.