Claude Platform Docs
Messages도구

Web fetch 도구

특정 URL에서 콘텐츠를 가져오고 읽어 Claude의 컨텍스트를 실시간 웹 콘텐츠로 보강합니다.

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

최신 web fetch 도구 버전(web_fetch_20260318)은 동적 필터링(dynamic filtering)을 지원합니다. Claude는 가져온 콘텐츠가 컨텍스트 윈도우에 도달하기 전에 코드를 작성하고 실행하여 필터링할 수 있으며, 관련 정보만 유지하고 나머지는 버립니다. 이를 통해 응답 품질을 유지하면서 토큰 소비를 줄입니다. 동적 필터링은 Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6에서 사용할 수 있습니다. web_fetch_20260318은 또한 에이전트 워크플로를 위한 응답 포함(response inclusion) 제어를 추가합니다. 이전 버전(동적 필터링 및 캐시 우회(cache bypass)를 위한 web_fetch_20260309, 동적 필터링만을 위한 web_fetch_20260209, 기본 fetch를 위한 web_fetch_20250910)도 계속 사용할 수 있습니다.

web fetch(동적 필터링 포함 및 미포함)는 Claude API, Claude Platform on AWS, Microsoft Foundry에서 사용할 수 있습니다. Microsoft Foundry에서 Azure에 호스팅된 배포는 기본 web fetch 도구(web_fetch_20250910, 동적 필터링 미포함)만 지원합니다. Anthropic에 호스팅된 배포는 모든 버전을 지원합니다. web fetch는 현재 Amazon Bedrock 또는 Google Cloud에서 사용할 수 없습니다.

Zero Data Retention 자격 및 allowed_callers 해결 방법에 대해서는 서버 도구를 참조하세요.

모델 지원에 대해서는 도구 참조를 참조하세요.

web fetch 작동 방식

web fetch는 서버 도구입니다. API는 요청 중에 콘텐츠를 가져와 결과를 대화에 삽입합니다. 아무것도 실행하거나 tool_result를 반환할 필요가 없습니다. 예외는 Claude가 동일한 병렬 도구 호출 그룹에서 web fetch와 클라이언트 도구 중 하나를 호출하는 경우입니다. 이 경우 API는 해당 fetch가 실행되기 전에 stop_reason: "tool_use"와 함께 응답을 반환한 다음, 클라이언트 tool_result 블록을 다시 보내면 fetch를 실행합니다. 한 턴에서 서버 도구와 클라이언트 도구 혼합을 참조하세요.

API 요청에 web fetch 도구를 추가하면:

  1. Claude는 프롬프트와 사용 가능한 URL을 기반으로 콘텐츠를 가져올 시점을 결정합니다.
  2. API는 지정된 URL에서 전체 텍스트 콘텐츠를 검색합니다.
  3. PDF의 경우, API는 콘텐츠를 base64로 인코딩된 데이터로 반환하고 직접 첨부된 PDF 문서처럼 처리합니다.
  4. Claude는 가져온 콘텐츠를 분석하고 선택적 인용과 함께 응답을 제공합니다.

Claude가 가져오는 시점

Claude는 요청이 특정 페이지 또는 문서를 가리킬 때 가져옵니다:

  • 대화(또는 이전 도구 결과)에 URL이 제공된 경우
  • 사용자가 URL 없이 특정 리소스(특정 기사, README, 가격 페이지 또는 문서 섹션)를 지정하고, web search 도구도 활성화되어 있어 Claude가 먼저 이를 찾을 수 있는 경우(검색 및 가져오기 결합 참조)

Claude는 특정 페이지를 참조하지 않는 일반 지식 또는 개방형 질문에 대해서는 가져오기를 하지 않습니다. "이 기사를 요약해 주세요: <url>"은 가져오기를 트리거합니다. "REST API 설계의 모범 사례는 무엇인가요?"는 직접 답변됩니다.

동적 필터링

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

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

  • 긴 문서에서 특정 섹션 추출
  • 웹 페이지에서 구조화된 데이터 처리
  • PDF에서 관련 정보 필터링
  • 대용량 문서 작업 시 토큰 비용 절감

동적 필터링을 활성화하려면 web_fetch_20260209 또는 이후 버전을 사용하세요. 다음 예제는 web_fetch_20260318을 사용합니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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_20260318", "name": "web_fetch"}],
)
print(response)

web fetch 사용 방법

API 요청에 web fetch 도구를 제공하세요:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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)

도구 정의

web fetch 도구는 다음 매개변수를 지원합니다:

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

  // Optional: Limit the number of fetches per request
  "max_uses": 10,

  // Optional: Only fetch from these domains
  "allowed_domains": ["example.com", "docs.example.com"],

  // Optional: Never fetch from these domains (cannot be combined with allowed_domains)
  "blocked_domains": ["private.example.com"],

  // Optional: Enable citations for fetched content
  "citations": {
    "enabled": true
  },

  // Optional: Maximum content length in tokens
  "max_content_tokens": 100000
}

이후 도구 버전은 두 개의 선택적 매개변수를 추가합니다. use_cache는 web_fetch_20260309 이상이 필요하며(캐시 우회 참조), response_inclusion은 web_fetch_20260318 이상이 필요합니다(응답 포함 참조).

최대 사용 횟수

max_uses 매개변수는 수행되는 web fetch 횟수를 제한합니다. 실패한 가져오기도 제한에 포함됩니다. Claude가 허용된 것보다 더 많은 가져오기를 시도하면 web_fetch_tool_result는 max_uses_exceeded 오류 코드와 함께 오류가 됩니다. 현재 기본 제한은 없습니다.

도메인 필터링

allowed_domains 및 blocked_domains를 사용한 도메인 필터링에 대해서는 서버 도구를 참조하세요.

Claude Managed Agents에서는 에이전트 도구 세트의 web_fetch 항목에 이러한 필드를 설정하며, 나열된 각 도메인은 경로가 없는 일반 호스트 이름이어야 합니다. 웹 검색 및 web fetch 도메인 제한을 참조하세요.

콘텐츠 제한

max_content_tokens 매개변수는 컨텍스트에 포함되는 콘텐츠의 양을 제한합니다. 가져온 콘텐츠가 이 제한을 초과하면 도구가 이를 잘라냅니다. 이는 대용량 문서를 가져올 때 토큰 사용량을 제어하는 데 도움이 됩니다. 이 제한은 텍스트 콘텐츠에 적용되며, PDF와 같은 바이너리 콘텐츠에는 적용되지 않습니다.

Claude Managed Agents에서는 에이전트 도구 세트의 web_fetch 항목도 max_content_tokens를 허용합니다. 웹 검색 및 web fetch 도메인 제한을 참조하세요.

캐시 우회

use_cache 매개변수는 캐시된 콘텐츠를 반환할 수 있는지 여부를 제어합니다. 캐시를 우회하고 새로운 콘텐츠를 가져오려면 "use_cache": false로 설정하세요. 기본값은 true입니다. 캐시를 우회하면 지연 시간이 증가하므로, 사용자가 명시적으로 새로운 콘텐츠를 요청하거나 빠르게 변경되는 소스를 가져올 때만 캐싱을 비활성화하세요.

{
  "tools": [
    {
      "type": "web_fetch_20260309",
      "name": "web_fetch",
      "use_cache": false
    }
  ]
}

응답 포함

response_inclusion 매개변수는 결과가 동일한 턴에서 완료된 code execution 호출에 의해 소비된 경우 fetch 결과 블록이 API 응답에 어떻게 나타나는지를 제어합니다. "response_inclusion": "excluded"로 설정하면 이러한 중첩된 server_tool_use 및 결과 블록 쌍을 응답에서 완전히 제거하여, 원시 페이지 콘텐츠를 클라이언트에 다시 에코할 필요가 없는 에이전트 워크플로의 출력 토큰 비용을 줄입니다. 기본값은 "full"입니다. 직접 호출의 결과 또는 완료되기 전에 일시 중지된 code execution 호출의 결과는 다음 턴에 다시 보낼 수 있도록 항상 전체가 반환됩니다.

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "response_inclusion": "excluded"
    }
  ]
}

인용

인용이 항상 활성화되는 웹 검색과 달리, web fetch의 경우 인용은 선택 사항이며 기본적으로 비활성화되어 있습니다. Claude가 가져온 문서에서 특정 구절을 인용할 수 있도록 하려면 "citations": {"enabled": true}로 설정하세요.

응답

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

Output
{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to fetch
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. The fetch request
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Fetch results
    {
      "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's analysis with citations (if enabled)
    {
      "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: 콘텐츠를 검색한 타임스탬프

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

오류

web fetch 도구에서 오류가 발생하면 Claude API는 응답 본문에 오류가 표시된 200(성공) 응답을 반환합니다. Claude는 오류 결과를 확인하고 턴을 계속합니다. 예를 들어:

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

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

  • invalid_tool_input: 잘못된 형식의 URL 또는 비 HTTP(S) 스킴과 같은 잘못된 도구 입력
  • url_too_long: URL이 최대 길이(250자)를 초과함
  • url_not_allowed: 도메인 필터링 규칙(조직 설정 포함) 또는 Anthropic 측 제한(예: 사설 주소, robots.txt, 직접 제공하지 않은 자격 증명이 포함된 것으로 보이는 URL)에 의해 URL이 차단됨
  • url_not_in_prior_context: URL이 대화에서 이전에 나타나지 않음(URL 검증 참조)
  • url_not_accessible: 콘텐츠 가져오기 실패(HTTP 오류)
  • too_many_requests: 속도 제한 초과
  • unsupported_content_type: 지원되지 않는 콘텐츠 유형(텍스트, HTML, PDF만 지원)
  • max_uses_exceeded: 최대 web fetch 도구 사용 횟수 초과
  • unavailable: 내부 오류 발생

URL 검증

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

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

이 도구는 Claude 자신의 출력에만 나타나거나 시스템 프롬프트에만 나타나는 URL은 가져올 수 없습니다. 시스템 프롬프트의 URL을 가져올 수 있게 하려면 사용자 메시지에도 해당 URL을 포함하세요. 코드 실행, MCP 커넥터, 도구 검색과 같은 다른 서버 측 도구의 결과도 허용되는 소스가 아닙니다. 클라이언트 측 도구 결과는 Claude가 생성한 텍스트를 그대로 반영하는 경우(예: 입력을 출력하는 명령이나 입력을 인용하는 오류 메시지)에도 허용되는 소스입니다.

또한 이 도구는 API 키나 비밀번호와 같은 자격 증명이 포함된 것으로 보이는 URL을 거부합니다. 단, 해당 자격 증명이 시스템 프롬프트나 사용자 메시지의 텍스트에 나타나는 경우는 예외입니다. 도구 결과에만 나타나는 자격 증명은 이 예외에 해당하지 않습니다. 이 경우 url_not_allowed 오류가 반환됩니다. 이러한 URL을 가져오려면 사용자 메시지에 포함하세요.

검색 및 가져오기 결합

web search 및 web fetch 도구가 모두 활성화되어 있고, 사용자가 URL을 제공하지 않고 특정 페이지 또는 문서를 지정하는 경우(예: "anthropics/anthropic-sdk-python 저장소에서 README를 읽어 주세요"), Claude는 웹 검색을 사용하여 이를 찾은 다음 결과를 가져옵니다. 다음 예제는 하나의 요청에서 검색과 분석을 요청합니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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},
        },
    ],
)
print(response)

이 워크플로에서 Claude는:

  1. 웹 검색을 사용하여 관련 기사를 찾습니다.
  2. 가장 유망한 결과를 선택합니다.
  3. web fetch를 사용하여 전체 콘텐츠를 검색합니다.
  4. 인용과 함께 상세한 분석을 제공합니다.

프롬프트 캐싱

턴 전반에 걸쳐 도구 정의를 캐시하려면 프롬프트 캐싱을 사용한 도구 사용을 참조하세요.

스트리밍

스트리밍이 활성화되면 가져오기 이벤트는 콘텐츠 검색 중 일시 중지와 함께 스트림의 일부가 됩니다:

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's decision to fetch

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}

// Fetch URL streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Pause while fetch executes

// Fetch results streamed
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's response continues...

배치 요청

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

사용량 및 가격

Web fetch(웹 가져오기) 사용에는 표준 토큰 비용 외에 추가 요금이 없습니다:

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

Web fetch 도구는 Claude API에서 추가 비용 없이 사용할 수 있습니다. 대화 컨텍스트의 일부가 되는 가져온 콘텐츠에 대해서만 표준 토큰 비용을 지불합니다.

과도한 토큰을 소비할 수 있는 대용량 콘텐츠를 의도치 않게 가져오는 것을 방지하려면, max_content_tokens 파라미터를 사용하여 사용 사례와 예산 고려 사항에 따라 적절한 한도를 설정하세요.

일반적인 콘텐츠의 토큰 사용량 예시:

  • 평균적인 웹 페이지 (10 kB): 약 2,500 토큰
  • 대용량 문서 페이지 (100 kB): 약 25,000 토큰
  • 연구 논문 PDF (500 kB): 약 125,000 토큰

다음 단계

Code execution 도구

샌드박스 컨테이너에서 Python 및 bash 코드를 실행하여 데이터를 분석하고, 파일을 생성하고, 솔루션을 반복합니다.

서버 도구

Anthropic이 실행하는 도구 작업: server_tool_use 블록, pause_turn 연속, 도메인 필터링.

도구 참조

Anthropic이 제공하는 도구 디렉터리 및 선택적 도구 정의 속성에 대한 참조.

Was this page helpful?