Загрузить файлы в «platform»

Add report

platform/practice_report_Malinin_Yaroslav.md

@@ -0,0 +1,205 @@
+**ФЕДЕРАЛЬНОЕ ГОСУДАРСТВЕННОЕ АВТОНОМНОЕ ОБРАЗОВАТЕЛЬНОЕ УЧРЕЖДЕНИЕ ВЫСШЕГО ОБРАЗОВАНИЯ**
+
+**«МОСКОВСКИЙ АВИАЦИОННЫЙ ИНСТИТУТ**
+
+**(национальный исследовательский университет)»**
+
+Институт № 8 «Компьютерные науки и прикладная математика»
+
+Кафедра ЦОП ВО «ТОП-ИТ»
+
+**Журнал практики**
+
+Учебная группа: \[указать группу\]
+
+ФИО обучающегося: Малинин Ярослав ...
+
+Направление подготовки / специальность:
+
+\[указать код и название направления\]
+
+Вид практики: \[указать вид практики\]
+
+Оценка за практику: \___\___\___\___\___\___\__ \[ФИО руководителя\]
+
+**Москва 2026**
+
+# **1\. Место и сроки проведения практики**
+
+Наименование организации: ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"»
+
+Сроки проведения практики:
+
+Дата начала практики: 09.02.2026
+
+Дата окончания практики: 07.06.2026
+
+# **2\. Инструктаж по технике безопасности**
+
+Проведен инструктаж по технике безопасности.
+
+Подпись проводившего: \___\___\___\___\___\___\___\___\__
+
+Расшифровка подписи: Ухов П.А.
+
+Дата проведения: 9 февраля 2026 г.
+
+# **3\. Индивидуальное задание обучающегося**
+
+Разработка клиентской библиотеки (SDK) для агентной платформы Lambda в интересах команды пользовательских поверхностей. В рамках задания необходимо принять участие в проектировании общей архитектуры агента, согласовать с командой поверхностей протокол канала общения, спроектировать и реализовать основные модели взаимодействия SDK, реализовать клиентскую часть канала общения с поддержкой потоковых ответов, отключения и обработки ошибок. Интегрировать готовые навыки на базе Composio в логику агента, разработать подсистему логирования с конфигурацией через YAML-манифесты и настроить инструмент наблюдаемости Langfuse для трассировки сессий агента.
+
+# **4\. План выполнения индивидуального задания обучающегося**
+
+|     |     |     |     |
+| --- | --- | --- | --- |
+| **№ п/п** | **Место проведения** | **Тема** | **Период выполнения** |
+| 1   | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Инструктаж по технике безопасности. Знакомство с задачами, архитектурой агентной платформы и ролью SDK-слоя в инфраструктуре. | 09.02.2026-09.02.2026 |
+| 2   | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Разработка и согласование высокоуровневой архитектуры агента: компоненты платформы, потоки данных, границы ответственности команд, интерфейсы взаимодействия. | 10.02.2026–20.02.2026 |
+| 3   | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Созвон с командой поверхностей (surfaces). Определение протокола канала общения: стриминг, отключение, обработка ошибок. Согласование контракта клиент–агент. | 23.02.2026–27.02.2026 |
+| 4   | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Исследование существующих подходов к построению клиентских SDK для AI-агентов. Изучение Composio, Langfuse и смежных инструментов наблюдаемости. | 02.03.2026–13.03.2026 |
+| 5   | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Проектирование и реализация основных моделей взаимодействия SDK: базовые классы клиента, структуры запроса и ответа, типизация событий стриминга. | 16.03.2026–27.03.2026 |
+| 6   | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Реализация клиентской части канала общения: потоковая передача ответа (streaming), механизм отключения сессии, обработка ошибок и повторных подключений. | 30.03.2026–17.04.2026 |
+| 7   | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Созвон с командой Browseuse. Уточнение требований к интеграции навыков на базе Composio, согласование форматов входных и выходных данных для внешних действий. | 20.04.2026–24.04.2026 |
+| 8   | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Интеграция готовых навыков (skills) через Composio: подключение внешних API-инструментов, маппинг схем входных параметров, тестирование вызова инструментов из агента. | 27.04.2026–08.05.2026 |
+| 9   | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Разработка подсистемы логирования: настройка конфигурации через манифесты YAML, реализация структурированного вывода, маршрутизация логов по уровням и компонентам. | 11.05.2026–15.05.2026 |
+| 10  | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Настройка Langfuse: интеграция трассировки в SDK, передача span-данных по сессиям агента, конфигурирование проекта и проверка дашборда наблюдаемости. | 18.05.2026–22.05.2026 |
+| 11  | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Интеграционное тестирование SDK совместно с агентной платформой и командой поверхностей. Отладка edge-сценариев стриминга, ошибок транспорта и поведения при разрыве соединения. | 25.05.2026–29.05.2026 |
+| 12  | ООО «ГРУППА КОМПАНИЙ "ИННОТЕХ"» | Подготовка материалов отчета. Описание архитектуры SDK, принятых решений, результатов разработки и итогов практики. | 01.06.2026–07.06.2026 |
+
+Утверждаю: __________________________ / Ухов П.А. / 9 февраля 2026 г.
+Подпись руководителя от МАИ, расшифровка подписи, дата утверждения
+
+Утверждаю: __________________________ / ____________________ / 9 февраля 2026 г.
+Подпись руководителя от организации/предприятия, расшифровка подписи, дата утверждения
+
+Ознакомлен: __________________________ / Малинин Я.Ю. / 9 февраля 2026 г.
+Подпись обучающейся, расшифровка подписи, дата ознакомления
+
+# **5\. Отзыв руководителя практики от организации/предприятия**
+
+Обучающийся группы М80-102БВ-25 Малинин Ярослав Юрьевич проходил практику в ООО “Группа компаний “Иннотех”.
+
+В ходе практики обучающийся был включён в разработку ядра агентной платформы Lambda и отвечал за создание клиентской библиотеки (SDK), предназначенной для команды пользовательских поверхностей. Основное внимание было уделено участию в формировании общей архитектуры агента, проектированию моделей взаимодействия, реализации клиентской части канала общения с поддержкой стриминга, интеграции навыков через Composio, построению подсистемы логирования и настройке Langfuse.
+
+Обучающийся принял участие в архитектурных обсуждениях с командами поверхностей и Browseuse, самостоятельно определил протокол канала общения, спроектировал и реализовал базовые классы SDK, реализовал потоковую передачу ответов агента с корректной обработкой отключения и ошибок, подключил инструменты Composio и обеспечил их вызов из агента, разработал гибкую систему конфигурирования логов через YAML-манифесты и настроил трассировку сессий в Langfuse.
+
+За время прохождения практики обучающийся продемонстрировал высокий уровень самостоятельности, глубокое понимание архитектурных паттернов построения клиентских библиотек, уверенные знания Python, асинхронного программирования, работы с потоковыми HTTP-ответами, инструментов интеграции внешних API (Composio), систем наблюдаемости (Langfuse) и конфигурирования через YAML.
+
+Материалы, изложенные в отчете обучающегося, полностью соответствуют индивидуальному заданию, рекомендуемая оценка «отлично».
+
+Подпись руководителя от организации/предприятия: \___\___\___\___\___\___\___\___\__
+
+Расшифровка подписи: \[ФИО руководителя\]
+
+Дата: \___\__ \___\___\____ 2026 г.
+
+# **6\. Отчет обучающегося по практике**
+
+## **Цель и задачи практики**
+
+Целью моей практики была разработка клиентской библиотеки (SDK) для агентной платформы Lambda, используемой командой пользовательских поверхностей. Под SDK в проекте понимался слой, который абстрагирует протокол общения с агентом: предоставляет удобный интерфейс для инициации диалога, получения потоковых ответов, управления жизненным циклом сессии и обработки ошибок транспорта; кроме этого — интегрирует готовые навыки и обеспечивает наблюдаемость через логирование и трассировку.
+
+В рамках практики были поставлены следующие задачи:
+
+- принять участие в проектировании общей архитектуры агентной платформы;
+- согласовать с командой поверхностей протокол канала общения;
+- изучить инструменты интеграции навыков (Composio) и наблюдаемости (Langfuse);
+- спроектировать и реализовать основные модели взаимодействия SDK;
+- реализовать клиентскую часть канала общения с поддержкой стриминга, отключения и обработки ошибок;
+- интегрировать готовые навыки через Composio;
+- разработать подсистему логирования с конфигурацией через YAML-манифесты;
+- настроить Langfuse для трассировки сессий агента;
+- провести интеграционное тестирование совместно с командами платформы и поверхностей.
+
+## **Общий контекст проекта**
+
+Практика проходила в ООО “Группа компаний “Иннотех” и была связана с разработкой core-платформы для AI-агентов. Платформа задумана не как отдельный агент, а как инфраструктура, на которой можно запускать персональных агентов для пользователей, подключать разные навыки и внешние API, изолированно исполнять действия в среде агента и предоставлять поверхностям единую точку взаимодействия.
+
+Я отвечал за SDK-слой, предназначенный для команды поверхностей. Поверхности — это транспортные интерфейсы ( Matrix, MAX и другие), через которые пользователь общается с агентом. Им нужен был надёжный клиент, способный открывать сессию с агентом, получать ответы в потоковом режиме, корректно завершать сессию и сообщать об ошибках. Моей задачей было создать такой клиент, а также подключить к агентной платформе готовые навыки через Composio и организовать наблюдаемость через Langfuse.
+
+Разработка велась в репозитории агентной платформы. В рамках практики мной реализованы основные компоненты SDK, система логирования и интеграция с внешними сервисами.
+
+## **Участие в проектировании архитектуры агента**
+
+На первом этапе практики я вместе с командой участвовал в выработке высокоуровневой архитектуры агентной платформы. Обсуждались состав компонентов платформы, способы изоляции агентных контейнеров, модели хранения состояния и пути взаимодействия между поверхностями, SDK, агентом и внешними инструментами.
+
+В ходе архитектурного этапа были зафиксированы следующие ключевые решения. Платформа строится вокруг персональных агентных контейнеров: каждый пользователь получает изолированную среду выполнения. SDK выступает тонким клиентом между поверхностью и агентом: он не содержит логики принятия решений, но обеспечивает надёжный транспорт и единый интерфейс. Навыки подключаются как внешние инструменты и вызываются через агент. Наблюдаемость обеспечивается на уровне трассировки отдельных сессий.
+
+Участие в этом этапе позволило мне точно понять требования к SDK ещё до начала реализации и заранее учесть ограничения платформы.
+
+## **Взаимодействие с командами поверхностей и Browseuse**
+
+Прежде чем приступить к реализации SDK, я провёл серию рабочих встреч с командой поверхностей. На этих созвонах были определены: формат событий, которые поверхность должна передавать в SDK; ожидаемое поведение при получении частичных ответов агента (стриминг); условия завершения сессии; требуемое поведение при сетевых ошибках и таймаутах. Результатом стал согласованный контракт между поверхностью и SDK, который лёг в основу интерфейсов клиентской библиотеки.
+
+Отдельный созвон был проведён с командой Browseuse. На нём обсуждались требования к интеграции навыков: какие инструменты нужны агенту для работы с браузером, как передаются параметры вызова, какой формат ответа ожидается. Это позволило заранее спроектировать схему маппинга Composio-инструментов с учётом реальных сценариев использования.
+
+## **Проектирование моделей взаимодействия SDK**
+
+На основе зафиксированного контракта я спроектировал основные модели взаимодействия SDK. В их состав вошли: класс клиента агента, представляющий точку входа в SDK; модели запроса (сообщение пользователя, идентификатор сессии, метаданные контекста) и ответа (текстовое сообщение, событие завершения, событие ошибки); перечисления состояний сессии и типов событий стриминга.
+
+Ключевым архитектурным решением стало разделение на три уровня: транспортный слой (HTTP-клиент, управление соединением), слой событий (типизированные модели потоковых сообщений) и публичный API SDK (методы запуска сессии, отправки сообщения, отключения). Такое разделение позволило тестировать бизнес-логику в изоляции от сетевого кода и упростило поддержку новых транспортных режимов.
+
+## **Реализация клиентской части канала общения**
+
+Основной технической задачей стала реализация потоковой передачи ответов агента. Агент возвращает ответ не единым блоком, а частями — событиями Server-Sent Events. SDK должен был принимать эти события, разбирать их тип (текстовый чанк, признак завершения, ошибка), передавать в коллбэк поверхности и корректно завершать цикл чтения.
+
+Была реализована асинхронная логика чтения потока: построчный разбор SSE-событий, отдельный обработчик для каждого типа события, механизм отключения через asyncio.Task.cancel() с гарантированным закрытием HTTP-соединения. Обработка ошибок покрывает сценарии разрыва соединения на середине стрима, ответов с HTTP-статусами ошибок, а также таймаутов чтения.
+
+Отдельно был реализован механизм отключения по инициативе клиента. Поверхность может в любой момент отменить текущую сессию — SDK гарантирует, что соединение будет закрыто, ресурсы освобождены, а поверхность получит соответствующее событие завершения.
+
+## **Интеграция навыков через Composio**
+
+Для подключения готовых навыков к агентной платформе использовался Composio — инструмент, предоставляющий унифицированный интерфейс к большому набору внешних API (браузер, файловая система, веб-поиск и другие).
+
+В ходе интеграции я изучил модель инструментов Composio: формат описания, схемы входных параметров, механизм выполнения действий через API Composio. На основе этого была разработана обёртка, позволяющая агенту регистрировать нужные Composio-инструменты и вызывать их в рамках шага рассуждения. При получении вызова инструмента агент передаёт управление в Composio-клиент, который исполняет действие и возвращает результат в нужном формате.
+
+В процессе интеграции были проработаны сценарии ошибок вызова инструментов: таймаут, недоступность внешнего сервиса, некорректные параметры. Агент получает структурированный ответ об ошибке и может учесть его при формировании следующего шага.
+
+## **Подсистема логирования и конфигурация через YAML-манифесты**
+
+Для диагностики и мониторинга работы SDK и агентной платформы была разработана подсистема логирования. Основная задача — предоставить гибкую и единообразную настройку логов без необходимости менять код: вся конфигурация описывается в YAML-манифестах.
+
+Манифест позволяет задать: уровень логирования для каждого компонента (SDK, агент, Composio-клиент, транспортный слой); формат вывода (plain text или структурированный JSON); направление потоков (stdout, файл, оба варианта); имена файлов логов и правила их ротации. Конфиг загружается при старте агента, валидируется и применяется к иерархии логгеров Python.
+
+Структурированный формат (JSON) использован для машинно-читаемых логов, что позволяет собирать их централизованно. В каждую запись включаются: временная метка, уровень, компонент, идентификатор сессии и трассировочный идентификатор, что упрощает корреляцию событий при отладке.
+
+## **Настройка Langfuse**
+
+Langfuse — система наблюдаемости, специализированная для LLM-приложений. Она позволяет отслеживать трассировки сессий агента: какие сообщения поступили на вход, какие шаги рассуждения выполнил агент, какие инструменты были вызваны, сколько токенов потрачено и какой ответ вернул агент.
+
+В ходе настройки Langfuse я интегрировал трассировку в SDK: при начале каждой сессии создаётся корневой trace, каждый LLM-вызов и вызов инструмента добавляется как вложенный span. Идентификатор трассировки передаётся через контекст сессии, что позволяет связать события SDK, агента и Composio в единую цепочку.
+
+Конфигурация Langfuse вынесена в YAML-манифест: ключи API, адрес сервера, включение/выключение трассировки и уровень детализации — всё управляется через конфиг без изменения кода. В дашборде Langfuse была проверена корректность отображения трасс, их структура и полнота атрибутов.
+
+## **Тестирование**
+
+Разработка SDK сопровождалась юнит- и интеграционными тестами. Юнит-тесты покрывали разбор SSE-событий, поведение клиента при разных типах ответов, корректность отключения, логику маппинга Composio-инструментов и загрузку конфигурации из YAML.
+
+Для изоляции сетевого кода использовались моки HTTP-клиента: тесты проверяли поведение SDK при нормальном завершении стрима, при обрыве соединения на середине, при ошибочном HTTP-статусе и при таймауте. Это позволило покрыть большинство граничных сценариев без необходимости поднимать реальный агент.
+
+Интеграционное тестирование проводилось совместно с командой поверхностей: Matrix-поверхность подключалась к реальному агенту через разработанный SDK. В ходе тестирования были выявлены и исправлены несколько проблем с обработкой многострочных чанков и закрытием соединения при отмене сессии.
+
+## **Полученные результаты**
+
+По итогам практики мной были выполнены следующие работы:
+
+- принято участие в проектировании архитектуры агентной платформы Lambda;
+- согласован с командой поверхностей протокол канала общения;
+- спроектированы основные модели взаимодействия SDK (клиент, запрос, ответ, события стриминга);
+- реализована клиентская часть канала общения с поддержкой потоковых ответов (SSE);
+- реализована обработка отключения сессии по инициативе клиента;
+- реализована обработка ошибок транспорта (разрыв соединения, таймаут, HTTP-ошибки);
+- выполнена интеграция готовых навыков через Composio;
+- разработана подсистема логирования с конфигурацией через YAML-манифесты;
+- настроена трассировка сессий агента в Langfuse;
+- проведено юнит- и интеграционное тестирование совместно с командой поверхностей.
+
+## **Вывод**
+
+В ходе практики был спроектирован и реализован SDK-слой для агентной платформы Lambda, предназначенный для использования командой пользовательских поверхностей. Основными результатами стали: надёжная клиентская реализация потоковых ответов агента с корректной обработкой отключения и ошибок; интеграция внешних навыков через Composio; гибкая система логирования на основе YAML-конфигурации и трассировка сессий в Langfuse.
+
+Разработанный SDK был использован командой поверхностей при интеграции Matrix-адаптера с агентной платформой, что подтвердило работоспособность выбранных решений в реальном сценарии. В ходе практики я получил практический опыт проектирования клиентских библиотек для AI-систем, работы с потоковыми HTTP-протоколами, интеграции внешних API через инструментальный слой, построения систем логирования и наблюдаемости, а также взаимодействия с несколькими параллельными командами разработки.
+
+Материалы, изложенные в отчете обучающегося, полностью соответствуют индивидуальному заданию.
+
+Подпись обучающегося: \___\___\___\___\___\___\___\___\__ / Малинин Ярослав / 07.06.2026