Инструмент получения веб-страниц

Инструмент получения веб-страниц (web fetch) позволяет 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 получение веб-страниц требует развёртывания Hosted on 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_20260318:

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)



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

Укажите инструмент получения веб-страниц в вашем запросе к 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. Отключайте кэширование только тогда, когда пользователь явно запрашивает свежее содержимое или при получении быстро меняющихся источников, поскольку обход кэша увеличивает задержку (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_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-адреса из серверных инструментов на основе контейнеров (таких как Code Execution и 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 токенов



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