Сервер агента LangGraph з самостійним хостингом та PostgreSQL та Redis

Зберігайте LangGraph SDK, Studio та Agent Server точно такими, як вони є. Перенесіть стабільний стан у Postgres та делегуйте обов’язки з координації Redis, причому для цього не потрібен ключ ліцензії часу виконання.

Написання агента LangGraph зазвичай є найпростішою частиною.

Ви запускаєте граф локально, інструменти виконують свої функції, стан передається від вузла до вузла. Потім хтось ставить запитання, яке перетворює прототип на справжню проблему для експлуатації: як насправді запустити це для роботи з реальним трафіком?

Сервер-агент має відстежувати набагато більше, ніж це може зробити простий API типу запит-відповідь. Для ведення розмов потрібні стабільні потоки, які зберігаються протягом усіх сеансів. Деякі процеси зупиняються у очікуванні схвалення кроку людиною, а потім продовжуються значно пізніше. Клієнти очікують потоку подій, а не єдиної відповіді. Заплановані завдання мають виконуватися рівно один раз, навіть коли кілька працівників намагаються їх виконати одночасно. А якщо один працівник зупиняється під час виконання, інший має без проблем перейняти його роботу, не пошкодивши стан системи.

langgraph dev підходить для локальної розробки, і сама документація LangChain описує його як сервер для розробки, а не для продакшну. Він зберігає стан у пам’яті та локальній папці. Стандартний шлях для переходу у продакшн — це LangSmith Deployments, який доступний як якісь обслуговувана послуга, так і за ліцензією самостійного розміщення.

Langhost пропонує інший підхід. Він запускає незмінений LangGraph Agent Server на базі Postgres та Redis, використовуючи механізм зберігання даних, оприлюднений під ліцензією MIT.

На перший погляд це здається незначною заміною. І справді це незначна зміна, але саме тому варто звернути на неї увагу.

Вибір конструкції, який робить Langhost цікавим

Замість того, щоб перереалізувати Agent Protocol або змусити додатки використовувати інший API, Langhost залишає офіційний пакет Agent Server langgraph-api недоторканим. Змінюється лише шар під ним: пакет langgraph-runtime-pg бере на себе функції зберігання даних.

Ось приблизно як усі елементи взаємодіють між собою:

LangSmith Studio, SDK clients, Chat UI, MCP, A2A
                         |
                   langhost serve
                         |
              stock langgraph-api
                         |
              langgraph-runtime-pg
                    /          \
              Postgres        Redis

Існуючі додатки зберігають свої визначення графу та файл langgraph.json у незмінному вигляді. Клієнти продовжують спілкуватися з langgraph-sdk. Studio продовжує підключатися через ту саму API Agent Server, яку завжди використовував. Langhost навмисно уникає будь-яких складних дій на цьому рівні, що є абсолютно правильним підходом для інфраструктури.

Оскільки офіційний пакет сервера залишається на своєму місці, весь його набір функцій також зберігається після заміни сервера: керування асистентами, відстеження потоків та окремих запусків, доступ до сховища типу key-value, виконання запланованих завдань, надсилання потокового виводу, виклик webhooks та підтримка як MCP, так і A2A. Конкуруючі реалізації сервера мусили б постійно відстежувати кожну зміну протоколу, щоб усе це продовжувало працювати. Langhost повністю уникає цього тягаря обслуговування, залишаючи поведінку протоколу на розсуд верхнього рівня сервера та зосереджуючись лише на зберіганні даних та координації.

Що роблять Postgres та Redis

Postgres зберігає все, що потрібно для продовження роботи після перезапуску: конфігурації асистентів, історію потоків, записи виконань, визначення запланованих завдань, контрольні точки та будь-які дані додатку, які зберігаються в системі. Міграції схем здійснюються за допомогою Alembic. Для продакшн-розгортань рекомендується спочатку застосувати міграції, а потім вимкнути автоматичні міграції під час запуску сервера.

Redis призначений для короткочасних завдань координації. Він сповіщає працівників про нові завдання, які потрапляють у чергу, транслює події потоку до всіх підключених серверів та відстежує стан працівників.

Цей механізм стає важливим, коли ви розгортаєте кілька реплік. Коли працівник хоче взяти на себе виконання завдання, яке ще не розпочалося, він бере під контроль відповідний рядок у Postgres за допомогою параметра SKIP LOCKED, що запобігає тому, щоб інший працівник одночасно взяв це завдання. Сигнали життєздатності від Redis підтверджують, що працівник все ще активний; якщо сигнал не надходить, черга може перерозподілити це завдання комусь іншому. Набір тестів проекту охоплює питання ексклюзивності контролю над завданнями, відновлення після зупинки працівника, одночасну роботу потоків, поведінку під час стрімінгу даних, скасування завдань та оновлення стану під час його виконання.

Саме цей аспект часто ігнорують багато посібників типу „як розгорнути ваш агент“. Запуск сервера ASGI — це проста справа. Справжньою інженерною проблемою є забезпечення правильної роботи механізмів керування чергою та відновлення після збоїв під конкурентним навантаженням.

Переміщення існуючого проекту

Якщо у вас вже є проект Python LangGraph із файлом langgraph.json, налаштування Langhost займає лише кілька кроків.

Встановіть його:

uv add langhost

Потім налаштуйте його на ваші інстанції Postgres та Redis:

DATABASE_URI=postgresql+asyncpg://postgres:postgres@localhost:5432/langgraph?sslmode=disable
REDIS_URI=redis://localhost:6379/0

І запустіть сервер:

uv run langhost serve --reload

Для продакшн-середовища вкажіть конкретний мережевий інтерфейс та встановіть фіксовану кількість працівників:

uv run langhost serve --host 0.0.0.0 --workers 4

За замовчуванням він прослуховує порт 31296. Після запуску виводиться інформація з посиланнями на сам API, його документацію, LangSmith Studio та інтерфейс Agent Chat. Ваш код клієнта залишається без змін та продовжує використовувати стандартний SDK:

import asyncio
from langgraph_sdk import get_client

client = get_client(url="http://127.0.0.1:31296")async def main():
    async for chunk in client.runs.stream(
        None,
        "agent",
        input={
            "messages": [
                {"role": "human", "content": "What is LangGraph?"}
            ]
        },
    ):
        print(chunk.event, chunk.data)asyncio.run(main())

Цей простий шлях міграції, безумовно, є найсильнішою перевагою Langhost. Команда може його випробувати, не торкаючись коду програми чи не змінюючи клієнтські бібліотеки.

Умови ліцензії потребують уважного прочитання

Інструменти CLI langhost та langgraph-runtime-pg постачаються під ліцензією MIT. Однак стандартний пакет langgraph-api все ще підпадає під ліцензію Elastic License 2.0. Фактично Langhost замінює пропріетарний рівень виконання Postgres та Redis. Це не впливає на умови ліцензування самого офіційного серверного пакета.

Цю нюансність часто не помічають, коли люди називають усю стек-технологію „відкритим кодом“. Рівень зберігання даних, який ви запускаєте та можете модифікувати через Langhost, справді постачається під ліцензією MIT. Але серверний компонент, який розташований над ним, залишається доступним під ліцензією Elastic 2.0, і ви все одно зобов’язані дотримуватися цих умов.

Проте для багатьох організацій практичний перехід має велике значення. Вони отримують можливість запускати стабільні завдання LangGraph на самокерованих базах даних без необхідності використання ключа ліцензії для роботи. Це також означає, що стан додатку може залишатися повністю всередині їхнього власного облакового рахунку або внутрішньої мережі. Тим не менш, кожен, хто розглядає цей варіант для корпоративного використання, повинен доручити юридичній чи закупівельній команді уважно прочитати обидві ліцензії безпосередньо, замість того щоб покладатися на рекламний огляд.

Що ви берете на себе, самостійно хостуючи

Langhost скасовує обмеження, пов’язані з ліцензуванням та роботою програми. Однак він не скасовує операційних труднощів.

Ви несете відповідальність за планування пропускної здатності Postgres, створення резервних копій, відпрацювання сценаріїв відновлення, обмеження кількості з’єднань та міграцію схем. Ви також відповідаєте за стабільну роботу Redis та політику звільнення пам’яті. Крім того, вам потрібна можливість контролю – метрики та журнали, які показують, чи відбувається створення резервних копій у черзі завдань, чи зупинилися працівники, або чи беззвучно втрачаються потоки даних. І перед тим, як зробити API доступним за межами надійної мережі, ви повинні належним чином захистити його.

Пам’ятайте, що цей проект все ще знаходиться на ранній стадії. текуща версія на PyPI — це 0.11.1.post1, позначена як бета-версія. Вона фіксує певну версію langgraph-api, що забезпечує стабільну сумісність для цієї конкретної версії, але водночас означає, що проект мусить постійно стежити за змінами у вихідному коді, щоб залишатися актуальним. Набір тестів репозиторію виконує як власні тести, так і тести інтеграції Python SDK проти реального Agent Server, що є запевнюючим фактором — проте це не замінює перевірку ваших власних графів, шаблонів трафіку, сценаріїв збоїв та процедур оновлення.

Для команд, які не хочуть самостійно керувати всім цим, кращим варіантом залишається використання керованої версії LangSmith Deployment. Langhost більше підходить для команд, які вже добре працюють з Postgres та Redis, потребують чіткого контролю над місцем фізичного зберігання своїх даних, або тих, хто просто не може використовувати ліцензовану самостійну версію.

Практичний спосіб оцінки

Замість того, щоб починати з переліку функцій, візьміть тестову копію додатку LangGraph, який ви вже запускаєте, та налаштуйте його на роботу з Langhost.

Використовуйте той самий langgraph.json, той самий клієнт SDK та ту саму робочу схему Studio, на які ви покладаєтесь сьогодні. Створіть стабільний поток. Транслюйте тривалу обробку. Перервіть її під час виконання та продовжіть пізніше. Запустіть більше одного робочого процесу. Завершіть роботу одного з працівників під час виконання завдання та перевірте, чи обробка все одно завершиться правильно. Потім зробіть резервну копію бази даних Postgres, відновіть її у окремому середовищі та переконайтеся, що історія потоків залишилась недоторканою.

Якщо ваша конфігурація пройде всі ці перевірки, ви дасте відповідь на справді важливе питання — чи може Langhost без проблем інтегруватися у вашу інфраструктуру, не ставши джерелом проблем.

Вихідний код, посібник з налаштування та система відстеження проблем доступні за адресою langhost/langhost на GitHub.

Пов’язана література

• Створення безпечних AI-агентів за допомогою LangChain Guardrails та Middleware — Дізнайтеся, як функціонують детерміновані та модельні механізми контролю в LangChain для виявлення витоків конфіденційної інформації, застосування бізнес-правил та додавання кроків людського схвалення до AI-агентів.
• Що насправді автоматизує LangChain після створення циклу агента — Пояснюється, як LangChain, LangGraph та схожі SDK-и обгортають той самий основний цикл агента, створений з нуля, та коли використання фреймворку є корисним, а коли — шкідливим.