웹 검색 도구 · Claude API로 구축하기

중요 참고 사항: 웹 검색 도구를 사용하기 전에 조직에서 설정 콘솔에서 이 기능을 활성화해야 합니다. 이 설정은 여기에서 확인할 수 있습니다: https://platform.claude.com/settings/privacy

Claude에는 사용자 질문에 답변하기 위해 최신 정보나 전문 정보를 인터넷에서 검색할 수 있는 내장 웹 검색 도구가 포함되어 있습니다. 구현을 직접 제공해야 하는 다른 도구와 달리, Claude는 전체 검색 프로세스를 자동으로 처리합니다 - 이를 활성화하기 위해 간단한 스키마만 제공하면 됩니다.

웹 검색 도구 설정하기

웹 검색 도구를 사용하려면 다음과 같은 필수 필드를 포함하는 스키마 객체를 생성합니다:

python

web_search_schema = {
    "type": "web_search_20250305",
    "name": "web_search", 
    "max_uses": 5
}

max_uses 필드는 Claude가 수행할 수 있는 검색 횟수를 제한합니다. Claude는 초기 결과를 바탕으로 후속 검색을 수행할 수 있으므로, 이는 과도한 API 호출을 방지합니다. 단일 검색은 여러 결과를 반환하지만, Claude는 추가 검색이 필요하다고 판단할 수 있습니다.

응답 작동 방식

Claude가 웹 검색 도구를 사용할 때, 응답에는 여러 유형의 블록이 포함됩니다:

텍스트 블록 - Claude가 수행 중인 작업에 대한 설명
ServerToolUseBlock - Claude가 사용한 정확한 검색 쿼리를 표시
WebSearchToolResultBlock - 검색 결과를 포함
WebSearchResultBlock - 제목과 URL이 있는 개별 검색 결과
Citation 블록 - Claude의 진술을 뒷받침하는 텍스트

응답 구조를 통해 Claude가 정확히 무엇을 검색했는지, 그리고 어떤 소스를 찾았는지 확인할 수 있습니다. Citation에는 Claude가 답변을 뒷받침하기 위해 사용한 구체적인 텍스트와 소스 URL이 포함됩니다.

검색 도메인 제한하기

allowed_domains 필드를 사용하여 검색을 특정 도메인으로 제한할 수 있습니다. 이는 신뢰할 수 있는 권위 있는 소스를 원할 때 특히 유용합니다:

python

web_search_schema = {
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5,
    "allowed_domains": ["nih.gov"]
}

예를 들어, 의료나 운동 관련 조언을 물을 때 PubMed(nih.gov)와 같은 도메인으로 제한하면 무작위 블로그 콘텐츠가 아닌 증거 기반 정보를 얻을 수 있습니다.

검색 결과 렌더링하기

응답의 다양한 블록 유형은 특정 UI 렌더링을 위해 설계되었습니다:

텍스트 블록은 일반 콘텐츠로 렌더링합니다
웹 검색 결과는 상단에 소스 목록으로 표시합니다
Citation은 소스 도메인, 페이지 제목, URL, 인용된 텍스트를 포함하여 텍스트와 함께 인라인으로 표시합니다

이 구조는 사용자가 Claude가 어떻게 답변에 도달했는지 이해하는 데 도움이 되며, 사용된 소스에 대한 투명성을 제공합니다. Citation 형식은 어떤 구체적인 정보가 어떤 소스에서 나왔는지 명확하게 보여주어 AI 응답에 대한 신뢰를 구축합니다.

실제 사용

웹 검색 도구는 다음과 같은 경우에 가장 효과적입니다:

최신 이벤트 및 최근 동향
Claude의 학습 데이터에 없는 전문 정보
사실 확인 및 권위 있는 소스 찾기
최신 정보가 필요한 연구 작업

API 호출 시 tools 배열에 스키마를 포함하기만 하면, Claude가 사용자의 질문에 답변하는 데 웹 검색이 도움이 될지 자동으로 판단합니다.