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

Пожалуйста, свяжитесь с нами через нашу форму обратной связи, чтобы поделиться своим опытом использования инструмента веб-поиска.

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

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

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (новый) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

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

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

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

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

Администратор вашей организации должен включить веб-поиск в Консоли.

Предоставьте инструмент веб-поиска в вашем 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-20250514",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Как обновить веб-приложение до TypeScript 5.5?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

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

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

JSON
{
  "type": "web_search_20250305",
  "name": "web_search",

  // Опционально: Ограничить количество поисков на запрос
  "max_uses": 5,

  // Опционально: Включать результаты только с этих доменов
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Опционально: Никогда не включать результаты с этих доменов
  "blocked_domains": ["untrustedsource.com"],

  // Опционально: Локализовать результаты поиска
  "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.

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

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

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

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

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

​
Ответ

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

{
  "role": "assistant",
  "content": [
    // 1. Решение Claude искать
    {
      "type": "text",
      "text": "Я поищу, когда родился Claude Shannon."
    },
    // 2. Используемый поисковый запрос
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Результаты поиска
    {
      "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": "На основе результатов поиска, ",
      "type": "text"
    },
    // 4. Ответ Claude с цитатами
    {
      "text": "Claude Shannon родился 30 апреля 1916 года в Петоски, Мичиган",
      "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 не засчитываются в использование входных или выходных токенов.

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

​
Ошибки

Если во время веб-поиска происходит ошибка, вы получите ответ следующего вида:

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

# Первый запрос с веб-поиском и точкой останова кэша
messages = [
    {
        "role": "user",
        "content": "Какая сегодня погода в Сан-Франциско?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-20250514",
    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"
        }
    }]
)

# Добавить ответ Claude в разговор
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Второй запрос с точкой останова кэша после результатов поиска
messages.append({
    "role": "user",
    "content": "Стоит ли ожидать дождь на этой неделе?",
    "cache_control": {"type": "ephemeral"}  # Кэшировать до этой точки
})

response2 = client.messages.create(
    model="claude-opus-4-20250514",
    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"
        }
    }]
)
# Второй ответ получит преимущество от кэшированных результатов поиска
# при этом все еще сможет выполнять новые поиски при необходимости
print(f"Токены чтения кэша: {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 искать

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}

// Поисковый запрос передается потоком
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Пауза во время выполнения поиска

// Результаты поиска передаются потоком
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 с цитатами (опущен в этом примере)

​
Пакетные запросы

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