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

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

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

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

  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • 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 предоставляет финальный ответ с цитированными источниками.

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

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

Предоставьте инструмент веб-поиска в вашем 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-1-20250805",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "How do I update a web app to 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, но не оба в одном запросе.

Ограничения доменов на уровне запроса должны быть совместимы с ограничениями доменов на уровне организации, настроенными в Console. Домены на уровне запроса могут только дополнительно ограничивать домены, но не переопределять или расширять за пределы списка на уровне организации. Если ваш запрос включает домены, которые конфликтуют с настройками организации, API вернет ошибку валидации.

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

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

​
Ответ

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

{
  "role": "assistant",
  "content": [
    // 1. Решение Claude искать
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 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": "Based on the search results, ",
      "type": "text"
    },
    // 4. Ответ Claude с цитатами
    {
      "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 не учитываются в использовании входных или выходных токенов.

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

​
Ошибки

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

# Первый запрос с веб-поиском и точкой прерывания кэша
messages = [
    {
        "role": "user",
        "content": "What's the current weather in San Francisco today?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-1-20250805",
    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": "Should I expect rain later this week?",
    "cache_control": {"type": "ephemeral"}  # Кэшировать до этой точки
})

response2 = client.messages.create(
    model="claude-opus-4-1-20250805",
    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"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 искать

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 с цитатами (опущен в этом примере)

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

Вы можете включить инструмент веб-поиска в 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 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.