Claude Web Search

Включите веб-поиск для запросов Claude и обрабатывайте блоки результатов и ссылки.

Claude Web Search позволяет поддерживающим его моделям Claude искать в интернете при ответе и возвращать блоки результатов и ссылки, если это допускает протокол. Это подходит для недавних фактов, проверки источников и поиска на заданных сайтах.

AGTCloud может предоставлять Claude через совместимый интерфейс Chat или структуру Anthropic Messages. Поля включения и структура ответа различаются: выбирайте интерфейс по сведениям о текущей модели.

Не фиксируйте версию поискового инструмента навсегда

Нативный инструмент поиска Anthropic использует версионированное имя типа. Доступные версии и поддержка моделей могут меняться. Используйте значения из текущих сведений о модели и соответствующего Reference, а не фиксированные модели или версии из старых проектов.

Поиск через совместимый интерфейс Chat

В прежней документации основной путь AGTCloud включал добавление web_search_options в запрос Chat:

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Найдите важные сегодняшние новости о регулировании искусственного интеллекта и перечислите источники."
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

Текст обычно читается из Assistant Message. Вид ссылок — структурированный Annotation, URL или текст — зависит от модели и интерфейса. Не создавайте ссылки без основания в ответе.

Нативная структура инструментов Anthropic

В интерфейсе Messages с поддержкой нативного Claude Web Search поисковый инструмент находится в tools. Ниже показана только структура протокола: замените тип инструмента версией из документации текущей модели.

{
  "model": "MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Найдите важные сегодняшние новости о регулировании искусственного интеллекта и перечислите источники."
    }
  ],
  "tools": [
    {
      "type": "WEB_SEARCH_TOOL_VERSION",
      "name": "web_search",
      "max_uses": 5
    }
  ]
}

Используйте max_uses, фильтры доменов, местоположение пользователя и динамическую фильтрацию только при поддержке соответствующей версией инструмента. Полные контейнеры Messages и Content Block см. в Anthropic Messages Reference.

Чтение результатов поиска и ссылок

Нативный ответ Messages может содержать разные Content Block:

server_tool_use: модель вызвала серверный инструмент поиска.
web_search_tool_result: результаты поиска или ошибка инструмента.
text: итоговый ответ пользователю.
citations: связь фрагментов ответа с веб-источниками, если она предоставлена.

Клиент должен обрабатывать ветви по type, а не склеивать все Content Blocks как обычные строки.

{
  "content": [
    {
      "type": "text",
      "text": "Согласно результатам поиска…",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://example.com/article",
          "title": "Название источника"
        }
      ]
    }
  ]
}

Пример показывает, что ссылки и текст принадлежат одной структуре ответа. Точные поля определяются текущим ответом и Messages Reference.

Домены, местоположение и динамическая фильтрация

Если версия инструмента поддерживает это, используйте:

allowed_domains: разрешает только заданные домены.
blocked_domains: исключает домены; не задавайте одновременно со списком разрешений.
user_location: город, регион, страна, часовой пояс и другие сведения для локализации.
Динамическую фильтрацию: поддерживаемая комбинация инструментов дополнительно отбирает результаты поиска.

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

Ошибки инструмента и HTTP

Сбой поиска не обязательно означает сбой всего HTTP-запроса. Нативный ответ может иметь успешный статус, но содержать объект ошибки в web_search_tool_result.

Ситуация	Действие
Ошибка HTTP-аутентификации или параметров	Обработайте статус, не переходя к обычному разбору Content Block
Инструмент вернул блок ошибки	Запишите тип ошибки и выберите переформулировку вопроса, сужение области или ответ без поиска
Поиск успешен, но ссылок нет	Укажите, что проверяемые источники отсутствуют; не выдумывайте ссылки
Достигнут лимит поисковых вызовов	Прекратите поиск и сообщите, что результат может быть неполным

Нативный поиск и собственные инструменты

Claude Web Search выполняется моделью или серверным поисковым инструментом. При собственном Tool Calling приложение вызывает свой поисковый сервис и возвращает результат. Для контроля индекса, прав доступа или внутренних данных лучше подходит Tool Calling.

Проверка перед запуском

Модель и протокол явно поддерживают используемые поля Web Search.
Версия типа инструмента взята из текущей документации, а не старого примера.
Content Block, результаты поиска, текст и ссылки разбираются отдельно.
Ошибки инструмента не считаются обычными результатами поиска.
Домены и местоположение отправляются только при необходимости.
Поисковое содержимое не запускает рискованные инструменты напрямую и не обходит авторизацию.

Поля Chat см. в Chat Completions Reference. При ошибках см. Ошибки и диагностика.