コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

コアインポーター

コンパイラのリポジトリは、ソース形式ごとに 1 つずつ、計 10 個の独自のインポータープラグインをビルドし、 コンパイラのリリースごとに公開します。

Plugin対象読み取る内容
importer/langflowimport:langflowLangflow からエクスポートされたフロー(JSON)
importer/flowiseimport:flowiseFlowise からエクスポートされた chatflow または agentflow(JSON)
importer/n8nimport:n8nn8n からエクスポートされたワークフロー(JSON)
importer/mcpimport:mcpMCP クライアントの設定(.mcp.json、claude_desktop_config.json、.vscode/mcp.json または .cursor/mcp.json)、または MCP レジストリのサーバー記述 server.json(JSON)
importer/composeimport:composeCompose アプリケーション(compose.yaml、docker-compose.yml とそれらのオーバーライドファイル)(YAML)
importer/difyimport:difyDify からその DSL でエクスポートされたアプリケーション(YAML)
importer/crewaiimport:crewaiCrewAI プロジェクトが宣言するエージェントとタスク。config/agents.yaml と config/tasks.yaml(YAML)、または crew.jsonc と agents/<name>.jsonc、あるいはその厳格な JSON 表記である crew.json と agents/<name>.json(コメント付き JSON)
importer/langgraphimport:langgraphLangGraph アプリケーションの設定 langgraph.json(JSON)、および設定が指定する環境ファイルについては、インポートに with.sources で渡された場合に変数名のみ
importer/google-adkimport:google-adkGoogle ADK で構築されたアプリケーションの Agent Config ファイルで宣言されたエージェント(root_agent.yaml とそのサブエージェントが指定する設定)(YAML)
importer/agent-frameworkimport:agent-frameworkMicrosoft Agent Framework の宣言型エージェント。任意の名前を持つ種類 Prompt のドキュメント(YAML)

それぞれはコンパイラ自身のソースからビルドされ、コンパイラのバージョンが刻印されます。そのため、 X.Y.Z のコンパイラとともにリリースされたインポーターはバージョン X.Y.Z を報告し、その Plugin エンティティにも それが記録されます。組み込みプラグインに列挙されたプラグインとは異なり、どれもバイナリに コンパイルされてはいません。バイナリはそれぞれの Plugin エンティティと、それに対して受け入れる唯一のモジュールの ダイジェストを保持しているため、各インポーターはカタログにエントリがなくても、すべてのワークスペースでその形式を扱います。

10 個すべてが Go キットのインポーターパッケージ github.com/aggrega-ai/aggrega-pdk/go/pkg/importer の上に構築されています。Langflow、Flowise、n8n の各インポーターでは、形式にかかわらずインポーターが行うこと(ワークスペースカタログの Components を各ノードに対してスコアリングすること、既存のものを参照するか新たに下書きするかを決めること、下書きをレイアウトすること、保持する認証情報の値を引き継ぐか、設定の指定に従い空で書き出すこと、下書きを書き出し、以下の設定を読み取ること)はすべてそのパッケージが担い、形式の読み取りと、フローが動作するプラットフォームの把握だけが各インポーター固有です。MCP インポーターはサーバーごとに 1 つの Component のインスタンスを下書きするため、スコアリングは行いません。読み取る設定の解釈、認証情報の値に関する判断、および下書きの命名と説明に用いる慣例はパッケージと共有しています。詳細は MCP インポーター で説明します。Compose インポーターは、照合した各サービスについてフローインポーターがノードを判断するのと同じように、同じパッケージを通じて判断し、下書きも同様にレンダリングし、残りは MCP インポーターと同様に共有します。詳細は Compose インポーター で説明します。Dify インポーターは、標準ライブラリが組み立てる Dify インストールを、アプリケーションを載せた形で、同じパッケージのプラットフォーム下書きを通じ、インストール全体であるプラットフォーム向けの形式で下書きします。詳細は Dify インポーター で説明します。CrewAI インポーターは、プロジェクトが宣言するエージェントごとに標準ライブラリの CrewAI エージェントのインスタンスを下書きし、指定されたモデルに接続し、残りは MCP インポーターと同様に共有します。詳細は CrewAI インポーター で説明します。LangGraph インポーターは、アプリケーションの設定が宣言するグラフごとに標準ライブラリの LangGraph エージェントのインスタンスを下書きし、チェックポインターが状態を保持するデータストアに接続し、残りは MCP インポーターと同様に共有します。詳細は LangGraph インポーター で説明します。Google ADK インポーターは、アプリケーションの設定が宣言するエージェントツリーごとに標準ライブラリの ADK エージェントのインスタンスを下書きし、ADK がリクエストを Gemini API に送る場合にはツリーが指定するモデルに接続し、残りは MCP インポーターと同様に共有します。詳細は Google ADK インポーター で説明します。Agent Framework インポーターは、宣言型エージェントごとに標準ライブラリの Agent Framework エージェントのインスタンスを下書きし、指定された OpenAI モデルに接続します(指定された各 MCP サーバーはコメントとして書き出されます。モデルの提供元がホスト型ツールとしてそのサーバーに到達するためです)。残りは MCP インポーターと同様に共有します。詳細は Agent Framework インポーター で説明します。インポーターソケットの仕組みと、それに渡されるものについては、インポーターソケットで説明します。

このページは、各インポーターが何を読み取り、何を下書きするかのリファレンスです。独自のプロジェクトをインポートして結果をビルドするには、インポート から始めてください。そこでは、形式ごとに、プロジェクトをソースからビルドまで順に説明しています。

インポートがコアインポーターを取得する方法

aggrega import、エディタセッションの aggrega/import メソッド、アシスタントの import ツールは、いずれも同じ方法でコアインポーターを取得します。マシンがすでにそのモジュールをワークスペースのコンテンツキャッシュに保持している場合、インポートはそこから読み込み、そのためにネットワークは使いません。保持していない場合は、それを必要とする最初のインポートが、ワークスペースのデフォルトレジストリからコンパイラのバージョンでモジュールを取得し、次のことを行います。

  • バイナリが持つダイジェストにモジュールを照合し、コンパイラの Release が公開したモジュールだけが 実行されるようにします。
  • pull が取得したプラグインを検証するのと同じように検証します。すなわち、そのレジストリのトラストポリシーのもとでの署名と、 使用するホスト関数を、その Plugin エンティティが記録するものと照合します。
  • ワークスペースのコンテンツキャッシュに保持します。そのために書き込まれるのはこれだけです。インポートはどのインポーターも固定しないため、ロックファイルも、信頼済みプラグインの記録も書き込まれません。

以降のインポートはすべてコンテンツキャッシュからモジュールを読み込みます。検証に通らないモジュールは拒否され、何も保持されません。どのワークスペースにも属さないフォルダには保持先となるコンテンツキャッシュがないため、そこでは取得が拒否され、そのフォルダ名と、ワークスペースを指定する方法またはそのフォルダをワークスペースにする方法が示されます。モジュールが、カタログフォルダ内の同名で別バージョンの Plugin エンティティの隣から読み込まれることはありません。そのモジュールは別のエンティティに属するものだからです。

モジュールを取得できない場合、インポートは A plugin’s .wasm is not on this machine(プラグインの .wasm ファイルがこのマシン上にありません) で停止し、インポーターとそのバージョンを示したうえで、そのモジュールをマシン上に配置する方法を示します。

  • ネットワークが利用できる状態でインポートを一度実行します。ワークスペースがオフラインである場合や、レジストリに 到達できなかった場合に該当します。その実行でモジュールが取得され、以降の実行はすべてオフラインで行えます。
  • そのインポーターのそのバージョンの Plugin エンティティの隣に、カタログフォルダ内でモジュールを配置します。ファイル名はメッセージが示すものを使います。Langflow インポーターであれば importer--langflow.wasm です。コアインポーターと同じ名前とバージョンのカタログエンティティは、その代わりに実行され、モジュールはその隣から読み込まれます。隣にモジュールがないそのようなエンティティは代わりに実行されず、コアインポーターは上記のとおり取得されます。レジストリがモジュールを保持していない場合や、ワークスペースがデフォルトレジストリを指定していない場合は、メッセージが示す対処法はこれだけです。

独自のインポーターと並んでどれが実行されるか

コアインポーターは、ワークスペースのカタログが保持するインポーターと並ぶ候補であり、すべてのインポーターの選択に適用される規則に従います。その規則は Which importer turns a source into drafts(どのインポーターがソースをドラフトに変換するか) で説明されています。

  • 同じ名前の中では、最も高いバージョン、または plugins.importer エントリが指定するバージョンが実行されます。
  • カタログが langflow、flowise、n8n、mcp、compose、dify、crewai、langgraph、google-adk、agent-framework のいずれかについて別の名前のインポーターを保持している場合、2 つのインポーターがその形式をアドバタイズすることになり、どちらもアタッチしないインポートは両方の名前を示して A parse or import format is advertised by more than one plugin(パースまたはインポートの形式が複数のプラグインによってアドバタイズされています) で拒否されます。 使用したいほうを指定する plugins.importer エントリで解決します。
  • カタログがコアインポーターと同じ名前とバージョンで保持し、そのエンティティの隣にモジュールがあるインポーターが実行され、そこから読み込まれます。
  • コアインポーターの名前を持ち、カタログフォルダ内で隣にモジュールがない Plugin エンティティ — たとえば、あるリリースが公開したインポーターを記録するカタログのチェックアウトにあるもの — は、モジュールが他のどこからも読み込まれないため、どのインポートも実行できないエンティティです。したがって実行の候補にはなりませんが、それが記録するシグネチャは引き続きソースの認識に関与します。コンパイラ自身のバージョンでは、その代わりにコアインポーターが実行されます。それ以外のバージョンでは、古くても新しくても候補から外され、実行できるインポーターの中から選択が行われます — ただし、plugins.importer エントリがまさにそのバージョンを指定している場合や、実行できるその名前のインポーターがどれも要求された形式を宣言していない場合(エンティティが、コンパイラ自身のインポーターが記録していない形式を記録している場合など)は除きます。その場合は上記の規則に従って候補のままとなり、それを選んだインポートは、モジュールを置くべきフォルダを示して停止します。

カタログ独自のインポーターのどれが選ばれても、そのモジュールはそれ自身のエンティティの隣から、それ自身のバージョンで読み込まれます。別のバージョンの同名エンティティの隣に置かれたモジュールは、そのエンティティに属します。

ソースの認識方法

--format でフォーマットを指定しないインポートは、各インポーターが宣言するシグネチャによって認識されます。

  • Langflow — JSON としてパースでき、data.nodes に配列を持つソース。
  • Flowise — JSON としてパースでき、nodes と edges に配列を持ち、 data.nodes には何も持たないソース。
  • n8n — JSON としてパースでき、nodes に配列を、 connections にオブジェクトを持ち、edges と data.nodes には何も持たないソース。
  • MCP — JSON としてパースでき、名前が .mcp.json、claude_desktop_config.json または .cursor/mcp.json で、mcpServers にオブジェクトを持つソース。Visual Studio Code が読むようにコメント付き JSON としてパースでき、 名前が .vscode/mcp.json で、servers にオブジェクトを持つソース。または、 任意の名前で JSON としてパースでき、$schema が https://static.modelcontextprotocol.io/schemas/ で始まるテキストであるソース、つまりレジストリのサーバー記述です。名前は インポートに渡されたパスの末尾と照合されるため、project/.vscode/mcp.json は認識されますが、 .vscode の内部から渡された mcp.json や、それ以外の名前のクライアントのファイルは、 --format mcp を指定してインポートします。
  • Compose — YAML としてパースでき、Compose がデフォルトで Compose ファイルまたはそのオーバーライド ファイルとして読む名前 — compose.yaml、compose.yml、docker-compose.yml、docker-compose.yaml、 compose.override.yml、compose.override.yaml、docker-compose.override.yml または docker-compose.override.yaml — を持ち、services にオブジェクトを持つソース。それ以外の 名前の Compose ファイルは、--format compose を指定してインポートします。
  • Dify — 任意の名前で YAML としてパースでき、kind にテキスト app を持ち、 app.mode と version に何らかの値を持つソース。Dify がエクスポートするすべてのアプリケーションがこれに該当します。
  • CrewAI — YAML としてパースできる config/agents.yaml または config/tasks.yaml という名前のソース、 コメント付き JSON としてパースでき agents にリストを持つ crew.jsonc または crew.json という名前のソース、 あるいはコメント付き JSON としてパースでき role に何らかの値を持つ agents/<name>.jsonc または agents/<name>.json という名前のソース。クラシックなプロジェクトはエージェントとタスクを作成者が選んだ名前でキー付けするため、 その 2 つのファイルは名前だけで判別されます。
  • LangGraph — JSON としてパースでき graphs にオブジェクトを持つ langgraph.json という名前のソース、 または任意の名前で JSON としてパースでき、graphs にオブジェクトを持ち、$schema が LangGraph が自身の設定用に公開するスキーマであるテキスト https://langgra.ph/schema.json であるソース。 別の名前でスキーマを指定しない設定は、--format langgraph を指定してインポートします。環境ファイルを指定する インポーターのシグネチャはないため、ディレクトリを認識しても環境ファイルは開かれません。
  • Google ADK — YAML としてパースできる root_agent.yaml という名前のソースで、LlmAgent の設定のように name と instruction に何らかの値を持つか、その他のエージェントの設定のように agent_class にテキストを、 name に何らかの値を持つもの。別の名前の設定は、 --format google-adk を指定してインポートします。サブエージェントの設定は任意の名前を取りうるため、それを指定するシグネチャはなく、 ディレクトリを認識しても root_agent.yaml 以外の YAML ファイルは開かれません。
  • Agent Framework — 任意の名前で YAML としてパースでき、kind にテキスト Prompt を、 model にオブジェクトを持つソース。モデルを指定する宣言的エージェントがこれに該当します。Agent Framework は アプリケーションが指定する任意のファイルから宣言的エージェントを読み込むため、シグネチャはファイル名を指定しません。 モデルを指定しない宣言的エージェント、または kind を別の大文字・小文字や Agent として記述したものは、 --format agent-framework を指定してインポートします。

2 つのシグネチャに一致するソースは両方のフォーマットを示して拒否され、--format でどちらかを指定するとインポートされます。Langflow、Flowise、n8n、LangGraph の各インポーターはソースを parse:json を提供するパーサーで読みます。MCP インポーターは、サーバーを servers の下に列挙する設定を parse:jsonc を提供するパーサーで、それ以外のソースを parse:json を提供するパーサーで読みます。Compose、Dify、Google ADK、Agent Framework の各インポーターは parse:yaml を提供するパーサーで読み、CrewAI インポーターはクラシックなプロジェクトのファイルを parse:yaml を提供するパーサーで、それ以外を parse:jsonc を提供するパーサーで読みます。いずれもワークスペースのカタログが提供するものがあればそれを、なければコンパイラ自身がその構文用に持つパーサーを使います(Embedded plugins を参照)。そのため、これらのいずれを通したインポートでもカタログにパーサーは不要で、そのために何も取得されません。カタログがパーサーを提供する場合はそれが使われ、コンパイラのパーサーは関与しません。Langflow、Flowise、n8n、Dify、Agent Framework の各インポーターはファイルパターンを宣言しないため、それぞれ 1 つのファイルを読み、これらを通したディレクトリのインポートは拒否されます。MCP インポーターは 4 つのクライアントファイル名を宣言するため、ディレクトリはそこに含まれるクライアント設定を通して読まれます。Compose インポーターは 8 つの Compose ファイル名を宣言するため、ディレクトリはそこに含まれる Compose ファイルを通して読まれます。CrewAI インポーターはプロジェクトの宣言の 6 つの名前を宣言するため、プロジェクトのディレクトリはその宣言を通してのみ読まれ、それ以外は読まれません。LangGraph インポーターは langgraph.json を宣言するため、アプリケーションのディレクトリはその設定のみを通して読まれ、コードも環境ファイルも読まれることはありません。そして Google ADK インポーターは root_agent.yaml を宣言するため、アプリケーションのディレクトリはそのルート設定のみを通して読まれ — サブエージェントが指定する設定は、アタッチメントの with.sources の下でのみインポーターに届きます — コードも環境ファイルも読まれることはありません。ファイルを指定しないシグネチャ — Langflow、Flowise、n8n の各インポーターのもの、レジストリのサーバー記述に対する MCP インポーターのもの、スキーマを指定する設定に対する LangGraph インポーターのもの、Dify インポーターのもの、Agent Framework インポーターのもの — は、単独でインポートされるすべてのファイルに適用されます。フォーマットを指定しないインポートは、どのインポーター向けのファイルであっても、それらと同じパーサーを通して、試しにそのファイルを JSON として、また YAML として読みます — コンパイラは両方を持つため、どちらについても何も取得されません。コメントや末尾のカンマを含むファイルは JSON としてパースできないため、JSON を読むシグネチャはそれを認識しません。CrewAI インポーターの crew.jsonc、agents/<name>.jsonc およびそれらの .json 表記に対するシグネチャと、MCP インポーターの .vscode/mcp.json に対するシグネチャは、コメント付き JSON を読みます。カタログがパーサーを提供しない場合は、コンパイラがその構文用に持つパーサーを通して読みます。

パーサーが拒否するソース — Langflow、Flowise、n8n、LangGraph の各インポーターでは JSON でないもの、MCP インポーターではコメント付き JSON でないもの、またはサーバーを servers の下に列挙していない場合は JSON でないもの、Compose、Dify、Agent Framework の各インポーターでは YAML でないもの、CrewAI インポーターでは YAML でない、またはコメント付き JSON でない宣言、 Google ADK インポーターでは YAML でない設定 — は、インポートを parse-failed で停止させ、そのメッセージにはパーサー自身の理由が含まれます。フォーマットを指定してもこれは変わりません。 インポーターはソースのツリーを要求し、パーサーの拒否がその答えとなるためです。

ドラフトの命名方法

どのインポーターも、ドラフトする Aggregate と、Release もドラフトする場合はその横の Release に、<target_namespace>/<name> という名前を付けます。最初の部分は target_namespace 設定で、別の値を設定しない限り imported です。<name> は次のうち空でない最初のものです:

  • ソースが自身に付けている名前。その形式が名前を宣言するフィールドから読み取ります:

    インポーター読み取る名前
    importer/langflowフローの name
    importer/flowiseなし:エクスポートは独自の名前を持ちません
    importer/n8nワークフローの name
    importer/mcpレジストリのサーバー記述の name。クライアントの構成は名前を持ちません
    importer/composeプロジェクトのトップレベルの name。Compose がファイルをマージするのと同様に、オーバーライドファイルの名前が、それがオーバーライドするファイルの名前の代わりに使われます
    importer/difyapp の下にあるアプリケーションの name
    importer/crewaicrew.jsonc または crew.json にあるクルーの name。config/agents.yaml と config/tasks.yaml は名前を持ちません。クラシックなプロジェクトはクルーの名前をプログラム内で付けるためです
    importer/langgraph構成が宣言するグラフの ID。構成は独自の名前を持たないためです
    importer/google-adkルートエージェントの name
    importer/agent-frameworkエージェントの name。displayName は読み取られません
  • インポートに渡されたディレクトリの名前全体 — my.project はピリオドを保持したまま my-project と書かれます — で、Compose がプロジェクトにそれを含むディレクトリの名前を付けるのと同じです。aggrega import . では、実行しているディレクトリの名前になります;

  • インポートに単独で渡されたファイルの名前(拡張子を除く);

  • flow。

複数のソース(複数の Compose プロジェクト、構成、エージェントツリー、サーバー、または複数のグラフを宣言する 1 つの構成)から作られたドラフトは、そのすべてが自身に名前を付けており、かつすべてが同じ表記である場合にのみその名前を使い、そうでなければ次の候補を使います。名前は小文字で書かれ、ASCII の英字と数字以外の文字の連続はそれぞれ 1 つのハイフンになり、両端のハイフンは削除されます。Basic Prompting は basic-prompting、SupportAgent は supportagent と書かれます。同じソースは、どのインポートでも同じように命名されます。インポートがターゲット用にドラフトする Manifest は Release の名前を使い、Release がドラフトされない場合は Aggregate の名前を使います。これは ターゲットが追加するもの で説明するとおりです。

Langflow インポーターが読み取るもの

  • フローのトップレベルの data オブジェクトの下にあるノードとエッジ、すなわち data.nodes と data.edges。
  • 各ノードについて、ノードの data.type からその型を、data.node.template のエントリのうち値が type を持つオブジェクトであるものからそのフィールドを読み取ります。 テンプレートのその他のエントリはフィールドではありません。
  • オブジェクトが password: true を持つフィールドは認証情報スロットとして、それ以外のすべての フィールドは値フィールドとしてドラフトされます。フィールドの名前は関与せず、ノードを Component としてドラフトする際にはどのフィールドの値も読み取りません。
  • キャンバスに貼り付けられたメモ、つまり型が noteNode のノードはインポートされず、インポートされないノードへのエッジは 破棄されます。
  • フローを運ぶプラットフォームをドラフトする際には、フローから次のものも読み取ります。トップレベルの id、 password: true とマークされた各フィールドの値、MCP Tools ノードの mcp_server フィールド(それが指定する MCP サーバーとそのサーバーの設定)、またはその代わりにサーバーを保持するフィールド、Langflow が認証情報ではないとマークしながら認証情報を保持し得る各入力( Credential values the flow holds(フローが保持する認証情報の値) に列挙されているもの)、ノードがモデルを指定するフィールドとそれが動作するモデルプロバイダー、そしてノードがパーツのアドレスとキーに到達するためのフィールド(これは書き換えられます)。 それぞれがどうなるかは What they draft(ドラフトされるもの) で説明しています。

Flowise インポーターが読み取るもの

  • フローのトップレベルにあるノードとエッジ、nodes と edges。
  • 各ノードについて、ノードの data.name からその型、data.inputParams のエントリのうち type が credential であるものからその name によって資格情報スロット、そして data.inputs のキーから値フィールドを読み取ります。値フィールドからは、data.inputAnchors が指定するもの(別のノードが接続される箇所で、両者の間のエッジがそれを記録します)と資格情報を除きます。
  • ノードを Component としてドラフトする際にはどのフィールドの値も読み取らず、資格情報の名前はそれが資格情報であるかどうかに関与しません。
  • キャンバスに貼られたメモ、つまり型が stickyNote のノードはインポートされず、インポートされないノードへのエッジは破棄されます。
  • チャットフローを運ぶプラットフォームをドラフトする際には、そこから次のものも読み取ります。UUID である場合のトップレベルの id、ノードが data.credential に保持する資格情報、その inputParams が型 password として宣言する各入力の値、ノードの入力のうちの FLOWISE_CREDENTIAL_ID、およびそれらの任意の深さにある設定オブジェクト内の credential または FLOWISE_CREDENTIAL_ID、ノードの mcpServerConfig 入力にあるサーバー設定、フローが保持する資格情報の値が列挙するとおり、Flowise が資格情報ではないと示しているものの資格情報を含みうる各入力、およびエージェントフローの設定が、選択するモデルやツールを指定するメンバー、ノードの modelName 入力、そして OpenAI ノードの Base Path、つまりその basepath 入力です。 それぞれがどうなるかはドラフトされるもので説明します。

n8n インポーターが読み取るもの

  • エクスポートの最上位にあるワークフローの nodes と connections。
  • 各ノードについて、ノードを識別する name(n8n の接続は、結ぶノードを名前で指定し、ワークフロー内のノード名は一意です)と、パッケージを含めて完全な形で書かれた type。たとえば @n8n/n8n-nodes-langchain.lmChatOpenAi や n8n-nodes-base.httpRequest です。名前のないノードは id で識別されます。
  • ワークフローが列挙する各接続は、種類にかかわらず、出ていくノードから入るノードへの 1 本のエッジです。main 接続はあるノードから次のノードへデータを運び、AI 接続 (ai_languageModel、ai_tool、ai_vectorStore、ai_embedding、ai_memory など)は、出ていくノードが表すモデル、ツール、ストア、またはメモリを入るノードに渡します。いずれの場合も、接続が入るノードは、接続が出ていくノードを消費します。
  • ノードの credentials が指定する各認証情報タイプと、n8n がパスワードとしてマークする各最上位パラメーターは、認証情報スロットとしてドラフトされます。ノードのその他の最上位パラメーターは値フィールドです。ノードを Component としてドラフトする際に、フィールドの値は読み取りません。
  • キャンバスに貼り付けられたメモ、つまり型が n8n-nodes-base.stickyNote のノードはインポートされず、インポートされないノードへの接続は破棄されます。
  • ワークフローを実行するプラットフォームをドラフトする際には、ワークフローから次のものも読み取ります。最上位の id、ノードが選択する各認証情報、n8n がパスワードとしてマークする各パラメーター、MCP クライアントノードが呼び出すアドレス、ワークフローが組み立てるリクエストとともにノードが送信するヘッダーとクエリパラメーター(フローが保持する認証情報の値が列挙するもの)、そしてモデルノードがモデルを指定するパラメーターです。それぞれがどうなるかは ドラフトされるもの で説明します。

ドラフトされる内容

各ノードは、インポーターソケットの説明どおり、ワークスペース自身のカタログの Components とのみ比較されます。また各インポーターは、その形式の一般的なノード型(チャットモデルと埋め込みモデル、検索、HTTP リクエスト、そして Langflow では core/ai-tool/mcp にマップされる MCP Tools ノード MCPTools)を標準ライブラリの Components にマップする短いテーブルを持っています。Langflow のテーブルはさらに、Language Model コンポーネント LanguageModelComponent、つまり Langflow のスターターフローが呼び出すチャットモデルを、Langflow プラットフォームのモデル接続が提供するモデルである core/ai-model/openai にマップします。このノードは provider フィールドが指すモデルプロバイダー(デフォルトでは OpenAI)で動作し、別のプロバイダーを指すノードは、どのノードがパーツになるかで説明するとおり、その接続に配線されることはありません。n8n インポーターのテーブルは、n8n のチャットモデルと埋め込みモデル、core/ai-tool/mcp へのその MCP クライアントツール、HTTP リクエストツール、SerpApi ツール、Qdrant、PGVector、Chroma、Milvus、Weaviate のベクトルストア、Postgres と Redis のチャットメモリーをマップします。n8n がワークフロー自体の中で実行するノード(エージェント、チェーン、トリガー、ワークフローが自身のプロセス内に保持するメモリー、コードツール)はワークフロー自身のものであり、どの行もそれをマップしません。このテーブルの行は、ワークスペースのカタログがその行の名前を持つ Component を保持している場合にのみ一致として数えられます。コマンドは、マップした各ノードについて、選んだもの、一致の階層、最良候補のスコアを示す行を 1 行ずつ報告し、独自の Component を与えないノードについては made no choice for <node id> (<node type>) という行を報告します。ドラフトされるのではなくカタログの Component を参照するノードは独自のファイルを持たず、ドラフトの Aggregate がその Component を名前で示します。

ドラフトの構成は layout 設定で決まります。デフォルトの platform は、フローを実行するプラットフォームを、エクスポートされたままのフローを保持する形でドラフトし、プラットフォームのソケットが受け入れるフローの各部分(標準ライブラリのプラットフォームでは、モデル、MCP サーバーまたは HTTP 経由で到達するその他のツール、およびベクトルストア)にのみ独自の Component を与えます。nodes はすべてのノードをそれぞれ独自の Component としてドラフトします。

フローを保持するプラットフォーム

デフォルトでは、インポートは次のものを書き出します。

  • aggregate.yaml:ドラフトの命名方法 で説明するとおりフローにちなんで名付けられた、ドラフトの Aggregate です。フローを実行するプラットフォームのインスタンスを 1 つ保持します(Langflow フローでは langflow キーの下に core/ai-agent/langflow、Flowise では flowise キーの下に core/ai-agent/flowise、n8n ワークフローでは n8n キーの下に core/ai-agent/n8n)。このインスタンスはその名前のカタログ Component を参照します。インスタンスは values.flow_definition にフローを保持し、その識別子の値(Langflow では flow_id、Flowise では chatflow_id、n8n では workflow_id)でフローを指定します。フローの各部分はその横に独自のエントリとして置かれ、インスタンスの uses の下でプラットフォームに配線されます。
  • release.yaml — 同じ名前のドラフトの Release で、その Aggregate を指定し、プラットフォームのエントリーと各パートのエントリーを持ち、プラットフォームのイメージを保持し、ドラフトが必要とするすべてのシークレットを参照によって付与します。詳細は ドラフトが Release に残すもの で説明しています。
  • 参照ではなくドラフトする各部分について、components/ の下に 1 ファイルずつ。ノードごとのレイアウトがドラフトされたノードを書き出すのと同じ形で書き出されます。

ターゲットが指定されると、インポートはそれらの横に manifest.yaml をドラフトします。詳細は ターゲットが追加するもの で説明しています。

部分ではないノードはすべて、プラットフォームが保持するフローの中に留まり、Component にはなりません。その判定は比較された候補を記録して何も選ばず、その理由は kept in the flow <platform> carries, with no Component of its own: に続けて、その理由(たとえば、その型を指定するマッピング行がなく、最も近い候補のスコアがこれだけにとどまったこと)を記します。ノード間のエッジはフローが保持し、ドラフトは独自のエッジを書きません。

Multiple Documents QnA.json としてエクスポートされた Flowise の Multiple Documents QnA チャットフローを、標準ライブラリの Flowise プラットフォームとそのモデルおよび検索ツールの Components を保持するカタログに対して、設定もターゲットも指定せずにインポートすると、次の Aggregate としてドラフトされます(フローの大部分はここでは省略し、... で示しています)。

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/multiple-documents-qna
version: 0.1.0
description: Draft Aggregate imported from a source in the flowise format.
spec:
components:
flowise:
type: core/ai-agent/flowise
# For the compose target only, uncomment the lines below, which declare owner_password on flowise: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# owner_password:
# type: core/secret-value
# values:
# key: OWNER_PASSWORD
values:
# chatflow_id is derived from the exported flow, which gives no identifier of its own.
chatflow_id: '96da3b80-86d0-5f23-b4e7-2573ea1f76ad'
flow_definition: |
{
"description": "Tool agent that can retrieve answers from multiple sources using relevant Retriever Tools",
...
"embeddings": "{{"{{"}}openAIEmbeddings_0.data.instance}}",
...
}
uses:
model:
chatopenai-0:
target: chatopenai-0
# For the compose target only, uncomment the lines below, which declare credential on chatopenai-0: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: OPENAI_API_KEY
# swap to core/ai-model/azure-openai (score 0.4000) by setting type: core/ai-model/azure-openai
chatopenai-0:
type: core/ai-model/openai
values:
model: |-
gpt-3.5-turbo

配線される部分はチャットモデルだけです。モデルソケットは単一の接続しか取らないため 2 つの埋め込みモデルはフローに留まり、プラットフォームのどのソケットも受け入れないため検索ツールもフローに留まります。インポートはそれぞれを報告します。

フローの識別子は、エクスポートが与えるもの(Langflow フローではトップレベルの id、Flowise チャットフローでは UUID である場合のトップレベルの id、n8n ワークフローではトップレベルの id)で、それが英字、数字、.、-、_ または : からなる 1~128 文字で、英字か数字で始まる場合に使われます。エクスポートが識別子を与えない場合、またはそれ以外の文字を含む場合、ドラフトは形式名と保持されるフローから導出した名前ベースの UUID を書き出すため、1 つのフローからは常に 1 つの識別子が得られます。値の上には、導出されたものであることを示すコメントが付きます。 Flowise のエディターからエクスポートされたチャットフローは id を持たないため、導出された識別子が与えられます。

ワークスペースのカタログにプラットフォームの名前を持つ Component がない場合でも、ドラフトはプラットフォームを名前で示しますが、どの部分もそれに配線しません。部分となるはずだった各ノードはフローに留まって報告され、インポートはカタログにそのような Component がないことを警告します。

どのノードが部分になり、それぞれどこに配線されるか

インポーターのマッピングテーブルの行または mapping_overrides のエントリがその型をマップする場合、あるいは最良候補が少なくとも中位の一致である場合、ノードはフローの部分になります。Langflow の MCP Tools ノードは、スコアに関係なく部分になります。呼び出す MCP サーバーを指定しており、そのサーバーが部分になるからです。部分は独自の Component となり、reuse_mode の決定どおりに参照またはドラフトされ、プラットフォームのソケットのうち(プラットフォームのカタログエントリがソケットを宣言する順序で)部分の Component がラベルセレクターを満たす最初のソケットに配線されます。ここでのラベルとは、参照する Component のラベル、またはドラフトする部分については、最良候補が少なくとも中位の一致である場合のその候補のラベルです。Component がどのソケットのセレクターも満たさない部分、またはラベルを読み取る Component を持たない部分はフローに留まり、インポートはそれを報告します。

これを次の規則が絞り込みます。

  • 別のプロバイダーを指す Langflow モデルはモデル接続を受け取りません。 LanguageModelComponent ノードや EmbeddingModel ノードは、provider フィールドが指すモデルプロバイダー、それが空の場合は model フィールドが選択するモデルのプロバイダーで動作します。プラットフォームはモデル接続を OpenAI 互換クライアント向けに届けるため、OpenAI 以外のプロバイダーを指すノードは、マッピング行やオーバーライドが何にマップしていても、model ソケットに配線されることはありません。そのノードは、その Component が満たす次のソケットに配線されるか、フローに残ります。フローに残る場合、その決定は何も選ばず、そのための Component もドラフトされません。インポートはそのノードを、動作するプロバイダーを示して報告します。プロバイダーを選択しないノード、グローバル変数を通じてプロバイダーを指定するノード、別のノードからモデルを取得するノードは、他のパーツと同様に配線されます。
  • 単一の接続を取るソケットは 1 つの部分が保持します。 すべてのプラットフォームで model ソケットは 1 つの接続を取り、プラットフォームの Recipes はそれを 1 つの OPENAI_BASE_URL と 1 つの OPENAI_API_KEY として届けます。複数の部分がそこに置かれる場合、Component が model.aggrega.ai/capability: generative を持つ最初の部分(どれも持たない場合は最初の部分)がそれを保持し、それ以外はすべてフローに留まり、接続を保持する部分と、ノードが書かれたとおりにフローがそこへどう到達するかとともに報告されます。
  • Langflow は、tools 接続を指定する MCP Tools ノードを通じてのみその接続に到達します。 プラットフォームは、tools 接続のアドレスを、mcp_server フィールドがその接続を指定する MCP Tools ノードのサーバー設定に書き込みます。そのため、テンプレートに mcp_server フィールドを持たないノードは、型が何であれ、マッピング行やオーバーライドが何にマップしていても、tools ソケットには決して配線されず、Component が満たす次のソケットに配線されるか、フローに留まって報告されます。サーバーを指定しない MCP Tools ノードはどのソケットにも配線されず、報告されます。サーバー設定が独自のサーバーを起動するもの(command を持つか、Stdio モードを設定するもの)も同様で、その報告では削除すべきものが示されます。tools 接続が応答しないサーバーを指定するノードがあると、プラットフォームのビルドが停止するためです。
  • MCP サーバーは、フローが与える名前で配線されます。 1 つのフロー内で 1 つのサーバーを指定するノードは、1 度だけドラフトされる 1 つの部分に、1 つの接続を通じて到達します。接続のエイリアスは、サーバー名が接続のエイリアスとして使える文字(英字、数字、ハイフン、アンダースコア)からなり、かつそのソケットの他の接続が同じ変数名(エイリアスを大文字にし、それ以外の文字をすべてアンダースコアにしたもの)で値を届けない場合、サーバー名になります。そうでない場合、接続には部分のキーから導出したエイリアスが与えられ、ドラフトが保持するフロー内でノードのサーバーはそのエイリアスに改名され、部分の判定にその旨が記されます。

配線された部分の判定には、プラットフォームのどのソケットにどの接続を通じて配線されたかが記され、見送られた各ソケットとその理由も示されます。

保持されたフローが各部分に到達する方法

形式が許す場合、プラットフォームが保持するフローは、接続された各パートにその接続を通じて到達し、ドラフトはそのために必要なものをフローに書き込みます。変数の名前、空にしたアドレス、または接続が供給するものの代わりにノードが送信するはずのものを空にしたもので、値は決して書き込みません。これは配線であり、認証情報の値の削除ではありません。そこに値が残っていると接続が届けるものを上書きしてしまうため、ドラフトは empty_credentials 設定の内容にかかわらずこれを書き込みます。

  • Langflow の MCP Tools ノード。 プラットフォームは、接続が届けるアドレスをノードのサーバー設定に書き込み、接続が認証情報を持つ場合は、それを保持する変数の名前をツールが公開するヘッダーの下に書き込みます。ドラフトは、エクスポートがそこに保持していたアドレスを空にして書き込むため、フローにはその複製が残らず、サーバーのアドレス(パートの infra.endpoint)は Release に委ねられます。Langflow はノード自身の headers フィールドをサーバー設定のヘッダーより優先して送信するため、ドラフトはそのフィールドの値全体を、種類を保ったまま空にして書き込みます。オブジェクトは {}、リストは []、テキストは空文字列です。値を空にしたヘッダーが残っていても送信されてしまう一方、空のオブジェクトやリストは何も上書きしないためです。

  • Langflow のモデルノードまたはベクトルストアノード。 プラットフォームは、モデル接続を OPENAI_BASE_URL と OPENAI_API_KEY として、ベクトルストア接続をそのエイリアスにちなんだ名前の変数として届けます。Langflow はこれらをグローバル変数を指すフィールドを通じて読み取ります。オブジェクトが load_from_db: true を持つフィールドは変数の名前を値として保持し、Langflow はその名前のグローバル変数を、保存されていない場合は同じ名前の環境変数を読み取ります。ドラフトは、次の各フィールドを変数の名前と load_from_db: true で書き込みます。

    • OpenAIModel ノードの openai_api_base を OPENAI_BASE_URL として、api_key を OPENAI_API_KEY として。
    • OpenAIEmbeddings ノードの openai_api_base を OPENAI_BASE_URL として、openai_api_key を OPENAI_API_KEY として。
    • LanguageModelComponent ノードの api_key を OPENAI_API_KEY として。
    • EmbeddingModel ノードの api_base を OPENAI_BASE_URL として、api_key を OPENAI_API_KEY として。
    • pgvector ノードの pg_server_url を AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING として。ここで <ALIAS> は、接続のエイリアスを大文字にし、英字と数字以外のすべての文字をアンダースコアにしたものです。

    LanguageModelComponent ノードや EmbeddingModel ノードは、複数のモデルプロバイダーのいずれか(provider フィールドが指すもの、それが空の場合は model フィールドが選択するモデルのプロバイダー)で動作し、そのプロバイダーにキーを渡します。プラットフォームはモデル接続を OpenAI 互換クライアント向けに届けるため、このようなノードは OpenAI で動作する場合にのみ変数付きで書き込まれます。別のプロバイダーで動作するノードは、上述のとおり配線されることはありません。何も選択しないノード、グローバル変数を通じてプロバイダーを指定するノード、別のノードからモデルを取得するノードは、いずれの変数も付けずに書き込まれるため、ドラフトが別のプロバイダーを接続のキーに向けることはありません。このようなノードのどのフィールドも API のアドレスを与えない場合(LanguageModelComponent ノードは OpenAI 向けのアドレスを持たず、EmbeddingModel ノードの api_base は欠けているか、変数を指せない場合は空のことがあります)、そのノードが動かす OpenAI クライアントは環境から OPENAI_BASE_URL を取得するため、ノードはそれでもプラットフォームが届けるアドレスに到達します。

    OpenAIEmbeddings ノードのクライアントは、default_headers をキーから組み立てるヘッダーより優先して送信し、default_query を呼び出すアドレスのクエリにマージします。そのため、ドラフトが配線するこのようなノードでは、MCP Tools ノードの headers と同様に、それぞれの値全体を種類を保ったまま空にして書き込みます。

    エクスポートがこれら両方のメンバーを持たずに書き込んだフィールドは、新たに書き直されません。その中の認証情報フィールドは、後述のとおり、書かれたまま保持されるか、設定が求める場合は空にして書き込まれます。そのフィールドがパートのアドレスを持つもので(LanguageModelComponent ノードや EmbeddingModel ノードの場合はアドレスを与えるもので)、かつそのようなノードが OpenAI で動作しない場合、またはノードがそれ以外の種類である場合、インポートはそのパートを、フローまたはそのコンポーネントの既定値が与えるアドレスで到達するものとして報告します。

  • Flowise の OpenAI ノード。 Flowise が chatOpenAI ノードや openAIEmbeddings ノードを動かす OpenAI クライアントは、ノードの Base Path が空で、認証情報を何も選択していない場合に、環境から OPENAI_BASE_URL と OPENAI_API_KEY を読み取ります。そのためドラフトは、エクスポートが保持する Base Path を空にして書き込み、ノードが data.credential で選択する認証情報も空にします。このクライアントはノードの既定ヘッダーである baseOptions を、キーから組み立てるヘッダーより優先して送信するため、ドラフトはその値全体を種類を保ったまま空にして書き込みます。それ以外の種類のモデルノードは、チャットフローまたはそのノード自身の既定値が与えるアドレスで到達するものとして報告されます。

  • Flowise のツールまたはベクトルストア。 チャットフローは、プラットフォームがこれらに届けるアドレス(AGGREGA_TOOL_<ALIAS>_URL または AGGREGA_VECTOR_STORE_<ALIAS>_URL)を、その名前の Runtime 変数を通じてのみ読み取りますが、起動時にそれを作成するものはありません。ドラフトはこれについて何も書き込まず、インポートはチャットフローにそれを読み取らせる手順を報告します。Flowise の Variables ページで Runtime 変数を作成し、ノード内で $vars.<name> として読み取ってください。

  • n8n のすべてのノード。 プラットフォームはモデル接続を OPENAI_BASE_URL と OPENAI_API_KEY として、ツール接続やベクトルストア接続を AGGREGA_TOOL_<ALIAS>_URL または AGGREGA_VECTOR_STORE_<ALIAS>_URL として届けます。一方、n8n のノードは、選択した保存済み認証情報が与えるアドレス、またはノード自身のパラメーターが保持するアドレスでモデル、ストア、サービスに到達し、ワークフローが環境変数を読み取るのは $env を読む式を通じてのみです。プラットフォームは、Aggregate が values.allow_env_access_in_nodes を true に設定しない限りこれを拒否します。ドラフトはこの値を既定値の false のままにします。これを設定すると、すべてのワークフローと、ワークフローを編集できるすべてのユーザーが、届けられた認証情報を含め、プラットフォームの環境のすべての変数を読み取れるようになるためです。そのためドラフトは接続についてワークフローに何も書き込まず、配線されたすべてのパートは接続以外の経路で到達するものとして報告されます。MCP クライアントノードは、ワークフローが保持するアドレス(エクスポートが書いたままのもの、または後述のとおり empty_credentials 設定が空にした場合はなし)でサーバーに到達し、サーバー自身のアドレス(パートの infra.endpoint)は Release に委ねられます。

フローが保持される場合、配線された各パートは、次のどちらに当たるかとともに報告されます。フローが接続を通じてパートに到達する場合は part-reads-connection、接続以外の経路(フローが保持するアドレス、またはそのコンポーネントの既定値が与えるアドレス)でパートに到達する場合は part-address-in-flow です。パートの決定にも同じ内容が記されます。

ドラフトがどのソケットにも配線しないノードでも、書かれたとおりの状態で、ドラフトが配線する接続によって到達されることがあります。自身のアドレスもキーも持たない OpenAI クライアントは、プラットフォームがモデル接続のために届ける OPENAI_BASE_URL と OPENAI_API_KEY を環境から読み取ります。そうなる場合、ドラフトはそのノードを配線済みのノードと同じように書き込むため、ノードが保持するものが接続の供給するものの代わりに送信されることはなく、part-reads-connection として報告します。

  • アドレスフィールドが、プラットフォームが届ける変数 OPENAI_BASE_URL をグローバル変数として読み取るよう指定している Langflow の OpenAIEmbeddings ノードで、パートがモデルソケットに配線されている場合:その default_headers と default_query。
  • Base Path が空で認証情報を何も選択していない Flowise の chatOpenAI ノードまたは openAIEmbeddings ノード、およびエージェントフローのノードが入力の中に保持するそのようなモデルの設定で、パートがモデルソケットに配線されている場合:その baseOptions。

その他のノードでは、これらの値は配線ではありません。次のセクションで説明するとおり、記述されたまま運ばれるか、設定が求める場合は空に書き換えられます。

フローが保持する資格情報の値

フローを運ぶ前に、インポートは資格情報を運びうるフロー内のすべての値を、以下に挙げる場所で特定します。各値は次の三種類のいずれかです。フォーマットが資格情報としてマークしているもの、フォーマットが MCP サーバーの設定を保持している場合のその設定のメンバー、そしてフォーマットが資格情報ではないとマークしているものの、それでも資格情報を運びうる入力(リクエストヘッダー、クエリパラメータ、コマンドラインとして記述されたリクエスト全体、資格情報の名前で資格情報を保持する入力)です。

デフォルトでは、インポートはこれらのいずれも空にしません。フローはエクスポートされたとおりに運ばれ、何かを保持する特定済みの値(空文字列でも null でもないもの)はそれぞれ credential-carried 警告で、そのノードとフィールドによって(ヘッダーやクエリパラメータはその名前によって)示され、値やその一部によって示されることは決してなく、その値を空にする empty_credentials 設定の値が併記されます。この設定によって削除が有効になります。marked は、フォーマットが資格情報としてマークしているものと MCP サーバーの設定のすべてのメンバーを空にします。all は、資格情報ではないとマークされた入力も空にします。空にした各値は credential-emptied で、そのノードとフィールドによって報告され、値によって報告されることはありません。すでに空の値や null はそのまま残され、報告されません。設定が受け付けない値はインポートを停止させ、何もドラフトされません。none として読まれることはありません。

1 つの変数参照だけからなる特定済みの値は、それ自体の値を保持しません。変数の名前そのもの、${NAME}(${workspaceFolder} や ${userHome} などの定義済み変数を含む)、または MCP クライアントが定義する形式である ${env:NAME} と ${input:id} がこれにあたります。設定が何であれ、フローがどのフォーマットであれ、MCP インポーターが記述するのと同様に、これは記述されたまま運ばれ、どの警告でも示されません。フォーマットがテキストとして保持する値の中の 1 つの参照であるメンバーも同様です。たとえば JSON テキストとして記述された Flowise の mcpServerConfig や、Flowise と n8n でテキスト内の JSON オブジェクトとして保持されるヘッダーやクエリパラメータです。空にされても、そのテキストはそのメンバーを記述されたまま保持します。

演算子の後にテキストを持つ参照は、そのテキストを保持し、それはキーである可能性があります。演算子の前にコロンがあるかどうかは問いません。デフォルト ${NAME:-value} または ${NAME-value}、代替 ${NAME:+value} または ${NAME+value}、メッセージ ${NAME:?message} または ${NAME?message}、代入 ${NAME:=value} または ${NAME=value} がこれにあたります。これは他の値と同様に特定されます。デフォルトでは運ばれて credential-carried 警告で示され、設定がその種類を求める場合は空にされます。${config:name} のような ${…} 内のその他のテキストや、--key=${NAME} のような参照の横にあるテキストも同様です。

ノードが接続に到達するようにドラフトが書き込むもの(運ばれたフローが各パーツに到達する方法で説明する、空にされたアドレス、変数の名前、空にされた選択済みの資格情報やデフォルトヘッダー)は配線です。これは設定が何であれ書き込まれ、ノードが接続に到達する方法とともに報告され、資格情報の値として報告されることはありません。以下のどの場所にも含まれないものは、このセクションの最後で述べるとおり、作成者が確認するものです。

フォーマットが資格情報としてマークしているもの — marked と all で空にされます。

  • Langflow — password: true とマークされた各テンプレートフィールドの値。グローバル変数の名前を保持するフィールドも含みますが、上記のとおりドラフトがそのフィールドにプラットフォームが提供する変数の名前を書き込む場合は除きます。
  • Flowise — ノードが data.credential に保持し、その資格情報パラメータが選択する資格情報、その inputParams が型 password として宣言する各入力の値、そしてノードの入力中の FLOWISE_CREDENTIAL_ID と、agentflow がモデルやツールの設定を保持するように、入力の任意の深さにある設定オブジェクト内の credential または FLOWISE_CREDENTIAL_ID。
  • n8n — ノードが選択する各保存済み資格情報の id(credentials.<type>.id)。n8n のエクスポートは資格情報を参照として保持し、その値は決して保持しません。参照の name は特定されません。n8n は別のインスタンスでワークフローをインポートする際、保持していない id の資格情報をその型と名前で解決します。古いエクスポートが名前だけで選択する資格情報は、資格情報を名指しするだけで何も保持しないため、特定されません。さらに、n8n が基本ノードの定義でパスワードとしてマークしている各パラメータの値(たとえば Crypto ノードの secret や、ユーザーを作成するノードの password)が、ノードのパラメータ中のどこにあっても特定されます。エージェントのツールとして使われるノードは、そのノード自体として読まれます。

MCP サーバーの設定 — marked と all で空にされます。

  • JSON テキストまたはオブジェクトとして記述された、Langflow MCP Tools ノードの mcp_server 設定と Flowise ノードの mcpServerConfig。各ヘッダー値(ヘッダーがオブジェクト、キーと値の行、まるごとマージされるオブジェクトのいずれであっても。その他の種類の項目は全体として特定されます)、各環境変数の値、サーバーのアドレス、コマンド、そしてすべての引数です。どちらのフォーマットもアドレス、コマンド、引数を資格情報としてマークしませんが、いずれもキーを運びうる(アドレスはユーザー部、パス、クエリに)ため、両フォーマットでこの三つも特定されます。空にされても、コマンドと各引数はそのメンバーを保持するため、独自のサーバーを起動する設定は引き続きそのように読まれます。Langflow MCP Tools ノードがツール接続に配線されている場合、そのアドレスは上記のとおり配線であり、資格情報の値として報告されることはありません。JSON オブジェクトとして読めないテキストとして記述された Flowise の設定は、内部の何も特定できないため、全体として特定されます。
  • mcp_server フィールドを持たない Langflow MCP Tools ノードは、代わりに独自のフィールドにサーバーを保持します。アドレスは sse_url、ヘッダーは headers_input、環境変数は env、引数を含むコマンドライン全体は command です。Langflow はこれらのいずれも資格情報としてマークしないため、各ヘッダー値、env の各エントリ、アドレス、コマンドラインが特定され、空にされてもそのフィールドとエントリは保持されます。env がリストの場合、変数の名前とその値が 1 つのテキストを共有するため、各エントリはその位置によって報告されます。このようなノードは MCP サーバーを名指ししないため、ツール接続に配線されることはありません。
  • ドラフトが配線しないノードにおける、Langflow MCP Tools ノード自体の headers フィールド(Langflow はこれを設定のヘッダーより優先してサーバーに送信します)。その値全体が、配線されたノードと同様に種類を保持したまま空にされ、headers として一度だけ報告されます。
  • Langflow が非推奨としている MCP Tools (SSE) と MCP Tools (stdio) コンポーネントは、それぞれ 1 つのフィールドにサーバーを保持します。MCPSse ノードはアドレスを url に、MCPStdio ノードは引数を含むコマンドライン全体を command に保持し、全体として特定されます。どちらも MCP サーバーを名指ししないため、どちらもツール接続に配線されません。
  • n8n の MCP クライアントノード(エージェントが呼び出す MCP Client Tool、MCP Client ノード、または n8n のレジストリが掲載するサーバーのクライアント)は、サーバーのアドレスを endpointUrl パラメータ(最初のバージョンでは sseEndpoint)に保持し、ヘッダーは選択する資格情報としてのみ保持します。アドレスは、配線の有無にかかわらず全体として特定されます。

フォーマットが資格情報ではないとマークしている入力 — all でのみ空にされます。

  • リクエストヘッダー — Langflow では、APIRequest、URLComponent、 CloudflareWorkersAIEmbeddings または ConfluentKafkaProducer ノードの headers と、 DoclingRemote ノードの api_headers。Flowise では、httpAgentflow、getApiChain、 postApiChain、openApiChain、apiLoader、openAPIToolkit または searXNG ノードの headers、Requests ツールの requestsGetHeaders、requestsPostHeaders、requestsPutHeaders および requestsDeleteHeaders、 そして azureChatOpenAI、azureOpenAIEmbeddings、chatCerebras、chatOpenAICustom、 openAIEmbeddingsCustom、chatOpenRouter、chatSambanova または openAI ノードの baseOptions(モデルのクライアントが送信するデフォルトヘッダー)。n8n では、 n8n-nodes-base.httpRequest ノードの headerParameters、jsonHeaders、headerParametersUi および headerParametersJson(現行バージョンは最初の 2 つを、以前のバージョンは残りの 2 つを保持します)と、エージェントのツールとして使われる同じノードのもの、 @n8n/n8n-nodes-langchain.toolHttpRequest ノードの parametersHeaders と jsonHeaders、そして n8n-nodes-base.graphql ノードの headerParametersUi。ヘッダーの名前は秘密を含まないため、ヘッダーがどのような形であっても、各ヘッダーの値が検出され、その名前は保持されます。形とは、名前から値へのオブジェクト、キーと値の行(n8n では name と value の行)、または Langflow がヘッダーにまるごとマージするオブジェクトです。各ヘッダーはその名前で報告されます。リストの項目のうちヘッダー行でないものは、まるごと検出され、その位置で報告されます。テキストとして書かれたヘッダーはまるごと検出されます。ただし Flowise と n8n でテキストがヘッダーを JSON オブジェクトとして保持している場合は例外で、空にされるときはテキストがその場で書き換えられ、各値が空になり、保持しているヘッダーの名前とともに 1 回報告されます。= で始まる n8n のテキストは、ワークフローの実行時に n8n が評価する式であり、まるごと検出されます。 空にされるときは、User-Agent のような秘密を含まないヘッダーの値も含め、すべての値が空になります。そのため、インポートされたリクエストは、作成者が値を復元するまでそれらが空のまま送信されます。
  • クエリパラメーター — Langflow では、APIRequest または GoogleSerperAPI ノードの query_params と、SerpAPI、Serp、SearchAPI または SearchComponent ノードの search_params。Flowise では、 httpAgentflow ノードの queryParams と searchApi ローダーの customParameters。 n8n では、ツールとして使われるかどうかにかかわらず n8n-nodes-base.httpRequest ノードの queryParameters、jsonQuery、queryParametersUi および queryParametersJson、 @n8n/n8n-nodes-langchain.toolHttpRequest ノードの parametersQuery と jsonQuery、そして n8n-nodes-base.facebookGraphApi ノードが options の中に保持する queryParameters と queryParametersJson。いずれもリクエストのクエリとして送信され、クエリパラメーターはキーを含みうるため(検索 API の中にはキーをクエリの api_key として受け取るものがあります)、それぞれヘッダーと同じように検出されます。つまり、パラメーターがどのような形であっても各値が検出されてその名前は保持され、それぞれその名前で報告されます。テキストとして書かれたパラメーターはまるごと検出されます。ただし Flowise と n8n でテキストがパラメーターを JSON オブジェクトとして保持している場合は例外で、空にされるときはその場で書き換えられ、保持している名前とともに 1 回報告されます。空にされるときは、秘密を含まないパラメーターの値も含め、すべての値が空になります。そのため、インポートされたリクエストは、作成者が値を復元するまで、それらが空のまま送信されます(値が空のパラメーターを送信しない Flowise の HTTP ノードからは、それらなしで送信されます)。
  • どの接続も到達しない OpenAI ノードのデフォルトヘッダーとデフォルトクエリ — Langflow の OpenAIEmbeddings ノードの default_headers と default_query、および Flowise の chatOpenAI または openAIEmbeddings ノードの baseOptions です。ノードがどこにあっても対象となり、agentflow が選択するモデルの設定も含みます。ただし、ドラフトがそのノードを配線せず、書かれたとおりのノードに到達する接続も見つけない場合に限ります。配線するか接続が見つかる場合、それらは前述のとおり配線です。それぞれまるごと検出され、 空にされるときはその種類を保ち(オブジェクトは {}、リストは []、テキストは空文字列)、1 回報告されます。
  • コマンドラインとして書かれたリクエスト全体 — Langflow の APIRequest ノードの curl_input と Webhook ノードの curl で、Webhook のデフォルト値も含め、まるごと検出されます。どちらもフローの実行時には読まれません。前者はエディターでノードのフィールドを埋めるだけであり、後者は例を示すだけです。
  • 資格情報の名前で資格情報を保持する入力 — Langflow の OlivyaComponent ノードの api_key、すべての Composio コンポーネントの verification_token、および mem0_chat_memory ノードの mem0_config(空にされるときは値全体がその種類を保ちます)。そして Flowise の startAgentflow ノードの webhookSecret と callbackSecret、および teradataMCP ノードの bearerToken。それぞれまるごと検出されます。名前が資格情報に似ているだけの入力(別の場所に保存されたキーの名前、ユーザー名、またはコンポーネントが秘密ではないと宣言するオプション)は検出されません。

設定が空にする値、フローが各パートに到達するためにドラフトが書き込むもの、Langflow のエディターが書くとおりに書かれる Langflow のエッジのハンドル、および後述する改行(LF)として書かれる復帰(CR)を除き、フローはエクスポートされたとおりに運ばれます。これらがなければ、バイト単位でそのままです。

ドラフト内の接続は資格情報の値を運びません。各接続が提示する資格情報は、ドラフトされた Release が参照によって付与します。詳細は ドラフトが Release に残すもの で説明しています。

設定が書かれたままにするすべての値はドラフトに届き、作成者が credential-carried 警告を手がかりにそれをレビューします。フィールドに関する規則はフローの残りの部分には及ばないため、作成者はドラフトを共有する前にそれもレビューします。対象は次のとおりです。フローが運ぶコンポーネント自身のコード(カスタムコンポーネントはその中にキーを保持しえます)。コンポーネントが宣言する入力以外にエディターがノードに追加する入力。APIRequest や httpAgentflow ノードのものなど、リクエストとともに送信される本文(トークンを含みえます)。Langflow の EmbeddingModel ノードの model_kwargs や Flowise の replicate ノードの additionalInputs など、ノードがモデルのクライアントやローダーに独自の 1 つのオブジェクトとして渡す引数(任意の名前でキーを含みえます)。MCP サーバー以外のアドレス(ユーザー部分やクエリにキーを含みえます)。n8n の Code ノードのコード、およびインポーターが上に挙げていない、リクエストを送信するノードのヘッダーやクエリ。そして、プロンプトやメッセージなどの自由テキスト。

ドラフトが Release に残すもの

ドラフトされた Release は、プラットフォームのエントリーと各パートのエントリーに、フローが提供できないものを保持します。

  • プラットフォームのイメージ、infra.image として: インポーター自身が選んだイメージで、カタログにあるそのプラットフォーム用の Recipes が動作することが確認されているバージョン(langflowai/langflow:1.6.0、flowiseai/flowise:3.1.3、n8nio/n8n:1.110.1)のもので、その旨を述べるコメントが付きます。インポートがソースに合わせてこれを上げたり下げたりすることはありません。Langflow のフローの last_tested_version のように、エクスポートが異なるプラットフォームのバージョンを示している場合は、コメントがそれを示します。
  • プラットフォームが公開されるポート、infra.published_port として、--target compose の場合のみ: Langflow は 7860、Flowise は 3000、n8n は 5678 で、それぞれが待ち受けるポートであり、その Compose Recipe がホストのループバックアドレス 127.0.0.1 で公開します。その上のコメントは、このポートにはこのマシンからのみ、そこで動作する任意のプロセスからアクセスでき、その行を削除するとサービスが内部にとどまることを述べます。1 回のインポートの 2 つ目のフローは、それより前のフローが使っていない次のポートを使います。ほかのターゲットの場合やターゲットがない場合は書き込まれません。
  • プラットフォーム自身のシークレットと、各モデル接続の資格情報。参照によって付与され、値として付与されることはありません。Langflow では admin_password スロットで、values.require_authentication が true のままである間に読み込まれます。Flowise では owner_password スロットで、values.flow_definition が設定されている間は必須です。そして、パートがプラットフォームの model ソケットに接続されている場合は、その接続の credential です。n8n プラットフォームは独自のシークレットを取りません。それぞれの付与方法はターゲットによって異なります。詳細は ターゲットごとのシークレット で説明しています。
  • どのソースにもない各値。それが何であるかを述べるコメントの下に空文字列として書き込まれます。Flowise では infra.owner_email(所有者アカウントのメールアドレス)で、values.flow_definition が設定されている間は必須です。また、プラットフォームに接続された各 MCP サーバーのアドレス、つまりそのパートの infra.endpoint です。いずれもインポートが必要とする値で、インポートの回答ファイル で説明しているとおりに回答します。

ツールやベクトルストアへの接続が提示する資格情報はドラフトされません。そのような接続の資格情報は、ツールがそれを送るためのヘッダーを公開していない場合にビルドを停止させるため、プラットフォームのエントリーの上のコメントがそれを示し、ツールが資格情報を受け付ける場所で付与できるようにしています。

ターゲットごとのシークレット

--target helm では、各シークレットは core/referenced-secret であり、その origin は名前空間にすでに存在する Kubernetes Secret の名前で、その Secret はデータキー value の下に値を保持します。この名前はどのソースからも得られないため、何を保持するかを述べるコメントの下に空で書き込まれ、インポートが補うべき値になります。ドラフトされた Manifest は core/referenced-secret を helm/k8s-existing-secret にマッピングします。

その他のすべてのターゲット、およびターゲットなしの場合、各シークレットは core/secret-value であり、その origin は変数への参照です(${LANGFLOW_ADMIN_PASSWORD}、${FLOWISE_OWNER_PASSWORD}、モデル接続の資格情報には ${OPENAI_API_KEY})。変数参照を置換するターゲットは、Docker Compose がスタックの起動時に行うように、これを環境から読み取ります。そのため、値を含むファイルはなく、そのために補うべき値もありません。上の Flowise の chatflow をターゲットなしでインポートすると、次の Release でドラフトされます。

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/multiple-documents-qna
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the flowise format.
spec:
aggregate: imported/multiple-documents-qna
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
flowise:
infra:
# The image running core/ai-agent/flowise, at the version this importer drafts, which the catalog's Recipes for it are known to run; the import does not raise or lower it to follow the source.
image: "flowiseai/flowise:3.1.3"
# Left for the Release, since the source cannot supply it: infra.owner_email, the email address of the platform's owner account, required while values.flow_definition is set
owner_email: ""
features:
owner_password:
type: core/secret-value
infra:
# Attached by reference, never as a value: the owner account's password, required while values.flow_definition is set, read from the variable FLOWISE_OWNER_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${FLOWISE_OWNER_PASSWORD}"
uses:
model:
chatopenai-0:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential flowise presents to chatopenai-0 on its model connection, read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
chatopenai-0: {}

ターゲットなしでは、インポートは spec.manifest と infra.owner_email の 2 つの値を補う必要があります。--target compose ではオーナーのメールアドレスのみ、--target helm ではオーナーのメールアドレスと 2 つの Kubernetes Secret の名前です。

compose ターゲットでは、Release だけがアタッチするシークレットは 1 つのキー value で届くため、オーナーまたは管理者のパスワードと接続の資格情報がどちらもそのキーで届いてしまいます。そのため、プラットフォームが接続を張る場合、Aggregate はそれぞれを独自のキーで宣言します。Flowise ではキー OWNER_PASSWORD を持つ owner_password、Langflow ではキー LANGFLOW_SUPERUSER_PASSWORD を持つ admin_password、3 つのプラットフォームすべてでキー OPENAI_API_KEY を持つモデル接続の credential で、それぞれ理由を述べるコメントの下に置かれます。--target compose ではこれらの行は有効な状態で書き込まれます。ターゲットなしでは、上の例のようにコメントアウトされた状態で書き込まれ、compose 向けにビルドする場合にコメントを外します。その他のターゲットでは書き込まれません。Release は各スロットの origin をアタッチし、同じ型を指定するか、何も指定しません。

attach_egress_allowlist 設定が true の場合、プラットフォームのインスタンスは標準ライブラリの core/egress-allowlist Feature も features の下に egress-allowlist として宣言します。これにより、プラットフォームは接続が到達するコンポーネント、自身のポッド、クラスタの DNS にのみ接続します。これは 宣言された呼び出しとしての uses エッジの送信側の対応物です。Aggregate のアタッチメントは infra を持たないため、Aggregate はアタッチメントの型だけを宣言し、ドラフトされた Release もそのどれも書き込みません。プラットフォームのエントリの上のコメントは、features.egress-allowlist.infra の下に次のものを示します。control_plane_present は、クラスタのネットワークプラグインがネットワークポリシーを強制することを確認するためにオペレーターが true に設定するもので、これがないとビルドは停止します。admitted_destinations は、ホスト型モデルなど、クラスタが実行しないターゲットを持つ各接続について、ターゲットとアドレス範囲を示すエントリを保持するリストで、これがないとビルドはその接続を示して停止します。そして、プラットフォームを含む境界の aggrega.ai/namespace です。ポリシーはワークロードの名前空間に配置され、ワークロードがどの名前空間にも出力されない場合にビルドが停止するためです。どのキーも空で書き込まれないため、いずれもインポートが補うべき値には含まれません。配線された各パートの判定は、アタッチメントがその接続を許可することを示し、インポートはアタッチメントを feature-attached として報告します。Compose にはネットワークポリシーがないため、このようなドラフトの compose ビルドはアタッチメントを示して停止します。プラットフォームが接続を張る場合、上記の compose の行はインスタンスの features ブロック内に書き込まれ、2 つ目の features キーは置かれません。

パートが提供するモデル

ドラフトが参照するパートのうち、その Component が model という名前の値を宣言するもの(標準ライブラリの各モデル Component はこれを宣言し、必須としています)は、ノードが選択するモデルの名前を values.model として書かれます。

  • Langflow — OpenAIModel または AnthropicModel ノードの model_name、OpenAIEmbeddings ノードの model、そして LanguageModelComponent または EmbeddingModel ノードでは、設定されていれば model_name の上書き、それ以外は model フィールドが選択するモデル。
  • Flowise — chatOpenAI、chatAnthropic または openAIEmbeddings ノードの modelName。
  • n8n — インポーターの表がマッピングするチャット、補完、または埋め込みノードの model パラメーター、 あるいは Google Gemini および Vertex ノードではその modelName。名前として、または n8n の新しいノードがそれを保持するセレクターの値として書かれたものです。n8n はデフォルトに設定されたパラメーターをエクスポートから除外するため、デフォルトのモデルを保持するノードはエクスポートでモデルを示しません。

Release は値を書けません。そのため、ドラフトが書けるモデルをノードが示さない場合(何も選択していない、グローバル変数やフロー実行時にのみ読まれる式で示している、接続された別のノードから取得している、またはインポーターがモデルフィールドを読まない型である場合)、パート内のコメントが values.model を作成者に委ね、インポートは model-not-named でそれを報告します。ドラフトがドラフトするパートは値なしで書かれます。

フローをドラフトに書く方法

フローは、末尾の改行を保持するチョンピングを持つ YAML リテラルブロックとして書かれるため、 values.flow_definition はフロー自身のテキストとして読み戻されます。Aggregate のテキストはテンプレートとして読まれるため、フローが含む各 {{(Flowise のチャットフローは 2 つのノード間のすべての接続に {{<node id>.data.instance}} を書きます)は {{"{{"}} として書かれ、補間によって 2 つの波括弧に戻ります。詳細は Text that carries its own double braces で説明しています。モデルの名前も同じ方法で書かれます。

リテラルブロックは、すべての文字を書かれたとおりに保持できるわけではありません。

  • キャリッジリターンは、CR LF ペアのものも単独のものも、1 つのラインフィードとして書かれます。JSON ドキュメントはトークン間にのみこれを含み、そこではどの空白も同じように読まれるため、プラットフォームは同じフローを読み取ります。インポートはその数を carriage-returns-rewritten で報告します。
  • リテラルブロックが保持できないその他の文字があると、フローは保持されません。対象は、改行文字(U+0085、U+2028、U+2029)、タブとラインフィード以外の制御文字(U+0000 から U+001F、U+007F、U+0080 から U+009F)、非文字 U+FFFE と U+FFFF、UTF-8 シーケンスの一部でないバイトです。この場合 values.flow_definition は未設定のままとなり、その旨のコメントが付き、残りはドラフトされ、インポートは文字の種類ごとに、フローが含む数と最初の文字の行と列を添えて definition-not-carried を報告します。

ドラフトが空またはあらたに書く値が、解析されたツリーで保持される位置のエクスポートのバイト列に存在しない場合も、フローは保持されず、インポートはその値の位置を示して definition-not-carried を報告します。このとき、フローの識別子は、ドラフトが保持できる場合はフロー自身のもの、それ以外はフローのノードの識別子から導出されたものになります。

ノードごと

layout: nodes の場合、インポートはフローのすべてのノードをそれぞれ独立した Component としてドラフトし、次のものを書きます。

  • aggregate.yaml — ドラフトの命名方法 で説明するとおりフローにちなんで名付けられ、フローのノードを構成するドラフト Aggregate。各ノードのエントリを持ち、フローの各エッジは、それが供給するノードの uses 接続となります。そのソケットとエイリアスはどちらも供給元のノードのキーにちなんで名付けられるため、複数のノードから供給されるノードは各接続に独自のエイリアスを与えます。
  • ドラフトする各ノードについて components/ 下に 1 つのファイル。 <target_namespace>/<category>/<name> という名前(name はノードの型から取られます)、バージョン 0.1.0 のドラフト Component で、値フィールドは閉じた values オブジェクトの文字列フィールドとして、資格情報フィールドは配信方法を Recipe が決める必須の資格情報スロットとして書かれます。
  • release.yaml — 同じ名前の Release のドラフトで、その Aggregate を指定し、ノードごとにエントリを持ちます。

フロー自体は保持されず、どのフィールドの値も読まれません。

エクスポートされたフローそのものを運ぶ

デフォルトのドラフトはフローを運びます。プラットフォームのインスタンスは、エクスポートを values.flow_definition として受け取り、フローがドラフトにどのように書き込まれるかで説明するとおりに書き込まれます。フローを手作業で Aggregate に書き込む作成者も、ノード単位でレイアウトされたドラフトであれ、自身の Aggregate であれ、同じ方法で書き込みます。作成されたとおりにフローを実行する Component は、エクスポートを値として受け取ります。標準ライブラリの core/ai-agent/langflow と core/ai-agent/flowise では flow_definition です。また Aggregate のテキストはテンプレートとして読まれるため、エクスポートに含まれる二重波括弧はテンプレートアクションとして読まれてしまいます。Flowise のチャットフローは 2 つのノード間の接続ごとに {{<node id>.data.instance}} を書き込み、Flowise のプロンプトは変数を {{question}} と命名し、Langflow のエクスポートはそのコンポーネントのソースコードを含み、そこにも波括弧が現れることがあります。エクスポート内の各 {{ をブロックスカラーの中で {{"{{"}} と書くと、Component の Recipes が読む前に補間によってエクスポートのテキストが復元されます。その理由は独自の二重波括弧を含むテキストで説明しています。エクスポートに含まれる認証情報の値は、Aggregate ではなく Release がアタッチするシークレットに属します。empty_credentials 設定が求める場合にドラフトが行うのと同様に、空で書き込んでください。

# Aggregate fragment — a Flowise chatflow carried as exported
spec:
components:
chat:
type: core/ai-agent/flowise
values:
chatflow_id: 3f2b8c1e-7a4d-4e9b-8c2f-1a6d5e9b0c47
flow_definition: |
{
"nodes": [
{
"id": "llmChain_0",
"data": {
"name": "llmChain",
"inputs": {
"model": "{{"{{"}}chatOpenAI_0.data.instance}}",
"prompt": "{{"{{"}}promptTemplate_0.data.instance}}"
}
}
}
],
"edges": []
}

MCP インポーター

importer/mcp は、MCP クライアントの設定に列挙された MCP サーバー、または MCP レジストリのサーバー記述が記述する 1 つのサーバーを読み取り、各サーバーを標準ライブラリの MCP ツール core/ai-tool/mcp のインスタンスとしてドラフトします。すべてのサーバーがこれに該当するため、インポーターは候補を比較せず、マッピングの判断も報告しません。

読み取るもの

  • クライアントの設定。 Claude Code の .mcp.json、Claude Desktop の claude_desktop_config.json、Cursor の .cursor/mcp.json は、サーバーを名前ごとに mcpServers の下に列挙します。Visual Studio Code の .vscode/mcp.json は servers の下に列挙し、両方の下にサーバーを列挙するファイルは mcpServers の下が先に読み取られます。type が stdio であるサーバー、または type を指定せず command を持つサーバーは、コマンドライン(その command と args)から起動され、 env がその環境になります。type が http、streamable-http または sse であるサーバー、または type も command も指定せず url を持つサーバーには、その url で接続し、その headers を送信します。
  • レジストリのサーバー記述。 MCP レジストリが公開する server.json です。その name と、 最初のパッケージ、またはパッケージを列挙していない場合は最初のリモートを読み取ります。npm または PyPI のパッケージは、ランチャー(その runtimeHint、または npm なら npx、PyPI なら uvx)、 runtimeArguments、バージョン付きのパッケージ(npm では <identifier>@<version>、PyPI では <identifier>==<version> と記述)、および packageArguments から成るコマンドラインで起動され、 environmentVariables がその環境になります。位置引数はその value、または default です。 名前付き引数は、そのいずれかを持つ場合は <name>=<value> と記述し、どちらも持たない場合はその name と記述します。OCI パッケージは、その identifier が指定するイメージから実行されます。リモートにはその url で接続し、その headers を送信します。記述が列挙するその他のパッケージとリモートはすべて、1 つのインスタンスが実行するのはそのうち 1 つであるため、コメントで名前が示されます。

サーバーのその他のメンバー(cwd、envFile、Cursor の auth、またはコマンドラインから起動されるサーバーの url のように、その種類が読み取らないメンバー)は、core/ai-tool/mcp のどのインフラストラクチャキーも受け取らないため、どこにも書き込まれず、Release 内のサーバーのエントリの上のコメントで名前が示されます。設定の inputs は、Visual Studio Code が入力を求める内容を記述するもので値を持たないため、読み取られません。サーバー、その環境およびヘッダーは、ソースが記述する順序を保ちます。ただし、コメント付き JSON として読み取られる設定では、パースされたツリーが記述する順序、つまり名前順を保ちます(コメントを含む設定を参照)。

ディレクトリは、それが含むクライアント設定(任意の深さにある、4 つのいずれかの名前を持つすべてのファイル)を通じて、パスの順に読み取られ、すべてのファイルのすべてのサーバーが 1 つの Aggregate にドラフトされます。

サーバーが何になるか

aggregate.yaml は、ドラフトの命名方法で説明するとおりソースにちなんで名付けられたドラフト Aggregate で、サーバーごとに core/ai-tool/mcp のインスタンスを 1 つ保持します。インスタンスのキーはサーバー名で、小文字に変換され、英字と数字以外の文字の連続はそれぞれ 1 つのハイフンとして記述され、先のサーバーがそのキーを取っていた場合は数値の接尾辞が付きます。キーが記述どおりのサーバー名でない場合、またはインポートが複数のファイルを読み取った場合は、インスタンスの上のコメントがサーバーとその由来のファイルを示します。それらを使用するエージェントはドラフトされません。

その横の release.yaml は同じ名前のドラフト Release で、その spec.aggregate が Aggregate を指定し、各インスタンスについてソースが示す運用上の入力を保持します。

  • コマンドラインから起動されるサーバーには、infra.stdio_command(そのコマンドと続く各引数を、それぞれ 1 項目として)と、infra.stdio_runtime(ランチャーのエコシステム。 コマンドが npx、npm または node の場合は npm、uvx、uv、python または python3 の場合は pypi、 レジストリパッケージの場合はそのレジストリである npm または pypi)。
  • アドレスで接続するサーバーには、infra.endpoint。これはユーザー部分、クエリ、フラグメントを除いたアドレスです。Component はキーを含む部分を除いたアドレスを受け取るためです。除かれた各部分は、 サーバーが保持する資格情報の値が説明するとおり、エントリの上のコメントにアドレスと並べて記述されます。
  • OCI パッケージには、infra.image。
  • どのターゲットでも、どのサーバーにも infra.published_port は書き込まれません。ドラフトはサーバーをホスト上に公開することはありません。
  • サーバーの環境には、インポートのターゲットに応じて参照でアタッチされる server_env スロット。--target helm では、名前空間にすでに存在する Kubernetes Secret を指定する core/referenced-secret で、その Secret は変数ごとに 1 つのデータキーを保持し、各キーは保持する変数の名前を持ちます。Secret の名前はデータキーを示すコメントの下に空で書き込まれ、インポートが補うべき値になります。その他のすべてのターゲット、およびターゲットなしの場合は core/referenced-secret-set で、変数ごとに infra.entries の下に 1 つのエントリを持ち、キーは変数の名前、値はソースが記述したとおりです。そのため ${GITHUB_TOKEN} のような変数参照は参照のまま残り、変数参照を置換するターゲットがそれを環境から読み取ります。

ソースが示さないものは、それが何であるかを述べるコメントの下に空で書き込まれます。どちらのブリッジイメージも持たないランチャーのコマンドは infra.stdio_runtime を空のままにし、インポートが補うべき値になります。レジストリ記述がユーザーに委ねる引数は空の項目として、ソースが値を記述しない変数は値が空のエントリとして書き込まれ、それぞれエントリの上のコメントで名前が示されます。

ドラフトされるすべての Release と同様に、metadata.environment を development として、変更すべきドラフトのデフォルト値であることを述べるコメントの下に書き込みます。ターゲットなしの場合は、spec.manifest をインポートが補うべき空の文字列として書き込みます。ターゲットが与えられると、インポーターは Manifest 自体をドラフトします。カタログは core/ai-tool/mcp を複数の Recipes で実現しており、各サーバーがどのように実行されるかを知っているのはインポーターだけだからです。インポーターは各サーバーをキーによって mappings.components.name の下で、そのサーバーの実行方法に対応するターゲットの realization にマッピングします。コマンドラインには mcp-stdio-bridge、アドレスには mcp-remote、イメージには mcp で、たとえば helm/mcp-stdio-bridge や compose/mcp-remote です。また、環境がアタッチされるシークレットの型をその realization にマッピングします。helm では helm/k8s-existing-secret、compose では compose/dotenv-secret-set です。ターゲットが追加するものが説明するとおり、インポートはその Manifest を完成させ、Release でそれを指定します。

HTTP で接続するサーバーと npx で起動するサーバーを列挙する Claude Code の .mcp.json:

{
"mcpServers": {
"api-server": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer ${API_KEY}" }
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
}
}
}

は、次のようにドラフトされます。

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/mcp
version: 0.1.0
description: Draft Aggregate imported from a source in the mcp format.
spec:
components:
api-server:
type: core/ai-tool/mcp
github:
type: core/ai-tool/mcp
release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/mcp
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the mcp format.
spec:
aggregate: imported/mcp
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# The headers the source sends this server, which no infrastructure key of core/ai-tool/mcp takes, since a remote server's credential is held by each consumer, on its connection to the tool:
# - Authorization: "Bearer ${API_KEY}"
api-server:
infra:
endpoint: "https://api.example.com/mcp"
github:
infra:
stdio_command:
- "npx"
- "-y"
- "@modelcontextprotocol/server-github"
stdio_runtime: npm
features:
server_env:
type: core/referenced-secret-set
infra:
# Attached by reference wherever the source names a variable: the environment github is started with, one entry per variable, each written as the source writes it, so a variable reference stays one, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, and an empty value is one still owed.
entries:
- key: "GITHUB_PERSONAL_ACCESS_TOKEN"
value: "${GITHUB_TOKEN}"

--target helm でインポートすると、同じ設定の Release は環境を、それが指定する Secret としてアタッチし、インポーターがドラフトする Manifest は各サーバーをキーによってマッピングします。

# release.yaml, the github entry's environment
features:
server_env:
type: core/referenced-secret
infra:
# Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding the environment github is started with, one data key per variable, each named as the variable it holds: GITHUB_PERSONAL_ACCESS_TOKEN.
origin: ""
manifest.yaml
apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/mcp
version: 0.1.0
spec:
mappings:
components:
type: {}
name:
api-server: helm/mcp-remote
github: helm/mcp-stdio-bridge
features:
type:
core/referenced-secret: helm/k8s-existing-secret

サーバーが保持する認証情報の値

Release が書き込むサーバー設定の各値(各ヘッダーの値、コマンドラインの各項目、アドレス、infra.endpoint が除外するアドレスの各部分、各環境変数の値)はキーを含む可能性があり、どのクライアントもそれを認証情報としてマークしないため、インポートはそれぞれを MCP サーバーの設定のメンバーとして特定します。isSecret とマークされたレジストリ入力は、そのフォーマットが認証情報としてマークする値として特定されます。レジストリ入力(環境変数またはリモートのヘッダー)は、その value として、値が書かれていない場合はその default として読み取られます。デフォルトでは、それぞれは書かれたとおりに Release に引き継がれ、credential-carried 警告の中で、そのサーバーと場所(headers.<header>、infra.stdio_command.<position>、infra.endpoint または server_env.<variable>、アドレスの一部の場合はそれが書かれている url とその部分の名前。たとえば「url of node remote-search is carried with its query as written(ノード remote-search の url はそのクエリが書かれたとおりに引き継がれます)」)によって示され、値によって示されることはありません。empty_credentials 設定が marked または all の場合、それぞれは空で書き込まれ、credential-emptied で報告されます。コマンドラインの項目は空の項目として、環境変数の値は空の値として書き込まれ、それぞれエントリの上のコメントで名前が示されます。アドレスは空の infra.endpoint として書き込まれ、インポートが補うべき値になります。ヘッダーの値やアドレスの一部はコメントから除外され、コメントはヘッダーまたはその部分の名前のみを示します。クライアントの infra.stdio_runtime は Release が書き込むコマンドから読み取られるため、空で書き込まれたコマンドではこれも空になり、インポートが補うべき値になります。--target helm では、Release は環境変数の値をまったく書き込みません。それらは server_env スロットが指定する Secret が保持します。

1 つの変数参照だけからなる値(裸の名前 ${NAME}、${workspaceFolder} などの定義済み変数を含む、${env:NAME} または ${input:id})は、それ自体の値を保持しません。設定が何であってもそのままのテキストとして書き込まれ、フロー内の参照と同様に、どの警告にも示されません。値がそのような参照である環境変数は、エントリの値として書き込まれ、参照は参照のまま残ります。値がそのような参照であるヘッダーやアドレスの一部は、読み取り元の参照とともに一覧に示されます。演算子の後にテキストを持つ参照(デフォルト、代替、メッセージ、または代入。たとえばコロンの有無にかかわらず ${NAME:-value} や ${NAME-value})はそのテキストを保持し、参照の横にあるテキストも同様です。それぞれは他の値と同様に特定されます。

core/ai-tool/mcp のどのインフラストラクチャキーもヘッダーの値を受け取りません。リモートサーバーの認証情報は、各コンシューマーがツールへの接続上で保持するものであり、インポートはコンシューマーを作成しません。そのため、サーバーのエントリーの上のコメントには、ソースが送信する各ヘッダーが、書かれたとおりの値(ソースのテキストと正確に一致するダブルクォート文字列)とともに一覧され、それを提示するコンシューマーの接続に移すことができます。ソースが値を書いていないヘッダー(値もデフォルトも持たないレジストリのヘッダー入力など)は、値なしとして一覧されます。OCI パッケージが示すイメージはそのまま書き込まれ、設定の対象となる値ではありません。

infra.endpoint はキーを含む部分を除いたアドレスを受け取るため、ソースが書くアドレスのうち除外される部分(@ の前のユーザー部分、? の後のクエリ、# の後のフラグメント。最初の # 以降はすべてフラグメントです)は同じコメントに、それぞれの名前とともに、区切りの @、? または # を除いて書かれたとおりに一覧されます。アドレスからキーを読み取るコンシューマーは、ツールへの自身の接続上でアドレス全体を指定します。設定なしで https://user:pw@api.example.com/mcp?key=k で到達するサーバーは、次のように作成されます。

# The address's user part and query are not written in infra.endpoint, which holds the address without any part that carries a key; a consumer reading its key from the address supplies the whole address on its own connection to the tool:
# - user part: "user:pw"
# - query: "key=k"
api:
infra:
endpoint: "https://api.example.com/mcp"

また、empty_credentials が marked の場合、infra.endpoint は Release に委ねられ、コメントには user part と query がそれぞれ値を除外して一覧されます。

コメントを含む設定

Visual Studio Code は .vscode/mcp.json をコメント付き JSON として読み取り、MCP インポーターも同様です。このファイルに対するシグネチャは parse:jsonc を提供するパーサーを通して読み取るため、// や /* */ のコメント、末尾のカンマを含む設定は、フォーマットを指定しなくても認識され、インポーターは servers の下にサーバーを一覧するすべてのソースをこのパーサーで読み取ります。そのような設定は、コメントと末尾のカンマを除いた同じ設定とまったく同じように作成されます。パーサーはオブジェクトのメンバーを名前順に書き出すため、そのような設定のサーバー、その環境変数、そのヘッダーは、コメントの有無にかかわらず名前順に作成されます。コマンドラインは順序を保持します。その他のクライアントとレジストリはファイルを JSON として読み取り、インポーターも同様です。コメントを含む .mcp.json、claude_desktop_config.json、.cursor/mcp.json または server.json はどのシグネチャにも認識されず、--format mcp を指定してインポートすると、パーサーの理由とともに parse-failed で停止します。/* で開始されて閉じられないコメントは書かれたまま残され、パーサーはファイルを拒否します。

読み取る設定

MCP インポーターは、Settings で説明されている target_namespace と empty_credentials を読み取り、それ以外の設定は読み取りません。

Compose インポーター

importer/compose は、Compose ファイルが宣言するサービスとモデルを読み取ります。各サービスは、そのイメージが一致するカタログの Component のインスタンスとして、または標準ライブラリの汎用サーバー core/compute/server がそのイメージを実行するインスタンスとして下書きされます。各モデルは、カタログが標準ライブラリの Docker Model Runner ランタイム core/ai-model/docker-model-runner を保持している場合はそのインスタンスとして、保持していない場合は独自のモデル Component として下書きされます。さらに、それらと並んで、各サービスが動作のために記述する内容を保持する Release が下書きされます。

読み取るもの

  • ファイル。 単独でインポートされたファイルは、それだけが読み取られます。ディレクトリは Compose と同じ方法で読み取られます。 Compose ファイルを保持する各ディレクトリで、ディレクトリのパスの順に、compose.yaml、compose.yml、docker-compose.yml、docker-compose.yaml のうち最初に存在するものが Compose ファイルとなり、 compose.override.yml、compose.override.yaml、 docker-compose.override.yml、docker-compose.override.yaml のうち最初に存在するものがその上にマージされます。これらのファイルのうち それ以外のものは読み取られません。オーバーライドファイルを保持し Compose ファイルを保持しないディレクトリでは、最初の オーバーライドファイルが単独で読み取られます。下書きされた Aggregate の冒頭のコメントが、読み取られたファイルをマージされた順に、 また読み取られなかったファイルを示します。すべてのディレクトリのすべてのサービスとモデルは、 一つの Aggregate に下書きされます。
  • マージ。 オーバーライドファイルは Compose と同じ方法でマージされます。image は置き換えられます。ports は アドレス、公開ポート、コンテナポート、プロトコルによって、volumes はコンテナ内のパスによって、 environment は変数名によってマージされ、後のエントリが前のエントリに置き換わり、 新しいエントリは後に続きます。expose は追加されます。depends_on とサービスの models は結合され、 エントリの endpoint_var と model_var はそれぞれ、前のファイルが記述するものに置き換わります。 モデルについては、model と context_size は置き換えられ、runtime_flags は追加されます。Compose の !reset タグと !override タグは考慮されません。これらを持つ値は、YAML パーサーが読み取ったとおりにマージされます。
  • サービス。 その image と、build でイメージをビルドするかどうか。その ports、expose、 volumes、environment(マッピング、または NAME=value 項目のリストで、値のない名前は Compose が実行される環境から値を取ります)。depends_on(リストまたはマッピング)。そしてその models(モデル名のリスト、またはマッピングで、そのエントリは endpoint_var と model_var のもとに、モデルのアドレスと識別子がサービスに届く変数を指定できます)。それ以外の メンバー(command、healthcheck、secrets、env_file など)はどこにも書き込まれず、 Release 内のサービスのエントリの上にあるコメントで示されます。
  • モデル。 トップレベルの models の各エントリ。その model(モデルの OCI 識別子)、 context_size、runtime_flags は、カタログが core/ai-model/docker-model-runner を保持している場合はそのインスタンスに、 保持していない場合はそのために下書きされたモデル Component のインスタンスに、記述どおりに引き継がれます。どちらになるか、 またその理由はモデルの判定が示します。それ以外のメンバーは、そのインスタンスの上にある コメントで示されます。
  • その他。 その他のトップレベルのメンバー(name、networks、volumes、secrets、configs)は 読み取られず、Aggregate の冒頭のコメントがそれらを示します。

サービス、モデル、サービスの環境は、ファイルに記述された順序を保ちます。パーサーの ツリーはマッピングのメンバーをソート順に書き出すため、ブロックマッピングとして記述されている場合、その順序は ファイルのテキストから読み取られます。フロースタイルで記述されたマッピングはソート順を保ちます。

サービスがどの Component になるか

インポーターは、サービスをそのイメージが示すリポジトリによって照合します。リポジトリとは、タグと ダイジェストを除いた参照で、Docker Hub の参照は短縮形で記述されます(docker.io/library/postgres:16 に対する postgres)。 インポーターはリポジトリをイメージテーブルで照合します。これは、イメージリポジトリから、 標準カタログの Compose Recipe がそのリポジトリのイメージを実行する対象のカタログ Component への テーブルです。このテーブルはインポーターのビルド時に標準カタログの Compose Recipes と Components から生成されてインポーターにコンパイルされるため、インポートの実行時に Recipe は読み取られず、 テーブルはカタログが何を保持していても標準カタログのラベルを保持します。インポーターの Plugin エンティティは、その説明の中で、テーブルの生成元となった hub のリビジョンを示します。各 Recipe について、テーブルは Recipe が実装する Component と、main という名前のコンテナのイメージを読み取ります。 ただし、そのイメージが自身のテキストにリポジトリを記述している場合、またはそれを記述する locals エントリである場合に限ります。 Release が指定するイメージ全体を実行する Recipe や、テンプレートが別の方法で組み立てるイメージを実行する Recipe は 行を追加せず、Recipe がメインコンテナと並んで実行するイメージも行を追加しません。二つの Recipe が異なる Components に対して 一つのリポジトリを指定すると、テーブルの生成は停止するため、行が二つのうちの一方を指すことはありません。 行が示す Component について、テーブルはインポートに渡されるとおりにそのラベルを読み取ります。つまり、 バージョンを指定せずに Component を示す参照が解決されるバージョンで、extends を通じて継承するラベルも含めて読み取り、 component.aggrega.ai/category 以外のすべてのラベルをトレイトとして行に書き込みます。 標準カタログが保持しない Component を実装する Recipe も、テーブルの生成を停止させます。

行は、フローインポーターのテーブル行と同じように読み取られます。すなわち Component、その名前が属させるカテゴリ、 そのトレイト、そしてベンダーとしてのその名前の最後のセグメントです。 mapping_overrides 設定は、compose フォーマットのもとで、リポジトリをキーとしてテーブルの上に重ねられ、 テーブルがマッピングするリポジトリのエントリは その行に置き換わります。したがって、標準カタログの Recipes が指定しないイメージ(独自のイメージ、 またはカタログの Component が別のリポジトリで実行するイメージ)は、エントリによってマッピングされます。

with:
settings:
mapping_overrides:
compose:
bitnami/redis:
component: core/datastore/redis
category: datastore
traits:
datastore.aggrega.ai/engine: kv
vendor: redis

行がイメージをマッピングするサービスは、フローインポーターがノードを判定するのと同じように判定されます。カタログの Components に対してスコア付けされ、reuse_mode がデフォルトの auto-apply-above-threshold で、最良の候補が reuse_threshold 以上の上位ティアの一致である場合は参照され、それ以外の場合は独自の Component として下書きされ、下書きされた Component のファイルは、類似する Component を示すコメントで始まります。行はそれが示す Component のラベルを保持するため、カタログがその Component を標準カタログが与えるラベルのまま保持している場合、その行がマッピングするサービスはそれに対する上位ティアの一致となり、スコアは 0.90 で、auto-apply-above-threshold はデフォルトの reuse_threshold でそれを参照します。カタログがラベルを変更した Component は、行のトレイトのうちもう保持していない割合に応じてスコアが下がり、上位ティアにとどまる間だけ参照されます。カテゴリは独自のシグナルで一度だけ評価され、トレイトとして再度評価されることはありません。一つの Component を下書きするサービスは、その一つのファイルを共有します。行がイメージをマッピングしないサービス、イメージがインポーターの読み取るリポジトリを示さないサービス、またはイメージをビルドするサービスは、カタログが何を保持していても core/compute/server のインスタンスとなります。各サービスの判定は、各ノードの判定と同じように報告されます。

サービスが何になるか

aggregate.yaml は、ドラフトの命名方法で説明するとおりプロジェクトにちなんで名付けられたドラフト Aggregate で、サービスごとに、その判定が選んだ Component のインスタンスを 1 つずつ保持します。インスタンスは MCP インポーターがサーバーにキーを付けるのと同じ方法でキーが付けられ、キーがサービス名でない場合やインポートが複数のディレクトリを読んだ場合は、その上のコメントがサービスと読み込み元のファイルを示します。サービスの depends_on が示す各サービスは接続 uses: <key>: <key>: {target: <key>} になり、どちらもターゲットのキーにちなんで名付けられたソケットとエイリアスの下に書かれます。コンポーネントは、どのソケットに接続されていても各接続をそのエイリアスで読み取るため、サービスの各接続にはそれぞれ固有のエイリアスがあります。サービスの環境の変数も接続を生むことがあり、サービスの環境とイメージがどうなるかで説明するとおり、到達するサービスが公開するものから変数を届けます。各モデルは、ワークスペースのカタログが core/ai-model/docker-model-runner を保持する場合、reuse_mode の指定にかかわらずそのインスタンスになり、そのための Component はドラフトされません。インスタンスは model と runtime_flags をソースの記述どおりに書き、ソースの context_size を context_window として書きます。これはランタイムがモデルのコンテキスト長として宣言する値で、その Compose Recipe が Compose の context_size として書き戻します。カタログが core/ai-model/docker-model-runner を保持しない場合、モデルは <target_namespace>/ai-model/<key> としてドラフトされます。これは ai-model カテゴリの Component で、その values は model、context_size、runtime_flags を宣言し、そのインスタンスはソースが記述する各値を書きます。すべてのモデルには、どちらであるかを示す判定があり(mapped llm (model) to core/ai-model/docker-model-runner as a reference, NONE、またはワークスペースのカタログが core/ai-model/docker-model-runner を保持しないことを判定が記録するドラフト)、どちらの場合も、そのモデルを示す各サービスは、依存するサービスと同様にモデルに接続されます。長い形式で endpoint_var または model_var を使ってモデルを示すサービスは、モデルのアドレスと識別子がサービスに届く変数を示します。ドラフトのどのキーも変数名を保持しないため(接続はモデルにちなんで名付けられた、値を宣言しないソケットに書かれ、インポーターにはどの Component のインフラキーも渡されません)、接続の上のコメントがエントリの記述どおりに各変数を示し、サービスの判定も同じ文を記録します。

search:
type: core/compute/server
uses:
# The service search reads the address of the model embedder as AI_MODEL_URL and its identifier as AI_MODEL_NAME, the names its models entry gives them; no key of the draft holds either name.
embedder:
embedder:
target: embedder

短い形式で、またはどちらの変数も使わずにモデルを示すサービスは、コメントなしでモデルに接続されます。

その隣の release.yaml は同じ名前のドラフト Release で、その spec.aggregate が Aggregate を示します。core/compute/server のインスタンスについては、記述どおりのイメージである infra.image と、ports の最初のエントリ(ports が何も保持しない場合は expose の最初のエントリ)でコンテナが待ち受けるポートである infra.port を書きます。--target compose の場合は、同じ ports エントリが公開するホストポートである infra.published_port もソースの記述どおりに書き、このマシンからのみ、そこで動作する任意のプロセスから到達可能であり、その行を削除するとサービスは内部にとどまる旨のコメントを付けます。published_port が受け取らない 1024 未満のホストポートは書かれず、エントリの上のコメントがそれを示します。各サービスのエントリの上のコメントは、ソースが記述していてドラフトのどのキーも持たないもの(別の Component に一致し、ドラフトがそのタグを変換しないサービスのイメージ、その ports、expose、volumes、およびドラフトが変換しない environment の各変数)を、Component がそれを受け取る場所へ移せるように書きます。ドラフトが Release に委ねるもの(自身のイメージをビルドするサービスのように、イメージを示さないサービスのイメージと、単一の数値でないポート)は、理由を示すコメントの下に空で書かれます。ビルドは Release が示すインスタンスだけを配置するため、各モデルのインスタンスには、サービスのエントリの後に空のエントリ <key>: {} があります。これは、Compose 上でデフォルトのない入力を受け取らない core/ai-model/docker-model-runner のインスタンスでも、独自の Component としてドラフトされたモデルでも同じです。そのため、ドラフトされたモデルはすでに配置されており、それを実現する Recipe を書けばビルドできます。core/compute/server の下限 1024 未満のポートのように、Component が受け取らないポートはソースの記述どおりに書かれ、ビルドはそれを示して停止します。Release は、MCP インポーターの Release と同様に metadata.environment を書き、ターゲットがない場合は空の spec.manifest を書きます。ターゲットが与えられた場合、インポートは ターゲットが追加するもので説明するとおり Manifest をドラフトし、各 Component をそのターゲット上で実現する Recipe に対応付けます。core/compute/server は compose/server または helm/server に、core/ai-model/docker-model-runner は compose/docker-model-runner または helm/docker-model-runner に対応付けられます。

PostgreSQL と、それに依存する独自の API を実行する compose.yaml:

services:
db:
image: postgres:16
environment:
POSTGRES_DB: shop
api:
image: ghcr.io/example/shop-api:1.4.2
depends_on:
- db
ports:
- "8080:8080"
environment:
CACHE_URL: redis://cache:6379/0

は、単独でインポートされ、プロジェクトが name を持たないためファイルにちなんで名付けられ、設定なしで、標準ライブラリの core/datastore/postgres を含むカタログに対して次のようにドラフトされます。

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/compose
version: 0.1.0
description: Draft Aggregate imported from a source in the compose format.
spec:
components:
db:
type: core/datastore/postgres
# The values of core/datastore/postgres the source sets as POSTGRES_DB, the variables its Compose Recipes set from them.
values:
database: "shop"
api:
type: core/compute/server
uses:
db:
db:
target: db
release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/compose
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the compose format.
spec:
aggregate: imported/compose
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
db:
infra:
# The tag of the image the source runs, postgres:16, the engine_version of core/datastore/postgres its Compose Recipes run.
engine_version: "16"
# The source also states, for the Release to carry where core/compute/server takes it:
# ports:
# - "8080:8080"
# environment:
# CACHE_URL: "redis://cache:6379/0"
api:
infra:
image: "ghcr.io/example/shop-api:1.4.2"
port: 8080

インポートは mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9 を報告します。プロジェクトには cache サービスがないため、CACHE_URL は接続を生まず、コメントに残ります。reuse_mode: hints-only の場合、db は代わりに type: imported/datastore/postgres となり、components/imported-datastore-postgres.yaml にドラフトされます。このファイルは # resembles core/datastore/postgres (score 0.9000); reference it by setting type: core/datastore/postgres で始まります。ドラフトされた Component はカタログの Recipes が読む値を何も宣言しないため、そのイメージと環境はエントリの上のコメントに書かれます。--target compose の場合、Manifest は core/datastore/postgres を compose/postgres に、core/compute/server を compose/server に対応付けます。--target helm の場合は helm/postgres と helm/server に対応付けます。

サービスの環境とイメージがどうなるか

サービスが、そのイメージの行が示すカタログの Component のインスタンスであり、ワークスペースのカタログがその Component を保持する場合、インポーターは、イメージテーブルが各 Recipe について記録する内容から、標準カタログのその Component 用の Compose Recipes が読むのと同じようにイメージと環境を読み、ドラフトへ変換します。

  • イメージのタグは、Recipe がイメージ参照を組み立てる元となるインフラキーです。たとえば engine_version で、postgres:16 なら 16 です。これはソースのイメージを示すコメントの下で Release に書かれます。
  • Recipe が Component の値の 1 つから設定する変数(POSTGRES_DB、POSTGRES_USER)で、値がテキストを保持するものは、カタログの Component がその値を宣言している場合、インスタンスのその値(database または user)になり、変数を示すコメントの下で Aggregate に書かれます。
  • Recipe がパスワードを読む変数(POSTGRES_PASSWORD など)で、値が 1 つの変数参照であるものは、そのスロットに付けられるシークレットになり、参照が示す変数から読まれ、Recipe が読むときのキーで宣言されます。

さらに、すべてのサービスについて、このように読まれなかった環境の各変数は次のとおりです。

  • プロジェクトの別のサービスの名前である値は、そのサービスの行がホスト名を公開する provides キーを示す場合、そのサービスへの接続を生み、その inject ブロックがそのキーから変数を届けます。CACHE_HOST: cache は、キャッシュの host から得る CACHE_HOST になります。
  • 別のサービスがその Component に設定し、Component が公開する値と等しい値(POSTGRES_USER: notes を設定する PostgreSQL サービスと並ぶ DATABASE_USER: notes)は、その provides キーから変数を届ける接続を生みます。複数のサービスやキーがその値を保持する場合は、キーまたはそれ自身の変数の末尾が変数名の末尾と一致するものが読まれ、それがなければ、サービスの他の変数がまだ読まれていないものが読まれます。それ以外の場合、その変数は読まれません。
  • 別のサービスのシークレットの読み取り元である変数を示す、1 つの変数参照である値(DATABASE_PASSWORD: ${POSTGRES_PASSWORD})は、core/compute/server のインスタンス上では、ターゲットがシークレットをサーバーが受け取る値として書く場合、独自のシークレットになります。これは小文字の変数名で付けられ、同じ変数から読まれます。helm/server は core/referenced-secret を拒否するため、--target helm ではそのような変数はコメントに残ります。

その他の変数はすべて、ソースの記述どおりにサービスのエントリの上のコメントに残されます。Compose インポートのウォークスルーでは、API がこの方法でデータベースとキャッシュに到達するプロジェクトを、ドラフトどおりにビルドして実行します。

サービスが保持する認証情報の値

Compose はどの環境変数の値も認証情報としてマークせず、インポーターは変数名をその意味のために読まないため、何かを保持するすべての環境変数の値は、そのフォーマットが認証情報ではないとマークしつつ認証情報を持ち得る入力として検出されます。デフォルトでは、それぞれドラフトに記述どおりに移され(変換先の値、または Release 内のサービスのエントリの上のコメントへ)、credential-carried 警告でそのサービスと変数(environment.<variable>)によって示されます。値によって示されることはありません。empty_credentials 設定が all の場合、それぞれ空で書かれ、credential-emptied で報告されます。コメントは値なしで変数を示します。marked の場合、Compose が何もマークしないため、空で書かれるものはありません。Compose が補間する変数参照 1 つだけからなる値(${NAME} または $NAME)は独自の値を保持しません。そのままのテキストとして書かれ、どの警告でも示されません。${NAME:-value} のようにデフォルトやメッセージを持つ参照はそのテキストを保持し、他の値と同様に検出されます。Compose が別の場所から読む値(env_file やシークレットのファイル)は読まれません。

読み取る設定

Compose インポーターは、Settings で説明する target_namespace、reuse_mode、reuse_threshold、emit_hints、 render_mode、mapping_overrides、empty_credentials を読み、それ以外の設定は読みません。emit_hints が制御するヒントは、ドラフトされた Component のファイルにのみ書かれ、ドラフトされた Aggregate には何も含まれません。

Dify インポーター

importer/dify は、Dify からその DSL(Dify がアプリケーションのために書き出す YAML ドキュメント)でエクスポートされたアプリケーションを読み取り、標準ライブラリの Dify インストール core/dify を構成する Aggregate を下書きします。アプリケーションはインストールの app_definition パラメーターに格納されます。インストールは、その API サーバーの Recipe がそのためにレンダリングするステップを通じて、デプロイ時にアプリケーションをインポートします。

読み取るもの

  • アプリケーション。 kind(値は app)、version(アプリケーションが記述されている DSL のバージョン)、および mode を持つ app。
  • ワークフローまたはチャットフロー(mode が workflow または advanced-chat)は、グラフを workflow の下に保持します。workflow.graph.nodes の各ノードのうち、data.type の下に型を指定するものは、グラフが列挙する順序でアプリケーションのノードとなり、workflow.environment_variables はアプリケーションが読み取る変数を保持します。
  • チャット、エージェントチャット、または補完アプリケーションは、設定を model_config の下に保持します。その model、dataset_configs.datasets.datasets の下の各ナレッジベース、および agent_mode.tools の下の各ツールは、アプリケーションのノードとなり、model_config.model のようにその場所で名前が付けられます。agent モードのアプリケーションは 1 つのノード agent です。
  • 必要なプラグイン。 dependencies の各エントリもノードであり、dependencies.<n> という名前で、marketplace のようにエントリが指定する型を持ちます。

下書きの内容を決めるものはほかにありません。アプリケーション全体が格納されます。

アプリケーションがどうなるか

aggregate.yaml は、ドラフトの命名方法で説明するとおりアプリケーションにちなんで名付けられた下書き Aggregate で、dify をキーとする core/dify のエントリを 1 つ構成します。その app_definition パラメーターは、アプリケーションを記述どおりに格納します。これはフローについてフローが下書きにどう書き込まれるかで説明するとおりであり、Dify 独自の {{#…#}} 参照はエクスポートされたとおりにインストールに届きます。インストールは API サーバーのすべての接続(データベース、キャッシュ、ベクトルストア、サンドボックス、プラグインランタイム、エグレスプロキシ)を自ら配線するため、下書きは Component を下書きせず、何も配線しません。すべてのノードはアプリケーション内に残り、その決定にそのことが記録されます。その横の release.yaml は同じ名前の下書き Release で、インストールを境界 platform に配置し、アプリケーションが提供できないものを格納します。

インポートはワークスペースのカタログの Components を参照しますが、その Aggregates は参照しません。そのため、カタログが core/dify を保持しているかは確認せず、エントリの上のコメントにそのことが記されます。core/dify が実行する API サーバー core/ai-agent/dify をカタログが保持していない場合、インポートは platform-not-in-catalog で警告し、それでもエントリを下書きします。

インストールのアプリケーションシークレット、つまり Dify がセッション Cookie の署名に使い、保存するモデルプロバイダーの認証情報の暗号化に使うキーは、core/dify の secret_key パラメーターで、デフォルト値はありません。そのためドラフトは独自の secret_key パラメーター(文字列、必須、1 文字以上、デフォルト値なし)を宣言し、書き出すすべての core/dify エントリにそれを渡して、Release がその parameters で満たせるようにします。Release がこれを未設定のままにしたビルドは、その名前を示して停止します。

アプリケーションは、インストールのオーナーアカウントのもとでインポートされます。このアカウントは、Release がインストールに対するルーティングエントリで指定します。インストールの api コンポーネントの infra.owner_email と、同じコンポーネントの owner_password スロット(core/referenced-secret として付与)であり、これらがないとビルドは停止します。オーナーのメールアドレスはどのソースからも提供できないため、それが何であるかを示すコメントの下に空で書かれ、インポートはそれを未提供の値として報告します。

すべてのターゲットで、同じルーティングエントリはインストールの api、worker、scheduler コンポーネントで infra.marketplace_enabled を true に設定し、それぞれ理由を示すコメントの下に書かれます。Release が許可しない限りインストールは Dify のベンダーのどこにも到達せず、3 つはそれぞれ自身の設定を読み取り、Dify はアプリケーションのモデル(OpenAI のものなど)を提供するプラグインをそのプラグインマーケットプレイスからインストールするためです。

アプリケーションシークレットとオーナーのパスワードはシークレットであり、インポートのターゲットに応じて参照として下書きされます。

  • --target helm では、それぞれが名前空間にすでに存在する Kubernetes の Secret を指定します。secret_key は Secret の名前で、core/dify はそれをデータキー secret-key で読み取ります。owner_password はデータキー value にパスワードを保持する Secret です。どちらの名前もどのソースからも提供できないため、それぞれが何であるかを示すコメントの下に空で書かれ、インポートは両方を未提供の値として報告します。下書きされた Manifest は core/referenced-secret を helm/k8s-existing-secret にマッピングします。
  • その他のすべてのターゲットでは、またターゲットがない場合も、それぞれが変数への参照になります。secret_key は "${DIFY_SECRET_KEY}"、オーナーのパスワードは "${DIFY_OWNER_PASSWORD}" で、これらは標準カタログの Compose 向け Dify Recipes が読み取る名前です。Docker Compose はスタックの起動時にこれらを環境から読み取るため、どちらについても提供すべき値はありません。--target compose では、下書きされた Manifest は core/referenced-secret を compose/dotenv-referenced-secret にマッピングします。

ターゲットが与えられると、Manifest は、ターゲットが追加するもので説明するとおり、インストールが構成する各コンポーネントの型と、下書き自身の型をマッピングします。

このインポーターのテストがインポートする、Support Answers という名前の作成済みのワークフローアプリケーションは、設定なしで次のように下書きされます。

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support-answers
version: 0.1.0
description: Draft Aggregate imported from a source in the dify format.
spec:
parameters:
secret_key:
type: string
required: true
minLength: 1
description: "Passed down to core/dify's secret_key parameter, which has no default; that parameter's description in core/dify says what the value is."
aggregates:
# An import sees the Components of the workspace's catalog and none of its Aggregates, so it does not check that the catalog holds core/dify.
dify:
type: core/dify
parameters:
secret_key: "{{ .parameters.secret_key }}"
app_definition: |
app:
description: Answers a support question from a knowledge base and files it.
...

--target helm でインポートすると、下書きされた Release は secret_key を満たし、インストールを配置するルーティングエントリでオーナーを指定してプラグインマーケットプレイスを有効にします。未提供の値はそれぞれ空で書かれます。

release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/support-answers
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the dify format.
spec:
aggregate: imported/support-answers
manifest: imported/support-answers
parameters:
# Left for the Release, since the source cannot supply it: secret_key, which the drafted Aggregate declares and passes down to core/dify; that parameter's description there says what the value is
secret_key: ""
boundaries:
platform:
aggregates:
dify:
components:
api:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true
# Left for the Release, since the source cannot supply it: components.api.infra.owner_email, the email of the installation's owner account the application is imported under, on the api component of core/dify
owner_email: ""
features:
owner_password:
type: core/referenced-secret
infra:
# Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding, under the data key value, the owner account's password.
origin: ""
worker:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true
scheduler:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true

インポートは 3 つの空の値を未提供の値として報告します。--target compose でインポートすると、同じ Release は secret_key: "${DIFY_SECRET_KEY}" と origin: "${DIFY_OWNER_PASSWORD}" を書き、オーナーのメールアドレスだけを未提供の値として報告します。また、api コンポーネントに infra.published_port として 5001 を、フロントエンドである console コンポーネントに 3001 を書きます。それぞれ、このマシン上で動作する任意のプロセスからのみ到達可能であること、そしてその行を削除するとサービスが内部に留まることを示すコメントの下に書かれます。さらに、api コンポーネントのポートの下に、コンソールが公開されるアドレス "http://127.0.0.1:3001" を値とする infra.console_url を書き、Dify サーバーはこれをコンソールのアドレスとして使用します。Dify インポートのウォークスルーでは、両方のターゲット向けにアプリケーションをビルドし、Kubernetes 上で実行します。

Dify が自ら設定するもの

Dify は、アプリケーションが呼び出すモデルとツールのプロバイダーを自身の内部で設定し、 core/ai-agent/dify はモデル用のソケットを宣言しないため、下書きは何も配線しません。それらを指定する各ノードは、指定する内容に応じて part-configured-in-platform で報告され、その決定にも記録されます。

  • llm、question-classifier、parameter-extractor ノード、およびチャットアプリケーションの model_config.model:モデルを、その名前とプロバイダーで示します。
  • tool ノード、およびチャットアプリケーションのツール:ツールを、その名前とプロバイダーで示します。
  • agent ノード:エージェント戦略と、それを提供するプラグインを示します。
  • knowledge-retrieval ノード、およびチャットアプリケーションのナレッジベース:取得元のナレッジベースと、指定されている場合はクエリのルーティングまたはリランクに使うモデルを示します。アプリケーションは、エクスポート元のインストールの識別子でナレッジベースを指定し、そのドキュメントもストアも格納しません。そのため、それぞれは Dify 内で、インストールが API サーバーに配線するベクトルストアに作成します。
  • 依存関係:プラグインを、Dify がインストールする際の識別子と、Dify のインストール元で示します。

それ以外のノードは、何も報告されずにアプリケーション内に保持されます。

アプリケーションが保持する認証情報の値

インポーターは、アプリケーションが記述する順序で次のものを特定します。

  • value_type が secret である各環境変数の値。Dify はこれを認証情報としてマークします。Dify のエクスポートは、シークレットを含めない限りこれを空で書き出します。
  • HTTP リクエストノードの authorization.config.api_key。Dify はこれを認証情報としてマークし、記述どおりにエクスポートします。
  • tool ノード、または agent ノードのツールが credential_id の下で選択する保存済み認証情報。Dify はこれを認証情報としてマークし、エクスポートにシークレットが含まれる場合にのみ書き出します。
  • HTTP リクエストノードの headers と params(それぞれ全体)。Dify はこれらを認証情報としてマークしませんが、認証情報を含むことがあります。

デフォルトでは、値を保持するそれぞれはアプリケーション内に記述どおりに格納され、credential-carried 警告でそのノード(環境変数の場合は workflow)とフィールドによって示され、値によって示されることはありません。empty_credentials 設定が marked の場合、Dify が認証情報としてマークする各値が空で書き出され、all の場合はヘッダーとクエリパラメーターも空で書き出され、それぞれ credential-emptied で報告されます。1 つの変数参照だけからなる値は値を保持せず、フローの場合と同様に、設定にかかわらず記述どおりに格納され、警告で示されることはありません。値はアプリケーション自体のテキスト内で空にされます。キーの後のスカラーが '' に置き換えられ、それ以外は変更されません。アプリケーションが格納されるのは、parse:yaml を提供するパーサーが結果を読み戻したとき、それらの値だけが空にされたエクスポート済みアプリケーションと一致する場合に限られます。そうでない場合は格納されず、app_definition はコメント付きで未設定のままとなり、definition-not-carried がその理由を示します。たとえば、YAML エイリアスがシークレットの値を読むアプリケーションでは、その値を空にするとエイリアス側も変わってしまいます。設定によって記述どおりに残される値は書き換えられないため、アプリケーションの格納を妨げることはありません。

DSL のバージョン

アプリケーションが、Dify 1.17.0(core/ai-agent/dify がデフォルトで実行するバージョン)が書き出すバージョン 0.7.0 より新しい DSL で記述されている場合、インポートは dsl-version-newer で警告します。Dify はそのようなアプリケーションのインポートを確認待ちにし、デプロイ時にインポートするステップがその確認を与えます。そのため、Release が実行する Dify のバージョンに対してアプリケーションを確認してください。

読み取る設定

Dify インポーターは、設定で説明する target_namespace、empty_credentials、layout、attach_egress_allowlist、render_mode を読み取ります。また reuse_mode、reuse_threshold、emit_hints、mapping_overrides も読み取りますが、これらはデフォルトのレイアウトが下書きする内容を何も変えません。すべてのノードはアプリケーション内に残ります。構成された Aggregate のエントリはパラメーターを受け取り Feature を受け取らないため、attach_egress_allowlist は何もアタッチせず、これが true の場合、インポートは feature-not-attached で警告します。layout: nodes は、ノードごとで説明するとおり各ノードを独立した Component として下書きし、アプリケーションを格納しません。

CrewAI インポーター

importer/crewai は、CrewAI プロジェクトが設定ファイルで宣言するエージェントとタスクを読み取り、標準ライブラリの CrewAI エージェント core/ai-agent/crewai のインスタンスをエージェントごとに 1 つ保持する Aggregate をドラフトします。各インスタンスは設定が指定するモデルに配線され、その隣に Release もドラフトされます。

読み取るもの

CrewAI はクルーの振る舞いをプログラム内に保持し、エージェントとタスクを 2 つのレイアウトのいずれかで設定ファイルに宣言します。インポーターはどちらも読み取ります。

  • クラシックプロジェクト — 各エージェントを名前でキーにした config/agents.yaml と、各タスクを名前でキーにした config/tasks.yaml で、どちらも YAML として読み取られます。エージェントは agents.yaml に書かれた順に読み取られます。
  • JSON ファーストのレイアウトのプロジェクト — クルーのエージェントを agents の下に名前で、タスクを tasks の下に列挙する crew.jsonc と、エージェントごとに 1 ファイルの agents/<name>.jsonc で、いずれもコメント付き JSON として読み取られるため、コメントと末尾のカンマは CrewAI が読むとおりに読み取られます。エージェントは crew.jsonc が列挙する順に読み取られ、その後にその他のエージェントのファイルが名前順に続きます。クルーが列挙していても、そのファイルがインポートに渡されなかったエージェントは、コメントで名前が示され、何もドラフトされません。 同じレイアウトを厳密な JSON で書いたもの — crew.json と agents/<name>.json — も同じように読み取られます。クルーまたはエージェントが両方の形式で書かれている場合は、CrewAI が読むとおり .jsonc ファイルが読み取られ、.json ファイルは読み取られなかったものとしてコメントで名前が示されます。

エージェントについては、role、goal、backstory、宣言の最上位または settings の下にある allow_delegation と verbose(CrewAI が読むとおり settings が優先されます)、llm、そして tools の名前を読み取ります。タスクについては、その名前と割り当てられたエージェントを読み取ります。その他のメンバーはすべてコメントで名前が示され、どこにも引き継がれません。

ディレクトリは、そのシグネチャが指定するファイルだけとしてインポーターに渡されるため、クルーのプログラム — クラシックプロジェクトの crew.py、フローの main.py、プロジェクトが Python で定義するツール — が読み取られることはありません。単独でインポートされたファイルは、その形が示す宣言として読み取られます。プロジェクトのディレクトリは複数のクルーを保持でき、それぞれが自身のディレクトリから読み取られます。

プロジェクトが何になるか

aggregate.yaml は、ドラフトの命名方法で説明するとおりクルーにちなんで名付けられたドラフト Aggregate で、読み取った宣言、クルーのプログラムは読み取られないこと、そして各クルーのタスクとそれぞれが割り当てられたエージェントを示すコメントで始まります。エージェントごとに、その名前をキーとして、次の内容を持つ core/ai-agent/crewai のインスタンスを保持します。

  • 宣言どおりの role、goal、backstory。
  • 宣言どおりの allow_delegation。エージェントが宣言していない場合は false。
  • log_level。verbose と宣言されたエージェントには推論の各ステップを語る DEBUG、そうでないエージェントには進捗と問題のみを報告する INFO。true でも false でもない verbose または allow_delegation は Component のデフォルトに任され、コメントで名前が示されます。
  • その model 接続。llm が指定するモデルのインスタンスに配線されます。

<provider>/<model> と書かれた llm、またはモデルを model、model_name、deployment_name のいずれかで指定するオブジェクトとして書かれた llm は、プロバイダーとモデルを指定します。モデルは、そのプロバイダーに対応するカタログの Component(core/ai-model/<provider>。プロバイダー名のアンダースコアはハイフンとして読まれ、azure は azure-openai として読まれます)のインスタンスで、モデル名をキーとし、モデルを values.model として持ちます。同じプロバイダーとモデルを指定するエージェントは、1 つのインスタンスを共有します。ワークスペースのカタログにその名前の Component がない場合は、model 値を宣言する <target_namespace>/ai-model/<provider> が 1 つ下書きされ、その判断にその旨が記されます。エージェントの model ソケットが Component を選択する際に使う model.aggrega.ai/api ラベルと、そのエンドポイントとモデルを公開する Recipe は、冒頭のコメントにあるとおり、利用者に委ねられます。プロバイダーを指定しないもの(CrewAI がプログラムの実行時にプロバイダーを解決する素のモデル名、またはプログラムが定義する llm の名前、つまりプログラム内への参照)と、llm を宣言しないエージェント(CrewAI はその場合、プログラムが実行される環境から読み取ります)は、何にも接続されず、エージェントの上のコメントにその理由が記されます。いずれかが接続されるまで、ビルドは model ソケットを指摘して停止します。

タスクはクルーのプログラムが実行するロジックであり、ツールはプログラムが定義またはロードするコードです。どちらも Component にはなりません。それぞれは何も選択しない決定で報告され、名前 — 末尾の Tool、ハイフン、アンダースコアを除いたもの — がカタログにあるツール Component の名前であるツールは、その Component をヒントとして持ちます。search_tool と SearchTool はどちらも core/ai-tool/search をヒントとします。core/ai-agent/crewai はツール用のソケットを宣言しないため、ツールには何も配線されません。

その隣の release.yaml は、その Aggregate を指定する同名のドラフト Release です。各エージェントの infra.image(どの宣言も指定しない、クルーのプログラムを実行するイメージ)を、それが何であるかを示すコメントの下に空で書き、インポートはそれを未提供の値として報告します。--target compose の場合、各エージェントのエントリは infra.published_port として 8000 も書きます。これは Component の infra.port がプログラムに対してデフォルトで指定するポートで、その Compose の Recipe がホストのループバックアドレス 127.0.0.1 上に公開するものです。このマシン上で動作する任意のプロセスからのみ到達可能であること、そしてその行を削除するとサービスが内部に留まることを示すコメントの下に書かれます。2 つ目のエージェントは次の空きポートを使うため、クラシックプロジェクトの 2 つのエージェントは 8000 と 8001 で公開されます。各エージェントがモデルに提示する資格情報は、model 接続の credential の下に、値としてではなく参照として付与します。どの宣言もその変数を指定しないため、プロバイダーのクライアントライブラリが API キーを読み取る変数(OpenAI の場合は OPENAI_API_KEY)から読み取られます。helm 以外のすべてのターゲットでは ${…} 参照として、helm では Kubernetes の Secret の名前として書かれ、後者は空で書かれてインポートが未提供の値として報告します。compose では、エージェントの model 接続がそのキーでそれを宣言します。各モデルにもインフラを保持しないエントリがあり、それによって Release はモデルをエージェントと一緒に配置します。llm オブジェクトとして宣言されたモデルについては、その他の各メンバーは、カタログの Component がその名前の値を宣言している場合はモデルのインスタンスの値として書かれ、そうでない場合は Release のモデルのエントリの上のコメントに書かれ、Component がそれを受け取る場所に利用者が引き継げるようになっています。下書きされるすべての Release と同様に、metadata.environment を development として書き、ターゲットがない場合はインポートが未提供の値として報告する空の spec.manifest を書きます。ターゲットが与えられた場合は、ターゲットが追加するもので説明するとおり、インポートが Manifest を下書きします。

このインポーターのテストがインポートするクラシックプロジェクト(2 つのエージェントがどちらも openai/gpt-4o を指定)は、設定なしで以下のようにドラフトされます。プロジェクトディレクトリ market_brief(crewai create crew market_brief がこのようなプロジェクトを配置するディレクトリ)としてインポートすると、宣言がクルーを指定していないため、そのディレクトリにちなんで名付けられます。

aggregate.yaml
# CrewAI declarations read:
# - src/market_brief/config/agents.yaml
# - src/market_brief/config/tasks.yaml
# Not read: the crew's program, which runs its agents and its tasks and defines its tools; it runs in the image the Release names for each agent.
# Tasks the crew's program runs, drafted as no Component:
# - research_task, assigned to researcher
# - brief_task, assigned to brief_writer
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/market-brief
version: 0.1.0
description: Draft Aggregate imported from a source in the crewai format.
spec:
components:
# Tools the crew's program defines or loads for this agent, drafted as no Component: search_tool.
researcher:
type: core/ai-agent/crewai
values:
role: "{topic} Market Researcher\u000A"
goal: "Gather the facts about {topic} a buyer needs before a first meeting\u000A"
backstory: "You have briefed sales teams for years. ..."
allow_delegation: false
log_level: DEBUG
uses:
model:
gpt-4o:
target: gpt-4o
# For the compose target only, uncomment the lines below, which declare credential on gpt-4o: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: OPENAI_API_KEY
# The agent brief_writer.
# Not carried, since core/ai-agent/crewai takes no value for it: max_iter.
brief-writer:
type: core/ai-agent/crewai
...
# The model openai/gpt-4o.
gpt-4o:
type: core/ai-model/openai
values:
model: "gpt-4o"

そして、ターゲットなしで下書きされたその Release は以下のとおりです。2 番目のエージェントのエントリはここでは省略し ... で示しています。インポートは spec.manifest と各エージェントのイメージを未提供の値として報告します。

release.yaml
spec:
aggregate: imported/market-brief
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
researcher:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the crew's program
image: ""
uses:
model:
gpt-4o:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential researcher presents to gpt-4o on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
brief-writer:
...
gpt-4o: {}

各エージェントは、回答したイメージを実行するようにレンダリングされ、モデルのエンドポイントとモデル名が、CrewAI が読み取る変数である OPENAI_BASE_URL と MODEL として渡されます。

宣言が保持する資格情報の値

オブジェクトとして書かれた llm はキーを保持できます — api_key の下、アドレス内、ヘッダー内などです。モデルを指定するメンバー以外で、数値でもブール値でもない各メンバーは資格情報を保持しうる値であり、CrewAI はそれを資格情報としてマークしません。デフォルトでは、値を持つものはそれぞれ書かれたとおり引き継がれ(Component が値を宣言している場合はモデルのインスタンスの値として、そうでない場合は Release のモデルのエントリの上のコメントに)、credential-carried 警告でそのエージェントとメンバー(llm.api_key など)によって名前が示され、値で示されることはありません。empty_credentials 設定が all の場合、それぞれ値なしで書かれ、credential-emptied で報告されます。marked の場合は、CrewAI が何もマークしないため、それぞれ引き継がれます。メンバー名がその意味のために読まれることはありません。宣言が保持し、ドラフトが引き継がないその他のメンバー — ツールの設定、クルーの inputs — は、名前が示されるだけで、値は示されません。

読み取る設定

CrewAI インポーターは、設定で説明する target_namespace、empty_credentials、render_mode を読み取り、その他の設定は読み取りません。

LangGraph インポーター

importer/langgraph は、LangGraph アプリケーションの設定 langgraph.json が宣言するグラフを読み取り、標準ライブラリの LangGraph エージェント core/ai-agent/langgraph のインスタンスをグラフごとに 1 つ保持する Aggregate をドラフトします。各インスタンスは、そのチェックポインターが状態を保持するデータストアと、モデルに接続されます。あわせて、設定が記述する環境を持つ Release をその横にドラフトします。読み取るのはその設定であり、グラフのコードは決して読み取りません。

読み取るもの

LangGraph アプリケーションはグラフをコードに保持し、langgraph.json で宣言します。graphs の下で、各グラフの id は、アプリケーションのコード内にあるグラフのインポートパス(./src/agent/graph.py:graph または module:attr)に対応するか、そのパスを path の下に記し、グラフの説明を description の下に記すオブジェクトに対応します。インポーターは、設定が記述する順に次のものを読み取ります。

  • graphs — 各グラフの id、インポートパス、説明。
  • checkpointer — その backend。default は PostgreSQL で、何も指定されていない場合に LangGraph が読み取るものです。mongo は MongoDB のプロトコルを話すデータベースです。custom は、アプリケーションのコードが path で定義するチェックポインターです。
  • store — メモリストア。バックエンドは指定しません。LangGraph はこれを、サーバーが使用する PostgreSQL データベースに保持します。
  • env — アプリケーションが実行される環境。変数名から値へのオブジェクト、または KEY=VALUE 行からなる環境ファイルのパスです。

langgraph build がビルドするサーバーイメージを設定するメンバー(dependencies、source、python_version、node_version、base_image、image_distro、dockerfile_lines、pip_config_file、pip_installer、keep_pkg_tools、api_version)は、Release が指定するイメージはアプリケーション自身のものであるため、コメントで名前が示され、どこにも引き継がれません。その他すべてのメンバー(auth、http、webhooks などのサーバー自体の設定を含む)も同様であり、ストアの index と ttl、チェックポインターの ttl と serde も同様です。

ディレクトリは langgraph.json としてのみインポーターに渡され、他のファイルは渡されません。そのため、アプリケーションのコードも環境ファイルも、そこから読み取られることはありません。環境ファイルは、インポーターの with.sources が渡す場合にのみインポーターに届き、決してパースされません。設定の env が指定するもの(指定されたパスの最後のセグメントで照合されます)については変数の名前だけが読み取られ、どの設定も指定しない環境ファイルは、読み取られなかったものとしてコメントで名前が示されます。設定が指定するファイルがインポートに渡されなかった場合、Aggregate はそれを渡されなかったものとして名前を示し、インポーターの with.sources の下に指定するよう記します。その変数は Release に委ねられます。

plugins:
importer:
- uri: importer/langgraph:<version>
with:
sources:
- ./local.env

単独でインポートされた設定は、名前にかかわらず読み取られます。ディレクトリは複数のアプリケーションを保持でき、それぞれ独自のディレクトリから読み取られます。

アプリケーションがどうなるか

aggregate.yaml は、ドラフトの命名方法で説明するとおりグラフにちなんで名付けられたドラフト Aggregate で、読み取った設定、名前のためだけに読み取った環境ファイル、アプリケーションのコードを読み取っていないこと、ドラフトが引き継がないものを示すコメントで始まります。グラフごとに、その id をキーとして、次のものを持つ core/ai-agent/langgraph のインスタンスを保持します。

  • graph_entrypoint。設定が記述するとおりのグラフのインポートパス。
  • description。設定が指定している場合のグラフの説明。
  • アプリケーションのデータストアに接続された checkpointer_db 接続。
  • アプリケーションのモデルに接続された model 接続。

recursion_limit は書かれないため、Component のデフォルト値 25 が適用されます。設定はモデルを指定しないため、ドラフトは model をキーとする core/ai-model/openai のインスタンスを 1 つ保持し、すべてのグラフがそれを呼び出します。これはエージェントの OpenAI クライアントに渡されるモデルです。その values.model は、設定がモデルを指定していないことを示すコメントの下に空で書かれ、インポートはそれを未提供の値として報告します。

チェックポインターのバックエンドは、アプリケーションのすべてのグラフが接続されるデータストアです。default、またはバックエンドを指定しないチェックポインターは、postgres をキーとする core/datastore/postgres のインスタンスになります。mongo は FerretDB で、MongoDB のプロトコルを話し、DocumentDB 拡張を備えた PostgreSQL 上で動作します。すなわち、すべてのグラフが接続される ferretdb をキーとする core/datastore/ferretdb のインスタンスと、FerretDB の backend 接続が到達する documentdb をキーとする core/datastore/documentdb のインスタンスであり、その inject ブロックは DocumentDB が公開するものを FerretDB が読み取る名前で渡します。変数 FERRETDB_PASSWORD から読み取られる 1 つのパスワードが、DocumentDB、FerretDB からそれへの接続、および各グラフから FerretDB への接続に付与されます。ワークスペースのカタログに PostgreSQL データストアの名前の Component がない場合は、エージェントの checkpointer_db 接続が読み取る host と port を宣言する <target_namespace>/datastore/postgres がドラフトされ、そのデシジョンにその旨が記されます。データストアを実行してそれらを公開する Recipe は、冒頭のコメントが示すとおり利用者に委ねられます。カタログに FerretDB または DocumentDB の Component がない場合、mongo チェックポインターはどのデータストアにも接続されません。custom チェックポインター、またはインポーターがどのデータストアにも対応付けないバックエンドは何も接続せず、各グラフの上のコメントとチェックポインターのデシジョンがその理由を示します。接続されるまで、ビルドは checkpointer_db ソケットを示して停止します。ストアは、何も選択しないデシジョンで報告されます。

データストアのパスワードは、ドラフトが参照として付与するシークレットで、データストア自身の password スロットと各グラフの checkpointer_db 接続に付与されます。各グラフが model 接続でモデルに提示する資格情報も同様です。設定はどちらについても変数を指定しないため、それぞれ POSTGRES_PASSWORD(または FERRETDB_PASSWORD)と OPENAI_API_KEY から読み取られ、helm 以外のすべてのターゲットでは ${…} 参照として、helm では Kubernetes の Secret の名前として書かれ、後者は空で書かれてインポートが未提供の値として報告します。compose では、プラットフォームについてターゲットごとのシークレットで説明するとおり、Aggregate がそれぞれをその Recipe が読み取るキーで宣言します。

その横の release.yaml は、同じ名前でその Aggregate を指定するドラフト Release です。最初のグラフのエントリの上のコメントは、各グラフのイメージが何であるか(アプリケーション自身のもの、つまり LangGraph がインストールされたそのコードであり、langgraph build がビルドするサーバーイメージではありません)、それに渡される変数、そしてどの inject: ブロックがどの変数名を置き換えるかを示します。各グラフのエントリは、その infra.image、つまりアプリケーションを実行するイメージを、それが何であるかを示すコメントの下に空で書き、インポートはそれを未提供の値として報告します。それが未設定の間、Docker Compose の Recipe はカタログ自身のクイックスタートエージェントを実行し、これはデフォルトの変数を読み取ります。--target compose の場合、各グラフのエントリは infra.published_port として 8000 も書きます。これは Component の infra.port がアプリケーションに対してデフォルトで指定するポートで、その Compose の Recipe がホストのループバックアドレス 127.0.0.1 上に公開するものです。このマシン上で動作する任意のプロセスからのみ到達可能であること、そしてその行を削除するとサービスが内部に留まることを示すコメントの下に書かれます。2 つ目のグラフは次の空きポートを使います。データストアとモデルにもエントリがあるため、Release はそれらをグラフと一緒に配置します。アプリケーションの最初のグラフの上のコメントは、設定が記述する環境で説明するとおり、設定が宣言する環境を記述します。下書きされるすべての Release と同様に、metadata.environment を development として書き、ターゲットがない場合はインポートが未提供の値として報告する空の spec.manifest を書きます。ターゲットが与えられた場合は、ターゲットが追加するもので説明するとおり、インポートが Manifest を下書きします。

このインポーターのテストがインポートする Python アプリケーションは、2 つのグラフ、バックエンドを指定しないチェックポインター、ストア、オブジェクトとして書かれた env を宣言しており、設定なしで以下のようにドラフトされます。ディレクトリ support_desk(ここでのように、グラフが定義されているパッケージにちなんで名付けられたもの)としてインポートすると、id の異なる 2 つのグラフを持つため、そのディレクトリにちなんで名付けられます。

aggregate.yaml
# LangGraph configurations read:
# - langgraph.json
# Not read: the application's code, which defines each graph; it runs in the image the Release names for each graph.
# Not carried, since they configure the server image langgraph build builds, and the image the Release names is the application's own: dependencies, python_version.
# Not carried, since core/ai-agent/langgraph takes no value for them: http.
# The store configures the memory store, which LangGraph keeps in the PostgreSQL database its server uses; not carried, since core/ai-agent/langgraph takes no value for it: index, ttl.
# Not carried, since core/ai-agent/langgraph takes no value for them: checkpointer.ttl.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support-desk
version: 0.1.0
description: Draft Aggregate imported from a source in the langgraph format.
spec:
components:
triage:
type: core/ai-agent/langgraph
values:
graph_entrypoint: "./src/support_desk/triage.py:make_graph"
description: "Routes an incoming ticket to the {team} that owns it."
uses:
checkpointer_db:
postgres:
target: postgres
# For the compose target only, uncomment the lines below, which declare credential on postgres: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: POSTGRES_PASSWORD
model:
model:
target: model
# For the compose target only, uncomment the lines below, ...
support:
type: core/ai-agent/langgraph
...
# The database the configuration's checkpointer keeps each graph's state in, PostgreSQL.
postgres:
type: core/datastore/postgres
# For the compose target only, uncomment the lines below, ...
# The model every graph calls, which the configuration does not name.
model:
type: core/ai-model/openai
values:
# Left for the author, since the configuration names no model: values.model, the name of the model core/ai-model/openai serves.
model: ""
release.yaml
spec:
aggregate: imported/support-desk
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# Each graph's image is the application's own, not the server image langgraph build builds: its code, with LangGraph installed.
# It is handed, for its code to read, the graph to run as LANGGRAPH_GRAPH_ENTRYPOINT, the model's name as OPENAI_MODEL, the checkpointer store's host and port as LANGGRAPH_CHECKPOINTER_HOST and LANGGRAPH_CHECKPOINTER_PORT, its user and database, where the store publishes them, as LANGGRAPH_CHECKPOINTER_USER and LANGGRAPH_CHECKPOINTER_DATABASE, and a password attached on the checkpointer_db connection as LANGGRAPH_CHECKPOINTER_PASSWORD.
# It is also handed the model's address as OPENAI_BASE_URL and a key attached on the model connection as OPENAI_API_KEY, which the OpenAI client library reads, and recursion_limit as LANGGRAPH_DEFAULT_RECURSION_LIMIT, which LangGraph reads.
# An inject: block on the graph's own instance, through an entry reading graph_entrypoint alone, replaces LANGGRAPH_GRAPH_ENTRYPOINT with the name it writes; one on the model connection replaces OPENAI_MODEL, and one on the checkpointer_db connection the store's host, port, user and database, with the names it writes.
# The environment langgraph.json states for its application, for the Release to carry where core/ai-agent/langgraph takes it for each of its graphs:
# SUPPORT_QUEUE: "..."
# OPENAI_API_KEY: "..."
# MAX_TICKETS: "25"
triage:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application
image: ""
uses:
checkpointer_db:
postgres:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential triage presents to postgres on its checkpointer_db connection, the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${POSTGRES_PASSWORD}"
model:
model:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential triage presents to model on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
...
postgres:
features:
password:
type: core/secret-value
infra:
# Attached by reference, never as a value: the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${POSTGRES_PASSWORD}"
model: {}

インポートは 4 つの値を未提供の値として報告します。spec.manifest、各グラフのイメージ、そしてモデルの名前です。これらに回答すると、各グラフは回答したイメージを実行し、データストアのアドレスを LANGGRAPH_CHECKPOINTER_HOST と LANGGRAPH_CHECKPOINTER_PORT として、データストアが公開するユーザーとデータベースを LANGGRAPH_CHECKPOINTER_USER と LANGGRAPH_CHECKPOINTER_DATABASE として(PostgreSQL は両方を公開し、どちらも公開しないデータストアではどちらの変数もレンダリングされません)、モデルのエンドポイントと名前を OPENAI_BASE_URL と OPENAI_MODEL として、モデルの認証情報が渡すキーを OPENAI_API_KEY として、インポートパスを LANGGRAPH_GRAPH_ENTRYPOINT として、ステップ上限を LANGGRAPH_DEFAULT_RECURSION_LIMIT として受け取るようにレンダリングされます。checkpointer_db 接続に付けられた認証情報は、データストアのパスワードも LANGGRAPH_CHECKPOINTER_PASSWORD として渡します。

設定が記述する環境

設定の env が指定するすべての変数は Release が指定する入力であり、いずれもクレデンシャルスロットとしてはドラフトされません。LangGraph はどの変数もシークレットとしてマークせず、変数の名前はその意味のためには読み取られません。core/ai-agent/langgraph は環境の値を受け取らないため、Release はアプリケーションの最初のグラフの上のコメントにそれを記述します。

  • オブジェクトとして書かれた env は設定の一部であるため、その値は設定が記述する順に、書かれたとおりそのコメントに引き継がれます。何かを保持する各値はクレデンシャルを含みうるもので、LangGraph はそれをクレデンシャルではないとマークします。デフォルトでは、各値は書かれたとおり引き継がれ、credential-carried 警告で、その値ではなく設定と変数(env.OPENAI_API_KEY など)によって名前が示されます。empty_credentials 設定が all の場合、各値は値なしで書かれ、credential-emptied で報告されます。marked の場合は、LangGraph が何もマークしないため、各値が引き継がれます。
  • ファイルを指定する env は、設定が指し示すだけのファイルを指定します。このファイルには通常ローカルのシークレットが含まれます。インポーターの with.sources が渡す場合にのみ読み取られます。コメントは、ファイルが指定する各変数の名前を Release が指定するものとして示し、ファイルの値は一切読み取られません。設定にかかわらず、値がドラフト、デシジョン、診断に届くことはありません。複数行にわたって引用された値は 1 つの値であるため、その内部の行が変数と見なされることはなく、変数を指定しない行は行番号で示されます。インポートにファイルが渡されなかった場合(ディレクトリは決してファイルを渡さないため、ディレクトリでは常にそうなります)、Aggregate はそれを渡されなかったものとして渡し方とともに名前を示し、その変数は Release に委ねられます。

読み取る設定

LangGraph インポーターは、設定で説明する target_namespace、empty_credentials、render_mode を読み取り、それ以外の設定は読み取りません。

Google ADK インポーター

importer/google-adk は、Google の Agent Development Kit (ADK) 上に構築されたアプリケーションが Agent Config ファイル(root_agent.yaml とそのサブエージェントが指定する設定)で宣言するエージェントを読み取り、標準ライブラリの ADK エージェント core/ai-agent/google-adk のインスタンスをエージェントツリーごとに 1 つ持つ Aggregate(ツリーが指定するモデルのリクエストを ADK が Gemini API に送る場合は、そのモデルに接続されます)と、その横に Release を下書きします。読み取るのはそれらの設定であり、アプリケーションのコードは決して読み取りません。

ADK は、その Agent Config 機能が実験的であると明記しています。エージェントのモデルはデフォルトで Gemini モデルです。ADK は、他の一部のプロバイダーのモデルを claude-sonnet-4-5 や gpt-4o のように独自のクラスを通じて名前で提供し、それ以外は LiteLLM のモデル文字列を介して提供します。エージェントの model ソケットは Gemini API のみを受け付けるため、インポーターは ADK が Gemini API に送るモデルを接続し、それ以外は利用者に委ねます。エージェントツリーがどうなるかで説明するとおりです。

読み取るもの

ADK の adk create --type=config は、アプリケーションのルートエージェントの設定である root_agent.yaml と、その横に環境ファイルを書き出します。1 つの設定は 1 つのエージェントを宣言します。

  • name、description、agent_class:ADK がエージェントを構築するクラスで、何も指定されていない場合は LlmAgent です。
  • model:エージェントが求めるモデル。または model_code:そのモデルを構築するコードへの参照。
  • tools:各ツールを name で指定し、設定がそのツールに渡す args を伴います。
  • generate_content_config:エージェントのモデルリクエストのオプションで、http_options を含みます。
  • sub_agents:それぞれが config_path(それを指定する設定のディレクトリからの別の設定のパス)、または code(アプリケーションのコードが構築するエージェント)です。

ディレクトリはその root_agent.yaml ファイルとしてのみインポーターに渡され、他のファイルは渡されません。単独でインポートされた設定は、名前にかかわらずルートとして読み取られます。各ルートのツリーはルートから順に読み取られ、各エージェントのサブエージェントはそれが列挙する順に読み取られます。sub_agents のエントリが config_path で指定する設定は、インポーターの with.sources がそれを渡す場合にのみ読み取られ、パスの最後のセグメントで照合されます。インポートに渡されなかった設定は、Aggregate とその決定の中で渡されていないものとして、渡し方とともに示され、そのエージェントは読み取られません。

plugins:
importer:
- uri: importer/google-adk:<version>
with:
sources:
- ./my_agent/code_tutor_agent.yaml
- ./my_agent/math_tutor_agent.yaml

絶対パスである config_path、またはそれを指定する設定のディレクトリの外に出るものは、ADK も拒否するため読み取られません。どの設定も指定しない、with.sources が渡すファイルは、読み取られなかったものとしてコメントで示され、その内容は一切読み取られません。渡されたファイルは、ルートのツリーが指定する設定としてのみ読み取られます。そのため、root_agent.yaml も単独でインポートされたファイルも持たないインポートはツリーを読み取らず、各ファイルを no-nodes の下で報告します。アプリケーションのコード(設定がコードによって指定するツール、コールバック、スキーマ、エージェント)と環境ファイルは決して渡されず、インポーターはどちらも読み取りません。アプリケーションは、Release が指定するイメージから自身の設定を自ら読み込みます。ディレクトリは複数のアプリケーションを保持でき、それぞれ独自の root_agent.yaml から読み取られます。

設定のその他のメンバー(エージェントの instruction を含む)は、アプリケーションが自身の設定から読み取るため、下書きはそのいずれも保持しません。

エージェントツリーが何になるか

ADK はアプリケーションをそのルートエージェントから提供し、設定が指定するすべてのエージェントはその中で構築されます。core/ai-agent/google-adk はそのようなアプリケーションを 1 つ実行します。そのため、ドラフトの命名方法で説明するとおりルートエージェントにちなんで名付けられた下書き Aggregate である aggregate.yaml は、エージェントツリーごとに、ルートエージェントの名前をキーとして、次の内容を持つ core/ai-agent/google-adk のインスタンスを保持します。

  • description:ルートエージェントの説明(その設定が説明を与えている場合)。
  • model 接続:ADK がそのリクエストを Gemini API に送信する場合に、ツリーが指定するモデルに接続されます。

その上のコメントには、独自のインスタンスにならないツリーの他のエージェント、読み取られない各サブエージェントとその理由(アプリケーションのコードで構築されるもの、インポートに渡されなかった設定、または ADK が拒否するもの)、ツリーのエージェントが指定するツール(ADK が同梱するものとアプリケーションのコードが定義するもの)、ADK が Workflow を推奨して非推奨としているクラス(LoopAgent、ParallelAgent、SequentialAgent)のエージェント、そしてツリーのモデルが接続されている場合は、ツリーの他のエージェントが求めるモデルが、ADK がそれぞれを提供する経路となるファミリーとともに示されます。それぞれは何も選択しない決定として報告されます。

ルートから順に、モデルまたはモデルを構築するコードを指定するツリーの最初のエージェントが、インスタンスのモデルを決めます。指定されたモデルのうち ADK がそのリクエストを Gemini API に送信するもの、つまり ADK が Gemini クラスを通じて提供するモデル名(gemini-2.5-flash など。Vertex AI のリソース名は除きます)または Gemma クラスを通じて提供するモデル名は、そのモデルを提供しそれをキーとする core/ai-model/gemini のインスタンスとなり、同じモデルを指定するツリーは 1 つのインスタンスを共有します。ワークスペースのカタログに core/ai-model/gemini がない場合は、エージェントの model ソケットが選択する model.aggrega.ai/api: gemini ラベルを持つ <target_namespace>/ai-model/gemini が下書きされ、その決定でそのことが示されます。そのエンドポイントとモデルを公開する Recipe は、それを開くコメントが示すとおり、利用者に委ねられます。ADK がそれ以外の方法で提供するモデル(openai/gpt-4o のような LiteLLM のモデル文字列、Vertex AI のリソース名、または ADK が Anthropic や OpenAI を通じて提供する claude-sonnet-4-5 や gpt-4o のような名前)は何にも接続されません。エージェントの model ソケットは Gemini モデルを受け取り、エージェントは環境からモデル名を読み取らないため、そこに Gemini モデルを接続し、エージェントの設定でそのモデルを指定します。インスタンスの上のコメントとルートエージェントの決定には、そのモデルと、ADK がそれを提供する経路となるファミリーが示されます。アプリケーションのコードが構築するモデル、またはモデルを指定しないツリー(その場合 ADK は既定のモデルを使用します)も何にも接続されず、インスタンスの上のコメントがその理由を示します。モデルが何にも接続されていない場合は常に、接続されるまでビルドは model ソケットを示して停止します。ツリーの他のエージェントが求めるモデルのうち、ADK がそのリクエストを Gemini API に送信するものには独自の接続は不要です。ADK の Gemini クライアントが、インスタンスの接続が渡すキーでそのリクエストを送信するためです。アプリケーションが Gemini API と Vertex AI のどちらを通じて Gemini に到達するかはその環境によって選ばれ、インポートはそれを読み取りません。エージェントの model ソケットが受け入れるのは Gemini API のみです。

このインポーターのテストでは、openai/gpt-4o を指定する単独のルートエージェントもインポートしており、そのインスタンスは次のように下書きされます:

spec:
components:
# The agent tree of root_agent.yaml, served from its root agent routed_agent.
# The model connection is left for the author, since the model openai/gpt-4o, which routed_agent names, is one ADK serves through LiteLLM, not through the Gemini API, while core/ai-agent/google-adk takes a Gemini model on its model socket and reads no model name from its environment, so the author wires a Gemini model there and names that model in routed_agent's configuration; the build halts naming the socket until one is wired.
routed-agent:
type: core/ai-agent/google-adk
values:
description: "Answers questions with a model another provider serves."

その横の release.yaml は、同じ名前でその Aggregate を指定する下書き Release です。各インスタンスのエントリは、その infra.image(ADK 上に構築され、設定を保持するアプリケーションを実行するイメージ)を、それが何であるかを示すコメントの下に空のまま書き、インポートはそれを未回答の値として扱います。--target compose を指定すると、エントリは infra.published_port として 8000 も書きます。これはアプリケーションが待ち受けるポートで、その Compose Recipe がホストのループバックアドレス 127.0.0.1 で公開します。その上のコメントは、このポートにはこのマシンからのみ、そこで実行されている任意のプロセスから到達でき、この行を削除するとサービスが内部にとどまることを示します。2 つ目のツリーには次の空きポートが割り当てられます。モデルが接続されている場合、エントリはインスタンスがそのモデルに提示する資格情報を、model 接続の credential の下に、値としてではなく常に参照として付与します。どの設定もその変数を指定しないため、資格情報は Google の Gemini API クライアントライブラリがキーを読み取る変数 GOOGLE_API_KEY から読み取られます。helm 以外のすべてのターゲットでは ${…} 参照として、helm では Kubernetes Secret の名前として書かれ、空のまま書かれてインポートの未回答の値となります。compose では、model 接続がそのキーでそれを宣言します。接続されたモデルにもエントリがあり、インフラストラクチャを持たないため、Release はそれをインスタンスと同じ場所に配置します。ツリーの設定がツールとモデルリクエストに渡す値は、設定が保持する資格情報の値で説明するとおり、エントリの上のコメントに書かれます。下書きされるすべての Release と同様に、metadata.environment を development として書き、ターゲットがない場合はインポートの未回答の値となる空の spec.manifest を書きます。ターゲットが与えられた場合は、ターゲットが追加するもので説明するとおり、インポートが Manifest を下書きします。

このインポーターのテストがインポートするアプリケーション(2 つのサブエージェントの設定と、コードで構築される 1 つのサブエージェントを指定するルートエージェント)を、2 つの設定を with.sources に指定してそのディレクトリとしてインポートすると、設定なしで、ルートエージェントの名前 tutor_root のもとで次のように下書きされます。

aggregate.yaml
# Google ADK agent configurations read:
# - root_agent.yaml
# - code_tutor_agent.yaml
# - math_tutor_agent.yaml
# Not read: the application's code, which defines the tools, callbacks and agents a configuration names by their code, nor the environment file ADK's scaffold writes beside root_agent.yaml; the application runs in the image the Release names for each instance, and loads its configurations itself.
# ADK states that its Agent Config is experimental. An agent's model is a Gemini model by default; ADK serves some other providers' models by name through classes of its own, such as claude-sonnet-4-5 and gpt-4o, and others through a LiteLLM model string.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/tutor-root
version: 0.1.0
description: Draft Aggregate imported from a source in the google-adk format.
spec:
components:
# The agent tree of root_agent.yaml, served from its root agent tutor_root.
# Sub-agents ADK builds inside this application, drafted as no instance of their own: code_tutor_agent, math_tutor_agent.
# Not read: a sub-agent of tutor_root, which is built by the application's code at tutor_agents.review_agent, which the import does not read.
# Tools ADK ships, which run inside the application, drafted as no Component: google_search.
# Tools the application's code defines, drafted as no Component: tutor_tools.make_snippet_runner.
# Models other agents of the tree ask for, ...: gemini-pro-latest (math_tutor_agent, served through Gemini).
tutor-root:
type: core/ai-agent/google-adk
values:
description: "Learning assistant that tutors {{`{{`}} students }} in code and math."
uses:
model:
gemini-flash-latest:
target: gemini-flash-latest
# For the compose target only, uncomment the lines below, which declare credential on gemini-flash-latest: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: GOOGLE_API_KEY
# The model gemini-flash-latest.
gemini-flash-latest:
type: core/ai-model/gemini
values:
model: "gemini-flash-latest"

下書きが設定から Aggregate に値またはコメントとしてコピーするテキストでは、各 {{ を {{`{{`}}(結果が 2 つの波括弧となるアクション)として書きます。そのため、説明や、コメント内の 2 つの波括弧を含む名前は、Aggregate が評価されたときに書かれたとおりに読み戻されます。

release.yaml
spec:
aggregate: imported/tutor-root
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# The configurations also hand these values to their tools and their model requests, which the application reads from its own configurations, written here for review:
# code_tutor_agent tools.tutor_tools.make_snippet_runner.args.api_key: "..."
# code_tutor_agent tools.tutor_tools.make_snippet_runner.args.sandbox: "python3.12"
# code_tutor_agent tools.tutor_tools.make_snippet_runner.args.timeout_seconds: 20
# math_tutor_agent generate_content_config.http_options.headers: "..."
# math_tutor_agent generate_content_config.http_options.timeout: 30000
tutor-root:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on ADK, holding its configurations
image: ""
uses:
model:
gemini-flash-latest:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential tutor-root presents to gemini-flash-latest on its model connection (the source names no variable for it, so it is read from the one Google's Gemini API's client libraries read the API key from), read from the variable GOOGLE_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${GOOGLE_API_KEY}"
gemini-flash-latest: {}

イメージが回答されると、インスタンスはそれを実行するようにレンダリングされ、資格情報が GOOGLE_API_KEY として与えられます。ADK の Gemini クライアントはこれを Gemini API に送信します。モデルは Gemini API のアドレスに到達する Service としてレンダリングされます。

設定ファイルが保持する認証情報の値

設定ファイルは、ツールにはその args で、モデルリクエストにはその generate_content_config の http_options(ヘッダー、アドレス、クライアントの引数)で、キーを渡すことができます。ツールの args とその HTTP オプションの各メンバーは、Release 内のインスタンスのエントリーの上にあるコメントに、設定ファイルが記述したとおりに書き出されます。テキスト、オブジェクト、リストであるものはそれぞれ認証情報を保持し得ますが、ADK はどれも認証情報としてマークしません。そのため、デフォルトでは各値は記述どおりに保持され、credential-carried 警告の中で、値ではなく、エージェントとフィールド(tools.tutor_tools.make_snippet_runner.args.api_key など)によって名指しされます。empty_credentials 設定が all の場合、各値は値なしで書き出され、credential-emptied で報告されます。marked の場合は、ADK が何もマークしないため、各値は保持されます。数値やブール値はキーを保持しないため、設定ファイルが記述したとおりに書き出されます。ADK は設定ファイル内の変数参照を展開しないため、すべての値は記述どおりに読み取られます。ADK の Gemini クライアントが読み取るキーを一般に保持する環境ファイルは、設定の内容にかかわらず決して読み取られません。

読み取る設定

Google ADK インポーターは、Settings の説明どおりに target_namespace、empty_credentials、render_mode を読み取り、それ以外の設定は読み取りません。

Agent Framework インポーター

importer/agent-framework は、Microsoft Agent Framework の宣言型エージェント(Agent Framework 上に構築されたアプリケーションがエージェントを読み込む、kind が Prompt の YAML ドキュメント)を読み取り、標準ライブラリの Agent Framework エージェント core/ai-agent/agent-framework のインスタンスを 1 つ保持する Aggregate と、その隣の Release をドラフトします。このインスタンスは、宣言型エージェントが指定する OpenAI モデルに接続されます。読み取るのは宣言型エージェントであり、アプリケーションのコードは決して読み取りません。Agent Framework は、宣言型エージェントのパッケージをプレリリースとして公開しています。

読み取るもの

宣言型エージェントは次を宣言します。

  • name、displayName、description、その instructions、および入力と出力のスキーマ。
  • model:モデルの id、それを提供する provider、クライアントがリクエストを送信する API(apiType)、リクエストの options、およびその connection(key または apiKey の下に書かれたキーを endpoint に提示する key 接続、endpoint に到達する remote 接続、アプリケーションが解決する接続を指定する reference 接続、または何も提示しない anonymous 接続)。
  • tools:それぞれが次のいずれかの kind を持ちます。アプリケーションがコードをバインドする function、モデルのプロバイダーが実行する web_search、file_search、code_interpreter ツール、または url で到達する mcp サーバー。サーバーには、その呼び出しが従う approvalMode、エージェントが呼び出せるサーバーの allowedTools、および独自の connection が伴います。

=Env.NAME と記述されたメンバーは、アプリケーションが Agent Framework 自身のセキュリティ設定である AgentFactory(safe_mode=False) で宣言型エージェントを読み込み、かつ .NET ランタイムが存在する場合に限り、Agent Framework が環境変数 NAME から読み取ります。それ以外の場合は、記述されたとおりの式のテキストとして扱われます。= で始まるその他のメンバーは、アプリケーションが計算する式です。インポーターはどちらも読み取りません。参照はその変数で、式は式として名指しします。

単独でインポートされたファイルは、名前にかかわらず 1 つの宣言型エージェントとして読み取られ、インポーターの with.sources が渡す各ファイルはそれぞれ別の宣言型エージェントとして読み取られます。そのため、1 回のインポートで複数をドラフトできます。

plugins:
importer:
- uri: importer/agent-framework:<version>
with:
sources:
- ./agents/triage.yaml
- ./agents/writer.yaml

ディレクトリがインポーターに渡されることはありません。インポーターのシグネチャはファイルを指定しないため、形式を指定しないディレクトリのインポートではそれが認識されず、--format agent-framework を指定したインポートは、ディレクトリ内のファイルが開かれる前に An importer that declares no file patterns is handed a directory(ファイルパターンを宣言しないインポーターにディレクトリが渡されました) で拒否されます。代わりに、各宣言型エージェントを個別のファイルとしてインポートしてください。Agent Framework がプロンプトエージェントを構築しないソース(kind が、大文字小文字を問わず Prompt でも、Agent でもないもの)は、no-nodes で報告されます。アプリケーションのコード(各宣言型エージェントを読み込むプログラムと、そのツールにバインドする関数)がソースに含まれることはありません。アプリケーションは、Release が指定するイメージから、宣言型エージェントを自ら読み込みます。

宣言型エージェントが何になるか

aggregate.yaml は、ドラフトの命名方法で説明するとおりエージェントにちなんで名付けられたドラフト Aggregate で、宣言型エージェントごとに、その名前をキーとして、次を持つ core/ai-agent/agent-framework のインスタンスを保持します。

  • display_name と description。エージェントが displayName と description を記述している場合、その値です。
  • その model 接続。指定されたモデルが接続される場合、そのモデルに接続されます。

エージェントの指示、入力と出力のスキーマ、テンプレート、メタデータ、モデルリクエストのオプションは、アプリケーションが宣言型エージェントから読み取るため、インスタンスの上のコメントで名指しされます。関数ツール、モデルのプロバイダーが実行するツール、その他の種類のツールもコメントで名指しされ、何も選択しない判断として報告されます。

provider が OpenAI で、id を指定するモデルは、その id を提供し、それをキーとする core/ai-model/openai のインスタンスになります。エージェントの model ソケットは OpenAI API を提供するモデルを受け入れ、ランタイムはそのモデルのアドレス、名前、キーを、Agent Framework の OpenAI クライアントが読み取る変数で渡します。1 つのアドレスで 1 つのモデルを指定するエージェント同士は、1 つのインスタンスを共有します。ワークスペースのカタログに core/ai-model/openai がない場合は、エージェントの model ソケットが選択する model.aggrega.ai/api: openai ラベルを持つ <target_namespace>/ai-model/openai がドラフトされ、その判断でその旨が示されます。そのエンドポイントとモデルを公開する Recipe は、冒頭のコメントが示すとおり、利用者に委ねられます。参照として記述された id の場合、モデルの values.model は利用者に委ねられ、モデルの上のコメントがその変数を名指しします。設定されるまで、ビルドはそれを名指しして停止します。anonymous 接続は、接続の unauthenticated: true として記述されます。その他のプロバイダー(AzureOpenAI、Anthropic)のモデル、プロバイダーを参照として指定するモデルや指定しないモデル(この場合 Agent Framework はアプリケーションが設定するデフォルトのプロバイダーを使用します)、および id を指定しないモデルはどこにも接続されず、インスタンスの上のコメントがその理由を示します。接続されるまで、ビルドは model ソケットを名指しして停止します。

kind が mcp のツールは、Component としても接続としてもドラフトされません。Agent Framework はサーバーをホスト型ツールとしてモデルのプロバイダーに送り、アプリケーションではなくプロバイダーがその url でサーバーに到達します。したがって、このアドレスはプロバイダーから到達可能でなければならず、ドラフトがデプロイするものはいずれもサーバーに到達しません。エージェントのインスタンスの上のコメントは、サーバーを名指しし、その旨を述べ、宣言型エージェントがサーバーに対して記述する説明、approvalMode、allowedTools を名指しします。その url は、Release 内のエージェントのエントリーの上のコメントに全体が書き出され、その決定は何も選択しません。

その隣の release.yaml は、その Aggregate を指定する同名のドラフト Release です。エージェントのエントリーは、その infra.image(宣言型エージェントを保持する、Agent Framework 上に構築されたアプリケーションを実行するイメージ)を、それが何であるかを示すコメントの下に空のまま書き、インポートはそれを未回答の値として扱います。--target compose の場合、エントリーは infra.published_port として 8000 も書きます。これは Component の infra.port がアプリケーションに対してデフォルトで指定するポートで、その Compose の Recipe がホストのループバックアドレス 127.0.0.1 上に公開するものです。このマシン上で動作する任意のプロセスからのみ到達可能であること、そしてその行を削除するとサービスが内部に留まることを示すコメントの下に書かれます。モデルが接続されている場合、エントリーはエージェントがそのモデルに提示する認証情報を、model 接続の credential の下に、値としてではなく常に参照として付与します。認証情報は、宣言型エージェントがキーに指定する変数(=Env.NAME と記述)から読み取られ、それがなければ OpenAI のクライアントライブラリがキーを読み取る変数 OPENAI_API_KEY から読み取られます。helm 以外のすべてのターゲットでは ${…} 参照として、helm では Kubernetes Secret の名前として書かれ、空のまま書かれてインポートの未回答の値となります。compose では、model 接続がそのキーでそれを宣言します。宣言型エージェントがモデルと MCP サーバーに対して記述する値(キーと各サーバーの url)は、宣言型エージェントが保持する認証情報の値で説明するとおり、エージェントのエントリーの上のコメントに書き出されます。接続された各モデルにはエントリーがあるため、Release はそれをエージェントと同じ場所に配置します。その接続が記述するエンドポイントは、モデルの infra.endpoint として書き出され、参照として記述されたものはエントリーの横で名指しされ、設定されるまでは Component 自身のアドレスが使われます。エンドポイントを記述しない接続では、エントリーはインフラストラクチャを持たないままとなり、Component 自身のアドレスがそのまま使われます。下書きされるすべての Release と同様に、metadata.environment を development として書き、ターゲットがない場合はインポートの未回答の値となる空の spec.manifest を書きます。ターゲットが与えられた場合は、ターゲットが追加するもので説明するとおり、インポートが Manifest を下書きします。

このインポーターのテストがインポートする宣言型エージェント(キー接続を持つ OpenAI プロバイダー、独自のキーを提示する MCP サーバー、関数ツール、Web 検索を持つもの)を単独のファイルとしてインポートすると、設定なしで、その name である LearnAgent のもとで次のようにドラフトされます。

aggregate.yaml
# Not read: the application's code, which loads each declarative agent and binds the functions of its function tools; the application runs in the image the Release names for each instance, and loads its declarative agents itself.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/learnagent
version: 0.1.0
description: Draft Aggregate imported from a source in the agent-framework format.
spec:
components:
# The declarative agent LearnAgent.
# Read by the application from the declarative agent, and taken by no key of core/ai-agent/agent-framework: instructions, outputSchema, the options of its model requests (temperature, topP).
# Function tools, whose code the application binds, drafted as no Component: GetRelease.
# Tools the model's provider runs, drafted as no Component: search.
# The MCP server microsoft_learn, drafted as no Component and no connection, since Agent Framework sends it to the model's provider as a hosted tool, and the provider, not the application, reaches it at its url, which must therefore be reachable from the provider; its url is written above learnagent's entry in the Release.
# Stated by the declarative agent for microsoft_learn: its description, "Get information from Microsoft Learn."; its approval mode, never; the tools of the server it allows, microsoft_docs_search, microsoft_docs_fetch.
learnagent:
type: core/ai-agent/agent-framework
values:
display_name: "Learn Assistant"
description: "Answers questions about {{`{{`}} product }} from the Microsoft Learn content."
uses:
model:
gpt-4-1-mini:
target: gpt-4-1-mini
# For the compose target only, uncomment the lines below, which declare credential on gpt-4-1-mini: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: OPENAI_API_KEY
# The model gpt-4.1-mini, which LearnAgent names with the OpenAI provider.
gpt-4-1-mini:
type: core/ai-model/openai
values:
model: "gpt-4.1-mini"

ドラフトが宣言型エージェントから Aggregate に値またはコメントとしてコピーするテキストでは、各 {{ が {{`{{`}} として書き出されるため、Aggregate が評価されると記述どおりに読み戻されます。

release.yaml
spec:
aggregate: imported/learnagent
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# The declarative agent also states these values for its model and its MCP servers, written here for review:
# - model.connection.key: "..."
# - tools.microsoft_learn.url: "https://learn.microsoft.com/api/mcp?session=..."
# - tools.microsoft_learn.connection.key: "..."
learnagent:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on Agent Framework, holding its declarative agent
image: ""
uses:
model:
gpt-4-1-mini:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential learnagent presents to gpt-4-1-mini on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
gpt-4-1-mini:
infra:
endpoint: "https://llm-gateway.example.com/v1"

イメージが回答されると、エージェントはそれを実行するようにレンダリングされ、モデルのエンドポイントが OPENAI_BASE_URL、id が OPENAI_MODEL、認証情報が OPENAI_API_KEY として渡され、モデルはそのホストに到達する Service としてレンダリングされます。MCP サーバーのアドレスを運ぶ変数はありません。サーバーに到達するのはアプリケーションではなく、モデルのプロバイダーです。

宣言型エージェントが保持するクレデンシャルの値

key 接続が提示するキー(モデルまたは MCP サーバー上で、key または apiKey の下に書かれたもの)は、Agent Framework がクレデンシャルとしてマークする唯一のメンバーです。これは、そのローダーがログ出力から秘匿する唯一の値です。宣言型エージェントがリテラルとして書く各キーは、Release 内のエージェントのエントリの上にあるコメントに、宣言型エージェントが書いたとおりに書かれ、デフォルトでは書かれたとおりに引き継がれ、credential-carried 警告の中で、その値ではなく、エージェントとフィールド(model.connection.key など)によって示されます。MCP サーバーの url は、同じコメントに全体が書かれ、そのフィールドで示され(tools.microsoft_learn.url of node LearnAgent is carried as written)、MCP サーバーの設定のメンバーです。接続されたモデルのエンドポイントは、Agent Framework がクレデンシャルではないとマークする入力です。empty_credentials 設定が marked の場合、キーと MCP サーバーの url は値なしで書かれ(コメントはそれぞれをフィールドのみで示します)、credential-emptied で報告され、モデルのエンドポイントは引き継がれます。all の場合は、モデルの infra.endpoint も省かれ、そのエントリの上のコメントで Release に委ねられるものとして示され、設定されるまでは Component のデフォルトのアドレスが使われます。=Env.NAME として書かれた値は値を保持しないため、設定にかかわらず、Agent Framework が環境からそれを読み取る条件とともに、その変数によって示され(model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads …)、どちらのコードでも報告されません。それ以外の式として書かれた値は式として示され、書かれることはありません。

読み取る設定

Agent Framework インポーターは、Settings が説明する target_namespace、empty_credentials、render_mode を読み取り、それ以外の設定は読み取りません。

ターゲットが追加するもの

ターゲットを指定したインポート(aggrega import の --target、またはアシスタントのインポートツールとセッションの aggrega/import メソッドの target で、compose や helm などのプロバイダー機能を指定します)は、そのターゲットをインポーターに渡すため、インポーターはそのターゲット向けに下書きします。各シークレットはそのターゲットが読み取る形式で書かれ、そのターゲットだけが必要とする行は有効な状態で書かれ、別のターゲットだけが必要とする行は省かれます。compose では、各インポーターのセクションで説明するとおり、インポーターがホストのループバックアドレスでサービスを公開する箇所に、それらの行として infra.published_port が含まれます。インポーターが選ぶポートには、Release の別のポートが使っている番号が割り当てられることはありません。続いてインポートは、どのインポーターが実行された場合でも、インポーターが下書きしたものの隣に Manifest を下書きします。これは manifest.yaml で、下書きされた Release の隣に置かれ、Release と同じ名前とバージョンが付けられます(インポーターが Release を下書きしなかった場合は、下書きされた Aggregate の隣に置かれ、Aggregate と同じ名前とバージョンが付けられます)。

下書きが必要とする各コンポーネント型と各 feature 型(下書きされた Aggregate のコンポーネント、その接続とサブシステム、core/dify のようにそれが構成するカタログの Aggregates、そして下書きされた Release のアタッチメントにあるもの)について、Manifest はその型を、ワークスペースのカタログがその型に対して提供する、その機能の Recipe(feature 型の場合は feature recipe)にマッピングします。対象は、存在する唯一のもの(1 つの Recipe の複数のバージョンは 1 つとして数えます)か、名前の異なるものが複数ある場合は、core/datastore/postgres に対する helm/postgres のように型そのものにちなんだ名前を持つものです。該当するものがない型、または複数あってもそのような名前のものがない型はマッピングされないままとなり、警告がその型と理由を示します。下書きのビルドは、マッピングされるまでその型の各インスタンスまたはアタッチメントを示して停止します。

複数の Recipes のうちどれが該当するかをインポーターだけが知っている場合、インポーターが自ら Manifest を下書きします。MCP インポーターは各サーバーをそのキーによって、サーバーの実行方法の実現にマッピングし、名前でシークレットを付与するインポーターは core/referenced-secret を helm/k8s-existing-secret にマッピングします。そのうえでインポートがそれを補完します。インポーターが書いたマッピングのうち、カタログがその型と機能に対して提供するものは保持され、それ以外は警告とともに破棄され、残った型は上記のとおりマッピングされます。

ターゲットがない場合に空のまま書かれる、下書きされた Release の spec.manifest は Manifest の名前に設定され、その上のコメントは削除され、Release のそれ以外の部分は変更されません。aggrega import で詳しく説明しています。

設定

インポーターには、それをアタッチする plugins.importer エントリの設定が、どのインポーターがソースをドラフトに変換するかで説明するとおり with.settings の下で渡されます。エントリがない場合、または設定がない場合、各設定はデフォルト値を取ります。

plugins:
importer:
- uri: importer/langflow:<version>
with:
settings:
target_namespace: payments
reuse_mode: hints-only
設定デフォルト動作
target_namespaceimported作成されたエンティティに名前を付ける際の名前空間です。Component には <target_namespace>/<category>/<name>、Aggregate と Release には <target_namespace>/<name> が使われます。<name> はソース自身の名前で、それがなければそのディレクトリの名前、またはファイルの拡張子を除いた名前、それもなければ flow です。小文字で書かれ、ASCII の英字と数字以外の文字の連なりはそれぞれ 1 つのハイフンになります。詳しくはドラフトの命名方法で説明しています。
reuse_modeauto-apply-above-thresholdauto-apply-above-threshold は、ドラフトが独自の Component を与えるノードのうち、一致が高ティアにあり、スコアが reuse_threshold 以上のものについて最も一致するカタログの Component を参照し、それ以外はすべてドラフトします。hints-only はそのようなノードをすべてドラフトし、カタログの Component を参照せず、強い一致はヒントとして記録します。その他の値は hints-only として読まれます。
reuse_threshold0.85auto-apply-above-threshold が Component を参照するスコアの下限です。このモードでのみ読まれます。0 はデフォルト値として読まれます。
emit_hintstrue高ティアまたは中ティアの一致について、ドラフトされた Component のファイルの先頭に、類似するカタログの Component を示すコメントを置くかどうかです。ドラフトの Aggregate も、そのノードのエントリの上に同じコメントを持ち、参照されるエントリの上には、置き換え候補となる次点の候補を示すコメント、または 0 を超えるスコアの候補がないことを示すコメントを持ちます。false はコメントを省きます。
render_modehumanhuman は上で説明したドラフトを書き出します。llm はドラフトを書き出さず、代わりに判断記録全体(すべてのノード、比較した候補、行った選択)を、別のツールが読むための 1 つのドキュメント import-decisions.json として書き出します。その他の値は human として読まれます。
mapping_overridesなしインポーター自身のテーブルに重ねるマッピングで、フォーマット、次にノードタイプ(Compose インポーターではイメージリポジトリ)をキーとします。各エントリは、そのタイプのノードがマップされる component を示し、任意で、その category、一致する Component が持つ traits(ラベルとその値)、その名前が含む vendor の語を示します。テーブルがすでにマップしているノードタイプのエントリは、テーブルの行に置き換わります。インポート中のフォーマットの下にあるエントリのみが読まれます。
layoutplatformplatform は、フローを実行するプラットフォームを、フローを保持する形でドラフトし、フローを保持するプラットフォームで説明するとおり、その各部分をプラットフォームに配線された独自の Component とします。nodes は、ノードごとで説明するとおり、すべてのノードを独自の Component としてドラフトします。Dify インポーターでは、platform は、アプリケーションが何になるかで説明するとおり、アプリケーションを保持する Dify インストールをドラフトします。その他の値は platform としてドラフトされ、インポートは unknown-layout で警告します。
empty_credentialsnoneどの認証情報の値を空にして書き出すかを指定します。対象は、プラットフォームが保持するフロー(フローが保持する認証情報の値に列挙)、MCP インポーターがドラフトする Release(サーバーが保持する認証情報の値に列挙)、Compose インポーターがドラフトする Release(サービスが保持する認証情報の値に列挙)、Dify インポーターが保持するアプリケーション(アプリケーションが保持する認証情報の値に列挙)、CrewAI インポーターがドラフトする Release(宣言が保持する認証情報の値に列挙)、LangGraph インポーターがドラフトする Release(構成が記述する環境に列挙)、Google ADK インポーターがドラフトする Release(構成が保持する認証情報の値に列挙)、Agent Framework インポーターがドラフトする Release(宣言的エージェントが保持する認証情報の値に列挙)です。none は何も空にしません。各値は書かれたまま保持され、credential-carried 警告で示されます。marked は、フォーマットが認証情報としてマークするものと、MCP サーバーの構成のすべてのメンバーを空にします。all は、フォーマットが認証情報としてマークしていないが認証情報を保持しうる入力(リクエストヘッダー、クエリパラメーター、コマンドラインとして書かれたリクエスト、キーにちなんだ名前の入力)も空にします。ノードが接続先に到達するためにドラフトが書き出すものは、この設定にかかわらず書き出されます。その他の値はインポートを停止し、何もドラフトせず unknown-empty-credentials となります。ノードごとに作成されるドラフトは値を読まないため、この設定も読みません。
attach_egress_allowlistfalsetrue は、ドラフトが Release に残すもので説明するとおり、ドラフトが書き出す各プラットフォームインスタンスに、標準ライブラリの core/egress-allowlist Feature を egress-allowlist としてアタッチし、その infra は何も設定しません。false は何もアタッチしません。layout: nodes のもとでプラットフォームを書き出さないドラフトと、Dify インストールのエントリが Feature を取らない Dify インポーターのドラフトは、この設定にかかわらず何もアタッチせず、true の場合、インポートは feature-not-attached で警告します。ブール値でない値は false として読まれます。

インポーターが認識しない設定は無視されます。

with:
settings:
mapping_overrides:
langflow:
AzureOpenAIModel:
component: acme/ai-model/azure-openai
category: ai-model
vendor: azure

インポートが報告する内容

各コアインポーターは、実行できなかったことと、作成者に代わって行ったことを 診断として報告します。コマンドは各診断を、各ノードの行より前に、標準エラーへ <severity>: <message> として 出力します。エディタセッションの aggrega/import メソッドとアシスタントの import ツールは、各診断を その code とともに返します。

コード重大度報告される条件
parse-failedhaltソースを解析できません。パーサーがソースを拒否し、メッセージにはパーサーが示す理由が含まれます。
no-nodeswarnソースに、インポーターが認識するノードが含まれていません。MCP インポーターではサーバーがない場合、Compose インポーターではサービスもモデルもない場合、CrewAI インポーターではクルーがエージェントを宣言していない場合、LangGraph インポーターでは構成がグラフを宣言していない場合、Google ADK インポーターではルート構成がエージェントを宣言していないか、with.sources がインポートに渡すどのファイルにもルート構成がない場合、Agent Framework インポーターではソースがプロンプトエージェントを宣言していない場合です。
unknown-layoutwarnlayout が platform でも nodes でもありません。フローは platform として下書きされます。
unknown-empty-credentialshaltempty_credentials が none、marked、all 以外の値を持っています。その設定名が示され、インポートは何も下書きしません。
platform-not-in-catalogwarnワークスペースのカタログにプラットフォームの名前を持つ Component がないため、どのパーツもそれに接続されません。Dify インポーターでは core/ai-agent/dify がない場合で、その場合でも core/dify は構成されます。
part-not-placedwarnフローのパーツがプラットフォームのどのソケットにも接続されていません。理由が示されます。そのパーツはフロー内に残ります。
socket-selector-unreadablewarnプラットフォームのソケットが宣言するセレクターを読み取れないため、どのパーツもそのソケットに接続されません。ソケットごとに 1 回報告されます。
credential-carriedwarn認証情報の値が、下書きが保持するフロー内、または MCP、Compose、CrewAI、LangGraph、Google ADK、Agent Framework の各インポーターが下書きする Release 内に、記述どおりに保持されています。値そのものではなく、そのノード(またはサーバー、サービス、エージェント、構成)とフィールドで示され、その値を空にする empty_credentials の値が添えられます。
credential-emptiedwarnempty_credentials の指定に従い、下書きが保持するフロー内、または MCP、Compose、CrewAI、LangGraph、Google ADK、Agent Framework の各インポーターが下書きする Release 内で、認証情報の値が空に書き込まれました。そのノード(またはサーバー、サービス、エージェント、構成)とフィールドで示されます。
carriage-returns-rewrittenwarnフローのキャリッジリターンがラインフィードとして書き込まれました。その数が示されます。
definition-respelledwarnフローの値は、プラットフォーム自身のツールが読み取る表記で、同じ値のまま書かれ、どの値をなぜそうしたかが示されます。Langflow のフローのエッジハンドルは、Langflow のエディターが書くとおりに書かれます。フローがパーツに到達するために下書きが書く値や、資格情報を運び得る値は、表記が書き換えられることはなく、配線のもの、または empty_credentials のもののままとなります。警告は書き換えられなかった値をそれぞれ数えます。
definition-not-carriedwarnフローが values.flow_definition に保持されていないか、Dify インポーターのアプリケーションが parameters.app_definition に保持されていません。理由が示されます。
part-reads-connectionwarnフローが接続を通じて接続済みパーツに到達する方法、または下書きがどのソケットにも接続しないノードに、記述どおりの接続が到達する方法です。
part-address-in-flowwarnフローが接続以外の方法で接続済みパーツに到達しています。その方法が示されます。
model-not-namedwarn参照されるパーツの values.model が作成者に委ねられています。理由が示されます。
feature-attachedinfoattach_egress_allowlist により、下書きされたプラットフォームに core/egress-allowlist が付与されました。そのうち Release が設定するものが示されます。プラットフォームインスタンスごとに 1 回報告されます。
feature-not-attachedwarnattach_egress_allowlist が true ですが、下書きがプラットフォームを書き込まないか、エントリが Feature を受け付けない Dify インストールを構成するため、何も付与されません。
part-configured-in-platformwarnDify アプリケーションのノードが、Dify 自身が構成するもの(モデルとそのプロバイダー、ツール、ナレッジベース、エージェント戦略、プラグイン)を指定しているため、下書きはそれに対してパーツを接続しません。
dsl-version-newerwarnDify アプリケーションが、core/ai-agent/dify がデフォルトで実行する Dify のバージョンが書き出す DSL よりも新しいバージョンの DSL で記述されています。

ターゲットを指定したインポートは、インポーターの診断の後に、Manifest の下書きで判明したことを報告します。Manifest がマッピングしないままにする各コンポーネント型または feature 型とその理由を示す warn と、下書きされた Release がすでに Manifest を指定している場合、または下書きされたどの Release もそれを参照しない場合の info です。これらはインポーターではなくインポート自体の診断であり、コードを持ちません。ターゲットが追加するもので説明しています。続いてすべてのインポートは、同じくインポート自体の診断として、下書きにまだ必要な各値について、下書きされたファイル、キーのパスとその説明を示す warn を報告し、--offline では、Release を下書きして必要な値が残っていない場合に、次に実行する aggrega pull を示す info を報告します。インポートの回答ファイルで説明しています。

コンパイラの各リリースとともに公開

コンパイラの各リリースは、タグ付けされたソースから 10 個のインポーターをビルドし、それらの Plugin エンティティをインポーター自身から生成します。そのため、エンティティの機能、認識シグネチャ、ホスト 関数、説明は、そのインポーターが報告するとおりになります。リリースは 10 個すべて、 importer/langflow、importer/flowise、importer/n8n、importer/mcp、importer/compose、importer/dify、importer/crewai、importer/langgraph、importer/google-adk、importer/agent-framework をリリースのバージョンで、他の コアプラグインと並べて署名・公開し、それらのエンティティを他のコアプラグインのエンティティとともに標準 カタログに記録します。