commit 35ea0a73c72cc5e4326fe99263daf95c45d14db0 Author: Азамат Нураев Date: Thu Mar 19 20:49:23 2026 +0000 Add Home diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..4a5d950 --- /dev/null +++ b/Home.md @@ -0,0 +1,260 @@ +# Архитектура платформы sandbox-агентов + +Статус: черновик v1 + +## 1. Назначение + +Платформа должна запускать AI-агентов в изолированной среде и подключать их к внешним интеграциям (Telegram, Discord, Slack и др.). + +Команда отвечает не за сами интеграции, а за sandbox-платформу: жизненный цикл сессий, рабочее окружение агента, хранение данных и подключение тулов. + +## 2. Границы ответственности + +### В зоне команды + +- сервис `Master`, управляющий сессиями и sandbox-окружением; +- запуск и остановка контейнеров с агентами; +- выделение и монтирование workspace; +- доступ к объектному хранилищу и служебным метаданным; +- встроенные и платформенные инструменты агента; +- политика хранения файлов и кэшей. + +### Вне зоны команды + +- каналы интеграции с мессенджерами; +- UI/UX конкретных платформ; +- бизнес-логика внешних тулов, которые разрабатывают другие команды. + +## 3. Основные сущности + +### Интеграции + +Внешние каналы: Telegram, Discord, Slack и т.д. + +Они принимают сообщения пользователя, передают событие в `Master`, а затем работают с конкретным поднятым агентом по стриму. + +### Master + +`Master` - оркестратор платформы. Его обязанности: + +1. управлять жизненным циклом sandbox; +2. управлять сессиями и контекстом; +3. запускать контейнеры с агентами; +4. выбирать ноду и готовить окружение запуска; +5. подготавливать mount'ы и зависимости; +6. возвращать интеграции адрес или endpoint конкретного агента. + +`Master` логически один сервис, но физически может быть развернут в нескольких экземплярах. + +### AI-Agent + +AI-агент работает внутри изолированного контейнера. Он: + +- принимает стрим событий от интеграции; +- работает с файлами текущего чата; +- использует встроенные, платформенные и пользовательские тулы; +- создает артефакты; +- выгружает артефакты в S3-совместимое хранилище. + +### Workspace + +Каждому пользователю выделяется workspace с лимитом до 10 ГБ. + +Внутри workspace хранятся чаты. В ранних обсуждениях они назывались `projects`, но по факту текущая модель - это чат плюс связанные с ним файлы и метаданные. + +Пример содержимого чата: + +- пользовательские файлы (`pdf`, `png`, `docx`, `mp4` и т.д.); +- служебные файлы; +- локальная история (`history.db`); +- дополнительные метаданные (`memory.md`, `summary.md`, `goals.md` и т.п. - опционально). + +### S3-совместимое хранилище + +Используется как файловое хранилище: + +- входные файлы от пользователя; +- артефакты, созданные агентом; +- содержимое workspace; +- кэш зависимостей и общих ресурсов при необходимости. + +Это не обязательно AWS; важен именно S3-совместимый протокол. + +### DB + +Отдельная БД нужна как минимум для служебных метаданных платформы: + +- сессии; +- состояние контейнеров; +- маршрутизация; +- служебная информация `Master`. + +История конкретного чата на текущем этапе планируется хранить рядом с данными чата внутри workspace (например, в `history.db`), а не в общей централизованной БД. + +## 4. Поток обработки запроса + +1. Пользователь пишет в интеграцию и/или прикладывает файлы. +2. Интеграция сохраняет входные файлы в S3-совместимое хранилище. +3. Интеграция обращается к `Master` с запросом создать или восстановить сессию. +4. `Master`: + - выбирает машину; + - поднимает контейнер агента; + - монтирует текущий чат или workspace; + - монтирует кэш зависимостей; + - монтирует общие `lambda-tools`; + - при необходимости подтягивает данные с S3. +5. `Master` возвращает интеграции endpoint или адрес конкретного агента. +6. Дальнейшее общение идет напрямую между интеграцией и агентом по стриму, без проксирования через `Master`. +7. Агент выполняет задачу, создает артефакты и при необходимости выгружает их в S3. +8. Интеграция отдает результат пользователю. +9. По TTL бездействия контейнер завершается, а состояние workspace сохраняется для последующего восстановления. + +## 5. Устройство sandbox на машине + +На одной машине располагаются: + +- базовый слой `Linux`; +- общий environment; +- общий набор `lambda-tools`; +- mount-слой; +- несколько одновременно работающих контейнеров с агентами. + +Важно: `lambda-tools` общие для всей машины и не копируются внутрь каждого агента как отдельный набор файлов. Контейнеры получают к ним доступ через mount. + +## 6. Модель хранения данных + +### 6.1 Workspace и чат + +- лимит: до 10 ГБ на пользователя; +- пространство не резервируется физически заранее, лимит контролируется по фактическому объему данных; +- внутри workspace лежат чаты и их файлы; +- один и тот же чат может быть повторно поднят на той же машине без повторной загрузки. + +### 6.2 Кэш на ноде + +Если нужный чат, зависимости или инструменты уже есть на ноде, они используются повторно. + +Если их нет, `Master` подтягивает их из S3 и примонтирует в окружение агента. + +### 6.3 Репликация между машинами + +Если нужная машина занята или недоступна: + +- состояние workspace выгружается в S3; +- на новой машине workspace скачивается из S3; +- агент поднимается уже на новой ноде. + +## 7. Типы инструментов + +### 7.1 Встроенные инструменты агента + +Инструменты, зашитые в код самого агента. Примеры: + +- `web-search`; +- `fetch-url`; +- `bash`; +- скриптинг (`python` или другой встроенный runtime). + +Это базовые возможности агента. + +### 7.2 Lambda-tools + +Общие платформенные тулы, разрабатываемые другими командами и доступные всем агентам на машине. + +Требования к таким тулам: + +- человекочитаемый `--help`; +- машиночитаемый `--json`; +- agent-friendly режим (`--agent` или аналог); +- отдельная self-description команда вроде `man-agent `; +- единый способ вызова из агента. + +Реализация может быть: + +- локальным скриптом или бинарем; +- CLI-оберткой над удаленным HTTP API. + +Для агента это должен быть один и тот же контракт. + +Пример: `markitdown`. + +### 7.3 User-tools + +Пользовательские инструменты, относящиеся к конкретному workspace или чату. + +Ключевая идея обсуждения: такие тулы не должны генерироваться самим runtime-агентом внутри sandbox на лету. Предпочтительнее, чтобы они приходили извне через отдельный pipeline или сервис генерации и загружались как готовые файлы. + +Свойства `user-tools`: + +- область видимости: только конкретный пользователь или чат; +- доступ: `+x only` или execution-only; +- агент не должен свободно читать их исходники и секреты; +- рядом могут лежать env или секреты, недоступные для чтения агентом. + +Пример запроса на user-tool: + +> Создай простой task-tracker, который хранит задачи в `sqlite.db` и поддерживает команды `add` и `close`. + +## 8. Политика изоляции и безопасности + +Базовые принципы: + +- агент работает в sandbox-контейнере; +- доступ к файловой системе ограничен разрешенными mount'ами; +- чувствительные секреты не должны быть доступны агенту в открытом виде; +- код и env пользовательских тулов должны быть как минимум недоступны для изменения, а желательно и для чтения; +- машину и агента нужно считать потенциально небезопасными по умолчанию, особенно с учетом prompt injection. + +Актуальная нерешенная тема: защита от эксфильтрации пользовательских файлов и секретов через prompt injection и вредоносные внешние данные. + +## 9. Жизненный цикл файлов + +Черновые договоренности: + +- файлы внутри чата живут ограниченное время; на схеме зафиксирован ориентир `3 дня`; +- generated artifacts после длительного отсутствия обращений могут удаляться; +- полный workspace пользователя может удаляться после долгой неактивности аккаунта, значение TTL пока не зафиксировано; +- при повторном запросе отсутствующего файла система может попросить пользователя прислать его заново. + +Это пока продуктовая политика по умолчанию, не финальная спецификация. + +## 10. Жизненный цикл контейнера + +- контейнер создается при первом сообщении в сессии; +- при отсутствии активности контейнер останавливается по TTL; +- после остановки состояние нужно сохранить так, чтобы чат можно было восстановить; +- повторный запуск может происходить как на той же ноде, так и на другой через восстановление из S3. + +## 11. Что считается текущим решением + +На текущем этапе приняты такие решения: + +- интеграции и sandbox разделены; +- `Master` отвечает за orchestration; +- агент общается с интеграцией напрямую по стриму после старта; +- workspace ограничивается 10 ГБ на пользователя; +- история чата живет рядом с чатом, а не в общей истории платформы; +- общие `lambda-tools` доступны всем агентам на машине; +- пользовательские тулы изолированы сильнее, чем обычные файлы; +- S3 используется как основное файловое хранилище и транспорт между нодами. + +## 12. Открытые вопросы + +1. Финальная модель хранения истории: `SQLite` или файлы в чате vs специализированное решение. +2. Где проходит граница между локальными и удаленными `lambda-tools`. +3. Финальная политика хранения и удаления файлов. +4. Механизм защиты от prompt injection и утечки данных. +5. Способ тестирования стримового протокола без реальных интеграций. +6. Детали multi-node orchestration и autoscaling. +7. Нужно ли вводить отдельную сущность `project` поверх чатов в следующей версии. + +## 13. План по репозиториям + +На момент обсуждения предполагается минимум два репозитория: + +- `master` - orchestration, сессии, запуск контейнеров, mounts, routing; +- `agent` - runtime агента внутри sandbox и контракт вызова тулов. + +## 14. Краткая формула архитектуры + +Интеграция сообщает `Master` о новом запросе -> `Master` поднимает sandbox-агента и монтирует нужные данные -> интеграция общается с агентом напрямую по стриму -> агент работает в изолированной среде, использует тулы, складывает артефакты в S3 -> состояние workspace сохраняется и может быть восстановлено на любой ноде.