Инструмент веб-загрузки

Инструмент веб-загрузки позволяет Claude получать полное содержимое указанных веб-страниц и PDF-документов.

Последняя версия инструмента веб-загрузки (web_fetch_20260318) поддерживает динамическую фильтрацию с Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 и Claude Sonnet 4.6. Claude может писать и выполнять код для фильтрации загруженного содержимого до того, как оно попадёт в контекстное окно, сохраняя только релевантную информацию и отбрасывая остальное. Это снижает потребление токенов при сохранении качества ответов. web_fetch_20260318 также добавляет управление включением ответа для агентных рабочих процессов. Предыдущие версии (web_fetch_20260309 для динамической фильтрации и обхода кэша, web_fetch_20260209 только для динамической фильтрации, web_fetch_20250910 для базовой загрузки) остаются доступными.

Веб-загрузка (с динамической фильтрацией и без неё) доступна в Claude API, Claude Platform на AWS и Microsoft Foundry. В Microsoft Foundry веб-загрузка требует развёртывания с размещением на Anthropic. В настоящее время она недоступна в Amazon Bedrock и Google Cloud.

О соответствии требованиям Zero Data Retention и обходном решении с allowed_callers см. в разделе Серверные инструменты.

О поддержке моделей см. в Справочнике инструментов.



Как работает веб-загрузка

Веб-загрузка — это серверный инструмент: API загружает содержимое во время запроса и вставляет результаты в разговор. Вам не нужно ничего запускать или возвращать tool_result. Исключение составляет случай, когда Claude вызывает веб-загрузку и один из ваших клиентских инструментов в одной группе параллельных вызовов инструментов: API возвращает ответ с stop_reason: "tool_use" до выполнения этой загрузки, а затем выполняет загрузку, когда вы отправляете обратно клиентские блоки tool_result. См. Смешивание серверных и клиентских инструментов в одном ходе.

Когда вы добавляете инструмент веб-загрузки в свой запрос к API:

1. Claude решает, когда загружать содержимое, на основе подсказки и доступных URL-адресов.
2. API получает полный текстовый контент с указанного URL-адреса.
3. Для PDF-файлов API возвращает содержимое в виде данных, закодированных в base64, и обрабатывает его как напрямую прикреплённый PDF-документ.
4. Claude анализирует загруженное содержимое и предоставляет ответ с необязательными цитатами.



Когда Claude выполняет загрузку

Claude выполняет загрузку, когда запрос указывает на конкретную страницу или документ:

• URL-адрес предоставлен в разговоре (или в предыдущем результате инструмента)
• Пользователь называет конкретный ресурс (определённую статью, README, страницу с ценами или раздел документации) без URL-адреса, и инструмент веб-поиска также включён, чтобы Claude мог сначала найти его (см. Комбинированный поиск и загрузка)

Claude не выполняет загрузку для общих или открытых вопросов, которые не ссылаются на конкретную страницу. «Кратко изложи эту статью: <url>» запускает загрузку. На вопрос «Каковы лучшие практики проектирования REST API?» даётся прямой ответ.



Динамическая фильтрация

Загрузка полных веб-страниц и PDF-файлов может быстро расходовать токены, особенно когда из больших документов нужна только определённая информация. С web_fetch_20260209 или более поздней версией Claude может писать и выполнять код для фильтрации загруженного содержимого перед его загрузкой в контекст.

Эта динамическая фильтрация особенно полезна для:

• Извлечения определённых разделов из длинных документов
• Обработки структурированных данных с веб-страниц
• Фильтрации релевантной информации из PDF-файлов
• Снижения затрат на токены при работе с большими документами

Чтобы включить динамическую фильтрацию, используйте web_fetch_20260209 или любую более позднюю версию. В следующих примерах используется web_fetch_20260209:

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_20260209", "name": "web_fetch"}],
)
print(response)



Как использовать веб-загрузку

Укажите инструмент веб-загрузки в своём запросе к API:

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)



Определение инструмента

Инструмент веб-загрузки поддерживает следующие параметры:

{
  "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 ограничивает количество выполняемых веб-загрузок. Неудачные загрузки учитываются в лимите. Если Claude пытается выполнить больше загрузок, чем разрешено, web_fetch_tool_result содержит ошибку с кодом ошибки max_uses_exceeded. В настоящее время лимит по умолчанию отсутствует.



Фильтрация доменов

О фильтрации доменов с помощью allowed_domains и blocked_domains см. в разделе Серверные инструменты.



Ограничения содержимого

Параметр max_content_tokens ограничивает объём содержимого, включаемого в контекст. Если загруженное содержимое превышает этот лимит, инструмент усекает его. Это помогает контролировать использование токенов при загрузке больших документов. Лимит применяется к текстовому содержимому, но не к двоичному содержимому, такому как PDF-файлы.



Обход кэша

Параметр use_cache определяет, может ли возвращаться кэшированное содержимое. Установите "use_cache": false, чтобы обойти кэш и загрузить свежее содержимое. Значение по умолчанию — true. Отключайте кэширование только тогда, когда пользователь явно запрашивает свежее содержимое или при загрузке быстро меняющихся источников, поскольку обход кэша увеличивает задержку.

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



Включение ответа

Параметр response_inclusion определяет, как блоки результатов загрузки отображаются в ответе API, когда результат был использован завершённым вызовом выполнения кода в том же ходе. Установите "response_inclusion": "excluded", чтобы полностью исключить эти вложенные пары блоков server_tool_use и результатов из ответа, снижая затраты на выходные токены для агентных рабочих процессов, которым не нужно возвращать клиенту необработанное содержимое страницы. Значение по умолчанию — "full". Результаты прямых вызовов или вызовов выполнения кода, которые были приостановлены до завершения, всегда возвращаются полностью, чтобы их можно было отправить обратно на следующем ходе.

{
  "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_not_in_prior_context: URL-адрес не появлялся ранее в разговоре (см. Проверка URL-адресов)
• url_not_accessible: Не удалось загрузить содержимое (ошибка HTTP)
• too_many_requests: Превышено ограничение скорости
• unsupported_content_type: Тип содержимого не поддерживается (только текст, HTML и PDF)
• max_uses_exceeded: Превышено максимальное количество использований инструмента веб-загрузки
• unavailable: Произошла внутренняя ошибка



Проверка URL-адресов

По соображениям безопасности инструмент веб-загрузки может загружать только те URL-адреса, которые ранее появлялись в контексте разговора. Это включает:

• URL-адреса в сообщениях пользователя
• URL-адреса в результатах клиентских инструментов
• URL-адреса из предыдущих результатов веб-поиска или веб-загрузки

Инструмент не может загружать произвольные URL-адреса, которые генерирует Claude, или URL-адреса из контейнерных серверных инструментов (выполнение кода, Bash и т. д.).



Комбинированный поиск и загрузка

Когда включены оба инструмента — веб-поиск и веб-загрузка, — и пользователь называет конкретную страницу или документ без указания URL-адреса (например, «прочитай README из репозитория anthropics/anthropic-sdk-python»), 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. Использует веб-загрузку для получения полного содержимого.
4. Предоставляет подробный анализ с цитатами.



Кэширование подсказок

О кэшировании определений инструментов между ходами см. в разделе Использование инструментов с кэшированием подсказок.



Потоковая передача

При включённой потоковой передаче события загрузки являются частью потока с паузой во время получения содержимого:

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. Вызовы инструмента веб-загрузки через Messages 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
    }
  }
}

Инструмент web fetch доступен в Claude API без дополнительной платы. Вы оплачиваете только стандартную стоимость токенов за полученный контент, который становится частью контекста вашего разговора.

Чтобы защититься от непреднамеренного получения большого объёма контента, который потребил бы чрезмерное количество токенов, используйте параметр max_content_tokens для установки подходящих лимитов в зависимости от вашего сценария использования и бюджетных соображений.

Пример использования токенов для типичного контента:

• Средняя веб-страница (10 кБ): ~2 500 токенов
• Большая страница документации (100 кБ): ~25 000 токенов
• PDF-файл научной статьи (500 кБ): ~125 000 токенов



Дальнейшие шаги