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

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

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

Поддерживаемые модели

Веб-поиск доступен на:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (устарело) (claude-3-7-sonnet-20250219)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Haiku 3.5 (устарело) (claude-3-5-haiku-latest)

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

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

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

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

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

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

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

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

Чтобы включить динамическую фильтрацию, используйте версию инструмента web_search_20260209 с заголовком бета-версии code-execution-web-tools-2026-02-09:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-web-tools-2026-02-09" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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"
        }]
    }'

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

Предоставьте инструмент веб-поиска в вашем запросе API:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "What is the weather in NYC?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

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

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

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

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

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

При использовании фильтров доменов:

• Домены не должны включать схему HTTP/HTTPS (используйте example.com вместо https://example.com)
• Поддомены автоматически включаются (example.com охватывает docs.example.com)
• Конкретные поддомены ограничивают результаты только этим поддоменом (docs.example.com возвращает результаты только из этого поддомена, а не из example.com или api.example.com)
• Поддерживаются подпути и совпадают с чем-либо после пути (example.com/blog совпадает с example.com/blog/post-1)
• Вы можете использовать либо allowed_domains, либо blocked_domains, но не оба в одном запросе.

Поддержка подстановочных знаков:

• Только один подстановочный знак (*) разрешен на запись домена, и он должен появляться после части домена (в пути)
• Допустимо: example.com/*, example.com/*/articles
• Недопустимо: *.example.com, ex*.com, example.com/*/news/*

Неправильные форматы доменов вернут ошибку инструмента invalid_tool_input.

Локализация

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

• type: Тип местоположения (должен быть approximate)
• city: Название города
• region: Регион или штат
• country: Страна
• timezone: IANA timezone ID.

Ответ

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

{
  "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": "servertoolu_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, которая указывает, что API приостановил долгоживущий ход. Вы можете предоставить ответ как есть в последующем запросе, чтобы позволить Claude продолжить свой ход, или изменить контент, если вы хотите прервать разговор.

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

Веб-поиск работает с кэшированием подсказок. Чтобы включить кэширование подсказок, добавьте по крайней мере одну точку разрыва cache_control в ваш запрос. Система автоматически кэширует до последнего блока web_search_tool_result при выполнении инструмента.

Для многооборотных разговоров установите точку разрыва cache_control на или после последнего блока web_search_tool_result, чтобы повторно использовать кэшированный контент.

Например, чтобы использовать кэширование подсказок с веб-поиском для многооборотного разговора:

import anthropic

client = anthropic.Anthropic()

# First request with web search and cache breakpoint
messages = [
    {"role": "user", "content": "What's the current weather in San Francisco today?"}
]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "user_location": {
                "type": "approximate",
                "city": "San Francisco",
                "region": "California",
                "country": "US",
                "timezone": "America/Los_Angeles",
            },
        }
    ],
)

# Add Claude's response to the conversation
messages.append({"role": "assistant", "content": response1.content})

# Second request with cache breakpoint after the search results
messages.append(
    {
        "role": "user",
        "content": "Should I expect rain later this week?",
        "cache_control": {"type": "ephemeral"},  # Cache up to this point
    }
)

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "user_location": {
                "type": "approximate",
                "city": "San Francisco",
                "region": "California",
                "country": "US",
                "timezone": "America/Los_Angeles",
            },
        }
    ],
)
# The second response will benefit from cached search results
# while still being able to perform new searches if needed
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

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

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

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.

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

Web search usage is charged in addition to token usage:

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

Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.