Import
aggrega import odczytuje projekt zapisany w innym formacie — przepływ wyeksportowany z Langflow, konfigurację klienta MCP, plik Compose i pozostałe formaty wymienione poniżej — i zapisuje na jego podstawie pliki Aggrega: encję Aggregate, encję Release oraz, dla celu wskazanego przez --target, encję Manifest. Razem tworzą obszar roboczy, który przechodzi walidację i kompiluje się w zapisanej postaci, gdy tylko zostaną udzielone odpowiedzi na nieliczne wartości, których żadne źródło nie może zawierać: import pyta o każdą z nich raz i przechowuje odpowiedzi w pliku odpowiedzi. Niczego nie wdraża i nie łączy się z żadnym klastrem ani kontem w chmurze. Wersje robocze to zwykłe pliki w obszarze roboczym, a dalsze postępowanie z nimi należy do użytkownika.
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importrobocze pliki Aggrega
do przejrzenia i edycji
Na wejściu istniejący projekt, na wyjściu robocze pliki Aggrega. Nic nie jest wdrażane; najpierw należy przejrzeć wersje robocze.
Co daje import
- Projekt trafia do Aggrega bez ręcznego przepisywania. Wygenerowane encje Aggregate, Release i Manifest to ten sam rodzaj plików, który napisałoby się samodzielnie. Kompilują się w zapisanej postaci dla celu wskazanego przez import, a każda polityka zarządzania dołączona w obszarze roboczym ocenia tę kompilację tak jak każdą inną.
- To, co określa źródło, zostaje przeniesione. Węzeł lub usługa, dla których katalog zawiera silne dopasowanie, odwołuje się do tej encji Component z katalogu, z wartościami nadanymi jej przez źródło, takimi jak model wskazany przez przepływ. Platforma, na której działa źródło, jest zapisywana w wersji roboczej z obrazem uruchamianym przez encje Recipes z katalogu dla tej platformy. Sekret jest zapisywany jako odwołanie do miejsca, z którego pochodzi, nigdy jako jego wartość.
- Pytania dotyczą tylko tego, czego żadne źródło nie może zawierać, i padają jeden raz. Odpowiedzi są przechowywane w pliku odpowiedzi obok źródła, więc kolejny import tego samego źródła o nic nie pyta.
- Wersje robocze należą do użytkownika. To zwykły YAML w obszarze roboczym i nie pozostaje po nich nic, od czego zależałaby kompilacja. Można je edytować, zmieniać ich nazwy i commitować.
- Wersja robocza może podążać za źródłem.
aggrega import --syncuaktualnia wersje robocze z wcześniejszego importu do stanu zmienionego źródła, zmieniając tylko to, co zapisał import. Jeśli źródło zmieniło część, która została zmodyfikowana ręcznie, polecenie zatrzymuje się i wskazuje tę część, zamiast nadpisać wprowadzoną zmianę.
Czego nie robi
Import zapisuje w wersji roboczej to, co określa źródło, i to, co wyznacza katalog, a o resztę pyta. Każda wersja robocza informuje w komentarzu obok wartości, skąd pochodzi zapisana przez nią wartość.
- Nie zgaduje tego, czego źródło nie może określić. Żadne źródło nie wskazuje środowiska, w którym wdrażana jest encja Release, więc wygenerowana encja Release wskazuje
development, z komentarzem informującym, że jest to wartość domyślna do zmiany. Wartość, której wymaga katalog, a której nie zawiera żadne źródło — adres e-mail konta właściciela, obraz aplikacji zbudowanej z własnego kodu, nazwa obiektu Secret w Kubernetes — jest zapisywana jako pusta i wymaga odpowiedzi, jak opisuje sekcja Jak przebiega import poniżej. - Nie odczytuje kodu. Własny program przepływu lub projektu nie jest odczytywany: program załogi CrewAI, kod grafu aplikacji LangGraph, kod źródłowy komponentu Langflow poza przeniesieniem go wewnątrz przepływu.
- Nie ocenia, co oznacza wartość. Każdy węzeł lub usługa jest porównywany z encjami Components z katalogu obszaru roboczego — ich nazwami, kategoriami, etykietami i nazwami deklarowanych przez nie wartości. Dopasowanie z wysokiego progu jest wskazywane w wersji roboczej; słabsze jest zapisywane jako komentarz wskazujący encję Component i jej wynik punktowy, a wybór należy do użytkownika.
- Nie zmienia wersji uruchamianej przez platformę, aby podążać za źródłem. Obraz platformy jest zapisywany w wersji, o której wiadomo, że uruchamiają ją encje Recipes z katalogu dla tej platformy, a gdy źródło wskazuje inną wersję, wskazuje ją komentarz obok obrazu.
- Nie usuwa poświadczeń ze źródła za użytkownika. Wartość, która może zawierać klucz — wartość środowiskowa, nagłówek, wiersz polecenia serwera MCP — jest domyślnie przenoszona do wersji roboczej w postaci, w jakiej została zapisana, a import wskazuje każdą z nich w ostrzeżeniu
credential-carried, nigdy przez jej wartość. Ustawienieempty_credentialsimportera zapisuje je zamiast tego jako puste (Ustawienia). Przed udostępnieniem wersji roboczej należy przeczytać ostrzeżenia. - Niczego nie wdraża ani nie uruchamia. Odczytuje źródło i katalog, a następnie zapisuje pliki. Kompilacja wersji roboczych i uruchomienie tego, co zapisze kompilacja, to osobne kroki wykonywane przez użytkownika.
Jak przebiega import
Import można uruchomić poleceniami poniżej albo zlecić to asystentowi AI.
-
Punktem wyjścia jest obszar roboczy. Import zapisuje wersje robocze w obrębie folderu głównego obszaru roboczego, w którym jest uruchamiany — folderu zawierającego plik
.aggrega-config.yamlz kluczemworkspace— lub w obrębie folderu wskazanego przez--output-dir. Nigdy nie nadpisuje istniejącej już tam encji Aggregate. -
Katalog używany do porównania. Import ocenia źródło względem encji Components z katalogu obszaru roboczego i niczego innego. Jeśli obszar roboczy nie wskazuje własnego folderu katalogu, jest to katalog biblioteki standardowej, odczytywany z domyślnego rejestru obszaru roboczego: każda publikacja katalogu publikuje podpisaną migawkę całego katalogu, a pierwszy import pobiera tę migawkę, weryfikuje jej podpis, przechowuje ją w pamięci podręcznej treści obszaru roboczego i wskazuje ją przez jej skrót w zapisie, który umieszcza obok szkiców, dzięki czemu późniejszy import tych samych szkiców odczytuje ten sam katalog bez ponownego odpytywania rejestru. Względem niego usługa PostgreSQL jest dopasowywana do
core/datastore/postgres, a--targettworzy roboczą encję Manifest na podstawie encji Recipes z katalogu. Bez katalogu import nie ma do czego dopasowywać, a--targetjest odrzucane, ponieważ żadna encja Recipe nie jest powiązana z celem.Obszar roboczy, który wskazuje własne foldery katalogu, importuje zamiast tego względem nich i nie pobiera żadnej migawki: folderów wymienionych w
workspace.catalog_dirs, folderucatalogw folderze głównym obszaru roboczego lub folderów wskazanych przezAGGREGA_CATALOG_DIRS. Pliki samego katalogu biblioteki standardowej to folderaggrega-catalogrepozytoriumaggrega-hub, https://github.com/aggrega-ai/aggrega-hub, dla obszaru roboczego, który chce mieć je jako folder.--upgradepobiera najnowszą migawkę publikowaną przez rejestr i od tej pory importuje względem niej; przy--offlineimport, który musiałby pobrać migawkę, zatrzymuje się i wskazuje, co należy uruchomić. -
Uruchomienie importu. Należy wskazać plik lub folder:
Terminal window aggrega import compose.yaml --target composeFormat jest rozpoznawany na podstawie nazwy i zawartości pliku;
--formatwskazuje go tam, gdzie rozpoznanie się nie udaje.--targetwskazuje możliwość dostawcy, taką jakcomposelubhelm, i tworzy roboczą encję Manifest, która przypisuje każdy typ komponentu i każdy typ funkcji potrzebny szkicom do encji Recipe o tej możliwości, oferowanej dla niego przez katalog: tej jedynej, która istnieje, lub, spośród kilku, tej nazwanej od typu. Robocza encja Release wskazuje tę encję Manifest, a zawartość szkiców zależy od celu: wcomposesekret jest odwołaniem do zmiennej, które Docker Compose wypełnia z powłoki, whelm— nazwą obiektu Kubernetes Secret. Na standardowym wyjściu błędów import podaje odczytany format, każde ostrzeżenie i po jednym wierszu dla każdego zmapowanego węzła; na standardowym wyjściu wymienia zapisane pliki. -
Odpowiedź na to, czego nie zawiera żadne źródło. Na wartość wymaganą przez katalog, której żadne źródło nie może zawierać — adres e-mail konta właściciela, obraz aplikacji zbudowanej z własnego kodu, nazwę obiektu Kubernetes Secret — odpowiada się raz. Import odczytuje odpowiedzi z
import-answers.yamlobok źródła lub z pliku wskazanego przez--answers; w terminalu pyta o każdą wciąż brakującą wartość, po jednym pytaniu naraz, i zapisuje odpowiedzi w tym pliku. Na sekret odpowiada się wskazaniem, skąd pochodzi — zmienną lub nazwą obiektu Secret — nigdy jego wartością. Tam, gdzie nie można o nic zapytać — w ciągłej integracji, przez potok, z asystenta lub edytora — import zapisuje plik odpowiedzi z kluczem każdej brakującej wartości i pustą odpowiedzią, wymienia je i kończy działanie ze statusem 1; należy je uzupełnić i ponownie uruchomić import. Jeden plik odpowiedzi służy każdemu celowi: odpowiedź, której szkice dla danego celu nie potrzebują, pozostaje w pliku i nie jest używana. Plik odpowiedzi importu opisuje ten plik w całości. -
Import pobiera to, czego potrzebuje kompilacja. Gdy niczego już nie brakuje, import pobiera zależności roboczej encji Release, tak jak robi to
aggrega pull, i zapisuje obok niejrelease.lock. W trybie--offlineniczego nie pobiera i wskazuje polecenieaggrega pulldo uruchomienia. -
Walidacja i kompilacja. W folderze zawierającym wersje robocze:
Terminal window aggrega validate --release release.yamlaggrega build --release release.yamlGdy oba polecenia zakończą się powodzeniem, kompilacja ma już zapisane pliki celu w
dist/. Odmowa wskazuje, co i gdzie należy zmienić, w dokumencie, który się zmienia. -
Należy uruchomić to, co zapisała kompilacja. Kompilacja dla Docker Compose zapisuje
dist/compose/docker-compose.yaml, a plik nie wskazuje żadnego projektu Compose, więc nazwę projektu należy podać za pomocą-p:Terminal window docker compose -p <name> -f dist/compose/docker-compose.yaml up -dBez
-pDocker Compose nazywa projekt od folderu zawierającego plik,compose, więc dwa obszary robocze uruchomione w ten sposób współdzielą jeden projekt. Usługi znajdują się w jednej sieci, którą Docker Compose nazywa od projektu,<name>_compose. Do usługi, dla której build nie publikuje żadnego portu, można dotrzeć z wnętrza tej sieci, poleceniemdocker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, lub z kontenera uruchomionego w tej sieci poleceniemdocker run --network <name>_compose …. Sekcje „Uruchomienie” i „Test” przewodnika pokazują polecenia dla jego własnego buildu.Uruchomienie odpowiada bez klucza OpenAI, gdy jego model
core/ai-model/openaiwskazuje na mały model serwowany przez Ollama w tym samym projekcie, przy trzech zmianach w utworzonych plikach roboczych, kompilacji z--auto-pull, która pobiera to, czego potrzebuje dodany komponent, i jednym poleceniu po uruchomieniu stacku:- w encji Aggregate jeszcze jeden komponent, niepołączony z niczym:
local-model, typucore/ai-model/ollama, zmodel: qwen2.5:0.5bw jegovalues; - w encji Manifest jego Recipe dla Compose:
core/ai-model/ollama: compose/ollama; - w encji Release
local-model: {}oraz kluczendpointmodelu OpenAI, w jegoinfra, ustawiony na zgodny z OpenAI adres tego serwera,http://local-model:11434/v1; - po uruchomieniu stosu pobrany model skopiowany pod nazwą modelu, którą wskazuje model OpenAI buildu,
<model>, na przykładgpt-4o-minilubgpt-4.1:docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.
OPENAI_API_KEYmoże wtedy zawierać dowolną własną niepustą wartość: lokalny serwer żadnej nie sprawdza. Przepływ pracy n8n odczytuje adres i klucz modelu z poświadczenia wybranego przez jego węzeł modelu, a nie z adresu dostarczanego przezendpoint, dlatego należy przekazać temu poświadczeniu również adres serwera, jakourlobokapiKeyw jegodata. Serwer Ollama uruchamiany domyślnie przezcore/ai-model/ollamaobsługuje oprócz Chat Completions również Responses API OpenAI, dlatego deklaratywny agent Agent Framework, który wskazujeapiType: Responses, dociera do niego w postaci, w jakiej został napisany.Build dla Kubernetes, cel
helm, zapisuje zwykłe manifesty zamiast chartu, jak opisuje to dostawca helm: wdist/helm/lub, w przypadku komponentów, które encja Release umieszcza w granicy, wdist/boundaries/<boundary>/helm/, niektóre z nich we własnym folderze poniżej. Pliki, które nie wskazują przestrzeni nazw, jak pliki buildów MCP i Dify, trafiają do tej, którą wskazuje kontekstkubectl, lub dodefault, jeśli nie wskazuje żadnej; najpierw należy tam utworzyć obiekty Secrets, które te pliki odczytują, a następnie zastosować folder:Terminal window kubectl apply -R -f dist/helm/-Robejmuje pliki w tych folderach. Obiekt Service typuClusterIP, czyli typu, który buildy MCP i Dify nadają uruchamianym serwerom, jest osiągalny tylko z wnętrza klastra: aby dotrzeć do niego z własnej maszyny, należy przekierować do niego lokalny port za pomocąkubectl port-forward svc/<service> <local port>:<port>; to polecenie działa, dopóki się go nie zatrzyma. - w encji Aggregate jeszcze jeden komponent, niepołączony z niczym:
Obok wersji roboczych import zapisuje .aggrega-import.json, zapis tego, co utworzył. Należy go zachować tak długo, jak zamierza się uruchamiać aggrega import --sync, które odczytuje go, aby odróżnić zmiany użytkownika od własnych. Należy też zachować plik odpowiedzi: nie zawiera żadnego sekretu, więc może znajdować się w systemie kontroli wersji obok źródła, a każdy późniejszy import tego źródła go odczytuje.
Z asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić do niego ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Wywołaj narzędzie `import` z `source` ustawionym na `compose.yaml` i `target` ustawionym na `compose`: zapisuje ono swoje wersje robocze w folderze Workspace. Jeśli poinformuje, że wciąż brakuje wartości, podaj mi każdą z nich i wyjaśnij, czym jest, i poczekaj, aż wpiszę odpowiedzi obok ich kluczy w pliku odpowiedzi, który wskaże; następnie wywołaj ponownie narzędzie `import` w ten sam sposób. Potem wywołaj narzędzie `validate` z `release` ustawionym na `release.yaml` oraz narzędzie `build` z `release` ustawionym na `release.yaml` i `write` ustawionym na true. Powiedz mi, które pliki zapisał build; znajdują się w `dist/` w folderze Workspace.Otwieranie w VS Code
Po zainstalowaniu rozszerzenia Aggrega dla Visual Studio Code należy otworzyć w VS Code obszar roboczy, w którym uruchomiono import — folder zawierający jego .aggrega-config.yaml: wersje robocze są w nim, w katalogu głównym lub w folderze wskazanym przez --output-dir. Gdy obszar roboczy zawiera jedną encję Release, edytor sam ją wybiera; gdy zawiera ich więcej, Aggrega: Select Release… wybiera tę, na której pracuje edytor. Edytor sprawdza wersje robocze względem wybranej encji Release podczas edycji, oznaczając to, co znajdzie, w pliku i w panelu Problemy. Aggrega: Show topology graph w palecie poleceń rysuje komponenty wybranej encji Release i połączenia między nimi. Aggrega: Build, Aggrega: Preview build i Aggrega: Pull działają na tej samej encji Release, a każde z nich jest też przyciskiem w panelu Commands widoku Aggrega na pasku działań; Build zapisuje swoje pliki w katalogu dist/ obszaru roboczego. Resztę omawia Korzystanie z Aggrega w Visual Studio Code.
Skąd pochodzą importery
Każdy format jest odczytywany przez wtyczkę importera. Podstawowe importery kompilatora, po jednym dla każdego formatu z poniższej tabeli, są publikowane z każdym wydaniem kompilatora i obsługują swoje formaty w każdym obszarze roboczym, bez żadnego wpisu w katalogu. Pierwszy import, który potrzebuje któregoś z nich, pobiera go z domyślnego rejestru obszaru roboczego, w wersji samego kompilatora, weryfikuje go i przechowuje w pamięci podręcznej treści obszaru roboczego, dzięki czemu każdy kolejny import odczytuje go stamtąd, bez łączenia się w tym celu z siecią. Jeśli modułu w ogóle nie da się pobrać — na przykład gdy obszar roboczy jest offline — import zatrzymuje się i wskazuje dwa sposoby umieszczenia go na maszynie. Podstawowe importery opisują każdy importer w całości, a także ustawienia przekazywane importerowi przez wpis plugins.importer.
Formaty
| Format | Co odczytuje | Przewodnik |
|---|---|---|
| Compose | plik Compose i jego plik nadpisań albo folder, który je zawiera | Import projektu Compose |
| Konfiguracje klientów MCP | .mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json lub server.json z rejestru MCP | Import konfiguracji klienta MCP |
| Langflow | przepływ wyeksportowany z Langflow, jako JSON | Import przepływu Langflow |
| Flowise | chatflow lub agentflow wyeksportowany z Flowise, jako JSON | Import chatflow z Flowise |
| n8n | przepływ pracy wyeksportowany z n8n, jako JSON | Import workflow z n8n |
| Dify | aplikację wyeksportowaną z Dify w jej DSL, jako YAML | Import aplikacji Dify |
| CrewAI | deklaracje agentów i zadań projektu CrewAI | Import projektu CrewAI |
| LangGraph | plik langgraph.json aplikacji LangGraph | Import aplikacji LangGraph |
| Google ADK | pliki Agent Config aplikacji zbudowanej na Google ADK, począwszy od root_agent.yaml | Import agenta Google ADK |
| Microsoft Agent Framework | agent deklaratywny, dokument YAML rodzaju Prompt | Import agenta deklaratywnego Microsoft Agent Framework |
aggrega import to pełna dokumentacja referencyjna polecenia: każda flaga, sposób rozpoznawania źródła, co zmienia --sync i czego odmawia. Plik odpowiedzi importu opisuje plik odpowiedzi: gdzie się znajduje, co zawiera i jak udziela się odpowiedzi na sekret.