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

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

Последняя версия инструмента веб-загрузки (web_fetch_20260318) поддерживает «dynamic filtering» (динамическую фильтрацию): Claude может писать и выполнять код, чтобы отфильтровать загруженное содержимое до того, как оно попадёт в «context window» (контекстное окно). В контексте остаётся только релевантная информация, а всё остальное отбрасывается. Это снижает расход токенов без потери качества ответов. Динамическая фильтрация доступна в Claude 4.6 и более поздних моделях, а также в Claude Mythos Preview. Кроме того, 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.

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

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

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

Веб-загрузка — это «server tool» (серверный инструмент): 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?» Claude отвечает напрямую.

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

Загрузка полных веб-страниц и 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)

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

Добавьте инструмент веб-загрузки в запрос к API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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 см. в разделе Серверные инструменты.

В Claude Managed Agents задайте эти поля в записи web_fetch набора инструментов агента. Каждый указанный домен должен быть простым именем хоста без пути; см. Ограничение доменов для веб-поиска и веб-загрузки.

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

Параметр max_content_tokens ограничивает объём содержимого, включаемого в контекст. Если загруженное содержимое превышает этот лимит, инструмент обрезает его. Это помогает контролировать расход токенов при загрузке больших документов. Лимит применяется к текстовому содержимому, но не к двоичному содержимому, например 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 и результатов. Это снижает затраты на выходные токены в агентных рабочих процессах, которым не нужно возвращать клиенту необработанное содержимое страниц. Значение по умолчанию — "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-адресов, которые, по всей видимости, содержат не предоставленные вами учётные данные
• 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-адрес из системной подсказки можно было загрузить, укажите его также в сообщении пользователя. Результаты других серверных инструментов, таких как выполнение кода, коннектор MCP или поиск инструментов, также не являются допустимым источником. Результаты клиентских инструментов являются допустимым источником, даже если они повторяют текст, созданный Claude (например, команда, которая выводит свои входные данные, или сообщение об ошибке, которое их цитирует).

Инструмент также отклоняет URL-адрес, который, по всей видимости, содержит учётные данные, например ключ API или пароль, если только эти учётные данные не указаны в системной подсказке или в тексте сообщения пользователя. Учётные данные, которые встречаются только в результате инструмента, не учитываются. В результате возвращается ошибка url_not_allowed. Чтобы загрузить такой URL-адрес, укажите его в сообщении пользователя.

Совместное использование поиска и загрузки

Когда включены и инструмент веб-поиска, и инструмент веб-загрузки, а пользователь называет конкретную страницу или документ, не указывая 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:

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 токенов

Следующие шаги