목차
Claude 가이드 - 이 글은 시리즈의 일부입니다.
이 글은 Claude API 공식 문서의 Web search tool 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool 마지막 확인: 2026-05-24
1. 한 줄 요약 #
Claude에게 “지금 검색해도 돼” 한 줄을 더해주면, 인터넷에서 직접 자료를 찾아 출처와 함께 답해줍니다.
2. 무엇이고 왜 좋을까 #
Claude에게 도서관 출입증을 쥐여주는 것과 같습니다. 평소 Claude는 일정 시점까지 학습한 내용만 알고 있어서, “오늘 환율은?”, “이번 주 영화 순위는?” 같은 질문엔 “저는 잘 모릅니다"라고 답할 수밖에 없었습니다.
웹 검색 도구(Web Search Tool)를 켜두면 Claude가 필요하다고 판단할 때 스스로 인터넷을 검색합니다. 그리고 답변 끝에 어디서 가져온 정보인지 출처 링크까지 붙여줍니다. “그냥 지어낸 이야기 아닐까?” 하는 불안이 줄어드는 거죠.
비용은 검색 1,000번당 약 10달러 — 한 번 검색에 약 13원입니다. 토큰 비용은 별도로 들어가지만, 직접 자료를 찾아 정리해야 하는 시간을 생각하면 부담 없는 수준입니다.
3. 이런 상황에서 써요 #
상황 1: 강의 발표 자료를 만드는 대학생 #
“이번 발표 주제가 ‘2026년 인공지능 흐름’인데, 최신 뉴스를 모아야 해요.” Claude에게 그냥 물어보면 학습 시점 이후 소식은 알지 못합니다. 하지만 웹 검색 도구를 켜두면 Claude가 직접 최근 기사들을 찾아 핵심을 정리해주고, 인용한 기사의 링크도 함께 알려줍니다. 발표 자료의 출처 표기까지 한 번에 해결됩니다.
상황 2: 거래처 정보를 빠르게 파악해야 하는 직장인 #
“내일 미팅 갈 회사가 최근에 어떤 발표를 했는지 30분 안에 정리해야 해요.” 하나하나 기사를 찾아 읽기엔 시간이 빠듯하죠. Claude에게 회사 이름을 알려주고 검색을 부탁하면, 최근 보도자료나 뉴스 요약을 출처와 함께 정리해줍니다. 회의 직전에 핵심만 빠르게 훑기 좋습니다.
상황 3: 여행을 준비하는 일반인 #
“다음 달에 제주도 가는데, 요즘 날씨랑 핫한 카페 좀 알려줘.” 평소 Claude는 옛날 정보로 답할 수 있지만, 웹 검색을 켜두면 최근 블로그와 뉴스를 찾아 알려줍니다. 게다가 “사용자 위치"를 알려주면 그 지역에 맞는 결과를 우선해서 보여주기도 합니다.
4. 가볍게 시작하기 #
💻 개발 경험 있으신가요? 아래는 Python 기준 가장 짧은 예시입니다. 비개발자라면 “아, Claude에게 검색 도구를 쥐여주는 게 이런 식이구나” 정도로 보고 넘어가셔도 좋습니다.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[{"role": "user", "content": "오늘 뉴욕 날씨 어때?"}],
# ↓ 이 한 줄이 "필요하면 검색해도 돼" 신호
tools=[{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5 # 한 번 질문에 최대 5번까지 검색
}],
)
print(response)위 코드는 단 한 가지를 추가했을 뿐입니다 — tools 항목에 웹 검색 도구를 넣은 거죠. 이렇게 하면 Claude가 질문을 보고 “이건 최신 정보가 필요하네"라고 판단할 때 알아서 검색합니다. max_uses는 검색 횟수 상한선이라, “혹시 너무 많이 검색하면 어쩌지?” 하는 걱정을 덜어줍니다.
5. 흔한 오해와 함정 #
⚠️ 함정 1: “켜두기만 하면 매번 검색하겠죠?” #
아닙니다. Claude가 스스로 판단해서, 검색이 필요하다고 생각할 때만 검색합니다. 예를 들어 “1+1은?“이라고 물으면 검색하지 않습니다. 검색이 안 들어간다 싶으면 질문을 더 구체적으로 — “오늘 날짜 기준으로”, “최근 뉴스에서” 같은 표현 — 다듬어보세요.
⚠️ 함정 2: “관리자가 안 켜줬는데 왜 안 되죠?” #
웹 검색은 콘솔에서 조직 관리자가 먼저 활성화해야 합니다. 개인 계정이라면 본인이 관리자이니 Claude Console에서 켜주면 되고, 회사 계정이라면 담당자에게 한 번 확인해보세요. “에러가 났는데 코드 문제일까?” 하기 전에 관리자 설정부터 확인하면 시간을 아낄 수 있습니다.
⚠️ 함정 3: “출처 링크가 너무 많아서 정신없어요” #
웹 검색 결과는 항상 출처(Citations, 인용)가 함께 따라옵니다. 신뢰성을 위해서죠. 만약 특정 사이트만 신뢰하고 싶다면 allowed_domains(허용 도메인)으로 좁히고, 반대로 광고성 사이트를 빼고 싶다면 blocked_domains(차단 도메인)을 쓰면 됩니다. 결과의 질이 눈에 띄게 좋아집니다.
6. 한 단계 더 (관심 있는 분만) #
🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 알고 싶은 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.
검색 결과의 질을 한 단계 끌어올리고 싶다면, 지역 정보와 도메인 필터를 함께 써보세요. 위치를 알려주면 “근처 맛집” 같은 질문에 한국 결과가 우선되고, 도메인 필터를 쓰면 신뢰하는 사이트의 결과만 모입니다.
tools = [{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 3,
# 신뢰하는 사이트만 보기
"allowed_domains": ["wikipedia.org", "nature.com"],
# 사용자 위치 (한국 서울 기준)
"user_location": {
"type": "approximate",
"city": "Seoul",
"country": "KR",
"timezone": "Asia/Seoul"
}
}]또 최신 도구 버전(web_search_20260209)에서는 동적 필터링(Dynamic Filtering) 이 추가되었습니다. Claude가 검색 결과의 HTML(웹 페이지의 원본 코드) 전체를 통째로 읽는 대신, 코드로 핵심만 골라서 읽는 기능이에요. 결과적으로 답변이 더 정확해지고 토큰도 절약됩니다. 다만 이 기능을 쓰려면 코드 실행 도구(Code Execution Tool)도 함께 켜져 있어야 합니다.
비용 감각 잡기: 검색 한 번에 약 13원입니다. 하루 100번 검색해도 약 1,300원이니, 가볍게 써보기에 부담 없는 수준입니다. 단, 검색 결과 자체는 입력 토큰으로 계산되니, 긴 페이지를 자주 검색하면 토큰 비용이 따로 쌓인다는 점은 기억해두세요.
7. 한 마디 #
처음엔 “Claude가 인터넷을 직접 찾아본다고?” 하면 신기하면서도 조금 어렵게 느껴질 수 있어요. 하지만 실제로 추가하는 건 단 한 줄입니다. 그 한 줄이 “오늘”, “최근”, “지금” 같은 말이 들어간 질문을 모두 가능하게 만들어줘요.
막힌다면 대부분 함정 1~3 중 하나일 가능성이 큽니다 — 관리자가 안 켰거나, 질문이 너무 일반적이거나, 도메인 필터를 너무 좁게 잡았거나. 천천히 하나씩 점검해보면 됩니다.
다음 글에서는 #15 — 웹 페이지 가져오기 도구(Web Fetch) 를 다룹니다. 이번 글의 웹 검색이 “구글에서 찾기"라면, 다음 글은 “특정 페이지 한 곳을 통째로 읽어오기"에 가깝습니다. 둘을 함께 쓰면 Claude가 훨씬 더 든든한 조력자가 되어줄 거예요.
Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.
