Loading...
    • 개발자 가이드
    • API 참고자료
    • MCP
    • 리소스
    • 릴리스 노트
    Search...
    ⌘K

    첫 번째 단계

    Claude 소개빠른 시작

    모델 및 가격

    모델 개요모델 선택하기Claude 4.5의 새로운 기능Claude 4.5로 마이그레이션모델 지원 중단가격 정책

    Claude로 빌드하기

    기능 개요Messages API 작업컨텍스트 윈도우프롬프트 작성 모범 사례

    기능

    프롬프트 캐싱컨텍스트 편집확장된 사고스트리밍 메시지배치 처리인용다국어 지원토큰 카운팅임베딩비전PDF 지원Files API검색 결과Google Sheets 애드온

    도구

    개요도구 사용을 구현하는 방법토큰 효율적인 도구 사용세밀한 도구 스트리밍Bash 도구코드 실행 도구컴퓨터 사용 도구텍스트 편집기 도구웹 페치 도구웹 검색 도구메모리 도구

    에이전트 스킬

    개요빠른 시작Skill 작성 모범 사례Skills 사용하기

    Agent SDK

    개요Agent SDK 참조 - TypeScriptPython SDK

    가이드

    스트리밍 입력권한 처리세션 관리Agent SDK 호스팅시스템 프롬프트 수정하기SDK에서의 MCP사용자 정의 도구SDK의 서브에이전트SDK의 슬래시 명령어SDK의 에이전트 스킬비용 및 사용량 추적할 일 목록SDK의 플러그인

    API의 MCP

    MCP 커넥터원격 MCP 서버

    타사 플랫폼의 Claude

    Amazon BedrockVertex AI

    프롬프트 엔지니어링

    개요프롬프트 생성기프롬프트 템플릿 사용하기프롬프트 개선기명확하고 직접적으로예시(멀티샷 프롬프팅) 사용Claude가 생각하도록 하기(CoT)XML 태그 사용Claude에게 역할 부여하기 (시스템 프롬프트)Claude의 응답 미리 채우기복잡한 프롬프트 체이닝긴 컨텍스트 팁확장 사고 팁

    테스트 및 평가

    성공 기준 정의하기테스트 케이스 개발평가 도구 사용하기지연 시간 줄이기

    보안 강화

    환각 현상 줄이기출력 일관성 높이기탈옥 완화handle-streaming-refusals프롬프트 유출 감소Claude의 캐릭터 유지

    관리 및 모니터링

    Admin API 개요사용량 및 비용 APIClaude Code Analytics API
    Console
    도구

    웹 검색 도구

    웹 검색 도구는 Claude에게 실시간 웹 콘텐츠에 대한 직접 접근을 제공하여 지식 기한을 초과하는 최신 정보로 질문에 답할 수 있게 합니다. Claude는 자동으로 검색 결과의 출처를 답변의 일부로 인용합니다.

    웹 검색 도구 사용 경험을 공유하려면 피드백 양식을 통해 연락해 주세요.

    지원되는 모델

    웹 검색은 다음에서 사용 가능합니다:

    • Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
    • Claude Sonnet 4 (claude-sonnet-4-20250514)
    • Claude Sonnet 3.7 (deprecated) (claude-3-7-sonnet-20250219)
    • Claude Haiku 4.5 (claude-haiku-4-5-20251001)
    • Claude Haiku 3.5 (claude-3-5-haiku-latest)
    • Claude Opus 4.1 (claude-opus-4-1-20250805)
    • Claude Opus 4 (claude-opus-4-20250514)

    웹 검색 작동 방식

    API 요청에 웹 검색 도구를 추가하면:

    1. Claude는 프롬프트를 기반으로 검색 시기를 결정합니다.
    2. API는 검색을 실행하고 Claude에게 결과를 제공합니다. 이 프로세스는 단일 요청 전체에서 여러 번 반복될 수 있습니다.
    3. 턴이 끝날 때 Claude는 인용된 출처와 함께 최종 응답을 제공합니다.

    웹 검색 사용 방법

    조직의 관리자가 Console에서 웹 검색을 활성화해야 합니다.

    API 요청에 웹 검색 도구를 제공합니다:

    Shell
    curl https://api.anthropic.com/v1/messages \
        --header "x-api-key: $ANTHROPIC_API_KEY" \
        --header "anthropic-version: 2023-06-01" \
        --header "content-type: application/json" \
        --data '{
            "model": "claude-sonnet-4-5",
            "max_tokens": 1024,
            "messages": [
                {
                    "role": "user",
                    "content": "What's the weather in NYC?"
                }
            ],
            "tools": [{
                "type": "web_search_20250305",
                "name": "web_search",
                "max_uses": 5
            }]
        }'
    Python
    import anthropic
    
    client = anthropic.Anthropic()
    
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "What's the weather in NYC?"
            }
        ],
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    )
    print(response)
    TypeScript
    import { Anthropic } from '@anthropic-ai/sdk';
    
    const anthropic = new Anthropic();
    
    async function main() {
      const response = await anthropic.messages.create({
        model: "claude-sonnet-4-5",
        max_tokens: 1024,
        messages: [
          {
            role: "user",
            content: "What's the weather in NYC?"
          }
        ],
        tools: [{
          type: "web_search_20250305",
          name: "web_search",
          max_uses: 5
        }]
      });
    
      console.log(response);
    }
    
    main().catch(console.error);

    도구 정의

    웹 검색 도구는 다음 매개변수를 지원합니다:

    JSON
    {
      "type": "web_search_20250305",
      "name": "web_search",
    
      // 선택사항: 요청당 검색 수 제한
      "max_uses": 5,
    
      // 선택사항: 이 도메인의 결과만 포함
      "allowed_domains": ["example.com", "trusteddomain.org"],
    
      // 선택사항: 이 도메인의 결과는 절대 포함하지 않음
      "blocked_domains": ["untrustedsource.com"],
    
      // 선택사항: 검색 결과 지역화
      "user_location": {
        "type": "approximate",
        "city": "San Francisco",
        "region": "California",
        "country": "US",
        "timezone": "America/Los_Angeles"
      }
    }

    최대 사용 횟수

    max_uses 매개변수는 수행된 검색 수를 제한합니다. Claude가 허용된 것보다 많은 검색을 시도하면 web_search_tool_result는 max_uses_exceeded 오류 코드가 있는 오류가 됩니다.

    도메인 필터링

    도메인 필터를 사용할 때:

    • 도메인에는 HTTP/HTTPS 스키마가 포함되지 않아야 합니다 (https://example.com 대신 example.com 사용)
    • 하위 도메인이 자동으로 포함됩니다 (example.com은 docs.example.com을 포함)
    • 하위 경로가 지원됩니다 (example.com/blog)
    • allowed_domains 또는 blocked_domains를 사용할 수 있지만 동일한 요청에서 둘 다 사용할 수는 없습니다.

    요청 수준 도메인 제한은 Console에서 구성된 조직 수준 도메인 제한과 호환되어야 합니다. 요청 수준 도메인은 도메인을 더 제한할 수만 있으며 조직 수준 목록을 재정의하거나 확장할 수 없습니다. 요청에 조직 설정과 충돌하는 도메인이 포함되면 API는 유효성 검사 오류를 반환합니다.

    지역화

    user_location 매개변수를 사용하면 사용자의 위치를 기반으로 검색 결과를 지역화할 수 있습니다.

    • type: 위치 유형 (approximate이어야 함)
    • city: 도시 이름
    • region: 지역 또는 주
    • country: 국가
    • timezone: IANA 시간대 ID.

    응답

    다음은 응답 구조의 예입니다:

    {
      "role": "assistant",
      "content": [
        // 1. Claude의 검색 결정
        {
          "type": "text",
          "text": "I'll search for when Claude Shannon was born."
        },
        // 2. 사용된 검색 쿼리
        {
          "type": "server_tool_use",
          "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
          "name": "web_search",
          "input": {
            "query": "claude shannon birth date"
          }
        },
        // 3. 검색 결과
        {
          "type": "web_search_tool_result",
          "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
          "content": [
            {
              "type": "web_search_result",
              "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
              "title": "Claude Shannon - Wikipedia",
              "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
              "page_age": "April 30, 2025"
            }
          ]
        },
        {
          "text": "Based on the search results, ",
          "type": "text"
        },
        // 4. 인용과 함께 Claude의 응답
        {
          "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
          "type": "text",
          "citations": [
            {
              "type": "web_search_result_location",
              "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
              "title": "Claude Shannon - Wikipedia",
              "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
              "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
            }
          ]
        }
      ],
      "id": "msg_a930390d3a",
      "usage": {
        "input_tokens": 6039,
        "output_tokens": 931,
        "server_tool_use": {
          "web_search_requests": 1
        }
      },
      "stop_reason": "end_turn"
    }

    검색 결과

    검색 결과에는 다음이 포함됩니다:

    • url: 소스 페이지의 URL
    • title: 소스 페이지의 제목
    • page_age: 사이트가 마지막으로 업데이트된 시간
    • encrypted_content: 다중 턴 대화에서 인용을 위해 다시 전달해야 하는 암호화된 콘텐츠

    인용

    인용은 웹 검색에 대해 항상 활성화되며 각 web_search_result_location에는 다음이 포함됩니다:

    • url: 인용된 소스의 URL
    • title: 인용된 소스의 제목
    • encrypted_index: 다중 턴 대화를 위해 다시 전달해야 하는 참조입니다.
    • cited_text: 인용된 콘텐츠의 최대 150자

    웹 검색 인용 필드 cited_text, title 및 url은 입력 또는 출력 토큰 사용량에 포함되지 않습니다.

    API 출력을 최종 사용자에게 직접 표시할 때 원본 소스에 대한 인용을 포함해야 합니다. API 출력을 수정하는 경우(최종 사용자에게 표시하기 전에 재처리 및/또는 자신의 자료와 결합하는 경우 포함) 법무팀과의 상담을 기반으로 적절하게 인용을 표시하세요.

    오류

    웹 검색 도구가 오류(예: 속도 제한 도달)를 만나면 Claude API는 여전히 200(성공) 응답을 반환합니다. 오류는 다음 구조를 사용하여 응답 본문 내에 표시됩니다:

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

    가능한 오류 코드는 다음과 같습니다:

    • too_many_requests: 속도 제한 초과
    • invalid_input: 잘못된 검색 쿼리 매개변수
    • max_uses_exceeded: 최대 웹 검색 도구 사용 횟수 초과
    • query_too_long: 쿼리가 최대 길이를 초과함
    • unavailable: 내부 오류 발생

    pause_turn 중지 이유

    응답에 pause_turn 중지 이유가 포함될 수 있으며, 이는 API가 장시간 실행되는 턴을 일시 중지했음을 나타냅니다. 응답을 그대로 후속 요청에 제공하여 Claude가 턴을 계속하도록 할 수 있으며, 대화를 중단하려면 콘텐츠를 수정할 수 있습니다.

    프롬프트 캐싱

    웹 검색은 프롬프트 캐싱과 함께 작동합니다. 프롬프트 캐싱을 활성화하려면 요청에 최소 하나의 cache_control 중단점을 추가하세요. 시스템은 도구를 실행할 때 마지막 web_search_tool_result 블록까지 자동으로 캐시합니다.

    다중 턴 대화의 경우 마지막 web_search_tool_result 블록 이후에 cache_control 중단점을 설정하여 캐시된 콘텐츠를 재사용하세요.

    예를 들어 다중 턴 대화를 위해 웹 검색과 함께 프롬프트 캐싱을 사용하려면:

    import anthropic
    
    client = anthropic.Anthropic()
    
    # 웹 검색 및 캐시 중단점이 있는 첫 번째 요청
    messages = [
        {
            "role": "user",
            "content": "What's the current weather in San Francisco today?"
        }
    ]
    
    response1 = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "user_location": {
                "type": "approximate",
                "city": "San Francisco",
                "region": "California",
                "country": "US",
                "timezone": "America/Los_Angeles"
            }
        }]
    )
    
    # Claude의 응답을 대화에 추가
    messages.append({
        "role": "assistant",
        "content": response1.content
    })
    
    # 검색 결과 후 캐시 중단점이 있는 두 번째 요청
    messages.append({
        "role": "user",
        "content": "Should I expect rain later this week?",
        "cache_control": {"type": "ephemeral"}  # 이 지점까지 캐시
    })
    
    response2 = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "user_location": {
                "type": "approximate",
                "city": "San Francisco",
                "region": "California",
                "country": "US",
                "timezone": "America/Los_Angeles"
            }
        }]
    )
    # 두 번째 응답은 캐시된 검색 결과의 이점을 얻을 것입니다
    # 필요한 경우 새로운 검색을 수행할 수 있습니다
    print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

    스트리밍

    스트리밍이 활성화되면 스트림의 일부로 검색 이벤트를 받게 됩니다. 검색이 실행되는 동안 일시 중지가 있습니다:

    event: message_start
    data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}
    
    event: content_block_start
    data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
    
    // Claude의 검색 결정
    
    event: content_block_start
    data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}
    
    // 검색 쿼리 스트리밍
    event: content_block_delta
    data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}
    
    // 검색 실행 중 일시 중지
    
    // 검색 결과 스트리밍
    event: content_block_start
    data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}
    
    // 인용과 함께 Claude의 응답 (이 예에서는 생략됨)

    배치 요청

    Messages Batches API에 웹 검색 도구를 포함할 수 있습니다. Messages Batches API를 통한 웹 검색 도구 호출은 일반 Messages API 요청과 동일하게 가격이 책정됩니다.

    사용량 및 가격

    Web search usage is charged in addition to token usage:

    "usage": {
      "input_tokens": 105,
      "output_tokens": 6039,
      "cache_read_input_tokens": 7123,
      "cache_creation_input_tokens": 7345,
      "server_tool_use": {
        "web_search_requests": 1
      }
    }
    

    Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

    Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

      © 2025 ANTHROPIC PBC

      Products

      • Claude
      • Claude Code
      • Max plan
      • Team plan
      • Enterprise plan
      • Download app
      • Pricing
      • Log in

      Features

      • Claude and Slack
      • Claude in Excel

      Models

      • Opus
      • Sonnet
      • Haiku

      Solutions

      • AI agents
      • Code modernization
      • Coding
      • Customer support
      • Education
      • Financial services
      • Government
      • Life sciences

      Claude Developer Platform

      • Overview
      • Developer docs
      • Pricing
      • Amazon Bedrock
      • Google Cloud’s Vertex AI
      • Console login

      Learn

      • Blog
      • Catalog
      • Courses
      • Use cases
      • Connectors
      • Customer stories
      • Engineering at Anthropic
      • Events
      • Powered by Claude
      • Service partners
      • Startups program

      Company

      • Anthropic
      • Careers
      • Economic Futures
      • Research
      • News
      • Responsible Scaling Policy
      • Security and compliance
      • Transparency

      Help and security

      • Availability
      • Status
      • Support center

      Terms and policies

      • Privacy policy
      • Responsible disclosure policy
      • Terms of service: Commercial
      • Terms of service: Consumer
      • Usage policy

      Products

      • Claude
      • Claude Code
      • Max plan
      • Team plan
      • Enterprise plan
      • Download app
      • Pricing
      • Log in

      Features

      • Claude and Slack
      • Claude in Excel

      Models

      • Opus
      • Sonnet
      • Haiku

      Solutions

      • AI agents
      • Code modernization
      • Coding
      • Customer support
      • Education
      • Financial services
      • Government
      • Life sciences

      Claude Developer Platform

      • Overview
      • Developer docs
      • Pricing
      • Amazon Bedrock
      • Google Cloud’s Vertex AI
      • Console login

      Learn

      • Blog
      • Catalog
      • Courses
      • Use cases
      • Connectors
      • Customer stories
      • Engineering at Anthropic
      • Events
      • Powered by Claude
      • Service partners
      • Startups program

      Company

      • Anthropic
      • Careers
      • Economic Futures
      • Research
      • News
      • Responsible Scaling Policy
      • Security and compliance
      • Transparency

      Help and security

      • Availability
      • Status
      • Support center

      Terms and policies

      • Privacy policy
      • Responsible disclosure policy
      • Terms of service: Commercial
      • Terms of service: Consumer
      • Usage policy
      © 2025 ANTHROPIC PBC