---
title: 웹 가져오기 도구
url: https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool
description: 특정 URL에서 콘텐츠를 가져와 읽어 실시간 웹 콘텐츠로 Claude의 컨텍스트를 보강합니다.
featureMetadata:
status: stable
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). 가져온 웹 콘텐츠가 API 응답으로 반환됩니다. 웹 가져오기의 동적 필터링은 ZDR 또는 HIPAA 적격 대상이 아닙니다. 웹사이트 게시자는 자체 정책에 따라 요청 데이터(가져온 URL 및 요청 메타데이터 등)를 보존할 수 있습니다.
supportedModels:
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-mythos-preview
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-haiku-5-5
- claude-haiku-4-5-20251001
- claude-opus-4-8
- claude-opus-4-7
- claude-opus-4-6
- claude-sonnet-4-6
- claude-opus-4-5-20251101
- claude-sonnet-4-5-20250929
supportedPlatforms:
Claude API: stable
Claude Platform on AWS: stable
Claude Models on Google Cloud (Anthropic managed): stable
Microsoft Foundry:
availability: stable
note: Azure에서 호스팅되는 배포는 `web_fetch_20250910`만 지원합니다. 동적 필터링, 응답 포함, 캐시 우회는 지원되지 않습니다.
---
**API 지원**: 제품별로 사용법이 다릅니다.
* **Messages API**: 요청의 `tools`에 `web_fetch` 도구를 추가하세요.
* **Managed Agents**: 에이전트 도구 세트에서 기본적으로 켜져 있으며, `max_uses`, `citations`, `cache_control`은 지원되지 않습니다.
웹 가져오기 도구를 사용하면 Claude가 지정된 웹페이지와 PDF 문서에서 전체 콘텐츠를 가져올 수 있습니다.
최신 웹 가져오기 도구 버전(`web_fetch_20260318`)은 **dynamic filtering**(동적 필터링)을 지원합니다. Claude는 가져온 콘텐츠가 컨텍스트 윈도우에 도달하기 전에 코드를 작성하고 실행하여 필터링할 수 있으며, 관련 정보만 유지하고 나머지는 버립니다. 이를 통해 응답 품질을 유지하면서 토큰 소비를 줄일 수 있습니다. 동적 필터링은 Claude 4.6 이상 모델과 [Claude Mythos Preview](https://anthropic.com/glasswing)에서 사용할 수 있습니다. `web_fetch_20260318`은 에이전트 워크플로를 위한 [응답 포함](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#response-inclusion) 제어 기능도 추가합니다. 다른 버전(동적 필터링 및 [캐시 우회](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#cache-bypass)를 위한 `web_fetch_20260309`, 동적 필터링만 지원하는 `web_fetch_20260209`, 기본 가져오기를 위한 `web_fetch_20250910`)도 사용할 수 있습니다.
웹 가져오기(동적 필터링 포함 및 미포함)는 Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry)에서 사용할 수 있습니다. Microsoft Foundry에서 [Azure에 호스팅된](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure) 배포는 기본 웹 가져오기 도구(`web_fetch_20250910`, 동적 필터링 미포함)만 지원합니다. Anthropic에 호스팅된 배포는 모든 버전을 지원합니다.
[Claude Mythos Preview](https://anthropic.com/glasswing)의 경우 웹 가져오기는 Claude API와 Microsoft Foundry에서 사용할 수 있습니다.
모델 응답의 품질, API 자체 또는 문서의 품질에 대한 피드백을 제공하려면 [피드백 양식](https://forms.gle/NhWcgmkcvPCMmPE86)을 사용하세요.
제로 데이터 보존(Zero Data Retention) 적격성과 `allowed_callers` 해결 방법에 대해서는 [서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers)를 참조하세요.
Claude가 민감한 데이터와 함께 신뢰할 수 없는 입력을 처리하는 환경에서 웹 가져오기 도구를 활성화하면 데이터 유출 위험이 발생합니다. 이 도구는 신뢰할 수 있는 환경에서만 사용하거나 민감하지 않은 데이터를 처리할 때만 사용하세요.
유출 위험을 최소화하기 위해 Claude는 자신의 출력에만 나타나는 URL을 가져올 수 없습니다. Claude는 이전에 대화에 나타난 URL만 가져올 수 있습니다. 여기에는 사용자 메시지의 URL, 클라이언트 측 도구 결과의 URL, 이전 웹 검색 또는 웹 가져오기 결과의 URL이 포함됩니다([URL 검증](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#url-validation) 참조). 또한 Claude는 API 키나 비밀번호와 같은 자격 증명을 포함하는 것으로 보이는 URL은, 해당 자격 증명이 시스템 프롬프트나 사용자 메시지 텍스트에 나타나지 않는 한 가져올 수 없습니다.
그러나 이 도구를 사용할 때 신중하게 고려해야 할 잔여 위험은 여전히 존재합니다.
데이터 유출이 우려되는 경우 다음을 고려하세요:
* 웹 가져오기 도구를 완전히 비활성화
* [`max_uses`](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#max-uses) 매개변수를 사용하여 한 턴의 가져오기 횟수 제한
* `allowed_domains` 매개변수를 사용하여 알려진 안전한 도메인으로 제한
* `url_sources` 매개변수를 사용하여 클라이언트 측 도구 결과가 출처로 간주되지 않도록 설정([URL 출처](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#url-sources) 참조)
모델 지원에 대해서는 [도구 참조](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference)를 참조하세요.
## 웹 가져오기 작동 방식
웹 가져오기는 [서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools)입니다. API가 요청 중에 콘텐츠를 가져와 결과를 대화에 삽입합니다. 사용자가 무언가를 실행하거나 `tool_result`를 반환할 필요가 없습니다. 예외는 Claude가 동일한 병렬 도구 호출 그룹에서 웹 가져오기와 클라이언트 도구 중 하나를 함께 호출하는 경우입니다. 이때 API는 해당 가져오기가 실행되기 전에 `stop_reason: "tool_use"`와 함께 응답을 반환하고, 사용자가 클라이언트 `tool_result` 블록을 다시 보내면 가져오기를 실행합니다. [한 턴에서 서버 도구와 클라이언트 도구 혼합하기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn)를 참조하세요.
API 요청에 웹 가져오기 도구를 추가하면:
1. Claude는 프롬프트와 사용 가능한 URL을 기반으로 콘텐츠를 가져올 시점을 결정합니다.
2. API는 지정된 URL에서 전체 텍스트 콘텐츠를 가져옵니다.
3. PDF의 경우 API는 콘텐츠를 base64로 인코딩된 데이터로 반환하고, 직접 첨부된 PDF 문서처럼 처리합니다.
4. Claude는 가져온 콘텐츠를 분석하고 선택적 인용과 함께 응답을 제공합니다.
웹 가져오기 도구는 현재 JavaScript로 동적 렌더링되는 웹사이트를 지원하지 않습니다. 실제 브라우저가 필요한 페이지(JavaScript 렌더링, 클릭 또는 양식 작성)의 경우 [브라우저 사용 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool)를 고려하세요. 이는 애플리케이션이 브라우저를 구동하고 페이지 텍스트나 스크린샷을 도구 결과로 Claude에 반환하는 클라이언트 도구입니다.
### Claude가 가져오기를 수행하는 경우
Claude는 요청이 특정 페이지나 문서를 가리킬 때 가져오기를 수행합니다:
* 대화(또는 이전 도구 결과)에 URL이 제공된 경우
* 사용자가 URL 없이 특정 리소스(특정 기사, README, 가격 페이지 또는 문서 섹션)를 지칭하고, Claude가 먼저 이를 찾을 수 있도록 [웹 검색 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool)도 활성화된 경우([검색과 가져오기 결합](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#combined-search-and-fetch) 참조)
Claude는 특정 페이지를 참조하지 않는 일반 지식 질문이나 개방형 질문에 대해서는 가져오기를 수행하지 **않습니다**. "이 기사를 요약해 줘: ``"은 가져오기를 트리거합니다. “REST API 설계의 모범 사례는 무엇인가요?”는 직접 답변됩니다.
### 동적 필터링
전체 웹페이지와 PDF를 가져오면 특히 대용량 문서에서 특정 정보만 필요한 경우 토큰이 빠르게 소비될 수 있습니다. `web_fetch_20260209` 이상을 사용하면 Claude는 가져온 콘텐츠를 컨텍스트에 로드하기 전에 코드를 작성하고 실행하여 필터링할 수 있습니다.
이 동적 필터링은 특히 다음과 같은 경우에 유용합니다:
* 긴 문서에서 특정 섹션 추출
* 웹페이지에서 구조화된 데이터 처리
* PDF에서 관련 정보 필터링
* 대용량 문서 작업 시 토큰 비용 절감
동적 필터링은 [코드 실행 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool)에서 실행되며, API가 해당 요청에 대해 자동으로 활성화합니다. `tools` 배열에 코드 실행 도구를 추가할 필요가 없습니다.
동적 필터링을 활성화하려면 `web_fetch_20260209` 또는 그 이후 버전을 사용하세요. 다음 예제는 `web_fetch_20260318`을 사용합니다:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"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"
}]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--message '{role: user, content: "Fetch the content at https://example.com/research-paper and extract the key findings."}' \
--tool '{type: web_fetch_20260318, name: web_fetch}'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
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);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [new UserMessageParam { 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);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
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())
```
```java Java
import com.anthropic.models.messages.WebFetchTool20260318;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.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);
}
```
```php PHP
$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: Model::CLAUDE_OPUS_5_5,
tools: [[
'type' => 'web_fetch_20260318',
'name' => 'web_fetch',
]],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
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
```
## 웹 가져오기 사용 방법
조직 관리자는 Claude Console의 [**기능**](https://platform.claude.com/settings/capabilities) 페이지에서 조직의 웹 가져오기를 끌 수 있습니다. 웹 가져오기가 꺼져 있으면 해당 도구를 포함하는 Messages API 요청은 웹 가져오기가 활성화되지 않았다는 400 `invalid_request_error`와 함께 실패합니다. 웹 가져오기가 켜져 있으면 관리자는 같은 페이지에서 웹 가져오기에 대해 허용 또는 차단 도메인을 설정할 수도 있습니다. 이러한 목록이 요청에 적용되는 방식은 [도메인 필터링](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools#domain-filtering)을 참조하세요.
조직의 웹 가져오기 설정이 Claude Managed Agents 세션에 적용되는 방식은 [웹 검색 및 웹 가져오기 도메인 제한](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions)을 참조하세요.
API 요청에 웹 가져오기 도구를 제공하세요:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "Please analyze the content at https://example.com/article"
}
],
"tools": [{
"type": "web_fetch_20250910",
"name": "web_fetch",
"max_uses": 5
}]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--message '{role: user, content: "Please analyze the content at https://example.com/article"}' \
--tool '{type: web_fetch_20250910, name: web_fetch, max_uses: 5}'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
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);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [new UserMessageParam { 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);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
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())
```
```java Java
import com.anthropic.models.messages.WebFetchTool20250910;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.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);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Please analyze the content at https://example.com/article']
],
model: Model::CLAUDE_OPUS_5_5,
tools: [[
'type' => 'web_fetch_20250910',
'name' => 'web_fetch',
'max_uses' => 5,
]],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 4096,
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
```
## 도구 정의
웹 가져오기 도구는 다음 매개변수를 지원합니다:
```json JSON
{
"type": "web_fetch_20250910",
"name": "web_fetch",
// Optional: Limit the number of fetches
"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: Don't fetch URLs that appear only in client-side tool results
"url_sources": {
"client_tool_results": { "type": "none" }
},
// Optional: Enable citations for fetched content
"citations": {
"enabled": true
},
// Optional: Maximum content length in tokens
"max_content_tokens": 100000
}
```
이후 도구 버전에서는 두 개의 선택적 매개변수가 추가됩니다. `use_cache`는 `web_fetch_20260309` 이상이 필요하며([캐시 우회](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#cache-bypass) 참조), `response_inclusion`은 `web_fetch_20260318` 이상이 필요합니다([응답 포함](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#response-inclusion) 참조).
### 최대 사용 횟수
`max_uses` 매개변수는 단일 턴에서 수행되는 웹 가져오기 횟수를 제한합니다. 실패한 가져오기도 제한에 포함됩니다. Claude가 허용된 것보다 더 많이 웹 가져오기를 직접 호출하면 `web_fetch_tool_result`는 `max_uses_exceeded` 오류 코드가 포함된 오류가 됩니다. Claude가 코드 실행에서 허용된 것보다 더 많이 웹 가져오기를 호출하면 코드 실행 작업이 오류와 함께 종료됩니다. 기본 제한은 없습니다.
하나의 턴은 여러 요청에 걸쳐 이어질 수 있습니다. 요청이 [`pause_turn`](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn) 이후에 재개되거나 마지막 메시지에 `tool_result` 블록만 포함된 경우, 해당 요청은 턴을 이어 갑니다. 해당 턴의 이전 요청에서 수행된 가져오기는 제한에 포함됩니다. 단, Claude가 [동적 필터링](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#dynamic-filtering)을 통해 코드 실행에서 수행한 가져오기는 예외입니다.
### 도메인 필터링
`allowed_domains` 및 `blocked_domains`를 사용한 도메인 필터링에 대해서는 [서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools#domain-filtering)를 참조하세요.
[Claude Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview)에서는 에이전트 도구 세트의 `web_fetch` 항목에 이러한 필드를 설정하세요. [웹 검색 및 웹 가져오기 도메인 제한](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions)을 참조하세요.
### 콘텐츠 제한
`max_content_tokens` 매개변수는 컨텍스트에 포함되는 콘텐츠의 양을 제한합니다. 가져온 콘텐츠가 이 제한을 초과하면 도구가 이를 잘라냅니다. 이는 대용량 문서를 가져올 때 토큰 사용량을 제어하는 데 도움이 됩니다. 이 제한은 근사치이며, 실제로 사용되는 입력 토큰 수는 약간 달라질 수 있습니다. 이 제한은 텍스트 콘텐츠에 적용되며, PDF와 같은 바이너리 콘텐츠에는 적용되지 않습니다.
가져온 PDF로 인해 요청이 [PDF 페이지 또는 크기 제한](https://platform.claude.com/docs/ko/build-with-claude/pdf-support#check-pdf-requirements)을 초과하게 되면 `web_fetch_tool_result`는 `content_too_large` 오류 코드가 포함된 오류가 됩니다. 대화에 이미 있는 PDF와 이미지도 이러한 제한에 포함되므로, 해당 PDF와 이미지를 제거하면 가져오기가 성공할 수 있습니다.
Claude Managed Agents에서는 에이전트 도구 세트의 `web_fetch` 항목도 `max_content_tokens`를 허용합니다. [웹 도구 설정](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions#settings)을 참조하세요.
### 캐시 우회
`web_fetch_20260309` 이상(`web_fetch_20260318` 포함)이 필요합니다.
`use_cache` 매개변수는 캐시된 콘텐츠를 반환할 수 있는지 여부를 제어합니다. 캐시를 우회하고 새로운 콘텐츠를 가져오려면 `"use_cache": false`를 설정하세요. 기본값은 `true`입니다. 캐시를 우회하면 지연 시간이 늘어나므로, 사용자가 명시적으로 최신 콘텐츠를 요청하거나 빠르게 변하는 소스를 가져올 때만 캐싱을 비활성화하세요.
```json
{
"tools": [
{
"type": "web_fetch_20260309",
"name": "web_fetch",
"use_cache": false
}
]
}
```
### 응답 포함
`web_fetch_20260318` 이상이 필요합니다.
`response_inclusion` 매개변수는 같은 응답에서 완료된 [코드 실행](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool) 호출이 가져오기 결과를 사용한 경우, 가져오기 결과 블록이 API 응답에 표시되는 방식을 제어합니다. 원시 페이지 콘텐츠가 필요 없는 에이전트 워크플로의 경우 `"response_inclusion": "excluded"`를 설정하면 중첩된 `server_tool_use` 및 결과 블록 쌍이 응답에서 완전히 제거됩니다. Claude는 이러한 블록이 아니라 코드의 출력을 읽으므로 토큰 사용량에는 영향이 없습니다. 기본값은 `"full"`입니다. API는 직접 호출의 결과나 완료 전에 일시 중지된 코드 실행 호출의 결과를 다음 요청에서 다시 보낼 수 있도록 항상 전체를 반환합니다.
```json
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"response_inclusion": "excluded"
}
]
}
```
### 인용
인용이 항상 활성화되는 웹 검색과 달리, 웹 가져오기에서 인용은 선택 사항이며 기본적으로 비활성화되어 있습니다. Claude가 가져온 문서의 특정 구절을 인용할 수 있도록 하려면 `"citations": {"enabled": true}`를 설정하세요.
API 출력을 최종 사용자에게 직접 표시할 때는 원본 소스에 대한 인용을 포함하세요. API 출력을 수정하는 경우, 최종 사용자에게 표시하기 전에 재처리하거나 자체 자료와 결합하는 경우를 포함하여, 법무팀과의 협의를 바탕으로 적절하게 인용을 표시하세요.
## 응답
다음은 응답 구조의 예입니다:
```json 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`: 콘텐츠를 가져온 시점의 타임스탬프
웹 가져오기 도구는 성능을 향상하고 중복 요청을 줄이기 위해 결과를 캐시합니다. 반환된 콘텐츠가 항상 해당 URL에서 사용 가능한 최신 버전을 반영하지 않을 수 있습니다. 캐시 동작은 자동으로 관리되며, 다양한 콘텐츠 유형과 사용 패턴에 최적화하기 위해 시간이 지남에 따라 변경될 수 있습니다. 최신 콘텐츠를 가져오려면 `"use_cache": false`를 설정하세요([캐시 우회](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#cache-bypass) 참조).
PDF 문서의 경우 콘텐츠는 base64로 인코딩된 데이터로 반환됩니다:
```json 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(성공) 응답을 반환하며, 오류는 응답 본문에 표시됩니다. Claude는 오류 결과를 받고 턴을 계속 진행합니다. 예를 들면 다음과 같습니다:
```json 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`: 도메인 필터링 규칙(조직 설정 포함) 또는 비공개 주소, `robots.txt`, 사용자가 제공하지 않은 자격 증명을 포함하는 것으로 보이는 URL과 같은 Anthropic 측 제한에 의해 URL이 차단됨
* `url_not_in_prior_context`: URL이 대화에 이전에 나타나지 않았거나, `url_sources`가 제외하는 출처에만 나타남([URL 검증](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#url-validation) 참조)
* `url_not_accessible`: 콘텐츠 가져오기 실패(HTTP 오류)
* `too_many_requests`: 속도 제한 초과
* `unsupported_content_type`: 지원되지 않는 콘텐츠 유형(텍스트, HTML, PDF만 지원)
* `content_too_large`: 가져온 PDF로 인해 요청이 PDF 페이지 또는 크기 제한을 초과하게 됨([콘텐츠 제한](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#content-limits) 참조)
* `max_uses_exceeded`: 최대 웹 가져오기 도구 사용 횟수 초과
* `unavailable`: 내부 오류 발생
## URL 검증
보안상의 이유로 웹 가져오기 도구는 대화 컨텍스트에 이전에 나타난 URL만 가져올 수 있습니다. 여기에는 다음이 포함됩니다:
* 사용자 메시지의 URL
* 클라이언트 측 도구 결과의 URL
* 이전 웹 검색 또는 웹 가져오기 결과의 URL
이 도구는 Claude 자신의 출력에만 나타나거나 시스템 프롬프트에만 나타나는 URL은 가져올 수 없습니다. 시스템 프롬프트의 URL을 가져올 수 있게 하려면 사용자 메시지에도 포함하세요. [코드 실행](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool), [MCP 커넥터](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector), [도구 검색](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool)과 같은 다른 서버 측 도구의 결과도 허용된 출처가 아닙니다. 기본적으로 클라이언트 측 도구 결과는 Claude가 생성한 텍스트를 그대로 반영하는 경우(예: 입력을 출력하는 명령이나 입력을 인용하는 오류 메시지)에도 허용된 출처입니다.
또한 이 도구는 API 키나 비밀번호와 같은 자격 증명을 포함하는 것으로 보이는 URL을, 해당 자격 증명이 시스템 프롬프트나 사용자 메시지 텍스트에 나타나지 않는 한 거부합니다. 도구 결과에만 나타나는 자격 증명은 인정되지 않습니다. 결과는 `url_not_allowed` 오류입니다. 이러한 URL을 가져오려면 사용자 메시지에 포함하세요.
### URL 출처
`web_fetch_20250910`, `web_fetch_20260209`, `web_fetch_20260309`, `web_fetch_20260318`에서 작동합니다.
선택적 `url_sources` 매개변수를 사용하면 세 가지 허용된 출처 중 어느 것이든 끄거나, 도구 결과를 특정 도구로 제한할 수 있습니다. 각 출처마다 하나의 키가 있으며, 모든 키의 기본값은 `{"type": "all"}`입니다:
* `user_input`: 사용자 메시지의 URL입니다. `type`은 `"all"` 또는 `"none"`입니다.
* `client_tool_results`: 클라이언트 측 도구 결과의 URL입니다. `type`은 `"all"`, `"none"` 또는 다음 예제와 같이 도구 이름을 지정하는 `"only"` 또는 `"except"` 필터입니다.
* `server_tool_results`: 이전 웹 검색 또는 웹 가져오기 결과의 URL입니다. 동일한 값을 사용하며, 필터에는 `web_search` 또는 `web_fetch`를 지정합니다.
예를 들어 Claude가 작성한 코드를 실행하는 도구는 해당 코드가 출력하는 모든 내용을 반환하며, 여기에는 Claude가 넣은 URL도 포함됩니다. 해당 도구의 결과가 출처로 간주되지 않도록 하려면 `"except"` 필터에 해당 도구 이름을 지정하세요:
```json
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"url_sources": {
"client_tool_results": {
"type": "except",
"tools": [{ "type": "tool_reference", "name": "run_code" }]
}
}
},
{
"name": "run_code",
"description": "Run Python code and return its output",
"input_schema": {
"type": "object",
"properties": { "code": { "type": "string" } },
"required": ["code"]
}
}
]
}
```
필터는 도구를 `tool_reference` 객체로 나열합니다. 각 이름은 요청의 `tools` 배열에 있는 도구와 일치해야 합니다. `client_tool_results`의 경우 클라이언트 도구, `server_tool_results`의 경우 서버 도구여야 합니다. 그렇지 않으면 요청이 오류와 함께 실패합니다. `"except"`에서는 나중에 `tools`에 추가하는 도구가 출처로 간주됩니다. `"only"`에서는 간주되지 않습니다.
`run_code` 이외의 클라이언트 측 도구도 Claude가 작성한 텍스트를 반환할 수 있습니다(예: 해당 텍스트를 인용하는 오류 메시지). 모든 클라이언트 측 도구 결과를 제외하려면 `client_tool_results`를 `{"type": "none"}`으로 설정하세요.
URL이 `url_sources`가 제외하는 출처에만 나타난 경우, 해당 URL을 가져오면 `url_not_in_prior_context` 오류가 반환됩니다.
## 검색과 가져오기 결합
웹 검색 도구와 웹 가져오기 도구가 모두 활성화되어 있고 사용자가 URL을 제공하지 않고 특정 페이지나 문서를 지칭하는 경우(예: “anthropics/anthropic-sdk-python 저장소의 README를 읽어 줘”), Claude는 웹 검색을 사용하여 이를 찾은 다음 결과를 가져옵니다. 다음 예제는 한 번의 요청으로 검색과 분석을 요청합니다:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"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}
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
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
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
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);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [new UserMessageParam { 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);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
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())
```
```java Java
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_5_5)
.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);
}
```
```php PHP
$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: Model::CLAUDE_OPUS_5_5,
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;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
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는:
1. 웹 검색을 사용하여 관련 기사를 찾습니다.
2. 가장 유망한 결과를 선택합니다.
3. 웹 가져오기를 사용하여 전체 콘텐츠를 가져옵니다.
4. 인용과 함께 상세한 분석을 제공합니다.
## 프롬프트 캐싱
턴 간에 도구 정의를 캐시하려면 [프롬프트 캐싱과 함께 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-use-with-prompt-caching)을 참조하세요.
## 스트리밍
스트리밍이 활성화되면 가져오기 이벤트는 스트림의 일부가 되며, 콘텐츠를 가져오는 동안 일시 중지가 발생합니다:
```sse 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 runs
// 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...
```
## 배치 요청
[Message Batches API](https://platform.claude.com/docs/ko/build-with-claude/batch-processing)에 웹 가져오기 도구를 포함할 수 있습니다. Message Batches API를 통한 웹 가져오기 도구 호출은 일반 Messages API 요청과 동일한 가격이 책정됩니다.
## 사용량 및 가격
Web fetch(웹 가져오기) 사용에는 표준 토큰 비용 외에 **추가 요금이 없습니다**:
```json
{
"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 토큰
## 다음 단계
샌드박스 컨테이너에서 Python 및 Bash 코드를 실행하여 데이터를 분석하고, 파일을 생성하고, 솔루션을 반복 개선합니다.
Anthropic이 실행하는 도구를 다룹니다: `server_tool_use` 블록, `pause_turn` 이어서 진행, 도메인 필터링.
Anthropic 제공 도구 목록과 선택적 도구 정의 속성에 대한 참조입니다.
## 제공 여부
웹 가져오기 도구은(는) 모든 모델에서 사용 가능 상태이며 제로 데이터 보존에 적격합니다.
### API 지원
#### [Messages API](https://platform.claude.com/docs/ko/build-with-claude/working-with-messages)
* 제공 여부: 사용 가능
* 사용법: 요청의 `tools`에 `web_fetch` 도구를 추가하세요. `max_uses`, 도메인 목록, `citations`, `max_content_tokens` 같은 설정은 해당 도구에 지정합니다.
| 상태 | 클라우드 플랫폼 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 사용 가능 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry) |
| 사용 가능1 | [Microsoft Foundry (hosted on Azure)](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry) |
1. Azure에서 호스팅되는 배포는 `web_fetch_20250910`만 지원합니다. 동적 필터링, 응답 포함, 캐시 우회는 지원되지 않습니다.
#### [Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview)
* 제공 여부: 사용 가능
* 사용법: 에이전트 도구 세트의 일부이며, 도구 세트를 추가하면 기본적으로 켜집니다. 도메인 목록(경로 제외)과 `max_content_tokens`는 도구 세트의 `web_fetch` 항목에 지정하며, `max_uses`, `citations`, `cache_control`은 사용할 수 없습니다.
| 상태 | 클라우드 플랫폼 |
| ----- | ------------------------------------------------------------------------------------------------------------------ |
| 사용 가능 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws) |
### 데이터 처리
[데이터 처리 개요](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#feature-eligibility)
| 항목 | 제로 데이터 보존 | HIPAA |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------- | ----- |
| 상태 | 적격([적용 모델](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#model-specific-data-retention-requirements) 제외) | 적격 아님 |
| 세부 정보 | 가져온 웹 콘텐츠가 API 응답으로 반환됩니다. 웹 가져오기의 동적 필터링은 ZDR 또는 HIPAA 적격 대상이 아닙니다. 웹사이트 게시자는 자체 정책에 따라 요청 데이터(가져온 URL 및 요청 메타데이터 등)를 보존할 수 있습니다. | — |
적용 엔드포인트:
* `/v1/messages` `web_fetch` 도구 사용 시