# Как ограничить бюджет AI-агента до запуска

Разбираем, как ограничить бюджет AI-агента через maxSpendKopecks, effort, число источников, scopes, идемпотентность и контроль фактической стоимости.

Канонический URL: https://llmtokenapi.ru/blog/kak-ogranichit-byudzhet-ai-agenta
Опубликовано: 2026-08-31T15:17:50.830Z
Автор: Команда LLMTOKENAPI

Чтобы ограничить бюджет AI-агента, задайте верхнюю сумму до запуска, ограничьте число источников и глубину исследования, а после завершения сверяйте фактическую стоимость с полезностью результата. В Agent API LLMTOKENAPI за это отвечает `maxSpendKopecks`: значение передаётся в целых копейках и служит жёсткой верхней границей одного запуска.

## Почему лимит нужен до начала работы

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

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

В LLMTOKENAPI поле `maxSpendKopecks` передаётся в `POST /v1/agent/runs`. Сервис резервирует верхнюю границу, а после выполнения списывает фактически выполненную работу и освобождает остаток. Все денежные значения выражены целыми копейками, поэтому расчёт не зависит от ошибок округления float.

## Начните с минимального полезного результата

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

Для первого запуска используйте небольшой `maxSources` и уровень `effort`, соответствующий задаче. Если качество подтверждений недостаточно, увеличивайте один параметр за раз. Иначе вы не поймёте, что именно улучшило результат и почему выросла стоимость.

Полезная стартовая матрица выглядит так:

| Сценарий | Начальная глубина | Что проверять |
| --- | --- | --- |
| Быстрый обзор темы | `minimal` или `low` | Есть ли прямой ответ и рабочие ссылки |
| Сравнение вариантов | `medium` | Покрыты ли критерии и противоречия |
| Решение с высокой ценой ошибки | `high` и выше | Достаточны ли первичные источники и ручная проверка |

Уровень `effort` — не обещание качества и не замена эксперту. Для финансовых, юридических, медицинских и иных значимых решений итог должен проверять квалифицированный человек.

## Передайте ограничения в одном запросе

Пример ограниченного запуска:

```bash
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](/docs), а общий подход к расчёту полезной операции — в статье [о стоимости LLM API](/blog/stoimost-llm-api-v-rublyah).

Уникальный `Idempotency-Key` особенно полезен при сетевых сбоях. Если клиент не получил ответ на создание запуска, повтор с тем же ключом должен вернуть уже созданную работу, а не запустить второе исследование. Это согласуется с общей логикой идемпотентности HTTP: [RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2) рекомендует автоматически повторять запрос только тогда, когда клиент знает, что повтор не создаст новый эффект.

## Ограничивайте не только деньги

Денежный лимит — последняя линия защиты. До него должны работать содержательные ограничения:

- `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 предсказуемым: каждый запуск имеет измеримую цель, верхнюю границу и фактическую стоимость. Начните с малого лимита на реальном наборе задач, измерьте долю принятых результатов и повышайте бюджет только там, где дополнительная глубина доказуемо улучшает решение.