Importery podstawowe
Repozytorium kompilatora buduje dziesięć własnych wtyczek importerów, po jednej dla każdego formatu źródłowego, i publikuje je z każdym wydaniem kompilatora:
| Plugin | Obsługuje | Odczytuje |
|---|---|---|
importer/langflow | import:langflow | przepływ wyeksportowany z Langflow, jako JSON |
importer/flowise | import:flowise | chatflow lub agentflow wyeksportowany z Flowise, jako JSON |
importer/n8n | import:n8n | przepływ pracy wyeksportowany z n8n, jako JSON |
importer/mcp | import:mcp | konfigurację klienta MCP — .mcp.json, claude_desktop_config.json, .vscode/mcp.json lub .cursor/mcp.json — albo opis serwera z rejestru MCP, server.json, jako JSON |
importer/compose | import:compose | aplikację Compose — compose.yaml, docker-compose.yml i ich pliki nadpisujące — jako YAML |
importer/dify | import:dify | aplikację wyeksportowaną z Dify w jej DSL, jako YAML |
importer/crewai | import:crewai | agentów i zadania deklarowane przez projekt CrewAI — config/agents.yaml i config/tasks.yaml, jako YAML, albo crew.jsonc i agents/<name>.jsonc, lub ich zapisy w ścisłym JSON crew.json i agents/<name>.json, jako JSON z komentarzami |
importer/langgraph | import:langgraph | konfigurację aplikacji LangGraph, langgraph.json, jako JSON, a z pliku środowiskowego, który ona wskazuje, same nazwy zmiennych, jeśli import otrzymuje ten plik w with.sources |
importer/google-adk | import:google-adk | agentów zadeklarowanych w plikach Agent Config aplikacji zbudowanej na Google ADK — root_agent.yaml i konfiguracje wskazane przez jego subagentów — jako YAML |
importer/agent-framework | import:agent-framework | deklaratywnego agenta Microsoft Agent Framework, dokument rodzaju Prompt o dowolnej nazwie, jako YAML |
Każdy z nich jest budowany z własnych źródeł kompilatora i oznaczany wersją kompilatora, więc
importery wydane z kompilatorem w wersji X.Y.Z zgłaszają wersję X.Y.Z, a ich encje Plugin
ją zapisują. W odróżnieniu od wtyczek wymienionych w Wtyczki wbudowane żaden nie jest wkompilowany
w plik binarny. Plik binarny zawiera encję Plugin każdego z nich oraz skrót jedynego modułu, który
akceptuje dla niej, więc każdy obsługuje swój format w każdym obszarze roboczym, bez wpisu w jego katalogu.
Wszystkie dziesięć zbudowano na pakiecie importera z zestawu Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. W przypadku importerów Langflow, Flowise i n8n wszystko, co importer robi niezależnie od formatu — ocenianie Components z katalogu obszaru roboczego względem każdego węzła, decyzja, czy odwołać się do jednego z nich, czy utworzyć szkic nowego, rozmieszczenie szkicu, przenoszenie zawartych w nim wartości poświadczeń lub zapisywanie ich jako pustych, gdy wymaga tego ustawienie, zapisywanie szkiców i odczytywanie poniższych ustawień — należy do tego pakietu, a tylko odczyt formatu i znajomość platformy, na której działają jego przepływy, są właściwe dla każdego importera. Importer MCP tworzy szkic instancji jednego Component na serwer, więc niczego nie ocenia; dzieli z pakietem odczyt ustawień, które czyta, decyzję co do wartości poświadczeń oraz konwencje, według których nazywa i opisuje swoje szkice, jak opisano w Importer MCP. Importer Compose rozstrzyga o każdej dopasowanej usłudze tak, jak importery przepływów rozstrzygają o węźle, za pomocą tego samego pakietu, renderuje swoje szkice tak jak one, a resztę dzieli tak jak importer MCP, jak opisano w Importer Compose. Importer Dify tworzy szkic instalacji Dify, składanej przez bibliotekę standardową, zawierającej aplikację, za pomocą szkicu platformy z tego samego pakietu w postaci, jaką przyjmuje on dla platformy będącej całą instalacją, jak opisano w Importer Dify. Importer CrewAI tworzy szkic instancji agenta CrewAI z biblioteki standardowej dla każdego agenta zadeklarowanego przez projekt, połączonej ze wskazanym przez niego modelem, a resztę dzieli tak jak importer MCP, jak opisano w Importer CrewAI. Importer LangGraph tworzy szkic instancji agenta LangGraph z biblioteki standardowej dla każdego grafu zadeklarowanego w konfiguracji aplikacji, połączonej z magazynem danych, w którym jego checkpointer przechowuje stan, a resztę dzieli tak jak importer MCP, jak opisano w Importer LangGraph. Importer Google ADK tworzy szkic instancji agenta ADK z biblioteki standardowej dla każdego drzewa agentów zadeklarowanego w konfiguracjach aplikacji, połączonej z modelem wskazanym przez drzewo, gdy ADK wysyła swoje żądania do API Gemini, a resztę dzieli tak jak importer MCP, jak opisano w Importer Google ADK. Importer Agent Framework tworzy szkic instancji agenta Agent Framework z biblioteki standardowej dla każdego agenta deklaratywnego, połączonej ze wskazanym przez niego modelem OpenAI — przy czym każdy wskazany przez niego serwer MCP jest zapisywany w komentarzach, ponieważ dostawca modelu sięga do niego jako do narzędzia hostowanego — a resztę dzieli tak jak importer MCP, jak opisano w Importer Agent Framework. Sposób działania gniazda importera oraz to, co ono otrzymuje, opisano w sekcji Gniazdo importera.
Ta strona jest dokumentacją referencyjną tego, co każdy importer czyta i jakie szkice tworzy. Aby zaimportować własny projekt i skompilować wynik, należy zacząć od strony Import, która prowadzi projekt od źródła do kompilacji, po jednym formacie naraz.
Jak import go uzyskuje
aggrega import, metoda aggrega/import sesji edytora i narzędzie import asystenta uzyskują importer podstawowy w ten sam sposób. Jeśli maszyna ma już jego moduł — w pamięci podręcznej treści obszaru roboczego — import odczytuje go stamtąd, nie korzystając w tym celu z sieci. Jeśli go nie ma, pierwszy import, który go potrzebuje, pobiera go z domyślnego rejestru obszaru roboczego w wersji kompilatora i:
- sprawdza jego zgodność ze skrótem zapisanym w pliku binarnym, tak aby uruchamiany był tylko moduł opublikowany w wydaniu kompilatora;
- weryfikuje go tak, jak pull weryfikuje pobierany plugin — jego podpis zgodnie z polityką zaufania tego rejestru, a używane przez niego funkcje hosta względem tych, które zapisuje jego encja Plugin;
- przechowuje go w pamięci podręcznej treści obszaru roboczego, która jest jedyną rzeczą zapisywaną na jego potrzeby: bez pliku blokady i bez rejestru zaufanych pluginów, ponieważ import nie przypina żadnego importera.
Każdy kolejny import odczytuje go z pamięci podręcznej treści. Moduł, który nie przejdzie weryfikacji, zostaje odrzucony i nic nie jest zachowywane. W folderze, którego żaden obszar roboczy nie oznacza, nie ma pamięci podręcznej treści, w której można by go przechować, więc pobranie jest tam odrzucane z podaniem folderu oraz sposobu wskazania obszaru roboczego lub uczynienia z folderu obszaru roboczego. Moduł nigdy nie jest odczytywany obok encji Plugin o tej samej nazwie w innej wersji w folderze katalogu: ten moduł należy do tamtej encji.
Jeśli modułu nie można pobrać, import zatrzymuje się z błędem
A plugin’s .wasm is not on this machine (Pliku wasm pluginu nie ma na tej maszynie),
podając importer i jego wersję, oraz informuje, co umieszcza jego moduł na maszynie:
- Uruchomić import raz z dostępem do sieci, jeśli obszar roboczy jest offline lub nie udało się połączyć z jego rejestrem. To uruchomienie go pobiera, a każde kolejne działa offline.
- Umieścić jego moduł obok encji Plugin tego importera w tej wersji w folderze katalogu, pod nazwą podaną w komunikacie —
importer--langflow.wasmdla importera Langflow. Encja katalogu o tej samej nazwie i wersji co importer podstawowy jest uruchamiana zamiast niego, a jej moduł jest odczytywany z miejsca obok niej; encja w tym miejscu bez modułu obok niej nie jest uruchamiana zamiast niego, a importer podstawowy jest pozyskiwany tak, jak opisano powyżej. Jeśli rejestr nie zawiera modułu lub obszar roboczy nie wskazuje domyślnego rejestru, jest to jedyne rozwiązanie podawane w komunikacie.
Który z nich działa obok własnych importerów
Importery podstawowe są kandydatami obok importerów, które zawiera katalog obszaru roboczego, według reguł, według których wybierany jest każdy importer, opisanych w sekcji Which importer turns a source into drafts (Który importer zamienia źródło w szkice):
- W obrębie jednej nazwy działa najwyższa wersja albo wersja wskazana we wpisie
plugins.importer. - Jeśli katalog zawiera importer o innej nazwie dla
langflow,flowise,n8n,mcp,compose,dify,crewai,langgraph,google-adklubagent-framework, format ten ogłaszają dwa importery, a import, który nie dołącza żadnego z nich, zostaje odrzucony z podaniem obu, z błędem A parse or import format is advertised by more than one plugin (Format parsowania lub importu jest ogłaszany przez więcej niż jedną wtyczkę). Rozstrzyga to wpisplugins.importerwskazujący wybrany importer. - Importer, który katalog zawiera pod tą samą nazwą i w tej samej wersji co importer podstawowy, z modułem obok swojej encji, jest tym, który działa, a jego moduł jest odczytywany z tego miejsca.
- Encja Plugin o nazwie importera podstawowego, obok której w jej folderze katalogu nie ma modułu — na przykład w kopii roboczej katalogu, która rejestruje importery opublikowane w danym wydaniu — to encja, której żaden import nie mógłby uruchomić, ponieważ jej moduł nie jest odczytywany z żadnego innego miejsca; nie jest więc kandydatem do uruchomienia, choć sygnatury, które rejestruje, nadal biorą udział w rozpoznawaniu źródła. W wersji samego kompilatora zamiast niej uruchamiany jest importer podstawowy. W każdej innej wersji, starszej lub nowszej, jest pomijana, a wybór odbywa się spośród importerów, które mogą zostać uruchomione — chyba że wpis
plugins.importerwskazuje dokładnie tę wersję albo żaden możliwy do uruchomienia importer o tej nazwie nie deklaruje żądanego formatu, jak wtedy, gdy encja rejestruje format, którego nie rejestruje importer samego kompilatora. Wtedy pozostaje kandydatem zgodnie z powyższymi regułami, a import, który ją wybierze, zatrzymuje się, wskazując folder, do którego należy umieścić jej moduł.
Niezależnie od tego, który z własnych importerów katalogu zostanie wybrany, jego moduł jest odczytywany z miejsca obok jego własnej encji, w jego własnej wersji: moduł umieszczony obok encji o tej samej nazwie w innej wersji należy do tamtej encji.
Jak rozpoznawane jest źródło
Import, który nie podaje swojego formatu za pomocą --format, jest rozpoznawany po sygnaturach deklarowanych przez
poszczególne importery:
- Langflow — źródło, które parsuje się jako JSON i zawiera tablicę w
data.nodes. - Flowise — źródło, które parsuje się jako JSON, zawiera tablice w
nodesiedgesi nie zawiera niczego wdata.nodes. - n8n — źródło, które parsuje się jako JSON, zawiera tablicę w
nodesi obiekt wconnectionsoraz nie zawiera niczego wedgesani wdata.nodes. - MCP — źródło, które parsuje się jako JSON, nosi nazwę
.mcp.json,claude_desktop_config.jsonlub.cursor/mcp.jsoni zawiera obiekt wmcpServers; źródło, które parsuje się jako JSON z komentarzami, tak jak odczytuje go Visual Studio Code, nosi nazwę.vscode/mcp.jsoni zawiera obiekt wservers; albo źródło o dowolnej nazwie, które parsuje się jako JSON i którego$schemajest tekstem zaczynającym się odhttps://static.modelcontextprotocol.io/schemas/, czyli opis serwera z rejestru. Nazwa jest dopasowywana do końca ścieżki przekazanej do importu, więcproject/.vscode/mcp.jsonzostaje rozpoznany, natomiastmcp.jsonprzekazany z wnętrza.vscodelub plik klienta o dowolnej innej nazwie importuje się, podając--format mcp. - Compose — źródło, które parsuje się jako YAML, nosi nazwę, pod którą Compose domyślnie odczytuje plik Compose lub jego plik
nadpisujący —
compose.yaml,compose.yml,docker-compose.yml,docker-compose.yaml,compose.override.yml,compose.override.yaml,docker-compose.override.ymllubdocker-compose.override.yaml— i zawiera obiekt wservices. Plik Compose o dowolnej innej nazwie importuje się, podając--format compose. - Dify — źródło o dowolnej nazwie, które parsuje się jako YAML, zawiera tekst
appwkindoraz zawiera coś wapp.modei wversion, jak każda aplikacja eksportowana przez Dify. - CrewAI — źródło o nazwie
config/agents.yamllubconfig/tasks.yaml, które parsuje się jako YAML, źródło o nazwiecrew.jsonclubcrew.json, które parsuje się jako JSON z komentarzami i zawiera listę wagents, albo źródło o nazwieagents/<name>.jsonclubagents/<name>.json, które parsuje się jako JSON z komentarzami i zawiera coś wrole. Klasyczny projekt indeksuje swoich agentów i zadania nazwami wybranymi przez autora, więc jego dwa pliki rozpoznaje się wyłącznie po nazwach. - LangGraph — źródło o nazwie
langgraph.json, które parsuje się jako JSON i zawiera obiekt wgraphs; albo źródło o dowolnej nazwie, które parsuje się jako JSON, zawiera obiekt wgraphsi którego$schemajest tekstemhttps://langgra.ph/schema.json, czyli schematem publikowanym przez LangGraph dla jego konfiguracji. Konfigurację o innej nazwie, niewskazującą schematu, importuje się, podając--format langgraph. Żadna sygnatura importera nie wskazuje pliku środowiskowego, więc rozpoznawanie katalogu nie otwiera żadnego. - Google ADK — źródło o nazwie
root_agent.yaml, które parsuje się jako YAML i zawiera coś wnamei winstruction, jak konfiguracja LlmAgent, albo tekst wagent_classi coś wname, jak konfiguracja każdego innego agenta. Konfigurację o innej nazwie importuje się, podając--format google-adk. Żadna sygnatura nie wskazuje konfiguracji podagenta, która może nosić dowolną nazwę, więc rozpoznawanie katalogu nie otwiera żadnego pliku YAML pozaroot_agent.yaml. - Agent Framework — źródło o dowolnej nazwie, które parsuje się jako YAML, zawiera tekst
Promptwkindi obiekt wmodel, jak deklaratywny agent wskazujący swój model; Agent Framework wczytuje deklaratywnego agenta z dowolnego pliku wskazanego przez aplikację, więc sygnatura nie wskazuje pliku. Deklaratywnego agenta niewskazującego modelu lub zapisującego swój rodzaj inną wielkością liter albo jakoAgentimportuje się, podając--format agent-framework.
Źródło pasujące do dwóch z nich jest odrzucane z podaniem obu formatów i można je zaimportować, wskazując jeden z nich przez --format. Importery Langflow, Flowise, n8n i LangGraph odczytują swoje źródło przez parser obsługujący parse:json; importer MCP konfigurację wymieniającą serwery w servers przez parser obsługujący parse:jsonc, a każde inne źródło przez parser obsługujący parse:json; importery Compose, Dify, Google ADK i Agent Framework przez parser obsługujący parse:yaml; a importer CrewAI pliki klasycznego projektu przez parser obsługujący parse:yaml, a pozostałe przez parser obsługujący parse:jsonc: ten, który udostępnia katalog przestrzeni roboczej, jeśli go udostępnia, a w przeciwnym razie parser, który kompilator ma wbudowany dla danej składni (zob. Wbudowane wtyczki). Import przez którykolwiek z nich nie wymaga więc parsera w katalogu i nic nie jest w tym celu pobierane. Parser udostępniany przez katalog jest używany, a parser kompilatora nie odgrywa żadnej roli. Importery Langflow, Flowise, n8n, Dify i Agent Framework nie deklarują wzorca pliku, więc każdy odczytuje jeden plik, a import katalogu przez którykolwiek z nich jest odrzucany; importer MCP deklaruje cztery nazwy plików klientów, więc katalog jest odczytywany przez zawarte w nim konfiguracje klientów; importer Compose deklaruje osiem nazw plików Compose, więc katalog jest odczytywany przez zawarte w nim pliki Compose; importer CrewAI deklaruje sześć nazw deklaracji projektu, więc katalog projektu jest odczytywany przez jego deklaracje i nic więcej; importer LangGraph deklaruje langgraph.json, więc katalog aplikacji jest odczytywany wyłącznie przez jej konfigurację, a ani jej kod, ani plik środowiskowy nigdy nie są odczytywane; importer Google ADK deklaruje root_agent.yaml, więc katalog aplikacji jest odczytywany wyłącznie przez jej konfigurację główną — konfiguracje wskazywane przez jej podagentów docierają do importera tylko przez with.sources jego dołączenia — a ani jej kod, ani plik środowiskowy nigdy nie są odczytywane. Sygnatura niewskazująca pliku — sygnatury importerów Langflow, Flowise i n8n, sygnatura importera MCP dla opisu serwera z rejestru, sygnatura importera LangGraph dla konfiguracji wskazującej swój schemat, sygnatura importera Dify i importera Agent Framework — dotyczy każdego pliku importowanego osobno: import niepodający formatu odczytuje taki plik jako JSON i jako YAML, aby je wypróbować, niezależnie od tego, dla którego importera jest przeznaczony, przez te same parsery — kompilator ma oba wbudowane, więc dla żadnego nic nie jest pobierane. Plik zawierający komentarz lub końcowy przecinek nie parsuje się jako JSON, więc żadna sygnatura odczytująca JSON go nie rozpoznaje; sygnatury importera CrewAI dla crew.jsonc, agents/<name>.jsonc i ich wariantów .json oraz sygnatura importera MCP dla .vscode/mcp.json odczytują JSON z komentarzami przez parser wbudowany w kompilator dla tej składni, jeśli katalog żadnego nie udostępnia.
Źródło odrzucone przez swój parser — dla importerów Langflow, Flowise, n8n i LangGraph takie, które nie jest
JSON, dla importera MCP takie, które nie jest JSON z komentarzami lub, o ile nie wymienia serwerów w
servers, nie jest JSON, dla importerów Compose, Dify i Agent Framework takie, które
nie jest YAML, dla importera CrewAI deklaracja, która nie jest YAML lub JSON z komentarzami, a dla
importera Google ADK konfiguracja, która nie jest YAML —
zatrzymuje import z błędem
parse-failed, którego komunikat zawiera powód podany przez parser. Podanie formatu tego nie zmienia:
importer prosi o drzewo źródła, a odmowa parsera jest odpowiedzią, którą otrzymuje.
Jak nazywany jest szkic
Każdy importer nadaje szkicowanej encji Aggregate, a także encji Release obok niej, jeśli ją szkicuje, nazwę <target_namespace>/<name>. Pierwsza część to ustawienie target_namespace, imported, o ile nie ustawi się innego. <name> to pierwsza z poniższych wartości, która nie jest pusta:
-
nazwa, którą źródło nadaje samo sobie, w polu, w którym deklaruje ją jego format:
Importer Odczytywana nazwa importer/langflownameprzepływuimporter/flowisebrak: eksport nie ma własnej nazwy importer/n8nnameprzepływu pracyimporter/mcpnameopisu serwera w rejestrze; konfiguracja klienta nie ma żadnejimporter/composenamenajwyższego poziomu projektu, przy czym nazwa z pliku nadpisującego zastępuje nazwę z pliku, który on nadpisuje, tak jak scala je Composeimporter/difynameaplikacji, wappimporter/crewainamezałogi wcrew.jsonclubcrew.json;config/agents.yamliconfig/tasks.yamlnie mają żadnej, ponieważ klasyczny projekt nadaje nazwę swojej załodze w swoim programieimporter/langgraphidentyfikator grafu deklarowanego przez konfigurację, ponieważ konfiguracja nie ma własnej nazwy importer/google-adknameagenta głównegoimporter/agent-frameworknameagenta; jegodisplayNamenie jest odczytywane -
nazwa katalogu przekazanego do importu, w całości —
my.projectzachowuje kropkę i jest zapisywane jakomy-project— tak jak Compose nazywa projekt od katalogu, który go zawiera;aggrega import .wskazuje katalog, w którym jest uruchamiane; -
nazwa pliku przekazanego do importu samodzielnie, bez rozszerzenia;
-
flow.
Szkic utworzony z kilku źródeł — kilku projektów Compose, konfiguracji, drzew agentów lub serwerów albo konfiguracji deklarującej kilka grafów — przyjmuje ich nazwę tylko wtedy, gdy każde z nich nadaje sobie nazwę i wszystkie są zapisane tak samo; w przeciwnym razie przyjmuje następną. Nazwę zapisuje się małymi literami, każdy ciąg znaków innych niż litery i cyfry ASCII jako jeden łącznik, a łączniki na obu końcach są usuwane: Basic Prompting zapisuje się jako basic-prompting, a SupportAgent jako supportagent. To samo źródło jest nazywane tak samo przy każdym imporcie. Encja Manifest, którą import szkicuje dla celu, przyjmuje nazwę encji Release lub encji Aggregate, gdy żadna encja Release nie jest szkicowana, jak opisuje Co dodaje cel.
Co odczytuje importer Langflow
- Węzły i krawędzie w obiekcie
datanajwyższego poziomu przepływu,data.nodesidata.edges. - Dla każdego węzła: jego typ z pola
data.typewęzła oraz jego pola z tych wpisówdata.node.template, których wartością jest obiekt zawierającytype. Pozostałe wpisy szablonu nie są polami. - Pole, którego obiekt zawiera
password: true, jest szkicowane jako slot poświadczenia, a każde inne pole jako pole wartości. Nazwa pola nie ma znaczenia, a szkicowanie węzła jako encji Component nie odczytuje wartości żadnego pola. - Notatka przypięta do kanwy, czyli węzeł typu
noteNode, nie jest importowana, a krawędź do węzła, który nie jest importowany, jest pomijana. - Szkicowanie platformy, która przenosi przepływ, odczytuje z przepływu również: jego
idnajwyższego poziomu; wartość każdego pola oznaczonegopassword: true; polemcp_serverwęzła MCP Tools — wskazany w nim serwer MCP i konfigurację tego serwera — albo pola, w których węzeł przechowuje swój serwer zamiast niego; każde wejście, które Langflow oznacza jako niebędące poświadczeniem, a które może je zawierać, zgodnie z listą w sekcji Wartości poświadczeń przechowywane w przepływie; pole, w którym węzeł wskazuje swój model, oraz dostawcę modelu, na którym działa; a także pola, przez które węzeł dociera do adresu i klucza części, które przepisuje. Sekcja Co szkicują opisuje, co dzieje się z każdym z nich.
Co odczytuje importer Flowise
- Węzły i krawędzie na najwyższym poziomie przepływu,
nodesiedges. - Dla każdego węzła: jego typ z
data.namewęzła; jego miejsca na poświadczenia z tych wpisówdata.inputParams, którychtypetocredential, według ichname; oraz jego pola wartości z kluczydata.inputs, z pominięciem tych, które wskazujedata.inputAnchors— tam, gdzie podłącza się inny węzeł, co zapisuje krawędź między nimi — oraz z pominięciem poświadczeń. - Szkicowanie węzła jako encji Component nie odczytuje wartości żadnego pola, a nazwa poświadczenia nie ma wpływu na to, że jest ono poświadczeniem.
- Notatka przypięta do kanwy, czyli węzeł typu
stickyNote, nie jest importowana, a krawędź do węzła, który nie jest importowany, zostaje pominięta. - Szkicowanie platformy, która przenosi chatflow, odczytuje z niego również: jego
idnajwyższego poziomu, o ile jest to UUID; poświadczenie, które węzeł przechowuje wdata.credential; wartość każdego wejścia, które jegoinputParamsdeklarują jako typpassword;FLOWISE_CREDENTIAL_IDwśród wejść węzła orazcredentiallubFLOWISE_CREDENTIAL_IDwewnątrz obiektu konfiguracji na dowolnej głębokości tych wejść; konfigurację serwera w wejściumcpServerConfigwęzła; każde wejście, które Flowise oznacza jako niebędące poświadczeniem, a które może je zawierać, tak jak wymienia je sekcja Wartości poświadczeń przechowywane w przepływie, oraz element, w którym konfiguracja agentflow wskazuje wybrany model lub narzędzie; wejściemodelNamewęzła; a także Base Path węzła OpenAI, czyli jego wejściebasepath. Sekcja Co szkicują opisuje, co dzieje się z każdym z nich.
Co odczytuje importer n8n
- Węzły przepływu pracy,
nodes, i jego połączenia,connections, na najwyższym poziomie eksportu. - Dla każdego węzła: jego
name, które go identyfikuje — połączenia n8n wskazują łączone węzły po nazwie, a nazwy węzłów przepływu pracy są unikatowe — oraz jegotype, zapisany w całości, wraz z pakietem: na przykład@n8n/n8n-nodes-langchain.lmChatOpenAilubn8n-nodes-base.httpRequest. Węzeł bez nazwy jest identyfikowany przez swójid. - Każde połączenie wymienione w przepływie pracy jest jedną krawędzią, od węzła, z którego wychodzi, do węzła, do którego wchodzi,
niezależnie od typu: połączenie
mainprzenosi dane z jednego węzła do następnego, a połączenie AI —ai_languageModel,ai_tool,ai_vectorStore,ai_embedding,ai_memoryi pozostałe — przekazuje węzłowi, do którego wchodzi, model, narzędzie, magazyn lub pamięć reprezentowane przez węzeł, z którego wychodzi. W obu przypadkach węzeł, do którego wchodzi połączenie, konsumuje węzeł, z którego ono wychodzi. - Każdy typ poświadczeń wskazany w
credentialswęzła oraz każdy parametr najwyższego poziomu oznaczony przez n8n jako hasło jest szkicowany jako slot poświadczeń; każdy inny parametr najwyższego poziomu węzła jest polem wartości. Szkicowanie węzła jako encji Component nie odczytuje wartości żadnego pola. - Notatka przypięta do kanwy, czyli węzeł typu
n8n-nodes-base.stickyNote, nie jest importowana, a połączenie z węzłem, który nie jest importowany, zostaje pominięte. - Szkicowanie platformy, która przenosi przepływ pracy, odczytuje z niego również: jego
idnajwyższego poziomu; każde poświadczenie wybrane przez węzeł; każdy parametr oznaczony przez n8n jako hasło; adres wywoływany przez węzeł klienta MCP; nagłówki i parametry zapytania, które węzeł wysyła z żądaniem składanym przez przepływ pracy, tak jak wymienia je Wartości poświadczeń przechowywane w przepływie; oraz parametr, w którym węzeł modelu wskazuje swój model. Co szkicują opisuje, co dzieje się z każdym z nich.
Co tworzą w szkicu
Każdy węzeł jest porównywany wyłącznie z encjami Components z własnego katalogu przestrzeni roboczej, jak opisuje to gniazdo importera, a każdy importer zawiera krótką tabelę mapującą typowe rodzaje węzłów swojego formatu — modele czatu i osadzeń, wyszukiwanie, żądania HTTP oraz, w Langflow, węzeł MCP Tools MCPTools, mapowany na core/ai-tool/mcp — na encje Components z biblioteki standardowej. Tabela Langflow mapuje też komponent Language Model, LanguageModelComponent, model czatu wywoływany przez przepływy startowe Langflow, na core/ai-model/openai, model obsługiwany przez połączenie z modelem platformy Langflow: węzeł działa u dostawcy modeli wskazanego w jego polu provider, domyślnie OpenAI, a węzeł wskazujący innego dostawcę nigdy nie jest podłączany do tego połączenia, jak opisuje to Które węzły stają się częściami. Tabela importera n8n mapuje modele czatu i osadzeń n8n, jego narzędzie klienta MCP na core/ai-tool/mcp, jego narzędzia żądań HTTP, narzędzie SerpApi, magazyny wektorowe Qdrant, PGVector, Chroma, Milvus i Weaviate oraz pamięci czatu Postgres i Redis. Węzeł, który n8n uruchamia w samym przepływie pracy — agent, łańcuch, wyzwalacz, pamięć przechowywana przez przepływ pracy we własnym procesie, narzędzie kodu — należy do przepływu pracy i żaden wiersz go nie mapuje. Wiersz tej tabeli liczy się do dopasowania tylko wtedy, gdy katalog przestrzeni roboczej zawiera encję Component, którą ten wiersz wskazuje. Polecenie wypisuje po jednym wierszu dla każdego zmapowanego węzła, podając dokonany wybór, poziom dopasowania i wynik najlepszego kandydata, a dla węzła, któremu nie nadaje własnej encji Component, wiersz made no choice for <node id> (<node type>). Węzeł, który odwołuje się do encji Component z katalogu zamiast zostać naszkicowany, nie ma własnego pliku: szkic encji Aggregate wskazuje tę encję Component.
Układ szkicu określa ustawienie layout. platform, wartość domyślna, tworzy szkic
platformy uruchamiającej przepływ, przenoszącej przepływ w postaci, w jakiej go wyeksportowano, i nadaje własną encję Component
tylko tym częściom przepływu, które przyjmuje gniazdo platformy — na platformach biblioteki standardowej są to
model, serwer MCP lub inne narzędzie dostępne przez HTTP oraz magazyn wektorowy. nodes tworzy szkic każdego węzła
jako osobnej encji Component.
Platforma przenosząca przepływ
Domyślnie import zapisuje:
aggregate.yaml— szkic encji Aggregate nazwany od przepływu, jak opisuje Jak nazywany jest szkic. Zawiera on jedną instancję platformy uruchamiającej przepływ —core/ai-agent/langflowpod kluczemlangflowdla przepływu Langflow,core/ai-agent/flowisepod kluczemflowisedla przepływu Flowise orazcore/ai-agent/n8npod kluczemn8ndla przepływu pracy n8n — odwołującą się do encji Component z katalogu o tej nazwie. Instancja przenosi przepływ wvalues.flow_definitioni wskazuje go w swojej wartości identyfikatora:flow_idw Langflow,chatflow_idwe Flowise iworkflow_idw n8n. Każda część przepływu jest osobnym wpisem obok niej, połączonym z platformą wusesinstancji.release.yaml— szkic encji Release o tej samej nazwie, wskazujący tę encję Aggregate, z wpisem dla platformy i po jednym dla każdej części, niosący obraz platformy i dołączający przez odwołanie każdy sekret, którego szkic potrzebuje, jak opisuje Co szkic pozostawia encji Release.- po jednym pliku w
components/dla każdej części, której szkic tworzy zamiast się do niej odwoływać, zapisanym tak, jak układ węzeł po węźle zapisuje naszkicowany węzeł.
Gdy podano cel, import szkicuje obok nich manifest.yaml, jak opisuje Co dodaje cel.
Każdy węzeł, który nie jest częścią, pozostaje w przepływie przenoszonym przez platformę i nie staje się encją Component.
Jego decyzja zapisuje kandydatów, z którymi go porównano, i niczego nie wybiera, a jej uzasadnienie
brzmi kept in the flow <platform> carries, with no Component of its own:, po czym następuje przyczyna — na przykład to, że żaden
wiersz mapowania nie wskazuje jego typu, a najbliższy kandydat uzyskał tylko określony wynik. Przepływ zachowuje
krawędzie między węzłami; szkic nie zapisuje własnych.
Przepływ czatu Multiple Documents QnA z Flowise, wyeksportowany jako Multiple Documents QnA.json i zaimportowany bez żadnego ustawienia i bez celu na podstawie katalogu zawierającego platformę Flowise z biblioteki standardowej oraz jej encje Components modelu i narzędzia wyszukiwania, zostaje naszkicowany jako następująca encja Aggregate; większość przepływu pominięto tu i oznaczono ...:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: 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-turboJego model czatu jest jedyną połączoną częścią; oba modele osadzeń pozostają w przepływie, ponieważ gniazdo modelu przyjmuje jedno połączenie, a narzędzia wyszukiwania pozostają w przepływie, ponieważ żadne gniazdo platformy ich nie przyjmuje. Import zgłasza każdy z nich.
Identyfikator przepływu to ten, który nadaje mu eksport — id najwyższego poziomu przepływu Langflow, id najwyższego poziomu
przepływu czatu Flowise, o ile jest to UUID, oraz id najwyższego poziomu przepływu pracy n8n — o ile składa się on z od 1
do 128 liter, cyfr, ., -, _
lub : i zaczyna się literą lub cyfrą. Jeśli eksport nie podaje identyfikatora lub podaje taki, który zawiera inny
znak, szkic zapisuje UUID oparty na nazwie, wyprowadzony z nazwy formatu i przepływu w postaci,
w jakiej jest przenoszony, więc jeden przepływ zawsze daje jeden identyfikator, a komentarz nad wartością informuje, że została wyprowadzona.
Przepływ czatu wyeksportowany z edytora Flowise nie zawiera id, więc otrzymuje identyfikator wyprowadzony.
Jeśli katalog przestrzeni roboczej nie zawiera encji Component o nazwie platformy, szkic mimo to wskazuje platformę, ale nie łączy z nią żadnej części: każdy węzeł, który byłby częścią, pozostaje w przepływie i zostaje zgłoszony, a import ostrzega, że katalog nie zawiera takiej encji Component.
Które węzły stają się częściami i gdzie każdy jest podłączany
Węzeł jest częścią przepływu, jeśli jego typ mapuje wiersz tabeli mapowania importera lub wpis mapping_overrides,
albo jeśli jego najlepszy kandydat jest dopasowaniem co najmniej średniego poziomu. Węzeł MCP
Tools z Langflow jest częścią niezależnie od wyników: wskazuje serwer MCP, który wywołuje, i to ten serwer jest
częścią. Część staje się osobną encją Component, do której szkic się odwołuje lub którą tworzy, dokładnie tak, jak rozstrzyga reuse_mode,
i zostaje podłączona do pierwszego gniazda platformy — w kolejności, w jakiej wpis katalogu platformy deklaruje
jej gniazda — którego selektor etykiet spełnia encja Component tej części: etykiety encji Component, do której
się odwołuje, lub, w przypadku części tworzonej w szkicu, etykiety jej najlepszego kandydata, o ile jest on dopasowaniem co najmniej
średniego poziomu. Część, której encja Component nie spełnia selektora żadnego gniazda lub która nie ma encji Component,
z której można odczytać etykiety, pozostaje w przepływie, a import ją zgłasza.
Zawężają to te reguły:
- Model Langflow wskazujący innego dostawcę nie otrzymuje połączenia z modelem. Węzeł
LanguageModelComponentlubEmbeddingModeldziała u dostawcy modeli wskazanego w jego poluprovideralbo, gdy jest ono puste, u dostawcy modelu wybranego w polumodel. Platforma dostarcza swoje połączenie z modelem dla klienta zgodnego z OpenAI, dlatego węzeł wskazujący dowolnego dostawcę innego niżOpenAI— niezależnie od tego, na co mapuje go wiersz mapowania lub nadpisanie — nigdy nie jest podłączany do gniazdamodel: jest podłączany do następnego gniazda, które spełnia jego encja Component, albo pozostaje w przepływie, a jego decyzja niczego nie wybiera i nie powstaje dla niego szkic żadnej encji Component, a import zgłasza go, podając dostawcę, u którego działa. Węzeł niewybierający żadnego dostawcy, wskazujący go przez zmienną globalną albo pobierający model z innego węzła jest podłączany jak każda inna część. - Gniazdo przyjmujące jedno połączenie zajmuje jedna część. Na każdej platformie gniazdo
modelprzyjmuje jedno połączenie, które encje Recipes platformy dostarczają jako jednoOPENAI_BASE_URLi jednoOPENAI_API_KEY. Jeśli umieszczono w nim kilka części, zajmuje je pierwsza, której encja Component mamodel.aggrega.ai/capability: generative— a jeśli żadna nie ma, pierwsza część — a każda pozostała zostaje w przepływie i jest zgłaszana wraz z częścią zajmującą połączenie oraz ze sposobem, w jaki przepływ do niej dociera przy zapisanym węźle. - Langflow dociera do połączenia
toolstylko przez wskazujący je węzeł MCP Tools. Platforma zapisuje adres połączenia narzędzi w konfiguracji serwera tego węzła MCP Tools, którego polemcp_serverwskazuje to połączenie, więc węzeł, którego szablon nie zawiera polamcp_server— niezależnie od typu i od tego, na co mapuje go wiersz mapowania lub nadpisanie — nigdy nie jest podłączany do gniazdatools: zostaje podłączony do następnego gniazda, które spełnia jego encja Component, albo pozostaje w przepływie i jest zgłaszany. Węzeł MCP Tools niewskazujący żadnego serwera nie jest podłączany do żadnego gniazda i zostaje zgłoszony. Tak samo węzeł, którego konfiguracja serwera uruchamia własny serwer — zawieracommandlub ustawia trybStdio— a jego zgłoszenie podaje, co usunąć, ponieważ kompilacja platformy zatrzymuje się na węźle wskazującym serwer, któremu nie odpowiada żadne połączenie narzędzi. - Serwer MCP jest podłączany według nazwy nadanej mu w przepływie. Węzły jednego przepływu wskazujące jeden serwer docierają do jednej części, naszkicowanej raz, przez jedno połączenie. Aliasem połączenia jest nazwa serwera, o ile alias połączenia może ją przyjąć — litery, cyfry, łączniki i podkreślenia — i żadne inne połączenie tego gniazda nie dostarcza danych pod tą samą nazwą zmiennej, czyli aliasem zapisanym wielkimi literami, w którym każdy inny znak zastąpiono podkreśleniem. W przeciwnym razie połączenie otrzymuje alias wyprowadzony z klucza części, serwer węzła zostaje przemianowany na ten alias w przepływie przenoszonym przez szkic, a decyzja części to odnotowuje.
Decyzja podłączonej części podaje, do którego gniazda platformy jest podłączona i przez które połączenie, oraz wymienia każde gniazdo, które ją pominęło, wraz z przyczyną.
Jak przenoszony przepływ dociera do każdej części
Tam, gdzie format na to pozwala, przepływ przenoszony przez platformę dociera do każdej podłączonej części przez jej połączenie, a szkic zapisuje w przepływie to, co to umożliwia — nazwę zmiennej, opróżniony adres albo opróżnione to, co węzeł wysłałby zamiast tego, co dostarcza połączenie — i nigdy wartość. To jest podłączanie, a nie usuwanie wartości poświadczenia: szkic zapisuje je niezależnie od tego, co mówi ustawienie empty_credentials, ponieważ zachowana tam wartość nadpisałaby to, co dostarcza połączenie.
-
Węzeł MCP Tools w Langflow. Platforma zapisuje adres dostarczany przez połączenie w konfiguracji serwera węzła, a tam, gdzie połączenie niesie poświadczenie, także nazwę zmiennej, która je przechowuje, pod nagłówkiem publikowanym przez narzędzie. Szkic zapisuje adres, który eksport tam przechowywał, jako pusty, aby przepływ nie zawierał jego kopii, i pozostawia adres serwera —
infra.endpointczęści — dla encji Release. Langflow wysyła własne poleheaderswęzła ponad nagłówkami jego konfiguracji serwera, dlatego szkic zapisuje całą wartość tego pola jako pustą, zachowując jej rodzaj — obiekt jako{}, listę jako[], tekst jako pusty ciąg — ponieważ nagłówek zachowany z opróżnioną wartością nadal byłby wysyłany, a pusty obiekt lub lista niczego nie nadpisuje. -
Węzeł modelu lub magazynu wektorów w Langflow. Platforma dostarcza połączenie z modelem jako
OPENAI_BASE_URLiOPENAI_API_KEY, a połączenie z magazynem wektorów jako zmienne nazwane od jego aliasu, które Langflow odczytuje przez pole wskazujące zmienną globalną: pole, którego obiekt zawieraload_from_db: true, przechowuje jako wartość nazwę zmiennej, a Langflow odczytuje zmienną globalną o tej nazwie albo, gdy żadna nie jest zapisana, zmienną środowiskową o tej nazwie. Szkic zapisuje każde z tych pól z nazwą zmiennej iload_from_db: true:- pole
openai_api_basewęzłaOpenAIModeljakoOPENAI_BASE_URL, a jegoapi_keyjakoOPENAI_API_KEY; - pole
openai_api_basewęzłaOpenAIEmbeddingsjakoOPENAI_BASE_URL, a jegoopenai_api_keyjakoOPENAI_API_KEY; - pole
api_keywęzłaLanguageModelComponentjakoOPENAI_API_KEY; - pole
api_basewęzłaEmbeddingModeljakoOPENAI_BASE_URL, a jegoapi_keyjakoOPENAI_API_KEY; - pole
pg_server_urlwęzłapgvectorjakoAGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING, gdzie<ALIAS>to alias połączenia zapisany wielkimi literami, z każdym znakiem innym niż litera lub cyfra zapisanym jako podkreślenie.
Węzeł
LanguageModelComponentlubEmbeddingModeldziała u jednego z kilku dostawców modeli — tego, którego wskazuje jego poleprovider, albo, gdy jest ono puste, dostawcy modelu wybranego w polumodel— i przekazuje swój klucz temu dostawcy. Platforma dostarcza połączenie z modelem dla klienta zgodnego z OpenAI, dlatego taki węzeł jest zapisywany ze zmiennymi tylko wtedy, gdy działa uOpenAI. Węzeł działający u innego dostawcy nigdy nie jest podłączany, jak opisano wyżej; węzeł niewybierający żadnego, wskazujący dostawcę przez zmienną globalną albo pobierający model z innego węzła jest zapisywany bez żadnej z nich, aby szkic nigdy nie kierował innego dostawcy do klucza połączenia. Tam, gdzie żadne pole takiego węzła nie podaje adresu jego API — węzełLanguageModelComponentnie ma takiego pola dla OpenAI, a poleapi_basewęzłaEmbeddingModelmoże nie istnieć lub być puste, gdy nie może wskazać zmiennej — uruchamiany przez niego klient OpenAI pobieraOPENAI_BASE_URLze środowiska, więc węzeł i tak dociera do adresu dostarczanego przez platformę.Klient węzła
OpenAIEmbeddingswysyła swojedefault_headersponad nagłówkami, które buduje z klucza, i scala swojedefault_queryz zapytaniem wywoływanego adresu, dlatego w takim węźle, który szkic podłącza, cała wartość każdego z nich jest zapisywana jako pusta z zachowaniem rodzaju, tak jakheaderswęzła MCP Tools.Pole, które eksport zapisuje bez obu tych elementów, nie jest zapisywane na nowo — pole poświadczenia wśród nich jest przenoszone tak, jak zostało zapisane, albo zapisywane jako puste, gdy wymaga tego ustawienie, jak opisano poniżej. Tam, gdzie to pole niesie adres części — a w przypadku węzła
LanguageModelComponentlubEmbeddingModelgo podaje — tam, gdzie taki węzeł nie działa uOpenAI, albo tam, gdzie węzeł jest dowolnego innego typu, import zgłasza część jako osiąganą pod adresem podanym przez przepływ lub domyślne ustawienia jego komponentu. - pole
-
Węzeł OpenAI we Flowise. Klient OpenAI, na którym Flowise uruchamia węzeł
chatOpenAIlubopenAIEmbeddings, odczytujeOPENAI_BASE_URLiOPENAI_API_KEYze środowiska, gdy Base Path węzła jest pusta i węzeł nie wybiera żadnego poświadczenia, dlatego szkic zapisuje Base Path przechowywaną w eksporcie jako pustą, a poświadczenie wybrane przez węzeł, wdata.credential, również jako puste. Ten klient wysyła domyślne nagłówki węzła, jegobaseOptions, ponad nagłówkiem budowanym z klucza, dlatego szkic zapisuje całą ich wartość jako pustą z zachowaniem rodzaju. Węzeł modelu dowolnego innego typu jest zgłaszany jako osiągany pod adresem podanym przez chatflow lub jego własne ustawienia domyślne. -
Narzędzie lub magazyn wektorów we Flowise. Chatflow odczytuje adres dostarczany dla nich przez platformę —
AGGREGA_TOOL_<ALIAS>_URLlubAGGREGA_VECTOR_STORE_<ALIAS>_URL— wyłącznie przez zmienną Runtime o tej nazwie, której nic nie tworzy przy uruchomieniu. Szkic niczego dla niej nie zapisuje, a import zgłasza krok, dzięki któremu chatflow ją odczyta: należy utworzyć zmienną Runtime na stronie Variables we Flowise i odczytać ją w węźle jako$vars.<name>. -
Dowolny węzeł n8n. Platforma dostarcza połączenie z modelem jako
OPENAI_BASE_URLiOPENAI_API_KEY, a połączenie z narzędziami lub magazynem wektorów jakoAGGREGA_TOOL_<ALIAS>_URLlubAGGREGA_VECTOR_STORE_<ALIAS>_URL, podczas gdy węzeł n8n dociera do modelu, magazynu lub usługi pod adresem podanym przez wybrane zapisane poświadczenie albo przechowywanym w jego własnych parametrach, a workflow odczytuje zmienną środowiskową tylko przez wyrażenie odczytujące$env, czego platforma odmawia, o ile encja Aggregate nie ustawiavalues.allow_env_access_in_nodesnatrue. Szkic pozostawia tę wartość domyślną,false, ponieważ jej ustawienie pozwala każdemu workflow i każdemu użytkownikowi, który może go edytować, odczytać każdą zmienną środowiska platformy, łącznie z dostarczonymi poświadczeniami. Dlatego szkic nie zapisuje w workflow niczego dla połączenia, a każda podłączona część jest zgłaszana jako osiągana inaczej niż przez nie. Węzeł klienta MCP dociera do swojego serwera pod adresem przechowywanym w workflow — tak, jak zapisał go eksport, lub żadnym, gdy ustawienieempty_credentialszapisuje go jako pusty, jak opisano poniżej — a własny adres serwera —infra.endpointczęści — pozostaje dla encji Release.
Tam, gdzie przepływ jest przenoszony, każda podłączona część jest zgłaszana z informacją, który z tych
przypadków zachodzi: part-reads-connection, gdy przepływ dociera do części przez jej połączenie, oraz
part-address-in-flow, gdy dociera do części inaczej niż przez połączenie — pod adresem przechowywanym
w przepływie lub podanym przez domyślne ustawienia jego komponentu. Decyzja części mówi to samo.
Węzeł, którego szkic nie podłącza do żadnego gniazda, nadal może zostać osiągnięty przez połączenie,
które szkic podłącza, zależnie od zapisu węzła: klient OpenAI bez własnego adresu i klucza odczytuje ze
środowiska OPENAI_BASE_URL i OPENAI_API_KEY dostarczane przez platformę dla połączenia z modelem.
Gdy tak się dzieje, szkic zapisuje węzeł tak jak podłączony, aby nic, co przechowuje, nie było wysyłane
zamiast tego, co dostarcza połączenie, i zgłasza go z part-reads-connection:
- węzeł
OpenAIEmbeddingsw Langflow, którego pole adresu wskazuje zmiennąOPENAI_BASE_URLdostarczaną przez platformę, odczytywaną jako zmienna globalna, gdy jakaś część jest podłączona do gniazda modelu: jegodefault_headersidefault_query; - węzeł
chatOpenAIlubopenAIEmbeddingswe Flowise, którego Base Path jest pusta i który nie wybiera żadnego poświadczenia, oraz konfiguracja takiego modelu przechowywana przez węzeł agentflow wśród jego wejść, gdy jakaś część jest podłączona do gniazda modelu: jegobaseOptions.
W każdym innym węźle te wartości nie są okablowaniem: są przenoszone tak, jak zostały zapisane, lub zapisywane jako puste, gdy wymaga tego ustawienie, jak opisuje następna sekcja.
Wartości poświadczeń zawarte w przepływie
Przed przeniesieniem przepływu import lokalizuje w nim każdą wartość, która może zawierać poświadczenie, w miejscach wymienionych poniżej, a każda należy do jednego z trzech rodzajów: to, co format oznacza jako poświadczenie; element konfiguracji serwera MCP, gdziekolwiek format ją przechowuje; oraz dane wejściowe, które format oznacza jako niebędące poświadczeniem, a które mimo to mogą je zawierać — nagłówki żądań, parametry zapytania, całe żądanie zapisane jako wiersz poleceń, dane wejściowe przechowujące poświadczenie pod nazwą poświadczenia.
Domyślnie import nie zapisuje żadnej z nich jako pustej: przepływ jest przenoszony tak, jak został wyeksportowany, a każda zlokalizowana wartość, która coś zawiera — nie jest pustym ciągiem ani null — jest wskazywana w ostrzeżeniu credential-carried przez swój węzeł i pole — nagłówek lub parametr zapytania przez jego nazwę — nigdy przez swoją wartość ani jakąkolwiek jej część, wraz z wartością ustawienia empty_credentials, która zapisuje ją jako pustą. Ustawienie włącza usuwanie: marked zapisuje jako puste to, co format oznacza jako poświadczenie, oraz każdy element konfiguracji serwera MCP; all zapisuje jako puste również dane wejściowe oznaczone jako niebędące poświadczeniem. Każda wartość zapisana jako pusta jest zgłaszana przez credential-emptied, przez swój węzeł i pole, nigdy przez wartość; wartość już pusta lub null pozostaje bez zmian i nie jest zgłaszana. Wartość, której ustawienie nie przyjmuje, zatrzymuje import, który niczego nie tworzy, zamiast być odczytana jako none.
Zlokalizowana wartość, która jest jednym odwołaniem do zmiennej i niczym więcej, nie zawiera własnej wartości: sama nazwa zmiennej, ${NAME} — łącznie ze zmienną predefiniowaną, taką jak ${workspaceFolder} lub ${userHome} — lub jedna z form definiowanych przez klientów MCP, ${env:NAME} i ${input:id}. Niezależnie od ustawienia jest przenoszona tak, jak została zapisana, i nie jest wskazywana w żadnym ostrzeżeniu, bez względu na format przepływu, tak jak zapisuje ją importer MCP. Tak samo jest z elementem będącym jednym odwołaniem wewnątrz wartości, którą format przechowuje jako tekst, np. mcpServerConfig we Flowise zapisany jako tekst JSON lub nagłówki i parametry zapytania przechowywane jako obiekt JSON w tekście we Flowise i n8n: przy zapisie jako pusty tekst zachowuje ten element w postaci zapisanej.
Odwołanie zawierające tekst po operatorze zawiera ten tekst, który może być kluczem, niezależnie od tego, czy przed operatorem stoi dwukropek: wartość domyślna, ${NAME:-value} lub ${NAME-value}; wartość alternatywna, ${NAME:+value} lub ${NAME+value}; komunikat, ${NAME:?message} lub ${NAME?message}; przypisanie, ${NAME:=value} lub ${NAME=value}. Jest lokalizowane jak każda inna wartość — domyślnie przenoszone i wskazywane w ostrzeżeniu credential-carried, zapisywane jako puste, gdy ustawienie tego wymaga dla jego rodzaju — i tak samo każdy inny tekst wewnątrz ${…}, np. ${config:name}, oraz tekst obok odwołania, np. --key=${NAME}.
To, co szkic zapisuje, aby węzeł docierał do swojego połączenia — adres zapisany jako pusty, nazwa zmiennej, wybrane poświadczenie lub domyślne nagłówki zapisane jako puste, jak opisuje Jak przenoszony przepływ dociera do każdej części — jest okablowaniem: jest zapisywane niezależnie od ustawienia, zgłaszane wraz ze sposobem, w jaki węzeł dociera do swojego połączenia, i nigdy nie jest zgłaszane jako wartość poświadczenia. To, co leży poza wszystkimi poniższymi miejscami, autor musi przejrzeć sam, jak mówi koniec tej sekcji.
To, co format oznacza jako poświadczenie — zapisywane jako puste przy marked i all:
- Langflow — wartość każdego pola szablonu oznaczonego
password: true, łącznie z polem zawierającym nazwę zmiennej globalnej, chyba że szkic zapisuje to pole z nazwą zmiennej dostarczanej przez platformę, jak opisano wyżej. - Flowise — poświadczenie, które węzeł przechowuje w
data.credential, wybierane przez jego parametr poświadczenia; wartość każdego wejścia deklarowanego winputParamsjako typupassword; orazFLOWISE_CREDENTIAL_IDwśród wejść węzła, a takżecredentiallubFLOWISE_CREDENTIAL_IDwewnątrz obiektu konfiguracji na dowolnej głębokości tych wejść, tak jak agentflow przechowuje konfigurację modelu lub narzędzia. - n8n —
idkażdego przechowywanego poświadczenia wybieranego przez węzeł, wcredentials.<type>.id. Eksport n8n przechowuje poświadczenie jako odwołanie, nigdy jego wartość, anameodwołania nie jest lokalizowane: n8n, importując przepływ pracy na innej instancji, rozwiązuje poświadczenie, któregoidnie posiada, po jego typie i nazwie. Poświadczenie, które starszy eksport wybiera wyłącznie po nazwie, wskazuje poświadczenie, ale żadnego nie zawiera, i nie jest lokalizowane. Ponadto wartość każdego parametru, który n8n oznacza jako hasło w definicjach swoich węzłów bazowych — np.secretwęzła Crypto lubpasswordwęzłów tworzących użytkownika — gdziekolwiek znajduje się wśród parametrów węzła; węzeł używany jako narzędzie agenta jest odczytywany jako węzeł, którym jest.
Konfiguracja serwera MCP — zapisywana jako pusta przy marked i all:
- Konfiguracja
mcp_serverwęzła MCP Tools w Langflow orazmcpServerConfigwęzła Flowise, zapisane jako tekst JSON lub jako obiekt: każda wartość nagłówka, niezależnie od tego, czy nagłówki są obiektem, wierszami klucza i wartości, czy obiektami scalanymi w całości, przy czym element innego rodzaju jest lokalizowany w całości; każda wartość środowiskowa; adres serwera; polecenie; oraz każdy argument. Żaden z formatów nie oznacza adresu, polecenia ani argumentu jako poświadczenia, a każde z nich może zawierać klucz — adres w części użytkownika, ścieżce lub zapytaniu — więc wszystkie trzy są również lokalizowane, w obu formatach. Po zapisaniu jako puste polecenie i każdy argument zachowują swoje elementy, więc konfiguracja uruchamiająca własny serwer nadal jest odczytywana jako taka. Gdy węzeł MCP Tools w Langflow jest podłączony do połączenia narzędzi, jego adres jest okablowaniem, jak opisano wyżej, i nigdy nie jest zgłaszany jako wartość poświadczenia. Konfiguracja Flowise zapisana jako tekst, który nie daje się odczytać jako obiekt JSON, jest lokalizowana w całości, ponieważ niczego w jej wnętrzu nie można zlokalizować. - Węzeł MCP Tools w Langflow, który nie ma pola
mcp_server, przechowuje swój serwer w osobnych polach — adres wsse_url, nagłówki wheaders_input, środowisko wenv, a cały wiersz poleceń wraz z argumentami wcommand— i Langflow również żadnego z nich nie oznacza jako poświadczenia, więc lokalizowane są każda wartość nagłówka, każdy wpisenv, adres i wiersz poleceń, przy czym ich pola i wpisy są zachowywane po zapisaniu jako puste. Gdyenvjest listą, każdy wpis jest zgłaszany według pozycji, ponieważ nazwa zmiennej i jej wartość dzielą jeden tekst. Taki węzeł nie wskazuje żadnego serwera MCP, więc nigdy nie jest podłączany do połączenia narzędzi. - Własne pole
headerswęzła MCP Tools w Langflow, które Langflow wysyła do serwera ponad nagłówkami jego konfiguracji, w węźle, którego szkic nie podłącza: cała jego wartość, zapisana jako pusta z zachowaniem rodzaju, tak jak w podłączonym węźle, i zgłaszana raz, jakoheaders. - Komponenty MCP Tools (SSE) i MCP Tools (stdio) w Langflow, które Langflow oznacza jako przestarzałe, przechowują swój serwer w jednym polu każdy — węzeł
MCPSseadres wurl, węzełMCPStdiocały wiersz poleceń wraz z argumentami wcommand— lokalizowanym w całości. Żaden z nich nie wskazuje serwera MCP, więc żaden nie jest podłączany do połączenia narzędzi. - Węzeł klienta MCP w n8n — MCP Client Tool wywoływany przez agenta, węzeł MCP Client lub klient serwera wymienionego w rejestrze n8n — przechowuje adres serwera w parametrze
endpointUrl, lubsseEndpointw pierwszej wersji, a nagłówki wyłącznie jako wybierane przez siebie poświadczenia; adres jest lokalizowany w całości, niezależnie od podłączenia.
Dane wejściowe, które format oznacza jako niebędące poświadczeniem — zapisywane jako puste tylko przy all:
- Nagłówki żądań — w Langflow
headerswęzłaAPIRequest,URLComponent,CloudflareWorkersAIEmbeddingslubConfluentKafkaProducerorazapi_headerswęzłaDoclingRemote; we FlowiseheaderswęzłahttpAgentflow,getApiChain,postApiChain,openApiChain,apiLoader,openAPIToolkitlubsearXNG,requestsGetHeaders,requestsPostHeaders,requestsPutHeadersirequestsDeleteHeadersnarzędzi Requests orazbaseOptions— domyślne nagłówki wysyłane przez klienta modelu — węzłaazureChatOpenAI,azureOpenAIEmbeddings,chatCerebras,chatOpenAICustom,openAIEmbeddingsCustom,chatOpenRouter,chatSambanovalubopenAI; w n8nheaderParameters,jsonHeaders,headerParametersUiiheaderParametersJsonwęzłan8n-nodes-base.httpRequest— jego bieżąca wersja przechowuje dwa pierwsze, wcześniejsze wersje dwa pozostałe — również tego samego węzła użytego jako narzędzie agenta,parametersHeadersijsonHeaderswęzła@n8n/n8n-nodes-langchain.toolHttpRequestorazheaderParametersUiwęzłan8n-nodes-base.graphql. Nazwa nagłówka nie zawiera sekretu, więc lokalizowana jest wartość każdego nagłówka, a jego nazwa zostaje zachowana, niezależnie od postaci nagłówków: obiekt nazw i wartości, wiersze klucza i wartości — w n8n wiersze znameivalue— lub obiekty, które Langflow scala w całości z nagłówkami. Każdy nagłówek jest zgłaszany po nazwie. Element listy, który nie jest wierszem nagłówka, jest lokalizowany w całości i zgłaszany według pozycji. Nagłówki zapisane jako tekst są lokalizowane w całości, z wyjątkiem Flowise i n8n, gdzie tekst zawiera nagłówki jako obiekt JSON: tam, przy opróżnianiu, tekst jest przepisywany w miejscu, każda wartość pusta, i zgłaszany raz z nazwami zawartych w nim nagłówków. Tekst n8n zaczynający się od=jest wyrażeniem, które n8n oblicza podczas wykonywania przepływu pracy, i jest lokalizowany w całości. Przy opróżnianiu opróżniana jest każda wartość, także wartości nagłówków bez sekretu, takich jakUser-Agent, więc zaimportowane żądanie jest wysyłane z pustymi nagłówkami, dopóki autor ich nie przywróci. - Parametry zapytania — w Langflow
query_paramswęzłaAPIRequestlubGoogleSerperAPIorazsearch_paramswęzłaSerpAPI,Serp,SearchAPIlubSearchComponent; we FlowisequeryParamswęzłahttpAgentfloworazcustomParametersloaderasearchApi; w n8nqueryParameters,jsonQuery,queryParametersUiiqueryParametersJsonwęzłan8n-nodes-base.httpRequest, użytego jako narzędzie lub nie,parametersQueryijsonQuerywęzła@n8n/n8n-nodes-langchain.toolHttpRequestorazqueryParametersiqueryParametersJson, które węzełn8n-nodes-base.facebookGraphApiprzechowuje w swoichoptions. Każdy jest wysyłany jako zapytanie żądania, a parametr zapytania może zawierać klucz — niektóre API wyszukiwania przyjmują go jakoapi_keyw zapytaniu — więc każdy jest lokalizowany tak jak nagłówki: każda wartość, z zachowaną nazwą, niezależnie od postaci parametrów, i każdy zgłaszany po nazwie; parametry zapisane jako tekst są lokalizowane w całości, z wyjątkiem Flowise i n8n, gdzie tekst zawiera je jako obiekt JSON, który przy opróżnianiu jest przepisywany w miejscu i zgłaszany raz z zawartymi w nim nazwami. Przy opróżnianiu opróżniana jest każda wartość, także wartości parametrów bez sekretu, więc zaimportowane żądanie jest wysyłane z pustymi parametrami — lub, z węzła HTTP Flowise, który nie wysyła parametru o pustej wartości, bez nich — dopóki autor ich nie przywróci. - Domyślne nagłówki i domyślne zapytanie węzła OpenAI, do którego nie dociera żadne połączenie —
default_headersidefault_querywęzła LangflowOpenAIEmbeddingsorazbaseOptionswęzła FlowisechatOpenAIlubopenAIEmbeddings, gdziekolwiek węzeł się znajduje, łącznie z konfiguracją modelu wybieranego przez agentflow, jeśli szkic ani nie podłącza węzła, ani nie znajduje docierającego do niego połączenia w zapisanej postaci; jeśli tak, są one okablowaniem, jak wyżej. Każde jest lokalizowane w całości i przy opróżnianiu zachowuje swój rodzaj — obiekt jako{}, lista jako[], tekst jako pusty ciąg — i jest zgłaszane raz. - Całe żądanie zapisane jako wiersz polecenia —
curl_inputwęzła LangflowAPIRequestorazcurlwęzłaWebhook, lokalizowane w całości, łącznie z wartością domyślną Webhooka. Żadne z nich nie jest odczytywane podczas działania przepływu: pierwsze tylko wypełnia pola węzła w edytorze, drugie pokazuje przykład. - Wejście przechowujące poświadczenie pod nazwą poświadczenia —
api_keywęzła LangflowOlivyaComponent,verification_tokenkażdego komponentu Composio orazmem0_configwęzłamem0_chat_memory, którego cała wartość przy opróżnianiu zachowuje swój rodzaj; a takżewebhookSecreticallbackSecretwęzła FlowisestartAgentfloworazbearerTokenwęzłateradataMCP. Każde jest lokalizowane w całości. Wejście, którego nazwa jedynie przypomina poświadczenie — nazwa klucza przechowywanego gdzie indziej, nazwa użytkownika lub opcja, którą komponent deklaruje jako niebędącą sekretem — nie jest lokalizowane.
Poza wartościami opróżnianymi przez ustawienie, tym, co szkic zapisuje, aby przepływ docierał do swoich części, uchwytami krawędzi Langflow, zapisanymi tak, jak zapisuje je edytor Langflow, oraz znakami powrotu karetki zapisywanymi jako znaki nowego wiersza (opisanymi niżej), przepływ jest przenoszony tak, jak został wyeksportowany: bez żadnej z tych zmian — bajt w bajt.
Połączenie w szkicu nie przenosi wartości poświadczenia: szkic encji Release dołącza przez odwołanie to, które przedstawia każde połączenie, jak opisuje Co szkic pozostawia encji Release.
Każda wartość, którą ustawienie pozostawia bez zmian, trafia do szkicu, a autor przegląda ją, kierując się
ostrzeżeniami credential-carried. Do reszty przepływu nie odnosi się też żadna reguła dotycząca pól, więc autor
przegląda ją również przed udostępnieniem szkicu: własny kod komponentu, który przepływ przenosi i w którym
niestandardowy komponent może przechowywać klucz; wejścia, które edytor dodaje do węzła poza zadeklarowanymi przez
jego komponent; treść, z jaką wysyłane jest żądanie, np. węzła APIRequest lub httpAgentflow, która
może zawierać token; argumenty, które węzeł przekazuje klientowi swojego modelu lub loaderowi jako osobny
obiekt, np. model_kwargs węzła Langflow EmbeddingModel lub additionalInputs węzła Flowise replicate,
które mogą zawierać klucz pod dowolną nazwą; adres inny niż adres serwera MCP,
który może zawierać klucz w części użytkownika lub w zapytaniu; kod węzła Code w n8n oraz nagłówki lub
zapytanie węzła wysyłającego żądanie, którego importer nie wymienia powyżej; a także dowolny tekst, taki jak
prompt czy wiadomość.
Co szkic pozostawia encji Release
Szkic encji Release zawiera, we wpisie platformy i we wpisie każdej części, to, czego przepływ nie może dostarczyć:
- Obraz platformy, jako
infra.image: obraz wybrany przez sam importer, w wersji, z którą wiadomo, że działają encje Recipes katalogu dla tej platformy —langflowai/langflow:1.6.0,flowiseai/flowise:3.1.3in8nio/n8n:1.110.1— pod komentarzem, który to stwierdza. Import nigdy nie podnosi ani nie obniża tej wersji, by podążać za źródłem; gdy eksport podaje inną wersję platformy, jak robi tolast_tested_versionprzepływu Langflow, komentarz ją wymienia. - Port, na którym publikowana jest platforma, jako
infra.published_port, wyłącznie z--target compose: 7860 dla Langflow, 3000 dla Flowise i 5678 dla n8n, czyli porty, na których każda z nich obsługuje żądania, a które jej encja Recipe dla Compose publikuje na adresie pętli zwrotnej hosta, 127.0.0.1. Komentarz nad nim mówi, że port jest osiągalny tylko z tej maszyny, przez dowolny działający na niej proces, oraz że usunięcie wiersza pozostawia usługę wewnętrzną. Drugi przepływ jednego importu otrzymuje następny port, którego nie zajmuje żaden wcześniejszy. Z każdym innym celem lub bez celu nie jest zapisywany. - Własny sekret platformy i poświadczenie każdego połączenia z modelem, dołączane przez odwołanie i nigdy jako wartość: w Langflow slot
admin_password, odczytywany, dopókivalues.require_authenticationpozostajetrue; we Flowise slotowner_password, wymagany, dopóki ustawionovalues.flow_definition; oraz, gdy część jest podłączona do gniazdamodelplatformy,credentialtego połączenia. Platforma n8n nie przyjmuje własnego sekretu. Sposób dołączenia każdego z nich zależy od celu, jak opisuje Sekrety dla każdego celu. - Każda wartość, której nie zawiera żadne źródło, zapisywana jako pusty ciąg pod komentarzem mówiącym, czym jest: we Flowise
infra.owner_email, adres e-mail konta właściciela, wymagany, dopóki ustawionovalues.flow_definition; oraz adres każdego serwera MCP podłączonego do platformy,infra.endpointjego części. Każda z nich jest wartością, której wymaga import, a odpowiada się na nią tak, jak opisuje Plik odpowiedzi importu.
Poświadczenie, które przedstawia połączenie z narzędziem lub magazynem wektorowym, nie jest szkicowane: poświadczenie takiego połączenia zatrzymuje kompilację tam, gdzie narzędzie nie publikuje nagłówka, w którym można je wysłać, więc komentarz nad wpisem platformy je wymienia, aby można je było dołączyć tam, gdzie narzędzie je przyjmuje.
Sekrety dla każdego celu
W --target helm każdy sekret jest typu core/referenced-secret, którego origin to nazwa obiektu Secret Kubernetes znajdującego się już w przestrzeni nazw i przechowującego wartość pod kluczem danych value. Tej nazwy nie może podać żadne źródło, więc jest zapisywana jako pusta pod komentarzem opisującym, co przechowuje, i należy do wartości, które import pozostaje winien; szkic encji Manifest mapuje core/referenced-secret na helm/k8s-existing-secret.
W każdym innym celu, a także bez celu, każdy sekret jest typu core/secret-value, którego origin jest odwołaniem do zmiennej — ${LANGFLOW_ADMIN_PASSWORD}, ${FLOWISE_OWNER_PASSWORD} oraz ${OPENAI_API_KEY} dla poświadczenia połączenia z modelem — które cel podstawiający odwołania do zmiennych, tak jak robi to Docker Compose przy uruchamianiu stosu, odczytuje ze środowiska, więc żaden plik nie zawiera wartości i nic nie pozostaje za nią winne. Powyższy chatflow Flowise, zaimportowany bez celu, otrzymuje szkic z taką encją Release:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: 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: {}Bez celu import pozostaje winien dwie wartości, spec.manifest i infra.owner_email; z --target compose tylko adres e-mail właściciela; z --target helm adres e-mail właściciela i nazwy dwóch obiektów Secret Kubernetes.
W celu compose sekret dołączany wyłącznie przez encję Release trafia pod jeden klucz, value, więc hasło właściciela lub administratora i poświadczenie połączenia trafiłyby pod ten sam klucz. Dlatego encja Aggregate deklaruje każde z nich z własnym kluczem tam, gdzie platforma rysuje połączenie: owner_password z kluczem OWNER_PASSWORD we Flowise, admin_password z kluczem LANGFLOW_SUPERUSER_PASSWORD w Langflow oraz credential połączenia z modelem z kluczem OPENAI_API_KEY na wszystkich trzech platformach, każde pod komentarzem wyjaśniającym powód. Z --target compose te wiersze są zapisywane jako aktywne; bez celu są zapisywane jako zakomentowane, jak w przykładzie powyżej, aby można je było odkomentować przy kompilacji dla compose; z każdym innym celem nie są zapisywane. Encja Release dołącza źródło każdego slotu, wskazując ten sam typ lub żaden.
Gdy ustawienie attach_egress_allowlist ma wartość true, instancja platformy deklaruje także encję Feature core/egress-allowlist z biblioteki standardowej w features, jako egress-allowlist, dzięki czemu platforma łączy się tylko z komponentami, do których prowadzą jej połączenia, z własnymi podami i z DNS klastra — jest to wychodzący odpowiednik krawędzi uses jako zadeklarowanego wywołania. Encja Aggregate deklaruje typ załącznika i nic więcej, ponieważ załącznik encji Aggregate nie zawiera infra, a szkic encji Release nie zapisuje niczego z tego: komentarz nad wpisem platformy wymienia w features.egress-allowlist.infra klucz control_plane_present, który operator ustawia na true, aby potwierdzić, że wtyczka sieciowa klastra egzekwuje politykę sieciową, bez czego kompilacja zostaje zatrzymana; admitted_destinations, listę zawierającą dla każdego połączenia, którego celu klaster nie uruchamia, na przykład hostowanego modelu, wpis wskazujący cel i zakres adresów, bez której kompilacja zostaje zatrzymana ze wskazaniem tego połączenia; oraz aggrega.ai/namespace dla granicy zawierającej platformę, ponieważ polityka jest umieszczana w przestrzeni nazw jej obciążeń, a kompilacja zostaje zatrzymana, gdy nie są one emitowane do żadnej. Żaden z tych kluczy nie jest zapisywany jako pusty, więc żaden nie należy do wartości, które import pozostaje winien. Decyzja każdej podłączonej części stwierdza, że załącznik dopuszcza jej połączenie, a import zgłasza załącznik jako feature-attached. Compose nie ma polityki sieciowej, więc kompilacja compose takiego szkicu zostaje zatrzymana ze wskazaniem załącznika; tam, gdzie platforma rysuje połączenie, powyższe wiersze compose są zapisywane w bloku features instancji, bez drugiego klucza features.
Model obsługiwany przez część
Część, do której odwołuje się szkic i której encja Component deklaruje wartość o nazwie model — jak robi to, i wymaga tego,
każda modelowa encja Component biblioteki standardowej — jest zapisywana z nazwą modelu wybranego przez jej węzeł,
jako values.model:
- Langflow —
model_namewęzłaOpenAIModellubAnthropicModel;modelwęzłaOpenAIEmbeddings; oraz nadpisaniemodel_namewęzłaLanguageModelComponentlubEmbeddingModel, jeśli jest ustawione, a w przeciwnym razie model wybrany w jego polumodel. - Flowise —
modelNamewęzłachatOpenAI,chatAnthropiclubopenAIEmbeddings. - n8n — parametr
modelwęzła czatu, uzupełniania lub osadzeń, który mapuje tabela importera, albo jegomodelNamew węzłach Google Gemini i Vertex, zapisany jako nazwa lub jako wartość selektora, w którym przechowują go nowsze węzły n8n. n8n pomija w eksporcie parametr ustawiony na wartość domyślną, więc węzeł zachowujący domyślny model nie wskazuje w eksporcie żadnego.
Encja Release nie może zapisać wartości. Dlatego tam, gdzie węzeł nie wskazuje modelu, który szkic mógłby zapisać — nie wybiera
żadnego, wskazuje go przez zmienną globalną lub wyrażenie odczytywane dopiero podczas działania przepływu, pobiera go
z innego połączonego z nim węzła albo jest typu, którego pola modelu importer nie odczytuje — komentarz
wewnątrz części pozostawia values.model autorowi, a import zgłasza to jako
model-not-named. Część tworzona przez szkic jest zapisywana bez wartości.
Jak przepływ jest zapisywany w szkicu
Przepływ jest zapisywany jako blok literałowy YAML, którego tryb obcinania zachowuje końcowe znaki nowego wiersza, więc
values.flow_definition odczytuje się jako własny tekst przepływu. Tekst encji Aggregate jest odczytywany jako
szablon, więc każde {{ zawarte w przepływie — chatflow Flowise zapisuje {{<node id>.data.instance}} dla
każdego połączenia między dwoma węzłami — jest zapisywane jako {{"{{"}}, które interpolacja zamienia z powrotem
na dwa nawiasy klamrowe, jak opisuje
Tekst zawierający własne podwójne nawiasy klamrowe.
Nazwa modelu jest zapisywana w ten sam sposób.
Blok literałowy nie może przenieść każdego znaku w zapisanej postaci:
- Powrót karetki — z pary CR LF lub samodzielny — jest zapisywany jako jeden znak nowego wiersza. Dokument
JSON zawiera go tylko między tokenami, gdzie każdy biały znak jest odczytywany tak samo, więc platforma odczytuje
ten sam przepływ. Import zgłasza ich liczbę jako
carriage-returns-rewritten. - Każdy inny znak, którego blok literałowy nie może przenieść, uniemożliwia przeniesienie przepływu:
znak podziału wiersza — U+0085, U+2028 lub U+2029; znak sterujący inny niż tabulator i znak nowego
wiersza — od U+0000 do U+001F, U+007F oraz od U+0080 do U+009F; nieznaki U+FFFE i U+FFFF; oraz
bajt niebędący częścią sekwencji UTF-8.
values.flow_definitionpozostaje wtedy nieustawione, z komentarzem, który o tym informuje, reszta jest tworzona w szkicu, a import zgłaszadefinition-not-carrieddla każdego rodzaju znaku, podając, ile ich zawiera przepływ, oraz wiersz i kolumnę pierwszego.
Przepływ nie jest przenoszony również wtedy, gdy wartość, którą szkic zapisuje jako pustą lub od nowa, nie występuje w bajtach
eksportu w miejscu, w którym przechowuje ją sparsowane drzewo, a import zgłasza definition-not-carried, wskazując miejsce tej
wartości. Identyfikatorem przepływu jest wtedy jego własny, jeśli szkic może go przenieść, a w przeciwnym razie identyfikator
wyprowadzony z identyfikatorów węzłów przepływu.
Węzeł po węźle
Przy layout: nodes import tworzy w szkicu każdy węzeł przepływu jako osobną encję Component i zapisuje:
aggregate.yaml— szkic encji Aggregate nazwany od przepływu, jak opisuje Jak nazywany jest szkic, składający węzły przepływu: wpis dla każdego, a każda krawędź przepływu staje się połączeniemuseswęzła, który zasila, a jej gniazdo i alias są nazwane od klucza węzła, który ją zasila, więc węzeł zasilany przez kilka węzłów nadaje każdemu połączeniu własny alias.- jeden plik w
components/dla każdego węzła tworzonego w szkicu — szkic encji Component o nazwie<target_namespace>/<category>/<name>, z nazwą wziętą z typu węzła, w wersji0.1.0, z polami wartości jako polami tekstowymi zamkniętego obiektuvaluesi polami poświadczeń jako wymaganymi slotami poświadczeń, o których dostarczeniu decyduje encja Recipe. release.yaml— szkic encji Release o tej samej nazwie, wskazujący tę encję Aggregate, z wpisem dla każdego węzła.
Sam przepływ nie jest przenoszony i nie jest odczytywana wartość żadnego pola.
Przenoszenie samego wyeksportowanego przepływu
Domyślny szkic przenosi przepływ: instancja platformy przyjmuje eksport jako
values.flow_definition, zapisany tak, jak opisuje to Jak przepływ jest zapisywany w szkicu.
Autor, który ręcznie zapisuje przepływ w encji Aggregate — w szkicu rozpisanym węzeł po węźle albo
we własnej encji Aggregate — zapisuje go w ten sam sposób. Encja Component, która uruchamia przepływ w postaci, w jakiej go utworzono,
przyjmuje eksport jako wartość — flow_definition w core/ai-agent/langflow
i core/ai-agent/flowise z biblioteki standardowej — a tekst encji Aggregate jest odczytywany jako szablon, więc podwójne nawiasy klamrowe zawarte w
eksporcie zostałyby odczytane jako akcje szablonu: chatflow Flowise zapisuje {{<node id>.data.instance}}
dla każdego połączenia między dwoma węzłami, prompt Flowise nazywa zmienną jako {{question}}, a
eksport Langflow zawiera kod źródłowy swoich komponentów, w którym nawiasy klamrowe również mogą wystąpić.
Każde {{ w eksporcie należy zapisać jako {{"{{"}}, wewnątrz skalara blokowego, a interpolacja przywróci
tekst eksportu, zanim odczytają go encje Recipes tej encji Component;
Tekst zawierający własne podwójne nawiasy klamrowe
wyjaśnia dlaczego. Wartość poświadczenia zawarta w eksporcie należy do sekretu dołączanego przez encję Release, a nie do
encji Aggregate: należy ją zapisać jako pustą, tak jak robi to szkic, gdy wymaga tego ustawienie empty_credentials.
# Aggregate fragment — a Flowise chatflow carried as exportedspec: 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": [] }Importer MCP
importer/mcp odczytuje serwery MCP wymienione w konfiguracji klienta MCP albo jeden serwer opisany w opisie serwera z rejestru MCP i tworzy szkic każdego serwera jako instancji narzędzia MCP z biblioteki standardowej, core/ai-tool/mcp. Każdy serwer jest takim narzędziem, więc importer nie rozważa żadnych kandydatów i nie raportuje żadnej decyzji o mapowaniu.
Co odczytuje
- Konfiguracja klienta. Pliki
.mcp.jsonprogramu Claude Code,claude_desktop_config.jsonprogramu Claude Desktop i.cursor/mcp.jsonprogramu Cursor wymieniają swoje serwery według nazwy pod kluczemmcpServers; plik.vscode/mcp.jsonprogramu Visual Studio Code wymienia je pod kluczemservers, a plik wymieniający serwery pod oboma kluczami jest odczytywany najpierw podmcpServers. Serwer, któregotypetostdio, albo który nie podajetypei zawieracommand, jest uruchamiany z wiersza poleceń — jegocommandi jegoargs— z jegoenvjako środowiskiem. Serwer, któregotypetohttp,streamable-httplubsse, albo który nie podaje anitype, anicommandi zawieraurl, jest osiągany pod swoimurli otrzymuje swojeheaders. - Opis serwera z rejestru. Plik
server.jsonpublikowany przez rejestr MCP: jegonameoraz jego pierwszy pakiet albo, gdy nie wymienia żadnego, jego pierwszy zdalny serwer. Pakiet npm lub PyPI jest uruchamiany z wiersza poleceń, który tworzą jego program uruchamiający — jegoruntimeHintalbonpxdla npm iuvxdla PyPI — jegoruntimeArguments, pakiet wraz z wersją, zapisany jako<identifier>@<version>dla npm i<identifier>==<version>dla PyPI, oraz jegopackageArguments, z jegoenvironmentVariablesjako środowiskiem. Argument pozycyjny to jegovaluealbo jegodefault; argument nazwany jest zapisywany jako<name>=<value>, gdy ma którąś z nich, a jako jegoname, gdy nie ma żadnej. Pakiet OCI jest uruchamiany z obrazu wskazanego przez jegoidentifier. Zdalny serwer jest osiągany pod swoimurli otrzymuje swojeheaders. Każdy inny pakiet i zdalny serwer wymieniony w opisie jest wskazany w komentarzu, ponieważ jedna instancja uruchamia jeden z nich.
Każdy inny element serwera — cwd, envFile, auth programu Cursor albo element, którego dany rodzaj serwera nie
odczytuje, taki jak url serwera uruchamianego z wiersza poleceń — nie jest nigdzie zapisywany, lecz jest wskazany w
komentarzu nad wpisem serwera w encji Release, ponieważ żaden klucz infrastruktury core/ai-tool/mcp
go nie przyjmuje. Klucz inputs konfiguracji, który opisuje, o co pyta Visual Studio Code, i nie zawiera
wartości, nie jest odczytywany. Serwery, ich środowisko i ich nagłówki zachowują kolejność, w jakiej zapisuje je źródło,
z wyjątkiem konfiguracji odczytywanej jako JSON z komentarzami, która zachowuje kolejność, w jakiej zapisuje je jej przeanalizowane
drzewo: kolejność nazw (zob. Konfiguracja zawierająca komentarze).
Katalog jest odczytywany poprzez zawarte w nim konfiguracje klientów — każdy plik nazwany jak jeden z czterech, na dowolnej głębokości — w kolejności ich ścieżek, a każdy serwer z każdego pliku trafia do szkicu jednej encji Aggregate.
Czym staje się serwer
aggregate.yaml to szkic encji Aggregate nazwany od źródła, jak opisuje Jak nazywany jest szkic, zawierający jedną instancję core/ai-tool/mcp na każdy serwer. Kluczem instancji jest nazwa jej serwera zapisana małymi literami, w której każdy ciąg znaków innych niż litery i cyfry zapisano jako jeden łącznik, z przyrostkiem liczbowym, gdy wcześniejszy serwer zajął już ten klucz. Gdy klucz nie jest nazwą serwera w zapisanej postaci albo import odczytał kilka plików, komentarz nad instancją wskazuje serwer i plik, z którego pochodzi. Nie powstaje szkic żadnego agenta, który by z nich korzystał.
Obok niego release.yaml to szkic encji Release o tej samej nazwie, której spec.aggregate wskazuje
encję Aggregate, zawierający dla każdej instancji dane operacyjne podane przez źródło:
- dla serwera uruchamianego z wiersza poleceń:
infra.stdio_command, jego polecenie, a następnie każdy argument, każdy jako osobny element; orazinfra.stdio_runtime, ekosystem programu uruchamiającego:npm, gdy polecenie tonpx,npmlubnode,pypi, gdy touvx,uv,pythonlubpython3, a dla pakietu z rejestru — jego rejestr,npmlubpypi; - dla serwera osiąganego pod adresem:
infra.endpoint, czyli adres bez części użytkownika, zapytania i fragmentu, ponieważ encja Component przyjmuje adres bez żadnej części zawierającej klucz; każda pominięta część jest zapisywana w komentarzu nad wpisem, obok adresu, jak opisuje Wartości poświadczeń przechowywane przez serwer; - dla pakietu OCI:
infra.image; - dla żadnego serwera, w żadnym celu,
infra.published_port: szkic nigdy nie publikuje serwera na hoście; - dla środowiska serwera slot
server_env, dołączany przez odwołanie zgodnie z celem importu. W--target helmjest tocore/referenced-secretwskazujący obiekt Secret Kubernetes znajdujący się już w przestrzeni nazw, który przechowuje jeden klucz danych na zmienną, każdy nazwany tak jak zmienna, którą przechowuje; nazwa obiektu Secret jest zapisywana jako pusta pod komentarzem wymieniającym klucze danych i należy do wartości, które import pozostaje winien. W każdym innym celu, a także bez celu, jest tocore/referenced-secret-setz jednym wpisem winfra.entriesna zmienną, z nazwą zmiennej jako kluczem i wartością w postaci zapisanej przez źródło, więc odwołanie do zmiennej, takie jak${GITHUB_TOKEN}, pozostaje odwołaniem, które cel podstawiający odwołania do zmiennych odczytuje ze środowiska.
To, czego źródło nie podaje, jest zapisywane jako puste pod komentarzem opisującym, czym jest: polecenie, którego programu uruchamiającego nie zawiera żaden z obrazów mostka, pozostawia infra.stdio_runtime puste, a import pozostaje je winien; argument, który opis z rejestru pozostawia użytkownikowi, jest zapisywany jako pusty element, a zmienna, której wartości źródło nie zapisuje, jako wpis z pustą wartością, każde wskazane w komentarzu nad wpisem.
Jak każdy szkic encji Release, zapisuje metadata.environment jako development pod komentarzem mówiącym, że jest to domyślna wartość szkicu do zmiany, a bez celu spec.manifest jako pusty ciąg, który import pozostaje winien. Gdy podano cel, importer sam tworzy szkic encji Manifest, ponieważ katalog realizuje core/ai-tool/mcp za pomocą kilku encji Recipes i tylko importer wie, jak działa każdy serwer: mapuje każdy serwer według jego klucza, w mappings.components.name, na realizację celu odpowiadającą sposobowi działania serwera — mcp-stdio-bridge dla wiersza poleceń, mcp-remote dla adresu, mcp dla obrazu, na przykład helm/mcp-stdio-bridge lub compose/mcp-remote — a typ sekretu, jako który dołączane jest środowisko, na jego realizację: helm/k8s-existing-secret w helm i compose/dotenv-secret-set w compose. Import uzupełnia tę encję Manifest i wskazuje ją w encji Release, jak opisuje Co dodaje cel.
Plik .mcp.json programu Claude Code wymieniający serwer osiągany przez HTTP i serwer uruchamiany przez npx:
{ "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}" } } }}daje następujący szkic:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: 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/mcpapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: 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}"Po imporcie z --target helm encja Release tej samej konfiguracji dołącza środowisko jako wskazany przez siebie obiekt Secret, a szkic encji Manifest tworzony przez importer mapuje każdy serwer według jego klucza:
# 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: ""apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/mcp version: 0.1.0spec: mappings: components: type: {} name: api-server: helm/mcp-remote github: helm/mcp-stdio-bridge features: type: core/referenced-secret: helm/k8s-existing-secretWartości poświadczeń przechowywane przez serwer
Każda wartość konfiguracji serwera zapisywana przez encję Release — wartość każdego nagłówka, każdy element wiersza polecenia, adres, każda część adresu pomijana przez infra.endpoint oraz każda wartość środowiskowa — może zawierać klucz, a żaden klient nie oznacza jej jako poświadczenia, dlatego import lokalizuje każdą z nich jako element konfiguracji serwera MCP; dane wejściowe rejestru oznaczone isSecret są lokalizowane jako wartość, którą jej format oznacza jako poświadczenie. Dane wejściowe rejestru — zmienna środowiskowa lub nagłówek serwera zdalnego — są odczytywane jako ich value albo jako ich default, jeśli nie zapisują żadnej wartości. Domyślnie każda z nich jest przenoszona do encji Release w zapisanej postaci i wymieniana w ostrzeżeniu credential-carried według serwera i miejsca — headers.<header>, infra.stdio_command.<position>, infra.endpoint lub server_env.<variable>, a część adresu według url, w którym jest zapisana, i nazwy tej części, jak w „url of node remote-search is carried with its query as written (url węzła remote-search jest przenoszony z zapytaniem w zapisanej postaci)” — nigdy według wartości. Przy ustawieniu empty_credentials równym marked lub all każda z nich jest zapisywana jako pusta i zgłaszana przez credential-emptied: element wiersza polecenia jako pusty element, a wartość środowiskowa jako pusta wartość, każde wskazane w komentarzu nad wpisem; adres jako puste infra.endpoint, które import pozostaje winien; a wartość nagłówka lub część adresu są pomijane w komentarzu, który wymienia wyłącznie nagłówek lub część. infra.stdio_runtime klienta jest odczytywane z polecenia w postaci zapisanej przez encję Release, więc polecenie zapisane jako puste pozostawia je również puste, a import pozostaje je winien. W --target helm encja Release nie zapisuje żadnej wartości środowiskowej: przechowuje je obiekt Secret wskazany przez slot server_env.
Wartość, która jest jednym odwołaniem do zmiennej i niczym więcej — sama nazwa ${NAME}, w tym predefiniowana zmienna, taka jak ${workspaceFolder}, ${env:NAME} lub ${input:id} — nie przechowuje własnej wartości: jest zapisywana jako tekst, którym jest, niezależnie od ustawienia, i nie jest wymieniana w żadnym ostrzeżeniu, podobnie jak odwołanie w przepływie. Zmienna środowiskowa, której wartością jest takie odwołanie, jest zapisywana jako wartość wpisu, a odwołanie pozostaje odwołaniem; nagłówek lub część adresu, których wartością jest takie odwołanie, są wymieniane wraz z odwołaniem, z którego czytają. Odwołanie zawierające tekst po operatorze — wartość domyślną, alternatywę, komunikat lub przypisanie, np. ${NAME:-value} lub ${NAME-value}, z dwukropkiem lub bez — przechowuje ten tekst, podobnie jak tekst obok odwołania; każdy z nich jest lokalizowany jak każda inna wartość.
Żaden klucz infrastruktury core/ai-tool/mcp nie przyjmuje wartości nagłówka: poświadczenie serwera zdalnego przechowuje każdy konsument w swoim połączeniu z narzędziem, a import nie tworzy szkicu żadnego konsumenta. Dlatego komentarz nad wpisem serwera wymienia każdy nagłówek wysyłany do niego przez źródło, obok jego wartości w zapisanej postaci — ciągu w podwójnych cudzysłowach odczytywanego dokładnie jako tekst źródła — aby można było przenieść go do połączenia konsumenta, który go przedstawia. Nagłówek, którego wartości źródło nie zapisuje, np. nagłówek wejściowy rejestru bez wartości i bez wartości domyślnej, jest wymieniany jako nieposiadający wartości. Obraz wskazany przez pakiet OCI jest zapisywany bez zmian i nie jest wartością, której dotyczy ustawienie.
infra.endpoint przyjmuje adres bez żadnej części zawierającej klucz, więc zapisane przez źródło części adresu, które pomija — część użytkownika przed @, zapytanie po ? i fragment po #, przy czym fragmentem jest wszystko po pierwszym # — są wymieniane w tym samym komentarzu, każda obok swojej nazwy i w zapisanej postaci, bez oddzielającego ją @, ? lub #. Konsument odczytujący klucz z adresu podaje cały adres we własnym połączeniu z narzędziem. Serwer osiągany pod adresem https://user:pw@api.example.com/mcp?key=k, bez ustawienia, jest szkicowany jako:
# 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"a przy empty_credentials równym marked wartość infra.endpoint jest pozostawiana encji Release, a komentarz wymienia user part i query, każdą z pominiętą wartością.
Konfiguracja zawierająca komentarze
Visual Studio Code odczytuje .vscode/mcp.json jako JSON z komentarzami, podobnie jak importer MCP: jego sygnatura dla tego pliku odczytuje go za pomocą parsera obsługującego parse:jsonc, więc konfiguracja zawierająca komentarze // i /* */ oraz końcowe przecinki jest rozpoznawana bez podawania formatu, a importer odczytuje za pomocą tego parsera każde źródło wymieniające serwery w servers. Taka konfiguracja jest szkicowana dokładnie tak samo jak ta sama konfiguracja bez komentarzy i końcowych przecinków. Parser zapisuje elementy obiektu w kolejności nazw, więc serwery takiej konfiguracji, ich środowisko i nagłówki są szkicowane w kolejności nazw, niezależnie od tego, czy zawiera ona komentarz; wiersz polecenia zachowuje swoją kolejność. Pozostali klienci i rejestr odczytują swoje pliki jako JSON, podobnie jak importer: plik .mcp.json, claude_desktop_config.json, .cursor/mcp.json lub server.json zawierający komentarz nie jest rozpoznawany przez żadną sygnaturę, a zaimportowany z podaniem --format mcp zatrzymuje się z parse-failed i przyczyną podaną przez parser. Komentarz otwarty przez /* i nigdy niezamknięty pozostaje w zapisanej postaci, a parser odrzuca plik.
Odczytywane ustawienia
Importer MCP odczytuje target_namespace i empty_credentials w sposób opisany w sekcji Ustawienia i nie odczytuje żadnego innego ustawienia.
Importer Compose
importer/compose odczytuje usługi i modele deklarowane w pliku Compose. Każdą usługę tworzy w wersji roboczej jako instancję encji Component z katalogu, do której pasuje jej obraz, albo ogólnego serwera z biblioteki standardowej, core/compute/server, uruchamiającego jej obraz; każdy model jako instancję środowiska uruchomieniowego Docker Model Runner z biblioteki standardowej, core/ai-model/docker-model-runner, jeśli katalog go zawiera, a jako osobną encję Component modelu, jeśli go nie zawiera; a obok nich encję Release zawierającą to, co każda usługa określa dla swojego działania.
Co odczytuje
- Pliki. Plik importowany samodzielnie jest odczytywany osobno. Katalog jest odczytywany tak, jak odczytuje go Compose:
w każdym katalogu zawierającym pliki Compose, w kolejności ścieżek katalogów, pierwszy obecny
spośród
compose.yaml,compose.yml,docker-compose.ymlidocker-compose.yamljest plikiem Compose, a pierwszy obecny spośródcompose.override.yml,compose.override.yaml,docker-compose.override.ymlidocker-compose.override.yamljest na niego nakładany. Pozostałe z tych plików nie są odczytywane. W katalogu zawierającym pliki nadpisujące i żadnego pliku Compose odczytywany jest osobno pierwszy plik nadpisujący. Komentarz otwierający roboczą encję Aggregate wymienia odczytane pliki w kolejności ich scalania oraz pliki nieodczytane. Każda usługa i każdy model ze wszystkich katalogów trafiają do jednej encji Aggregate. - Scalanie. Plik nadpisujący jest scalany tak, jak scala go Compose:
imagejest zastępowane;portssą scalane według adresu, portu publikowanego, portu kontenera i protokołu,volumeswedług ścieżki w kontenerze, aenvironmentwedług nazwy zmiennej, przy czym późniejszy wpis zajmuje miejsce wcześniejszego, a nowy jest dopisywany na końcu;exposejest dołączane;depends_onimodelsusługi są łączone, aendpoint_varimodel_varwpisu zajmują miejsce tych, które określa wcześniejszy plik. W przypadku modelumodelicontext_sizesą zastępowane, aruntime_flagsdołączane. Znaczniki Compose!reseti!overridenie są uwzględniane: wartość z takim znacznikiem jest scalana tak, jak odczytuje ją parser YAML. - Usługa. Jej
imageoraz to, czy buduje obraz w ramachbuild; jejports,expose,volumesienvironment— mapowanie albo lista elementówNAME=value, przy czym nazwa bez wartości przyjmuje wartość ze środowiska, w którym działa Compose;depends_on, lista lub mapowanie; oraz jejmodels, lista nazw modeli albo mapowanie, którego wpisy mogą wskazywać, wendpoint_varimodel_var, zmienne, pod którymi adres i identyfikator modelu docierają do usługi. Żaden inny element —command,healthcheck,secrets,env_filei pozostałe — nie jest nigdzie zapisywany, lecz jest wymieniany w komentarzu nad wpisem usługi w encji Release. - Model. Każdy wpis najwyższego poziomu
models: jegomodel, identyfikator OCI modelu, jegocontext_sizeiruntime_flags, przenoszone bez zmian do instancjicore/ai-model/docker-model-runner, jeśli katalog go zawiera, a do instancji encji Component modelu utworzonej dla niego, jeśli go nie zawiera; decyzja modelu mówi, która z nich i dlaczego. Każdy inny element jest wymieniany w komentarzu nad jego instancją. - Pozostałe. Inne elementy najwyższego poziomu —
name,networks,volumes,secrets,configs— nie są odczytywane, a wymienia je komentarz otwierający encję Aggregate.
Usługi, modele i środowisko usługi zachowują kolejność, w jakiej zapisuje je plik. Drzewo parsera zapisuje elementy mapowania w kolejności posortowanej, dlatego kolejność ta jest odczytywana z tekstu pliku, gdy są one zapisane jako mapowanie blokowe; mapowanie zapisane w stylu przepływowym zachowuje kolejność posortowaną.
Którą encją Component jest usługa
Importer dopasowuje usługę według repozytorium wskazanego przez jej obraz: odwołania bez tagu i
skrótu (digest), przy czym odwołanie do Docker Hub jest zapisywane w formie skróconej — postgres dla
docker.io/library/postgres:16. Repozytorium dopasowuje za pomocą swojej tabeli obrazów, tabeli przypisującej repozytorium
obrazów encję Component z katalogu, dla której encja Recipe Compose z katalogu standardowego uruchamia obraz
z tego repozytorium. Tabela jest generowana z encji Recipes Compose i
Components katalogu standardowego podczas budowania importera i wkompilowywana w niego, więc podczas importu
nie jest odczytywana żadna encja Recipe, a tabela zawiera etykiety katalogu standardowego niezależnie od zawartości katalogu użytkownika; encja
Plugin importera podaje w swoim opisie rewizję huba, z której wygenerowano tabelę. Z każdej
encji Recipe tabela odczytuje encję Component implementowaną przez Recipe oraz obraz jej kontenera o nazwie
main, jeśli obraz ten zapisuje swoje repozytorium we własnym tekście lub jest wpisem locals, który to robi. Encja
Recipe uruchamiająca obraz w całości wskazany przez Release albo obraz składany inaczej przez jej szablon nie dodaje
wiersza; nie dodaje go też obraz uruchamiany przez Recipe obok głównego kontenera. Dwie encje Recipes wskazujące jedno
repozytorium dla różnych encji Components przerywają generowanie tabeli, więc wiersz nigdy nie wskazuje jednej z dwóch.
Z encji Component wskazanej przez wiersz tabela odczytuje etykiety w postaci, w jakiej otrzymuje je import — w wersji,
do której rozwiązuje się odwołanie wskazujące Component bez wersji, wraz z etykietami dziedziczonymi przez
extends — i zapisuje w wierszu wszystkie etykiety oprócz component.aggrega.ai/category jako jego cechy. Encja
Recipe implementująca Component, którego katalog standardowy nie zawiera, również przerywa generowanie
tabeli.
Wiersz jest odczytywany tak samo jak wiersz tabeli importera przepływów: encja Component, kategoria wynikająca z jej nazwy,
jej cechy oraz ostatni segment jej nazwy jako dostawca.
Ustawienie mapping_overrides nakłada się na tabelę w formacie compose, z kluczami według
repozytorium, a wpis dla repozytorium, które
tabela mapuje, zajmuje miejsce wiersza. Dlatego obraz, którego nie wskazują encje Recipes katalogu standardowego — własny
albo taki, który Component katalogu uruchamia z innego repozytorium — jest mapowany wpisem:
with: settings: mapping_overrides: compose: bitnami/redis: component: core/datastore/redis category: datastore traits: datastore.aggrega.ai/engine: kv vendor: redisO usłudze, której obraz mapuje wiersz, decyduje się tak, jak importery przepływów decydują o węźle: jest oceniana względem encji Components katalogu, przywoływana przez odwołanie, gdy reuse_mode ma wartość auto-apply-above-threshold, czyli domyślną, a jej najlepszy kandydat jest dopasowaniem z wysokiego poziomu równym lub wyższym niż reuse_threshold, a w przeciwnym razie tworzona jako osobna encja Component, przy czym plik utworzonej encji Component otwiera komentarz wskazujący Component, do którego jest podobna. Wiersz zawiera etykiety wskazanej encji Component, więc jeśli katalog zawiera tę encję Component z etykietami nadanymi jej przez katalog standardowy, usługa mapowana przez wiersz jest dla niej dopasowaniem z wysokiego poziomu z wynikiem 0.90, a auto-apply-above-threshold przywołuje ją przy domyślnym reuse_threshold. Encja Component, której etykiety zmieniono w katalogu, uzyskuje niższy wynik, proporcjonalnie do udziału cech wiersza, których już nie ma, i jest przywoływana tylko dopóki pozostaje w wysokim poziomie; kategoria jest uwzględniana raz, we własnym sygnale, a nie ponownie jako cecha. Usługi tworzące jedną encję Component współdzielą jej jeden plik. Usługa, której obrazu nie mapuje żaden wiersz, której obraz nie wskazuje repozytorium odczytywanego przez importer lub która buduje swój obraz, jest instancją core/compute/server niezależnie od zawartości katalogu. Decyzja dla każdej usługi jest raportowana tak jak decyzja dla każdego węzła.
Czym staje się usługa
aggregate.yaml to szkic encji Aggregate nazwany od projektu, jak opisuje Jak nazywany jest szkic, zawierający po jednej instancji na usługę, typu Component wybranego przez decyzję dla tej usługi, z kluczem nadawanym tak, jak importer MCP nadaje klucz serwerowi; komentarz nad instancją wskazuje usługę i plik, z którego pochodzi, jeśli klucz nie jest nazwą usługi lub import odczytał kilka katalogów. Każda usługa wskazana w depends_on danej usługi jest połączeniem, uses: <key>: <key>: {target: <key>}, zapisywanym pod gniazdem i aliasem, obydwoma nazwanymi od klucza celu. Komponent odczytuje każde ze swoich połączeń po jego aliasie, niezależnie od tego, do którego gniazda jest ono podłączone, dlatego każde połączenie usługi ma własny alias. Połączenie może też utworzyć zmienna środowiska usługi, dostarczając zmienną z tego, co publikuje usługa, do której prowadzi, jak opisuje Czym stają się środowisko i obraz usługi. Każdy model jest instancją core/ai-model/docker-model-runner, jeśli katalog obszaru roboczego ją zawiera, niezależnie od wartości reuse_mode, i nie jest dla niego tworzony szkic encji Component: instancja zapisuje model i runtime_flags tak, jak podaje je źródło, a context_size ze źródła jako context_window, wartość deklarowaną przez środowisko uruchomieniowe dla długości kontekstu modelu, którą jego Recipe dla Compose zapisuje z powrotem jako context_size Compose. Jeśli katalog nie zawiera core/ai-model/docker-model-runner, model jest szkicowany jako <target_namespace>/ai-model/<key>, encja Component kategorii ai-model, której wartości deklarują model, context_size i runtime_flags, a jego instancja zapisuje każdą z nich podaną w źródle. Każdy model ma decyzję wskazującą, który wariant zastosowano — mapped llm (model) to core/ai-model/docker-model-runner as a reference, NONE lub szkic, którego decyzja zapisuje, że katalog obszaru roboczego nie zawiera core/ai-model/docker-model-runner — a każda usługa wskazująca model jest z nim połączona w obu przypadkach, tak jak z usługą, od której zależy. Usługa wskazująca model w formie długiej, z endpoint_var lub model_var, podaje zmienne, pod którymi adres i identyfikator modelu docierają do usługi. Żaden klucz szkicu nie przechowuje nazwy zmiennej — połączenie jest zapisywane na gnieździe nazwanym od modelu, które nie deklaruje żadnej wartości, a importer nie otrzymuje kluczy infrastruktury żadnej encji Component — dlatego komentarz nad połączeniem podaje każdą z nich tak, jak zapisuje ją wpis, a decyzja dla usługi zapisuje to samo zdanie:
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: embedderUsługa wskazująca model w formie krótkiej lub bez żadnej z tych zmiennych jest z nim połączona bez komentarza.
Obok niego release.yaml to szkic encji Release o tej samej nazwie, której spec.aggregate wskazuje encję Aggregate. Dla instancji core/compute/server zapisuje infra.image, obraz w zapisanej postaci, oraz infra.port, port, na którym nasłuchuje kontener, z pierwszego wpisu ports lub expose, jeśli ports nie zawiera żadnego. Z --target compose zapisuje także infra.published_port, port hosta publikowany przez ten sam wpis ports, tak jak podaje go źródło, pod komentarzem informującym, że jest on osiągalny tylko z tej maszyny, przez dowolny działający na niej proces, oraz że usunięcie wiersza pozostawia usługę wewnętrzną; port hosta poniżej 1024, którego published_port nie przyjmuje, nie jest zapisywany, a komentarz nad wpisem go wskazuje. Komentarz nad wpisem każdej usługi zapisuje to, co podaje źródło, a czego nie przenosi żaden klucz szkicu — obraz usługi dopasowanej do innej encji Component, której tagu szkic nie tłumaczy, jej ports, expose, volumes oraz każdą zmienną jej environment, której szkic nie tłumaczy — aby można było przenieść to tam, gdzie Component to przyjmuje. To, co szkic pozostawia encji Release — obraz usługi, która go nie wskazuje, jak usługa budująca własny obraz, oraz port, który nie jest pojedynczą liczbą — jest zapisywane jako puste pod komentarzem wyjaśniającym dlaczego. Kompilacja rozmieszcza tylko instancje wskazane przez Release, dlatego instancja każdego modelu ma pusty wpis, <key>: {}, po wpisach usług: zarówno instancja core/ai-model/docker-model-runner, która nie przyjmuje w Compose żadnego wejścia bez wartości domyślnej, jak i model szkicowany jako osobna encja Component, dzięki czemu szkicowany model jest już rozmieszczony i kompiluje się, gdy tylko zostanie napisany realizujący go Recipe. Port, którego Component nie przyjmuje, na przykład poniżej dolnej granicy 1024 w core/compute/server, jest zapisywany tak, jak podaje go źródło, a kompilacja zatrzymuje się, wskazując go. Encja Release zapisuje metadata.environment oraz, bez celu, puste spec.manifest, tak jak w przypadku importera MCP; po podaniu celu import tworzy szkic encji Manifest, jak opisuje Co dodaje cel, przypisując każdy Component do realizującego go na tym celu Recipe — core/compute/server do compose/server lub helm/server, a core/ai-model/docker-model-runner do compose/docker-model-runner lub helm/docker-model-runner.
Plik compose.yaml uruchamiający PostgreSQL i własne API, które od niego zależy:
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/0jest szkicowany, bez żadnego ustawienia, względem katalogu zawierającego core/datastore/postgres z biblioteki standardowej, zaimportowany samodzielnie i nazwany od pliku, ponieważ projekt nie ma name, jako:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: 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: dbapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: 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: 8080Import zgłasza mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9. Projekt nie zawiera usługi cache, dlatego CACHE_URL nie tworzy połączenia i pozostaje w komentarzu. Przy reuse_mode: hints-only db jest zamiast tego type: imported/datastore/postgres, szkicowanym w components/imported-datastore-postgres.yaml, który zaczyna się od # resembles core/datastore/postgres (score 0.9000); reference it by setting type: core/datastore/postgres; jego obraz i środowisko są wtedy zapisywane w komentarzu nad jego wpisem, ponieważ szkicowana encja Component nie deklaruje żadnej z wartości odczytywanych przez Recipes katalogu. Przy --target compose encja Manifest przypisuje core/datastore/postgres do compose/postgres, a core/compute/server do compose/server; przy --target helm do helm/postgres i helm/server.
Czym stają się środowisko i obraz usługi
Jeśli usługa jest instancją encji Component z katalogu, którą wskazuje wiersz jej obrazu, a katalog obszaru roboczego zawiera tę encję Component, importer odczytuje jej obraz i środowisko tak, jak odczytują je Recipes dla Compose ze standardowego katalogu dla tej encji Component, na podstawie tego, co tabela obrazów zapisuje o każdym Recipe, i tłumaczy je na szkice:
- Tag obrazu jest kluczem infrastruktury, z którego Recipe buduje odwołanie do obrazu, na przykład
engine_version—16dlapostgres:16— zapisywanym w encji Release pod komentarzem wskazującym obraz ze źródła. - Zmienna, którą Recipe ustawia z jednej z wartości encji Component —
POSTGRES_DB,POSTGRES_USER— i której wartość zawiera tekst, jest tą wartością instancji,databaselubuser, jeśli Component z katalogu ją deklaruje, zapisywaną w encji Aggregate pod komentarzem wskazującym zmienne. - Zmienna, z której Recipe odczytuje hasło, na przykład
POSTGRES_PASSWORD, i której wartość jest pojedynczym odwołaniem do zmiennej, jest sekretem dołączonym w tym slocie, odczytywanym ze zmiennej wskazanej przez odwołanie i deklarowanym z kluczem, pod którym Recipe go odczytuje.
A dla każdej usługi każda zmienna jej środowiska, która nie została odczytana w ten sposób:
- Wartość będąca nazwą innej usługi projektu, jeśli wiersz tej usługi wskazuje klucz
providespublikujący jej nazwę hosta, tworzy połączenie z tą usługą, którego blokinjectdostarcza zmienną z tego klucza —CACHE_HOST: cachetoCACHE_HOSTzhostpamięci podręcznej. - Wartość równa wartości, którą inna usługa ustawia dla swojej encji Component i którą ta encja Component publikuje —
DATABASE_USER: notesobok usługi PostgreSQL ustawiającejPOSTGRES_USER: notes— tworzy połączenie dostarczające zmienną z tego kluczaprovides. Jeśli tę wartość zawiera kilka usług lub kluczy, odczytywany jest ten, którego klucz lub własna zmienna kończy się tak, jak kończy się nazwa zmiennej, a w razie braku takiego ten, z którego nie odczytano jeszcze innych zmiennych usługi; w przeciwnym razie zmienna nie jest odczytywana. - Wartość będąca pojedynczym odwołaniem do zmiennej wskazującym zmienną, z której odczytywany jest sekret innej usługi —
DATABASE_PASSWORD: ${POSTGRES_PASSWORD}— jest na instancjicore/compute/serverwłasnym sekretem, dołączonym pod nazwą zmiennej zapisaną małymi literami i odczytywanym z tej samej zmiennej, jeśli cel zapisuje sekret jako wartość przyjmowaną przez serwer.helm/serverodrzucacore/referenced-secret, dlatego przy--target helmtaka zmienna pozostaje w komentarzu.
Każda inna zmienna pozostaje w komentarzu nad wpisem usługi, tak jak zapisuje ją źródło. Przewodnik po imporcie z Compose pokazuje projekt, którego API w ten sposób łączy się ze swoją bazą danych i pamięcią podręczną, skompilowany i uruchomiony w postaci szkicu.
Wartości poświadczeń przechowywane przez usługę
Compose nie oznacza żadnej wartości środowiskowej jako poświadczenia, a importer nie odczytuje znaczenia z nazwy żadnej zmiennej, dlatego każda niepusta wartość środowiskowa jest traktowana jako wejście, które jego format oznacza jako niebędące poświadczeniem, ale mogące je zawierać. Domyślnie każda jest przenoszona w zapisanej postaci do szkiców — do wartości, na którą jest tłumaczona, lub do komentarza nad wpisem jej usługi w encji Release — i wskazywana w ostrzeżeniu credential-carried przez usługę i zmienną — environment.<variable> — nigdy przez wartość. Przy ustawieniu empty_credentials równym all każda jest zapisywana jako pusta i zgłaszana przez credential-emptied: komentarz podaje jej zmienną bez wartości. Przy marked żadna nie jest opróżniana, ponieważ Compose żadnej nie oznacza. Wartość będąca wyłącznie jednym odwołaniem do zmiennej interpolowanym przez Compose — ${NAME} lub $NAME — nie zawiera własnej wartości: jest zapisywana jako taki tekst i nie jest wskazywana w żadnym ostrzeżeniu. Odwołanie z wartością domyślną lub komunikatem, na przykład ${NAME:-value}, zawiera ten tekst i jest traktowane jak każda inna wartość. Wartość, którą Compose odczytuje z innego miejsca — z env_file, z pliku sekretu — nie jest odczytywana.
Odczytywane ustawienia
Importer Compose odczytuje target_namespace, reuse_mode, reuse_threshold, emit_hints,
render_mode, mapping_overrides i empty_credentials, zgodnie z opisem w Ustawieniach,
i żadnych innych ustawień. Wskazówka, którą steruje emit_hints, jest zapisywana wyłącznie w pliku szkicowanej encji Component;
szkicowana encja Aggregate nie zawiera żadnej.
Importer Dify
importer/dify odczytuje aplikację wyeksportowaną z Dify w jego DSL, czyli dokumencie YAML, który Dify zapisuje dla
aplikacji, i tworzy szkic encji Aggregate składającej się z instalacji Dify z biblioteki standardowej,
core/dify, z aplikacją przenoszoną w parametrze app_definition instalacji. Instalacja
importuje ją podczas wdrożenia, w kroku, który renderuje dla niej Recipe jej serwera API.
Co odczytuje
- Aplikacja.
kind, którego wartością jestapp;version, wersja DSL, w której aplikacja jest zapisana; orazappz jegomode. - Workflow lub chatflow —
modeworkflowlubadvanced-chat— przechowuje swój graf wworkflow: każdy węzełworkflow.graph.nodes, który podaje swój typ wdata.type, jest węzłem aplikacji, w kolejności, w jakiej wymienia je graf, aworkflow.environment_variableszawiera zmienne, które aplikacja odczytuje. - Aplikacja czatu, czatu z agentem lub uzupełniania przechowuje swoją konfigurację w
model_config: jejmodel, każda baza wiedzy wdataset_configs.datasets.datasetsi każde narzędzie wagent_mode.toolsjest węzłem aplikacji, nazwanym według swojego miejsca, np.model_config.model. Aplikacja w trybieagentjest jednym węzłem,agent. - Potrzebne wtyczki. Każdy wpis
dependenciesrównież jest węzłem, nazwanymdependencies.<n>, typu, który wpis podaje, np.marketplace.
Nic innego nie decyduje o tym, co powstaje w szkicu: przenoszona jest cała aplikacja.
Czym staje się aplikacja
aggregate.yaml to szkic encji Aggregate nazwany od aplikacji, jak opisuje Jak nazywany jest szkic, składający się z jednego wpisu core/dify z kluczem dify, którego parametr app_definition przenosi aplikację w zapisanej postaci — tak jak Jak przepływ jest zapisywany w szkicu opisuje to dla przepływu, dzięki czemu własne odwołania Dify {{#…#}} docierają do instalacji w wyeksportowanej postaci. Instalacja sama łączy każde połączenie swojego serwera API — bazę danych, pamięć podręczną, magazyn wektorów, piaskownicę, środowisko wykonawcze wtyczek i serwer proxy ruchu wychodzącego — więc szkic nie tworzy żadnej encji Component i niczego nie łączy: każdy węzeł pozostaje w aplikacji, co stwierdza jego decyzja. Obok niego release.yaml to szkic encji Release o tej samej nazwie, który umieszcza instalację w granicy platform i przenosi to, czego aplikacja nie może dostarczyć.
Import widzi encje Components katalogu obszaru roboczego, ale żadnej z jego encji Aggregates, więc nie
sprawdza, czy katalog zawiera core/dify, o czym mówi komentarz nad wpisem. Jeśli katalog
nie zawiera core/ai-agent/dify, czyli serwera API uruchamianego przez core/dify, import ostrzega komunikatem
platform-not-in-catalog i mimo to tworzy wpis.
Sekret aplikacji instalacji, czyli klucz, którym Dify podpisuje swoje pliki cookie sesji i którym szyfruje przechowywane poświadczenia dostawców modeli, to parametr secret_key z core/dify, który nie ma wartości domyślnej. Dlatego szkic deklaruje własny parametr secret_key — ciąg znaków, wymagany, o długości co najmniej jednego znaku i bez wartości domyślnej — i przekazuje go do każdego wpisu core/dify, który zapisuje, aby encja Release wypełniła go w swoich parameters; build, którego encja Release pozostawia go nieustawionym, zatrzymuje się, wskazując go.
Aplikacja jest importowana na konto właściciela instalacji, które encja Release wskazuje w swoim wpisie routingu dla instalacji: infra.owner_email w komponencie api instalacji oraz gniazdo owner_password w tym komponencie, dołączone jako core/referenced-secret; bez nich kompilacja zostaje zatrzymana. Adresu e-mail właściciela nie może dostarczyć żadne źródło, więc jest on zapisywany jako pusty pod komentarzem wyjaśniającym, czym jest, a import zgłasza tę wartość jako wymaganą.
W każdym celu ten sam wpis routingu ustawia infra.marketplace_enabled na true w komponentach api, worker i scheduler instalacji, każde pod komentarzem wyjaśniającym dlaczego: instalacja nie sięga do niczego u dostawcy Dify, chyba że encja Release na to pozwala, każdy z trzech komponentów odczytuje własne ustawienie, a Dify instaluje wtyczkę obsługującą model aplikacji, taki jak model OpenAI, ze swojego marketplace’u wtyczek.
Sekret aplikacji i hasło właściciela są sekretami, tworzonymi w szkicu przez odwołanie dla celu importu:
- Przy
--target helmkażdy wskazuje obiekt Secret Kubernetes, który już istnieje w przestrzeni nazw:secret_key— nazwę obiektu Secret, którycore/difyodczytuje pod kluczem danychsecret-key, aowner_password— obiekt Secret przechowujący hasło pod kluczem danychvalue. Żadnej z tych nazw nie może dostarczyć żadne źródło, więc każda jest zapisywana jako pusta pod komentarzem wyjaśniającym, czym jest, a import zgłasza obie wartości jako wymagane; szkic encji Manifest mapujecore/referenced-secretnahelm/k8s-existing-secret. - W każdym innym celu, a także bez celu, każdy jest odwołaniem do zmiennej —
secret_keyjako"${DIFY_SECRET_KEY}", a hasło właściciela jako"${DIFY_OWNER_PASSWORD}", czyli nazwy, które odczytują encje Recipes Dify dla Compose z katalogu standardowego — którą Docker Compose odczytuje ze środowiska przy uruchamianiu stosu, więc dla żadnego z nich nie ma wymaganych wartości; przy--target composeszkic encji Manifest mapujecore/referenced-secretnacompose/dotenv-referenced-secret.
Gdy podany jest cel, encja Manifest mapuje typ każdego komponentu, z którego składa się instalacja, a także typ samego szkicu, jak opisuje Co dodaje cel.
Utworzona aplikacja workflow o nazwie Support Answers, którą importują testy tego importera, bez żadnego ustawienia daje szkic:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: 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. ...Przy imporcie z --target helm jej szkic encji Release wypełnia secret_key, a we wpisie routingu rozmieszczającym instalację wskazuje właściciela i włącza marketplace wtyczek, przy czym każda wymagana wartość jest zapisywana jako pusta:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: 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: trueImport zgłasza trzy puste wartości jako wymagane. Przy imporcie z --target compose ta sama encja Release zapisuje secret_key: "${DIFY_SECRET_KEY}" i origin: "${DIFY_OWNER_PASSWORD}", a jako wymagany zgłasza tylko adres e-mail właściciela; zapisuje też infra.published_port w komponencie api, 5001, oraz w interfejsie użytkownika, komponencie console, 3001, każde pod komentarzem informującym, że usługa jest osiągalna tylko z tej maszyny, dla każdego działającego na niej procesu, oraz że usunięcie wiersza pozostawia usługę wewnętrzną, a pod portem komponentu api zapisuje infra.console_url z adresem, pod którym publikowana jest konsola, "http://127.0.0.1:3001", który serwer Dify przyjmuje jako adres konsoli. Przewodnik po imporcie Dify buduje aplikację dla obu celów i uruchamia ją w Kubernetes.
Co Dify konfiguruje samo
Dify samo konfiguruje dostawców modeli i narzędzi wywoływanych przez aplikację, a
core/ai-agent/dify nie deklaruje gniazda dla modelu, więc szkic żadnego nie łączy. Każdy węzeł, który go wskazuje, jest
zgłaszany komunikatem part-configured-in-platform oraz w swojej decyzji, według tego, co wskazuje:
- węzeł
llm,question-classifierlubparameter-extractororazmodel_config.modelaplikacji czatu: model, według nazwy i dostawcy; - węzeł
tooloraz narzędzie aplikacji czatu: narzędzie, według nazwy i dostawcy; - węzeł
agent: strategia agenta i wtyczka, która ją dostarcza; - węzeł
knowledge-retrievaloraz baza wiedzy aplikacji czatu: bazy wiedzy, z których pobiera dane, oraz model, którym kieruje zapytanie lub zmienia ranking, jeśli go wskazuje. Aplikacja wskazuje bazę wiedzy identyfikatorem instalacji, z której została wyeksportowana, i nie przenosi żadnych jej dokumentów ani magazynu, więc każdą tworzy się w Dify, w magazynie wektorów, który instalacja łączy ze swoim serwerem API; - zależność: wtyczka, według identyfikatora, pod którym Dify ją instaluje, oraz miejsca, z którego ją instaluje.
Każdy inny węzeł pozostaje w aplikacji bez żadnego zgłoszenia.
Wartości poświadczeń przechowywane w aplikacji
Importer lokalizuje, w kolejności, w jakiej zapisuje je aplikacja:
- wartość każdej zmiennej środowiskowej, której
value_typetosecret, oznaczanej przez Dify jako poświadczenie. Eksport Dify zapisuje ją pustą, chyba że obejmuje sekrety; authorization.config.api_keywęzła żądania HTTP, który Dify oznacza jako poświadczenie i eksportuje w zapisanej postaci;- przechowywane poświadczenie, które węzeł
toollub narzędzie węzłaagentwybiera wcredential_id, oznaczane przez Dify jako poświadczenie i zapisywane tylko wtedy, gdy eksport obejmuje sekrety; headersiparamswęzła żądania HTTP, których Dify nie oznacza jako poświadczenia, a które mogą je zawierać, każde w całości.
Domyślnie każda z nich, która zawiera wartość, jest przenoszona w zapisanej postaci w aplikacji i wskazywana w
ostrzeżeniu credential-carried przez swój węzeł — workflow dla zmiennej środowiskowej — i swoje pole,
nigdy przez wartość. Przy ustawieniu empty_credentials równym marked każda wartość, którą Dify
oznacza jako poświadczenie, jest zapisywana jako pusta, a przy all także nagłówki i parametry zapytania; każda jest
zgłaszana komunikatem credential-emptied. Wartość będąca wyłącznie jednym odwołaniem do zmiennej nie zawiera
żadnej wartości i jest przenoszona w zapisanej postaci niezależnie od ustawienia oraz nie jest wskazywana w żadnym ostrzeżeniu, jak
w przepływie. Wartość jest opróżniana w tekście samej aplikacji:
skalar po jej kluczu zostaje zastąpiony przez '' i nic poza tym się nie zmienia. Aplikacja jest przenoszona tylko
wtedy, gdy parser obsługujący parse:yaml odczytuje wynik z powrotem jako wyeksportowaną aplikację z opróżnionymi dokładnie
tymi wartościami; w przeciwnym razie nie jest przenoszona, app_definition pozostaje nieustawione z komentarzem, a
definition-not-carried podaje przyczynę — jak w przypadku aplikacji, w której alias YAML odczytuje wartość
sekretu, którą opróżnienie tej wartości również by zmieniło. Wartość, którą ustawienie pozostawia w zapisanej postaci, nigdy nie jest
przepisywana, więc nigdy nie uniemożliwia przeniesienia aplikacji.
Wersja DSL
Jeśli aplikacja jest zapisana w wersji DSL nowszej niż 0.7.0, czyli wersja, którą zapisuje Dify 1.17.0
— wersja uruchamiana domyślnie przez core/ai-agent/dify — import ostrzega komunikatem
dsl-version-newer. Dify wstrzymuje import takiej aplikacji do czasu potwierdzenia, które daje krok
importujący ją podczas wdrożenia, dlatego należy sprawdzić aplikację względem wersji Dify uruchamianej przez encję Release.
Odczytywane ustawienia
Importer Dify odczytuje target_namespace, empty_credentials, layout, attach_egress_allowlist
i render_mode, zgodnie z opisem w sekcji Ustawienia, a także reuse_mode, reuse_threshold,
emit_hints i mapping_overrides, które nie zmieniają niczego w szkicu domyślnego układu: każdy węzeł pozostaje
w aplikacji. attach_egress_allowlist niczego nie dołącza, ponieważ wpis złożonej
encji Aggregate przyjmuje parametry, a nie encję Feature, a gdy ma wartość true, import ostrzega komunikatem
feature-not-attached. layout: nodes tworzy każdy węzeł jako osobną encję Component, zgodnie z opisem w sekcji
Węzeł po węźle, i nie przenosi aplikacji.
Importer CrewAI
importer/crewai odczytuje agentów i zadania, które projekt CrewAI deklaruje w swoich plikach konfiguracyjnych,
i tworzy szkic encji Aggregate zawierającej po jednej instancji agenta CrewAI z biblioteki standardowej,
core/ai-agent/crewai, na każdego agenta, każdą podłączoną do modelu wskazanego w jej konfiguracji, a obok niej szkic encji
Release.
Co odczytuje
CrewAI przechowuje zachowanie załogi (crew) w programie, a jej agentów i zadania deklaruje w plikach konfiguracyjnych, w jednym z dwóch układów; importer odczytuje każdy z nich:
- Projekt klasyczny —
config/agents.yaml, w którym każdy agent ma klucz w postaci swojej nazwy, orazconfig/tasks.yaml, w którym każde zadanie ma klucz w postaci swojej nazwy; oba są odczytywane jako YAML. Agenci są odczytywani w kolejności, w jakiej zapisuje ichagents.yaml. - Projekt w układzie JSON-first —
crew.jsonc, który wymienia agentów załogi z nazwy wagents, a jej zadania wtasks, orazagents/<name>.jsonc, po jednym pliku na agenta; wszystkie są odczytywane jako JSON z komentarzami, więc komentarze i końcowe przecinki są odczytywane tak, jak odczytuje je CrewAI. Agenci są odczytywani w kolejności, w jakiej wymienia ichcrew.jsonc, a następnie pliki pozostałych agentów w kolejności nazw; agent wymieniony przez załogę, którego pliku nie przekazano importowi, jest wymieniony w komentarzu i nie powstaje dla niego żaden szkic. Ten sam układ zapisany w ścisłym JSON —crew.jsoniagents/<name>.json— jest odczytywany w ten sam sposób. Gdy załoga lub agent są zapisani w obu wariantach, odczytywany jest plik.jsonc, tak jak odczytuje go CrewAI, a plik.jsonjest wymieniony w komentarzu jako nieodczytany.
Z agenta odczytywane są jego role, goal i backstory; allow_delegation i verbose, na najwyższym poziomie
jego deklaracji lub w settings, przy czym pierwszeństwo ma settings, tak jak odczytuje je CrewAI; jego llm; oraz
nazwy jego tools. Z zadania odczytywana jest jego nazwa i agent, do którego jest przypisane. Każdy inny element jest
wymieniony w komentarzu i nigdzie nie jest przenoszony.
Katalog jest przekazywany importerowi jako pliki wskazane przez jego sygnatury i żadne inne, więc program
załogi — crew.py projektu klasycznego, main.py przepływu, narzędzie zdefiniowane przez projekt w Pythonie — nigdy
nie jest odczytywany. Plik importowany samodzielnie jest odczytywany jako deklaracja odpowiadająca jego kształtowi. Katalog projektu
może zawierać kilka załóg, każdą odczytywaną z jej własnego katalogu.
Czym staje się projekt
aggregate.yaml to szkic encji Aggregate nazwany od załogi, jak opisuje Jak nazywany jest szkic, rozpoczynający się komentarzami wymieniającymi odczytane deklaracje, informującymi, że program załogi nie jest odczytywany, oraz wymieniającymi zadania każdej załogi wraz z agentem, do którego jest przypisane każde z nich. Zawiera, dla każdego agenta i z kluczem w postaci jego nazwy, instancję core/ai-agent/crewai z:
role,goalibackstoryw postaci zadeklarowanej;allow_delegationw postaci zadeklarowanej orazfalse, gdy agent go nie deklaruje;log_levelDEBUGdla agenta zadeklarowanego jakoverbose, który relacjonuje każdy krok swojego rozumowania, orazINFOdla agenta, który nim nie jest i zgłasza tylko postęp i problemy. Wartośćverboseluballow_delegation, która nie jest anitrue, anifalse, pozostaje przy wartości domyślnej encji Component i jest wymieniona w komentarzu;- jego połączeniem
model, podłączonym do instancji modelu wskazanego przez jegollm.
llm zapisane jako <provider>/<model> lub jako obiekt wskazujący model w model, model_name
lub deployment_name wskazuje dostawcę i model. Model jest instancją encji
Component z katalogu dla tego dostawcy — core/ai-model/<provider>, przy czym podkreślenie w nazwie dostawcy jest odczytywane
jako łącznik, a azure jako azure-openai — z kluczem w postaci nazwy modelu i z modelem jako jej
values.model; agenci wskazujący tego samego dostawcę i model współdzielą jedną instancję. Gdy katalog obszaru roboczego
nie zawiera encji Component o tej nazwie, tworzony jest jej szkic, <target_namespace>/ai-model/<provider>, deklarujący
wartość model, i mówi o tym jego decyzja; etykietę model.aggrega.ai/api, po której gniazdo model agenta
wybiera encję Component, oraz encję Recipe publikującą jej punkt końcowy i model należy dodać samodzielnie,
jak mówi otwierający ją komentarz. llm niewskazujące dostawcy — sama nazwa modelu, dla której CrewAI ustala
dostawcę podczas działania programu, lub nazwa llm zdefiniowanego przez program — czyli odwołanie do
programu, a także agent niedeklarujący llm, które CrewAI odczytuje wtedy ze środowiska, w którym działa jego program,
nie są do niczego podłączane, a komentarz nad agentem wyjaśnia dlaczego; kompilacja zatrzymuje się, wskazując gniazdo
model, dopóki nie zostanie ono podłączone.
Zadanie jest logiką wykonywaną przez program załogi, a narzędzie jest kodem, który program definiuje lub ładuje: żadne z nich
nie staje się encją Component. Każde jest zgłaszane w decyzji, która niczego nie wybiera, a narzędzie, którego nazwa — po usunięciu
końcowego Tool, łączników i podkreśleń — jest nazwą encji Component narzędzia zawartej w katalogu,
niesie tę encję Component jako wskazówkę: search_tool i SearchTool wskazują na
core/ai-tool/search. core/ai-agent/crewai nie deklaruje gniazda dla narzędzia, więc nic nie jest dla niego
podłączane.
release.yaml, obok niego, to szkic encji Release o tej samej nazwie, wskazujący tę encję Aggregate. Zapisuje on infra.image każdego agenta — obraz uruchamiający program załogi, którego żadna deklaracja nie wskazuje — jako pusty pod komentarzem wyjaśniającym, czym jest, a import zgłasza tę wartość jako wymaganą. Z --target compose wpis każdego agenta zapisuje także infra.published_port, 8000, port, który infra.port encji Component domyślnie wskazuje dla programu i który jej encja Recipe Compose publikuje na adresie pętli zwrotnej hosta, 127.0.0.1, pod komentarzem informującym, że usługa jest osiągalna tylko z tej maszyny, dla każdego działającego na niej procesu, oraz że usunięcie wiersza pozostawia usługę wewnętrzną; drugi agent otrzymuje następny wolny port, więc dwaj agenci klasycznego projektu są publikowani na 8000 i 8001. Poświadczenie, które każdy agent przedstawia swojemu modelowi, dołącza w credential w jego połączeniu model, przez odwołanie i nigdy jako wartość: żadna deklaracja nie wskazuje dla niego zmiennej, więc jest ono odczytywane ze zmiennej, z której biblioteki klienckie dostawcy odczytują swój klucz API — OPENAI_API_KEY dla OpenAI — jako odwołanie ${…} w każdym celu oprócz helm, a w helm jako nazwa obiektu Secret Kubernetes, zapisana jako pusta, aby import zgłosił ją jako wymaganą; w compose połączenie model agenta deklaruje je z tym kluczem. Każdy model również ma wpis, niezawierający żadnej infrastruktury, dzięki czemu encja Release rozmieszcza go razem z agentami. W przypadku modelu zadeklarowanego jako obiekt llm każdy pozostały element jest zapisywany jako wartość instancji modelu, gdy encja Component z katalogu deklaruje wartość o tej nazwie, a w przeciwnym razie w komentarzu nad wpisem modelu w encji Release, aby można go było przenieść tam, gdzie encja Component go przyjmuje. Jak każdy szkic encji Release, zapisuje metadata.environment jako development oraz, bez celu, puste spec.manifest, które import zgłasza jako wymagane; gdy podany jest cel, import tworzy szkic encji Manifest, jak opisuje Co dodaje cel.
Projekt klasyczny importowany w testach tego importera, którego dwaj agenci wskazują openai/gpt-4o, jest bez żadnego ustawienia przekształcany w szkic pokazany poniżej; zaimportowany jako jego katalog projektu, market_brief — katalog, w którym crewai create crew market_brief rozmieszcza taki projekt — ponieważ jego deklaracje nie wskazują żadnej załogi, otrzymuje nazwę od tego katalogu:
# 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_writerapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: 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"oraz jego encja Release, utworzona w szkicu bez celu, jak poniżej, z wpisem drugiego agenta pominiętym tutaj i oznaczonym ...; import zgłasza jako wymagane spec.manifest i obraz każdego agenta:
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: {}Każdy agent jest wtedy renderowany jako uruchamiający obraz podany w odpowiedzi, z punktem końcowym i nazwą modelu przekazanymi jako OPENAI_BASE_URL i MODEL, zmienne, z których odczytuje je CrewAI.
Wartości poświadczeń zawarte w deklaracji
llm zapisane jako obiekt może zawierać klucz — w api_key, w adresie, w nagłówkach. Każdy z jego elementów poza tym, który wskazuje model, niebędący liczbą ani wartością logiczną, jest wartością, która może zawierać klucz, a której CrewAI nie oznacza jako poświadczenia. Domyślnie każdy zawierający wartość jest przenoszony w postaci zapisanej — jako wartość instancji modelu, gdy jego encja Component ją deklaruje, a w przeciwnym razie do komentarza nad wpisem jego modelu w encji Release — i wymieniany w ostrzeżeniu credential-carried z podaniem agenta i elementu, np. llm.api_key, nigdy wartości. Przy ustawieniu empty_credentials równym all każdy jest zapisywany bez wartości i zgłaszany jako credential-emptied; przy marked każdy jest przenoszony, ponieważ CrewAI żadnego nie oznacza. Nazwa elementu nie jest interpretowana pod kątem znaczenia. Każdy inny element deklaracji, którego szkic nie przenosi — konfiguracja narzędzia, inputs załogi — jest wymieniany z nazwy, nigdy z wartością.
Odczytywane ustawienia
Importer CrewAI odczytuje target_namespace, empty_credentials i render_mode, jak opisuje je sekcja
Ustawienia, i żadnego innego ustawienia.
Importer LangGraph
importer/langgraph odczytuje grafy deklarowane w konfiguracji aplikacji LangGraph, langgraph.json, i tworzy szkic encji Aggregate zawierającej po jednej instancji agenta LangGraph z biblioteki standardowej, core/ai-agent/langgraph, na każdy graf, każdą połączoną z magazynem danych, w którym jej checkpointer przechowuje stan, oraz z modelem, a obok niej encję Release przenoszącą środowisko określone w konfiguracji. Odczytuje tę konfigurację, nigdy zaś kodu grafów.
Co odczytuje
Aplikacja LangGraph przechowuje swoje grafy w kodzie i deklaruje je w langgraph.json: w
graphs identyfikator każdego grafu wskazuje ścieżkę importu grafu w kodzie aplikacji —
./src/agent/graph.py:graph lub module:attr — albo obiekt podający tę ścieżkę w path i
opisujący graf w description. Importer odczytuje, w kolejności, w jakiej zapisuje je
konfiguracja:
graphs— identyfikator każdego grafu, jego ścieżkę importu i opis;checkpointer— jegobackend:default, czyli PostgreSQL, przyjmowany przez LangGraph, gdy żaden nie jest podany;mongo, czyli baza danych obsługująca protokół MongoDB; lubcustom, checkpointer zdefiniowany w kodzie aplikacji podpath;store— magazyn pamięci, który nie podaje backendu: LangGraph przechowuje go w bazie PostgreSQL używanej przez jego serwer;env— środowisko, w którym działa aplikacja: obiekt odwzorowujący nazwy zmiennych na wartości lub ścieżka pliku środowiskowego z wierszamiKEY=VALUE.
Elementy konfigurujące obraz serwera, który buduje langgraph build — dependencies, source, python_version, node_version, base_image, image_distro, dockerfile_lines, pip_config_file, pip_installer, keep_pkg_tools, api_version — są wymieniane w komentarzu i nigdzie nie są przenoszone, ponieważ obraz wskazany w encji Release jest własnym obrazem aplikacji; tak samo jest z każdym innym elementem, w tym z własną konfiguracją serwera, taką jak auth, http i webhooks, oraz z index i ttl magazynu i ttl i serde checkpointera.
Katalog jest przekazywany importerowi jako langgraph.json i żaden inny plik, więc ani
kod aplikacji, ani plik środowiskowy nigdy nie są z niego odczytywane. Plik środowiskowy trafia do
importera tylko wtedy, gdy przekazuje go with.sources importera, i nigdy nie jest parsowany: z pliku wskazanego przez
env konfiguracji — dopasowanego po ostatnim segmencie podanej ścieżki — odczytywane są tylko
nazwy zmiennych, a plik środowiskowy niewskazany przez żadną konfigurację jest wymieniany w komentarzu jako nieodczytany.
Gdy import nie otrzymał pliku wskazanego przez konfigurację, encja Aggregate wymienia go jako nieprzekazany
i wskazuje, by podać go w with.sources importera, a jego zmienne pozostają dla encji Release:
plugins: importer: - uri: importer/langgraph:<version> with: sources: - ./local.envKonfiguracja importowana samodzielnie jest odczytywana niezależnie od nazwy. Katalog może zawierać kilka aplikacji, każdą odczytywaną z jej własnego katalogu.
Czym staje się aplikacja
aggregate.yaml to szkic encji Aggregate nazwany od grafu, jak opisuje Jak nazywany jest szkic, rozpoczynający się komentarzami wymieniającymi odczytane konfiguracje, pliki środowiskowe odczytane wyłącznie dla nazw, informację, że kod aplikacji nie jest odczytywany, oraz to, czego szkic nie przenosi. Zawiera, na każdy graf i pod kluczem jego identyfikatora, instancję core/ai-agent/langgraph z:
graph_entrypoint— ścieżką importu grafu, tak jak zapisuje ją konfiguracja;description— opisem grafu, jeśli konfiguracja go podaje;- połączeniem
checkpointer_db, podłączonym do magazynu danych aplikacji; - połączeniem
model, podłączonym do modelu aplikacji.
recursion_limit nie jest zapisywany, więc obowiązuje wartość domyślna encji Component, 25. Konfiguracja nie podaje modelu, więc szkic zawiera jedną instancję core/ai-model/openai z kluczem model, którą wywołuje każdy graf: model przekazywany klientowi OpenAI agenta. Jej values.model jest zapisywane jako puste, pod komentarzem informującym, że konfiguracja nie podaje żadnego modelu, a import zgłasza tę wartość jako wymaganą.
Backend checkpointera to magazyn danych, do którego podłączony jest każdy graf aplikacji: default lub checkpointer niepodający backendu to instancja core/datastore/postgres z kluczem postgres. mongo to FerretDB, obsługujący protokół MongoDB, działający na PostgreSQL z rozszerzeniem DocumentDB: instancja core/datastore/ferretdb z kluczem ferretdb, do której podłączony jest każdy graf, oraz instancja core/datastore/documentdb z kluczem documentdb, do której sięga połączenie backend FerretDB, a jego blok inject dostarcza to, co publikuje DocumentDB, pod nazwami odczytywanymi przez FerretDB; jedno hasło, odczytywane ze zmiennej FERRETDB_PASSWORD, jest dołączane do DocumentDB, do połączenia FerretDB z nim oraz do połączenia każdego grafu z FerretDB. Gdy katalog obszaru roboczego nie zawiera encji Component o nazwie magazynu danych PostgreSQL, tworzony jest jej szkic, <target_namespace>/datastore/postgres, deklarujący host i port odczytywane przez połączenie checkpointer_db agenta, co odnotowuje jego decyzja; encja Recipe uruchamiająca magazyn danych i publikująca je pozostaje do uzupełnienia, jak mówi otwierający ją komentarz. Gdy nie zawiera encji Component FerretDB lub DocumentDB, checkpointer mongo nie jest podłączany do żadnego magazynu danych. Checkpointer custom lub backend, którego importer nie odwzorowuje na żaden magazyn danych, niczego nie podłącza, a komentarz nad każdym grafem i decyzja checkpointera wyjaśniają dlaczego; budowanie zatrzymuje się, wskazując gniazdo checkpointer_db, dopóki nie zostanie ono podłączone. Magazyn pamięci jest zgłaszany w decyzji, która niczego nie wybiera.
Hasło magazynu danych jest sekretem, który szkic dołącza przez odwołanie, do własnego gniazda password magazynu danych oraz do połączenia checkpointer_db każdego grafu, podobnie jak poświadczenie, które każdy graf przedstawia modelowi w swoim połączeniu model: odczytywane z POSTGRES_PASSWORD (lub FERRETDB_PASSWORD) oraz OPENAI_API_KEY, ponieważ konfiguracja nie wskazuje zmiennej dla żadnego z nich, jako odwołanie ${…} w każdym celu oprócz helm, a w helm jako nazwa obiektu Secret Kubernetes, zapisana jako pusta, aby import zgłosił ją jako wymaganą. W compose encja Aggregate deklaruje każde z nich z kluczem, który odczytuje jej encja Recipe, jak opisuje Sekrety dla każdego celu w odniesieniu do platformy.
release.yaml, obok niego, to szkic encji Release o tej samej nazwie, wskazującej tę encję Aggregate. Komentarze nad wpisem pierwszego grafu mówią, czym jest obraz każdego grafu — własnym obrazem aplikacji, jej kodem z zainstalowanym LangGraph, a nie obrazem serwera, który buduje langgraph build — jakie zmienne otrzymuje i który blok inject: zastępuje którą z ich nazw. Wpis każdego grafu zapisuje jego infra.image, obraz uruchamiający aplikację, jako pusty pod komentarzem wyjaśniającym, czym jest, a import zgłasza tę wartość jako wymaganą; dopóki nie jest ustawiony, encja Recipe Docker Compose uruchamia własnego agenta quickstart katalogu, który odczytuje zmienne domyślne. Z --target compose wpis każdego grafu zapisuje także infra.published_port, 8000, port, który infra.port encji Component domyślnie wskazuje dla aplikacji i który jej encja Recipe Compose publikuje na adresie pętli zwrotnej hosta, 127.0.0.1, pod komentarzem informującym, że usługa jest osiągalna tylko z tej maszyny, dla każdego działającego na niej procesu, oraz że usunięcie wiersza pozostawia usługę wewnętrzną; drugi graf otrzymuje następny wolny port. Magazyn danych i model również mają wpisy, więc encja Release umieszcza je razem z grafami. Komentarz nad pierwszym grafem aplikacji określa środowisko deklarowane w jej konfiguracji, jak opisuje Środowisko określane przez konfigurację. Jak każdy szkic encji Release, zapisuje metadata.environment jako development oraz, bez celu, puste spec.manifest, które import zgłasza jako wymagane; gdy podany jest cel, import tworzy szkic encji Manifest, jak opisuje Co dodaje cel.
Aplikacja w Pythonie importowana w testach tego importera, deklarująca dwa grafy, checkpointer niepodający backendu, magazyn pamięci oraz env zapisane jako obiekt, jest bez żadnego ustawienia przekształcana w szkic pokazany poniżej; zaimportowana jako jej katalog, support_desk — nazwany, jak tutaj, od pakietu, w którym zdefiniowano jej grafy — przy dwóch grafach o różnych identyfikatorach otrzymuje nazwę od tego katalogu:
# 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/v1beta1kind: Aggregatemetadata: 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: ""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: {}Import zgłasza cztery wartości jako wymagane: spec.manifest, obraz każdego grafu i nazwę modelu. Po udzieleniu odpowiedzi każdy graf jest renderowany jako uruchamiający obraz podany w odpowiedzi, z adresem swojego magazynu danych przekazanym jako LANGGRAPH_CHECKPOINTER_HOST i LANGGRAPH_CHECKPOINTER_PORT, użytkownikiem i bazą danych, które publikuje magazyn danych, jako LANGGRAPH_CHECKPOINTER_USER i LANGGRAPH_CHECKPOINTER_DATABASE — PostgreSQL publikuje oba, a w przypadku magazynu danych niepublikującego żadnego z nich żadna z tych zmiennych nie jest renderowana — punktem końcowym i nazwą modelu jako OPENAI_BASE_URL i OPENAI_MODEL, kluczem dostarczanym przez poświadczenie modelu jako OPENAI_API_KEY, swoją ścieżką importu jako LANGGRAPH_GRAPH_ENTRYPOINT i swoim limitem kroków jako LANGGRAPH_DEFAULT_RECURSION_LIMIT. Poświadczenie dołączone do jego połączenia checkpointer_db przekazuje mu też hasło magazynu danych jako LANGGRAPH_CHECKPOINTER_PASSWORD.
Środowisko określane przez konfigurację
Każda zmienna wymieniona w env konfiguracji jest wejściem, które ma dostarczyć encja Release, i żadna nie jest
tworzona jako miejsce na poświadczenie: LangGraph nie oznacza żadnej zmiennej jako sekretu, a nazwa zmiennej nie jest
interpretowana pod kątem znaczenia. core/ai-agent/langgraph nie przyjmuje wartości dla środowiska, więc encja Release określa
je w komentarzu nad pierwszym grafem aplikacji.
envzapisane jako obiekt jest częścią konfiguracji, więc jego wartości są przenoszone w niezmienionej postaci do tego komentarza, w kolejności, w jakiej zapisuje je konfiguracja. Każda niepusta wartość może zawierać poświadczenie, a LangGraph nie oznacza żadnej jako poświadczenia: domyślnie każda jest przenoszona w niezmienionej postaci i wymieniana w ostrzeżeniucredential-carriedprzez swoją konfigurację i zmienną, np.env.OPENAI_API_KEY, nigdy przez wartość. Przy ustawieniuempty_credentialsrównymallkażda jest zapisywana bez wartości i zgłaszana jakocredential-emptied; przymarkedkażda jest przenoszona, ponieważ LangGraph nie oznacza żadnej.envwskazujące plik wskazuje plik, do którego konfiguracja jedynie się odwołuje i który zwykle zawiera lokalne sekrety. Jest on odczytywany tylko wtedy, gdy przekazuje gowith.sourcesimportera. Komentarz wymienia każdą zmienną wymienioną w pliku, pozostawioną do dostarczenia przez encję Release, a żadna wartość z pliku nie jest odczytywana: żadna nie trafia do szkicu, decyzji ani diagnostyki, niezależnie od ustawienia. Wartość ujęta w cudzysłów w kilku wierszach jest jedną wartością, więc wiersz w jej wnętrzu nigdy nie jest brany za zmienną, a wiersz niepodający zmiennej jest wskazywany przez swój numer. Gdy import nie otrzymał pliku — zawsze w przypadku katalogu, który nigdy go nie przekazuje — encja Aggregate wymienia go jako nieprzekazany, wraz ze sposobem przekazania, a jego zmienne pozostają dla encji Release.
Odczytywane ustawienia
Importer LangGraph odczytuje target_namespace, empty_credentials i render_mode, tak jak
opisuje je sekcja Ustawienia, i żadnego innego ustawienia.
Importer Google ADK
importer/google-adk odczytuje agentów, których aplikacja zbudowana na Agent Development Kit (ADK) firmy Google deklaruje w swoich plikach Agent Config — root_agent.yaml i konfiguracjach wskazanych przez jej subagentów — i przygotowuje szkic encji Aggregate zawierającej po jednej instancji agenta ADK z biblioteki standardowej, core/ai-agent/google-adk, na każde drzewo agentów, podłączonej do modelu wskazanego przez drzewo, o ile ADK wysyła jego żądania do Gemini API, oraz obok niej encję Release. Odczytuje te konfiguracje, nigdy zaś kodu aplikacji.
ADK podaje, że jego funkcja Agent Config jest eksperymentalna. Modelem agenta jest domyślnie model Gemini; modele niektórych innych dostawców ADK obsługuje po nazwie przez własne klasy, takie jak claude-sonnet-4-5 i gpt-4o, a inne przez ciąg modelu LiteLLM. Gniazdo model agenta dopuszcza wyłącznie Gemini API, więc importer podłącza model, który ADK wysyła do Gemini API, a każdy inny pozostawia użytkownikowi, jak opisuje Czym staje się drzewo agentów.
Co odczytuje
Polecenie ADK adk create --type=config zapisuje root_agent.yaml, konfigurację głównego agenta aplikacji,
oraz obok niego plik środowiskowy. Konfiguracja deklaruje jednego agenta:
name,descriptioniagent_class— klasę, jako którą ADK buduje agenta;LlmAgent, jeśli żadna nie jest podana;model— model, o który prosi agent — lubmodel_code, odwołanie do kodu budującego jego model;tools— każde narzędzie wedługname, z argumentamiargs, które przekazuje mu konfiguracja;generate_content_config— opcje żądań agenta do modelu, w tymhttp_options;sub_agents— każdy jakoconfig_path, ścieżka innej konfiguracji względem katalogu konfiguracji, która ją wskazuje, lubcode, agent budowany przez kod aplikacji.
Katalog jest przekazywany importerowi jako jego pliki root_agent.yaml i żaden inny plik, a konfiguracja
importowana samodzielnie jest odczytywana jako korzeń, niezależnie od nazwy. Drzewo każdego korzenia jest odczytywane od korzenia,
subagenci każdego agenta w kolejności, w jakiej je wymienia. Konfiguracja wskazana we wpisie sub_agents
przez config_path jest odczytywana tylko wtedy, gdy przekazuje ją with.sources importera, dopasowana po ostatnim segmencie
ścieżki; konfiguracja, której import nie otrzymał, jest wskazana w encji Aggregate i w jej decyzji jako nieprzekazana,
wraz z informacją, jak ją przekazać, a jej agent nie jest odczytywany:
plugins: importer: - uri: importer/google-adk:<version> with: sources: - ./my_agent/code_tutor_agent.yaml - ./my_agent/math_tutor_agent.yamlŚcieżka config_path, która jest bezwzględna lub wychodzi poza katalog wskazującej ją konfiguracji, nie jest
odczytywana, ponieważ ADK również ją odrzuca. Plik przekazany przez with.sources, którego nie wskazuje żadna konfiguracja, jest wymieniony w
komentarzu jako nieodczytany i nic z niego nie jest odczytywane; przekazany plik jest odczytywany tylko jako konfiguracja wskazana w drzewie
korzenia, więc import, który nie zawiera root_agent.yaml ani pliku importowanego samodzielnie, nie odczytuje żadnego drzewa i
zgłasza każdy plik w ramach no-nodes. Kod aplikacji — narzędzia, wywołania zwrotne, schematy i agenci, których
konfiguracja wskazuje przez ich kod — oraz plik środowiskowy nigdy nie są przekazywane i importer nie odczytuje
żadnego z nich: aplikacja sama wczytuje swoje konfiguracje z obrazu wskazanego w encji Release.
Katalog może zawierać kilka aplikacji, z których każda jest odczytywana z własnego root_agent.yaml.
Pozostałe pola konfiguracji — w tym instruction agenta — aplikacja odczytuje
z własnej konfiguracji, więc szkic nie zawiera żadnego z nich.
Czym staje się drzewo agentów
ADK obsługuje aplikację z jej głównego agenta, a każdy agent wskazany w jej konfiguracjach jest budowany wewnątrz niego; core/ai-agent/google-adk uruchamia jedną taką aplikację. Dlatego aggregate.yaml, szkic encji Aggregate nazwany od głównego agenta, jak opisuje Jak nazywany jest szkic, zawiera dla każdego drzewa agentów, z kluczem będącym nazwą jego głównego agenta, instancję core/ai-agent/google-adk z:
description, opisem głównego agenta, jeśli podaje go jego konfiguracja;- jej połączeniem
model, podłączonym do modelu wskazanego przez drzewo, gdy ADK wysyła jego żądania do Gemini API.
Komentarze nad nią wymieniają pozostałych agentów drzewa, którzy nie stają się osobnymi instancjami; każdego subagenta, który nie został odczytany, wraz z powodem — budowany przez kod aplikacji, konfiguracja nieprzekazana importowi lub odrzucana przez ADK; narzędzia wskazane przez agentów drzewa, zarówno dostarczane przez ADK, jak i definiowane przez kod aplikacji; agentów, których klasę — LoopAgent, ParallelAgent lub SequentialAgent — ADK oznacza jako przestarzałą na rzecz Workflow; oraz, gdy model drzewa jest podłączony, modele, o które proszą inni agenci drzewa, każdy wraz z rodziną, przez którą obsługuje go ADK. Każdy z nich jest zgłaszany w decyzji, która niczego nie wybiera.
O modelu instancji decyduje pierwszy agent drzewa, licząc od korzenia, który wskazuje model lub budujący go kod. Wskazany model, którego żądania ADK wysyła do Gemini API — nazwa modelu obsługiwana przez ADK za pomocą klasy Gemini, taka jak gemini-2.5-flash, inna niż nazwa zasobu Vertex AI, lub nazwa obsługiwana za pomocą klasy Gemma — jest instancją core/ai-model/gemini, obsługującą ten model i mającą go jako klucz, a drzewa wskazujące ten sam model współdzielą jedną instancję. Jeśli katalog obszaru roboczego nie zawiera core/ai-model/gemini, przygotowywany jest szkic <target_namespace>/ai-model/gemini z etykietą model.aggrega.ai/api: gemini, którą wybiera gniazdo model agenta, i mówi o tym jego decyzja; encję Recipe publikującą jego punkt końcowy i model należy dodać samodzielnie, jak mówi otwierający ją komentarz. Model obsługiwany przez ADK w jakikolwiek inny sposób — ciąg modelu LiteLLM, taki jak openai/gpt-4o, nazwa zasobu Vertex AI lub nazwa taka jak claude-sonnet-4-5 czy gpt-4o, którą ADK obsługuje przez Anthropic lub OpenAI — nie jest podłączany do niczego: gniazdo model agenta przyjmuje model Gemini, a agent nie odczytuje nazwy modelu ze swojego środowiska, więc należy podłączyć tam model Gemini i wskazać ten model w konfiguracji agenta. Komentarz nad instancją i decyzja agenta głównego wskazują model oraz rodzinę, przez którą obsługuje go ADK. Model budowany przez kod aplikacji lub drzewo niewskazujące żadnego modelu — ADK używa wtedy swojego modelu domyślnego — również nie jest podłączany do niczego, a komentarz nad instancją wyjaśnia dlaczego. Wszędzie tam, gdzie model nie jest do niczego podłączony, kompilacja zatrzymuje się, wskazując gniazdo model, dopóki ktoś go nie podłączy. Spośród modeli, o które proszą inni agenci drzewa, model, którego żądania ADK wysyła do Gemini API, nie potrzebuje własnego połączenia: klient Gemini w ADK wysyła jego żądania z kluczem dostarczanym przez połączenie instancji. To, czy aplikacja łączy się z Gemini przez Gemini API, czy przez Vertex AI, określa jej środowisko, którego import nie odczytuje; gniazdo model agenta dopuszcza wyłącznie Gemini API.
Testy importera importują też pojedynczego agenta głównego wskazującego openai/gpt-4o, którego instancja jest przygotowywana w szkicu jako:
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, obok niego, to szkic encji Release o tej samej nazwie, wskazujący tę encję Aggregate. Wpis każdej instancji zapisuje jej infra.image — obraz uruchamiający aplikację zbudowaną na ADK, zawierający jej konfiguracje — jako pusty, pod komentarzem mówiącym, czym on jest, a import zgłasza go jako brakujący. Z --target compose wpis zapisuje też infra.published_port, 8000, port, na którym nasłuchuje aplikacja, publikowany przez jej encję Recipe dla Compose na adresie pętli zwrotnej hosta, 127.0.0.1, pod komentarzem mówiącym, że jest on osiągalny tylko z tej maszyny, przez każdy uruchomiony na niej proces, i że usunięcie tego wiersza pozostawia usługę wewnętrzną; drugie drzewo otrzymuje kolejny wolny port. Gdy jej model jest podłączony, wpis dołącza poświadczenie, które instancja przedstawia temu modelowi, pod credential w jej połączeniu model, przez odwołanie, a nigdy jako wartość: żadna konfiguracja nie wskazuje dla niego zmiennej, więc jest ono odczytywane z GOOGLE_API_KEY, zmiennej, z której biblioteki klienckie Gemini API od Google odczytują swój klucz, jako odwołanie ${…} w każdym celu oprócz helm, a w helm jako nazwa obiektu Kubernetes Secret, zapisana jako pusta i zgłaszana przez import jako brakująca; w compose połączenie model deklaruje je z tym kluczem. Podłączony model również ma wpis, niezawierający żadnej infrastruktury, więc encja Release umieszcza go razem z instancją. Wartości, które konfiguracje drzewa przekazują swoim narzędziom i żądaniom do modelu, są zapisywane w komentarzu nad wpisem, jak opisuje Wartości poświadczeń zawarte w konfiguracji. Jak każdy szkic encji Release, zapisuje metadata.environment jako development oraz, bez celu, puste spec.manifest, które import zgłasza jako brakujące; po podaniu celu import tworzy szkic encji Manifest, jak opisuje Co dodaje cel.
Aplikacja importowana w testach tego importera, główny agent wskazujący konfiguracje dwóch subagentów i jednego budowanego przez kod, zaimportowana jako katalog z dwiema konfiguracjami wskazanymi w with.sources, jest bez żadnego ustawienia przygotowywana pod nazwą swojego głównego agenta, tutor_root, jako:
# 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/v1beta1kind: Aggregatemetadata: 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"Tekst, który szkic kopiuje z konfiguracji do encji Aggregate, w wartości lub w komentarzu, zapisuje każde
{{ jako {{`{{`}}, akcję, której wynikiem są dwa nawiasy klamrowe, dzięki czemu opis, a w komentarzu nazwa zawierająca
dwa nawiasy klamrowe, odczytują się tak, jak zostały zapisane, po ewaluacji encji Aggregate.
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: {}Gdy obraz otrzyma odpowiedź, instancja jest renderowana jako uruchamiająca go i otrzymuje poświadczenie jako GOOGLE_API_KEY, które klient Gemini w ADK wysyła do Gemini API, a model jest renderowany jako Service kierujący do adresu Gemini API.
Wartości poświadczeń przechowywane w konfiguracji
Konfiguracja może przekazać klucz narzędziu, w jego args, lub swoim żądaniom do modelu, w
http_options swojego generate_content_config — ich nagłówkom, ich adresowi, argumentom ich
klienta. Każdy element args narzędzia i tych opcji HTTP jest zapisywany w komentarzu nad
wpisem instancji w encji Release, tak jak zapisuje go konfiguracja, a każdy, który jest tekstem, obiektem lub
listą, może zawierać poświadczenie, choć ADK żadnego nie oznacza jako takie: domyślnie każdy jest przenoszony w postaci zapisanej i wskazywany
w ostrzeżeniu credential-carried przez swojego agenta i swoje pole, np.
tools.tutor_tools.make_snippet_runner.args.api_key, nigdy przez swoją wartość. Przy
ustawieniu empty_credentials równym all każdy jest zapisywany bez wartości i zgłaszany jako
credential-emptied; przy marked każdy jest przenoszony, ponieważ ADK żadnego nie oznacza. Liczba ani wartość logiczna nie zawiera
klucza i jest zapisywana tak, jak zapisuje ją konfiguracja. ADK nie rozwija żadnych odwołań do zmiennych w
konfiguracji, więc każda wartość jest odczytywana w postaci zapisanej; plik środowiskowy, który zwykle zawiera klucz
odczytywany przez klienta Gemini w ADK, nigdy nie jest odczytywany, niezależnie od ustawienia.
Odczytywane ustawienia
Importer Google ADK odczytuje target_namespace, empty_credentials i render_mode, zgodnie z opisem w sekcji
Ustawienia, i żadnych innych ustawień.
Importer Agent Framework
importer/agent-framework odczytuje deklaratywnego agenta Microsoft Agent Framework — dokument YAML rodzaju Prompt, z którego aplikacja zbudowana na Agent Framework ładuje agenta — i tworzy szkic encji Aggregate zawierającej jedną instancję agenta Agent Framework z biblioteki standardowej, core/ai-agent/agent-framework, podłączoną do wskazanego przez niego modelu OpenAI, a obok niej encję Release. Odczytuje deklaratywnych agentów, nigdy kodu aplikacji. Agent Framework publikuje swoje pakiety deklaratywnych agentów jako wersje przedpremierowe.
Co odczytuje
Deklaratywny agent deklaruje:
name,displayNameidescription, swojeinstructionsoraz schematy swojego wejścia i wyjścia;model—idmodelu, obsługujący goprovider, API, do którego jego klient wysyła żądania (apiType),optionsjego żądań oraz jegoconnection: połączeniekeyprzedstawiające klucz, zapisany podkeylubapiKey, wobecendpoint; połączenieremotedocierające doendpoint; połączeniereferencewskazujące połączenie rozwiązywane przez aplikację; lub połączenieanonymous, które niczego nie przedstawia;tools— każde określonegokind:function, której kod wiąże aplikacja, narzędzieweb_search,file_searchlubcode_interpreteruruchamiane przez dostawcę modelu albo serwermcposiągany pod jegourl, zapprovalModeobowiązującym jego wywołania,allowedToolsserwera, które agent może wywoływać, oraz własnymconnection.
Element zapisany jako =Env.NAME jest odczytywany przez Agent Framework ze zmiennej środowiskowej NAME tylko wtedy, gdy aplikacja ładuje deklaratywnego agenta za pomocą AgentFactory(safe_mode=False), własnego ustawienia bezpieczeństwa Agent Framework, i obecne jest środowisko uruchomieniowe .NET, a w przeciwnym razie jest traktowany jako tekst wyrażenia w zapisanej postaci; każdy inny element zaczynający się od = jest wyrażeniem obliczanym przez aplikację. Importer nie odczytuje żadnego z nich: odwołanie wskazuje przez jego zmienną, a wyrażenie — jako wyrażenie.
Plik importowany samodzielnie jest odczytywany jako jeden deklaratywny agent, niezależnie od nazwy, a każdy plik
przekazany przez with.sources importera jest odczytywany jako kolejny, więc jeden import tworzy szkice kilku:
plugins: importer: - uri: importer/agent-framework:<version> with: sources: - ./agents/triage.yaml - ./agents/writer.yamlKatalog nigdy nie jest przekazywany importerowi: jego sygnatura nie wskazuje żadnego pliku, więc import katalogu
bez wskazania formatu go nie rozpoznaje, a import ze wskazaniem --format agent-framework jest odrzucany z błędem
An importer that declares no file patterns is handed a directory (Importer, który nie deklaruje wzorców plików, otrzymuje katalog)
zanim zostanie otwarty jakikolwiek jego plik. Zamiast tego należy importować każdego deklaratywnego agenta jako osobny plik. Źródło,
z którego Agent Framework nie buduje agenta promptowego — takie, którego kind nie jest ani Prompt, w dowolnej wielkości liter,
ani Agent — jest zgłaszane pod no-nodes. Kod aplikacji — program ładujący każdego
deklaratywnego agenta i funkcje wiązane przez niego z narzędziami — nigdy nie należy do źródeł:
aplikacja sama ładuje swoich deklaratywnych agentów z obrazu wskazanego przez encję Release.
Czym staje się deklaratywny agent
aggregate.yaml, szkic encji Aggregate nazwany od agenta, jak opisuje Jak nazywany jest szkic, zawiera dla każdego deklaratywnego agenta, pod kluczem jego nazwy, instancję core/ai-agent/agent-framework z:
display_nameidescription— wartościamidisplayNameidescriptionagenta, o ile je podaje;- jej połączeniem
model, podłączonym do wskazanego modelu, o ile ten model jest podłączony.
Jego instrukcje, schematy wejścia i wyjścia, szablon, metadane i opcje żądań do modelu aplikacja odczytuje z deklaratywnego agenta; są one wymienione w komentarzu nad instancją. Narzędzie funkcyjne, narzędzie uruchamiane przez dostawcę modelu i narzędzie dowolnego innego rodzaju również są wymienione w komentarzu i zgłoszone w decyzji, która niczego nie wybiera.
Model, którego provider to OpenAI i który wskazuje id, jest instancją core/ai-model/openai,
obsługującą ten identyfikator i umieszczoną pod jego kluczem: gniazdo model agenta przyjmuje model obsługujący API OpenAI, a
środowisko uruchomieniowe dostarcza adres, nazwę i klucz tego modelu w zmiennych odczytywanych przez klientów OpenAI
Agent Framework. Agenci wskazujący jeden model pod jednym adresem współdzielą jedną instancję. Jeśli katalog obszaru roboczego
nie zawiera core/ai-model/openai, tworzony jest jego szkic, <target_namespace>/ai-model/openai, z etykietą
model.aggrega.ai/api: openai, którą wybiera gniazdo model agenta, a jego decyzja o tym informuje;
encja Recipe publikująca jego punkt końcowy i model pozostaje do uzupełnienia, o czym mówi otwierający ją komentarz. id
zapisany jako odwołanie pozostawia values.model modelu do uzupełnienia, a komentarz nad modelem wskazuje
zmienną; kompilacja zatrzymuje się, wskazując ją, dopóki nie zostanie ustawiona. Połączenie anonymous jest zapisywane jako
unauthenticated: true połączenia. Model dowolnego innego dostawcy — AzureOpenAI, Anthropic — model
wskazujący dostawcę jako odwołanie lub niewskazujący go wcale, w którym to przypadku Agent Framework używa domyślnego dostawcy ustawionego przez
aplikację, oraz model niewskazujący id nie są do niczego podłączane, a komentarz nad instancją wyjaśnia
dlaczego; kompilacja zatrzymuje się, wskazując gniazdo model, dopóki coś nie zostanie do niego podłączone.
Narzędzie rodzaju mcp nie jest szkicowane ani jako encja Component, ani jako połączenie: Agent Framework wysyła serwer do dostawcy modelu jako narzędzie hostowane, a to dostawca, nie aplikacja, łączy się z nim pod jego url, który musi więc być osiągalny od strony dostawcy, tak że nic, co wdraża szkic, się z nim nie łączy. Komentarz nad instancją agenta wskazuje serwer, informuje o tym i wskazuje opis, approvalMode oraz allowedTools, które deklaratywny agent podaje dla niego; jego url jest zapisywany w całości w komentarzu nad wpisem agenta w encji Release, a jego decyzja niczego nie wybiera.
release.yaml, obok niego, to szkic encji Release o tej samej nazwie, wskazujący tę encję Aggregate. Wpis agenta zapisuje jego infra.image — obraz uruchamiający aplikację zbudowaną na Agent Framework, który zawiera jej deklaratywnego agenta — jako pusty, pod komentarzem mówiącym, czym on jest, a import zgłasza go jako brakujący. Z --target compose wpis zapisuje także infra.published_port, 8000, port, który infra.port encji Component domyślnie wskazuje dla aplikacji i który jej encja Recipe Compose publikuje na adresie pętli zwrotnej hosta, 127.0.0.1, pod komentarzem informującym, że usługa jest osiągalna tylko z tej maszyny, dla każdego działającego na niej procesu, oraz że usunięcie wiersza pozostawia usługę wewnętrzną. Gdy jego model jest podłączony, wpis dołącza poświadczenie, które agent przedstawia temu modelowi, pod credential w jego połączeniu model, przez odwołanie, a nigdy jako wartość: odczytywane ze zmiennej, którą deklaratywny agent wskazuje dla swojego klucza, zapisanej jako =Env.NAME, a w przeciwnym razie z OPENAI_API_KEY, zmiennej, z której biblioteki klienckie OpenAI odczytują swój klucz; jako odwołanie ${…} w każdym celu oprócz helm, a w helm jako nazwa obiektu Kubernetes Secret, zapisana jako pusta i zgłaszana przez import jako brakująca; w compose połączenie model deklaruje je z tym kluczem. Wartości, które deklaratywny agent podaje dla swojego modelu i swoich serwerów MCP — klucze oraz url każdego serwera — są zapisywane w komentarzu nad wpisem agenta, jak opisuje Wartości poświadczeń w deklaratywnym agencie. Każdy podłączony model ma wpis, więc encja Release umieszcza go razem z agentem. Punkt końcowy podany przez jego połączenie jest zapisywany jako infra.endpoint modelu, a punkt końcowy zapisany jako odwołanie jest wskazany obok jego wpisu, przy czym do czasu jego ustawienia używany jest własny adres encji Component; połączenie niepodające punktu końcowego pozostawia wpis bez żadnej infrastruktury, a własny adres encji Component pozostaje w mocy. Jak każdy szkic encji Release, zapisuje metadata.environment jako development oraz, bez celu, puste spec.manifest, które import zgłasza jako brakujące; po podaniu celu import tworzy szkic encji Manifest, jak opisuje Co dodaje cel.
Deklaratywny agent importowany w testach tego importera, korzystający z dostawcy OpenAI z połączeniem typu key, serwerem MCP przedstawiającym własny klucz, narzędziem funkcyjnym i wyszukiwaniem w sieci, zaimportowany jako osobny plik, jest bez żadnych ustawień przekształcany, pod nazwą podaną w name, LearnAgent, w następujący szkic:
# 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/v1beta1kind: Aggregatemetadata: 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"Tekst kopiowany przez szkic z deklaratywnego agenta do encji Aggregate, w wartości lub w komentarzu, zapisuje
każde {{ jako {{`{{`}}, aby po ewaluacji encji Aggregate odczytywał się tak, jak został zapisany.
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"Gdy obraz otrzyma odpowiedź, agent jest renderowany jako uruchamiający go i otrzymuje punkt końcowy modelu jako OPENAI_BASE_URL, jego identyfikator jako OPENAI_MODEL i poświadczenie jako OPENAI_API_KEY, a model jest renderowany jako Service docierający do swojego hosta. Żadna zmienna nie przenosi adresu serwera MCP: łączy się z nim dostawca modelu, a nie aplikacja.
Wartości poświadczeń przechowywane przez agenta deklaratywnego
Klucz przedstawiany przez połączenie key — zapisany pod key lub apiKey, w modelu lub w serwerze MCP — jest jedynym elementem, który Agent Framework oznacza jako poświadczenie: to jedyna wartość, którą jego loader usuwa z tego, co zapisuje w logach. Każdy klucz, który agent deklaratywny zapisuje jako literał, jest zapisywany w komentarzu nad wpisem agenta w encji Release, tak jak zapisuje go agent deklaratywny, i domyślnie przenoszony w niezmienionej postaci oraz wskazywany w ostrzeżeniu credential-carried przez swojego agenta i swoje pole, np. model.connection.key, nigdy przez swoją wartość. url serwera MCP, zapisany w całości w tym samym komentarzu i wskazany przez swoje pole — tools.microsoft_learn.url of node LearnAgent is carried as written — jest elementem konfiguracji serwera MCP, a punkt końcowy podłączonego modelu jest wejściem, które Agent Framework oznacza jako niebędące poświadczeniem. Przy ustawieniu empty_credentials o wartości marked klucze i url serwerów MCP są zapisywane bez wartości — komentarz wskazuje każdy z nich jedynie przez jego pole — i zgłaszane z kodem credential-emptied, a punkt końcowy modelu jest przenoszony; przy all pomijany jest również infra.endpoint modelu, wskazany w komentarzu nad jego wpisem jako pozostawiony encji Release, a do czasu jego ustawienia używany jest domyślny adres encji Component. Wartość zapisana jako =Env.NAME nie zawiera żadnej wartości, więc jest wskazywana przez swoją zmienną wraz z warunkiem, pod którym Agent Framework odczytuje ją ze środowiska — model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads … — niezależnie od ustawienia, i nie jest zgłaszana pod żadnym z tych kodów; wartość zapisana jako dowolne inne wyrażenie jest wskazywana jako wyrażenie i nigdy nie jest zapisywana.
Odczytywane ustawienia
Importer Agent Framework odczytuje target_namespace, empty_credentials i render_mode, zgodnie z opisem w sekcji Ustawienia, i żadnego innego ustawienia.
Co dodaje cel
Import, któremu podano cel — --target w poleceniu aggrega import albo target w narzędziu importu asystenta i w metodzie sesji aggrega/import, wskazujący możliwość dostawcy, taką jak compose lub helm — przekazuje ten cel importerowi, więc importer tworzy szkice dla niego: każdy sekret w postaci, którą ten cel odczytuje, oraz wiersze potrzebne tylko temu celowi, zapisane jako aktywne, natomiast wiersze potrzebne tylko innemu celowi są pomijane. W compose te wiersze obejmują infra.published_port wszędzie tam, gdzie importer publikuje usługę na adresie pętli zwrotnej hosta, jak mówi sekcja każdego importera; port wybrany przez importer nigdy nie otrzymuje numeru zajętego przez inny port encji Release. Następnie import tworzy szkic encji Manifest obok tego, co utworzył importer, niezależnie od tego, który importer został uruchomiony: manifest.yaml, obok szkicu encji Release, nazwany i wersjonowany tak jak ona — albo, jeśli importer nie utworzył szkicu encji Release, obok szkicu encji Aggregate, nazwany i wersjonowany tak jak ona.
Dla każdego typu komponentu i każdego typu feature, których potrzebują szkice — w komponentach szkicu encji Aggregate, ich połączeniach i jego podsystemach, w encjach katalogowych Aggregates, które on składa, takich jak core/dify, oraz w dołączeniach szkicu encji Release — Manifest przypisuje typowi encję Recipe, a typowi feature encję feature recipe, tej możliwości, którą katalog przestrzeni roboczej oferuje dla tego typu: tę jedyną, która istnieje, przy czym kilka wersji jednej liczy się jako jedna; albo, gdy jest ich kilka o różnych nazwach, tę nazwaną od samego typu, jak helm/postgres dla core/datastore/postgres. Typ bez żadnej takiej encji albo z kilkoma, z których żadna nie ma takiej nazwy, pozostaje nieprzypisany, ostrzeżenie wskazuje go wraz z powodem, a kompilacja szkiców zatrzymuje się, wskazując każdą jego instancję lub dołączenie, dopóki nie zostanie on przypisany.
Gdy tylko importer wie, która z kilku encji Recipes ma zastosowanie, sam tworzy szkic encji Manifest — importer MCP przypisuje każdemu serwerowi, według jego klucza, realizację sposobu, w jaki serwer działa, a importer dołączający sekret według nazwy przypisuje core/referenced-secret do helm/k8s-existing-secret — a import go uzupełnia: każde przypisanie zapisane przez importer, które katalog oferuje dla tego typu i tej możliwości, zostaje zachowane, każde inne zostaje odrzucone z ostrzeżeniem, a typy, które pozostawia, są przypisywane jak wyżej.
spec.manifest szkicu encji Release, zapisane jako puste bez celu, zostaje ustawione na nazwę encji Manifest, komentarz nad nim zostaje usunięty, a nic innego w encji Release się nie zmienia. Pełny opis zawiera strona aggrega import.
Ustawienia
Importer otrzymuje ustawienia wpisu plugins.importer, który go dołącza, pod kluczem
with.settings, jak opisuje Który importer zamienia źródło w szkice.
Gdy nie ma wpisu ani ustawień, każde ustawienie przyjmuje wartość domyślną.
plugins: importer: - uri: importer/langflow:<version> with: settings: target_namespace: payments reuse_mode: hints-only| Ustawienie | Domyślnie | Działanie |
|---|---|---|
target_namespace | imported | Przestrzeń nazw, w której nazywane są encje utworzone jako szkic: <target_namespace>/<category>/<name> dla encji Component oraz <target_namespace>/<name> dla encji Aggregate i Release, gdzie <name> to własna nazwa źródła, a w jej braku nazwa jego katalogu lub nazwa jego pliku bez rozszerzenia, a w ich braku flow, zapisana małymi literami, przy czym każdy ciąg znaków innych niż litery i cyfry ASCII zastępowany jest jednym łącznikiem, jak opisuje sekcja Jak nazywany jest szkic. |
reuse_mode | auto-apply-above-threshold | auto-apply-above-threshold odwołuje się do najlepiej dopasowanej encji Component z katalogu dla węzła, któremu szkic daje własną encję Component i którego dopasowanie należy do wysokiego poziomu i ma wynik równy reuse_threshold lub wyższy, a każdy inny szkicuje. hints-only szkicuje każdy taki węzeł i nie odwołuje się do żadnej encji Component z katalogu, zapisując silne dopasowanie jako wskazówkę. Każda inna wartość jest odczytywana jako hints-only. |
reuse_threshold | 0.85 | Wynik, od którego (włącznie) auto-apply-above-threshold odwołuje się do encji Component. Odczytywane tylko w tym trybie; 0 jest odczytywane jako wartość domyślna. |
emit_hints | true | Czy plik szkicowanej encji Component zaczyna się komentarzem wskazującym encję Component z katalogu, do której jest podobna, przy dopasowaniu wysokiego lub średniego poziomu. Szkic encji Aggregate zawiera ten sam komentarz nad wpisem tego węzła, a nad wpisem z odwołaniem — komentarz wskazujący następnego najlepszego kandydata, na którego można go zamienić, lub informujący, że żaden nie uzyskał wyniku powyżej zera. false pomija te komentarze. |
render_mode | human | human zapisuje opisane wyżej szkice. llm nie zapisuje szkiców, lecz cały zapis decyzji — każdy węzeł, rozważonych kandydatów i dokonany wybór — jako jeden dokument, import-decisions.json, do odczytu przez inne narzędzie. Każda inna wartość jest odczytywana jako human. |
mapping_overrides | brak | Mapowania nałożone na własną tabelę importera, kluczowane formatem, a następnie typem węzła — w przypadku importera Compose repozytorium obrazu. Każdy wpis wskazuje component, na który mapowany jest węzeł tego typu, oraz opcjonalnie jego category, traits — etykiety i ich wartości — które ma pasująca encja Component, i słowo vendor zawarte w jej nazwie. Wpis dla typu węzła, który tabela już mapuje, zastępuje wiersz tabeli. Odczytywane są tylko wpisy dla importowanego formatu. |
layout | platform | platform szkicuje platformę uruchamiającą przepływ i niosącą go, a każda jego część staje się osobną encją Component połączoną z platformą, jak opisuje Platforma niosąca przepływ. nodes szkicuje każdy węzeł jako osobną encję Component, jak opisuje Węzeł po węźle. W przypadku importera Dify platform szkicuje instalację Dify niosącą aplikację, jak opisuje Czym staje się aplikacja. Każda inna wartość daje szkic jak platform, a import ostrzega kodem unknown-layout. |
empty_credentials | none | Które wartości poświadczeń są zapisywane jako puste: w przepływie niesionym przez platformę, jak wymienia Wartości poświadczeń w przepływie, w encji Release szkicowanej przez importer MCP, jak wymienia Wartości poświadczeń serwera, w encji Release szkicowanej przez importer Compose, jak wymienia Wartości poświadczeń usługi, w aplikacji niesionej przez importer Dify, jak wymienia Wartości poświadczeń aplikacji, w encji Release szkicowanej przez importer CrewAI, jak wymienia Wartości poświadczeń deklaracji, w encji Release szkicowanej przez importer LangGraph, jak wymienia Środowisko podane w konfiguracji, w encji Release szkicowanej przez importer Google ADK, jak wymienia Wartości poświadczeń konfiguracji, oraz w encji Release szkicowanej przez importer Agent Framework, jak wymienia Wartości poświadczeń agenta deklaratywnego. none nie zapisuje pustych: każda jest przenoszona tak, jak ją zapisano, i wskazywana w ostrzeżeniu credential-carried. marked zapisuje jako puste to, co format oznacza jako poświadczenie, oraz każdy element konfiguracji serwera MCP. all zapisuje jako puste także dane wejściowe, których format nie oznacza jako poświadczenia, a które mogą je zawierać — nagłówki żądań, parametry zapytania, żądanie zapisane jako wiersz poleceń, dane wejściowe nazwane od klucza. To, co szkic zapisuje, aby węzeł dotarł do swojego połączenia, jest zapisywane niezależnie od tego ustawienia. Każda inna wartość zatrzymuje import, który nic nie szkicuje, z kodem unknown-empty-credentials. Szkic tworzony węzeł po węźle nie odczytuje żadnej wartości, więc nie odczytuje też tego ustawienia. |
attach_egress_allowlist | false | true dołącza encję Feature core/egress-allowlist z biblioteki standardowej do każdej instancji platformy zapisanej przez szkic, jako egress-allowlist, nie ustawiając żadnego z jej infra, jak opisuje Co szkic zostawia encji Release. false niczego nie dołącza. Szkic, który nie zapisuje platformy, przy layout: nodes, oraz szkic importera Dify, którego wpis dla instalacji Dify nie przyjmuje encji Feature, niczego nie dołączają niezależnie od tego ustawienia, a gdy ma ono wartość true, import ostrzega kodem feature-not-attached. Każda wartość niebędąca wartością logiczną jest odczytywana jako false. |
Ustawienie nieznane importerowi jest ignorowane.
with: settings: mapping_overrides: langflow: AzureOpenAIModel: component: acme/ai-model/azure-openai category: ai-model vendor: azureCo zgłasza import
Każdy importer podstawowy zgłasza jako diagnostyki to, czego nie mógł wykonać, oraz to, co zrobił w imieniu autora. Polecenie wypisuje każdą z nich na standardowe wyjście błędów jako <severity>: <message>, przed wierszem dla
każdego węzła; metoda aggrega/import sesji edytora i narzędzie import asystenta zwracają każdą
również z jej code.
| Kod | Ważność | Zgłaszane, gdy |
|---|---|---|
parse-failed | halt | Źródła nie da się sparsować: parser je odrzuca, a komunikat zawiera powód podany przez parser. |
no-nodes | warn | Źródło nie zawiera żadnego węzła rozpoznawanego przez importer — dla importera MCP żadnego serwera, dla importera Compose żadnej usługi ani modelu, dla importera CrewAI załoga nie deklaruje żadnego agenta, dla importera LangGraph konfiguracja nie deklaruje żadnego grafu, dla importera Google ADK konfiguracja główna nie deklaruje żadnego agenta lub żaden plik przekazany importowi przez with.sources nie zawiera konfiguracji głównej, a dla importera Agent Framework źródło nie deklaruje żadnego agenta promptowego. |
unknown-layout | warn | layout nie ma wartości ani platform, ani nodes; przepływ jest tworzony jako platform. |
unknown-empty-credentials | halt | empty_credentials ma wartość inną niż none, marked lub all, podaną wraz z ustawieniem; import niczego nie tworzy. |
platform-not-in-catalog | warn | Katalog przestrzeni roboczej nie zawiera encji Component o nazwie platformy, więc żadna część nie jest do niej podłączona; dla importera Dify brak core/ai-agent/dify, a core/dify i tak jest komponowany. |
part-not-placed | warn | Część przepływu nie jest podłączona do żadnego gniazda platformy, wraz z powodem; pozostaje w przepływie. |
socket-selector-unreadable | warn | Selektora deklarowanego przez gniazdo platformy nie da się odczytać, więc żadna część nie jest do niego podłączona; raz dla każdego gniazda. |
credential-carried | warn | Wartość poświadczenia jest przenoszona tak, jak została zapisana, w przepływie niesionym przez szkic lub w encji Release tworzonej przez importer MCP, Compose, CrewAI, LangGraph, Google ADK lub Agent Framework; wskazuje się ją przez jej węzeł — lub serwer, usługę, agenta albo konfigurację — i pole, nigdy przez wartość, wraz z wartością empty_credentials, która zapisuje ją jako pustą. |
credential-emptied | warn | Wartość poświadczenia jest zapisywana jako pusta w przepływie niesionym przez szkic lub w encji Release tworzonej przez importer MCP, Compose, CrewAI, LangGraph, Google ADK lub Agent Framework, gdy wymaga tego empty_credentials; wskazuje się ją przez jej węzeł — lub serwer, usługę, agenta albo konfigurację — i pole. |
carriage-returns-rewritten | warn | Znaki powrotu karetki w przepływie są zapisywane jako znaki nowego wiersza, wraz z ich liczbą. |
definition-respelled | warn | Wartości przepływu są zapisywane w pisowni, w której odczytują je własne narzędzia platformy, z tymi samymi wartościami, z podaniem których i dlaczego: uchwyty krawędzi przepływu Langflow, zapisane tak, jak zapisuje je edytor Langflow. Wartość, którą szkic zapisuje, aby przepływ dotarł do części, lub taka, która może przenosić poświadczenie, nigdy nie jest zapisywana inaczej — pozostaje wartością połączenia lub wartością empty_credentials — a ostrzeżenie liczy każdą wartość, której pisowni nie zmieniono. |
definition-not-carried | warn | Przepływ nie jest przenoszony w values.flow_definition lub aplikacja importera Dify w parameters.app_definition, wraz z powodem. |
part-reads-connection | warn | Jak przepływ dociera do podłączonej części przez jej połączenie lub jak połączenie dociera do węzła, którego szkic nie podłącza do żadnego gniazda, w postaci, w jakiej zostało zapisane. |
part-address-in-flow | warn | Przepływ dociera do podłączonej części inaczej niż przez jej połączenie, wraz z opisem, jak. |
model-not-named | warn | values.model przywołanej części pozostawia się autorowi, wraz z powodem. |
feature-attached | info | attach_egress_allowlist dołączył core/egress-allowlist do utworzonej platformy, wraz z tym, co z niej ustawia encja Release; raz dla każdej instancji platformy. |
feature-not-attached | warn | attach_egress_allowlist ma wartość true, a szkic nie zapisuje żadnej platformy lub komponuje instalację Dify, której wpis nie przyjmuje encji Feature, więc nic nie zostaje dołączone. |
part-configured-in-platform | warn | Węzeł aplikacji Dify wskazuje coś, co Dify konfiguruje samodzielnie — model i jego dostawcę, narzędzie, bazę wiedzy, strategię agenta, wtyczkę — więc szkic nie podłącza dla niego żadnej części. |
dsl-version-newer | warn | Aplikacja Dify jest zapisana w wersji DSL nowszej niż ta, którą zapisuje wersja Dify uruchamiana domyślnie przez core/ai-agent/dify. |
Import, któremu podano cel, zgłasza po diagnostykach importera to, co wykazało tworzenie encji Manifest: warn wskazujące każdy typ komponentu lub feature, którego Manifest nie mapuje, wraz z powodem, oraz info, gdy utworzona encja Release już wskazuje Manifest lub żadna utworzona encja Release go nie przywołuje. Są to diagnostyki samego importu, a nie importera, i nie mają kodu; opisuje je Co dodaje cel. Następnie każdy import zgłasza, również jako własne, warn dla każdej wartości, której szkicom wciąż brakuje, wskazujące szkic pliku, ścieżkę klucza i jego opis, a w trybie --offline, gdy utworzył szkic encji Release i niczego nie brakuje, info wskazujące aggrega pull do uruchomienia jako następne, jak opisuje Plik odpowiedzi importu.
Publikowane z każdym wydaniem kompilatora
Każde wydanie kompilatora buduje dziesięć importerów z otagowanych źródeł i generuje ich encje Plugin
z samych importerów, dzięki czemu możliwość, sygnatury rozpoznawania, funkcje hosta i opis encji
są tym, co zgłasza jej importer. Wydanie podpisuje i publikuje wszystkie dziesięć,
importer/langflow, importer/flowise, importer/n8n, importer/mcp, importer/compose, importer/dify, importer/crewai, importer/langgraph, importer/google-adk i importer/agent-framework, w wersji wydania, obok pozostałych
wbudowanych pluginów, i zapisuje ich encje razem z encjami pozostałych wbudowanych pluginów na potrzeby
standardowego katalogu.