agentarium

Платформа для сборки распределённых мультиагентных систем. Агенты — независимые сервисы в контейнерах, каждый обрабатывает свой тип сообщений и не знает о существовании остальных. Систему описывает один YAML-файл: перечень агентов и маршруты между ними. Добавить агента нового типа можно без правки ядра платформы.

Понять суть — минута чтения. Убедиться, что всё работает, — три команды, без ключей и без Docker (ниже).

---

Что это

Ядро платформы (core/) — это шина сообщений, протокол, SDK агента и маршрутизация из конфигурации. Ядро не содержит предметной логики и не привязано к LLM-фреймворку.

Поверх ядра собран рабочий пример (agents/, configs/): система обработки заявок администратора баз данных. Заявка на естественном языке («проверь доступы ivanov на проде») превращается в план работ с реальными read-only проверками против целевой БД.

Проверка без ключа и без Docker

Нужны uv и make (Python 3.12 uv поставит сам):

uv sync --group dev      # поставить окружение
make lint                # ruff по коду — без замечаний
make test                # юнит-тесты — без внешних сервисов

Ожидаемый результат make test:

111 passed, 4 skipped, 39 deselected

111 юнит-тестов проходят за секунды из чистого клона. 4 пропущенных — e2e-тесты на живом GigaChat (make test-e2e); 39 отфильтрованных — интеграционные, им нужны сервис-контейнеры (make test-integration). Логика ядра — протокол, доставка, fail-fast, фиксированный список (allowlist) проверок к БД — покрыта юнит-тестами и читается без запуска системы.

Запуск живьём

Понадобятся Docker, uv, make и ключ GigaChat. Бесплатный персональный ключ выдаётся на developers.sber.ru/gigachat (вход по Сбер ID, пара минут). Команда запуска зависит от того, какой у вас ключ:

Какой у вас ключ	Эмбеддинги в тарифе	Ваша команда
Корпоративный	есть	make demo — и чат, и RAG-векторы через API GigaChat
Персональный бесплатный	нет: чат бесплатный, эмбеддинги — отдельный платный пакет	make demo-local — чат через API, RAG-векторы считает локальная bge-m3
Пока никакого	—	раздел «Проверка без ключа» выше; ключ — по ссылке

cp env.example .env      # вписать ключ GigaChat в GIGACHAT_CREDENTIALS
make demo                # или make demo-local — какая ваша, см. таблицу
make down                # остановить и снести стенд, когда закончите

Для корпоративного ключа в .env поставьте GIGACHAT_SCOPE=GIGACHAT_API_CORP (по умолчанию там персональный GIGACHAT_API_PERS).

Что из этого проверено живьём. Путь make demo-local прогнан end-to-end: три заявки прошли конвейер целиком, с реальными проверками против целевой БД — пример вывода ниже именно оттуда. Путь make demo (эмбеддинги по API) живьём не прогонялся: у бесплатного персонального ключа автора доступа к эмбеддингам нет. Вызов эмбеддингов использует тот же клиент и ту же авторизацию, что и проверенный чат, и покрыт юнит-тестом; если с вашим ключом он всё же не заработает — make demo-local даёт тот же результат без API-эмбеддингов.

Что делает команда: поднимает стенд одной командой — шина, хранилища, трейсинг, целевая БД, три агента и шлюз (9 контейнеров; demo-local добавляет десятый — Ollama), индексирует регламенты в векторное хранилище и прогоняет три заявки.

Сколько ждать: make demo — обычно 1–2 минуты, почти всё уходит на первую сборку образов. make demo-local при первом запуске дольше: докачивается модель bge-m3 (~1.2 ГБ, 5–15 минут в зависимости от сети), Docker потребует ≥4 ГБ памяти.

Обе команды автоматически передают контейнерам сертификат НУЦ Минцифры из репозитория. Если сеть подменяет TLS корпоративным proxy, положи его публичный CA в infra/certs/ и укажи контейнерный путь в GIGACHAT_CA_BUNDLE_FILE.

Пароли в репозитории (agentarium/agentarium, роли демо-БД) — публичные значения локального стенда, не секреты. Настоящий ключ GigaChat лежит только в .env, которого в git нет.

Сервисы, чей дефолтный порт разработчик часто уже занял своим, сдвинуты наружу: Postgres — на 5433, Ollama (на офлайн-пути) — на 11534. Остальные на штатных портах (RabbitMQ 5672, Qdrant 6333, Jaeger 16686).

Три варианта демо

Каждое демо — одна команда; система пересобирается под YAML-конфигурацию сама. У первых двух — та же развилка эмбеддингов, что в таблице ключей: команда без суффикса — эмбеддинги по API, с -local — локальная bge-m3.

Демо	Что показывает	Команды	Конфигурация
Базовое (в тексте — конфигурация A)	конвейер parser → knowledge → executor: разбор заявки, RAG по регламентам, реальные проверки БД	make demo / make demo-local	configs/dba-base[-local].yaml
Расширенное (конфигурация B)	плюс агент-аудитор: план сверяется с историей инцидентов. Новый тип агента добавлен без правки ядра — ядро и остальные агенты не тронуты	make demo-extended / make demo-extended-local	configs/dba-extended[-local].yaml
Техническое (echo-pair)	цепочка echo → reverse без LLM и без ключа: шина, доставка и трейсинг работают с любой логикой агента	make demo-echo	configs/echo-pair.yaml

Пример вывода (конфигурация A):

Заявка: Проверь, какие доступы у пользователя ivanov в базе billing на проде
  путь:    parser → knowledge → executor   (интент: check_access)
  проверка user_roles({'user': 'ivanov'}) → [{'role': 'billing_rw'}]   ← из живой БД
  проверка user_privileges({'user': 'ivanov', 'database': 'billing'}) → []
  источники: [access-provisioning.md, role-model.md]
  ВЕРДИКТ:  ivanov состоит в billing_rw, прямых привилегий на базу нет. План и факты согласуются.

Заявка: Что за ерунда:))  → отказ: не является заявкой DBA

Посмотреть систему изнутри:

Окно	Адрес	Что видно
Swagger шлюза	http://localhost:8000/docs	подать свою заявку из браузера
Jaeger	http://localhost:16686	путь заявки через агентов как водопад трейсов
RabbitMQ UI	http://localhost:15672	очереди и сообщения в полёте

Как устроено

Клиент ──POST /requests──▶ gateway ──▶ [RabbitMQ] ──▶ parser ──▶ knowledge ──▶ executor
                             │                         (LLM)      (RAG)          │
                             ◀────────────── plan.ready ◀────────────────────────┘
      хранилища: PostgreSQL (состояние) · Qdrant (знания) · трейсы: Jaeger

На схеме — имена экземпляров агентов; knowledge — экземпляр типа rag, в этом примере он ищет по коллекции регламентов (тип и экземпляр соотносятся как класс и объект — подробнее в docs/ARCHITECTURE.md).

Четыре ключевых решения:

• Оркестрация без центрального оркестратора. Отдельного процесса-маршрутизатора нет. Маршруты из конфигурации становятся биндингами RabbitMQ, доставку выполняет сам брокер. Агент публикует результат и не знает, кто следующий, — это решает таблица маршрутов.
• LLM не пишет SQL. Агент-исполнитель выбирает проверки из allowlist типизированных read-only функций (user_roles, user_privileges, pg_version и т.д.). К целевой БД он ходит под отдельной ролью с pg_monitor, statement_timeout и READ ONLY-транзакциями. Свободного SQL от модели в системе нет по построению — prompt-инъекция в тексте заявки упирается в это ограничение.
• У каждого агента своя модель. Модель — поле в конфигурации агента. В примере parser и knowledge используют лёгкую GigaChat-2, а executor — GigaChat-3-Ultra (планирование и выбор проверок тяжелее классификации). Смена модели или переключение между уже реализованными провайдерами (GigaChat, локальная bge-m3 для эмбеддингов) — это правка YAML. Новый провайдер — небольшой адаптер внутри типа агента; ядро не меняется в любом случае.
• Отказоустойчивость на механике брокера. Агента можно убить посреди обработки: сообщение доживает в quorum-очереди, рестарт доделывает работу. «Ядовитое» сообщение после трёх доставок уходит в dead-letter-очередь, и заявка честно завершается статусом failed. Механизм закрыт интеграционными тестами на живом брокере (tests/integration/test_sdk.py).

Подробнее, в формате «решение → почему → что было бы без него», — в docs/ARCHITECTURE.md.

Структура репозитория

Папка	Что там
core/	ядро платформы: протокол сообщений (Envelope), шина, SDK агента, шлюз
agents/	типы агентов примера (parser, rag, executor, auditor) и каталог типов
configs/	конфигурации систем в YAML (dba-base, dba-extended и др.)
spec/	спецификации 00–70: архитектура и контракты
knowledge/	базы знаний для RAG (regulations, incidents)
tests/	юнит-, интеграционные и e2e-тесты
demo/	запуск демо (run_demo.py) и сценарий отказа (chaos.sh)
tools/	индексатор баз знаний в Qdrant
infra/	init-скрипты целевой БД
docs/	архитектура и гайд по сборке своих систем

Что работает и ограничения

• Конфигурации A и B работают end-to-end на живом GigaChat: заявка проходит весь конвейер, executor выполняет реальные read-only проверки против целевой БД (пример вывода выше).
• Отказоустойчивость покрыта интеграционными тестами на живом брокере (tests/integration/test_sdk.py: сообщение переживает смерть консюмера, ядовитое сообщение уходит в dlq, зависшая обработка обрывается по таймауту — вотчдог).
• Эмбеддинги: живьём проверен локальный путь (make demo-local); путь по API GigaChat покрыт юнит-тестом, живого прогона не было — что и почему, в разделе «Запуск живьём».
• Конфигурация B прогнана живьём (make demo-extended-local): заявка проходит четырёх агентов, и аудитор реально ловит грабли — например, план проверки доступов без срока действия он сверил с историей инцидентов и указал на повтор privilege-creep-инцидента.

Документы

Что искать	Где
Как устроена платформа: решения и обоснования	docs/ARCHITECTURE.md
Как собрать свою систему на платформе	docs/GUIDE.md
Спецификации 00–70 (порядок чтения)	spec/README.md
Критерии приёмки — проверить руками	spec/60-acceptance.md

---

MIT © 2026 Lukyan Stulkov · см. LICENSE