Claude API 웹 검색 도구 사용법: 최신 정보를 출처와 함께 답하게 하기

모델은 학습 시점 이후의 일을 모릅니다. 그래서 "오늘 발표된 정책", "현재 가격" 같은 질문에 정확히 답하려면 검색이 필요합니다. Claude API에서는 웹 검색 도구를 선언하는 것만으로 클로드가 필요할 때 직접 검색하고, 출처와 함께 답하게 할 수 있습니다.

서버 도구로 동작합니다

툴 사용에서 다룬 일반 도구는 내 코드가 실행해야 했습니다. 웹 검색은 다릅니다. Anthropic 서버에서 실행되는 서버 도구라서, 요청에 선언만 하면 검색 실행과 결과 처리까지 한 번의 API 호출 안에서 끝납니다.

파이썬 예제

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=2048,
    tools=[{
        "type": "web_search_20260209",
        "name": "web_search",
        "max_uses": 3,
    }],
    messages=[{"role": "user", "content": "이번 주 발표된 국내 AI 관련 정책 소식을 출처와 함께 3개만 정리해 줘."}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

도구의 type 값(버전 이름)은 모델에 따라 지원 버전이 다를 수 있습니다. 쓰는 모델에 맞는 버전을 공식 문서에서 확인하세요.

응답에는 검색 결과 블록과 텍스트 블록이 함께 오고, 텍스트에는 근거가 된 출처 정보가 붙습니다. 서비스 화면에서는 이 출처 링크를 함께 보여 주는 것이 좋습니다.

검색을 통제하는 옵션

• max_uses: 한 요청에서 검색할 수 있는 횟수 상한입니다. 비용과 응답 시간을 관리합니다.
• allowed_domains / blocked_domains: 검색 범위를 정합니다. 예를 들어 사내 고객 지원 봇이라면 회사 공식 사이트와 공식 문서만 허용할 수 있습니다. 둘 중 하나만 쓰세요.
• user_location: 지역에 따라 달라지는 정보를 물을 때 힌트를 줍니다.

오류도 응답 안에 옵니다

서버 도구는 실패해도 예외가 나지 않고, 응답 안에 오류 정보가 담긴 결과 블록이 옵니다. 예를 들어 검색 횟수 상한에 닿으면 그 사실이 결과 블록에 표시됩니다. 결과 블록을 처리할 때 정상 결과(목록)와 오류(객체)를 구분하세요.

비용 관리

웹 검색은 검색 사용량에 따른 별도 요금이 있고, 검색 결과가 입력에 들어가 토큰도 늘어납니다.

결과 검증

출처가 붙는다고 내용이 항상 정확한 것은 아닙니다. 웹 검색 활용법에서 정리한 원칙이 API에서도 같습니다. 출처의 게시 날짜를 확인하고, 중요한 정보는 1차 출처(공식 발표)를 우선하도록 시스템 프롬프트에 적어 두세요.

써 보며 느낀 점

웹 검색 도구를 붙이면 봇이 갑자기 "다 아는" 것처럼 보이는데, 그만큼 검색 범위 통제가 중요했습니다. 범위를 열어 두면 블로그 글이나 오래된 기사까지 근거로 섞여 들어옵니다. 저는 처음엔 허용 도메인을 좁게 두고, 필요할 때만 넓히는 방식을 씁니다.

핵심 요약

1. 웹 검색은 서버 도구라 선언만 하면 검색·결과 처리가 한 번의 호출 안에서 끝납니다.
2. max_uses, 허용·차단 도메인으로 비용과 근거 범위를 통제하세요.
3. 오류도 응답 블록으로 오니 구분해 처리하고, 출처 날짜와 1차 출처를 확인합니다.

공식 문서와 함께 읽을 글

• Web search tool (Anthropic 공식 문서)
• Claude API 요금 (공식)