AIST Agent — API-шлюз к AI-ассистентам

Как это работает

Три шага между вашим кодом и ответом AI-ассистента.

1

Отправьте задачу

POST /api/tasks с JWT-токеном из Aist Back. Укажите ассистента, входные данные — текст, файлы или голос. Получите uuid задачи мгновенно.

2

Обработка в фоне

Agent создаёт чат и ход в Aist Back, передаёт конфигурацию ассистента в Aist Core. Если ассистенту нужны внешние инструменты — Agent вызовет их автоматически.

3

Заберите результат

Поллинг: GET /api/tasks/{uuid} — опрашивайте статус, пока задача не завершится.
Webhook: передайте callback_url при создании — Agent сам уведомит вас, как только обработка завершится.

Ваш сервис

AIST Agent

Aist Back

Aist Core

Внешние API

Возможности

Всё необходимое для интеграции AI в ваш продукт.

Асинхронная обработка

Задачи обрабатываются через Redis-очередь с Horizon. Ваш сервер не ждёт — периодически опрашивает статус по uuid.

Текст, файлы, голос

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

Внешние инструменты

Ассистент сам вызывает внешние HTTP API во время обработки — получает данные, выполняет действия, возвращает результат в контексте ответа.

Безопасность

RS256 JWT-аутентификация с кэшированием публичного ключа. HMAC-подпись webhook-ов. Автоматический отзыв скомпрометированных токенов.

Контроль нагрузки

Атомарный лимит одновременных задач на пользователя с Redis-блокировкой. Настраивается через переменную окружения.

Выбор модели

Передайте llm_model_id или image_generator_id, чтобы выбрать конкретную модель из конфигурации ассистента.

Horizon и масштабирование

Redis-очередь с Laravel Horizon: авто-масштабирование воркеров, мониторинг, повторные попытки при сбоях с экспоненциальной задержкой.

Мультиходовые разговоры

Передайте массив turns с предыдущими ходами — AI продолжит разговор с полным контекстом. Каждый ход содержит messages для восстановления истории.

Webhook-уведомления

Передайте callback_url — Agent отправит результат на ваш URL сразу по завершении. Укажите callback_secret для подписи запроса через HMAC-SHA256: до 5 попыток с backoff.

Где это пригодится

Agent раскрывает потенциал AI-ассистентов за пределами чат-интерфейса.

Чат-боты в мессенджерах

Подключите Telegram, VK или любой мессенджер. Бот отправляет сообщение пользователя в Agent, поллит статус и пересылает ответ обратно. Все возможности ассистента — включая поиск в интернете, генерацию картинок и работу с документами — доступны прямо в чате.

Автоматизация процессов

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

Встраивание AI в продукт

Добавьте AI-функции в своё мобильное или веб-приложение без сложной инфраструктуры. Agent берёт на себя оркестрацию между вашим приложением, хранилищем ассистентов и AI-движком.

Пакетная обработка

Загрузите пачку файлов или текстов, запустите одного ассистента на все задачи. Лимит одновременных задач защищает систему от перегрузки, а Horizon распределяет нагрузку между воркерами.

Быстрый старт

Основные сценарии — от простого запроса до мультиходового разговора с файлами.

POST /api/tasks

// Создаём задачу
curl -X POST https://agent-api.ai.neobash.ru/api/tasks \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "assistant_id": 1,
    "input": [
      {
        "type": "text",
        "text": "Проанализируй этот документ"
      }
    ]
  }'
// Ответ:
{ "uuid": "550e8400-...", "status": "pending" }

GET /api/tasks/{uuid}

// Получаем результат
curl https://agent-api.ai.neobash.ru/api/tasks/550e8400-... \
  -H "Authorization: Bearer <jwt>" \
  -H "Accept: application/json"
// Ответ:
{
  "uuid": "550e8400-...",
  "status": "completed",
  "turn": {
    "output": [{ "type": "text", "text": "Анализ документа..." }],
    "messages": [...],
    "metadata": {...}
  },
  "created_at": "2026-04-16T...",
  "completed_at": "2026-04-16T..."
}

Получение результата через webhook

Передайте callback_url при создании задачи — Agent сам уведомит вас, когда готово. Поллинг не нужен.

POST /api/tasks — с callback_url

// Создаём задачу с webhook
curl -X POST https://agent-api.ai.neobash.ru/api/tasks \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "assistant_id": 1,
    "callback_url": "https://yourapp.com/hook",
    "callback_secret": "your-secret",
    "input": [{
      "type": "text",
      "text": "Что такое Laravel?"
    }]
  }'

VERIFY Верификация входящего webhook

// Agent пришлёт заголовок:
X-Signature: sha256=abc123...
// Верифицируйте на своём сервере:
$body = file_get_contents('php://input');
$expected = hash_hmac(
    'sha256', $body, $secret
);
// Сравните с X-Signature
hash_equals($expected, $received);
// Тело — тот же формат, что GET /api/tasks/{uuid}

Agent доставляет webhook при любом финальном статусе (completed или failed). До 5 попыток с экспоненциальным backoff: 10 с, 30 с, 60 с, 120 с. Если callback_secret не указан — заголовок X-Signature не отправляется, верификация не требуется.

Загрузка файлов

Загрузите файл через POST /api/files, получите id, затем используйте его в задаче.

POST /api/files

// 1. Загружаем файл
curl -X POST https://agent-api.ai.neobash.ru/api/files \
  -H "Authorization: Bearer <jwt>" \
  -H "Accept: application/json" \
  -F "file=@document.pdf"
// Ответ:
{
  "id": 42,
  "name": "document.pdf",
  "mime_type": "application/pdf",
  "size": 102400
}

POST /api/tasks — с файлом

// 2. Используем файл в задаче
curl -X POST https://agent-api.ai.neobash.ru/api/tasks \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "assistant_id": 1,
    "input": [
      { "type": "text", "text": "Резюмируй документ" },
      {
        "type": "file",
        "file": {
          "id": "42",
          "name": "document.pdf",
          "mime_type": "application/pdf"
        }
      }
    ]
  }'

Важно: поле id передаётся как строка (не число), хотя POST /api/files возвращает его как integer. Все три поля (id, name, mime_type) обязательны. Макс. размер файла: 1 ГБ. Поддерживаемые форматы: изображения, документы, текст, аудио, видео.

Мультиходовые разговоры

Передайте предыдущие ходы в массиве turns — AI продолжит разговор с полным контекстом.

1 Первый запрос

// Первый ход — без turns
{
  "assistant_id": 1,
  "input": [
    { "type": "text", "text": "Что такое Laravel?" }
  ]
}
// Ответ — сохраните turn целиком
{ "turn": { "input": [...], "output": [...],
  "messages": [...], "metadata": {...} } }

2 Продолжение разговора

// Второй ход — передаём предыдущий turn
{
  "assistant_id": 1,
  "input": [
    { "type": "text", "text": "Как работает роутинг?" }
  ],
  "turns": [
    // turn из предыдущего ответа целиком
    { "input": [...], "output": [...],
      "messages": [...], "metadata": {...} }
  ]
}

Каждый следующий запрос добавляет предыдущий turn в массив turns. AI-движок использует поле messages из каждого хода для восстановления контекста разговора.

Форматы входных данных

type: "text"

                            { "type": "text",
  "text": "Ваш запрос" }
                        

Текстовый запрос. Основной формат для большинства задач.

type: "file"

                            { "type": "file",
  "file": { "id": "42",
    "name": "doc.pdf",
    "mime_type": "application/pdf" } }
                        

Файл для анализа AI. Загрузите через POST /api/files, используйте id как строку.

type: "voice"

                            { "type": "voice",
  "voice": { "id": "43",
    "name": "rec.mp3",
    "mime_type": "audio/mpeg" } }
                        

Голосовое сообщение. Транскрибируется в текст перед обработкой. Тот же процесс загрузки.

Структура ответа (turn)

{
  "input": [/* входные данные (эхо из запроса) */],
  "output": [{ "type": "text", "text": "Ответ AI..." }],
  "messages": [
    { "role": "user", "content": [...] },
    { "role": "assistant", "content": [...] }
  ],
  "metadata": {
    "cost": { "total": 0.003, "details": { "llm": 0.003, "tools": 0 } },
    "model": "claude-sonnet-4-20250514"
  }
}

Поле	Тип	Описание
input	array	Входные элементы (эхо из запроса)
output	array	Ответ AI — элементы с `type` и `text`
messages	array	Полная история LLM — передайте в `turns` для мультихода
metadata	object	Стоимость и идентификатор использованной модели

Архитектура

Agent — мост между вашим кодом и экосистемой AIST.

AIST Agent

API-шлюз. Принимает задачи, ставит в очередь, оркестрирует обработку, возвращает результат. Laravel 13 + Horizon.

Aist Back

Центральный бэкенд. Хранит пользователей, ассистентов, чаты, ходы, модели, документы, инструменты и балансы.

Aist Core

AI-движок. Работает с 40+ моделями от 6 провайдеров. Обрабатывает ходы, выполняет инструменты, стримит ответы.

Aist Chat

Middleware для чат-интерфейса. SSE-стриминг ответов в реальном времени. Работает параллельно с Agent.

Два пути к одному ассистенту

Через Agent (программный)

REST API → Redis-очередь → Aist Back → Aist Core → polling или webhook. Для серверных интеграций, ботов, автоматизации. Асинхронно, без UI.

Через Chat (интерактивный)

Браузер → Aist Chat → Aist Back → Aist Core → SSE-стрим. Для пользовательского чат-интерфейса. В реальном времени, с UI.

Под капотом

Технические детали для тех, кто будет интегрировать.

Параметр	Значение
Аутентификация	RS256 JWT из Aist Back; поля `sub`, `sanctum`, `exp`, `abilities`
Отзыв токена	403 от Aist Back автоматически вносит JWT в чёрный список; следующие запросы вернут 401
Лимит задач	До 5 активных (Pending/Processing) на пользователя; при превышении — 429
Таймаут принятия	Если aist-core не подтвердил приём в течение 30 с, задача автоматически переходит в `failed`
Коды ошибок задачи	`Assistant is not available` — ассистент недоступен; `Insufficient balance` — недостаточно баланса; `Token revoked` — токен отозван
Webhook-доставка	До 5 попыток с backoff 10 с, 30 с, 60 с, 120 с; заголовки `X-Task-Uuid` и `X-Signature` (если задан `callback_secret`)
Загрузка файлов	Макс. 1 ГБ; форматы: изображения, документы, текст, аудио, видео
Хранение задач	Завершённые и упавшие задачи доступны 30 дней, затем удаляются

llms.txt

Используйте AI-кодинг ассистента для интеграции. Файл llms.txt содержит полную документацию API в формате, оптимизированном для LLM.

Claude Code, Cursor, Windsurf и другие кодинг-ассистенты могут прочитать этот файл и сразу сгенерировать рабочий интеграционный код — с аутентификацией, загрузкой файлов, поллингом и верификацией вебхуков.

Открыть llms.txt

                            Claude Code / Cursor / Windsurf
                        
// Скажите своему ассистенту:
"Прочитай https://agent-api.ai.neobash.ru/llms.txt
 и интегрируй AIST Agent в мой проект.
 Мне нужна отправка текстовых задач
 и приём результата через webhook"