Voice Agent на FastAPI и Next.js: от идеи к продакшену

Голос вместо текста: как собрать Voice Agent с нуля на FastAPI и Next.js

Проект Voice Agent начинался как амбициозная идея: приложение, которое понимает речь, общается по голосу и реагирует в реальном времени. Ничего необычного для 2025 года, казалось бы. Но когда встал вопрос архитектуры — монорепозиторий с разделением Python-бэкенда и Next.js-фронтенда, отдельный обработчик голоса, система аутентификации и асинхронный чат с потоковым UI, — осознал: нужно не просто писать код, а выстраивать систему.

Первым делом разобрался с бэкендом. Выбор был между Django REST и FastAPI. FastAPI выиграл благодаря асинхронности из коробки и простоте работы с WebSocket и Server-Sent Events. Версия 0.115 уже вышла с улучшениями для продакшена, и вместе с sse-starlette 2 она идеально подходила для потокового общения. Начал с классического: настройка проекта, структура папок, переменные окружения через load_dotenv(). Важный момент — в Python-бэкенде приходилось быть очень внимательным с импортами: из-за специфики монорепо легко запутаться в пути до модулей, поэтому сразу завел привычку валидировать импорты через python -c 'from src.module import Class' после каждого изменения.

Потом понадобилась аутентификация. Не сложная система, но надежная: JWT-токены, refresh-логика, интеграция с TMA SDK на фронтенде (это была особенность — приложение работает как мини-приложение в Telegram). На фронтенде поднял Next.js 15 с React 19, и здесь выскочила неожиданная беда: Tailwind CSS v4 полностью переписал синтаксис конфигурации. Вместо привычного JavaScript-объекта — теперь CSS-first подход с @import. Монорепо с Turbopack в Next.js еще больше усложнял ситуацию: приходилось добавлять turbopack.root в next.config.ts и явно указывать base в postcss.config.mjs, иначе сборщик терялся в корне проекта.

Интересный момент: FastAPI 0.115 получил встроенные улучшения для middleware и CORS — это было критично для взаимодействия фронтенда и бэкенда через потоковые запросы. Оказалось, многие разработчики всё ещё пытаются использовать старые схемы с простыми HTTP-ответами для голосовых данных, но streaming с SSE — это совсем другой уровень эффективности. Бэкенд отправляет куски данных по мере их готовности, фронтенд их тут же отображает, юзер не висит, дожидаясь полного ответа.

Система валидации стала ключом к стабильности. На бэкенде — проверка импортов и тесты перед коммитом. На фронтенде — npm build перед каждым мерджем. Завел привычку писать в ERROR_JOURNAL.md каждую ошибку, которая повторялась: это предотвратило много дублирования проблем.

В итоге получилась система, где голос идет с клиента, бэкенд его обрабатывает через FastAPI endpoints, генерирует ответ, отправляет его потоком обратно, а React UI отображает в реальном времени. Просто, но изящно. Дальше — добавление более умных агентов и интеграция с внешними API, но фундамент уже крепкий.

Если Java работает — не трогай. Если не работает — тоже не трогай, станет хуже. 😄