Importazione
aggrega import legge un progetto scritto in un altro formato — un flusso esportato da Langflow, la configurazione di un client MCP, un file Compose e gli altri formati elencati più avanti — e ne ricava file Aggrega: un Aggregate, una Release e, per la destinazione indicata da --target, un Manifest. Insieme formano un workspace che si convalida e si compila così com’è scritto, una volta date le risposte ai pochi valori che nessuna sorgente può contenere: l’importazione chiede ciascuno di essi una sola volta e conserva le risposte in un file di risposte. Non distribuisce nulla e non raggiunge alcun cluster né account cloud. Le bozze sono semplici file nel tuo workspace, e cosa farne dopo spetta a te.
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importbozze di file Aggrega
da rivedere e modificare
Entra il tuo progetto esistente, escono bozze di file Aggrega. Nulla viene distribuito; prima rivedi le bozze.
Cosa ti offre
- Il tuo progetto arriva in Aggrega senza essere riscritto a mano. L’Aggregate, la Release e il Manifest redatti sono lo stesso tipo di file che scriveresti tu. Si compilano così come sono scritti per la destinazione indicata dall’importazione, e ogni policy di governance che il tuo workspace collega giudica quella build come qualsiasi altra.
- Ciò che la sorgente dichiara viene riportato. Un nodo o un servizio per cui il catalogo contiene una corrispondenza forte fa riferimento a quel Component del catalogo, con i valori che la sorgente gli assegna, come il modello indicato da un flusso. Una piattaforma su cui la sorgente gira viene redatta con l’immagine eseguita dalle Recipes del catalogo per quella piattaforma. Un segreto viene redatto come riferimento alla sua provenienza, mai come il suo valore.
- Ti viene chiesto solo ciò che nessuna sorgente può contenere, una sola volta. Le risposte sono conservate in un file di risposte accanto alla sorgente, così la successiva importazione della stessa sorgente non chiede nulla.
- Le bozze sono tue. Sono semplice YAML nel tuo workspace, e non resta indietro nulla da cui la build dipenda. Modificale, rinominale, fanne il commit.
- La bozza può seguire la sua sorgente.
aggrega import --syncallinea le bozze di un’importazione precedente a una sorgente modificata, cambiando solo ciò che l’importazione ha scritto. Dove la sorgente ha cambiato una parte che hai modificato tu, si ferma e indica quella parte invece di sovrascrivere la tua modifica.
Che cosa non fa
Un’importazione redige in bozza ciò che la sorgente dichiara e ciò che il tuo catalogo determina, e chiede il resto. Ogni bozza dice, in un commento accanto al valore, da dove proviene un valore che ha redatto.
- Non indovina ciò che la tua sorgente non può dichiarare. Nessuna sorgente indica l’ambiente in cui una Release viene distribuita, quindi la Release redatta indica
development, con un commento che dice che si tratta di un valore predefinito da cambiare. Un valore che il catalogo richiede e che nessuna sorgente contiene — l’email dell’account di un proprietario, l’immagine di un’applicazione compilata dal tuo codice, il nome di un Secret Kubernetes — viene redatto vuoto e richiesto, come descrive Come si svolge un’importazione più avanti. - Non legge codice. Il programma proprio di un flusso o di un progetto non viene letto: il programma di una crew CrewAI, il codice del grafo di un’applicazione LangGraph, il sorgente di un componente Langflow, se non per riportarlo all’interno del flusso.
- Non giudica cosa significa un valore. Ogni nodo o servizio viene confrontato con i Components del catalogo del tuo workspace — i loro nomi, le loro categorie, le loro etichette e i nomi dei valori che dichiarano. Una corrispondenza nella fascia alta viene referenziata nella bozza; una più debole viene scritta come commento che indica il Component e il suo punteggio, e la scelta è tua.
- Non cambia la versione eseguita da una piattaforma per seguire la sorgente. L’immagine di una piattaforma viene redatta alla versione che è noto essere eseguita dalle Recipes del catalogo per quella piattaforma, e dove la sorgente indica un’altra versione, un commento accanto all’immagine la riporta.
- Non sposta al posto tuo le credenziali fuori dalla tua sorgente. Un valore che può contenere una chiave — un valore d’ambiente, un header, la riga di comando di un server MCP — per impostazione predefinita viene riportato nella bozza così com’è scritto, e l’importazione nomina ciascuno in un avviso
credential-carried, mai tramite il suo valore. L’impostazioneempty_credentialsdell’importatore li scrive invece vuoti (Impostazioni). Leggi gli avvisi prima di condividere una bozza. - Non distribuisce né esegue nulla. Legge la sorgente e il tuo catalogo, e scrive file. Compilare le bozze ed eseguire ciò che la build scrive sono passi separati che compi tu.
Come si svolge un’importazione
Puoi eseguire un’importazione con i comandi qui sotto, oppure farla eseguire al tuo assistente AI.
-
Parti da un workspace. Un’importazione scrive le sue bozze sotto la radice del workspace in cui viene eseguita — la cartella che contiene un
.aggrega-config.yamlcon una chiaveworkspace— oppure sotto la directory indicata da--output-dir. Non sovrascrive mai un Aggregate già presente. -
Il catalogo con cui confronta. L’importazione valuta la tua sorgente rispetto ai Components del catalogo del workspace, e nient’altro. Dove il workspace non indica una propria cartella di catalogo, si tratta del catalogo della libreria standard, letto dal registry predefinito del workspace: ogni pubblicazione del catalogo pubblica uno snapshot firmato dell’intero catalogo, e la prima importazione scarica quello snapshot, ne verifica la firma, lo conserva nella cache dei contenuti del workspace e lo indica tramite il suo digest nel registro che scrive accanto alle bozze, così un’importazione successiva delle stesse bozze legge lo stesso catalogo senza interpellare di nuovo il registry. Rispetto a esso, un servizio PostgreSQL viene associato a
core/datastore/postgres, e--targetredige un Manifest a partire dalle Recipes del catalogo. Senza catalogo, l’importazione non ha nulla da associare, e--targetviene rifiutato, poiché nessuna Recipe è associata alla destinazione.Un workspace che indica proprie cartelle di catalogo importa invece rispetto a quelle, e non scarica alcuno snapshot: le directory elencate in
workspace.catalog_dirs, una cartellacatalogalla radice del workspace, o le directory indicate daAGGREGA_CATALOG_DIRS. I file del catalogo della libreria standard sono la cartellaaggrega-catalogdel repositoryaggrega-hub, https://github.com/aggrega-ai/aggrega-hub, per un workspace che li vuole come cartella.--upgradescarica lo snapshot più recente pubblicato dal registry e da quel momento importa rispetto a esso; con--offline, un’importazione che dovrebbe scaricare uno snapshot si ferma e indica cosa eseguire. -
Esegui l’importazione. Indica il file o la directory:
Terminal window aggrega import compose.yaml --target composeIl formato viene riconosciuto dal nome e dal contenuto del file;
--formatlo indica dove non lo è.--targetindica una capacità di provider, comecomposeohelm, e redige un Manifest che associa ogni tipo di componente e ogni tipo di funzionalità di cui le bozze hanno bisogno alla Recipe di quella capacità che il tuo catalogo offre per esso: quella che c’è o, tra più d’una, quella che porta il nome del tipo. La Release redatta indica quel Manifest, e ciò che le bozze contengono segue la destinazione: sucomposeun segreto è un riferimento a una variabile che Docker Compose valorizza dalla tua shell, suhelmil nome di un Kubernetes Secret. Sullo standard error l’importazione indica il formato che ha letto, ogni avviso e una riga per ogni nodo che ha mappato; sullo standard output elenca i file che ha scritto. -
Rispondi a ciò che nessuna sorgente contiene. Un valore che il catalogo richiede e che nessuna sorgente può contenere — l’email dell’account di un proprietario, l’immagine di un’applicazione compilata dal tuo codice, il nome di un Kubernetes Secret — riceve risposta una volta sola. L’importazione legge le risposte da
import-answers.yamlaccanto alla sorgente, o dal file indicato da--answers; in un terminale chiede ogni valore ancora mancante, una domanda alla volta, e scrive le tue risposte in quel file. A un segreto si risponde con la sua provenienza — una variabile o il nome di un Secret — mai con il suo valore. Dove non si può chiedere nulla — in integrazione continua, attraverso una pipe, dall’assistente o dall’editor — l’importazione scrive il file delle risposte con la chiave di ogni valore mancante e una risposta vuota, li elenca ed esce con stato 1; compilali ed esegui di nuovo l’importazione. Un solo file delle risposte serve ogni destinazione: una risposta che le bozze per una destinazione non richiedono viene conservata nel file e lasciata inutilizzata. Il file delle risposte dell’importazione descrive il file per intero. -
L’importazione scarica ciò che serve alla build. Quando non manca più nulla, l’importazione scarica le dipendenze della Release redatta, come fa
aggrega pull, e scriverelease.lockaccanto a essa. Con--offlinenon scarica nulla e indica il comandoaggrega pullda eseguire. -
Convalida e compila. Nella cartella che contiene le bozze:
Terminal window aggrega validate --release release.yamlaggrega build --release release.yamlQuando entrambi passano, la build ha scritto i file della destinazione sotto
dist/. Un rifiuto indica cosa cambiare e dove, nel documento che modifichi. -
Esegui ciò che la build ha scritto. Una build per Docker Compose scrive
dist/compose/docker-compose.yaml, e il file non nomina alcun progetto Compose, quindi assegnane uno con-p:Terminal window docker compose -p <name> -f dist/compose/docker-compose.yaml up -dSenza
-p, Docker Compose dà al progetto il nome della cartella che contiene il file,compose, quindi due workspace avviati in questo modo condividono un unico progetto. I servizi si trovano su un’unica rete, a cui Docker Compose dà il nome del progetto,<name>_compose. Un servizio per cui la build non pubblica alcuna porta si raggiunge dall’interno della rete, condocker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, oppure da un container che avvii su quella rete condocker run --network <name>_compose …. Le sezioni «Eseguilo» e «Testalo» di una guida passo passo mostrano i comandi per la sua build.Un’esecuzione risponde senza una chiave OpenAI quando il suo modello
core/ai-model/openaipunta a un piccolo modello servito da Ollama nello stesso progetto, con tre modifiche ai file redatti, una build con--auto-pull, che scarica ciò di cui ha bisogno il componente aggiunto, e un comando una volta avviato lo stack:- nell’Aggregate, un componente in più, collegato a nulla:
local-model, di tipocore/ai-model/ollama, conmodel: qwen2.5:0.5bnei suoivalues; - nel Manifest, la sua Recipe per Compose:
core/ai-model/ollama: compose/ollama; - nella Release,
local-model: {}, e la chiaveendpointdel modello OpenAI, sotto il suoinfra, impostata sull’indirizzo compatibile con OpenAI di quel server,http://local-model:11434/v1; - una volta avviato lo stack, il modello scaricato copiato con il nome di modello indicato dal modello OpenAI della build,
<model>, comegpt-4o-miniogpt-4.1:docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.
OPENAI_API_KEYpuò quindi contenere qualsiasi valore non vuoto a tua scelta: il server locale non ne verifica nessuno. Un workflow n8n legge l’indirizzo e la chiave del modello dalla credenziale che il suo nodo del modello seleziona, non dall’indirizzo cheendpointfornisce, perciò dai anche a quella credenziale l’indirizzo del server, comeurlaccanto adapiKeynei suoidata. Il server Ollama checore/ai-model/ollamaesegue per impostazione predefinita serve la Responses API di OpenAI oltre a Chat Completions, perciò un agente dichiarativo Agent Framework che indicaapiType: Responseslo raggiunge così com’è scritto.Una build per Kubernetes, il target
helm, scrive manifest semplici anziché un chart, come descrive il provider helm: sottodist/helm/oppure, per i componenti che una Release colloca in un boundary, sottodist/boundaries/<boundary>/helm/, alcuni dei quali in una cartella propria al suo interno. I file che non indicano alcun namespace, come quelli delle build MCP e Dify, finiscono in quello indicato dal tuo contestokubectl, oppure indefaultse non ne indica nessuno; crea prima lì i Secret che leggono, poi applica la cartella:Terminal window kubectl apply -R -f dist/helm/-Rraggiunge i file in quelle cartelle. Un ServiceClusterIP, il tipo che le build MCP e Dify assegnano ai server che eseguono, è raggiungibile solo dall’interno del cluster: per raggiungerne uno dalla tua macchina inoltragli una porta locale, conkubectl port-forward svc/<service> <local port>:<port>, che resta in esecuzione finché non lo interrompi. - nell’Aggregate, un componente in più, collegato a nulla:
Accanto alle bozze, l’importazione scrive .aggrega-import.json, il registro di ciò che ha scritto. Conservalo finché intendi eseguire aggrega import --sync, che lo legge per distinguere le tue modifiche dalle sue. Conserva anche il file delle risposte: non contiene alcun segreto, quindi può stare nel controllo di versione accanto alla sorgente, e ogni importazione successiva di quella sorgente lo legge.
Con un assistente AI
Un assistente AI configurato con gli strumenti di Aggrega può fare lo stesso: incollaci questo prompt.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Chiama lo strumento `import` con `source` impostato su `compose.yaml` e `target` impostato su `compose`: scrive le sue bozze nella cartella Workspace. Se dice che mancano ancora dei valori, dimmi ciascuno e che cos’è, e aspetta mentre scrivo le mie risposte accanto alle rispettive chiavi nel file delle risposte che indica; poi chiama di nuovo lo strumento `import` allo stesso modo. Quindi chiama lo strumento `validate` con `release` impostato su `release.yaml`, e lo strumento `build` con `release` impostato su `release.yaml` e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano sotto `dist/` nella cartella Workspace.Aprilo in VS Code
Con l’estensione Aggrega per Visual Studio Code installata, apri in VS Code il workspace in cui è stata eseguita l’importazione — la cartella che contiene il suo .aggrega-config.yaml: le bozze sono lì, nella radice o nella cartella indicata da --output-dir. Dove il workspace contiene una sola Release, l’editor la seleziona per te; dove ne contiene di più, Aggrega: Select Release… sceglie quella su cui lavora l’editor. L’editor controlla le bozze rispetto alla Release selezionata mentre le modifichi, segnalando ciò che trova nel file e nel pannello Problemi. Aggrega: Show topology graph, nel riquadro comandi, disegna i componenti della Release selezionata e le connessioni tra di essi. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull agiscono sulla stessa Release, e ciascuno è anche un pulsante nel pannello Commands della vista Aggrega nella barra delle attività; Build scrive i suoi file nella cartella dist/ del workspace. Usare Aggrega in Visual Studio Code tratta il resto.
Da dove provengono gli importatori
Ogni formato viene letto da un plugin importatore. Gli importatori core del compilatore, uno per ogni formato della tabella seguente, vengono pubblicati con ogni rilascio del compilatore e servono i loro formati in ogni workspace, senza alcuna voce nel tuo catalogo. La prima importazione che ne ha bisogno lo recupera dal registry predefinito del workspace, alla versione del compilatore stesso, lo verifica e lo conserva nella cache dei contenuti del workspace, così ogni importazione successiva lo legge da lì, senza bisogno di rete per esso. Dove il modulo non può essere recuperato affatto — ad esempio perché il workspace è offline — l’importazione si ferma e indica i due modi per metterlo sulla macchina. Importatori core descrive ogni importatore per intero, e le impostazioni che un importatore riceve tramite una voce plugins.importer.
I formati
| Formato | Che cosa legge | Procedura guidata |
|---|---|---|
| Compose | un file Compose e il suo file di override, oppure una directory che li contiene | Importare un progetto Compose |
| Configurazioni di client MCP | .mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json oppure un server.json di un registry MCP | Importare la configurazione di un client MCP |
| Langflow | un flusso esportato da Langflow, in JSON | Importare un flusso Langflow |
| Flowise | un chatflow o un agentflow esportato da Flowise, in JSON | Importare un chatflow Flowise |
| n8n | un workflow esportato da n8n, in JSON | Importare un workflow n8n |
| Dify | un’applicazione esportata da Dify nel suo DSL, in YAML | Importare un’applicazione Dify |
| CrewAI | le dichiarazioni di agenti e task di un progetto CrewAI | Importare un progetto CrewAI |
| LangGraph | il langgraph.json di un’applicazione LangGraph | Importare un’applicazione LangGraph |
| Google ADK | i file Agent Config di un’applicazione costruita su Google ADK, a partire da root_agent.yaml | Importare un agente Google ADK |
| Microsoft Agent Framework | un agente dichiarativo, un documento YAML di tipo Prompt | Importare un agente dichiarativo di Microsoft Agent Framework |
aggrega import è il riferimento completo del comando: ogni flag, come viene riconosciuta una sorgente, cosa cambia --sync e cosa rifiuta. Il file delle risposte dell’importazione descrive il file delle risposte: dove si trova, cosa contiene e come si risponde a un segreto.