Agent API нужен, когда задача требует нескольких управляемых шагов: спланировать поиск, собрать публичные источники, проверить факты и вернуть текстовый или структурированный результат. В LLMTOKENAPI такой запуск создаётся через POST /v1/agent/runs, выполняется асинхронно и имеет собственный статус, историю событий, верхний бюджет и подтверждающие ссылки.
Отличите Agent API от Search и Research
POST /v1/search решает один поисковый запрос и быстро возвращает ранжированные страницы. Research API готовит развёрнутое веб-исследование с цитатами. Agent API добавляет управляемый многошаговый run: он подходит для сбора списка, проверки входных строк, обогащения таблицы и продолжения предыдущей работы.
Выбирайте Agent API, если есть явная задача и критерий готовности, а промежуточные действия заранее не сводятся к одному вызову. Для простого факта начните с Search. Для одного отчёта без входного набора обычно достаточно Research API. Это снижает задержку и делает стоимость предсказуемее.
Сформулируйте проверяемый query
Поле query допускает до 20 000 символов, но объём не заменяет точность. Укажите объект исследования, период, географию, обязательные поля, допустимые источники и поведение при отсутствии данных. Например: «Проверь публичные страницы пяти компаний, найди действующий тариф API и верни только значения, подтверждённые официальной ссылкой; если цена не найдена, поставь null».
В systemPrompt можно закрепить правила роли длиной до 8 000 символов. Не дублируйте туда секреты и пользовательские данные. Инструкции из найденных страниц считайте недоверенным содержимым: они не должны менять системное задание, scopes или формат результата.
Запустите run идемпотентно
Для создания нужен scope research:write и заголовок Idempotency-Key. Лимит maxSpendKopecks задаётся целым числом копеек:
curl https://api.llmtokenapi.ru/v1/agent/runs \
-H "Authorization: Bearer $LLMTOKENAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: api-prices-2026-09-08" \
-d '{
"query": "Собери действующие тарифы API трёх указанных компаний. Для каждого значения верни официальную ссылку и дату проверки.",
"effort": "medium",
"maxSources": 20,
"maxSpendKopecks": 800
}'
Ответ 202 Accepted содержит run, заголовок Location ведёт на /v1/agent/runs/RUN_ID, а Link указывает на поток событий. При таймауте повторите тот же запрос с тем же ключом: новый ключ означает новую логическую работу и может создать отдельное резервирование.
Передайте строки для проверки или обогащения
Поле input.data принимает до 1 000 объектов. Это удобно, если приложение уже знает компании, товары или URL и просит дополнить только недостающие данные. В input.exclusion можно передать до 1 000 сущностей, которые нельзя возвращать повторно:
{
"input": {
"data": [
{"company": "Компания А", "url": "https://example.com"},
{"company": "Компания Б", "url": "https://example.org"}
],
"exclusion": [
{"company": "Уже проверенная компания"}
]
}
}
Не загружайте весь CRM-экспорт «на всякий случай». Оставляйте только поля, необходимые для текущей задачи, и заранее удаляйте секреты и персональные данные. Ограничение в 1 000 строк — технический максимум, а не рекомендация для одного запуска; сначала измерьте качество на малом пакете.
Зафиксируйте результат через JSON Schema
Без outputSchema агент может вернуть текст. Для последующей автоматизации задайте безопасную JSON Schema с обязательными полями, типами и разрешением null там, где доказательства могут отсутствовать. Например, объект результата может содержать массив items, а каждая строка — name, price, checkedAt и sourceUrl.
Схема проверяет форму, но не истинность. После завершения сверяйте grounding: важное значение должно иметь публичный источник, который действительно его подтверждает. Не превращайте отсутствие данных в пустую строку или выдуманное число. Более подробная работа со схемами разобрана в статье про структурированный веб-анализ.
Наблюдайте через status или SSE
Для чтения нужен scope research:read. Обычный polling выглядит так:
curl https://api.llmtokenapi.ru/v1/agent/runs/RUN_ID \
-H "Authorization: Bearer $LLMTOKENAPI_API_KEY"
Состояние проходит через queued и running к completed, failed или cancelled. Увеличивайте интервал polling и прекращайте запросы после конечного статуса. Список последних запусков доступен через GET /v1/agent/runs?limit=20.
Для интерфейса с живым прогрессом используйте GET /v1/agent/runs/RUN_ID/events с Accept: text/event-stream. Сохраняйте идентификатор последнего события и при реконнекте отправляйте Last-Event-ID; так клиент получает продолжение истории, а не начинает наблюдение вслепую. Актуальные поля ответа опубликованы в OpenAPI LLMTOKENAPI.
Ограничьте стоимость и умейте отменять
effort принимает minimal, low, medium, high, xhigh, auto или max. Начинайте с auto либо medium, затем сравнивайте качество на одинаковых задачах. maxSources ограничивает ширину доказательной базы, а maxSpendKopecks задаёт верхний бюджет до запуска. Подробная модель резервирования описана в материале как ограничить бюджет AI-агента.
Активную работу можно отменить через POST /v1/agent/runs/RUN_ID/cancel со scope research:write. До фактического старта резерв освобождается полностью; после старта учитываются уже выполненные операции. Клиент должен уметь отменять run при уходе пользователя, изменении входных данных или достижении собственного таймаута.
Продолжайте и удаляйте осознанно
previousRunId позволяет продолжить завершённый запуск в той же рабочей области. Передавайте его только для связанной задачи и формулируйте, что изменилось: новые строки, другой период или уточнённый критерий. Не используйте цепочку как бесконечную память — сохраняйте итоговые факты в собственной системе после проверки.
Удалить можно только конечный run через DELETE /v1/agent/runs/RUN_ID. Это удаляет сохранённый результат запуска, но не отменяет уже учтённое использование и не удаляет данные, которые ваше приложение успело скопировать.
Постройте оценку до масштабирования
Соберите набор типовых задач с ожидаемыми полями и источниками. Измеряйте долю заполненных строк, точность значений, качество grounding, дубликаты, задержку и фактическую стоимость. Отдельно тестируйте отсутствие ответа, конфликт источников, разрыв SSE и повтор запроса с тем же идемпотентным ключом.
Полная документация LLMTOKENAPI содержит scopes и соседние методы. Надёжный Agent API — это не максимальная автономность, а ограниченный run с проверяемой целью, бюджетом, воспроизводимыми событиями и явным решением о том, когда результат достаточно хорош для вашего продукта.
