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

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

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

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

Для информации о Zero Data Retention и обходном решении allowed_callers см. Server tools.

Для поддержки моделей см. Tool reference.

Как работает веб-поиск

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

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

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

Веб-поиск требует много токенов. При базовом веб-поиске Claude должен загрузить результаты поиска в контекст, получить полный HTML с нескольких веб-сайтов и рассуждать над всем этим перед получением ответа. Часто большая часть этого контента не релевантна, что может снизить качество ответа.

С версией инструмента web_search_20260209 Claude может писать и выполнять код для постобработки результатов запроса. Вместо рассуждений над полными HTML-файлами Claude динамически фильтрует результаты поиска перед загрузкой их в контекст, сохраняя только релевантное и отбрасывая остальное.

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

Поиска в технической документации
Обзора литературы и проверки цитирований
Технических исследований
Обоснования и проверки ответов

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

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

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

Администратор вашей организации должен включить веб-поиск в Claude Console.

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

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

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

JSON

{
  "type": "web_search_20250305",
  "name": "web_search",

  // Optional: Limit the number of searches per request
  "max_uses": 5,

  // Optional: Only include results from these domains
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optional: Never include results from these domains
  "blocked_domains": ["untrustedsource.com"],

  // Optional: Localize search results
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

Max uses

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

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

Для фильтрации по доменам с allowed_domains и blocked_domains см. Server tools.

Локализация

Параметр user_location позволяет локализовать результаты поиска на основе местоположения пользователя.

type: Тип местоположения (должен быть approximate)
city: Название города
region: Регион или штат
country: Страна
timezone: IANA timezone ID.

Ответ

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

Output

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to search
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. The search query used
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Search results
    {
      "type": "web_search_tool_result",
      "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "content": [
        {
          "type": "web_search_result",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
          "page_age": "April 30, 2025"
        }
      ]
    },
    {
      "text": "Based on the search results, ",
      "type": "text"
    },
    // 4. Claude's response with citations
    {
      "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
      "type": "text",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
          "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 6039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_search_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

Результаты поиска

Результаты поиска включают:

url: URL исходной страницы
title: Название исходной страницы
page_age: Когда сайт был последний раз обновлен
encrypted_content: Зашифрованный контент, который должен быть передан обратно в многооборотных разговорах для цитирований

Цитирования

Цитирования всегда включены для веб-поиска, и каждый web_search_result_location включает:

url: URL цитируемого источника
title: Название цитируемого источника
encrypted_index: Ссылка, которая должна быть передана обратно для многооборотных разговоров.
cited_text: До 150 символов цитируемого контента

Поля цитирования веб-поиска cited_text, title и url не учитываются в использовании входных или выходных токенов.

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

Ошибки

Когда инструмент веб-поиска встречает ошибку (например, превышение лимита скорости), Claude API все равно возвращает ответ 200 (успех). Ошибка представлена в теле ответа со следующей структурой:

Output

{
  "type": "web_search_tool_result",
  "tool_use_id": "servertoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

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

too_many_requests: Превышен лимит скорости
invalid_input: Неверный параметр поискового запроса
max_uses_exceeded: Превышено максимальное количество использований инструмента веб-поиска
query_too_long: Запрос превышает максимальную длину
unavailable: Произошла внутренняя ошибка

Причина остановки `pause_turn`

Для продолжения после причины остановки pause_turn см. Server tools.

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

Для кэширования определений инструментов между ходами см. Tool use with prompt caching.

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

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

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's decision to search

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

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}

// Claude's response with citations (omitted in this example)

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

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

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

Web search usage is charged in addition to token usage:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 6039,
    "cache_read_input_tokens": 7123,
    "cache_creation_input_tokens": 7345,
    "server_tool_use": {
      "web_search_requests": 1
    }
  }
}

Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

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

Server tools

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

Tool reference

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
        }
    ],
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
)
print(response)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)

Как работает веб-поиск

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

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

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

Max uses

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

Локализация

Ответ

Результаты поиска

Цитирования

Ошибки

Причина остановки pause_turn

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

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

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

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

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

Причина остановки `pause_turn`