Practice_reports/platform/Nuraev_Azamat_report.md

Нураев Азамат Ринатович

Индивидуальное задание

Разработка master-service - сервиса управления для работы с контейнерами-песочницами ИИ-агентов, организации жизненного цикла пользовательских сессий, подключения рабочих обсластей, выдачи сетевого адреса среды выполнения и обеспечения obsevability жизненного цикла песочниц.

План выполнения

№ п/п	Место проведения	Тема	Период выполнения
1	ООО “Группа компаний “Иннотех”	Инструктаж. Изучение постановки задачи и требований к платформе ИИ-агентов.	09.02.2026-09.02.2026
2	ООО “Группа компаний “Иннотех”	Изучение OpenTelemetry. Проектирование всей агентской системы: взаимодействие master-service, agent-service и интеграционных поверхностей, а также контрактов работы с инструментами.	10.02.2026-06.03.2026
3	ООО “Группа компаний “Иннотех”	Проектирование master-service, границ ответственности и API первой версии.	07.03.2026-27.03.2026
4	ООО “Группа компаний “Иннотех”	Реализация конфигурации, внедрения зависимостей и базовой HTTP-инфраструктуры.	28.03.2026-16.04.2026
5	ООО “Группа компаний “Иннотех”	Разработка оркестрации контейнеров-песочниц, TTL, очистки и сверки состояния при запуске.	17.04.2026-15.05.2026
6	ООО “Группа компаний “Иннотех”	Реализация obsevability, управляющего HTTP API, тестирование и ревью кода.	16.05.2026-06.06.2026
7	ООО “Группа компаний “Иннотех”	Оформление отчёта. Подведение итогов практики.	07.06.2026-07.06.2026

Отзыв руководителя

Обучающийся группы М8О-104БВ-25 Нураев Азамат Ринатович проходил ознакомительную практику в ООО “Группа компаний “Иннотех”. За время практики студент работал над продуктовой частью платформы ИИ-агентов, предназначенной для запуска пользовательских агентских сред, управления их жизненным циклом и подключения внешних пользовательских интерфейсов.

В соответствии с индивидуальным заданием была разработана первая версия master-service как управляющего компонента агентской системы. Сервис решает задачу подготовки изолированной среды для ИИ-агента, переиспользования активных пользовательских сессий, подключения рабочих данных, выдачи параметров доступа к агенту и последующей очистки неактивных сред. Также студент участвовал в проектировании взаимодействия master-service с agent-service и интеграционными поверхностями: matrix бот и макс бот.

За время прохождения практики практикант проявил высокий уровень самостоятельности, лидерские качества и умение организовывать командную работу. Он руководил командой из двух человек: отвечал за оркестрацию, бизнес-логику, архитектурные решения и делегирование задач, а участники команды занимались реализацией репозиториев. Практикант показал способность связывать технические решения с продуктовыми целями, аргументированно выбирать приоритеты и доводить задачу до рабочего результата.

Рекомендуемая оценка «Отлично». Материалы, изложенные в отчёте обучающегося, соответствуют индивидуальному заданию.

Отчёт обучающегося по практике

Современные платформы ИИ-агентов требуют не только реализации самих интеллектуальных агентов, но и надёжной инфраструктуры для их запуска, изоляции, масштабирования и контроля жизненного цикла. ИИ-агент часто выполняется в отдельной среде-песочнице, где ему предоставляются рабочие файлы, зависимости и инструменты. Поэтому важной частью такой платформы становится управляющий backend-сервис, который отвечает за создание песочницы, подключение нужных ресурсов, проверку состояния и безопасное завершение сессий среды выполнения.

Основной целью практики была разработка master-service - сервиса-оркестратора управления платформы ИИ-агентов. В отличие от прокси плоскости данных, такой сервис не должен постоянно пропускать через себя рабочий трафик агента. Его задача состоит в управлении жизненным циклом контейнеров-песочниц, хранении служебного состояния, подготовке рабочего пространства и выдаче параметров подключения к уже запущенному агенту. Такой подход позволяет отделить управляющую логику от непосредственного взаимодействия пользователя с ИИ-агентом и делает систему более гибкой.

На начальном этапе были изучены требования к master-service. В документации были выделены ключевые сущности: пользователь, рабочее пространство, чат, сессия песочницы, временный доступ, пользовательские файлы и артефакты. Также были определены границы ответственности сервиса. В область ответственности master-service вошли оркестрация песочниц, управление сессиями среды выполнения, хранение служебных метаданных, выдача и отзыв доступа, процессы очистки и наблюдаемость. Вне области ответственности первой версии были оставлены интеграции с Telegram, Discord, Slack, бизнес-логика ИИ-агента, защита от prompt injection на уровне большой языковой модели, полноценные CRUD API для рабочих пространств и чатов, центральная база данных, S3-хранилище артефактов и политика квот.

Отдельным направлением стало проектирование всей агентской системы, в которую master-service входит как управляющий компонент. В рамках этой работы рассматривалось взаимодействие master-service с agent-service, который исполняет логику ИИ-агента внутри песочницы, а также взаимодействие с интеграционными поверхностями: matrix бот и макс бот. Для таких интеграций важно, чтобы внешний клиент не зависел от деталей запуска контейнера, а получал понятный контракт создания сессии, подключения к агенту и передачи пользовательских файлов. Также прорабатывался контракт взаимодействия с инструментами, чтобы агент мог запускать разрешённые инструменты предсказуемым способом, а платформа сохраняла контроль над доступами, рабочими директориями и жизненным циклом выполнения.

Важной частью работы стало проектирование архитектуры. Проект был построен на принципах чистой архитектуры и SOLID. Внутренний слой domain/ содержит базовые сущности и доменные ошибки. Слой usecase/ описывает прикладные сценарии и интерфейсы, через которые внутренняя логика взаимодействует с внешними ресурсами. Слой repository/ содержит реализации хранилищ, а внешний слой adapter/ отвечает за HTTP, конфигурацию, среду выполнения Docker, внедрение зависимостей и наблюдаемость. Такое разделение позволяет не связывать бизнес-логику с конкретным web-фреймворком, Docker SDK или OpenTelemetry SDK.

Для явного связывания зависимостей была реализована точка сборки в adapter/di/container.py. Репозитории, классы сценариев, конфигурация и адаптеры наблюдаемости создаются один раз при старте приложения и затем переиспользуются во время обработки запросов. Такой подход делает жизненный цикл объектов понятным и тестируемым, а также предотвращает создание тяжёлых зависимостей на каждый HTTP-запрос.

Конфигурация сервиса была вынесена в типизированные dataclass-структуры. Базовые несекретные значения хранятся в YAML-файлах, а чувствительные параметры, такие как APP_API_TOKEN и APP_SIGNING_KEY, передаются через переменные окружения. Итоговая конфигурация собирается в единое дерево AppConfig, которое затем передаётся во внешний слой приложения. Внутренние слои при этом не читают переменные окружения и не зависят от YAML-парсера, что соответствует принципу инверсии зависимостей.

Следующим этапом стала реализация HTTP-интерфейса. В качестве первого web-адаптера использовался FastAPI, однако код FastAPI был изолирован в директории adapter/http/fastapi/. API первой версии размещён под префиксом /api/v1, что позволяет в дальнейшем добавлять новые версии без изменения контрактов сценариев. В текущей первой версии реализованы маршрут проверки состояния, маршрут POST /api/v1/create для создания или переиспользования песочницы и маршрут DELETE /api/v1/sandboxes/{chat_id} для удаления активной песочницы.

Основная прикладная логика была связана с жизненным циклом песочницы. Для этого в доменном слое была описана сущность SandboxSession, содержащая идентификатор сессии, chat_id, Docker container_id, статус, время создания, время истечения TTL, agent_id, путь к хостовому тому и сетевой адрес агента в Docker-сети. В слое сценариев были реализованы сценарии создания, удаления и очистки песочницы. Важным правилом стало ограничение «одна активная песочница на один чат». Если активная песочница ещё не истекла и параметры agent_id и volume_host_path совпадают, повторный запрос на создание переиспользует существующую сессию. Если параметры отличаются, возвращается конфликт, и новый контейнер не создаётся.

Для запуска среды выполнения был реализован Docker-адаптер. Он отвечает за создание контейнера с ИИ-агентом, подключение томов, установку меток, передачу AGENT_ID в окружение контейнера, подключение к заданной Docker-сети и получение сетевого адреса вида ip:port. При этом все детали, связанные с Docker, остались во внешнем слое-адаптере. Слой сценариев взаимодействует со средой выполнения только через интерфейс SandboxRuntime, поэтому в будущем Docker-реализация может быть заменена на другой механизм оркестрации без изменения внутренней логики.

В проекте были реализованы правила подключения томов. Хранилище чата подключается в режиме чтения и записи, кеш зависимостей и lambda-tools подключаются в режиме только для чтения, а том из HTTP-запроса монтируется в контейнер как рабочий том. Такой подход позволяет агенту работать с пользовательскими данными и при этом снижает риск изменения системных зависимостей и платформенных инструментов.

Отдельное внимание было уделено жизненному циклу и устойчивости. Для сессий песочниц используется TTL, после истечения которого сессия может быть завершена процессом очистки. Фоновая очистка запускается в жизненном цикле приложения и периодически удаляет просроченные песочницы. Также была реализована сверка состояния при запуске: после рестарта master-service сервис может восстановить информацию о уже работающих контейнерах по меткам Docker и тем самым избежать запуска дубликатов для одного и того же чата.

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

Для наблюдаемости проекта были реализованы логи, метрики и трейсы. Внутренние слои используют только интерфейсы Logger, Metrics и Tracer, а конкретная реализация через OpenTelemetry находится во внешних адаптерах. Жизненный цикл песочниц публикует метрики создания, удаления, очистки, ошибок и количества активных песочниц. Среда выполнения Docker фиксирует длительность операций создания, остановки и получения списка активных контейнеров, а также ошибки среды выполнения. Такой подход позволяет анализировать работу сервиса в production-среде и при этом не нарушает границы чистой архитектуры.

В процессе практики также велась проектная документация. Для ключевых архитектурных решений были оформлены короткие ADR-документы: точка сборки и жизненный цикл объектов, конфигурация из YAML и переменных окружения, наблюдаемость через интерфейсы, версионированный HTTP API, оркестрация Docker-песочниц в первой версии, сверка состояния при запуске, наблюдаемость жизненного цикла и управляющий HTTP API для песочниц. Наличие таких документов помогает фиксировать не только итоговое решение, но и причины его выбора, ограничения и последствия.

Значительная часть работы была связана с тестированием и ревью. Для логики сценариев использовались тесты с поддельными часами, поддельной средой выполнения и поддельными портами наблюдаемости, что позволяло проверять поведение без запуска реального Docker. Были покрыты сценарии создания, переиспользования, конфликта, TTL, очистки, удаления, отката, сверки состояния при запуске, наблюдаемости и HTTP-границы. Для Docker-адаптера использовались тесты, проверяющие политику монтирования, конфигурацию сети, передачу AGENT_ID, получение сетевого адреса и обработку ошибок. Также проводились ревью архитектурных границ, направленные на проверку того, что FastAPI, Docker и OpenTelemetry не протекают во внутренние слои.

Итогом практики стала рабочая реализация первой версии master-service для управления контейнерами-песочницами ИИ-агентов. Сервис умеет создавать и переиспользовать песочницу по chat_id, учитывать agent_id и volume_host_path, возвращать сетевой адрес агента внутри Docker-сети, удалять активную песочницу, очищать просроченные сессии, восстанавливать состояние после рестарта и публиковать сигналы наблюдаемости. При этом архитектура проекта остаётся расширяемой: в дальнейшем можно добавить аутентификацию, временный доступ, WebSocket или p2p-транспорт, CRUD API для рабочих пространств и чатов, центральную базу данных, S3-хранилище артефактов, политику квот и многоузловую оркестрацию.

В результате прохождения практики были получены и закреплены навыки проектирования backend-сервисов, применения чистой архитектуры и SOLID, работы с FastAPI, Docker, OpenTelemetry, типизированной конфигурацией, внедрением зависимостей, тестированием и технической документацией. Практика позволила глубже понять устройство инфраструктурных компонентов платформы ИИ-агентов и приобрести опыт разработки сервиса, который может использоваться как основа для дальнейшего развития production-системы.