# Agent API: как запустить многошагового AI-агента

Практическое руководство по Agent API: постановка задачи, Idempotency-Key, входные строки, JSON Schema, SSE-события, бюджет, отмена и проверка источников.

Канонический URL: https://llmtokenapi.ru/blog/agent-api-mnogoshagovyy-ai-agent
Опубликовано: 2026-09-08T15:20:42.718Z
Автор: Команда LLMTOKENAPI

Agent API нужен, когда задача требует нескольких управляемых шагов: спланировать поиск, собрать публичные источники, проверить факты и вернуть текстовый или структурированный результат. В LLMTOKENAPI такой запуск создаётся через `POST /v1/agent/runs`, выполняется асинхронно и имеет собственный статус, историю событий, верхний бюджет и подтверждающие ссылки.

## Отличите Agent API от Search и Research

`POST /v1/search` решает один поисковый запрос и быстро возвращает ранжированные страницы. Research API готовит развёрнутое веб-исследование с цитатами. Agent API добавляет управляемый многошаговый run: он подходит для сбора списка, проверки входных строк, обогащения таблицы и продолжения предыдущей работы.

Выбирайте Agent API, если есть явная задача и критерий готовности, а промежуточные действия заранее не сводятся к одному вызову. Для простого факта начните с Search. Для одного отчёта без входного набора обычно достаточно [Research API](/blog/research-api-dlya-web-issledovaniy). Это снижает задержку и делает стоимость предсказуемее.

## Сформулируйте проверяемый query

Поле `query` допускает до 20 000 символов, но объём не заменяет точность. Укажите объект исследования, период, географию, обязательные поля, допустимые источники и поведение при отсутствии данных. Например: «Проверь публичные страницы пяти компаний, найди действующий тариф API и верни только значения, подтверждённые официальной ссылкой; если цена не найдена, поставь `null`».

В `systemPrompt` можно закрепить правила роли длиной до 8 000 символов. Не дублируйте туда секреты и пользовательские данные. Инструкции из найденных страниц считайте недоверенным содержимым: они не должны менять системное задание, scopes или формат результата.

## Запустите run идемпотентно

Для создания нужен scope `research:write` и заголовок `Idempotency-Key`. Лимит `maxSpendKopecks` задаётся целым числом копеек:

```bash
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 сущностей, которые нельзя возвращать повторно:

```json
{
  "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`: важное значение должно иметь публичный источник, который действительно его подтверждает. Не превращайте отсутствие данных в пустую строку или выдуманное число. Более подробная работа со схемами разобрана в статье про [структурированный веб-анализ](/blog/strukturirovannyy-web-analiz-v-json).

## Наблюдайте через status или SSE

Для чтения нужен scope `research:read`. Обычный polling выглядит так:

```bash
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](https://api.llmtokenapi.ru/openapi.json).

## Ограничьте стоимость и умейте отменять

`effort` принимает `minimal`, `low`, `medium`, `high`, `xhigh`, `auto` или `max`. Начинайте с `auto` либо `medium`, затем сравнивайте качество на одинаковых задачах. `maxSources` ограничивает ширину доказательной базы, а `maxSpendKopecks` задаёт верхний бюджет до запуска. Подробная модель резервирования описана в материале [как ограничить бюджет AI-агента](/blog/kak-ogranichit-byudzhet-ai-agenta).

Активную работу можно отменить через `POST /v1/agent/runs/RUN_ID/cancel` со scope `research:write`. До фактического старта резерв освобождается полностью; после старта учитываются уже выполненные операции. Клиент должен уметь отменять run при уходе пользователя, изменении входных данных или достижении собственного таймаута.

## Продолжайте и удаляйте осознанно

`previousRunId` позволяет продолжить завершённый запуск в той же рабочей области. Передавайте его только для связанной задачи и формулируйте, что изменилось: новые строки, другой период или уточнённый критерий. Не используйте цепочку как бесконечную память — сохраняйте итоговые факты в собственной системе после проверки.

Удалить можно только конечный run через `DELETE /v1/agent/runs/RUN_ID`. Это удаляет сохранённый результат запуска, но не отменяет уже учтённое использование и не удаляет данные, которые ваше приложение успело скопировать.

## Постройте оценку до масштабирования

Соберите набор типовых задач с ожидаемыми полями и источниками. Измеряйте долю заполненных строк, точность значений, качество grounding, дубликаты, задержку и фактическую стоимость. Отдельно тестируйте отсутствие ответа, конфликт источников, разрыв SSE и повтор запроса с тем же идемпотентным ключом.

Полная [документация LLMTOKENAPI](/docs) содержит scopes и соседние методы. Надёжный Agent API — это не максимальная автономность, а ограниченный run с проверяемой целью, бюджетом, воспроизводимыми событиями и явным решением о том, когда результат достаточно хорош для вашего продукта.