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-системы.

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