# Журнал практики ФЕДЕРАЛЬНОЕ ГОСУДАРСТВЕННОЕ АВТОНОМНОЕ ОБРАЗОВАТЕЛЬНОЕ УЧРЕЖДЕНИЕ ВЫСШЕГО ОБРАЗОВАНИЯ «МОСКОВСКИЙ АВИАЦИОННЫЙ ИНСТИТУТ (национальный исследовательский университет)» Институт № 8 «Компьютерные науки и прикладная математика» Кафедра ЦОП ВО «ТОП-ИТ» Учебная группа: [указать группу] ФИО обучающегося: [Путиловский Михаил ...] Направление подготовки / специальность: [указать код и название направления] Вид практики: [указать вид практики] Оценка за практику: ____________________ [ФИО руководителя] Москва 2026 ## 1. Место и сроки проведения практики Наименование организации: ИИ-лаборатория lambda Сроки проведения практики: Дата начала практики: [дата начала] Дата окончания практики: [дата окончания] ## 2. Инструктаж по технике безопасности Проведен инструктаж по технике безопасности. Подпись проводившего: __________________________ Расшифровка подписи: [ФИО проводившего инструктаж] Дата проведения: [дата начала практики] ## 3. Индивидуальное задание обучающегося Разработка и сопровождение поверхностей взаимодействия пользователей с AI-агентами платформы Lambda. В рамках задания необходимо исследовать пользовательские сценарии Telegram и Matrix, спроектировать общий surface-слой, реализовать простой Telegram-прототип, разработать и довести до рабочего deployment-состояния Matrix-поверхность, подготовить эксплуатационную документацию и координировать командную работу по дальнейшему развитию поверхностей, включая старт направления MAX. Поверхность MAX разрабатывалась другими участниками команды. В данном отчете она учитывается только как зона тимлидской координации, без включения ее реализации в мой личный технический вклад. ## 4. План выполнения индивидуального задания обучающегося | № п/п | Место проведения | Тема | Период выполнения | |---|---|---|---| | 1 | ИИ-лаборатория lambda | Инструктаж по технике безопасности. Знакомство с задачами лаборатории Lambda, агентной платформой и направлением пользовательских поверхностей. | [дата]-[дата] | | 2 | ИИ-лаборатория lambda | Исследование Telegram Bot API, Matrix API, вариантов организации пользовательских чатов, команд и передачи вложений. | [дата]-[дата] | | 3 | ИИ-лаборатория lambda | Проектирование общего ядра surface-слоя: протокол событий, диспетчеризация, хранение состояния, абстракция платформенного клиента. | [дата]-[дата] | | 4 | ИИ-лаборатория lambda | Реализация простого Telegram-прототипа и проверка режима Telegram Forum Topics. | [дата]-[дата] | | 5 | ИИ-лаборатория lambda | Реализация Matrix-поверхности: onboarding, рабочие комнаты, команды управления чатами, маршрутизация сообщений и состояние чатов. | [дата]-[дата] | | 6 | ИИ-лаборатория lambda | Интеграция Matrix-поверхности с реальным agent API, поддержка потоковых ответов и разделение контекстов по Matrix room. | [дата]-[дата] | | 7 | ИИ-лаборатория lambda | Реализация передачи файлов через shared workspace, поддержки нескольких агентов и маршрутизации пользователей к агентам. | [дата]-[дата] | | 8 | ИИ-лаборатория lambda | Подготовка Docker- и production deployment-артефактов, документации для передачи Matrix-поверхности в эксплуатацию. | [дата]-[дата] | | 9 | ИИ-лаборатория lambda | Координация работ команды по дальнейшим поверхностям, включая старт направления MAX. | [дата]-[дата] | | 10 | ИИ-лаборатория lambda | Подготовка материалов отчета, описание архитектуры проекта, результатов разработки и итогов практики. | [дата]-[дата] | Утверждаю: __________________________ / [ФИО руководителя от МАИ] / [дата начала практики] Подпись руководителя от МАИ, расшифровка подписи, дата утверждения Утверждаю: __________________________ / [ФИО руководителя от организации] / [дата начала практики] Подпись руководителя от организации/предприятия, расшифровка подписи, дата утверждения Ознакомлен: __________________________ / [Путиловский М.] / [дата начала практики] Подпись обучающегося, расшифровка подписи, дата ознакомления ## 5. Отзыв руководителя практики от организации/предприятия Обучающийся группы [указать группу] [ФИО] проходил практику в ИИ-лаборатории lambda. В ходе практики обучающийся был назначен тимлидом команды поверхностей взаимодействия с агентами и принимал участие в разработке surface-слоя для платформы Lambda. Основное внимание было уделено проектированию транспортно-независимой архитектуры, реализации простого Telegram-прототипа, разработке полноценной Matrix-поверхности, интеграции с agent API, передаче файлов через shared workspace и подготовке deployment-артефактов. Обучающийся выполнил исследование ограничений Telegram и Matrix, подготовил архитектурные спецификации, реализовал ключевые backend-компоненты, настроил маршрутизацию пользователей к агентам и оформил эксплуатационную документацию. Matrix-поверхность была доведена до рабочего состояния, задеплоена и используется для взаимодействия пользователей с агентами Lambda. Как тимлид обучающийся координировал дальнейшую работу команды по развитию новых поверхностей, включая старт направления MAX, обеспечивал передачу контекста и поддерживал единый архитектурный подход к разработке адаптеров. За время прохождения практики обучающийся продемонстрировал высокий уровень самостоятельности, системного мышления и инженерной ответственности, уверенные знания Python, асинхронного программирования, Docker, API мессенджеров, проектирования интеграционных сервисов и командной разработки. Материалы, изложенные в отчете обучающегося, полностью соответствуют индивидуальному заданию, рекомендуемая оценка «отлично». Подпись руководителя от организации/предприятия: __________________________ Расшифровка подписи: [ФИО руководителя] Дата: _____ __________ 2026 г. ## 6. Отчет обучающегося по практике ### Цель и задачи практики Целью моей практики была разработка пользовательских поверхностей для взаимодействия с AI-агентами платформы Lambda. Под поверхностью в проекте понимался транспортный интерфейс, через который пользователь может создавать отдельные контексты общения, отправлять сообщения и файлы, получать потоковые ответы агента и работать с несколькими агентными сессиями без прямого доступа к внутренней инфраструктуре платформы. В рамках практики были поставлены следующие задачи: - изучить ограничения Telegram Bot API и Matrix API для сценариев агентного общения; - спроектировать общий surface-слой, не зависящий от конкретного мессенджера; - реализовать простой Telegram-прототип для проверки ранних UX-гипотез; - реализовать полноценную Matrix-поверхность для рабочих агентных чатов; - подключить Matrix-поверхность к реальному agent API; - обеспечить разделение контекстов по комнатам и маршрутизацию пользователей к агентам; - реализовать передачу файлов через shared workspace; - подготовить Docker- и deployment-артефакты; - оформить техническую документацию; - координировать командную работу по новым поверхностям, включая направление MAX. ### Общий контекст проекта Практика проходила в ИИ-лаборатории lambda и была связана с развитием агентной платформы Lambda. Одной из задач платформы является предоставление пользователю удобного интерфейса для работы с AI-агентом. Пользователь не должен напрямую взаимодействовать с внутренними сервисами платформы: ему нужен привычный канал общения, например мессенджер, в котором можно создать отдельный чат, отправить запрос, приложить файл и получить ответ агента. В ходе практики я был назначен тимлидом команды поверхностей взаимодействия с агентами. Основным техническим результатом стала Matrix-поверхность, которая была доведена до рабочего состояния, задеплоена и используется для взаимодействия с агентами Lambda. Дополнительно был реализован простой Telegram-прототип, использованный для проверки ранних архитектурных и UX-решений. После стабилизации Matrix-направления часть команды начала работу над поверхностью MAX; эту работу я координировал как тимлид, но не выполнял ее реализацию лично. Разработка велась в репозитории `surfaces-bot`. По истории Git мой личный вклад включает 197 авторских коммитов, сделанных в период с 26 марта по 8 мая 2026 года. Основные зоны изменений: `core/`, `sdk/`, `adapter/telegram/`, `adapter/matrix/`, `config/`, Docker Compose-артефакты, тесты и проектная документация. ### Анализ задачи и исследование вариантов реализации На первом этапе была изучена предметная область проекта. Для платформы было важно иметь изолированный и расширяемый слой коммуникации, который не привязан к одному мессенджеру. Поэтому в основу проекта была положена идея общего ядра и тонких транспортных адаптеров. Для Telegram были исследованы варианты организации нескольких чатов: обычные личные сообщения, группы, супергруппы и Forum Topics. Telegram Bot API не позволяет боту самостоятельно создавать группы для пользователя, поэтому автоматическое создание полноценного рабочего пространства оказалось невозможным. В результате Telegram был использован как быстрый прототип, а Forum Topics рассматривались как дополнительный режим для пользователей, которые готовы вручную подключить супергруппу. Для Matrix были исследованы события комнат, приглашения, организация пространств, работа с отдельными room-чатами, ограничения шифрования и способы хранения метаданных. Matrix лучше подходил для целевой задачи, поскольку позволяет создавать отдельные комнаты, приглашать пользователей, хранить структуру общения на уровне транспорта и строить управляемую модель `room-per-chat`. Также на раннем этапе был зафиксирован платформенный контракт. Поскольку реальный SDK платформы находился в развитии, для независимой разработки surface-слоя был создан собственный интерфейс клиента платформы и mock-реализация. Это позволило разрабатывать пользовательский сценарий, обработчики, хранилище и адаптеры без ожидания финального состояния агентной платформы. ### Проектирование общего ядра surface-слоя Для исключения дублирования логики между Telegram и Matrix было реализовано общее ядро в директории `core/`. В него вошли единый протокол событий и ответов, диспетчер входящих событий, менеджер чатов, менеджер авторизации, менеджер настроек и абстракции хранилища состояния. Ключевое архитектурное решение состояло в разделении проекта на три слоя: - транспортный адаптер, который знает особенности конкретного мессенджера; - общее ядро, которое работает с унифицированными событиями и не зависит от Telegram или Matrix; - платформенный клиент, через который surface-слой обращается к агенту. Такой подход позволил проверять бизнес-логику через тесты без запуска реальных мессенджеров. Он также подготовил проект к добавлению новых поверхностей: для новой платформы требуется написать адаптер, конвертер входящих событий и рендеринг ответов, не меняя базовые правила работы с чатами и сообщениями. В ходе разработки также была устранена архитектурная проблема с именованием: ранний каталог `platform/` был переименован в `sdk/`, чтобы избежать конфликта с одноименным модулем стандартной библиотеки Python и точнее выразить назначение слоя. ### Реализация Telegram-прототипа Telegram-направление использовалось как быстрый способ проверить UX взаимодействия пользователя с агентом. В рамках личного вклада был реализован адаптер на базе `aiogram 3.x`, базовая обработка команд, конвертация сообщений в общий протокол, хранение соответствий Telegram-пользователей и внутренних чатов, а также прототип режима Forum Topics. В простом Telegram-прототипе были реализованы стартовый сценарий через `/start`, создание и выбор чатов, обработка пользовательских сообщений, меню команд бота, базовая работа с настройками и подтверждениями, привязка Telegram thread/topic к внутреннему контексту и первичная поддержка передачи файлов в общий формат вложений. Отдельно была проработана модель Telegram Forum Topics. Она позволяла использовать темы супергруппы как визуальное представление отдельных чатов. При этом из-за ограничений Telegram Bot API пользователь должен был создать группу самостоятельно и выдать боту права администратора. В ходе проверки были исправлены проблемы обработки команд, архивирования тем, маршрутизации сообщений и поведения `/new` в topic-контексте. Telegram-прототип не стал основной production-поверхностью, но выполнил важную роль: помог проверить общий surface-протокол, выявить ограничения транспортов, уточнить требования к хранению контекста и подготовить архитектуру для Matrix. ### Реализация Matrix-поверхности Основной результат практики - полноценная Matrix-поверхность, которая была доведена до рабочего состояния, задеплоена и используется для взаимодействия с агентами Lambda. В Matrix-адаптере были реализованы entrypoint бота на базе `matrix-nio`, обработка приглашений пользователя, создание персонального пространства и рабочих комнат, модель отдельной Matrix room для отдельного агентного чата, конвертация Matrix-событий во внутренний протокол, маршрутизация входящих сообщений, команды управления чатами, обработка подтверждений через текстовые команды, защита от обработки собственных сообщений бота, хранение метаданных комнат, восстановление состояния после рестарта и документация по запуску. В процессе реализации Matrix-направления были пересмотрены некоторые ранние UX-гипотезы. Изначально рассматривалась модель Space-first с отдельной комнатой настроек. На практике более устойчивым оказался DM-first onboarding с последующим созданием реальных рабочих комнат. Пользователь приглашает бота, бот создает рабочее пространство и комнату первого чата, а дальнейшая работа ведется в отдельных комнатах. Это решение лучше соответствует модели Matrix и делает чаты видимыми сущностями самого транспорта. Существенная часть работы была связана с надежностью. Были исправлены сценарии повторного invite, дублирующего приветствия, случайной обработки собственных сообщений, потери room metadata, неправильного соответствия между Matrix room и платформенным chat id. Также была реализована startup reconciliation: при рестарте бот восстанавливает локальные связи между пользователями, комнатами и агентными контекстами. ### Интеграция с агентной платформой После стабилизации базового Matrix-адаптера была выполнена интеграция с реальным agent API. Поверхность стала обращаться к агенту через тонкий transport adapter, использующий `AgentApi`. Для каждого Matrix room поддерживается отдельный `platform_chat_id`, что позволяет разделять контексты разных комнат и не смешивать историю общения. Была реализована маршрутизация пользователей к агентам через статический реестр. Конфигурация `matrix-agents.yaml` задает соответствие Matrix-пользователей и агентных контейнеров, а также `base_url` и `workspace_path` каждого агента. Такой подход подходит для MVP-топологии, где один инстанс Matrix-бота обслуживает несколько пользователей, а каждый пользователь связан со своим агентным контейнером. Отдельное внимание было уделено потоковым ответам. Поверхность должна не просто ждать финального ответа агента, а корректно принимать события, обновлять пользовательский интерфейс и передавать сообщения в Matrix. В результате Matrix-поверхность стала пригодна для реального диалога с агентом, а не только для mock-сценария. ### Передача файлов и shared workspace Для практического использования агентной поверхности требовалась передача файлов от пользователя агенту и обратно. В Matrix файлы и текстовые сообщения приходят отдельными событиями, поэтому была реализована staged-модель вложений: пользователь может отправить файл, посмотреть список вложений, удалить лишнее и затем отправить текстовую инструкцию, с которой файлы будут переданы агенту. Для production-сценария была выбрана схема shared workspace. Matrix-бот сохраняет входящие файлы в рабочую директорию конкретного агента, а агент видит эту же директорию как свой `/workspace`. Если имя файла уже существует, бот выбирает безопасное имя с суффиксом вида `file (1).ext`. Исходящие файлы работают в обратную сторону: агент пишет файл в workspace, бот читает его и отправляет пользователю как Matrix file message. Такой подход упростил интеграцию: не потребовался отдельный HTTP-сервис для upload/download, а контракт между поверхностью и агентом остался понятным и воспроизводимым в Docker Compose. ### Deployment и эксплуатационная документация Для передачи Matrix-поверхности в эксплуатацию были подготовлены Docker-артефакты и документация. Production-сценарий оформлен как bot-only deployment: платформа запускает свои агентные контейнеры отдельно, а surface-контейнер подключается к ним через `base_url` и общий volume. Были подготовлены `Dockerfile` с production target, `docker-compose.prod.yml` для production handoff, `docker-compose.fullstack.yml` для внутреннего fullstack E2E-сценария, пример реестра агентов `config/matrix-agents.example.yaml`, документация `docs/deploy-architecture.md` и обновленный `README.md` с инструкциями по запуску, конфигурации и ограничениям. В README зафиксировано, что production target - один контейнер Matrix-поверхности на 25-30 внешних agent containers/services. Также описаны обязательные переменные окружения, формат `matrix-agents.yaml`, схема shared volume и известные ограничения. ### Тестирование и контроль качества Разработка сопровождалась тестами и документированием принятых решений. В репозитории были добавлены тесты для общего ядра, mock- и real-platform слоев, Telegram-адаптера, Matrix-адаптера, передачи файлов, agent registry, восстановления состояния, per-room маршрутизации и deployment handoff. Проверялись сценарии создания и маршрутизации чатов, преобразования сообщений разных транспортов во внутренний протокол, обработки команд пользователя, подтверждения действий, соответствия Matrix room внутреннему chat id и платформенному chat id, загрузки agent registry, передачи файлов через workspace, восстановления состояния после рестарта и корректности Docker/deployment-артефактов. Кроме автоматических проверок, Matrix-поверхность была доведена до фактического deployment-состояния и работает в инфраструктуре проекта. Это является ключевой практической проверкой результата: поверхность не ограничилась локальным прототипом, а была подготовлена к реальному использованию. ### Тимлидская работа и координация команды Помимо личной разработки, в ходе практики я выполнял функции тимлида команды поверхностей. Эта роль включала декомпозицию задач, фиксацию архитектурных решений, подготовку спецификаций, ревью планов, оформление known limitations и передачу контекста другим участникам. В репозитории это отражено большим количеством документации и planning-артефактов: спецификации Telegram и Matrix, планы реализации, исследования API, deployment-документация, инструкции по созданию новой поверхности и отчеты о ходе работ. После стабилизации Matrix-направления часть команды начала заниматься поверхностью MAX. Я не включаю реализацию MAX в свой личный технический вклад, однако как тимлид участвовал в постановке направления: объяснял общую архитектуру surface-слоя, границы ответственности адаптеров и требования к совместимости с ядром и агентной платформой. ### Полученные результаты По итогам практики мной были выполнены следующие работы: - спроектирован общий surface-слой для разных пользовательских транспортов; - реализовано общее ядро с унифицированным протоколом событий; - создан простой Telegram-прототип и проверен режим Forum Topics; - реализована полноценная Matrix-поверхность; - выполнена интеграция Matrix-поверхности с agent API; - реализовано разделение контекстов по Matrix room; - добавлена маршрутизация пользователей к агентам через agent registry; - реализована передача файлов через shared workspace; - подготовлены Docker- и deployment-артефакты; - оформлена эксплуатационная документация; - выполнена тимлидская координация команды поверхностей. ### Вывод В ходе практики был создан и доведен до рабочего состояния surface-слой для взаимодействия пользователей с агентами Lambda. Личным основным результатом стала Matrix-поверхность: она поддерживает отдельные комнаты для чатов, команды управления контекстом, маршрутизацию к агентам, передачу файлов через shared workspace, восстановление состояния после рестарта и production deployment-сценарий. Также был реализован простой Telegram-прототип, который позволил проверить ранние UX-решения и общий протокол взаимодействия. Несмотря на ограничения Telegram Bot API, этот прототип оказался полезен для архитектурной проверки и исследования альтернативных пользовательских сценариев. В ходе практики я получил практический опыт проектирования транспортно-независимых backend-слоев, интеграции мессенджеров с агентной платформой, работы с асинхронными Python-сервисами, Docker deployment, тестирования, документирования архитектуры и технического руководства небольшой командой разработки. Материалы, изложенные в отчете обучающегося, полностью соответствуют индивидуальному заданию. Подпись обучающегося: __________________________ / [Путиловский М.] / [дата окончания практики]