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

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

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

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

• web_search_20250305: базовый веб-поиск
• web_search_20260209: добавляет динамическую фильтрацию
• web_search_20260318: добавляет управление включением в ответ для агентных рабочих процессов

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

Информацию о соответствии веб-поиска требованиям Zero Data Retention и связанной конфигурации allowed_callers см. в разделе Серверные инструменты.

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

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

Когда вы добавляете инструмент веб-поиска в свой запрос к 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 Console применяются только к запросам Messages API. Сессии Claude Managed Agents используют только списки allowed_domains и blocked_domains для каждого инструмента в наборе инструментов агента; см. Ограничение доменов для веб-поиска и веб-загрузки.

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

client = anthropic.Anthropic()

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

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

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

{
  "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.
  // 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"]. О том, как его настроить, см. Серверные инструменты. web_search_20260318 и более поздние версии также принимают response_inclusion.

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

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

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

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

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

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

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

Локализация

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

• type: тип местоположения (должен быть approximate)
• city: название города
• region: регион или штат
• country: двухбуквенный код страны ISO 3166-1 alpha-2. API отклоняет неподдерживаемые коды стран с ошибкой 400.
• timezone: идентификатор часового пояса IANA.

В Claude Managed Agents запись web_search набора инструментов агента принимает объект user_location с теми же полями. API отклоняет неподдерживаемый код country с ошибкой 400 при создании или обновлении агента, а также при создании или обновлении сессии, которая предоставляет эту настройку. См. Ограничение доменов для веб-поиска и веб-загрузки.

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

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

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

Ответ

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

{
  "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 (успех). Ошибка представлена в теле ответа с использованием следующей структуры:

{
  "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» (потоковой передаче) вы будете получать события поиска как часть потока. Во время выполнения поиска будет пауза:

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.

Для защиты общей ёмкости 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 за 1 000 поисковых запросов, плюс стандартная стоимость токенов для контента, сгенерированного в результате поиска. Результаты веб-поиска, полученные в ходе разговора, учитываются как входные токены (input tokens) — как в итерациях поиска, выполненных в рамках одного хода, так и в последующих ходах разговора.

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

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