From d99167416b30f86f53b27defebd1a472d5d3bd2c Mon Sep 17 00:00:00 2001 From: gglamer Date: Wed, 20 May 2026 23:52:07 +0300 Subject: [PATCH 1/2] [feat] add Azamat report --- platform/Nuraev_Azamat_report.md | 65 ++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 platform/Nuraev_Azamat_report.md diff --git a/platform/Nuraev_Azamat_report.md b/platform/Nuraev_Azamat_report.md new file mode 100644 index 0000000..85ad094 --- /dev/null +++ b/platform/Nuraev_Azamat_report.md @@ -0,0 +1,65 @@ +# Нураев Азамат Ринатович + +### Индивидуальное задание + +Разработка 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-системы. -- 2.49.1 From bb1b10a1de555048e3a3a820353e466110930152 Mon Sep 17 00:00:00 2001 From: chupappo <2904yr@mail.ru> Date: Sat, 23 May 2026 19:28:34 +0000 Subject: [PATCH 2/2] =?UTF-8?q?=D0=97=D0=B0=D0=B3=D1=80=D1=83=D0=B7=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D1=84=D0=B0=D0=B9=D0=BB=D1=8B=20=D0=B2=20=C2=AB?= =?UTF-8?q?platform=C2=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add report --- platform/practice_report_Malinin_Yaroslav.md | 205 +++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 platform/practice_report_Malinin_Yaroslav.md 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 -- 2.49.1