Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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 import

bozze 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 --sync allinea 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’impostazione empty_credentials dell’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.

  1. 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.yaml con una chiave workspace — oppure sotto la directory indicata da --output-dir. Non sovrascrive mai un Aggregate già presente.

  2. 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 --target redige un Manifest a partire dalle Recipes del catalogo. Senza catalogo, l’importazione non ha nulla da associare, e --target viene 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 cartella catalog alla radice del workspace, o le directory indicate da AGGREGA_CATALOG_DIRS. I file del catalogo della libreria standard sono la cartella aggrega-catalog del repository aggrega-hub, https://github.com/aggrega-ai/aggrega-hub, per un workspace che li vuole come cartella. --upgrade scarica 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.

  3. Esegui l’importazione. Indica il file o la directory:

    Terminal window
    aggrega import compose.yaml --target compose

    Il formato viene riconosciuto dal nome e dal contenuto del file; --format lo indica dove non lo è. --target indica una capacità di provider, come compose o helm, 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: su compose un segreto è un riferimento a una variabile che Docker Compose valorizza dalla tua shell, su helm il 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.

  4. 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.yaml accanto 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.

  5. 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 scrive release.lock accanto a essa. Con --offline non scarica nulla e indica il comando aggrega pull da eseguire.

  6. Convalida e compila. Nella cartella che contiene le bozze:

    Terminal window
    aggrega validate --release release.yaml
    aggrega build --release release.yaml

    Quando entrambi passano, la build ha scritto i file della destinazione sotto dist/. Un rifiuto indica cosa cambiare e dove, nel documento che modifichi.

  7. 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 -d

    Senza -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, con docker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, oppure da un container che avvii su quella rete con docker 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/openai punta 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 tipo core/ai-model/ollama, con model: qwen2.5:0.5b nei suoi values;
    • nel Manifest, la sua Recipe per Compose: core/ai-model/ollama: compose/ollama;
    • nella Release, local-model: {}, e la chiave endpoint del modello OpenAI, sotto il suo infra, 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>, come gpt-4o-mini o gpt-4.1: docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.

    OPENAI_API_KEY può 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 che endpoint fornisce, perciò dai anche a quella credenziale l’indirizzo del server, come url accanto ad apiKey nei suoi data. Il server Ollama che core/ai-model/ollama esegue per impostazione predefinita serve la Responses API di OpenAI oltre a Chat Completions, perciò un agente dichiarativo Agent Framework che indica apiType: Responses lo raggiunge così com’è scritto.

    Una build per Kubernetes, il target helm, scrive manifest semplici anziché un chart, come descrive il provider helm: sotto dist/helm/ oppure, per i componenti che una Release colloca in un boundary, sotto dist/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 contesto kubectl, oppure in default se non ne indica nessuno; crea prima lì i Secret che leggono, poi applica la cartella:

    Terminal window
    kubectl apply -R -f dist/helm/

    -R raggiunge i file in quelle cartelle. Un Service ClusterIP, 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, con kubectl port-forward svc/<service> <local port>:<port>, che resta in esecuzione finché non lo interrompi.

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

FormatoChe cosa leggeProcedura guidata
Composeun file Compose e il suo file di override, oppure una directory che li contieneImportare 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 MCPImportare la configurazione di un client MCP
Langflowun flusso esportato da Langflow, in JSONImportare un flusso Langflow
Flowiseun chatflow o un agentflow esportato da Flowise, in JSONImportare un chatflow Flowise
n8nun workflow esportato da n8n, in JSONImportare un workflow n8n
Difyun’applicazione esportata da Dify nel suo DSL, in YAMLImportare un’applicazione Dify
CrewAIle dichiarazioni di agenti e task di un progetto CrewAIImportare un progetto CrewAI
LangGraphil langgraph.json di un’applicazione LangGraphImportare un’applicazione LangGraph
Google ADKi file Agent Config di un’applicazione costruita su Google ADK, a partire da root_agent.yamlImportare un agente Google ADK
Microsoft Agent Frameworkun agente dichiarativo, un documento YAML di tipo PromptImportare 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.