Claude 웹 검색 도구 max_uses로 리서치 자동화

Claude API 웹 검색 도구로 출처가 달린 조사를 자동화하면서 비용은 어떻게 제한할까요? max_uses로 검색 횟수 상한을 걸고 토큰 비용을 따로 계산하면 됩니다.

조회 36
Claude 웹 검색 도구 max_uses로 리서치 자동화

핵심 요약

  • web_search_20250305 서버 도구는 도구 정의 하나만 추가하면 붙는다
  • max_uses로 턴당 검색 횟수를 제한해 검색 비용 상한을 계산한다
  • 검색은 1,000건당 10달러에 입력 토큰 비용이 별도로 더해진다

Claude API에서 web_search_20250305 서버 도구를 tools에 넣고 max_uses를 지정하면, 출처가 달린 조사 결과를 받으면서 요청당 검색 횟수도 제한할 수 있습니다. 비용은 Anthropic 웹 검색 도구 문서에 따르면 검색 1,000건당 10달러에 검색 결과가 만드는 표준 토큰 비용이 더해집니다. 아래는 이 구성을 순서대로 짜 보는 과정입니다.

서버 도구라서 붙이기가 쉽다

웹 검색은 Anthropic 서버에서 실행되는 도구입니다. 검색 API를 따로 연동하거나 결과를 받아 되돌려 보내는 루프를 만들 필요가 없고, 도구 정의 하나만 추가하면 됩니다. 공식 문서의 예시 정의는 다음과 같습니다.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="사용할 모델 ID",
    max_tokens=2048,
    messages=[{"role": "user", "content": "최근 6개월간 국내 데이터센터 전력 정책 변화를 조사해 줘"}],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    }],
)

모델 ID는 환경에 맞게 바꿔 쓰시면 됩니다. 도구 타입 문자열과 max_uses 필드는 공식 문서의 예시와 같은 형태입니다. 같은 문서에는 검색 결과를 현지화하는 선택 파라미터도 있습니다.

출처 표기는 응답 구조에서 꺼낸다

문서에 따르면 검색 결과에는 인용 정보가 들어 있습니다. 그래서 본문 문장마다 어떤 페이지에서 나온 내용인지 코드로 뽑아 각주나 링크로 바꿀 수 있습니다. 모델에게 "출처를 달아 줘"라고 프롬프트로 부탁하는 방식과 다릅니다. 이쪽은 응답 데이터의 구조를 이용하므로 후처리를 자동화하기 좋습니다.

실무에서는 응답의 content 블록을 순회하며 텍스트 블록에 붙은 인용(URL, 제목)을 모으고, 중복 URL을 제거해 문서 끝에 목록으로 붙이는 정도로 시작하면 됩니다. 블록 필드 이름은 응답 스키마를 확인한 뒤 맞추세요. 여기서는 필드명을 단정하지 않겠습니다.

max_uses로 검색 횟수에 상한을 건다

비용 통제의 핵심은 max_uses입니다. 문서는 이 파라미터가 한 번의 턴에서 수행할 수 있는 검색 횟수를 제한한다고 설명합니다. Claude가 한도보다 많이 검색하려 하면 도구 결과에 오류가 반환된다고 안내되어 있습니다. 조사 질문이 넓을수록 모델이 검색을 거듭할 수 있으니, 상한을 두면 요청 하나의 최대 검색 비용을 미리 계산할 수 있습니다.

최악의 경우 검색 비용만 보면 이렇게 됩니다. 검색 비용은 건당 0.01달러(1,000건에 10달러)이므로 계산은 단순합니다.

max_uses 요청당 검색 비용 상한 100회 요청 시
3 0.03달러 3달러
5 0.05달러 5달러
10 0.10달러 10달러

이 표는 공식 단가를 곱한 산식이고, 토큰 비용은 포함하지 않았습니다.

토큰 비용은 따로 계산해야 한다

문서에 따르면 검색 결과는 입력 토큰으로 집계됩니다. 한 턴 안에서 반복된 검색 결과도, 이후 대화 턴에 이어지는 검색 결과도 마찬가지입니다. 검색 횟수를 줄이는 것만으로는 부족하고, 긴 대화에서 결과가 누적되어 입력 토큰이 늘어나는 점도 봐야 합니다. 모델별 토큰 단가는 Anthropic 가격 문서에서 확인하세요. 단가는 모델마다 다르고 바뀔 수 있어서 이 글에는 적지 않았습니다.

과금 규칙에서 헷갈리기 쉬운 부분이 있습니다. 문서에는 검색 1회가 결과 개수와 관계없이 1회 사용으로 집계된다고 되어 있습니다. 오류로 실패한 검색은 과금되지 않는다고도 되어 있습니다. 반면 다른 대목에는 실패한 검색도 max_uses 한도에는 포함된다고 적혀 있습니다. 즉 실패는 돈은 안 들어도 한도는 깎습니다. 한도를 빠듯하게 잡으면 실패 몇 번에 조사가 일찍 끝날 수 있다는 뜻입니다.

배치로 돌릴 때 알아둘 점

대량 조사는 Message Batches API에도 웹 검색 도구를 넣을 수 있습니다. 문서에 따르면 배치의 검색 호출 가격은 일반 Messages API 요청과 같습니다. 다만 공유 용량을 보호하려고 조직별로 웹 검색 요청을 조절하므로, 검색이 많은 대형 배치는 완료까지 더 걸릴 수 있다고 합니다. 배치라고 검색 단가가 내려가지는 않는다는 점을 기억해 두세요.

실천 가이드

  1. 도구 정의에 max_uses를 항상 명시하세요. 처음에는 3~5 정도로 시작하는 것을 권합니다. 이 숫자는 필자의 제안이고 공식 권장값이 아닙니다.
  2. 실패한 검색도 한도를 소진하므로, 한도에는 여유를 조금 두세요.
  3. 응답의 인용 정보를 코드로 추출해 URL 중복을 제거하고, 본문과 함께 저장하세요.
  4. 비용은 검색비(건수 × 0.01달러)와 토큰비를 따로 집계하세요. 토큰 단가는 가격 문서를 기준으로 삼으면 됩니다.
  5. 대화형 서비스에서는 이전 턴의 검색 결과가 입력 토큰으로 계속 쌓이므로, 대화 길이에도 상한을 두세요.

정리하면, 검색 도구는 붙이기 쉽고 max_uses로 비용 상한도 간단히 정할 수 있습니다. 실제 청구액을 좌우하는 것은 검색 횟수보다 누적되는 입력 토큰인 경우가 많을 수 있으니 둘을 함께 보시길 권합니다.

자주 묻는 질문

Q. 웹 검색 도구를 쓰려면 별도 검색 API를 연동해야 하나요?

아닙니다. 웹 검색은 Anthropic 서버에서 실행되는 서버 도구라서 검색 API 연동이나 결과를 되돌려 보내는 루프가 필요 없습니다. tools에 도구 정의 하나만 추가하면 됩니다.

Q. max_uses로 검색 비용 상한을 어떻게 계산하나요?

검색은 건당 0.01달러(1,000건에 10달러)이므로 max_uses에 0.01달러를 곱하면 요청당 검색 비용 상한이 나옵니다. 예를 들어 max_uses가 5이면 0.05달러입니다. 이 값에는 토큰 비용이 포함되지 않습니다.

Q. 실패한 검색은 과금되나요?

문서에 따르면 오류로 실패한 검색은 과금되지 않지만 max_uses 한도에는 포함됩니다. 그래서 한도를 빠듯하게 잡으면 실패 몇 번에 조사가 일찍 끝날 수 있습니다.

참고 자료

이 글은 웹 검색으로 확인한 위 출처를 바탕으로 AI(claude-sonnet-5-5)가 작성했습니다. 수치·가격은 출처 원문에서 다시 확인하세요.

#AI기술#Claude API#max_uses#Message Batches#리서치 자동화#비용 관리#웹 검색 도구