Перейти до основного вмісту

Плагіни інтеграції

Плагіни інтеграції дозволяють просторам імен підключатися до зовнішніх джерел даних і підписуватися на події, не захардкоджуючи поведінку провайдерів у ядро. Вбудовані плагіни лежать у 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: ідентифікатори простору імен і відділу, провалідовану конфігурацію, Prisma, логер і HTTP-клієнт із rate limiting. Усі виклики ініціалізації плагіна та його хуків загорнуті у try/catch з 5-секундним таймаутом, тому помилки плагіна логуються і пропускаються, не ламаючи host-flow.

Можливості​

  • agent_query: виконується під час збагачення запиту і повертає структурований PluginResult.
  • approval_hook: отримує події створення схвалення.
  • document_hook: отримує події готовності документа після успішного ingestion.
  • tools: експонуватиме визначення інструментів для агентів (майбутнє).

Вбудовані плагіни​

  • opendatabot: заглушка (stub) пошуку EDRPOU за 8-значним кодом у запиті користувача.
  • webhooks: вихідний HTTP POST для подій approval.created і document.ready, з опціональним HMAC-підписом у заголовку x-agentcore-signature.

API​

Усі маршрути вимагають JWT-авторизації. Менеджмент плагінів простору імен вимагає canManagePlugins або canManageNamespaces; неглобальні користувачі обмежені просторами імен у межах свого ефективного 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-схемі плагіна і зберігається у таблиці namespace_plugins. Оновлення через API інвалідує кеш реєстру для цього простору імен, тож наступний виклик підхоплює свіжу конфігурацію.