Лимиты запусков агентов по тарифу

30 июня 2026

AI-агенты потребляют ресурсы: токены LLM, время GPU, деньги. В коммерческом SaaS это нужно ограничивать и показывать пользователю прозрачно. Шаблон связывает тарифный план с месячной (или дневной) квотой запусков агентов — agentRunsIncluded в plans.ts.

Цифры из коробки: Daily — 20 запусков в день (удобно для тестов), Pro — 200 в месяц, Enterprise — 2000 в месяц. Меняйте их вместе с ценой: пользователь на /billing видит остаток и историю, маркетинг на Premium — включённый объём в списке фич.

Один запуск — один успешный вызов POST к api/agents/$slug. Демо на /demo не списывает квоту. Просмотр страницы агента (agent_viewed) тоже не списывает — только отправка сообщения, которое запускает стрим.

Логика учёта в app/lib/usage/usage.server.ts. Три фазы: reserve перед началом стрима (атомарно уменьшает остаток или возвращает ошибку), commit после успешного завершения (фиксирует запись в истории), release при ошибке или обрыве (возвращает единицу в квоту).

Почему reserve, а не списание после? Чтобы два параллельных запроса при остатке 1 не оба прошли. Транзакция в PostgreSQL гарантирует, что второй получит 402 Payment Required.

На странице /billing компонент AgentUsageMeter показывает прогресс-бар: использовано / включено в тариф, процент, предупреждение при приближении к лимиту. AgentUsageHistoryTable — таблица последних запусков: дата, slug агента, статус (success, error, refunded).

При исчерпании квоты API возвращает HTTP 402 с телом, понятным клиенту: сообщение об апгрейде и ссылка на /billing. AgentWorkspace перехватывает это и показывает CTA вместо пустого чата.

Смена тарифа (апгрейд) пересчитывает лимит: новый agentRunsIncluded применяется с момента активации подписки. Downgrade обычно вступает в силу в следующем периоде — детали в billing.server.ts и docs/specs/usage-billing.md.

Админ может временно поднять лимит для тестового аккаунта, изменив подписку в БД или добавив enterprise-план. Для внутренней команды заведите отдельный тариф с высоким agentRunsIncluded.

Аналитика фиксирует agent_message_sent с slug и длительностью — можно строить отчёты «какой агент популярнее» и «среднее время ответа». Это не заменяет биллинговый учёт, но дополняет продуктовую аналитику.

При добавлении нового платного API (не только агенты) копируйте паттерн reserve/commit/release. Один модуль usage.server.ts на агентов — шаблон для других metered features.

Документация по биллингу usage: docs/specs/usage-billing.md. Читайте перед изменением формул периода (календарный месяц vs 30 дней с момента оплаты) — от этого зависит справедливость квоты.