웹 패치 도구

웹 패치 도구 (Web fetch tool)

웹 패치 도구는 Claude가 지정된 웹 페이지와 PDF 문서의 전체 콘텐츠를 가져와서 실시간 웹 콘텐츠로 컨텍스트를 풍부하게 만들어 줘요. 최신 버전(web_fetch_20260318)은 동적 필터링과 응답 포함 제어를 지원해서 에이전트 워크플로에 더 잘 맞춰요. 이 기능에 제로 데이터 보존(ZDR)이 어떻게 적용되는지는 API와 데이터 보존을 참고하세요.

출처: 문서

본문

웹 패치 도구는 Claude가 지정된 웹 페이지와 PDF 문서에서 전체 콘텐츠를 가져올 수 있게 해 줘요.

최신 웹 패치 도구 버전(web_fetch_20260318)은 동적 필터링을 지원해요. 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은 또한 에이전트 워크플로를 위한 응답 포함 제어를 추가했어요. 이전 버전(web_fetch_20260309은 동적 필터링과 캐시 우회, web_fetch_20260209는 동적 필터링 전용, web_fetch_20250910은 기본 패치)는 계속 사용할 수 있어요.

웹 패치(동적 필터링 포함/미포함)는 Claude API, Claude Platform on AWS, Microsoft Foundry에서 사용할 수 있어요. Microsoft Foundry에서 Azure에 호스팅된 배포는 기본 웹 패치 도구만 지원해요(web_fetch_20250910, 동적 필터링 없음). Anthropic에 호스팅된 배포는 모든 버전을 지원해요. 웹 패치는 현재 Amazon Bedrock이나 Google Cloud에서는 사용할 수 없어요.

참고: Claude Mythos Preview의 경우 웹 패치는 Claude API와 Microsoft Foundry에서 사용할 수 있어요. Mythos Preview의 Amazon Bedrock이나 Google Cloud에서는 현재 사용할 수 없어요.

참고: 모델 응답의 품질, API 자체, 또는 문서 품질에 대한 피드백은 피드백 양식으로 보내 주세요.

ZDR 자격과 allowed_callers 해결 방법은 서버 도구를 참고하세요.

경고: Claude가 신뢰할 수 없는 입력을 민감한 데이터와 함께 처리하는 환경에서 웹 패치 도구를 활성화하면 데이터 유출(data exfiltration) 위험이 있어요. 이 도구는 신뢰할 수 있는 환경이나 비민감 데이터를 다룰 때만 사용하세요.

유출 위험을 최소화하기 위해, Claude는 자신의 출력에만 나타나는 URL은 가져올 수 없어요. Claude는 대화에 이전에 나타난 URL만 가져올 수 있어요: 사용자 메시지의 URL, 클라이언트 측 도구 결과의 URL(결과가 Claude가 생성한 텍스트를 반향하더라도), 그리고 이전 웹 검색 또는 웹 패치 결과의 URL (URL 검증 참고). Claude는 또한 API 키나 비밀번호 같은 자격 증명이 포함된 것처럼 보이는 URL은, 그 자격 증명이 시스템 프롬프트나 사용자 메시지 텍스트에 나타나지 않는 한 가져올 수 없어요.

하지만 이 도구를 사용할 때 여전히 신중히 고려해야 할 잔여 위험이 있어요.

데이터 유출이 우려된다면 다음을 고려하세요:

웹 패치 도구를 완전히 비활성화하기

max_uses 매개변수로 요청 수 제한하기

allowed_domains 매개변수로 알려진 안전한 도메인으로 제한하기

모델 지원은 도구 레퍼런스를 참고하세요.

웹 패치가 동작하는 방식

웹 패치는 서버 도구예요. API가 요청 중에 콘텐츠를 가져와서 결과를 대화에 삽입해요. 당신은 아무것도 실행하거나 tool_result를 반환하지 않아요. 예외는 Claude가 같은 병렬 도구 호출 그룹에서 웹 패치와 당신의 클라이언트 도구 중 하나를 함께 호출할 때예요. 이 경우 API는 그 패치가 실행되기 전에 stop_reason: "tool_use"로 응답을 반환하고, 당신이 클라이언트 tool_result 블록을 다시 보내면 패치를 실행해요. 한 턴에서 서버 도구와 클라이언트 도구 혼합하기를 참고하세요.

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

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

참고: 웹 패치 도구는 현재 JavaScript로 동적으로 렌더링되는 웹사이트를 지원하지 않아요. 실제 브라우저가 필요한 페이지(JavaScript 렌더링, 클릭, 폼 작성)는 browser use 도구를 고려해 보세요. 이는 당신의 애플리케이션이 브라우저를 구동하고 페이지 텍스트나 스크린샷을 도구 결과로 Claude에 반환하는 클라이언트 도구예요.

Claude가 언제 가져오는지

Claude는 요청이 특정 페이지나 문서를 가리킬 때 가져와요:

URL이 대화(또는 이전 도구 결과)에 제공될 때
사용자가 URL 없이 특정 리소스(특정 기사, README, 가격 페이지, 문서 섹션)를 지명하고, 웹 검색 도구도 활성화되어 있어 Claude가 먼저 찾을 수 있을 때 (결합된 검색과 패치 참고)

Claude는 특정 페이지를 참조하지 않는 일반 지식이나 개방형 질문에는 가져오지 않아요. "이 기사를 요약해 줘: <url>"은 패치를 트리거해요. "REST API 설계의 모범 사례는 뭐야?"는 직접 답변돼요.

동적 필터링

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

이 동적 필터링은 특히 다음에 유용해요:

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

참고: 동적 필터링은 코드 실행 도구에서 실행돼요. API가 요청에 대해 자동으로 활성화해요. tools 배열에 코드 실행 도구를 추가할 필요가 없어요.

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

```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "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" }] }' ```

ant messages create <<'YAML'
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
YAML

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)

const client = new Anthropic();

const response = await 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" }]
});

console.log(response);

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_8,
    MaxTokens = 4096,
    Messages = [new() { Role = Role.User, Content = "Fetch the content at https://example.com/research-paper and extract the key findings." }],
    Tools = [new ToolUnion(new WebFetchTool20260318())]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);

client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     anthropic.ModelClaudeOpus4_8,
	MaxTokens: 4096,
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(anthropic.NewTextBlock("Fetch the content at https://example.com/research-paper and extract the key findings.")),
	},
	Tools: []anthropic.ToolUnionParam{
		{OfWebFetchTool20260318: &anthropic.WebFetchTool20260318Param{}},
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(response.RawJSON())

import com.anthropic.models.messages.WebFetchTool20260318;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_8)
        .maxTokens(4096L)
        .addUserMessage("Fetch the content at https://example.com/research-paper and extract the key findings.")
        .addTool(WebFetchTool20260318.builder().build())
        .build();

    Message response = client.messages().create(params);
    IO.println(response);
}

$client = new Client();

$message = $client->messages->create(
    maxTokens: 4096,
    messages: [
        ['role' => 'user', 'content' => 'Fetch the content at https://example.com/research-paper and extract the key findings.']
    ],
    model: 'claude-opus-4-8',
    tools: [[
        'type' => 'web_fetch_20260318',
        'name' => 'web_fetch',
    ]],
);
echo $message;

client = Anthropic::Client.new

message = 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"
  }]
)
puts message

웹 패치 사용법

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

```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "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 }] }' ```

ant messages create \
  --model claude-opus-4-8 \
  --max-tokens 1024 \
  --message '{role: user, content: "Please analyze the content at https://example.com/article"}' \
  --tool '{type: web_fetch_20250910, name: web_fetch, max_uses: 5}'

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)

const client = new Anthropic();

const response = await 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
    }
  ]
});

console.log(response);

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_8,
    MaxTokens = 1024,
    Messages = [new() { Role = Role.User, Content = "Please analyze the content at https://example.com/article" }],
    Tools = [new ToolUnion(new WebFetchTool20250910() { MaxUses = 5 })]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);

client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     anthropic.ModelClaudeOpus4_8,
	MaxTokens: 1024,
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(anthropic.NewTextBlock("Please analyze the content at https://example.com/article")),
	},
	Tools: []anthropic.ToolUnionParam{
		{OfWebFetchTool20250910: &anthropic.WebFetchTool20250910Param{
			MaxUses: anthropic.Int(5),
		}},
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(response.RawJSON())

import com.anthropic.models.messages.WebFetchTool20250910;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_8)
        .maxTokens(1024L)
        .addUserMessage("Please analyze the content at https://example.com/article")
        .addTool(WebFetchTool20250910.builder()
            .maxUses(5L)
            .build())
        .build();

    Message response = client.messages().create(params);
    IO.println(response);
}

$client = new Client();

$message = $client->messages->create(
    maxTokens: 1024,
    messages: [
        ['role' => 'user', 'content' => 'Please analyze the content at https://example.com/article']
    ],
    model: 'claude-opus-4-8',
    tools: [[
        'type' => 'web_fetch_20250910',
        'name' => 'web_fetch',
        'max_uses' => 5,
    ]],
);
echo $message;

client = Anthropic::Client.new

message = 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
  }]
)
puts message

도구 정의

웹 패치 도구는 다음 매개변수를 지원해요:

{
  "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)

max_uses 매개변수는 수행되는 웹 패치 횟수를 제한해요. 실패한 패치도 한도에 포함돼요. Claude가 허용된 횟수보다 더 패치를 시도하면, web_fetch_tool_result는 max_uses_exceeded 오류 코드를 가진 오류가 돼요. 현재 기본 한도는 없어요.

도메인 필터링

allowed_domains와 blocked_domains로 도메인 필터링을 하려면 서버 도구를 참고하세요.

Claude Managed Agents에서는 에이전트 도구셋의 web_fetch 항목에 이 필드를 설정하세요. 이때 나열된 각 도메인은 경로가 없는 일반 호스트 이름이어야 해요. 웹 검색 및 웹 패치 도메인 제한하기를 참고하세요.

콘텐츠 한도

max_content_tokens 매개변수는 컨텍스트에 포함되는 콘텐츠의 양을 제한해요. 가져온 콘텐츠가 이 한도를 초과하면 도구가 잘라내요. 이는 큰 문서를 가져올 때 토큰 사용을 제어하는 데 도움이 돼요. 이 한도는 텍스트 콘텐츠에 적용되며, PDF 같은 이진 콘텐츠에는 적용되지 않아요.

참고: max_content_tokens 매개변수 한도는 근사치예요. 실제 사용되는 입력 토큰 수는 약간 달라질 수 있어요.

Claude Managed Agents에서 에이전트 도구셋의 web_fetch 항목도 max_content_tokens를 허용해요. 웹 검색 및 웹 패치 도메인 제한하기를 참고하세요.

캐시 우회 (Cache bypass)

참고: web_fetch_20260309 이상(web_fetch_20260318 포함)이 필요해요.

use_cache 매개변수는 캐시된 콘텐츠가 반환될 수 있는지 제어해요. "use_cache": false를 설정하면 캐시를 우회하고 새 콘텐츠를 가져와요. 기본값은 true예요. 캐시 우회는 지연 시간을 늘리므로, 사용자가 새 콘텐츠를 명시적으로 요청하거나 빠르게 변하는 소스를 가져올 때만 캐시를 비활성화하세요.

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

응답 포함 (Response inclusion)

참고: web_fetch_20260318 이상이 필요해요.

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

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

인용 (Citations)

항상 활성화되는 웹 검색과 달리, 웹 패치의 인용은 선택 사항이며 기본적으로 비활성화돼 있어요. "citations": {"enabled": true}를 설정하면 Claude가 가져온 문서의 특정 구절을 인용할 수 있어요.

참고: API 출력을 최종 사용자에게 직접 표시할 때는 원본 소스에 대한 인용을 포함하세요. API 출력을 수정할 때(재처리하거나 당신의 자료와 결합해서 최종 사용자에게 표시하기 전에)는 법무팀과 상의한 대로 적절히 인용을 표시하세요.

응답 (Response)

응답 구조 예시예요:

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

패치 결과 (Fetch results)

패치 결과는 다음을 포함해요:

url: 가져온 URL
content: 가져온 콘텐츠를 담은 문서 블록
retrieved_at: 콘텐츠가 가져와진 타임스탬프

참고: 웹 패치 도구는 성능을 개선하고 중복 요청을 줄이기 위해 결과를 캐시해요. 반환되는 콘텐츠가 URL의 최신 버전을 항상 반영하지는 않을 수 있어요. 캐시 동작은 자동으로 관리되며 콘텐츠 유형과 사용 패턴에 맞춰 시간이 지나며 바뀔 수 있어요. 새 콘텐츠를 가져오려면 "use_cache": false를 설정하세요(캐시 우회 참고).

PDF 문서의 경우 콘텐츠는 base64로 인코딩된 데이터로 반환돼요:

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

오류 (Errors)

웹 패치 도구가 오류를 만나면 Claude API는 200(성공) 응답을 반환하고 오류를 응답 본문에 표현해요. Claude는 오류 결과를 보고 턴을 계속해요. 예시:

{
  "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: 웹 패치 도구 최대 사용 횟수 초과
unavailable: 내부 오류 발생

URL 검증 (URL validation)

보안상의 이유로 웹 패치 도구는 대화 컨텍스트에 이전에 나타난 URL만 가져올 수 있어요. 여기에는 다음이 포함돼요:

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

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

이 도구는 또한 API 키나 비밀번호 같은 자격 증명이 포함된 것처럼 보이는 URL을 거부해요. 단, 그 자격 증명이 시스템 프롬프트나 사용자 메시지 텍스트에 나타나는 경우는 제외예요. 도구 결과에만 나타나는 자격 증명은 인정되지 않아요. 결과는 url_not_allowed 오류예요. 그런 URL을 가져오려면 사용자 메시지에 포함하세요.

결합된 검색과 패치 (Combined search and fetch)

웹 검색과 웹 패치 도구가 모두 활성화되어 있고, 사용자가 URL 없이 특정 페이지나 문서를 지명하면(예: "anthropics/anthropic-sdk-python 저장소에서 README를 읽어 줘"), Claude는 웹 검색으로 위치를 찾은 다음 결과를 패치해요. 다음 예시는 한 요청에서 검색과 분석을 함께 요청해요:

```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "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} } ] }' ```

ant messages create <<'YAML'
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
YAML

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)

const client = new Anthropic();

const response = await 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 }
    }
  ]
});

console.log(response);

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_8,
    MaxTokens = 4096,
    Messages = [new() { Role = Role.User, Content = "Find recent articles about quantum computing and analyze the most relevant one in detail" }],
    Tools = [
        new ToolUnion(new WebSearchTool20250305() { MaxUses = 3 }),
        new ToolUnion(new WebFetchTool20250910() { MaxUses = 5, Citations = new() { Enabled = true } })
    ]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);

client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     anthropic.ModelClaudeOpus4_8,
	MaxTokens: 4096,
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(anthropic.NewTextBlock("Find recent articles about quantum computing and analyze the most relevant one in detail")),
	},
	Tools: []anthropic.ToolUnionParam{
		{OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{
			MaxUses: anthropic.Int(3),
		}},
		{OfWebFetchTool20250910: &anthropic.WebFetchTool20250910Param{
			MaxUses:   anthropic.Int(5),
			Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
		}},
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(response.RawJSON())

import com.anthropic.models.messages.CitationsConfigParam;
// ...
import com.anthropic.models.messages.WebFetchTool20250910;
import com.anthropic.models.messages.WebSearchTool20250305;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_8)
        .maxTokens(4096L)
        .addUserMessage("Find recent articles about quantum computing and analyze the most relevant one in detail")
        .addTool(WebSearchTool20250305.builder()
            .maxUses(3L)
            .build())
        .addTool(WebFetchTool20250910.builder()
            .maxUses(5L)
            .citations(CitationsConfigParam.builder().enabled(true).build())
            .build())
        .build();

    Message response = client.messages().create(params);
    IO.println(response);
}

$client = new Client();

$message = $client->messages->create(
    maxTokens: 4096,
    messages: [
        ['role' => 'user', 'content' => 'Find recent articles about quantum computing and analyze the most relevant one in detail']
    ],
    model: 'claude-opus-4-8',
    tools: [
        [
            'type' => 'web_search_20250305',
            'name' => 'web_search',
            'max_uses' => 3,
        ],
        [
            'type' => 'web_fetch_20250910',
            'name' => 'web_fetch',
            'max_uses' => 5,
            'citations' => ['enabled' => true],
        ],
    ],
);
echo $message;

client = Anthropic::Client.new

message = 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 }
    }
  ]
)
puts message

이 워크플로에서 Claude는:

웹 검색으로 관련 기사를 찾아요.
가장 유망한 결과를 선택해요.
웹 패치로 전체 콘텐츠를 가져와요.
인용과 함께 상세한 분석을 제공해요.

프롬프트 캐싱

여러 턴에 걸쳐 도구 정의를 캐시하려면 프롬프트 캐싱과 함께하는 도구 사용을 참고하세요.

스트리밍 (Streaming)

스트리밍을 활성화하면 패치 이벤트가 콘텐츠 검색 중 일시 정지와 함께 스트림의 일부가 돼요:

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...

배치 요청 (Batch requests)

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

사용 및 가격 (Usage and pricing)

웹 패치 사용에는 표준 토큰 비용 외에 추가 요금이 없어요:

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

웹 패치 도구는 Claude API에서 추가 비용 없이 사용할 수 있어요. 당신은 대화 컨텍스트의 일부가 되는 가져온 콘텐츠에 대한 표준 토큰 비용만 지불해요.

실수로 많은 토큰을 소모하는 큰 콘텐츠를 가져오지 않도록, max_content_tokens 매개변수로 사용 사례와 예산 고려에 맞는 적절한 한도를 설정하세요.

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

평균 웹 페이지(10 kB): ~2,500 토큰
큰 문서 페이지(100 kB): ~25,000 토큰
연구 논문 PDF(500 kB): ~125,000 토큰

다음 단계 (Next steps)

Run Python and bash code in a sandboxed container to analyze data, generate files, and iterate on solutions. Work with Anthropic-executed tools: server\_tool\_use blocks, pause\_turn continuation, and domain filtering. Directory of Anthropic-provided tools and reference for optional tool definition properties.

웹 패치 도구