Инструмент веб-поиска предоставляет 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 предоставляет окончательный ответ с цитируемыми источниками.

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

Администратор вашей организации должен включить веб-поиск в 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-20250514",
        "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, но не оба в одном запросе.

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

Параметр 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 не учитываются при подсчете токенов ввода или вывода.

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

​
Ошибки

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

{
  "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-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": "Should I expect rain later this week?",
    "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"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 с цитатами (опущен в этом примере)

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

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

​
Использование и ценообразование

Использование веб-поиска оплачивается дополнительно к использованию токенов:

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

Веб-поиск доступен в API Anthropic по цене $10 за 1000 поисков, плюс стандартная стоимость токенов для контента, сгенерированного поиском. Результаты веб-поиска, полученные в течение беседы, учитываются как входные токены, как в итерациях поиска, выполненных за один ход, так и в последующих ходах беседы.

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