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

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

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

Поддерживаемые модели

Веб-выборка доступна на:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (устарела) (claude-3-7-sonnet-20250219)

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

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

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

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

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

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

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

Чтобы включить динамическую фильтрацию, используйте версию инструмента web_fetch_20260209 с заголовком бета-версии code-execution-web-tools-2026-02-09:

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

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

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

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

{
  "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. В настоящее время нет ограничения по умолчанию.

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

При использовании фильтров доменов:

• Домены не должны включать схему HTTP/HTTPS (используйте example.com вместо https://example.com)
• Поддомены автоматически включены (example.com охватывает docs.example.com)
• Поддерживаются подпути (example.com/blog)
• Вы можете использовать либо allowed_domains, либо blocked_domains, но не оба в одном запросе.

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

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

Цитаты

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

Ответ

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

{
  "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: Временная метка, когда содержимое было получено

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

{
  "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 и т. д.).

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

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    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 будет:

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

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

Веб-выборка работает с кэшированием подсказок. Чтобы включить кэширование подсказок, добавьте точки разрыва cache_control в ваш запрос. Кэшированные результаты выборки можно повторно использовать в разных ходах разговора.

import anthropic

client = anthropic.Anthropic()

# Первый запрос с веб-выборкой
messages = [
    {
        "role": "user",
        "content": "Analyze this research paper: https://arxiv.org/abs/2024.12345",
    }
]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch"}],
)

# Добавить ответ Claude в разговор
messages.append({"role": "assistant", "content": response1.content})

# Второй запрос с точкой разрыва кэша
messages.append(
    {
        "role": "user",
        "content": "What methodology does the paper use?",
        "cache_control": {"type": "ephemeral"},
    }
)

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch"}],
)

# Второй ответ получает преимущество от кэшированных результатов выборки
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

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

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

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 продолжается...

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

Вы можете включить инструмент веб-выборки в Messages Batches API. Вызовы инструмента веб-выборки через Messages Batches API оцениваются так же, как в обычных запросах Messages 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 (10KB): ~2,500 tokens
• Large documentation page (100KB): ~25,000 tokens
• Research paper PDF (500KB): ~125,000 tokens