웹 검색 도구는 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": "How do I update a web app to 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": "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은 입력 또는 출력 토큰 사용량에 포함되지 않습니다.

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

​
오류

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

{
  "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 중지 이유

응답에는 API가 긴 실행 턴을 일시 중지했음을 나타내는 pause_turn 중지 이유가 포함될 수 있습니다. Claude가 턴을 계속할 수 있도록 후속 요청에서 응답을 그대로 다시 제공하거나, 대화를 중단하려면 콘텐츠를 수정할 수 있습니다.

​
프롬프트 캐싱

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

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

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

import anthropic

client = anthropic.Anthropic()

# 웹 검색 및 캐시 중단점이 있는 첫 번째 요청
messages = [
    {
        "role": "user",
        "content": "What's the current weather in San Francisco today?"
    }
]

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": "Should I expect rain later this week?",
    "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"Cache read tokens: {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 요청과 동일한 가격으로 책정됩니다.

​
사용량 및 가격

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

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

웹 검색은 Anthropic API에서 1,000회 검색당 $10, 그리고 검색으로 생성된 콘텐츠에 대한 표준 토큰 비용으로 이용 가능합니다. 대화 전체에서 검색된 웹 검색 결과는 단일 턴 동안 실행된 검색 반복과 후속 대화 턴에서 입력 토큰으로 계산됩니다.

반환된 결과 수에 관계없이 각 웹 검색은 한 번의 사용으로 계산됩니다. 웹 검색 중 오류가 발생하면 웹 검색 비용이 청구되지 않습니다.