웹 페치 도구

웹 가져오기 도구

웹 페치 도구를 사용하면 Claude가 지정된 웹 페이지 및 PDF 문서에서 전체 콘텐츠를 검색할 수 있습니다.

최신 웹 페치 도구 버전(web_fetch_20260209)은 Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 및 Claude Sonnet 4.6에서 동적 필터링을 지원합니다. Claude는 코드를 작성하고 실행하여 가져온 콘텐츠를 컨텍스트 윈도우에 도달하기 전에 필터링하여 관련 정보만 유지하고 나머지는 버릴 수 있습니다. 이는 응답 품질을 유지하면서 토큰 소비를 줄입니다. 이전 도구 버전(web_fetch_20250910)은 동적 필터링 없이 계속 사용 가능합니다.

Claude Mythos Preview의 경우 웹 페치는 Claude API 및 Microsoft Foundry에서만 지원됩니다. Amazon Bedrock 또는 Google Vertex AI의 Mythos Preview에서는 사용할 수 없습니다.

피드백 양식을 사용하여 모델 응답의 품질, API 자체 또는 문서의 품질에 대한 피드백을 제공하세요.

Zero Data Retention 적격성 및 allowed_callers 해결 방법은 Server tools를 참조하세요.

Claude가 신뢰할 수 없는 입력을 민감한 데이터와 함께 처리하는 환경에서 웹 페치 도구를 활성화하면 데이터 유출 위험이 발생합니다. 신뢰할 수 있는 환경에서만 이 도구를 사용하거나 민감하지 않은 데이터를 처리할 때만 사용하세요.

유출 위험을 최소화하기 위해 Claude는 동적으로 URL을 구성할 수 없습니다. Claude는 사용자가 명시적으로 제공한 URL 또는 이전 웹 검색 또는 웹 페치 결과에서 나온 URL만 가져올 수 있습니다. 그러나 이 도구를 사용할 때 신중하게 고려해야 할 잔여 위험이 여전히 있습니다.

데이터 유출이 우려되는 경우 다음을 고려하세요:

웹 페치 도구를 완전히 비활성화
max_uses 매개변수를 사용하여 요청 수 제한
allowed_domains 매개변수를 사용하여 알려진 안전한 도메인으로 제한

모델 지원은 Tool reference를 참조하세요.

웹 페치 작동 방식

API 요청에 웹 페치 도구를 추가하면:

Claude는 프롬프트 및 사용 가능한 URL을 기반으로 콘텐츠를 가져올 시기를 결정합니다.
API는 지정된 URL에서 전체 텍스트 콘텐츠를 검색합니다.
PDF의 경우 자동 텍스트 추출이 수행됩니다.
Claude는 가져온 콘텐츠를 분석하고 선택적 인용과 함께 응답을 제공합니다.

웹 페치 도구는 현재 JavaScript를 통해 동적으로 렌더링되는 웹사이트를 지원하지 않습니다.

동적 필터링

전체 웹 페이지 및 PDF를 가져오면 특히 큰 문서에서 필요한 특정 정보만 필요할 때 토큰을 빠르게 소비할 수 있습니다. web_fetch_20260209 도구 버전을 사용하면 Claude는 코드를 작성하고 실행하여 가져온 콘텐츠를 컨텍스트에 로드하기 전에 필터링할 수 있습니다.

이 동적 필터링은 다음에 특히 유용합니다:

긴 문서에서 특정 섹션 추출
웹 페이지에서 구조화된 데이터 처리
PDF에서 관련 정보 필터링
큰 문서로 작업할 때 토큰 비용 감소

동적 필터링을 사용하려면 code execution tool을 활성화해야 합니다. 웹 페치 도구(동적 필터링 포함 및 제외)는 Claude API 및 Microsoft Azure에서 사용 가능합니다.

동적 필터링을 활성화하려면 web_fetch_20260209 도구 버전을 사용하세요:

웹 페치 사용 방법

API 요청에 웹 페치 도구를 제공하세요:

도구 정의

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

JSON

{
  "type": "web_fetch_20250910",
  "name": "web_fetch",

  // 선택사항: 요청당 페치 수 제한
  "max_uses": 10,

  // 선택사항: 이 도메인에서만 페치
  "allowed_domains": ["example.com", "docs.example.com"],

  // 선택사항: 이 도메인에서는 절대 페치하지 않음
  "blocked_domains": ["private.example.com"],

  // 선택사항: 가져온 콘텐츠에 대한 인용 활성화
  "citations": {
    "enabled": true
  },

  // 선택사항: 토큰 단위의 최대 콘텐츠 길이
  "max_content_tokens": 100000
}

최대 사용 횟수

max_uses 매개변수는 수행되는 웹 페치 수를 제한합니다. Claude가 허용된 것보다 많은 페치를 시도하면 web_fetch_tool_result는 max_uses_exceeded 오류 코드가 있는 오류입니다. 현재 기본 제한이 없습니다.

도메인 필터링

allowed_domains 및 blocked_domains를 사용한 도메인 필터링은 Server tools를 참조하세요.

콘텐츠 제한

max_content_tokens 매개변수는 컨텍스트에 포함된 콘텐츠의 양을 제한합니다. 가져온 콘텐츠가 이 제한을 초과하면 도구가 이를 자릅니다. 이는 큰 문서를 가져올 때 토큰 사용을 제어하는 데 도움이 됩니다.

max_content_tokens 매개변수 제한은 근사값입니다. 실제로 사용되는 입력 토큰 수는 약간 다를 수 있습니다.

인용

웹 검색에서 인용이 항상 활성화되는 것과 달리 웹 페치의 경우 인용은 선택사항입니다. "citations": {"enabled": true}를 설정하여 Claude가 가져온 문서의 특정 구절을 인용하도록 활성화하세요.

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

응답

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

Output

{
  "role": "assistant",
  "content": [
    // 1. Claude의 페치 결정
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. 페치 요청
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. 페치 결과
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01234567890abcdef",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          },
          "title": "Article Title",
          "citations": { "enabled": true }
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Claude의 인용과 함께한 분석 (활성화된 경우)
    {
      "text": "Based on the article, ",
      "type": "text"
    },
    {
      "text": "the main argument presented is that artificial intelligence will transform healthcare",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Article Title",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "Artificial intelligence is poised to revolutionize healthcare delivery..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

페치 결과

페치 결과에는 다음이 포함됩니다:

url: 페치된 URL
content: 가져온 콘텐츠를 포함하는 문서 블록
retrieved_at: 콘텐츠를 검색한 타임스탬프

웹 페치 도구는 성능을 개선하고 중복 요청을 줄이기 위해 결과를 캐시합니다. 반환된 콘텐츠가 항상 URL에서 사용 가능한 최신 버전을 반영하지는 않을 수 있습니다. 캐시 동작은 자동으로 관리되며 다양한 콘텐츠 유형 및 사용 패턴에 최적화하기 위해 시간이 지남에 따라 변경될 수 있습니다.

PDF 문서의 경우 콘텐츠는 base64 인코딩 데이터로 반환됩니다:

Output

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_02",
  "content": {
    "type": "web_fetch_result",
    "url": "https://example.com/paper.pdf",
    "content": {
      "type": "document",
      "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..."
      },
      "citations": { "enabled": true }
    },
    "retrieved_at": "2025-08-25T10:30:02Z"
  }
}

오류

웹 페치 도구에서 오류가 발생하면 Claude API는 200(성공) 응답을 반환하고 오류는 응답 본문에 표시됩니다:

Output

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_fetch_tool_error",
    "error_code": "url_not_accessible"
  }
}

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

invalid_input: 잘못된 URL 형식
url_too_long: URL이 최대 길이(250자)를 초과함
url_not_allowed: 도메인 필터링 규칙 및 모델 제한으로 인해 URL이 차단됨
url_not_accessible: 콘텐츠 페치 실패(HTTP 오류)
too_many_requests: 속도 제한 초과
unsupported_content_type: 지원되지 않는 콘텐츠 유형(텍스트 및 PDF만 지원)
max_uses_exceeded: 최대 웹 페치 도구 사용 횟수 초과
unavailable: 내부 오류 발생

URL 검증

보안상의 이유로 웹 페치 도구는 이전에 대화 컨텍스트에 나타난 URL만 페치할 수 있습니다. 여기에는 다음이 포함됩니다:

사용자 메시지의 URL
클라이언트 측 도구 결과의 URL
이전 웹 검색 또는 웹 페치 결과의 URL

도구는 Claude가 생성하는 임의의 URL이나 컨테이너 기반 서버 도구(Code Execution, Bash 등)의 URL을 페치할 수 없습니다.

결합된 검색 및 페치

웹 페치는 웹 검색과 원활하게 작동하여 포괄적인 정보 수집을 가능하게 합니다:

Python

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Find recent articles about quantum computing and analyze the most relevant one in detail",
        }
    ],
    tools=[
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
        {
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5,
            "citations": {"enabled": True},
        },
    ],
)

이 워크플로우에서 Claude는:

웹 검색을 사용하여 관련 기사 찾기
가장 유망한 결과 선택
웹 페치를 사용하여 전체 콘텐츠 검색
인용과 함께 상세 분석 제공

프롬프트 캐싱

여러 턴에 걸쳐 도구 정의를 캐싱하려면 Tool use with prompt caching을 참조하세요.

스트리밍

스트리밍이 활성화되면 페치 이벤트는 콘텐츠 검색 중 일시 중지와 함께 스트림의 일부입니다:

Output

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_fetch"}}

// 페치 URL 스트리밍
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// 페치 실행 중 일시 중지

// 페치 결과 스트리밍
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Article content..."}}}}}

// Claude의 응답 계속...

배치 요청

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

사용 및 가격

Web fetch usage has no additional charges beyond standard token costs:

"usage": {
  "input_tokens": 25039,
  "output_tokens": 931,
  "cache_read_input_tokens": 0,
  "cache_creation_input_tokens": 0,
  "server_tool_use": {
    "web_fetch_requests": 1
  }
}

The web fetch tool is available on the Claude API at no additional cost. You only pay standard token costs for the fetched content that becomes part of your conversation context.

To protect against inadvertently fetching large content that would consume excessive tokens, use the max_content_tokens parameter to set appropriate limits based on your use case and budget considerations.

Example token usage for typical content:

Average web page (10 kB): ~2,500 tokens
Large documentation page (100 kB): ~25,000 tokens
Research paper PDF (500 kB): ~125,000 tokens

다음 단계

Server tools

Anthropic 실행 도구의 공유 메커니즘입니다.

Tool reference

모든 Anthropic 제공 도구의 디렉토리입니다.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Fetch the content at https://example.com/research-paper and extract the key findings.",
        }
    ],
    tools=[{"type": "web_fetch_20260209", "name": "web_fetch"}],
)
print(response)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Please analyze the content at https://example.com/article",
        }
    ],
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5}],
)
print(response)