LangGraph-агенты с ChatGPT-интерфейсом: как собрать удобный AI-сервис

Многие эксперименты с LLM заканчиваются на уровне консоли или notebook: модель отвечает, tool calling работает, агент вызывает инструменты, но пользоваться этим каждый день неудобно. Для реального применения нужен интерфейс, история диалогов, авторизация, понятный API и нормальный деплой.

Именно поэтому связка LangGraph + FastAPI + ChatGPT-подобный UI выглядит практичной. LangGraph отвечает за агентную логику, backend публикует API, а frontend даёт пользователю привычный формат общения: список чатов, поле ввода, потоковый вывод ответа, переключение между агентами и сохранение контекста.

Финальный этап такого стека выглядит так: уже есть LLM на сервере, есть агентный backend на LangGraph, есть REST API, и дальше к нему подключается официальный интерфейс agent-chat-ui от LangChain. Для homelab и внутренних AI-инструментов это хороший пример того, как превратить эксперимент в сервис.

Почему одного backend недостаточно

Агентный backend без UI полезен разработчику, но плохо подходит для команды. Если пользователь должен отправлять curl, помнить JSON-схемы и читать streaming response в терминале, инструмент останется игрушкой для инженеров.

UI решает несколько задач:

делает AI-сервис доступным не только backend-разработчикам;
показывает историю диалогов;
позволяет переключать разные режимы или разных агентов;
скрывает технические детали API;
упрощает тестирование сценариев;
помогает быстро показать результат заказчику или команде.

Для внутренних инструментов это особенно важно. Например, агент может анализировать документацию, помогать с incident response, отвечать по базе знаний или запускать безопасные diagnostic tools. Без интерфейса им будет пользоваться только тот, кто его написал.

Роль LangGraph в архитектуре

LangGraph удобен там, где обычной цепочки prompt → answer уже недостаточно. Агент может иметь несколько узлов, состояние, branching, вызовы инструментов и разные маршруты выполнения.

Типичная схема:

Пользовательский запрос
        ↓
LangGraph workflow
        ↓
LLM + tools + память + проверки
        ↓
Ответ и обновлённое состояние диалога

Вместо одного большого prompt появляется граф: отдельный узел может классифицировать запрос, другой — вызвать инструмент, третий — проверить результат, четвёртый — сформировать финальный ответ. Это проще сопровождать, чем монолитную функцию с десятками условий.

Для production-подхода важно, что агент становится не «магией», а программируемой системой. Его поведение можно тестировать, логировать и постепенно усложнять.

Backend: FastAPI и REST API

Если агент должен работать как сервис, ему нужен стабильный API. FastAPI здесь подходит естественно: асинхронность, OpenAPI-документация, удобная типизация и простая интеграция с Python-экосистемой.

Backend обычно закрывает такие задачи:

принимает сообщения пользователя;
передаёт их в LangGraph;
возвращает streaming response;
хранит или прокидывает thread/session id;
валидирует входные данные;
проверяет авторизацию;
логирует ошибки и latency;
ограничивает доступ к инструментам агента.

Даже если сервис внутренний, API лучше проектировать как production-компонент. Потом к нему может подключиться не только web UI, но и Telegram-бот, CLI, Slack-интеграция или другой backend.

Frontend: зачем нужен agent-chat-ui

agent-chat-ui интересен тем, что даёт готовую основу для ChatGPT-подобного интерфейса. Это экономит время: не нужно с нуля писать список сообщений, состояние чата, input, streaming, layout и базовую UX-логику.

Для команды это снижает порог входа. Можно сосредоточиться на агенте и инфраструктуре, а не на верстке очередного chat window.

Что обычно хочется доработать:

русскую локализацию интерфейса;
переключатель между несколькими агентами;
удаление или архивирование чатов;
отображение ошибок backend;
настройки endpoint;
branding для внутреннего портала;
ограничения на размер сообщения.

Важный момент: UI не должен напрямую раскрывать технические секреты. Ключи моделей, endpoints внутренних сервисов и credentials должны оставаться на backend-стороне.

Авторизация: нельзя оставлять AI-сервис открытым

Даже если агент развёрнут «просто для себя», наружу его лучше не выставлять без защиты. AI-сервис может быть дорогим, иметь доступ к внутренним tools или отвечать на базе приватных данных.

Минимальный набор:

HTTPS;
reverse proxy;
Bearer token или SSO;
rate limiting;
ограничение CORS;
логирование запросов;
отдельные права для разных агентов.

Если агент умеет выполнять действия, а не только отвечать текстом, авторизация становится ещё важнее. Пользователь, которому можно задавать вопросы, не обязательно должен иметь право запускать диагностические команды или менять состояние системы.

Деплой на VPS или homelab-сервер

Для homelab-сценария стек может выглядеть так:

Nginx/Caddy
   ├── frontend: agent-chat-ui
   └── backend: FastAPI + LangGraph
          └── LLM endpoint: локальная модель или облачный API

LLM может быть локальной, если хватает GPU/VRAM, или внешней через API. Важно разделить контуры: frontend доступен пользователю, backend закрывает агентную логику, модель и tools не торчат напрямую наружу.

Практические детали деплоя:

запуск backend через systemd, Docker Compose или process manager;
healthcheck endpoint;
ограничение body size в reverse proxy;
таймауты для long-running ответов;
ротация логов;
отдельный .env без попадания в git;
monitoring latency и ошибок.

AI-сервисы часто имеют более долгие ответы, чем обычный CRUD-backend. Поэтому таймауты proxy и клиента нужно настраивать осознанно.

Несколько агентов в одном интерфейсе

Один из полезных сценариев — переключение между агентами. Например:

агент для документации;
агент для анализа логов;
агент для DevOps runbook;
агент для code review;
агент для поиска по базе знаний.

Архитектурно лучше не превращать это в один универсальный prompt. У каждого агента может быть свой graph, набор tools, system prompt, ограничения и уровень доступа. UI при этом остаётся единым.

Такой подход проще масштабировать. Добавление нового агента становится инженерной задачей: описать graph, tools, policy и подключить его в список доступных режимов.

Что стоит предусмотреть заранее

Перед тем как отдавать AI-интерфейс пользователям, полезно пройти короткий чеклист:

что логируется и не попадают ли туда секреты;
как ограничивается стоимость запросов;
можно ли отключить проблемного агента отдельно;
есть ли понятные ошибки при падении модели;
как обновлять prompts и graph без ручной правки на сервере;
где хранятся истории диалогов;
есть ли лимит длины сообщений и контекста;
что произойдёт при одновременных запросах.

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

Итог

LangGraph помогает описать поведение агента как управляемый workflow, FastAPI превращает его в сервис, а ChatGPT-подобный frontend делает результат удобным для людей. Такая архитектура хорошо подходит для homelab, внутренних AI-помощников и прототипов, которые постепенно становятся production-инструментами.

Главная идея проста: LLM-агенту нужен не только хороший prompt, но и нормальная инженерная оболочка — API, авторизация, UI, деплой, логи и ограничения. Без этого даже сильная модель останется экспериментом. С этим — её можно встроить в ежедневную работу команды.