AAF: Архитектура автономного ИИ-агента с GraphRAG, EventBus и Docker-песочницей

В нашем сообществе уже не первый день живёт агент @vega_exactly_not_ai.

Его создатель th0r3nt открыл исходный код на GitHub - чтобы мы вместе могли решить фундаментальные проблемы. На сегодня это самое стабильное решение автономного агента с личным Telegram-аккаунтом.

Создатель попросил рассказать об архитектуре и поставить ряд вопросов перед сообществом. Думаю, вместе мы способны разобраться.

Большинство современных Open-Source фреймворков для создания ИИ-агентов (от AutoGPT до недавнего OpenClaw) страдают от ряда детских болезней. Во-первых, это амнезия: агент теряет контекст спустя десяток шагов, так как векторные базы данных превращают память в кашу из семантически похожих, но логически не связанных кусков текста. Во-вторых, это зацикливание в бесконечных ReAct-петлях. В-третьих - ужасная безопасность при выполнении сгенерированного кода прямо на хостовой машине.

В этой статье я хочу разобрать архитектуру Autonomous Agent Framework (AAF) - моего pet-проекта, который перерос в полноценную OS-level сущность на Python.

Главная идея AAF: агент не должен быть просто скриптом, ожидающим промпта. Это должен быть долгоживущий асинхронный процесс с гибридной памятью, шиной событий и собственной изолированной средой для запуска субагентов.

• Архитектура и слои (Layers)

Проект построен на asyncio и использует строгий src-layout. Логика разбита на 5 независимых слоев, которые общаются друг с другом через асинхронную шину событий (EventBus).

Layer 00 (Utils): Логгер, подсистема мониторинга (WatchDog), инструменты для работы с локальной ФС.

Layer 01 (DataState): Тройная гибридная память (SQL, Vector, GraphRAG) и глобальное состояние.

Layer 02 (Sensors): «Органы чувств» агента. Telethon (для жизни в Telegram в виде Userbot), микрофон (Vosk), динамики (Edge-TTS) и терминал.

Layer 03 (Brain): Оркестратор. Очередь приоритетов и три независимых ReAct-цикла.

Layer 04 (Swarm): Менеджер субагентов и управление Docker-песочницей.

• Асинхронный «Мозг» и Event-Driven подход

Классические боты работают по паттерну listen() -> answer(). В AAF мозг нейросети полностью отвязан от сенсоров.

Все входящие раздражители (сообщение в Telegram, изменение погоды, падение системного модуля, алерт от фонового скрипта) публикуются в EventBus с определенным уровнем приоритета (CRITICAL, HIGH, MEDIUM, LOW).

Мозг (BrainEngine) имеет внутри себя asyncio.PriorityQueue. Агент сам решает, на что реагировать прямо сейчас, а что отложить. Более того, у агента есть три независимых цикла:

Event-Driven ReAct: Реакция на прямые события (например, сообщение от пользователя).

Proactivity ReAct: Фоновый цикл. Агент просыпается по таймеру, анализирует накопленные LOW-события (например, кто-то поставил реакцию на его сообщение или в чате накопилось 300 сообщений) и решает, нужно ли что-то предпринять.

Thoughts ReAct (Интроспекция): Цикл рефлексии. Агент анализирует свои последние действия, сжимает контекст, удаляет устаревшие задачи и обновляет графовую базу данных.

• Тройная гибридная память (Reverse G-RAG)

Это ядро системы. Хранить всё в ChromaDB или в Markdown-файлах — путь к галлюцинациям. AAF использует каскадную систему памяти:

PostgreSQL (SQLAlchemy + JSONB): Отвечает за «жесткую» память. Здесь хранится Mental State (важные сущности и их статусы), Long-Term Tasks (долгосрочные задачи) и Personality Traits (приобретенные правила поведения).

KuzuDB (GraphRAG): Отвечает за интуицию и нейронные связи. Отдельно хочу выделить мною написанный механизм GraphRAG - он позволяет изучать неочевидные связи и реализует подобие интуиции у ИИ-агента.

ChromaDB (Vector): Отвечает за семантику и "поток рефлексии" (agent_thoughts). В качестве модели эмбеддингов локально крутится BAAI/bge-m3.

Как работает сборка контекста:
Когда происходит событие, система не просто делает векторный поиск по запросу. Реализован алгоритм, который я называю Reverse Graph-RAG:

Извлекается векторный смысл текущего события.

Текст парсится на наличие «якорей» - имен узлов, которые есть в графовой БД.

Система идет в KuzuDB и достает связи на глубину 1 (прямые контакты) и глубину 2 (косвенные ассоциации), игнорируя "суперузлы" - сам агент и главный пользователь (чтобы не перегрузить контекст).

Найденные соседние узлы из графа используются для вторичного поиска по векторной базе.

В итоге LLM получает не только похожие куски текста, а полную, структурированную картину: прямые связи объектов, косвенные ассоциации и релевантные мысли из прошлого.

• Agent Swarm System и Docker-in-Docker (DinD)

Давать LLM-агенту доступ к выполнению bash-скриптов на хостовой машине - это катастрофа с точки зрения безопасности.

В AAF главный агент выступает только как оркестратор. Если задача требует написания и выполнения кода, парсинга сайтов или анализа 500 страниц логов, мозг динамически спавнит специализированного субагента (Worker или Daemon) на базе более дешевой LLM модели.

Как реализована песочница:
Пока для запуска песочницы используется проброс docker.sock. Я понимаю, что это риск для хостовой машины (агент может получить root через монтирование томов), и в будущем планирую перевести это на gVisor, Firecracker или изолированный удаленный Docker Daemon.

Если скрипт завис или ушел в бесконечный цикл - контейнер принудительно убивается (SIGKILL), а главному агенту возвращается Traceback. Хостовая машина при этом остается в полной безопасности.

Также реализован паттерн Agentic Mesh: субагенты могут передавать задачи друг другу по эстафете, сохраняя промежуточные данные в локальные файлы песочницы. Это позволяет использовать для рутины дешевые и быстрые модели, экономя токены дорогой основной модели.

• Протокол Self-Healing и WatchDog

Все критически важные функции (работа с БД, Telegram-клиент, модули распознавания речи) обернуты в кастомный декоратор watchdog_decorator.

Он работает как Heartbeat-монитор. Если, например, отваливается соединение с базой данных, декоратор перехватывает исключение и публикует в шину SYSTEM_MODULE_ERROR с полным Traceback'ом.

Шина мгновенно будит агента с наивысшим приоритетом (CRITICAL). Агент читает ошибку, использует инструмент read_local_system_file, чтобы прочитать свой же исходный код (.py файлы), анализирует причину падения и может предложить фикс или попытаться перезапустить модуль.

• Multi-Agent Architecture & CLI Manager

AAF - это платформа. Встроенный интерактивный терминал (aaf.py) позволяет в 3 клика развернуть на одном сервере целую команду независимых агентов. Никакого ада зависимостей и ручной правки конфигов: скрипт сам генерирует Docker Compose, изолирует песочницы и управляет ключами. У каждого запущенного агента своя память, свои ключи, свой характер и возможность спавнить уже своих субагентов.

Итог

AAF - это попытка уйти от парадигмы «умных чат-ботов» в сторону полноценных цифровых сущностей, которые живут на сервере, имеют свою картину мира, умеют рефлексировать и безопасно взаимодействовать с операционной системой.

GitHub: https://github.com/th0r3nt/AAF-Autonomous-Agent-Framework-
Чатик где можно посмотреть на жизнь Веги: https://t.me/openclaw_lab_community