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

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

Начиная с версии web_search_20260209, Claude может писать и выполнять код, который фильтрует результаты поиска до того, как они попадут в контекстное окно (динамическая фильтрация), сохраняя только релевантную информацию. Динамическая фильтрация доступна для 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 отвечает напрямую без поиска, когда запрос опирается на стабильные знания:

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

Поведение при запуске поиска можно регулировать через системную подсказку: вы можете побудить 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",
    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)



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

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

client = anthropic.Anthropic()

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

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



Локализация

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

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



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

Параметр 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 не учитываются при подсчёте входных или выходных токенов.



Ошибки

Когда инструмент веб-поиска сталкивается с ошибкой (например, при достижении ограничений скорости), 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 руководства по серверным инструментам.



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

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



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

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

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

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



Дальнейшие шаги