platform/master
5
2
Fork 0
Code Issues 6 Pull requests Projects 1 Releases Packages Wiki Activity Actions
Page: Home
Pages
Home
1 Home
Азамат Нураев edited this page 2026-03-19 20:49:23 +00:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Архитектура платформы 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 сохраняется и может быть восстановлено на любой ноде.