Инструмент веб-поиска
Предоставьте Claude доступ к актуальному веб-контенту с цитированием источников, необязательной динамической фильтрацией и управлением доменами.
Использование зависит от продукта
web_search в tools запроса. Такие настройки, как max_uses, списки доменов и user_location, задаются в этом инструменте.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_20260209: добавляет динамическую фильтрациюweb_search_20260318: добавляет управление включением в ответ для агентных рабочих процессов
В примерах на этой странице используется web_search_20250305 для базового поиска и web_search_20260318 для динамической фильтрации.
Сведения о соответствии веб-поиска требованиям «Zero Data Retention» (нулевое хранение данных), или ZDR, и о связанной конфигурации allowed_callers см. в разделе Серверные инструменты.
Сведения о поддержке моделей см. в справочнике инструментов.
Чтобы проверить, поддерживает ли модель веб-поиск, до отправки запроса, прочитайте её значение capabilities.server_tools.web_search.supported из Models API. Это поле описано в разделе Использование Models API.
Как работает веб-поиск
Когда вы добавляете инструмент веб-поиска в свой запрос к API:
- Claude определяет, когда выполнять поиск, на основе подсказки.
- API выполняет поиск и предоставляет Claude результаты. Этот процесс может повторяться несколько раз в рамках одного запроса.
- В конце своего хода 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)Определение инструмента
Инструмент веб-поиска поддерживает следующие параметры:
{
"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.
type: тип местоположения (должен бытьapproximate)city: название городаregion: регион или штатcountry: двухбуквенный код страны ISO 3166-1 alpha-2 (API отклоняет неподдерживаемый код с ошибкой 400)timezone: идентификатор часового пояса IANA
В Claude Managed Agents запись web_search набора инструментов агента также принимает user_location; см. настройки веб-инструментов.
Включение в ответ
Параметр response_inclusion управляет тем, как блоки результатов поиска отображаются в ответе API, когда результат был использован завершённым вызовом выполнения кода в том же ответе. Установите "response_inclusion": "excluded", чтобы полностью исключить эти вложенные пары блоков server_tool_use и результатов из ответа, — для агентных рабочих процессов, которым не нужен необработанный контент поиска. Расход токенов при этом не меняется, поскольку Claude читает выходные данные кода, а не эти блоки. Значение по умолчанию — "full". API всегда возвращает полностью результаты прямых вызовов или вызовов выполнения кода, которые были приостановлены до завершения, чтобы вы могли отправить их обратно в следующем запросе.
{
"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 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, и справочник по необязательным свойствам определения инструментов.
Доступность
Claude API
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Claude Platform on AWS
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Модели
- Все модели
- Примечание
Только базовый инструмент веб-поиска (
web_search_20250305), без динамической фильтрации.
Microsoft Foundry (hosted on Azure)
- API
- Messages API
- Модели
- Все модели
- Примечание
Только базовый инструмент веб-поиска (
web_search_20250305), без динамической фильтрации.
Microsoft Foundry (hosted on Anthropic)
- API
- Messages API
- Модели
- Все модели
Обработка данных
Обзор обработки данныхПрименимые конечные точки
/v1/messagesс инструментомweb_search
Кроме Охватываемые модели
Результаты веб-поиска в реальном времени возвращаются в ответе API. Динамическая фильтрация для веб-поиска не подпадает под ZDR или HIPAA.
Динамическая фильтрация для веб-поиска не подпадает под ZDR или HIPAA.
Эта страница была полезной?