Integration Plugins

Integration plugins let a namespace opt into external data sources and event hooks without hardcoding vendor behavior into the core backend. Built-ins live under src/plugins/integrations/builtin/. Custom plugins implement the contract from src/plugins/integrations/types.ts.

Contract

Each plugin exports an 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,
    });
  },
};

The registry supplies PluginContext: namespace and department ids, validated config, Prisma, logger, and a rate-limited HTTP client. Plugin init and hook calls run inside try/catch with a 5-second timeout — failures are logged and skipped without breaking the host flow.

Capabilities

• agent_query — runs during query enrichment and returns structured PluginResult values.
• approval_hook — receives approval-created events.
• document_hook — receives document-ready events after ingestion succeeds.
• tools — reserved for future agent tool definitions.

Built-Ins

• opendatabot — mock EDRPOU lookup from an 8-digit code in a user query.
• webhooks — outbound HTTP POST for approval.created and document.ready events, with optional HMAC signature in x-agentcore-signature.

API

All routes require JWT auth. Plugin management requires canManagePlugins or canManageNamespaces. Non-global users are restricted to namespaces in their effective 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

Config is validated against the plugin's Zod schema before it's written to namespace_plugins. API updates invalidate the registry cache, so the next hook call reloads the latest config.