Инструмент веб-выборки

Инструмент веб-запросов

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

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

Для Claude Mythos Preview веб-выборка поддерживается только на Claude API и Microsoft Foundry. Она недоступна для Mythos Preview на Amazon Bedrock или Google Vertex AI.

Используйте форму обратной связи для предоставления отзывов о качестве ответов модели, самом API или качестве документации.

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

Включение инструмента веб-выборки в окружениях, где Claude обрабатывает ненадёжные входные данные наряду с конфиденциальными данными, создаёт риски утечки данных. Используйте этот инструмент только в доверенных окружениях или при работе с неконфиденциальными данными.

Чтобы минимизировать риски утечки, Claude не может динамически конструировать URL-адреса. Claude может получать только URL-адреса, которые были явно предоставлены пользователем или которые поступают из предыдущих результатов веб-поиска или веб-выборки. Однако остаётся остаточный риск, который следует тщательно учитывать при использовании этого инструмента.

Если утечка данных вызывает беспокойство, рассмотрите:

Полное отключение инструмента веб-выборки
Использование параметра max_uses для ограничения количества запросов
Использование параметра allowed_domains для ограничения известными безопасными доменами

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

Как работает веб-выборка

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

Claude решает, когда получить содержимое на основе подсказки и доступных URL-адресов.
API получает полное текстовое содержимое с указанного URL-адреса.
Для PDF-файлов выполняется автоматическое извлечение текста.
Claude анализирует полученное содержимое и предоставляет ответ с опциональными цитатами.

Инструмент веб-выборки в настоящее время не поддерживает веб-сайты, динамически отображаемые через JavaScript.

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

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

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

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

Динамическая фильтрация требует, чтобы был включен инструмент выполнения кода. Инструмент веб-выборки (с динамической фильтрацией и без неё) доступен на Claude API и Microsoft Azure.

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

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

Предоставьте инструмент веб-выборки в запросе API:

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

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

JSON

{
  "type": "web_fetch_20250910",
  "name": "web_fetch",

  // Опционально: ограничить количество выборок на запрос
  "max_uses": 10,

  // Опционально: получать только с этих доменов
  "allowed_domains": ["example.com", "docs.example.com"],

  // Опционально: никогда не получать с этих доменов
  "blocked_domains": ["private.example.com"],

  // Опционально: включить цитаты для полученного содержимого
  "citations": {
    "enabled": true
  },

  // Опционально: максимальная длина содержимого в токенах
  "max_content_tokens": 100000
}

Максимальное использование

Параметр max_uses ограничивает количество выполняемых веб-выборок. Если Claude попытается выполнить больше выборок, чем разрешено, результат web_fetch_tool_result будет ошибкой с кодом ошибки max_uses_exceeded. В настоящее время нет ограничения по умолчанию.

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

Для фильтрации доменов с allowed_domains и blocked_domains см. Серверные инструменты.

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

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

Ограничение параметра max_content_tokens является приблизительным. Фактическое количество использованных входных токенов может немного варьироваться.

Цитаты

В отличие от веб-поиска, где цитаты всегда включены, цитаты опциональны для веб-выборки. Установите "citations": {"enabled": true} чтобы позволить Claude цитировать конкретные отрывки из полученных документов.

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

Ответ

Вот пример структуры ответа:

Output

{
  "role": "assistant",
  "content": [
    // 1. Решение Claude получить содержимое
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. Запрос выборки
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Результаты выборки
    {
      "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 с цитатами (если включены)
    {
      "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-адресу. Поведение кэша управляется автоматически и может изменяться со временем для оптимизации различных типов содержимого и моделей использования.

Для PDF-документов содержимое возвращается как данные в кодировке base64:

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 (успех) с ошибкой, представленной в теле ответа:

Output

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_fetch_tool_error",
    "error_code": "url_not_accessible"
  }
}

Это возможные коды ошибок:

invalid_input: неверный формат URL
url_too_long: URL превышает максимальную длину (250 символов)
url_not_allowed: URL заблокирован правилами фильтрации доменов и ограничениями модели
url_not_accessible: не удалось получить содержимое (ошибка HTTP)
too_many_requests: превышен лимит частоты запросов
unsupported_content_type: тип содержимого не поддерживается (только текст и PDF)
max_uses_exceeded: превышено максимальное использование инструмента веб-выборки
unavailable: произошла внутренняя ошибка

Проверка URL

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

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

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

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

Веб-выборка работает бесперебойно с веб-поиском для комплексного сбора информации:

Python

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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},
        },
    ],
)

В этом рабочем процессе Claude будет:

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

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

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

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

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

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 получить содержимое

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}

// URL выборки передан потоком
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Пауза во время выполнения выборки

// Результаты выборки переданы потоком
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 продолжается...

Пакетные запросы

Вы можете включить инструмент веб-выборки в API пакетной обработки сообщений. Вызовы инструмента веб-выборки через API пакетной обработки сообщений оцениваются так же, как и в обычных запросах API сообщений.

Использование и цены

Web fetch usage has no additional charges beyond standard token costs:

{
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  }
}

The web fetch tool is available on the Claude API at no additional cost. You only pay standard token costs for the fetched content that becomes part of your conversation context.

To protect against inadvertently fetching large content that would consume excessive tokens, use the max_content_tokens parameter to set appropriate limits based on your use case and budget considerations.

Example token usage for typical content:

Average web page (10 kB): ~2,500 tokens
Large documentation page (100 kB): ~25,000 tokens
Research paper PDF (500 kB): ~125,000 tokens

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

Серверные инструменты

Общие механики для инструментов, выполняемых Anthropic.

Справочник инструментов

Каталог всех инструментов, предоставляемых Anthropic.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)