Claude 웹 검색 API 사용법

Anthropic의 Claude와 같은 대규모 언어 모델(LLM)은 우리가 정보 및 기술과 상호 작용하는 방식을 변화시켰습니다. 텍스트를 이해하고 생성하며 추론하는 LLM의 능력은 수많은 애플리케이션의 문을 열었습니다. 그러나 많은 LLM의 일반적인 한계는 정적 훈련 데이터에 의존한다는 점입니다. 이는 LLM의 지식이 특정 시점에 고정되어 있음을 의미합니다. 정보가 시시각각 변하는 세상에서 이러한 "지식 차단"은 상당한 장애물이 될 수 있습니다. 여기에 Claude의 웹 검색 API가 등장합니다. 이 강력한 도구는 Claude에게 인터넷에서 실시간 정보를 직접 액세스하고 응답에 통합할 수 있는 능력을 부여함으로써 이러한 격차를 해소하도록 설계되었습니다.

이 글에서는 Claude의 웹 검색 API를 이해하고 활용하는 방법에 대한 포괄적인 가이드를 제공합니다. 우리는 이 API의 중요성, 작동 방식, 실제 구현 단계, 고급 기능, 매력적인 사용 사례, 그리고 단순히 지능적일 뿐만 아니라 최신 정보와 문맥을 인지하는 차세대 AI 애플리케이션을 구축하려는 개발자를 위한 모범 사례를 살펴볼 것입니다.

💡

아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하시나요?

최대 생산성으로 개발팀이 함께 작업할 수 있는 통합 올인원 플랫폼을 원하시나요?

Apidog는 귀하의 모든 요구 사항을 충족하며, 훨씬 더 저렴한 가격으로 Postman을 대체합니다!

버튼

Claude 웹 검색 API: 간단히 살펴보기

디지털 세계는 끊임없이 변화하고 있습니다. 뉴스가 터지고, 시장 트렌드가 바뀌고, 과학적 발견이 발표되며, 소프트웨어 문서는 지속적으로 업데이트됩니다. 이러한 변화 이전에 생성된 데이터셋으로 훈련된 LLM은 의도치 않게 오래되거나 불완전한 정보를 제공하여, 최신 정확도가 요구되는 시나리오에서 유용성이 제한될 수 있습니다.

실시간 웹 액세스는 이러한 근본적인 한계를 여러 가지 주요 방식으로 해결합니다.

지식 차단 극복: 가장 분명한 이점은 LLM의 마지막 훈련 주기 이후에 생성되거나 업데이트된 정보에 액세스할 수 있다는 것입니다. 이는 Claude가 최근 사건, 시사 문제 또는 어떤 분야의 최신 개발에 대한 질문에 답할 수 있음을 의미합니다.
정확성 및 관련성 향상: 실시간 데이터를 가져옴으로써 LLM은 최신 정보뿐만 아니라 사용자의 즉각적인 문맥과 더 관련 있는 답변을 제공할 수 있습니다. 현재 날씨, 최신 주가, 속보 등 정보는 시의적절하고 실행 가능합니다.
동적 문제 해결: 많은 실제 문제는 본질적으로 동적인 정보가 필요합니다. 예를 들어, 소프트웨어 문제 해결에는 최신 버그 보고서나 포럼 토론이 필요할 수 있으며, 시장 조사에는 현재 경쟁사 데이터가 필요합니다. 웹 검색은 LLM이 이러한 동적 문제를 보다 효과적으로 해결할 수 있도록 지원합니다.
AI 애플리케이션의 새로운 지평: 실시간 데이터에 액세스하면 수많은 새로운 애플리케이션이 가능해집니다. 실시간 스포츠 점수를 제공할 수 있는 AI 비서, 현재 시장 움직임에 기반한 통찰력을 제공하는 금융 자문가, 최신 학술 논문을 종합할 수 있는 연구 도구를 상상해 보세요.
검증 가능성을 통한 신뢰 구축: LLM이 실시간 웹에서 출처를 인용할 수 있을 때 사용자 신뢰가 크게 향상됩니다. 사용자는 정보를 직접 확인할 수 있어 AI 응답의 투명성과 신뢰를 높일 수 있습니다.

Claude의 웹 검색 API는 이러한 요구에 대한 Anthropic의 답변이며, 개발자가 인터넷의 방대하고 끊임없이 진화하는 지식 기반을 활용하는 애플리케이션을 구축할 수 있는 강력하고 통합된 솔루션을 제공합니다.

Claude 웹 검색 API 사용 방법

본질적으로 Claude용 웹 검색 API는 Claude가 사용자의 쿼리가 외부의 최신 정보로부터 이점을 얻을 수 있다고 판단할 때 사용하기로 결정할 수 있는 "도구"입니다. 이것은 단순한 키워드 검색이 아닙니다. Claude는 정교한 추론 능력을 활용하여 언제, 어떻게 효과적으로 검색할지 이해합니다.

지원되는 Claude 모델:

출시 및 후속 업데이트 기준으로, 웹 검색 기능은 다음을 포함한 여러 강력한 Claude 모델에서 사용할 수 있습니다.

Claude 3.7 Sonnet (claude-3-7-sonnet-20250219 또는 claude-3-7-sonnet-latest)
업그레이드된 Claude 3.5 Sonnet (claude-3-5-sonnet-latest)
Claude 3.5 Haiku (claude-3-5-haiku-latest)

지원되는 모델의 최신 목록은 항상 Anthropic 공식 문서를 참조하세요.

Claude 웹 검색 API 작동 방식

지능형 호출: 사용자가 웹 검색 도구가 활성화된 지원되는 Claude 모델에 프롬프트를 보내면, Claude는 먼저 쿼리를 분석합니다. 주어진 쿼리에 대해 내부 지식이 불충분하거나 오래되었을 수 있다고 판단하면 웹 검색을 시작하기로 결정합니다.
쿼리 생성 및 실행: Claude는 사용자의 요구에 대한 이해를 바탕으로 대상 검색 쿼리를 생성합니다. 그런 다음 Anthropic API는 이 검색을 실행하여 관련 웹 페이지를 가져옵니다.
에이전트 검색 및 개선: Claude는 "에이전트 방식"으로 작동할 수 있습니다. 즉, 여러 단계의 검색을 수행할 수 있습니다. 초기 검색 결과를 사용하여 후속 쿼리를 알리고 개선하여 가벼운 조사를 수행하고 더 포괄적인 정보를 수집할 수 있습니다. 이 반복 프로세스는 Claude가 충분한 정보가 있다고 판단하거나 사전 설정된 한계(예: max_uses)에 도달할 때까지 계속됩니다.
분석 및 종합: Claude는 검색된 결과를 분석하고 주요 정보를 추출하여 일관되고 포괄적인 답변을 구성합니다.
인용된 응답: 중요하게도, Claude는 최종 응답에 원본 자료에 대한 인용을 함께 제공합니다. 이를 통해 사용자는 정보를 확인하고 출처를 이해하여 투명성과 신뢰를 높일 수 있습니다.

이 전체 프로세스는 개발자에게 원활하도록 설계되었습니다. 개발자는 자체 웹 스크래핑 및 검색 인프라를 구축하고 관리하는 대신 단순히 도구를 활성화하고 Claude가 실시간 정보 검색의 복잡성을 처리하도록 할 수 있습니다.

Claude 웹 검색 API 가격은 어떻게 되나요?

Claude의 웹 검색 API 가격 책정에 대해 Anthropic은 간단한 모델을 가지고 있습니다. 웹 검색 도구 자체 사용은 수행된 검색 1,000회당 10달러의 요금이 부과됩니다. 이 비용은 도구에 의해 실행된 검색 작업에만 해당된다는 점에 유의하는 것이 중요합니다.

이 수수료는 요청 처리에 관련된 표준 비용과는 별개이며 추가됩니다. 표준 비용에는 Claude 모델이 쿼리를 이해하고, 검색 결과를 처리하고, 최종 응답을 생성하기 위해 사용한 입력 및 출력 토큰에 대한 일반 요금이 포함됩니다.

Claude 웹 검색 API 사용 방법

Claude 기반 애플리케이션에 웹 검색을 통합하는 것은 몇 가지 간단한 단계를 포함합니다.

전제 조건

웹 검색 도구를 사용하기 전에 조직 관리자가 Anthropic 콘솔(일반적으로 개인 정보 보호 또는 도구 사용 관련 설정에서 찾을 수 있음) 내에서 이를 활성화해야 합니다.

API 요청하기

웹 검색 도구를 사용하려면 Messages API에 대한 API 요청의 tools 배열에 포함해야 합니다. 구조는 다음과 같습니다.

도구 정의

사용할 기본적인 도구 정의는 다음과 같습니다.

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

type: 이 특정 문자열은 웹 검색 도구 버전을 식별합니다.
name: 도구의 설명적인 이름으로, 일반적으로 "web_search"입니다.

다음은 curl 호출 예시입니다.

curl https://api.anthropic.com/v1/messages \\
    --header "x-api-key: $ANTHROPIC_API_KEY" \\
    --header "anthropic-version: 2023-06-01" \\ # Or the latest recommended version
    --header "content-type: application/json" \\
    --data '{
        "model": "claude-3.5-sonnet-latest",    # Or another supported model
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "What are the latest developments in quantum computing this year?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5 # Optional: Limit search iterations
        }]
    }'

웹 검색 도구는 동작을 사용자 정의할 수 있는 몇 가지 선택적 매개변수를 제공합니다.

max_uses (정수, 선택 사항):

이 매개변수는 Claude가 단일 API 요청 내에서 수행할 수 있는 고유한 검색 작업 수를 제한합니다.
연구 깊이와 검색 관련 잠재적 비용을 모두 관리하는 데 유용한 제어 기능입니다.
Claude가 이 제한을 초과하려고 시도하면 web_search_tool_result는 max_uses_exceeded 코드로 오류를 표시합니다.
지정하지 않으면 Claude는 추론에 따라 검색 횟수를 결정합니다.

allowed_domains (문자열 배열, 선택 사항):

Claude가 검색 결과를 가져올 수 있는 도메인 목록을 지정합니다. 이는 사전 승인된 신뢰할 수 있는 소스에서만 정보가 오도록 보장하는 데 탁월합니다.
중요:
HTTP/HTTPS 스키마를 포함하지 마세요 (예: https://example.com 대신 example.com 사용).
서브도메인은 자동으로 포함됩니다 (예: example.com에는 docs.example.com도 포함됩니다).
하위 경로가 지원됩니다 (예: example.com/blog).
단일 요청에서 allowed_domains 또는 blocked_domains 중 하나만 사용할 수 있으며, 둘 다 사용할 수는 없습니다.

blocked_domains (문자열 배열, 선택 사항):

Claude가 절대 액세스해서는 안 되는 도메인 목록을 지정합니다. 이는 경쟁사 사이트, 관련 없는 소스 또는 잘못된 정보로 알려진 도메인에 대한 액세스를 방지하는 데 유용합니다.
allowed_domains와 동일한 형식 규칙이 적용됩니다.
allowed_domains와 동시에 사용할 수 없습니다.

user_location (객체, 선택 사항):

이 매개변수를 사용하면 검색 결과를 현지화하여 사용자의 지리적 문맥과 더 관련성 있게 만들 수 있습니다.
구조는 다음과 같습니다.

"user_location": {
  "type": "approximate", // Currently, only "approximate" is supported
  "city": "San Francisco",
  "region": "California",
  "country": "US",
  "timezone": "America/Los_Angeles" // IANA timezone ID
}

이는 Claude가 지역 뉴스, 서비스 또는 날씨와 같이 지리적으로 관련된 결과를 가져오는 데 도움이 됩니다.

Claude 웹 검색 API 응답 처리 방법

Claude가 웹 검색 도구를 사용할 때 API 응답에는 검색 프로세스 및 결과를 자세히 설명하는 특정 정보 블록이 포함됩니다. 이 구조를 이해하는 것이 도구를 효과적으로 사용하는 데 중요합니다.

일반적인 응답 구조:

어시스턴트 메시지의 content 배열에는 다음이 포함됩니다.

Claude의 검색 결정 (type: "text"): 종종 Claude는 검색 의도를 나타내는 짧은 텍스트를 출력합니다. 예: "해당 주제에 대한 최신 뉴스를 검색하겠습니다."

서버 도구 사용 블록 (type: "server_tool_use"):

이 블록은 Claude가 서버 측 도구(예: 웹 검색)를 사용하기로 결정했음을 나타냅니다.
id(예: srvtoolu_01WYG3ziw53XMcoyKL4XcZmE), 도구의 name("web_search"), 그리고 input 객체를 포함합니다.
input 객체에는 Claude가 검색 엔진에 보낸 실제 query가 포함됩니다 (예: {"query": "claude shannon birth date"}).

웹 검색 도구 결과 블록 (type: "web_search_tool_result"):

이 블록은 검색 결과를 포함합니다. server_tool_use 블록의 tool_use_id를 참조합니다.
검색이 성공하면 이 블록 내의 content는 web_search_result 객체의 배열이 됩니다.
각 web_search_result 객체에는 다음이 포함됩니다.
url: 소스 페이지의 URL입니다.
title: 소스 페이지의 제목입니다.
encrypted_content: 페이지의 암호화된 콘텐츠입니다. Claude가 이 특정 콘텐츠를 정확하게 인용할 수 있도록 하려면 다중 턴 대화의 후속 턴에서 이를 다시 전달해야 합니다.
page_age: 사이트가 마지막으로 업데이트되거나 크롤링된 시점을 나타내는 지표입니다 (예: "2025년 4월 30일").

Claude의 종합 응답 (type: "text", 인용 포함):

검색 결과에 이어 Claude는 찾은 정보를 통합하여 텍스트 응답을 제공합니다.
중요하게도, 이 텍스트의 일부에는 관련 citations이 포함됩니다.
각 citation 객체(web_search_result_location 유형)에는 다음이 포함됩니다.
url: 인용된 소스의 URL입니다.
title: 인용된 소스의 제목입니다.
encrypted_index: 이 인용을 지원하는 encrypted_content의 특정 부분에 대한 참조입니다. 이것 또한 다중 턴 대화에서 다시 전달되어야 합니다.
cited_text: 인용되는 소스 텍스트의 스니펫(최대 150자)입니다.

인용에 대한 중요 참고 사항: 인용 필드(cited_text, title, url)는 입력 또는 출력 토큰 사용량에 포함되지 않으므로 검증 가능한 정보를 제공하는 비용 효율적인 방법입니다.

오류 처리:
웹 검색 프로세스 중에 오류가 발생하면 web_search_tool_result 블록에는 결과 대신 오류 객체가 포함됩니다.

{
  "type": "web_search_tool_result",
  "tool_use_id": "servertoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded" // Example error
  }
}

일반적인 오류 코드는 다음과 같습니다.

too_many_requests: 검색에 대한 속도 제한을 초과했습니다.
invalid_input: 검색 쿼리 매개변수에 문제가 있습니다 (예: 잘못된 도메인 필터).
max_uses_exceeded: Claude가 max_uses 매개변수로 허용된 것보다 더 많은 검색을 시도했습니다.
query_too_long: Claude가 생성한 검색 쿼리가 너무 깁니다.
unavailable: 검색 서비스 내에서 내부 오류가 발생했습니다.

pause_turn 중단 이유:
여러 검색을 포함하는 잠재적으로 오래 실행되는 턴의 경우, API 응답에 pause_turn의 stop_reason이 포함될 수 있습니다. 이는 API가 턴을 일시 중지했음을 나타냅니다. 후속 요청에서 전체 응답 내용을 다시 보내 턴을 재개할 수 있으며, 이를 통해 Claude는 작업을 계속할 수 있습니다.

Apidog로 Claude 웹 검색 API 테스트하기

Apidog는 Claude의 웹 검색과 같은 API를 테스트하기 위한 강력한 환경을 제공합니다. 접근 방법은 다음과 같습니다.

프로젝트 설정: Apidog에서 새 프로젝트를 생성하거나 기존 프로젝트를 사용합니다. Claude API 엔드포인트를 수동으로 정의하거나 Anthropic이 제공하는 경우 OpenAPI 사양을 가져올 수 있습니다.

요청 정의:

"요청" 또는 "디자인" 모드로 이동합니다. 새 API 요청을 생성합니다.
메서드: HTTP 메서드를 POST로 설정합니다.
URL: Claude Messages API 엔드포인트를 입력합니다 (예: https://api.anthropic.com/v1/messages).
헤더: 필요한 헤더를 추가합니다.
x-api-key: Anthropic API 키.
anthropic-version: 필요한 API 버전 (예: 2023-06-01).
content-type: application/json.

요청 본문 구성:

"본문" 탭("raw"를 선택한 다음 "JSON")에서 JSON 페이로드를 입력합니다. 여기에는 model, max_tokens, messages 배열(사용자 역할 및 내용 포함), 그리고 web_search 도구를 지정하는 tools 배열이 포함됩니다.

전송 및 검사: "전송"을 클릭합니다. Apidog는 응답을 표시하며, 상태 코드, 헤더, 본문(Claude의 웹 검색 결과 및 인용 포함)을 검사할 수 있습니다.

어설션 (선택 사항): Apidog의 어설션 기능을 사용하여 web_search_tool_result 블록의 존재 여부 또는 특정 인용 세부 정보와 같은 응답 요소를 자동으로 검증합니다.

Apidog의 이 간소화된 프로세스는 Claude 웹 검색 API의 기능을 빠르게 반복하고 확인할 수 있도록 돕습니다.

💡

버튼

Claude 웹 검색 API의 고급 기능 및 모범 사례

기본 사항 외에도 Claude의 웹 검색 API는 성능, 비용 및 사용자 경험을 최적화하는 기능을 제공합니다.

프롬프트 캐싱:

웹 검색은 Anthropic의 프롬프트 캐싱 기능과 통합됩니다.
요청에 전략적으로 cache_control 중단점을 배치함으로써(특히 다중 턴 대화에서) 웹 검색 결과를 캐시할 수 있습니다.
예를 들어, web_search_tool_result를 받은 후 메시지 기록에 추가하고 cache_control: {"type": "ephemeral"}이 포함된 새 사용자 메시지를 추가하면 후속 호출에서 캐시된 검색 결과를 재사용할 수 있어 캐시된 부분의 지연 시간과 토큰 비용을 줄이면서 필요에 따라 새로운 검색을 허용할 수 있습니다.

스트리밍:

API 요청에 대해 스트리밍이 활성화되면 웹 검색 프로세스와 관련된 이벤트를 실시간으로 받게 됩니다.
여기에는 Claude가 검색을 결정할 때 발생하는 content_block_start 이벤트, 검색 쿼리가 스트리밍될 때 발생하는 content_block_delta 이벤트, 검색 실행 중 자연스러운 일시 중지, 그리고 검색 결과(web_search_tool_result)가 다시 스트리밍될 때 발생하는 추가 이벤트가 포함됩니다.
스트리밍은 사용자가 AI가 정보를 검색하기 위해 적극적으로 작업하고 있음을 볼 수 있으므로 더 반응적인 사용자 경험을 제공합니다.

배치 요청:

웹 검색 도구는 Messages Batches API에 대한 요청에 포함될 수 있습니다. 이는 웹 검색이 필요한 여러 쿼리를 비동기식 배치 방식으로 처리하는 데 유용합니다.
Batches API를 통한 웹 검색 가격은 일반 Messages API 요청과 동일합니다.

신뢰와 제어를 통한 구축:

인용 활용: 항상 UI를 설계하여 Claude가 제공하는 인용을 표시합니다. 이 투명성은 사용자 신뢰의 핵심이며 사용자가 정보를 확인할 수 있도록 합니다.
도메인 필터링 사용: 소스 신뢰성이 가장 중요한 애플리케이션(예: 금융 또는 의료 조언)의 경우, allowed_domains를 사용하여 검색을 권위 있는 소스로 제한합니다. blocked_domains를 사용하여 부적절하거나 원치 않는 콘텐츠에 대한 액세스를 방지합니다.
조직 수준 설정: 관리자는 조직 수준에서 웹 검색을 활성화하거나 비활성화하여 포괄적인 제어 메커니즘을 제공할 수 있음을 기억하세요.

비용 관리:

웹 검색 사용량은 토큰 사용량과 별도로 청구됩니다. 최신 정보 기준으로 검색 1,000회당 10달러의 비용이 발생합니다. 검색 결과를 기반으로 Claude가 생성한 콘텐츠에 대한 표준 토큰 비용은 여전히 적용됩니다.
각 웹 검색 호출은 반환된 결과 수와 관계없이 1회 사용으로 계산됩니다. 검색 시도 중 발생한 오류는 일반적으로 청구되지 않습니다.
특히 Claude가 여러 검색을 수행할 수 있는 에이전트 시나리오에서는 max_uses 매개변수를 신중하게 사용하여 사용자 쿼리당 잠재적인 검색 횟수를 제어합니다.

결론

Claude의 웹 검색 API는 LLM을 보다 실용적이고 신뢰할 수 있으며 지능적으로 만드는 데 있어 중요한 진전을 나타냅니다. 정적 훈련 데이터의 제약에서 벗어남으로써 Claude는 이제 오늘날의 세계를 반영하는 대화에 참여하고 콘텐츠를 생성할 수 있습니다. 개발자에게 이는 정보의 동적인 특성에 진정으로 보조를 맞출 수 있는 더 강력하고 정확하며 신뢰할 수 있는 AI 애플리케이션을 구축할 수 있는 능력을 의미합니다.

LLM이 계속 발전함에 따라 웹 검색과 같은 통합 도구는 점점 더 표준화되어 이러한 모델을 인상적인 지식 저장소에서 정보 발견 및 문제 해결의 동적이고 상호 작용적인 파트너로 변화시킬 것입니다. Claude의 웹 검색 API 기능을 이해하고 활용함으로써 개발자는 이 흥미로운 진화의 최전선에 서서 똑똑할 뿐만 아니라 웹의 맥박에 의해 지속적으로 정보를 얻는 AI 솔루션을 만들 수 있습니다.

💡

버튼