Плагины интеграции

Плагины интеграции позволяют namespace подключаться к внешним источникам данных и хукам событий без жёсткой привязки провайдерской логики к основному бэкенду. Встроенные плагины лежат в src/plugins/integrations/builtin/; кастомные плагины должны реализовывать тот же контракт, что и src/plugins/integrations/types.ts.

Контракт

Каждый плагин экспортирует IntegrationPlugin:

import { z } from 'zod';
import { PluginCapability, type IntegrationPlugin } from '../types.ts';

const configSchema = z.object({
  url: z.string().url(),
});

export const examplePlugin: IntegrationPlugin<z.infer<typeof configSchema>> = {
  id: 'example',
  name: 'Example',
  category: 'automation',
  configSchema,
  capabilities: [PluginCapability.ApprovalHook],
  async onApprovalCreated(event, context) {
    await context.http.post(context.config.url, {
      event: 'approval.created',
      approvalId: event.approvalId,
    });
  },
};

Реестр даёт плагину PluginContext: namespace и department id, валидированную конфигурацию, Prisma, logger и HTTP-клиент с rate limit. Все вызовы init и хуков обёрнуты в try/catch с 5-секундным таймаутом — сбои плагина логируются и пропускаются, не ломая хост-поток.

Capabilities

• agent_query — запускается на этапе обогащения запроса, возвращает структурированные PluginResult.
• approval_hook — получает события approval.created.
• document_hook — получает события готовности документа после успешной генерации.
• tools — предоставляет агентам tool definitions (для будущего расширения).

Встроенные плагины

• opendatabot — мок-поиск по ЕДРПОУ по 8-значному коду из запроса пользователя.
• webhooks — исходящий HTTP POST для событий approval.created и document.ready, опциональная HMAC-подпись в заголовке x-agentcore-signature.

API

Все маршруты требуют JWT-авторизации. Управление плагинами namespace требует прав canManagePlugins или canManageNamespaces; не-глобальные пользователи ограничены namespaces в рамках их эффективного department scope.

• GET /api/v1/plugins
• GET /api/v1/namespaces/:id/plugins
• POST /api/v1/namespaces/:id/plugins/:pluginId
• PATCH /api/v1/namespaces/:id/plugins/:pluginId
• DELETE /api/v1/namespaces/:id/plugins/:pluginId

Конфигурация валидируется по Zod-схеме плагина перед записью в NamespacePlugin. Обновления через API инвалидируют кеш реестра для этого namespace — следующий вызов хука перезагрузит свежую конфигурацию.