Инструмент веб-загрузки
Получайте и читайте содержимое с определённых URL, чтобы дополнить контекст Claude актуальным веб-содержимым.
Использование зависит от продукта
web_fetch в tools запроса.max_uses, citations и cache_control.Инструмент получения веб-страниц (web fetch tool) позволяет Claude извлекать полное содержимое указанных веб-страниц и PDF-документов.
Последняя версия инструмента получения веб-страниц (web_fetch_20260318) поддерживает динамическую фильтрацию: Claude может писать и выполнять код для фильтрации полученного содержимого до того, как оно попадёт в контекстное окно, сохраняя только релевантную информацию и отбрасывая остальное. Это снижает потребление токенов при сохранении качества ответов. Динамическая фильтрация доступна в Claude 4.6 и более поздних моделях, а также в Claude Mythos Preview. web_fetch_20260318 также добавляет управление включением в ответ для агентных рабочих процессов. Другие версии (web_fetch_20260309 для динамической фильтрации и обхода кэша, web_fetch_20260209 только для динамической фильтрации, web_fetch_20250910 для базового получения) доступны.
Получение веб-страниц (с динамической фильтрацией и без неё) доступно в Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) и Microsoft Foundry. В Microsoft Foundry развёртывания, размещённые в Azure, поддерживают только базовый инструмент получения веб-страниц (web_fetch_20250910, без динамической фильтрации). Развёртывания, размещённые в Anthropic, поддерживают все версии.
Сведения о соответствии требованиям нулевого хранения данных и обходном решении с allowed_callers см. в разделе Серверные инструменты.
Сведения о поддержке моделей см. в справочнике по инструментам.
Как работает получение веб-страниц
Получение веб-страниц — это серверный инструмент: API получает содержимое во время запроса и вставляет результаты в разговор. Вам не нужно ничего запускать или возвращать tool_result. Исключение составляет случай, когда Claude вызывает получение веб-страниц и один из ваших клиентских инструментов в одной группе параллельных вызовов инструментов: API возвращает ответ с stop_reason: "tool_use" до выполнения этого получения, а затем выполняет получение, когда вы отправляете обратно клиентские блоки tool_result. См. Сочетание серверных и клиентских инструментов в одном ходе.
Когда вы добавляете инструмент получения веб-страниц в свой запрос API:
- Claude определяет, когда получать содержимое, на основе подсказки и доступных URL.
- API извлекает полное текстовое содержимое по указанному URL.
- Для PDF API возвращает содержимое в виде данных в кодировке base64 и обрабатывает его как непосредственно прикреплённый PDF-документ.
- Claude анализирует полученное содержимое и предоставляет ответ с необязательными цитатами.
Когда Claude получает содержимое
Claude получает содержимое, когда запрос указывает на конкретную страницу или документ:
- URL предоставлен в разговоре (или в предыдущем результате инструмента)
- Пользователь называет конкретный ресурс (определённую статью, README, страницу с ценами или раздел документации) без URL, и при этом также включён инструмент веб-поиска, чтобы 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-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)Как использовать получение веб-страниц
О том, как настройки получения веб-страниц вашей организации применяются в сеансах Claude Managed Agents, см. Ограничение доменов для веб-поиска и получения веб-страниц.
Укажите инструмент получения веб-страниц в своём запросе API:
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)Определение инструмента
Инструмент получения веб-страниц поддерживает следующие параметры:
{
"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 или более поздней версии (см. Обход кэша), а response_inclusion требует web_fetch_20260318 или более поздней версии (см. Включение в ответ).
Максимальное количество использований
Параметр max_uses ограничивает количество получений веб-страниц за один ход. Неудачные получения учитываются в лимите. Если Claude напрямую вызывает получение веб-страниц больше раз, чем разрешено, web_fetch_tool_result будет ошибкой с кодом max_uses_exceeded. Если Claude вызывает получение веб-страниц из выполнения кода больше раз, чем разрешено, запуск выполнения кода завершается ошибкой. Лимит по умолчанию отсутствует.
Один ход может охватывать несколько запросов. Запрос продолжает ход, если он возобновляется после pause_turn или если его последнее сообщение содержит только блоки tool_result. Получения из более ранних запросов этого хода учитываются в лимите, если только Claude не выполнил их из выполнения кода в рамках динамической фильтрации.
Фильтрация доменов
О фильтрации доменов с помощью allowed_domains и blocked_domains см. Серверные инструменты.
В Claude Managed Agents задайте эти поля в записи web_fetch набора инструментов агента; см. Ограничение доменов для веб-поиска и получения веб-страниц.
Ограничения содержимого
Параметр max_content_tokens ограничивает объём содержимого, включаемого в контекст. Если полученное содержимое превышает этот лимит, инструмент усекает его. Это помогает контролировать использование токенов при получении больших документов. Лимит является приблизительным: фактическое количество использованных входных токенов может незначительно отличаться. Лимит применяется к текстовому содержимому, а не к двоичному содержимому, такому как PDF.
Если из-за полученного PDF запрос превысит ограничения на количество страниц или размер PDF, web_fetch_tool_result будет содержать ошибку с кодом content_too_large. PDF и изображения, уже присутствующие в разговоре, учитываются в этих ограничениях, поэтому их удаление может позволить получению завершиться успешно.
В Claude Managed Agents запись web_fetch набора инструментов агента также принимает max_content_tokens; см. настройки веб-инструментов.
Обход кэша
Параметр use_cache определяет, может ли возвращаться кэшированное содержимое. Задайте "use_cache": false, чтобы обойти кэш и получить свежее содержимое. Значение по умолчанию — true. Отключайте кэширование только тогда, когда пользователь явно запрашивает свежее содержимое или при получении быстро меняющихся источников, поскольку обход кэша увеличивает задержку (latency).
{
"tools": [
{
"type": "web_fetch_20260309",
"name": "web_fetch",
"use_cache": false
}
]
}Включение в ответ
Параметр response_inclusion определяет, как блоки результатов получения отображаются в ответе API, если результат был использован завершённым вызовом выполнения кода в том же ответе. Задайте "response_inclusion": "excluded", чтобы полностью удалить эти вложенные пары блоков server_tool_use и результатов из ответа — для агентных рабочих процессов, которым не нужно необработанное содержимое страниц. Это не влияет на использование токенов, поскольку Claude читает выходные данные кода, а не эти блоки. Значение по умолчанию — "full". API всегда возвращает полностью результаты прямых вызовов или вызовов выполнения кода, которые были приостановлены до завершения, чтобы вы могли отправить их обратно в следующем запросе.
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"response_inclusion": "excluded"
}
]
}Цитаты
В отличие от веб-поиска, где цитаты всегда включены, для получения веб-страниц цитаты необязательны и по умолчанию отключены. Задайте "citations": {"enabled": true}, чтобы разрешить Claude цитировать определённые фрагменты из полученных документов.
Ответ
Вот пример структуры ответа:
{
"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:
{
"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 получает результат с ошибкой и продолжает ход. Например:
{
"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: URL заблокирован правилами фильтрации доменов (включая настройки вашей организации) или ограничениями на стороне Anthropic, такими как частные адреса,robots.txtи URL, которые, по всей видимости, содержат учётные данные, не предоставленные вамиurl_not_in_prior_context: URL ранее не появлялся в разговоре или появлялся только в источниках, которые исключаетurl_sources(см. Проверка URL)url_not_accessible: не удалось получить содержимое (ошибка HTTP)too_many_requests: превышено ограничение скоростиunsupported_content_type: тип содержимого не поддерживается (только текст, HTML и PDF)content_too_large: полученный PDF привёл бы к превышению запросом ограничений на количество страниц или размер PDF (см. Ограничения содержимого)max_uses_exceeded: превышено максимальное количество использований инструмента получения веб-страницunavailable: произошла внутренняя ошибка
Проверка URL
По соображениям безопасности инструмент получения веб-страниц может получать только те URL, которые ранее появлялись в контексте разговора. К ним относятся:
- URL в сообщениях пользователя
- URL в результатах клиентских инструментов
- URL из предыдущих результатов веб-поиска или получения веб-страниц
Инструмент не может получать URL, которые появляются только в собственных выходных данных Claude или только в системной подсказке. Чтобы URL из системной подсказки можно было получить, также включите его в сообщение пользователя. Результаты других серверных инструментов, таких как выполнение кода, коннектор MCP или поиск инструментов, также не являются разрешённым источником. По умолчанию результаты клиентских инструментов являются разрешённым источником, даже если они повторяют текст, созданный Claude (например, команда, выводящая свои входные данные, или сообщение об ошибке, которое их цитирует).
Инструмент также отклоняет URL, который, по всей видимости, содержит учётные данные, например ключ API или пароль, если только эти учётные данные не присутствуют в системной подсказке или в тексте сообщения пользователя. Учётные данные, которые появляются только в результате инструмента, не учитываются. Результатом будет ошибка url_not_allowed. Чтобы получить такой URL, включите его в сообщение пользователя.
Источники URL
Необязательный параметр 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, возвращает всё, что выводит этот код, включая любой URL, который Claude в него поместил. Чтобы результаты этого инструмента не считались источником, укажите его в фильтре "except":
{
"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_not_in_prior_context.
Совместный поиск и получение
Когда включены и инструмент веб-поиска, и инструмент получения веб-страниц, а пользователь называет конкретную страницу или документ, не предоставляя URL (например, «прочитай README из репозитория anthropics/anthropic-sdk-python»), Claude использует веб-поиск, чтобы найти его, а затем получает результат. В следующем примере в одном запросе запрашиваются поиск и анализ:
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)В этом рабочем процессе 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 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. Вызовы инструмента получения веб-страниц через Message Batches API тарифицируются так же, как и в обычных запросах к 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
}
}
}Инструмент веб-загрузки доступен в Claude API без дополнительной платы. Вы оплачиваете только стандартную стоимость токенов за загруженный контент, который становится частью контекста вашего разговора.
Чтобы защититься от непреднамеренной загрузки большого объёма контента, который потребил бы чрезмерное количество токенов, используйте параметр max_content_tokens для установки подходящих ограничений в зависимости от вашего сценария использования и бюджетных соображений.
Пример использования токенов для типичного контента:
- Средняя веб-страница (10 кБ): ~2 500 токенов
- Большая страница документации (100 кБ): ~25 000 токенов
- Научная статья в формате PDF (500 кБ): ~125 000 токенов
Следующие шаги
Запускайте код Python и Bash в изолированном контейнере, чтобы анализировать данные, создавать файлы и итеративно дорабатывать решения.
Работайте с инструментами, которые запускает Anthropic: блоки server_tool_use, продолжение через pause_turn и фильтрация доменов.
Каталог инструментов, предоставляемых Anthropic, и справочник по необязательным свойствам определения инструментов.
Доступность
Claude API
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Claude Platform on AWS
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Microsoft Foundry (hosted on Azure)
- API
- Messages API
- Модели
- Все модели
- Примечание
Развёртывания, размещённые в Azure, поддерживают только
web_fetch_20250910: без динамической фильтрации, включения ответа и обхода кэша.
Microsoft Foundry (hosted on Anthropic)
- API
- Messages API
- Модели
- Все модели
Обработка данных
Обзор обработки данныхПрименимые конечные точки
/v1/messagesс инструментомweb_fetch
Кроме Охватываемые модели
Загруженное веб-содержимое возвращается в ответе API. Динамическая фильтрация для веб-загрузки не подпадает под ZDR или HIPAA. Владельцы веб-сайтов могут хранить данные запросов (например, загруженные URL и метаданные запросов) в соответствии со своими политиками.
Эта страница была полезной?