SuperAGI

SuperAGI — self-hosted платформа для автономных агентов: веб-интерфейс, агенты с целями и ресурсами, набор встроенных инструментов (toolkits), журнал выполнения и параллельные запуски. Обращения к модели SuperAGI делает через OpenAI-совместимый клиент, поэтому подключение к SpeShu.AI сводится к замене адреса шлюза и ключа — код агентов и toolkits менять не нужно.

От SuperAGI нужны ровно две вещи: переменная OPENAI_API_BASE со значением https://speshu.ai/api/v1 и OPENAI_API_KEY с вашим ключом. Эндпоинт /api/v1/chat/completions совместим с OpenAI Chat Completions, поэтому клиент SuperAGI работает без изменений. Ключ создаётся на speshu.ai/profile, подробности — в разделе Аутентификация.

Ключ и идентификатор модели

Ключ

export SPESHU_API_KEY="sk-ваш-ключ"

Проверьте его запросом баланса — он не стоит токенов и не обращается к моделям:

cURL

curl -s https://speshu.ai/api/v1/balance \
  -H "Authorization: Bearer $SPESHU_API_KEY"

Идентификатор модели из каталога

Идентификаторы текстовых моделей не зашивайте в код: состав каталога меняется, и зашитое в конфиг значение начинает падать с 404 model_not_found без предупреждения. Возьмите значение из GET /api/v1/models:

cURL

export TEXT_MODEL=$(curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[0].id')
echo "$TEXT_MODEL"

.data[0] — первый элемент, чтобы пример был запускаемым. В своём конфиге выбирайте по context_length, cost_completion и наличию зрения. Формат ответа — в разделе Каталог моделей.

Развёртывание

SuperAGI читает настройки из файла config.yaml в корне проекта, шаблон которого лежит в config_template.yaml. Переменные окружения имеют приоритет над файлом, поэтому оба способа равнозначны.

git clone https://github.com/TransformerOptimus/SuperAGI.git
cd SuperAGI
cp config_template.yaml config.yaml

Запуск готовым образом — с монтированием каталога, чтобы config.yaml попал внутрь контейнера:

docker run -p 3030:3000 \
  -e OPENAI_API_KEY="$SPESHU_API_KEY" \
  -e OPENAI_API_BASE="https://speshu.ai/api/v1" \
  -e MODEL_NAME="$TEXT_MODEL" \
  -v "$PWD":/app \
  superagi/superagi

Порт в примере опубликован как 3030:3000; если ваша сборка отвечает на другом порту, поправьте правую часть. Через docker compose порт публикует nginx-прокси — в штатном docker-compose.yaml это 3000:80.

Конфигурация

Три значения в config.yaml. Имена ключей те же, что и у переменных окружения:

OPENAI_API_KEY: "sk-ваш-ключ"
OPENAI_API_BASE: "https://speshu.ai/api/v1"
MODEL_NAME: "<идентификатор из GET /api/v1/models>"
MAX_MODEL_TOKEN_LIMIT: 4032

Ключ	Что задаёт
`OPENAI_API_BASE`	Адрес шлюза. Именно его клиент OpenAI в SuperAGI использует как базу для всех вызовов
`OPENAI_API_KEY`	Ключ, который уходит в заголовок `Authorization: Bearer`
`MODEL_NAME`	Модель по умолчанию для старых версий; в текущих версиях агент берёт модель из списка в интерфейсе
`MAX_MODEL_TOKEN_LIMIT`	Потолок `max_tokens` в одном вызове. Слишком большое значение даёт `422 content_too_large`

Адрес пишите без завершающего слэша: https://speshu.ai/api/v1. Со слэшем на конце клиент склеит его с /chat/completions и получит 404 — при полностью верных ключе и модели.

Конфигурация читается при старте процесса. После правки config.yaml перезапустите контейнер: docker restart <имя-контейнера>. Переменная OPENAI_API_BASE действует глобально — по ней пойдёт и эмбеддинг-клиент, о котором ниже.

Модель в интерфейсе

В текущих версиях SuperAGI модель не одна на инсталляцию: агент выбирает её из списка, который заведён в базе. Откройте Settings → Models, добавьте модель с провайдером OpenAI, укажите в поле ключа значение SPESHU_API_KEY и впишите идентификатор из GET /api/v1/models в качестве имени модели. Поле Token limit задайте по context_length выбранной модели — SuperAGI обрезает по нему вход.

Модель с ключом можно добавить и позже, в момент создания агента: в форме агента поле Select Model показывает всё, что есть в Settings → Models. Хранить ключ в интерфейсе удобно тем, что он шифруется; в config.yaml он лежит открытым текстом — не коммитьте этот файл.

Первый работающий пример

Создайте агента с одной узкой целью и без инструментов, которые меняют внешнее состояние:

Откройте Create an Agent.
Agent name — speshu-smoke, Description — Проверка подключения.
Goals — Ответь одним предложением: работает ли подключение к языковой модели.
Select Model — модель, добавленная в Settings → Models.
Max Iteration — 2.
Permission type — Restricted: агент будет спрашивать подтверждение перед действиями.

Запустите агента и откройте журнал выполнения. Ожидаемый результат — короткий текстовый ответ и несколько шагов планирования, без вызовов инструментов.

Проверьте, что запрос дошёл до SpeShu.AI

Логи агента показывают ход рассуждения, но не адрес шлюза. Достоверная проверка — баланс и логи контейнера:

cURL

# было до запуска
curl -s https://speshu.ai/api/v1/balance -H "Authorization: Bearer $SPESHU_API_KEY"
# запустите агента, затем
curl -s https://speshu.ai/api/v1/balance -H "Authorization: Bearer $SPESHU_API_KEY"

Разница между двумя ответами — сумма, списанная за запуск. Поле usage.cost.total_cost в ответе /chat/completions содержит то же значение в рублях; как его читать — в разделе Тарификация и оплата. Если в логах контейнера видны Authentication error или OpenAi Exception, адрес или ключ не применились:

docker logs -f <имя-контейнера> 2>&1 | grep -iE "openai|exception|authentication"

Об инструментах, потоке и эмбеддингах

SpeShu.AI не отдаёт эмбеддинги: эндпоинта /embeddings в /api/v1 нет, и запрос к нему вернёт 404. При этом клиент эмбеддингов в SuperAGI устроен так же, как LLM-клиент: он берёт тот же ключ и тот же базовый адрес. Если у вас включён менеджер ресурсов (поиск по загруженным файлам), он пойдёт на https://speshu.ai/api/v1/embeddings и упадёт.Три честных варианта. Первый: держите эмбеддинги у другого провайдера — SuperAGI умеет работать с Pinecone, Weaviate, Qdrant и Redis, и там эмбеддинги считаются отдельным сервисом. Второй: уберите ресурсы у агента и не пользуйтесь менеджером ресурсов — цикл goals/instructions/tools от этого не меняется. Третий: замените векторное хранилище ресурсов на Chroma, ключи которого задаются отдельно в config.yaml. Подробнее о векторных хранилищах — на странице Chroma Vector DB.

Встроенные toolkits SuperAGI — это его собственные инструменты: агент выбирает их по описанию, а результат подставляет в следующий шаг. Это не поле tools в теле запроса /chat/completions, поэтому агентный цикл у SuperAGI не требует поддержки вызова функций на стороне модели. Если вам нужен именно протокол tool calling поверх SpeShu.AI — смотрите гайд Вызов функций.

SuperAGI ждёт полного ответа и печатает его в журнал выполнения, а не отдаёт по частям. Потоковая передача пригодится, если вы вызываете /chat/completions напрямую из своего кода или скрипта SuperAGI: параметр stream: true и формат SSE описаны в гайде Потоковая передача. Генерация медиа в цикл агента не входит — медиа-задачи асинхронные, с оплатой при создании и отдельным опросом. Создавайте их из своего кода, дожидаясь state: "success": Создание задачи и Статус задачи.

Частые проблемы

404 на запросе при верных ключе и модели

Проверьте OPENAI_API_BASE: должно быть ровно https://speshu.ai/api/v1 — без завершающего слэша и без потери /v1. Адрес вида https://speshu.ai/api даёт тот же 404. Если вы правили config.yaml, перезапустите контейнер: переменные читаются при старте.

401 invalid_api_key или Authentication error в логах

Ключ не подставился. Проверьте значение в самом контейнере: docker exec -it <имя-контейнера> env | grep OPENAI. Переменная окружения перекрывает config.yaml, поэтому ключ, прописанный в файле, может быть проигнорирован — проверьте оба места. Разбор — в разделе Аутентификация.

404 model_not_found

В MODEL_NAME или в карточке модели в интерфейсе зашит идентификатор, которого больше нет в GET /api/v1/models. Обновите его в обоих местах: переменная окружения и запись в Settings → Models не связаны.

Список моделей в интерфейсе пустой

Так ведёт себя код SuperAGI, который фильтрует ответ провайдера по короткому встроенному списку идентификаторов. Добавьте модель вручную в Settings → Models с именем из GET /api/v1/models — агент будет использовать именно её.

402 insufficient_quota или 422 content_too_large на запуске

Первое — исчерпан кошелёк: каждый шаг цикла агента — это отдельный платный запрос, поэтому ограничьте Max Iteration и пополните баланс. Второе — вход не помещается в окно модели: сократите инструкции, разбейте цель на части или возьмите модель с большим context_length из Каталога моделей. Полный список кодов и цикл повторов — на странице Ошибки.

Что дальше

Начало работы

Полный маршрут от ключа до медиа-задачи

Модели и цены

Как выбрать идентификатор и на что смотреть

Запрос чату

Поля запроса и формат ответа

Лимиты

Таймауты и частотные ограничения

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Ключ и идентификатор модели

Развёртывание

Конфигурация

Модель в интерфейсе

Первый работающий пример

Проверьте, что запрос дошёл до SpeShu.AI

Об инструментах, потоке и эмбеддингах

Частые проблемы

Что дальше

Начало работы

Модели и цены

Запрос чату

Лимиты

​Ключ и идентификатор модели

​Развёртывание

​Конфигурация

​Модель в интерфейсе

​Первый работающий пример

​Проверьте, что запрос дошёл до SpeShu.AI

​Об инструментах, потоке и эмбеддингах

​Частые проблемы

​Что дальше

Начало работы

Модели и цены

Запрос чату

Лимиты

Ключ и идентификатор модели

Развёртывание

Конфигурация

Модель в интерфейсе

Первый работающий пример

Проверьте, что запрос дошёл до SpeShu.AI

Об инструментах, потоке и эмбеддингах

Частые проблемы

Что дальше