拡張性
エコシステムの拡張性とコンパイラのガードレール
1. ユニバーサル WebAssembly (Wasm) インターフェース
エコシステム全体でアーキテクチャの対称性を確保するため、Aggrega はコンパイラパイプライン内のすべての Wasm ソケットに一様に適用される、標準化された実行契約を使用します。
あらゆるプラグインを呼び出すための YAML インターフェースは、意図的に選ばれた 2 つのキーワード function と with に基づいています。
function: Aggrega は Wasm ランタイム(Wazero エンジン上の Extism ツールキット)を組み込み、Wasm をメモリ上で直接実行するため、オペレーティングシステムのプロセスは起動されません。functionは Go ホストが呼び出すエクスポート、つまり Wasm モジュールから明示的にエクスポートされた関数を指定します。with: プラグイン自身の入力であり、Developer のvaluesや Release が満たすparametersとは区別されます。このキーワードは GitHub Actions の慣例(with:)に従います。プラグインが入力に対して JSON Schema を宣言している場合、ホストは実行前にそれに照らして入力を検証します。
Wasm Plugins の種類:
この共通の function と with のインターフェースは、コンパイラ内のすべてのプログラマブルなソケットをサポートします。
| Plugin の種類 | 実行される場所 | 目的 | 期待される出力 |
|---|---|---|---|
Provider (provider) | レンダリング(生成) | 最終的なインメモリ IR を、ターゲット形式(Helm、Terraform、Compose)向けの文字列化された物理ファイルに変換します。 | 文字列化されたファイルの配列。 |
FeatureRecipe パイプラインステップ (pipeline-step) | Recipe または FeatureRecipe のプラグインパイプライン | シークレットの取得やベース AST へのサイドカー注入を行う逐次ステップ。 | キー付きドキュメントセットに対する RFC 6902 の patches、および side_effects(新しいドキュメントまたはファイルの出力)、diagnostics、後続のステップが読み取れる outputs。ステップの入力には、そのキー付きドキュメントセットと、ステップのレンダリング済み with 入力が含まれます。 |
ガバナンス (governance) | アノテーション展開の前、トポロジー構築、静的解析、またはレンダーステージ | ビルドパイプラインのガバナンスの役割を担います。アノテーション展開の前には解決済みのコンポーネントにアノテーションを注入し、トポロジー構築時にはノードにコンプライアンスや環境のラベルを自動付与します(どちらもオペレーターがオプトインします)。静的解析時またはレンダーステージでは Loud Guardrail として動作し、グラフのエッジ、パス、ラベル、あるいはレンダリングされた成果物を、セキュリティ境界に照らして評価します。何を出力できるかを決めるのは、その種類ではなく、アタッチされた役割です。 | アノテーション展開の前には、アノテーションの注入。トポロジー構築時には、metadata.labels を対象とする JSONPatch の配列。静的解析時またはレンダーステージでは、halt、warn、info の重大度の判定(Rego ポリシーはそれらを deny、warn、audit のもとに収集します)。halt はビルドを停止します。 |
リンター (linter) | 帯域外 | 任意の FinOps チェックや衛生チェック(例: .infra からのクラウドコスト見積もり)、および公開時の規律。 | 警告文字列または致命的な停止。 |
CLI 拡張 (cli) | ランタイム(aggrega <command>) | 署名済みでサンドボックス化されたプラグインが提供する、そのまま追加できるトップレベルコマンド。ホスト側にコマンドごとの Go コードは一切不要です。 | ストリーミングされる標準出力と標準エラー、およびゲストの終了コード。 |
パーサー (parser) | 外部形式が読み込まれる場所で、必要に応じて | 外部ソーステキスト(HCL、TOML、YAML、JSON、コメント付き JSON)を正準 JSON ツリーに変換します。 | tree と diagnostics、および任意のソース spans。 |
インポーター (importer) | ビルドの外で、必要に応じて(aggrega import、エディタ、アシスタントの import ツール) | 外部のインフラストラクチャまたはエージェント定義のソース(Langflow、Flowise、n8n、MCP 設定、Compose アプリケーション、Dify アプリケーション、CrewAI プロジェクトで宣言されたエージェント、LangGraph アプリケーションの設定、Google ADK アプリケーションのエージェント設定、Agent Framework の宣言型エージェント)を Aggrega のドラフト作成ファイルに変換し、扱える形式を import:<format> ケイパビリティとして公開します。 | ドラフトの Aggregate / Component / Release エンティティ、または再利用するカタログ Components への参照、その背後にあるマッピングの判断、診断、および書き出すスキャフォールドファイル。 |
ホストランタイム: ケイパビリティを拒否するサンドボックス。 Aggrega は Wasm ホストを、Wazero エンジン上で動作する Extism ツールキットとして組み込んでいます。ホストバイナリはネイティブツールチェーンへの依存を持たない純粋な Go のままなので、aggrega はクリーンにクロスコンパイルできます。すべてのソケットは AOT 純粋性ファイアウォールの背後で実行されます。ホストは、ネットワーク、ファイルシステム、実時間クロック、環境、標準 I/O といったランタイムアクセスのケイパビリティをプラグインに一切付与しません。そのため、それらを使おうとする呼び出しは失敗し、ホストが提供していないホストサーフェスからインポートするプラグインは読み込み時に拒否されます。ネットワークに到達できず時計も読めないプラグインは、同じ入力から同じ出力が得られるというコンパイラの事前(ahead-of-time)保証を破ることができません。起動時にいくつかの無害なインポートを必要とする言語ランタイムは、それらのインポートのケイパビリティを拒否した構成に対して実行されます。ホストは観測可能な実時間クロックを固定し、実際のエントロピーを供給し、標準 I/O を破棄し、ファイルシステム、引数、環境へのアクセスを一切付与しません。そのため、プラグインはビルドごとに変化するホストのケイパビリティに到達できません。エントロピーは固定せず、意図的に実際のものにしています。固定すると、ゲスト言語ランタイムの内部ハッシュシードやマップの反復順序が安定し、出力が再現可能でないプラグインを、出力の差異として表面化させずに隠してしまうためです。結果がエントロピーに依存するプラグインは作成レベルの決定性の問題であり、この構成はそれを覆い隠すのではなく明らかにするように作られています。
ホストに対する作成: PDK。 プラグイン作成者は Wasm のメモリ ABI を手書きしません。Aggrega は Go、Rust、TypeScript の 3 言語で Plugin Development Kit を提供しています。これは各ソケットの型付き入出力を提示する薄いラッパーで、作成者は通常の関数を書くだけで済みます。上記の function / with インターフェースは、Aggregate や FeatureRecipe がプラグインを呼び出すために使うものであり、PDK はプラグイン作成者がそれに対してビルドするものです。
各ソケットが実行される場所。 すべてのソケットは同じホストを通じて実行されます。公開用リンターは aggrega lint のもとで、ガバナンスの役割、レンダープロバイダー、Recipe と FeatureRecipe のパイプラインステップは aggrega build の間に、パーサーは外部フォーマットが読み込まれる場所で、インポーターは aggrega import のもとで、CLI プラグインはトップレベルコマンドとして実行されます。ソケットごとの準備状況については 言語のステータス を参照してください。
どのプラグインが固定され、どのプラグインを環境が選ぶか。 Aggrega は、出荷する出力を変えるかどうかでプラグインを区別します。出力を形作るプラグイン(レンダープロバイダー、変換の役割でアタッチされたガバナンスプラグイン(label-transform、annotation-transform)、FeatureRecipe と Recipe のパイプラインステップ)は、aggrega pull を実行した時点でリリースのロックファイルに固定され、aggrega build と aggrega serve ではそのロックファイルだけからバイト単位で同一に再現されます。2 種類は固定されません。ビルドが毎回同じ場所から読み込むためです。コンパイラバイナリの内部から提供されるレンダープロバイダーと、Plugin エンティティが自身のカタログディレクトリのいずれかで記述されたプロバイダーまたはパイプラインステップです。適用される出力形成プラグインを変更するには、再度 pull します。pull の後にワークスペース設定を変更しても、次の pull まではビルドの出力は変わりません。ゲートプラグイン(ポリシーとリント)はビルドのバイトを変えずにビルドを判定するため、pull 時にキャッシュされますが(そのためビルドはオフラインでもそれらを実行できます。コンパイラバイナリが持つもの、または自身のカタログディレクトリで記述されたものは、代わりにそこから読み込まれます)、固定はされません。どのゲートを実行するかはビルド時に環境が選ぶため、開発では寛容・CI では厳格という使い分けは再 pull ではなく通常の設定上の選択であり、ゲートを切り替えても、合格したビルドが出力するものは決して変わりません。インポーターや CLI 拡張のように作成時の入力にのみ作用する Plugins は、ビルド出力を一切形作らず、固定されることもビルドのキャッシュ対象に含まれることもありません。
2. FeatureRecipe Plugin パイプライン
FeatureRecipes は、抽象的な運用上の意図(セキュリティプロキシのアタッチやサイドカーの注入など)を、バージョン管理された WebAssembly(Wasm)プラグインパイプラインに結び付けます。Ops は、具体的なプロバイダーターゲットにおいて Feature が必要とするものを宣言し、コンパイラは宣言されたパイプラインをフラットな IR グラフに対して実行します。
この結び付けは、エコシステムに 3 つの帰結をもたらします。
- 進化の分離。 インフラストラクチャの語彙は、Aggrega コンパイラのコアリリースを必要とせず、外部の Wasm プラグインを通じて拡大します。新しいプロバイダー、新しいサイドカー、新しいセキュリティ統合は、安定した Wasm ABI に対する独立した Wasm バイナリとして提供されます。
- セマンティックバージョニング。 FeatureRecipes はバージョンで Wasm プラグインを参照します。完全一致(
:1.0.0)か、キャレット範囲(:^1.0.0、それと互換性のある最上位のバージョン)です。キャレット範囲を使うと、Ops はメジャーバージョンを固定しつつ、aggrega pull --upgradeでロックファイルを再解決するたびにそのマイナーリリースとパッチリリースを取り込みます。 - 複雑さのオフロード。 ベンダー固有の CRD 生成や複雑なレンダリング(ベンダー固有のポリシーオブジェクト、プロバイダーネイティブのルーティングリソース)は、コンポーネント定義内のスキーマ宣言やテンプレートロジックに織り込むのではなく、フラットな IR グラフ上で動作する純粋な Wasm プラグインに置かれます。
パイプラインの連鎖 — プラグイン間での関心の分離。 FeatureRecipe パイプラインは複数の Wasm プラグインを順に連鎖させることができ、各プラグインはコンパイラから同じ IR ノードコンテキストを受け取ります。標準的なパターンでは責務を分割し、1 つのプラグインがフィーチャーのセマンティックな意図と、特定のターゲット環境における物理的なトラフィック傍受の仕組みの両方を担わないようにします。
典型的な 2 プラグインの連鎖は次のとおりです。
- 構成プラグインは、フィーチャーのセマンティックなルール(セキュリティポリシールール、監査パターン、レート制限のしきい値)を出力します。フィーチャーの意図は理解しますが、ターゲット環境のトラフィック傍受ファブリックは理解しません。
- ルーティングプラグインは、それらのルールを運ぶ物理的なメッシュ構成(ゲートウェイ CRD、サイドカー注入パッチ、ファイアウォールルール)を出力します。ターゲット環境のファブリックは理解しますが、フィーチャーのセマンティックな意図は理解しません。
両方のプラグインはコンパイラから同じ IR ノードコンテキストを順に受け取るため、互いに直接結合することなくきれいに組み合わさります。コンパイラがパイプラインをオーケストレーションし、プラグインがドメイン知識を担います。
3. トラフィック傍受: HTTPRoute ターゲット
Aggrega の拡張性モデルは、メッシュレベルのトラフィック傍受のためのプロバイダー横断的な成果物として、Kubernetes Gateway API の HTTPRoute 標準をターゲットとします。標準ライブラリは core/http-route Feature を通じて HTTPRoute オブジェクトを出力し、その helm FeatureRecipe はアタッチされたコンポーネントごとに 1 つのルートをレンダリングします。Gateway API を利用するターゲット環境は HTTPRoute をそれぞれのネイティブファブリックに変換します。
4. Plugin の自律性: ラベルの解決
Wasm プラグインが IR グラフから物理リソースを生成する際、SRE は稼働中の Kubernetes Pod やクラウドリソースを Aggregate における開発者のセマンティックな意図までさかのぼって追跡する必要があります。Aggrega の拡張性モデルは、その変換を完全に Wasm プラグイン作成者の管理下に置きます。
コンパイラは IR グラフの labels 辞書全体を解釈せずに Wasm サンドボックスへ渡します。そこからのマッピングロジックはプラグイン作成者(Platform Ops)が決定します。すべてのラベルをそのまま渡す、特定のドメインプレフィックス(*.aggrega.ai/*)で絞り込む、あるいはグラフのラベルをプロバイダーネイティブのタグ付けスキーマに直接マッピングする(IR ラベルを AWS の tags、Kubernetes の annotations、またはクラウド固有のメタデータ機構に変換する)といった方法があります。コンパイラは、生成された成果物にどのようにタグを付けるかについて一切制限を課しません。
この自律性により、ドメイン固有の知見(どのラベルがオブザーバビリティにとって重要か、どれがネイティブのタグ付け慣例に対応するか、どれがプラットフォーム内部のものか)は Wasm プラグイン層にとどまり、そこでエコシステムは Go コンパイラのリリースサイクルとは独立して進化します。
5. CLI 拡張: ランタイムコマンド
上記のソケットはビルドの内部で動作します。コンパイラは Aggregate を解析、変更、検証、レンダリングする過程でそれらをディスパッチします。CLI 拡張ソケットは種類が異なります。オペレーターが aggrega <command> を入力したときに、ターミナルで、あらゆるビルドの外側で動作します。これは、コアのリリースなしに aggrega コマンドの表面そのものを拡張する仕組みです。
CLI 拡張とは何か。 CLI 拡張とは、署名されサンドボックス化された Wasm プラグインが提供する、ドロップイン形式の aggrega <command> です。レンダリングソケットと同じく、ゲストが所有するドロップインの立場をとります。ドメインロジックはすべてゲスト内にあり、Go ホストはコマンドごとのコードを一切提供しません。新しいトップレベルコマンドを追加するのに必要なのは、.wasm バイナリ、pluginType: cli を宣言する 1 つの Plugin エンティティ(Plugin を参照)、そして明示的な aggrega plugin add cli の 3 つだけです。ホストはインストールされたプラグインの自己報告からコマンドを検出します。バイナリにコンパイルされるコマンドはありません。
ランタイムソケットがビルドソケットにできないことをできる理由。 コンパイル時のソケットはビルドの最中に動作するため、ケイパビリティを拒否された決定的な状態に保たれます。Aggrega は事前(ahead-of-time)コンパイラであり、同じ入力は常に同じ出力を生成しなければなりません(アーキテクチャ上の不変条件を参照)。そのため、レンダープラグインやポリシープラグインはネットワークへのアクセス、時計の読み取り、ターミナルへのストリーミングができません。実行ごとに変わるものはすべて、その保証を損なうためです。CLI 拡張は、その境界の後でかつ外側で動作し、決定的なパイプラインではなくプロンプトの前にいる人間によって駆動されます。まさにそれゆえに、CLI プラグインは実行中に標準出力と標準エラーをストリーミングし、プロセスの終了コードを返すことができます。それらの効果がバイト単位の安定性を脅かしうるビルド成果物は存在しないからです。
インストール、実行、検出。 aggrega plugin add cli <query> は、設定されたレジストリから一致する cli プラグインを検索し、レジストリのトラストポリシーに照らして検証し、トップレベルコマンドとしてインストールします。その際、まずプラグインが宣言したケイパビリティを表示するため、オペレーターはコマンドが導入される前に、そのコマンドに何が許可されるかを正確に確認できます。インストール後は、aggrega <command> が組み込みコマンドと同様にそれを実行します。CLI プラグインは自身のコマンドとそのフラグを describe() の自己報告で宣言し、ホストは組み込みコマンドとまったく同じように各コマンドのフラグを aggrega help <command> に表示します。そのため、オペレーターはインストール済みコマンドの --flags を同じ方法で見つけられます。インストール可能なコマンドやカタログのコンテンツを探すには、aggrega search が設定されたレジストリのローカルインデックスを照会します。--kind plugin --plugin-type cli は結果をインストール可能な CLI プラグインに絞り込み、フィルターなしの検索はカタログのエンティティを対象とします。aggrega plugin list はすでにインストールされているものを表示します。コマンドごとのフラグと出力の形式は、それぞれのリファレンスページに記載されています。
ケイパビリティモデル。 CLI 拡張は、宣言もプロンプトもなしにすべてのコマンドが受け取る、固定のベースラインから始まります。
| ベースラインのケイパビリティ | 付与 |
|---|---|
| コマンドライン引数の入力 | 常時 |
| 標準出力と標準エラーのストリーミング | 常時 |
| プロセス終了コードの出力 | 常時 |
ベースラインを超えるものはすべてデフォルトで無効です。それ以上を必要とするプラグインは、追加の各ケイパビリティを明示的に宣言し、ホストはインストール時にそれを表示してオペレーターが確認した後にのみ付与します。ベースラインを超えて追加されるケイパビリティのクラス(環境、ファイルシステム、ネットワークへのアクセス、対話的な入力)は、同じ宣言と確認のゲートの背後で付与されるため、オペレーターが承認していない権限をコマンドが黙って獲得することはありません。
組み込みコマンドが常に優先されます。 インストールされたプラグインが組み込みコマンドを隠すことはできません。拒否リストに基づく予約名ガードが、組み込みコマンドと組み込み用に予約された一連の名前を保護し、名前の衝突はコアの動作を上書きすることを許さずにインストール時に拒否されます。オペレーターが依存するコマンドの表面は、その上に何がインストールされても安定したままです。
6. Parser Plugins: 外部フォーマットの読み取り
コンパイラは、自身が作成したものではないフォーマットで書かれたテキストを日常的に読む必要があります。HCL の Terraform モジュール、TOML の設定ファイル、YAML や JSON のマニフェストなどです。パーサーソケットは、コンパイラのコアに特定のフォーマットを教えることなく、その読み取り機能を提供します。パーサーはステートレスなプラグインで、外部ソースのテキストを構造化された JSON ツリーに変換します。HCL ファイルのバイト列を渡すと、パイプラインの残りの部分がすでに走査方法を知っている JSON オブジェクトとして同じ内容を返します。ネイティブに解析しないフォーマットを読む必要があるコンパイラの各部分は、解析済みツリーを要求し、そこから処理します。
フォーマットはケイパビリティであり、コンパイラの機能ではありません。 パーサーは扱うフォーマットを parse:hcl、parse:toml などのケイパビリティとして公開し、ホストは要求されたフォーマットに応じてパーサーを解決し、実行し、ツリーを返します。これはレンダープロバイダーや CLI プラグインと同じ、ドロップイン型でケイパビリティを公開するモデルです。コンパイラのコアは組み込みのフォーマット一覧を持たないため、フォーマットの追加は新しいパーサープラグインを提供することであり、コアのリリースではありません。HCL、TOML、YAML、JSON、コメント付き JSON のパーサーは、スターターセットとしてバイナリに同梱されています。別のフォーマットを必要とする企業は、それを公開するパーサープラグインを提供します。
フォーマットの選択は宣言的であり、推測されることはありません。 ホストはファイルの内容を調べてその種類を判断することはありません。宣言されたシグナルを固定の優先順位で用いてフォーマットを選びます。レンダープロバイダーは出力する各ファイルのフォーマットを宣言でき、ホストはその生成元が宣言したフォーマットを無条件に優先します。バイト列を書いたプロバイダーこそが、その読み方についての権威だからです。生成元がタグ付けしなかったファイルについては、固定のファイル拡張子マップがフォールバックとなります。.tf は HCL、.toml は TOML、.yaml は YAML、.json は JSON を選択します。宣言されたフォーマットまたは固定の拡張子で選ぶことで、解析は決定的かつ読み解きやすいものに保たれます。同じ入力は常に同じパーサーに振り分けられ、オペレーターはファイル内のバイト列を知らなくても、どのパーサーが実行されるかを読み取れます。内容の嗅ぎ分け(content-sniffing)は選択をペイロードに依存させることになるため、Aggrega はそれを行いません。
パーサーは純粋に構文的です。 出力は JSON ツリーと診断情報であり、任意で各ノードの元となったソース位置を含みます。パーサーは Aggrega としての意味を一切持ちません。テキストが構造的に何を述べているかを報告するだけで、それが Component や Recipe、その他のエンティティとして何を意味するかについては何も報告しません。解析済みツリーを Aggrega のエンティティに変換することは別の関心事であり、別の場所にあります。パーサーの唯一の仕事は、構文から JSON への忠実な変換です。読み取りの方向も同じ考え方で一方向です。パーサーはフォーマットをツリーに読み込みますが、フォーマットを書き戻すことはしません。
利用例: Terraform HCL に対するポリシー。 ビルドが生成する Terraform を検査する必要があるレンダーステージのポリシーは、自ら HCL を学ぶことはありません。ホストがパーサーソケットを通じて HCL 成果物を解析し、ポリシープラグインがすでに読める JSON ツリーを渡すため、ポリシーは他のすべてのソケットが受け取るのと同じ形の構造化データに基づいて判断します。外部フォーマットの新しい読み手も同じように構成されます。ホストにツリーを要求し、JSON で処理するのです。そのため、コンパイラがフォーマットを理解する能力は、コアを拡大するのではなくパーサープラグインを追加することで拡張されます。
7. Importer Plugins: 外部ソースからのオーサリングファイルの下書き作成
チームが白紙の状態から始めることはまれです。エージェントのアーキテクチャは、多くの場合すでにどこか別の場所に存在しています。Langflow や Flowise のフロー、n8n のワークフロー、Dify のアプリケーション、クライアントに設定された MCP サーバー、Compose アプリケーション、フレームワークの設定が宣言するエージェントなどです。インポーターソケットは、そうした外部ソースを Aggrega のオーサリングの出発点に変えます。ソースを読み取り、最初のドラフトとなる Aggregate と Component のエンティティを、また MCP の設定、Compose アプリケーション、フレームワークの宣言された設定からはドラフトの Release を生成し、作成者がレビューして仕上げられるようにします。これにより、チームは既存の資産を手作業で書き直すことなく Aggrega に引き継げます。インポーターは意味をマッピングします。ソースのノードが何であるかを読み取り、それを表す Aggrega のエンティティを提案するか、ドラフトされたプラットフォームが保持するフローの中にそのまま残します。コンパイラは、どのプラグインが生成するものにも依存しないのとまったく同じように、出力されたエンティティを不透明なまま受け渡します。
フォーマットはコンパイラの機能ではなくケイパビリティです。 インポーターは、扱うフォーマットをケイパビリティとして公開します(import:langflow、import:flowise、import:n8n、import:mcp、import:compose、import:dify、import:crewai、import:langgraph、import:google-adk、import:agent-framework など)。ホストは要求されたフォーマットに基づいてインポーターを解決し、実行し、ドラフトされたエンティティを受け取ります。これは、パーサーソケットが parse:<format> で採用しているのと同じ、ドロップイン型でケイパビリティを公開するモデルです。コンパイラのコアはインポート可能なフォーマットの組み込みリストを持たないため、新しいフォーマットへの対応は、それを公開するインポータープラグインを出荷することであり、コアのリリースは不要です。
インポーターはパーサーソケットを通じて読み取り、再パースはしません。 インポーターはソースの構造化された形を必要としますが、エコシステムがすでにパースしているフォーマットの読み取りを再実装することはありません。ツリーが必要になると、パイプラインの他の部分が使うのと同じホスト仲介のパースケイパビリティを通じて、対応するパーサー(ワークスペースのカタログがソースの構文に対して提供するもの、カタログが何も提供しない場合はコンパイラ自身が持つもの)の実行をホストに依頼し、返ってきた JSON ツリーをもとに処理します。読み取り(構文からツリーへ)はパーサーの役割のままであり、マッピング(ツリーから Aggrega のエンティティへ)はインポーターの役割です。2 つのソケットは互いに重複することなく組み合わさります。インポーターはソースに対するマッピングの知見を加え、バイトの処理は既存のパーサーに委ねます。
フォーマットは推測されず、インポーターが宣言する内容から認識されます。 インポートではソースのフォーマットを明示的に指定できます。指定がない場合、フォーマットは各インポーターが自己申告で宣言し、その Plugin エンティティが記録するシグネチャから認識されます。シグネチャには、ソースを読み取る構文、シグネチャが適用されるファイル名、パース済みツリーが持つべき、または持ってはならないパスが含まれます。ホスト自身はどのフォーマットも知りません。シグネチャが指定する各構文について、ワークスペースのカタログが提供するパーサー(カタログが何も提供しない場合はコンパイラ自身のもの)でソースをパースし、返ってきたツリーに対して宣言された述語を評価し、シグネチャが一致した唯一のインポーターのフォーマットとしてソースを読み取ります。パーサーソケットでは固定のファイル拡張子マップが担う役割を、宣言されたシグネチャが担います。インポートが読み取るフォーマットは拡張子を共有しうるためです。Langflow のエクスポート、Flowise のエクスポート、n8n のワークフローはいずれも JSON ファイルです。どのシグネチャにも一致しないソースは拒否され、フォーマットの指定を求めるとともに、インポーターが公開するフォーマットを示します。ディレクトリの場合は、そのファイルのいずれか 1 つを単独で指定するか、ファイルパターンを宣言するインポーターのフォーマットを指定するよう求め、それらのフォーマットだけを示します。複数のフォーマットのシグネチャに一致するソースも拒否され、それらのフォーマットが示されます。認識はソース以外を読まず、ネットワークにもアクセスしないため、新しいフォーマットの認識は新しいインポーターが同梱する宣言であり、ホストの変更は不要です。シグネチャの書き方の規則は The importer socket にあります。
ディレクトリは、そのインポーターが宣言するファイルを通じて読み取られます。 ソースはファイルまたはディレクトリです。ファイルはそのまま丸ごとインポーターに渡されます。ディレクトリは名前付きのソースとして読み取られます。対象は、インポーターのシグネチャのファイルパターンが選択するファイルだけで、それぞれディレクトリ内のパスで名前が付けられ、ソート順に並びます。ディレクトリ内のそれ以外のファイルは開かれず、読み取りをディレクトリの外へ導くリンクは、何かを読む前に拒否されます。ファイルパターンを宣言しないインポーターは 1 つのファイルを読み取り、ディレクトリを拒否します。また、インポーターのパターンが選択するファイルを含まないディレクトリも拒否されます。コンパイラの Langflow、Flowise、n8n、Dify、Agent Framework の各インポーターはパターンを宣言しないため、それぞれエクスポートされたフロー、ワークフロー、アプリケーションのファイル 1 つ、または宣言型エージェント 1 つを読み取ります。MCP インポーターは読み取る MCP クライアント設定のファイル名を宣言するため、プロジェクトのディレクトリはそこに含まれる設定を通じて読み取られます。Compose インポーターは Compose がデフォルトで読み取るファイル名を宣言するため、プロジェクトのディレクトリはその Compose ファイルと、Compose がその上にマージするオーバーライドファイルを通じて読み取られます。CrewAI インポーターは CrewAI プロジェクトがエージェントとタスクを宣言するファイル名を宣言するため、プロジェクトのディレクトリはそれらの宣言を通じて読み取られ、プログラムは決して読まれません。LangGraph インポーターは langgraph.json を宣言するため、アプリケーションのディレクトリはその設定だけを通じて読み取られ、コードと環境ファイルは読まれません。設定が指定する環境ファイルは、アタッチメントの with.sources が渡す場合にのみインポーターに届き、その場合も変数名だけが読まれます。Google ADK インポーターは root_agent.yaml を宣言するため、アプリケーションのディレクトリはルートエージェントの設定だけを通じて読み取られます。サブエージェントが指定する設定は、アタッチメントの with.sources が渡す場合にのみインポーターに届き、コードも環境ファイルも決して読まれません。
マッピングは決定的で、信頼度でスコア付けされ、自身のカタログと照らし合わせて評価されます。 ホストは、ワークスペース自身のカタログが保持する Components のビューをインポーターに渡します。このカタログはインポーターの選択元となったカタログ、つまりワークスペースのカタログフォルダ、またはそれが指定されていない場合はデフォルトレジストリが公開するカタログスナップショットであり、エンタープライズカタログの Components も標準ライブラリのものとまったく同様に扱われます。ビューには各 Component の名前、バージョン、ラベル、その values と provides が宣言するキー名、ソケットのセレクターが含まれ、値、デフォルト、シークレットは含まれません。ビューのためにそのスナップショット以外のものが取得されることはなく、順序も固定されているため、1 つのカタログからは 1 つのビューが得られます。Go PDK のインポーターパッケージで構築されたインポーター(コンパイラ自身の Langflow、Flowise、n8n、Compose の各インポーターを含む)は、ソースの各ノードをそれらの Components とだけ照らし合わせ、モデルを使わない決定的な信頼度モデルで評価し、その判断(評価した候補、割り当てたマッチ階層、下した選択)を、作成者が読んで修正できるレビュー可能なヒントとして記録します。カタログに追加された Component は、インポーターを再ビルドすることなく、次回のインポートで候補になります。デフォルトはヒントのみです。インポートが提案し、作成者が決定します。高信頼度のマッチは、新たにドラフトした本体の代わりに既存のカタログ component への参照として書き出せますが、それはオペレーターがオプトインした場合に限られます。その場合も常に、作成者が判断する明示的で元に戻せる提案であり、暗黙の書き換えには決してなりません。スコアリングはモデルも実行時の検索も伴わないため、同じソースを同じカタログに対してスコア付けすると、常に同じヒントが生成されます。
フローは、それを実行するプラットフォームとしてドラフトされます。 Langflow のフロー、Flowise の chatflow、n8n のワークフローはプラットフォーム上で実行されるため、インポートは既定でフローのノードではなくそのプラットフォームをドラフトします。標準ライブラリのプラットフォーム Component(core/ai-agent/langflow、core/ai-agent/flowise または core/ai-agent/n8n)のインスタンスを 1 つ作り、エクスポートされたままのフローをその flow_definition 値に保持させます。プラットフォームはこの値をデプロイ時に読み込みます。フローのうちプラットフォームのソケットが受け取る部分(標準ライブラリのプラットフォームでは、モデル、HTTP 経由で到達する MCP サーバーやその他のツール、ベクトルストア)は、それぞれ独立した Component となり、マッピングの判断に従って参照またはドラフトされ、プラットフォームの uses の下でそのソケットに接続されます。したがって、フローがモデル、ツール、ストアに対して行う各呼び出しは、Aggregate が宣言する接続になります。グラフを判定するガバナンスプラグインは、それを他のエッジと同じように認識します。また、attach_egress_allowlist 設定がプラットフォームにアタッチする標準ライブラリのイーグレス許可リストにより、プラットフォームは自身の接続が到達する先、自身の Pod、クラスタの DNS にのみ接続できます。形式が許す場合、ドラフトは保持されたフローに、各部分へその接続を通じて到達させるための記述を書き込みます。それ以外のノード(エージェント、チェーン、トリガー)は保持されたフローの中に残り、Component にはならず、その判断には比較対象となった候補が記録されます。Dify アプリケーションも同じ方法で、インストール全体がとる形でドラフトされます。標準ライブラリが組み立てる Dify インストール core/dify のエントリを 1 つ作り、その app_definition パラメータにアプリケーションを保持させ、インストールが自身の接続を配線します。インポーターのアタッチメントの layout 設定がドラフトを選択します。既定の platform、またはソースのすべてのノードをそれぞれ独立した Component としてドラフトし、フローの各エッジを uses 接続とし、フローを保持しない nodes のいずれかです。どのノードが部分になり、それぞれがどこに接続されるかは、フローを保持するプラットフォームで説明しています。
コードファーストのフレームワークは、プログラムではなく宣言された設定を通じて読み取られます。 CrewAI、LangGraph、Google ADK、Agent Framework は、アプリケーションの振る舞いをプログラムに保持し、そのエージェント、グラフ、モデルをプログラムの横にある設定で宣言します。これらのインポーターはその宣言のみ(CrewAI プロジェクトのエージェントファイルとタスクファイル、LangGraph アプリケーションの langgraph.json、Google ADK アプリケーションのエージェント設定、Agent Framework の宣言型エージェント)を読み取り、一度も開かないプログラムを囲む形で、そのフレームワーク用の標準ライブラリのエージェントをドラフトし、宣言が名指すもの、すなわちエージェントが求めるモデル(エージェントの model ソケットがそれを受け付ける場合)と、LangGraph のチェックポインターが状態を保持するデータストアに接続します。Agent Framework のエージェントが名指す MCP サーバーには、モデルのプロバイダーがホスト型ツールとして到達するため、ドラフトはそれをコメントに記し、何も接続しません。プログラムは Release が名指すイメージ内で実行されます。プログラムだけが述べていること(タスクのロジック、コードが定義するツール、コードが構築するエージェント)は、ドラフトのコメントと判断に記され、Component にはなりません。それをオーサリングファイルに取り込むのは作成者の作業であり、手作業で行うか、作成者に代わってオーサリングする AI アシスタントを aggrega mcp 経由で使って行います。これはリファレンスを読み、エンティティのスキャフォールドと検証を行います。
ソースがその部分の実行方法について記述する内容は、ドラフトの Release に入ります。 運用上の入力は Release が提供するものであるため、MCP、Compose、CrewAI、LangGraph、Google ADK、Agent Framework のインポーターは Aggregate の横に Release をドラフトし、その spec.aggregate がその Aggregate を指定します。Release はソースが記述する内容(サーバーのコマンドラインまたはアドレス、汎用サーバーのイメージとポート、モデルのエンドポイント)を保持し、各エントリの上のコメントには、ドラフトされた Component のどのキーも受け取らないソースの記述内容(サービスのボリュームや設定の環境など)を記載します。どのソースも記述しないもの(フレームワークのプログラムを実行するイメージ、接続が提示する認証情報、Release の metadata.environment と spec.manifest)は、該当する箇所のコメントで指定され、オペレーターが提供します。ビルドは、イメージ、環境、Manifest のうちまだ設定されていないものを指定して停止します。プラットフォームのドラフトは Release を書き出しません。プラットフォームのインスタンスの上のコメントが、Release が提供するもの(プラットフォーム自身の入力、たとえば実行するイメージやオーナーアカウント、配線された各 MCP サーバーのアドレス、および各接続が提示する認証情報)を指定します。
ソースが保持する認証情報の値は、削除が求められない限り記述どおりに保持されます。 インポーターは、ソース内で認証情報を保持しうるすべての値を特定し、それぞれを 1 つのクラスに分類します。フォーマットが認証情報としてマークするもの、MCP サーバーの設定のメンバー、またはフォーマットが認証情報ではないとマークしながらも認証情報を保持しうる入力(リクエストのヘッダーなど)です。デフォルトでは、どれも空にはされません。何かを保持する各値は記述どおりに保持され(プラットフォームが保持するフローまたはアプリケーション内、あるいはドラフトの Release 内)、credential-carried 警告の中で、値ではなくその位置(ノード、サーバー、サービスまたはエージェント、およびそのフィールド)と、それを空にする設定値によって示されます。empty_credentials 設定は削除をクラスごとに有効にします。marked はフォーマットが認証情報としてマークするものと MCP サーバーの設定のすべてのメンバーを空にし、all は認証情報ではないとマークされた入力も空にします。空にされた各値は credential-emptied で報告されます。フローが接続に到達するためにドラフトが書き込む内容は配線であり、設定にかかわらず書き込まれます。また、ドラフト内の接続は認証情報を保持しません。各接続が提示する認証情報は Release がアタッチします。環境ファイルのように、ソースが参照するだけのファイルは、そもそも読み取られる場合でも、変数名のためだけに読み取られます。ノード単位で作成されるドラフトは値を読み取りません。インポーターが特定する箇所の外にあるもの(カスタムコンポーネントのコードやプロンプト)は、フローが保持する認証情報の値で説明するとおり、ドラフトを共有する前に作成者が確認するものです。
コマンド、エディタ、アシスタントは同一のインポートを実行します。 aggrega import <file or directory> はターミナルからインポートを実行します。エディタはセッションの aggrega/import リクエストを通じて同じ操作を実行し、AI アシスタントは aggrega mcp の import ツールを通じて実行します。3 つとも、ワークスペースのカタログが保持するインポーターとコンパイラのコアインポーターの中から、同じ方法でインポーターを選択します。plugins.importer アタッチメントが名前を指定し、それがそのフォーマットを公開している場合はそのインポーターを、それ以外の場合はそのフォーマットを公開する唯一のインポーターの最も高いバージョンを選びます。1 つのフォーマットに対して 2 つの名前のインポーターがあり、どちらもアタッチされていない場合は、両方の名前を示してインポートが停止します。詳細は Which importer turns a source into drafts で説明しています。3 つとも、ドラフトとあわせてマッピングの判断を報告します。コマンドは、マッピングされたノードごとに 1 行を標準エラーに出力し、そのノードに選ばれた Component またはドラフト、それが参照されたかドラフトされたか、マッチの段階、そしてインポーターが候補を比較した場合は最良の候補のスコアを示します。エディタは同じ行を表示し、エディタセッションの結果とアシスタントの回答には各判断が完全な形で含まれます。そのため作成者は、どの面で実行した場合でも、ドラフトを開かずにインポートが推測した箇所を確認できます。--format は、自動認識の代わりにソースのフォーマットを明示的に指定します。たとえば langflow、flowise、n8n、mcp、compose、dify、crewai、langgraph、google-adk、agent-framework などです。コマンドは、インポートが生成したエンティティとスキャフォールドファイルを、ワークスペースのルート、または --output-dir が指定するディレクトリの下に配置します。--dry-run は書き込み以外のすべてを実行し、ドラフトされたファイルを内容として返して各ファイルの対象を示します。そのため作成者は、作業ツリーに何かをコミットする前にスキャフォールドを確認できます。
コアインポーター。 コンパイラが提供するコアインポーターは、次のフォーマットをそれぞれ 1 つのインポーターで読み込みます。
- Langflow — Langflow からエクスポートされたフローです。フローを保持する標準ライブラリの Langflow プラットフォームとしてドラフトされ、フローのうちソケットが受け取る各部分はそのソケットに接続されます。
- Flowise — Flowise からエクスポートされたチャットフローまたはエージェントフローです。それを保持する標準ライブラリの Flowise プラットフォームとしてドラフトされ、そのうちソケットが受け取る各部分はそのソケットに接続されます。
- n8n — n8n からエクスポートされたワークフローです。それを保持する標準ライブラリの n8n プラットフォームとしてドラフトされ、そのうちソケットが受け取る各部分はそのソケットに接続されます。
- Dify — Dify からエクスポートされたアプリケーションです。アプリケーションを保持する、標準ライブラリが組み立てる Dify インストールとしてドラフトされ、アプリケーションが指定するモデル、ツール、ナレッジベースは Dify 内で設定されたものとして報告されます。
- MCP — MCP クライアントの設定または MCP レジストリのサーバー記述です。各サーバーは標準ライブラリの MCP ツールのインスタンスとしてドラフトされ、各サーバーのコマンドライン、アドレス、またはイメージを保持する
Releaseが作成されます。 - Compose — インフラストラクチャのフォーマットです。Compose アプリケーションの各サービスは、そのイメージに一致するカタログの Component として(インポーターが保持するテーブルを通じて。このテーブルはビルド時に標準カタログの Compose Recipes と Components から生成されます)、またはそのイメージを実行する汎用サーバーとしてドラフトされます。各汎用サーバーのイメージとポート、およびコメントとして各サービスが宣言するポート、ボリューム、環境を保持する
Releaseが作成されます。 - CrewAI — CrewAI プロジェクトが設定ファイルで宣言するエージェントです。各エージェントは、ロール、ゴール、バックストーリーを保持し、指定されたモデルに接続された標準ライブラリの CrewAI エージェントとしてドラフトされます。プロジェクトのタスクとツールはそのプログラムのものとして報告され、プログラム自体は読み込まれません。また、それを実行するイメージの指定をオペレーターに委ねる
Releaseが作成されます。 - LangGraph — LangGraph アプリケーションの設定が宣言するグラフです。各グラフは、そのグラフのインポートパスを保持し、チェックポインターが状態を保持するデータストアに接続された標準ライブラリの LangGraph エージェントとしてドラフトされます。設定が宣言する環境をコメントで記述する
Releaseが作成され、グラフのコードは読み込まれません。 - Google ADK — Google ADK アプリケーションのエージェント設定が宣言するエージェントツリーです。各ツリーは標準ライブラリの ADK エージェントとしてドラフトされ、ADK がそのモデルへのリクエストを Gemini API に送る場合は、指定されたモデルに接続されます。それ以外の方法(たとえば LiteLLM のモデル文字列経由)で到達するモデルはコメントに記され、その接続は作成者に委ねられます。アプリケーションを実行するイメージの指定をオペレーターに委ねる
Releaseが作成され、アプリケーションのコードは読み込まれません。 - Agent Framework — Agent Framework の宣言的エージェントです。指定された OpenAI モデルに接続された標準ライブラリの Agent Framework エージェントとしてドラフトされます。指定された各 MCP サーバーは、モデルのプロバイダーがホスト型ツールとして到達するため、コメントに記されます。モデルのエンドポイントを保持し、各サーバーのアドレスをコメントに記した
Releaseが作成され、アプリケーションのコードは読み込まれません。
これらは他と同じインポータープラグインです。フォーマット固有のマッピングの知見はコアではなくこれらの中にあります。コンパイラのソースからビルドされ、コンパイラの各リリースとともにそのリリースのバージョンで公開されます。いずれもバイナリにはコンパイルされていません。バイナリは各インポーターの Plugin エンティティと、受け入れる唯一のモジュールのダイジェストを保持しているため、各インポーターはカタログエントリなしにすべてのワークスペースでそのフォーマットを処理します。マシンが保持していないインポーターを必要とする最初のインポートは、ワークスペースのデフォルトレジストリからそれを取得し、そのダイジェストに固定し、pull が取得したプラグインを検証するのと同じ方法(そのレジストリの信頼ポリシーに基づく署名と、使用するホスト関数)で検証して、ワークスペースのコンテンツキャッシュに保持します。以降のインポートはすべてそこから読み込み、そのためにネットワークに接続することはありません。インポートはインポーターを固定しません。インポーターのために他に書き込まれるものはなく(ロックファイルのエントリも、信頼済みプラグインの記録もありません)、pull がそれをキャッシュすることも、ビルドがそれを読み込むこともありません。検証に失敗したモジュールは拒否され、何も保持されません。モジュールを取得できない場合(ワークスペースがオフラインである、レジストリに到達できない、またはレジストリがそれを保持していない場合)、インポートは停止し、インポーター、そのバージョン、そしてそのモジュールをマシンに配置する方法を示します。選択はワークスペースに委ねられます。これらのフォーマットのいずれかに対してカタログが別の名前で保持するインポーターは、plugins.importer アタッチメントがそれを指定した場合に実行され、コアインポーターと同じ名前とバージョンを持つインポーターはその代わりに実行されます。
カタログの立ち上げと拡充
カタログをゼロから構築する必要はありません。新しい環境向けに Recipes とプラグインを用意する作業の大半は、すべてのバイナリを手で書くことではなく、 スキャフォールディングと再利用です。
外部ソースをドラフトのオーサリングファイルへインポートする。 aggrega import <file or directory> は、宣言的なエージェント定義ソース(Langflow または Flowise のフロー、n8n のワークフロー、MCP クライアントの設定または MCP レジストリのサーバー記述)、Compose アプリケーション、Dify アプリケーション、CrewAI プロジェクトが宣言するエージェント、LangGraph アプリケーションの設定が宣言するグラフ、Google ADK アプリケーションのエージェント設定が宣言するエージェント、または Agent Framework の宣言的エージェントを読み取り、最初のドラフトとなる Aggregate と Component の YAML を生成し、MCP、Compose、CrewAI、LangGraph、Google ADK または Agent Framework のソースからはドラフトの Release も生成します。これらは作成者がレビューして仕上げるためのものであり、チームは既存の資産を手で書き直すことなく引き継げます。フローの各ノード、および Compose アプリケーションの各サービスについて、インポートはワークスペース自身のカタログ(標準ライブラリのものだけでなくエンタープライズカタログのものも含む)の Components を、モデルを使わない決定的な信頼度モデルでスコア付けし、その判断(検討した候補、割り当てたティア、行った選択)をレビュー可能なヒントとして記録します。これはコマンド、エディタ、アシスタントのいずれもが報告します。信頼度の高い一致は、オペレーターがオプトインした場合にカタログ参照として書き込むことができますが、常に作成者が承認する、明示的で元に戻せる提案であり、暗黙の書き換えではありません。カタログに加わる Component はすべて、次回のインポートで検討される候補になります。フォーマット固有のマッピングの知見はインポータープラグインにあります。コンパイラ自身の Langflow、Flowise、n8n、MCP、Compose、Dify、CrewAI、LangGraph、Google ADK、Agent Framework の各インポーターは、あらゆるワークスペースでそれらのフォーマットを扱い、初回使用時に取得・検証されます。カタログは、あるフォーマットを提示するインポータープラグインを保持することでそのフォーマットを追加します。ディレクトリのソースは、そのインポーターが宣言するファイルパターンを通じて読み取られます。Langflow、Flowise、n8n、Dify、Agent Framework の各インポーターはパターンを宣言せず、それぞれエクスポートされた 1 つのファイルまたは宣言的エージェントを読み取ります。一方、MCP インポーターはディレクトリが保持するクライアント設定を、Compose インポーターは Compose ファイルを Compose と同じ方法でマージして、CrewAI インポーターはプロジェクトの宣言を(プログラムは読まずに)、LangGraph インポーターはアプリケーションの設定を(コードや環境ファイルは読まずに。環境ファイルの名前は、アタッチメントがそのファイルを渡した場合にのみ読み取ります)、そして Google ADK インポーターはアプリケーションのルートエージェント設定を(コードや環境ファイルは読まずに。サブエージェントの設定はアタッチメントが渡した場合に読み取ります)読み取ります。この設定は、ADK 自身が実験的であると明記しているもので、そのエージェントはデフォルトで Gemini モデルを使用し、他のプロバイダーのモデルには ADK 独自のクラスを通じて名前で、または LiteLLM のモデル文字列を通じて接続します。
プラグイン作業の大半はテンプレートであり、コンパイル済みコードではない。 機能の多くは、静的なサイドカー、環境変数、ラベルを注入するだけで、条件ロジックを持たない単純な JSONPatch です。宣言的な JSONPatch テンプレートを with 入力として受け取るように一度だけ書かれた設定可能なパッチャープラグインが 1 つあれば、機能ごとに固有のコンパイル済みバイナリを用意せずに、このよくあるケースをカバーできます。作成者はテンプレートを書くだけで、CRD 形式のターゲットの多くでは valuesMapping テンプレート(多くの場合、MappingLibrary エントリ内の共有フラグメントを参照します)だけで十分です。専用に書かれた PDK プラグインは、本当に条件分岐が必要な残りの部分のためのものです。
確立されたツールを参照する。 新しいプラグインロジックを書く際、作成者は 確立されたオープンソースツールの、公開ドキュメントに記載された出力の形 (それらのツールが出力することが知られている CRD、パッチ、テンプレートの構造)を、 新しいプラグインが生成すべきターゲットの形の参考として参照できます。その際は 各プロジェクトのライセンスを尊重します。サイドカー注入 Webhook、上位レベルのコンストラクト ライブラリ、オペレーターの CRD ジェネレーター、トレイトやコンポジションのカタログはいずれも、 同等の FeatureRecipe やプラグインが出力すべきものによく対応する出力構造を公開しています。 目的は、よく理解された出力契約に合わせることであり、どのプロジェクトの実装も コピーすることではありません。