Чтобы ограничить бюджет AI-агента, задайте верхнюю сумму до запуска, ограничьте число источников и глубину исследования, а после завершения сверяйте фактическую стоимость с полезностью результата. В Agent API LLMTOKENAPI за это отвечает maxSpendKopecks: значение передаётся в целых копейках и служит жёсткой верхней границей одного запуска.
Почему лимит нужен до начала работы
Обычный вызов LLM чаще всего имеет один вход и один ответ. Исследовательский агент выполняет цепочку действий: планирует поиск, читает страницы, отбрасывает слабые источники, формирует вывод и иногда продолжает предыдущий запуск. Точная стоимость известна только после завершения, но бизнесу нужен предел ещё до старта.
Постфактум-уведомление не решает задачу. Если процесс уже потратил больше допустимого, отчёт лишь фиксирует проблему. Предварительный лимит позволяет отклонить невозможный сценарий или остановить работу внутри заранее согласованной суммы.
В LLMTOKENAPI поле maxSpendKopecks передаётся в POST /v1/agent/runs. Сервис резервирует верхнюю границу, а после выполнения списывает фактически выполненную работу и освобождает остаток. Все денежные значения выражены целыми копейками, поэтому расчёт не зависит от ошибок округления float.
Начните с минимального полезного результата
Не выбирайте бюджет отдельно от результата. Сначала опишите, что агент обязан вернуть: короткий ответ с проверяемыми ссылками, сравнительную таблицу, список организаций или структурированный объект. Чем точнее критерий готовности, тем легче определить достаточную глубину.
Для первого запуска используйте небольшой maxSources и уровень effort, соответствующий задаче. Если качество подтверждений недостаточно, увеличивайте один параметр за раз. Иначе вы не поймёте, что именно улучшило результат и почему выросла стоимость.
Полезная стартовая матрица выглядит так:
| Сценарий | Начальная глубина | Что проверять |
|---|---|---|
| Быстрый обзор темы | minimal или low | Есть ли прямой ответ и рабочие ссылки |
| Сравнение вариантов | medium | Покрыты ли критерии и противоречия |
| Решение с высокой ценой ошибки | high и выше | Достаточны ли первичные источники и ручная проверка |
Уровень effort — не обещание качества и не замена эксперту. Для финансовых, юридических, медицинских и иных значимых решений итог должен проверять квалифицированный человек.
Передайте ограничения в одном запросе
Пример ограниченного запуска:
curl https://api.llmtokenapi.ru/v1/agent/runs \
-H "Authorization: Bearer $LLMTOKENAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: research-market-2026-08-31" \
-d '{
"query": "Сравни три подхода к семантическому поиску и приведи источники",
"effort": "medium",
"maxSources": 12,
"maxSpendKopecks": 3000,
"metadata": {"scenario": "market-review"}
}'
Здесь 3000 означает верхний предел 30 рублей, а не заранее объявленную цену результата. Фактический расход зависит от выполненных этапов. Актуальные поля Agent API и доступные уровни усилия проверяйте в документации LLMTOKENAPI, а общий подход к расчёту полезной операции — в статье о стоимости LLM API.
Уникальный Idempotency-Key особенно полезен при сетевых сбоях. Если клиент не получил ответ на создание запуска, повтор с тем же ключом должен вернуть уже созданную работу, а не запустить второе исследование. Это согласуется с общей логикой идемпотентности HTTP: RFC 9110 рекомендует автоматически повторять запрос только тогда, когда клиент знает, что повтор не создаст новый эффект.
Ограничивайте не только деньги
Денежный лимит — последняя линия защиты. До него должны работать содержательные ограничения:
maxSourcesзадаёт максимум источников, которые агент может привлечь;effortуправляет глубиной исследовательского pipeline;outputSchemaограничивает форму структурированного результата;- входные данные и исключения сужают область поиска;
- отдельный API-ключ выдаёт только scopes
research:writeиresearch:read; - таймаут продукта определяет, сколько пользователь готов ждать.
Чем уже задача, тем меньше бессмысленных ветвей исследования. Запрос «изучи рынок» почти всегда хуже запроса с географией, периодом, критериями сравнения и форматом выхода. Хорошее ограничение экономит бюджет без снижения качества, потому что агент тратит меньше действий на угадывание намерения.
Наблюдайте за запуском и сохраняйте стоимость
После создания API возвращает объект agent_run и адрес состояния. GET /v1/agent/runs/{id} показывает статус, результат, grounding, использование и costKopecks. Для интерфейса в реальном времени используйте endpoint событий: он поддерживает обычную историю и SSE, а Last-Event-ID позволяет продолжить поток после разрыва соединения.
В аналитике сохраняйте минимум пять полей: сценарий, лимит, фактическую стоимость, длительность и признак принятого результата. Затем считайте не среднюю цену запуска, а стоимость принятого результата. Дешёвые исследования, которые постоянно отправляются на повтор, могут оказаться дороже одного более глубокого запуска.
Не сохраняйте полный запрос и найденные данные автоматически. Metadata должна содержать безопасные технические метки, а не персональные данные или секреты. Для диагностики достаточно идентификатора запуска, request ID, статуса, уровня effort и агрегированного использования.
Отменяйте работу осознанно
Если пользователь изменил задачу или результат больше не нужен, вызовите POST /v1/agent/runs/{id}/cancel. Отмена выполняется между этапами: незапущенная работа освобождает резерв полностью, а уже выполненные поиск, чтение и генерация оплачиваются один раз по факту.
Не создавайте новый запуск только потому, что SSE-соединение оборвалось. Сначала восстановите события через Last-Event-ID или запросите текущее состояние. Новый запуск нужен только для нового намерения либо явного продолжения завершённой работы через previousRunId.
Постройте продуктовый бюджетный контур
Для production удобно задать три уровня контроля. На уровне запроса действует maxSpendKopecks. На уровне сценария хранится рекомендованный лимит и допустимые effort с maxSources. На уровне организации работают рублёвый баланс, scopes ключей и оповещения по агрегированному расходу.
Такой контур делает Agent API предсказуемым: каждый запуск имеет измеримую цель, верхнюю границу и фактическую стоимость. Начните с малого лимита на реальном наборе задач, измерьте долю принятых результатов и повышайте бюджет только там, где дополнительная глубина доказуемо улучшает решение.
