Claude Platform Docs
СообщенияИнструменты

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

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

Использование зависит от продукта

Messages API
Добавьте инструмент web_search в tools запроса. Такие настройки, как max_uses, списки доменов и user_location, задаются в этом инструменте.
Managed Agents
Включён по умолчанию в наборе инструментов агента, без max_uses, citations и cache_control.

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

Начиная с web_search_20260209 и в более поздних версиях, Claude может писать и выполнять код, который фильтрует результаты поиска до того, как они попадут в «context window» (контекстное окно) («dynamic filtering» (динамическая фильтрация)), сохраняя только релевантную информацию. Динамическая фильтрация доступна для Claude 4.6 и более поздних моделей, а также для Claude Mythos Preview.

Доступны три версии инструмента веб-поиска:

В примерах на этой странице используется web_search_20250305 для базового поиска и web_search_20260318 для динамической фильтрации.

Сведения о соответствии веб-поиска требованиям «Zero Data Retention» (нулевое хранение данных), или ZDR, и о связанной конфигурации allowed_callers см. в разделе Серверные инструменты.

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

Чтобы проверить, поддерживает ли модель веб-поиск, до отправки запроса, прочитайте её значение capabilities.server_tools.web_search.supported из Models API. Это поле описано в разделе Использование Models API.

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

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

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

Когда Claude выполняет поиск

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

  • Недавние события, новости или объявления
  • Текущие цены, курсы, счёт матчей или статистика
  • Информация о конкретных организациях, людях или продуктах, которая могла измениться
  • Явные просьбы выполнить поиск или что-то найти

Claude отвечает напрямую, без поиска, когда запрос опирается на устойчивые знания:

  • Установленные факты, математика, основы науки или концепции программирования
  • Творческое письмо или мозговой штурм
  • Анализ контента, уже предоставленного в разговоре
  • Реплики разговора и приветствия

Запуск поиска можно направлять через вашу «system prompt» (системная подсказка): вы можете побудить Claude охотнее выполнять поиск или предпочитать прямые ответы. Чтобы принудительно ограничить количество поисков в рамках одного хода, используйте max_uses.

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

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

Динамическая фильтрация выполняет веб-поиск изнутри выполнения кода: в web_search_20260209 и более поздних версиях поле инструмента allowed_callers по умолчанию имеет значение ["code_execution_20260120"], и когда выполняется динамическая фильтрация, API автоматически предоставляет необходимое для запроса выполнение кода. Вам не нужно самостоятельно добавлять инструмент выполнения кода в tools. За вызовы выполнения кода, сделанные таким образом, не взимается дополнительная плата сверх стандартной стоимости токенов.

Чтобы вызывать веб-поиск напрямую, без динамической фильтрации, установите allowed_callers: ["direct"]. Модели, которые не поддерживают программный вызов инструментов, требуют этой настройки. Без неё API возвращает ошибку 400 с указанием установить её.

В следующих примерах используется web_search_20260318:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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_20260318", "name": "web_search"}],
)
print(response)

О том, как настройки веб-поиска вашей организации применяются в сеансах Claude Managed Agents, см. Ограничение доменов для веб-поиска и веб-загрузки.

Укажите инструмент веб-поиска в своём запросе к API:

client = anthropic.Anthropic()

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

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

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

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

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

  // Optional: Only include results from these domains.
  // Use allowed_domains or blocked_domains, not both.
  "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"
  }
}

Все версии инструмента веб-поиска принимают allowed_callers, который определяет, вызывает ли Claude веб-поиск напрямую или из выполнения кода через динамическую фильтрацию. В web_search_20260209 и более поздних версиях он по умолчанию имеет значение ["code_execution_20260120"] вместо ["direct"]. О том, как его настроить, см. ZDR и allowed_callers. web_search_20260318 и более поздние версии также принимают response_inclusion.

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

Параметр max_uses ограничивает количество поисков в рамках одного хода. Запросы об одном факте обычно используют 1–3 поиска; сравнительные исследования или исследования с несколькими сущностями могут использовать 10 и более.

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

Ход может охватывать несколько запросов. Запрос продолжает ход, когда он возобновляется после pause_turn или когда его последнее сообщение содержит только блоки tool_result. Поиски из более ранних запросов в этом ходе учитываются в лимите, если только Claude не выполнил их из выполнения кода через динамическую фильтрацию.

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

Укажите allowed_domains или blocked_domains, но не оба. Если запрос включает оба параметра, API возвращает ошибку 400. Записи представляют собой домены без схемы с необязательным путём, например example.com или example.com/blog.

Полные правила фильтрации доменов см. в разделе Фильтрация доменов руководства по серверным инструментам.

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

Локализация

Параметр user_location позволяет локализовать результаты поиска на основе местоположения пользователя. Укажите хотя бы одно из полей city, region, country или timezone.

В Claude Managed Agents запись web_search набора инструментов агента также принимает user_location; см. настройки веб-инструментов.

Включение в ответ

Параметр response_inclusion управляет тем, как блоки результатов поиска отображаются в ответе API, когда результат был использован завершённым вызовом выполнения кода в том же ответе. Установите "response_inclusion": "excluded", чтобы полностью исключить эти вложенные пары блоков server_tool_use и результатов из ответа, — для агентных рабочих процессов, которым не нужен необработанный контент поиска. Расход токенов при этом не меняется, поскольку Claude читает выходные данные кода, а не эти блоки. Значение по умолчанию — "full". API всегда возвращает полностью результаты прямых вызовов или вызовов выполнения кода, которые были приостановлены до завершения, чтобы вы могли отправить их обратно в следующем запросе.

JSON
{
  "tools": [
    {
      "type": "web_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}

Ответ

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

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"
}

В этом примере показан прямой поиск. Когда поиск выполняется через динамическую фильтрацию, ответ также содержит блоки результатов инструмента выполнения кода, а каждая вложенная пара server_tool_use и web_search_tool_result содержит поле caller, идентифицирующее вызов выполнения кода, который её создал.

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

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

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

Чтобы продолжить разговор, содержащий результаты поиска, отправьте блоки контента ассистента обратно в точности в том виде, в каком вы их получили, включая encrypted_content каждого результата. API расшифровывает этот контент в последующих запросах, чтобы восстановить результаты поиска в контексте Claude. Если encrypted_content отсутствует или изменён, запрос завершается ошибкой валидации 400.

Цитаты

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

  • url: URL цитируемого источника
  • title: заголовок цитируемого источника
  • encrypted_index: ссылка, которую необходимо передавать обратно в многоходовых разговорах
  • cited_text: до 150 символов цитируемого контента

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

Ошибки

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

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

При ошибке content является единственным объектом ошибки, а не списком блоков результатов. Поиск, который выполнен успешно, но не нашёл результатов, возвращает пустой список content, а не ошибку.

Возможные коды ошибок:

  • too_many_requests: превышено ограничение скорости
  • invalid_tool_input: недопустимый параметр поискового запроса
  • max_uses_exceeded: превышено максимальное количество использований инструмента веб-поиска
  • query_too_long: запрос превышает максимальную длину
  • request_too_large: поисковый запрос слишком велик, как правило, из-за длинного списка фильтрации доменов
  • unavailable: произошла внутренняя ошибка

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

API может приостановить длительный ход поиска и вернуть stop_reason: "pause_turn". Чтобы продолжить, отправьте приостановленное сообщение ассистента обратно без изменений в новом запросе.

Если Claude вызывает веб-поиск и один из ваших клиентских инструментов в одной группе параллельных вызовов инструментов, API вместо этого возвращает stop_reason: "tool_use" и пока не выполняет поиск. Чтобы продолжить, верните результаты клиентских инструментов, и API выполнит поиск в следующем запросе. См. Сочетание серверных и клиентских инструментов в одном ходе.

О серверном цикле и обработке pause_turn см. Серверный цикл и pause_turn в руководстве по серверным инструментам.

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

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

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

При включённой «streaming» (потоковая передача) вы получаете события поиска как часть потока. Во время выполнения поиска возникает пауза:

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 runs

// 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)

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

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

Для защиты общих ресурсов Batches API ограничивает частоту запросов веб-поиска для каждой организации, поэтому выполнение больших пакетов с большим количеством поисков может занять больше времени. Ограничение скорости веб-поиска для вашей организации можно посмотреть на странице Лимиты запросов в Claude Console. Чтобы запросить более высокое ограничение, свяжитесь с отделом продаж с этой страницы.

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

Использование веб-поиска оплачивается дополнительно к использованию токенов:

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

В Claude API веб-поиск стоит $10 USD за 1 000 поисковых запросов, плюс стандартная стоимость токенов за контент, сгенерированный поиском. Результаты поиска учитываются как входные токены — как пока Claude продолжает поиск в рамках одного хода, так и в последующих ходах разговора.

Каждый веб-поиск считается одним использованием, независимо от количества возвращённых результатов. Плата за веб-поиск, завершившийся ошибкой, не взимается.

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

Загружайте и читайте контент с определённых URL, чтобы дополнить контекст Claude актуальным веб-контентом.

Работайте с инструментами, которые выполняет Anthropic: блоки server_tool_use, продолжение pause_turn и фильтрация доменов.

Каталог инструментов, предоставляемых Anthropic, и справочник по необязательным свойствам определения инструментов.

Доступность

Инструмент веб-поиска
API
  • Messages API
  • Managed Agents
Модели
  • Все модели

Обработка данных

Обзор обработки данных

Применимые конечные точки

  • /v1/messages с инструментом web_search
Нулевое хранение данныхДопускается

Кроме Охватываемые модели

Результаты веб-поиска в реальном времени возвращаются в ответе API. Динамическая фильтрация для веб-поиска не подпадает под ZDR или HIPAA.

HIPAAДопускается

Динамическая фильтрация для веб-поиска не подпадает под ZDR или HIPAA.

Эта страница была полезной?