Control Plane Plugins
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/control-plane-plugins/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
Control Plane Plugins は、信頼されたファーストパーティの Elixir/OTP コードによって Ankole サイトの機能を拡張する仕組みです。プラグインは Ankole.Plugins を通じて、AppConfigure の設定キー、各種サブシステムアダプター、同期トランザクションフック、および監視対象の子プロセスを追加できます。
Control Plane Plugins はリリースビルドにコンパイルされるファーストパーティの Elixir モジュール(:control_plane_plugin_modules)であり、実行時に外部から未知のコードを読み込むマーケットプレイスやサンドボックス機構ではありません。アプリケーション起動時に検出と検証が行われ、:optional プラグインはサイト全体の有効化リストに従って次回のプロセス起動時に有効化されます。一方、activation: :always を宣言したプラグインはビルドに含まれている限り常にアクティブになります。
発見済みとアクティブの 2 段階
実行時のプラグインには、次の 2 つの段階があります。
- 発見済み(Discovered) — リリースにコンパイルされ、起動時の検証を通過したすべてのプラグインモジュールです。運用者は Site Admin Console 上でカタログ全体を確認できます。
- アクティブ(Active) —
activation/0が:alwaysであるプラグイン、またはactivation/0が:optionalかつplugins.enabled_idsに含まれているプラグインです(なお、初回セットアップsetup.completedが完了する前は、発見済みの全プラグインがアクティブとして扱われます)。AppConfigure定義の登録、サブシステムアダプターやドメインフックの公開、監視付き子プロセスの起動を行うのは、アクティブなプラグインだけです。
発見済みであっても非アクティブなプラグインは、管理カタログ上に表示され PostgreSQL 上の既存 AppConfigure 保存値も維持されますが、実行時の設定定義・アダプター・フック・プロセスとしては一切登録されません。
プラグイン契約
各プラグインモジュールは Ankole.Plugins.Plugin ビヘイビアを実装します。必須のコールバックは次の 1 つだけです。
plugin_id/0— 正規表現~r/\A[a-z][a-z0-9_-]*\z/に一致する一意な英小文字スラッグを返します。
それ以外のコールバックはすべて任意です。
activation/0—:optional | :alwaysを返します(既定値は:optional)。:optionalはplugins.enabled_idsの設定に従い、:alwaysはビルドに含まれる限り常時有効となって無効化リクエストを拒否します。display_name/0、description/0— 管理画面表示用のローカライズ済みテキストマップを返します。app_config_definitions/0、app_config_patterns/0— プラグインが追加するAnkole.AppConfigureキーおよびパターン定義を返します。adapter_declarations/0— プラグインを各サブシステム契約へ接続するためのアトムキー付き宣言リストを返します。ブラウザー設定フォーム向けのスキーマ定義にはAnkole.Plugins.ConfigFieldを使用します。hooks/0— 同期トランザクションフック[{hook_point, module}]のリストを返します。各モジュールは宣言されたフックポイント(:create_agent、:create_invitation、:enable_signal_binding)に対してAnkole.Plugins.Hook.before_commit_in_tx/2を実装し、{:error, reason}を返すことで呼び出し元のデータベーストランザクションをロールバックできます。children/0— プラグインランタイムのスーパーバイザー配下で起動するSupervisor.child_spec()のリストを返します。
起動時には Ankole.Plugins.Spec.from_module/1 がこれらを読み取って検証済みの Spec を組み立てます。構造上の不備、プラグイン ID の重複、またはサブシステム契約の検証エラーが見つかった場合、アプリケーションは該当モジュールを明示したうえで起動を停止します。
サブシステム契約とサイト拡張ポイント
Control Plane Plugins は 7 種類のサブシステムアダプター契約(Ankole.Plugins.Contracts および Ankole.Connectors.Registry)を宣言でき、起動時の validate に加えてアクティブ状態の反映(refresh)や無効化防止ガード(veto_disable)を組み合わせます。
signals.adapter—Ankole.Signals.Adaptersで検証されるメッセージング・イベントアダプターを宣言し、Signal Bindings および Conversations の配信で利用できるようにします。signals.webhook_handler—/webhooks/v1/:handler_id/:instance_id/:kindで受け付ける HTTP Webhook ハンドラーを宣言します(Ankole.Signals.WebhookHandlersが検証)。principals.identity_provider— エンタープライズ Identity Provider およびディレクトリ同期アダプターを宣言します(Ankole.IdentityProvidersが検証し、テナントの Identity Provider 設定が残っている間はveto_disableで無効化を拒否します)。ai_gateway.provider—Ankole.AIGateway.Providersで検証されるモデルプロバイダーアダプターを宣言し、refreshによってアクティブな宣言を AI Gateway に公開します。agent_workers.provider_kind— Agent Worker のインフラ種別(Ankole.AgentWorkers.ProviderKind)を宣言し、起動時に検証したうえでrefreshにより発見済み・アクティブな仕様を公開します。connectors.connector—Ankole.Connectorsが提供する統合プラットフォームコネクターを宣言し、共有アプリケーション認証情報(authConfigId)、個人 OAuth フロー、外部イベントトリガー、内部 MCP ツールキット(ToolSpec)を提供します。lark-adapter、github-adapter、linear-adapter、cloud-connectors-adapterが実装しており、後の 3 つはactivation: :alwaysを宣言しています。connectors.cloud_provider— Ankole Cloud サービスのアダプターを宣言します。Ankole.Connectors.CloudProviderが検証し、コネクターの検出、OAuth、ツール実行、イベントトリガーの照合に使用します。
さらにサイトビルド全体では、ファーストパーティ拡張向けにコンパイル時・サイトスコープの拡張ポイントも用意されています。
Ankole.Plugins.ConfigField— プラグインアダプターから Console や Pod の設定フォームへ、型付きフィールド定義を公開します。- ドメイントランザクションフック(
hooks/0) — 対象ドメインのトランザクションおよびロック順序の内側で、Ankole.Plugins.Hook.before_commit_in_tx/2を同期実行します。 - 外側 HTTP Plug — ビルド時に選択された外側ルーターが、
AnkoleWeb.runtime_forwardでコアルーターへリクエストを渡す前に、アドミッションチャレンジなどの Plug を実行します。 - デュアルスコープ拡張 JSON:API ルート — サイト Host と Pod Host 上の独立した
/api/v2/*スコープ配下に型付き拡張 JSON:API ルートをマウントし、Ankole.AuthZ.Authorizerで認可を行います。 - 型付き UI スロット(
entries.jsonのoverrides) — 公開 Web アプリ(PodAppSlots、ConsoleAppSlots、AuthAppSlots)をラップし、HTML シェルに埋め込まれたアクティブプラグイン一覧(ankole-active-plugins)および任意の OpenFeaturewhen条件にもとづいて遅延ロードコンポーネントを描画します。
なお、プロセスを再起動せずに動的に切り替える実行時フラグについては、プラグインの有効化機構ではなく OpenFeature(Ankole.Features)で管理します。
Cohort 監督ツリーと次回起動境界
初回セットアップ完了後の環境では、:optional プラグインは既定で無効(フェイルクローズ)となり、PostgreSQL 上のグローバル AppConfigure キー plugins.enabled_ids に含めることで明示的に有効化します。
plugins.enabled_ids を更新しても、実行中のプロセスやアダプター、設定定義がその場でホットスワップされるわけではなく、次回の Ankole プロセス起動時に向けて設定がステージングされます。なお、設定更新トランザクションの中で Ankole.Plugins.Contracts.veto_disable/2 が呼ばれるため、既存の永続データが依存しているプラグインを誤って無効化することはできません。
実行時には、Ankole.Plugins.Cohort が不変の起動時スナップショットを保持し、配下の Ankole.Plugins.Registry と Ankole.Plugins.Supervisor を :rest_for_one 戦略で監督します。
Ankole.Plugins.Registryは起動時に一度だけスナップショットを解決し、アクティブ宣言の検証、プラグイン由来AppConfigureキーの登録、各サブシステムのrefresh呼び出し、および:persistent_termへのスナップショット公開を行います。Ankole.Plugins.Supervisorはアクティブな各プラグインのchildren/0を起動します。- 万が一
Ankole.Plugins.Registryがクラッシュした場合、Ankole.Plugins.Cohortは起動時に確定した同じ不変スナップショットを使ってRegistryとSupervisorの両方を再起動します。そのため、起動後に設定値が変更されていても、障害復旧の途中でアクティブなプラグイン集合が変わってしまうことはありません。また、個別プラグインの子プロセスで起きた障害はAnkole.Plugins.Supervisor内に封じ込められます。
オペレーター API
サイト管理者は、次の 2 つの JSON:API ルートから Control Plane Plugins の状態確認と設定変更を行えます。
| メソッド | パス | 用途 |
|---|---|---|
GET |
/api/v2/site/control-plane-plugins |
発見済みプラグインの一覧と、activation・configured_enabled・active・restart_required の各状態を取得 |
PUT |
/api/v2/site/control-plane-plugins |
{ "data": { "id": string, "enabled": boolean } } を送り、次回プロセス起動時の :optional プラグインの有効/無効を設定 |
どちらのルートも、特権テナントの site_console:control_plane_plugins(read および update)権限によって保護されています。
責務の境界
Control Plane Plugins は control plane と同一の BEAM ノードおよび信頼ドメイン内で動作します。connectors.connector(Ankole.Connectors)を通じて公開される内部 MCP ツールキットを除き、Agent Computer Worker 側の Skill やワークスペーステンプレートはここには含まれず Meta Ankole(Agent Library)側で管理されます。control plane 側のアダプターと関連する Agent Plugin は、それぞれ独立した有効化状態を持ちます。
次のステップ
- プラグインが宣言するメッセージング・Webhook アダプターの詳細については、Signals を参照してください。
AppConfigureキーやフィーチャーフラグの運用については、AppConfigure および Console を参照してください。- サイト管理操作の認可モデルについては、Principal and AuthZ を参照してください。