Перейти к основному содержимому
Версия: main

Модули-интеграции

Интеграция внешнего сервиса — обычный модуль агента из пакета 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 неактивна, а интеграции работают на ручных токенах.

Как написать свою интеграцию​

  1. Создайте пакет modules/integrations/<сервис>/ с тремя частями: module.py (класс модуля с инструментами и проверкой подключения в is_enabled()), provider.py (сборка провайдера из StaticOAuthConfig), auth.py (получение токена пользователя внутри инструментов).
  2. Зарегистрируйте модуль в GigaAgent.get_modules().
  3. Если инструменты возвращают данные для виджета — соберите ответ конструктором payload с маркером widget и оберните with_widget_note(), чтобы агент не пересказывал содержимое (см. GenUI).

Трекеры​

Для сервисов задач есть общий слой modules/integrations/tracker_base.py: нормализованный контракт задачи (make_issue), payload доски и одиночной карточки, генеративная композиция emit_composed_board() и база BaseTrackerModule со стандартными серверными маршрутами переходов статусов. Провайдер, вернувший нормализованный payload, отображается готовыми виджетами без правок интерфейса. Активных модулей-трекеров сейчас нет — контракт готов к подключению следующего сервиса.