Модули-интеграции
Интеграция внешнего сервиса — обычный модуль агента из пакета modules/integrations/, дополненный провайдером подключения. Модуль отдаёт инструменты, провайдер описывает карточку в каталоге коннекторов и способ авторизации. Так устроены Яндекс.Почта, Яндекс.Календарь, Яндекс.Диск и VK.
Провайдер подключения
Провайдер строится из StaticOAuthConfig (core/integrations/static_provider.py). Поля описывают и карточку, и протокол:
key,label,icon— идентификатор и вид карточки в каталоге;auth_kind—oauth2,manual_tokenилиboth;authorization_endpoint,token_endpoint,scope— точки OAuth;manual_fields— поля формы для подключения по токену, с подсказками и ссылками;validate_url— проверка живости токена (GET с токеном, ответ 2xx — токен действует);auth_header_scheme— схема заголовка; Яндекс используетAuthorization: OAuth <токен>со схемойOAuthна месте обычнойBearer.
Реестр провайдеров
Реестр core/integrations/registry.py собирает провайдеров обходом модулей загруженного агента: при старте агент регистрируется через set_current_agent(), и каталог в интерфейсе получает список карточек из реестра. Добавленный в get_modules() модуль с провайдером появляется в каталоге сам.
Поток OAuth
Авторизация идёт через всплывающее окно с PKCE и одноразовым state; ответ сервиса принимает серверный обратный вызов, общий для всех интеграций. Полученный токен сохраняется за пользователем и продлевается автоматически. Если сервис вернул отказ или токен отозван, карточка сервиса переходит в состояние «Нужна повторная авторизация».
Учётные данные OAuth-приложения задаются переменными окружения (см. Конфигурацию): общие YANDEX_OAUTH_CLIENT_ID и YANDEX_OAUTH_CLIENT_SECRET, необязательный YANDEX_OAUTH_REDIRECT_URI и отдельная пара для Яндекс.Почты — Яндекс требует отдельное приложение под почтовую область доступа. Пока переменные не заданы, кнопка OAuth неактивна, а интеграции работают на ручных токенах.
Как написать свою интеграцию
- Создайте пакет
modules/integrations/<сервис>/с тремя частями:module.py(класс модуля с инструментами и проверкой подключения вis_enabled()),provider.py(сборка провайдера изStaticOAuthConfig),auth.py(получение токена пользователя внутри инструментов). - Зарегистрируйте модуль в
GigaAgent.get_modules(). - Если инструменты возвращают данные для виджета — соберите ответ конструктором payload с маркером
widgetи обернитеwith_widget_note(), чтобы агент не пересказывал содержимое (см. GenUI).
Трекеры
Для сервисов задач есть общий слой modules/integrations/tracker_base.py: нормализованный контракт задачи (make_issue), payload доски и одиночной карточки, генеративная композиция emit_composed_board() и база BaseTrackerModule со стандартными серверными маршрутами переходов статусов. Провайдер, вернувший нормализованный payload, отображается готовыми виджетами без правок интерфейса. Активных модулей-трекеров сейчас нет — контракт готов к подключению следующего сервиса.