Web search и fetch API для нейросетей: архитектура, ошибки интеграции и оплата

Для бизнеса это важный параметр: агент может получать данные из документации, ценовых страниц и отчётов, но каждая лишняя загруженная страница расходует контекстное окно, лимит итераций и бюджет. Хабр также разбирает подключение с оплатой в рублях, а Клерк.ру опубликовал материал о платежах OpenAI, Claude и Gemini и учёте расходов.

Поиск находит, fetch загружает

Начнём с конкретной задачи: агенту нужно найти подходящую страницу документации и проверить нужный параметр, а не выдать пользователю список URL.

Рабочая цепочка выглядит так:

1. Модель получает описание доступного инструмента и формирует структурированный вызов.

2. Web search отправляет запрос и возвращает заголовки, адреса и короткие сниппеты результатов.

3. Агент выбирает наиболее релевантный источник.

4. Web fetch загружает конкретный URL и очищает страницу от HTML, навигации, рекламы и скриптов.

5. Вызывающий код проверяет результат, ограничивает объём и передаёт его модели для следующей итерации.

Сниппет помогает выбрать источник, но для сложного вопроса его часто недостаточно. Поэтому search и fetch обычно работают последовательно: первый этап сужает область поиска, второй извлекает содержимое конкретной страницы.

То же правило работает даже для узкой справочной задачи: для гайда по Ретри Паладину в WoW Forever полезна конкретная страница о талантах, ротациях и выборе расы, поэтому fetch должен адресно открыть её, а не нагружать контекст всем сайтом.

Инфраструктуру можно собрать тремя способами:

1. Серверные инструменты провайдера модели. Поиск и загрузка выполняются внутри запроса, этот вариант проще.

2. Отдельные Search и Fetch API. Код вызывает их самостоятельно, получая больше контроля над содержимым контекста.

3. Собственный метапоисковик и парсер. Такой контур не требует оплаты стороннему API, но заметно увеличивает объём поддержки.

Где агент съедает контекст

По приведённой в материале Хабра оценке Anthropic, страница документации размером 100 КБ может занять около 25 000 токенов. Для обычной страницы размером 10 КБ оценка составляет примерно 2 500 токенов. Пять больших страниц подряд способны быстро заполнить значительную часть контекстного окна и бюджета.

Есть ещё один практический барьер: Cloudflare по умолчанию блокирует ИИ-краулеры и может вернуть код 402 Payment Required. Поэтому неудачный fetch не всегда означает проблему с самим API. Ошибку нужно показать модели, чтобы она смогла изменить запрос или выбрать другой источник.

Типичные ошибки связки выглядят так:

1. Слишком общее описание инструмента заставляет модель искать без ограничений.

2. Отсутствие параметров в JSON Schema приводит к вызовам с пустыми аргументами.

3. В OpenAI-совместимом API аргументы приходят строкой JSON, поэтому их нужно разобрать и проверить самостоятельно.

4. Если модель вернула несколько вызовов, каждому требуется отдельный ответ с совпадающим tool_call_id.

5. Необработанное исключение прерывает цикл вместо того, чтобы дать модели chance выбрать другую стратегию.

6. Без лимита шагов агент может зациклиться на одной ошибке и продолжить расходовать деньги.

Рабочая итерация и контроль расходов

Надёжный контур начинается не с выбора API, а с описания задачи. Параметр description должен объяснять, когда инструмент действительно нужен. Затем код валидирует аргументы, очищает HTML, преобразует содержимое в Markdown и обрезает результат до заданного числа символов или токенов.

Отдельно стоит учитывать число запросов, загруженных страниц и шагов цикла. Эти значения полезно сохранять вместе с моделью, инструментом и аргументами вызова. Тогда расходы можно объяснить, а повторяющийся сбой быстро заметить до масштабирования.

По доступным фрагментам двух публикаций нельзя подтвердить конкретный рублёвый платёжный маршрут или список подходящих сервисов. Хабр заявляет разбор подключения с оплатой в рублях, а Клерк.ру рассматривает оплату OpenAI, Claude и Gemini, но конкретные условия в заголовках не раскрыты. Перед интеграцией нужно проверить актуальную документацию, доступные способы оплаты, тарифы и лимиты, после чего провести короткий тест: один search, один fetch, обработку ошибки 402 и ограничение числа итераций.