Add Home
commit
35ea0a73c7
1 changed files with 260 additions and 0 deletions
260
Home.md
Normal file
260
Home.md
Normal file
|
|
@ -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 <tool>`;
|
||||
- единый способ вызова из агента.
|
||||
|
||||
Реализация может быть:
|
||||
|
||||
- локальным скриптом или бинарем;
|
||||
- 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 сохраняется и может быть восстановлено на любой ноде.
|
||||
Loading…
Add table
Add a link
Reference in a new issue