OpenAI Web Search

Ищите в интернете через Responses или Chat и обрабатывайте ссылки на источники.

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

Если данные находятся в вашей базе или бизнес-сервисе, определите контролируемый инструмент через Tool Calling, а не передавайте внутренние данные публичному веб-поиску.

Сначала проверьте модель и интерфейс

Наличие полей Web Search в протоколе не означает, что поиск поддерживает каждая модель вашей учётной записи. Сначала проверьте модель и протокол в каталоге моделей, затем изучите соответствующий API Reference.

Выбор Responses или Chat

Интерфейс	Включение	Расположение результата
Responses	Добавьте Web Search Tool в `tools`	`web_search_call` и Message Output Item
Chat Completions	Используйте `web_search_options`	Assistant Message и `annotations`

Responses удобнее приложениям, которым нужно различать вызов поиска, ответ и источники. Chat подходит проектам, уже использующим структуру сообщений.

Поиск через Responses

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "tools": [
      {
        "type": "web_search_preview",
        "search_context_size": "medium"
      }
    ],
    "input": "Какие технологические новости сегодня заслуживают внимания?"
  }'

Модель может решать, нужен ли поиск, исходя из вопроса. Если поиск выполнен, output обычно содержит и элемент вызова поиска, и текстовое сообщение. Полные типы Tool см. в Responses Reference.

Использование Chat Completions

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"
    }
  }'

Текст ответа Chat находится в choices[].message.content, а структурированные ссылки, если они предоставлены, — в choices[].message.annotations. Полные поля см. в Chat Completions Reference.

Чтение ответа и ссылок

{
  "output": [
    {
      "type": "web_search_call",
      "id": "ws_example",
      "status": "completed"
    },
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Согласно результатам поиска…",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://example.com/article",
              "title": "Название источника"
            }
          ]
        }
      ]
    }
  ]
}

Не сохраняйте только текст ответа. Сохраняйте URL, заголовки и связь ссылок с позициями текста, показывайте кликабельные источники и используйте безопасные атрибуты открытия внешних ссылок в новой вкладке.

Ограничение области поиска

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

Домены: поиск только на разрешённых сайтах, например медицинских, правовых или корпоративных источниках.
Местоположение пользователя: страна, город, регион или часовой пояс помогают получать локальные результаты.
Объём поискового контекста: выбирайте баланс качества ответа, задержки и расхода.
Список источников: Responses при поддержке может вернуть источники, изученные во время поиска, а не только процитированные в ответе.

В Responses и Chat эти поля расположены по-разному. Точные имена и ограничения см. в соответствующем Reference.

Ошибки и резервное поведение

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

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

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

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

При ошибках см. Ошибки и диагностика. Перед сменой протокола прочитайте Выбор протокола.