AgentGPT: как запустить автономного ИИ-агента прямо в браузере

AgentGPT — open-source раннер агента: вы задаёте цель, он разбивает её на задачи и выполняет их по кругу, пока не кончится лимит циклов. Self-hosted сборка состоит из трёх частей — фронтенд на Next.js (порт 3000), бэкенд на FastAPI (порт 8000) и MySQL. К модели обращается только бэкенд, через LangChain, поэтому подключение SpeShu.AI сводится к двум переменным окружения на серверной части: фронтенд трогать не нужно.

От AgentGPT нужны ровно два значения: адрес шлюза https://speshu.ai/api/v1 и API-ключ. Оба задаются в файле .env в корне репозитория — как REWORKD_PLATFORM_OPENAI_API_BASE и REWORKD_PLATFORM_OPENAI_API_KEY. Ключ создаётся в разделе API-ключей на speshu.ai/profile, подробности — в разделе Аутентификация.

Установка

git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
./setup.sh

На Windows — setup.bat. Скрипт создаёт .env из шаблона .env.example, поднимает базу, бэкенд и фронтенд; после него откройте http://localhost:3000. Файл .env лежит в корне клонированного репозитория на всех платформах одинаково — путь к нему зависит только от того, куда вы склонировали проект.

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

Ключ — переменная окружения, не литерал в коде:

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

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

cURL

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

echo "$SPESHU_MODEL"

Формат ответа и правила выбора — в разделе Модели и цены, сам эндпоинт — в Каталоге моделей.

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

Бэкенд читает .env через pydantic с префиксом REWORKD_PLATFORM_, поэтому названия переменных в шаблоне менять не нужно — правьте значения. Шаблон .env.example оставьте целиком: в нём есть ссылки вида ${VAR}, которые раскрываются при загрузке.

# адрес шлюза: LangChain подставит его в base_url клиента ChatOpenAI
REWORKD_PLATFORM_OPENAI_API_BASE="https://speshu.ai/api/v1"

# ключ SpeShu.AI
REWORKD_PLATFORM_OPENAI_API_KEY="sk-ваш-ключ"

# сколько кругов агент может сделать за один запуск
REWORKD_PLATFORM_MAX_LOOPS="25"

После правки перезапустите бэкенд: переменные окружения читаются при старте процесса, а не на каждый запрос.

Ключ вписывайте только в .env. Поле API Key на странице Settings во фронтенде — это «свой ключ для OpenAI», и оно работает не так, как выглядит. Если оно заполнено, бэкенд подставляет адрес https://api.openai.com/v1 вместо адреса из .env, то есть ваш ключ уйдёт провайдеру OpenAI, а не в SpeShu.AI. Кнопка Test рядом с этим полем дополнительно отправляет ключ на api.openai.com/v1/engines. Оставьте поле пустым.

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

Идентификатор модели в AgentGPT

Адрес и ключ живут на сервере, а вот идентификатор модели агент отправляет из браузера — и в ветке main он ограничен списком из трёх зашитых в код значений. Список задан словарём LLM_MODEL_MAX_TOKENS в platform/reworkd_platform/schemas/agent.py, а фронтенд подставляет модель из выпадающего списка, который наполняется тем же словарём с бэкенда (GET /api/models). Отсюда два честных варианта. Вариант 1 — модель из каталога есть в списке сборки. Сверьте $SPESHU_MODEL с тем, что показывает выпадающий список Settings → Advanced Settings → Model. Если значения совпадают, ничего менять не нужно. Вариант 2 — идентификатора нет в списке. Это ожидаемо: список в коде проекта не знает про SpeShu.AI. Сделайте форк и расширьте словарь, добавив $SPESHU_MODEL:

Python

# platform/reworkd_platform/schemas/agent.py
LLM_Model = Literal[
    "<идентификатор из GET /api/v1/models>",
]

LLM_MODEL_MAX_TOKENS: Dict[LLM_Model, int] = {
    "<идентификатор из GET /api/v1/models>": 8000,
}

Значение справа — потолок max_tokens для этой модели; запрос больше него бэкенд не примет. Тип Literal продублирован во фронтенде в next/src/types/modelSettings.ts, а next/src/stores/modelSettingsStore.ts перезаписывает выбранную модель при каждом сохранении настроек — эти два места правьте в том же форке, иначе значение вернётся к зашитому.

Первый запуск

Задайте цель

На главной странице введите цель и запустите агента. Один цикл агента — это несколько запросов к модели: анализ, создание задач, выполнение, суммаризация; поэтому лимит циклов напрямую влияет на расход.

Проверьте, что адрес и ключ приняты

Бэкенд не покажет адрес, по которому ушёл запрос, поэтому проверяйте ключ отдельно — он должен быть рабочим и привязанным к вашему балансу:

cURL

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

{ "RUB": "1250.00" }

Проверьте, что модель отвечает через шлюз

Повторите тот же запрос, который агент выполняет сам:

cURL

curl -s https://speshu.ai/api/v1/chat/completions \
-H "Authorization: Bearer $SPESHU_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"model\": \"$SPESHU_MODEL\",
\"messages\": [{\"role\": \"user\", \"content\": \"Назови три шага запуска RAG-бота.\"}]
}" | jq '{model, reply: .choices[0].message.content, charged_rub: .usage.cost.total_cost}'

Если этот запрос отвечает, а агент — нет, дело в конфигурации AgentGPT, а не в ключе. charged_rub — сумма, списанная за этот вызов; разбор поля — в разделе Тарификация и оплата.

Что из коробки работает через SpeShu.AI

Только генерация текста — то есть шаги анализа и планирования агента. Встроенные инструменты AgentGPT (поиск, генерация изображений) используют сторонние сервисы и отдельные ключи, к SpeShu.AI отношения не имеют:

Инструмент агента	Чем обслуживается
Поиск в интернете	отдельный ключ поискового сервиса, задаётся в `.env` рядом с ключом шлюза
Генерация изображений	отдельный токен сервиса генерации, тоже из `.env`

Если вам нужны поиск или изображения через SpeShu.AI, не настраивайте их в AgentGPT — вызывайте их напрямую: медиа-задачи описаны в Создании задачи и Статусе задачи.

Инструменты, которые вы описали сами как OpenAI-совместимые функции, работают через шлюз как обычно: схема уходит в tools, вызов возвращается в choices[0].message.tool_calls. Полный цикл — в гайде Вызов функций.

Потоковая передача

Бэкенд создаёт клиента с streaming: true, поэтому каждый шаг агента уходит в /chat/completions с "stream": true, а интерфейс получает обновления по своему websocket. Формат кадров, маркер [DONE] и кадр со списанием разобраны на странице Потоковая передача.

Об эмбеддингах

Эндпоинта эмбеддингов у SpeShu.AI нет: /embeddings в /api/v1 не существует. Если вы подключаете к AgentGPT векторную память поверх шлюза, она будет обращаться к несуществующему адресу и падать на первом же запросе. Варианта два: оставить память выключенной, либо поднять её на Pinecone — этот сервис считает эмбеддинги сам, отдельным ключом, и к SpeShu.AI отношения не имеет.

Типичные проблемы

401 invalid_api_key при верном ключе

Проверьте, что ключ стоит в REWORKD_PLATFORM_OPENAI_API_KEY в .env, а не в поле API Key на странице Settings, и что бэкенд перезапущен после правки. Заодно убедитесь, что поле во фронтенде пустое — иначе запрос уходит на адрес OpenAI, а не в шлюз.

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

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

404 model_not_found при запуске агента

Агент отправляет модель из своего собственного списка, а не из вашего каталога. Сверьте значение с выпадающим списком Settings → Advanced Settings → Model и, если оно чужое, расширьте словарь в форке — порядок шагов описан в разделе «Идентификатор модели в AgentGPT».

422 content_too_large на длинной цели

Входные токены плюс зарезервированный выход не поместились в окно модели. Уменьшите потолок max_tokens в словаре или в Settings → Advanced Settings → Tokens, сократите цель либо возьмите модель с окном побольше. Повтор с теми же аргументами не поможет.

402 insufficient_quota на первом же цикле

Баланс неположительный. Проверьте остаток через GET /api/v1/balance и пополните его в профиле. Деньги за отказ не списываются: проверка баланса идёт до обращения к модели.

Всё остальное

Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки, таймауты и квоты — в разделе Лимиты.

Что дальше

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

Пополнение счёта и организация ключей в кабинете

Модели и цены

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

Запрос чату

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

Вызов функций

Как описать инструмент для агента

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

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

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

Фреймворки

Базы данных

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

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

AgentGPT: как запустить автономного ИИ-агента прямо в браузере

Установка

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

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

Идентификатор модели в AgentGPT

Первый запуск

Что из коробки работает через SpeShu.AI

Потоковая передача

Об эмбеддингах

Типичные проблемы

Что дальше

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

Модели и цены

Запрос чату

Вызов функций

​Установка

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

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

​Идентификатор модели в AgentGPT

​Первый запуск

​Что из коробки работает через SpeShu.AI

​Потоковая передача

​Об эмбеддингах

​Типичные проблемы

​Что дальше

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

Модели и цены

Запрос чату

Вызов функций

Установка

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

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

Идентификатор модели в AgentGPT

Первый запуск

Что из коробки работает через SpeShu.AI

Потоковая передача

Об эмбеддингах

Типичные проблемы

Что дальше