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

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

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

О соответствии требованиям Zero Data Retention и обходном решении с allowed_callers см. в разделе Серверные инструменты.

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



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

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

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



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

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

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

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

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

Срабатыванием поиска можно управлять через системную подсказку: вы можете побудить Claude выполнять поиск охотнее или предпочитать прямые ответы. Для жёсткого ограничения используйте max_uses, чтобы ограничить количество поисковых запросов для каждого запроса.



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

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

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

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

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

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

client = anthropic.Anthropic()

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



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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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
  "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 ограничивает количество выполняемых поисковых запросов. Если Claude пытается выполнить больше поисков, чем разрешено, web_search_tool_result будет содержать ошибку с кодом max_uses_exceeded.

Простые фактологические запросы обычно используют 1–3 поиска; сравнительные исследования или исследования нескольких объектов могут использовать 10 и более. Для поисков, чувствительных к задержке, max_uses: 3 ограничивает стоимость и при этом редко приводит к усечению. Для исследовательских агентов установите max_uses равным 15–20 или не указывайте его вовсе.



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

О фильтрации доменов с помощью allowed_domains и blocked_domains см. в разделе Серверные инструменты.



Локализация

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

• type: тип местоположения (должен быть approximate)
• city: название города
• region: регион или штат
• country: страна
• 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"
}



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

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

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



Цитаты

Цитаты всегда включены для веб-поиска, и каждый 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"
  }
}

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

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



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

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



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