diff --git a/platform/practice_report_Malinin_Yaroslav.md b/platform/practice_report_Malinin_Yaroslav.md new file mode 100644 index 0000000..34aa2e5 --- /dev/null +++ b/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 \ No newline at end of file