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

Importatori core

Il repository del compilatore compila dieci plugin importatori propri, uno per ciascun formato sorgente, e li pubblica a ogni release del compilatore:

PluginServeLegge
importer/langflowimport:langflowun flusso esportato da Langflow, in JSON
importer/flowiseimport:flowiseun chatflow o un agentflow esportato da Flowise, in JSON
importer/n8nimport:n8nun workflow esportato da n8n, in JSON
importer/mcpimport:mcpla configurazione di un client MCP — .mcp.json, claude_desktop_config.json, .vscode/mcp.json o .cursor/mcp.json — oppure la descrizione di un server del registry MCP, server.json, in JSON
importer/composeimport:composeun’applicazione Compose — compose.yaml, docker-compose.yml e i loro file di sovrascrittura — in YAML
importer/difyimport:difyun’applicazione esportata da Dify nel suo DSL, in YAML
importer/crewaiimport:crewaigli agenti e i task che un progetto CrewAI dichiara — config/agents.yaml e config/tasks.yaml, in YAML, oppure crew.jsonc e agents/<name>.jsonc, o le loro varianti in JSON rigoroso crew.json e agents/<name>.json, in JSON con commenti
importer/langgraphimport:langgraphla configurazione di un’applicazione LangGraph, langgraph.json, in JSON, e, di un file di ambiente che la configurazione nomina, solo i nomi delle variabili, dove l’importazione riceve quel file sotto with.sources
importer/google-adkimport:google-adkgli agenti dichiarati nei file Agent Config di un’applicazione costruita su Google ADK — root_agent.yaml e le configurazioni nominate dai suoi sotto-agenti — in YAML
importer/agent-frameworkimport:agent-frameworkun agente dichiarativo di Microsoft Agent Framework, un documento di tipo Prompt con qualsiasi nome, in YAML

Ciascuno è compilato dai sorgenti del compilatore stesso e marcato con la versione del compilatore, quindi gli importatori rilasciati con il compilatore alla versione X.Y.Z riportano la versione X.Y.Z, e le loro entità Plugin la registrano. A differenza dei plugin elencati in Plugin integrati, nessuno è compilato nel binario. Il binario porta con sé l’entità Plugin di ciascuno e il digest dell’unico modulo che accetta per esso, quindi ciascuno serve il proprio formato in ogni workspace, senza alcuna voce nel suo catalogo.

Tutti e dieci sono costruiti sul package importer del kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Per gli importatori Langflow, Flowise e n8n, tutto ciò che un importatore fa qualunque sia il suo formato — valutare i Components del catalogo del workspace rispetto a ciascun nodo, decidere se fare riferimento a uno di essi o generarne uno nuovo in bozza, disporre la bozza, riportare i valori delle credenziali che contiene o scriverli vuoti come chiede un’impostazione, scrivere le bozze e leggere le impostazioni descritte più sotto — spetta a quel package, e solo leggere il formato, e conoscere la piattaforma su cui girano i suoi flussi, è proprio di ciascun importatore. L’importatore MCP genera in bozza un’istanza di un Component per server, quindi non valuta nulla; condivide con il package la lettura delle impostazioni che legge, la decisione sui valori delle credenziali e le convenzioni con cui le sue bozze vengono nominate e descritte, come descrive L’importatore MCP. L’importatore Compose decide ogni servizio a cui trova corrispondenza come gli importatori di flussi decidono un nodo, tramite lo stesso package, renderizza le sue bozze come fanno loro e condivide il resto come fa l’importatore MCP, come descrive L’importatore Compose. L’importatore Dify genera in bozza l’installazione Dify che la libreria standard assembla, che porta l’applicazione, tramite la bozza di piattaforma dello stesso package nella forma che assume per una piattaforma che è un’intera installazione, come descrive L’importatore Dify. L’importatore CrewAI genera in bozza un’istanza dell’agente CrewAI della libreria standard per ogni agente che un progetto dichiara, collegata al modello che quell’agente nomina, e condivide il resto come fa l’importatore MCP, come descrive L’importatore CrewAI. L’importatore LangGraph genera in bozza un’istanza dell’agente LangGraph della libreria standard per ogni grafo che la configurazione di un’applicazione dichiara, collegata al datastore in cui il suo checkpointer conserva lo stato, e condivide il resto come fa l’importatore MCP, come descrive L’importatore LangGraph. L’importatore Google ADK genera in bozza un’istanza dell’agente ADK della libreria standard per ogni albero di agenti che le configurazioni di un’applicazione dichiarano, collegata al modello che l’albero nomina quando ADK invia le sue richieste all’API Gemini, e condivide il resto come fa l’importatore MCP, come descrive L’importatore Google ADK. L’importatore Agent Framework genera in bozza un’istanza dell’agente Agent Framework della libreria standard per ogni agente dichiarativo, collegata al modello OpenAI che l’agente nomina — con ogni server MCP che nomina scritto nei commenti, poiché il fornitore del modello lo raggiunge come strumento ospitato — e condivide il resto come fa l’importatore MCP, come descrive L’importatore Agent Framework. Come funziona il socket importatore, e che cosa riceve, è descritto in Il socket importatore.

Questa pagina è il riferimento per ciò che ogni importatore legge e genera come bozza. Per importare un tuo progetto e compilarne il risultato, inizia da Importazione, che accompagna un progetto dalla sua sorgente a una compilazione, un formato alla volta.

Come un’importazione ne ottiene uno

aggrega import, il metodo aggrega/import della sessione dell’editor e lo strumento import dell’assistente ottengono un importatore core allo stesso modo. Dove la macchina contiene già il suo modulo — nella cache dei contenuti del workspace — l’importazione lo legge da lì, senza ricorrere alla rete per esso. Dove non lo contiene, la prima importazione che ne ha bisogno lo scarica dal registry predefinito del workspace, alla versione del compilatore, e:

  • lo verifica rispetto al digest che il binario porta con sé, così viene eseguito solo il modulo pubblicato dalla release del compilatore;
  • lo verifica come un pull verifica un plugin che scarica — la sua firma secondo il criterio di attendibilità di quel registry, e le funzioni host che usa rispetto a quelle che la sua entità Plugin registra;
  • lo conserva nella cache dei contenuti del workspace, che è l’unica cosa scritta per esso: nessun lockfile e nessun record dei plugin attendibili, perché un’importazione non fissa alcun importatore.

Ogni importazione successiva lo legge dalla cache dei contenuti. Un modulo che non supera la verifica viene rifiutato, e non viene conservato nulla. In una cartella che nessun workspace contrassegna non c’è alcuna cache dei contenuti in cui conservarlo, quindi lì lo scaricamento viene rifiutato, indicando la cartella e come nominare un workspace o rendere la cartella un workspace. Il modulo non viene mai letto da accanto a un’entità Plugin con lo stesso nome a un’altra versione in una cartella di catalogo: quel modulo appartiene all’altra entità.

Dove il modulo non può essere scaricato, l’importazione si arresta con A plugin’s .wasm is not on this machine (Il file Wasm di un plugin non è su questa macchina), indicando l’importatore e la sua versione, e dice che cosa mette il suo modulo sulla macchina:

  • Esegui l’importazione una volta con la rete disponibile, dove il workspace è offline o il suo registry non è stato raggiungibile. Quell’esecuzione lo scarica e ogni esecuzione successiva è offline.
  • Colloca il suo modulo accanto a un’entità Plugin di quell’importatore a quella versione in una cartella di catalogo, con il nome che il messaggio indica — importer--langflow.wasm per l’importatore Langflow. Un’entità di catalogo con lo stesso nome e la stessa versione di un importatore core viene eseguita al suo posto, con il suo modulo letto da accanto a essa; un’entità lì presente senza alcun modulo accanto non viene eseguita, e l’importatore core si ottiene come descritto sopra. Dove il registry non contiene il modulo, o il workspace non indica alcun registry predefinito, questo è l’unico rimedio che il messaggio indica.

Quale viene eseguito accanto ai tuoi importatori

Gli importatori core sono candidati accanto agli importatori che il catalogo del tuo workspace contiene, secondo le regole con cui viene selezionato ogni importatore, esposte in Quale importatore trasforma una sorgente in bozze:

  • All’interno di uno stesso nome viene eseguita la versione più alta, oppure la versione che una voce plugins.importer nomina.
  • Dove il tuo catalogo contiene un importatore con un altro nome per langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk o agent-framework, due importatori annunciano il formato, e un’importazione che non associa nessuno dei due viene rifiutata nominando entrambi, con A parse or import format is advertised by more than one plugin (Un formato di parsing o di importazione è annunciato da più di un plugin). Una voce plugins.importer che nomina quello che vuoi risolve la questione.
  • Un importatore che il tuo catalogo contiene con lo stesso nome e la stessa versione di un importatore core, con il suo modulo accanto alla sua entità, è quello che viene eseguito, letto da lì.
  • Un’entità Plugin con il nome di un importatore core e senza alcun modulo accanto nella sua cartella di catalogo — in un checkout di un catalogo che registra gli importatori pubblicati da un rilascio, ad esempio — è un’entità che nessuna importazione potrebbe eseguire, poiché il suo modulo non viene letto da nessun’altra parte; quindi non è candidata all’esecuzione, anche se le firme che registra partecipano comunque al riconoscimento di una sorgente. Alla versione del compilatore stesso viene eseguito al suo posto l’importatore core. A qualsiasi altra versione, più vecchia o più recente, viene scartata, e la scelta avviene tra gli importatori che possono essere eseguiti — a meno che una voce plugins.importer non indichi esattamente quella versione, o che nessun importatore con quel nome che possa essere eseguito dichiari il formato richiesto, come quando l’entità registra un formato che l’importatore del compilatore stesso non registra. In quel caso resta candidata secondo le regole descritte sopra, e un’importazione che la sceglie si interrompe indicando la cartella in cui va il suo modulo.

Qualunque sia l’importatore del tuo catalogo che viene scelto, il suo modulo viene letto da accanto alla sua entità, alla sua versione: un modulo posto accanto a un’entità con lo stesso nome a un’altra versione appartiene a quell’entità.

Come viene riconosciuta una sorgente

Un’importazione che non nomina il proprio formato con --format viene riconosciuta in base alle firme che ciascun importatore dichiara:

  • Langflow — una sorgente che si analizza come JSON e porta un array in data.nodes.
  • Flowise — una sorgente che si analizza come JSON, porta array in nodes e edges e non porta nulla in data.nodes.
  • n8n — una sorgente che si analizza come JSON, porta un array in nodes e un oggetto in connections, e non porta nulla in edges né in data.nodes.
  • MCP — una sorgente che si analizza come JSON, si chiama .mcp.json, claude_desktop_config.json o .cursor/mcp.json e porta un oggetto in mcpServers; una sorgente che si analizza come JSON con commenti, come lo legge Visual Studio Code, si chiama .vscode/mcp.json e porta un oggetto in servers; oppure una sorgente con qualsiasi nome che si analizza come JSON e il cui $schema è un testo che inizia con https://static.modelcontextprotocol.io/schemas/, una descrizione di server del registry. Un nome viene confrontato con la parte finale del percorso che l’importazione riceve, quindi project/.vscode/mcp.json viene riconosciuto, mentre mcp.json passato dall’interno di .vscode, o il file di un client con qualsiasi altro nome, viene importato nominando --format mcp.
  • Compose — una sorgente che si analizza come YAML, ha uno dei nomi con cui Compose legge per impostazione predefinita un file Compose o il suo file di sovrascrittura — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml, compose.override.yml, compose.override.yaml, docker-compose.override.yml o docker-compose.override.yaml — e porta un oggetto in services. Un file Compose con qualsiasi altro nome viene importato nominando --format compose.
  • Dify — una sorgente con qualsiasi nome che si analizza come YAML, porta il testo app in kind e porta qualcosa in app.mode e in version, come fa ogni applicazione che Dify esporta.
  • CrewAI — una sorgente chiamata config/agents.yaml o config/tasks.yaml che si analizza come YAML, una sorgente chiamata crew.jsonc o crew.json che si analizza come JSON con commenti e porta una lista in agents, oppure una sorgente chiamata agents/<name>.jsonc o agents/<name>.json che si analizza come JSON con commenti e porta qualcosa in role. Un progetto classico indicizza i suoi agenti e i suoi task con nomi scelti dal suo autore, quindi i suoi due file si distinguono solo dal nome.
  • LangGraph — una sorgente chiamata langgraph.json che si analizza come JSON e porta un oggetto in graphs; oppure una sorgente con qualsiasi nome che si analizza come JSON, porta un oggetto in graphs e il cui $schema è il testo https://langgra.ph/schema.json, lo schema che LangGraph pubblica per la propria configurazione. Una configurazione con un altro nome che non nomina alcuno schema viene importata nominando --format langgraph. Nessuna firma di importatore nomina un file di ambiente, quindi riconoscere una directory non ne apre alcuno.
  • Google ADK — una sorgente chiamata root_agent.yaml che si analizza come YAML e porta qualcosa in name e in instruction, come fa la configurazione di un LlmAgent, oppure un testo in agent_class e qualcosa in name, come fa quella di qualsiasi altro agente. Una configurazione con un altro nome viene importata nominando --format google-adk. Nessuna firma nomina la configurazione di un sotto-agente, che può chiamarsi in qualsiasi modo, quindi riconoscere una directory non apre alcun file YAML tranne root_agent.yaml.
  • Agent Framework — una sorgente con qualsiasi nome che si analizza come YAML, porta il testo Prompt in kind e un oggetto in model, come fa un agente dichiarativo che nomina il proprio modello; Agent Framework carica un agente dichiarativo da qualunque file la sua applicazione nomini, quindi la firma non nomina alcun file. Un agente dichiarativo che non nomina alcun modello, o che scrive il proprio tipo con un’altra combinazione di maiuscole e minuscole o come Agent, viene importato nominando --format agent-framework.

Una sorgente che corrisponde a due di esse viene rifiutata nominando entrambi i formati, e viene importata nominando quello giusto con --format. Gli importatori Langflow, Flowise, n8n e LangGraph leggono la propria sorgente tramite il parser che serve parse:json, l’importatore MCP una configurazione che elenca i propri server sotto servers tramite quello che serve parse:jsonc e ogni altra sorgente tramite quello che serve parse:json, gli importatori Compose, Dify, Google ADK e Agent Framework tramite quello che serve parse:yaml, e l’importatore CrewAI i file di un progetto classico tramite quello che serve parse:yaml e gli altri tramite quello che serve parse:jsonc: quello che serve il catalogo del tuo workspace, dove ne serve uno, e altrimenti il parser che il compilatore stesso porta con sé per quella sintassi (vedi Plugin integrati). Quindi un’importazione tramite uno qualsiasi di essi non richiede alcun parser nel tuo catalogo, e non viene scaricato nulla per un parser. Un parser che il tuo catalogo serve è quello usato, e quello del compilatore non ha alcun ruolo. Gli importatori Langflow, Flowise, n8n, Dify e Agent Framework non dichiarano alcun pattern di file, quindi ciascuno legge un solo file e un’importazione di una directory tramite uno qualsiasi di essi viene rifiutata; l’importatore MCP dichiara i quattro nomi di file dei client, quindi una directory viene letta tramite le configurazioni dei client che contiene; l’importatore Compose dichiara gli otto nomi di file Compose, quindi una directory viene letta tramite i file Compose che contiene; l’importatore CrewAI dichiara i sei nomi delle dichiarazioni di un progetto, quindi la directory di un progetto viene letta tramite le sue dichiarazioni e nient’altro; l’importatore LangGraph dichiara langgraph.json, quindi la directory di un’applicazione viene letta solo tramite la sua configurazione, e non vengono mai letti né il suo codice né un file di ambiente; e l’importatore Google ADK dichiara root_agent.yaml, quindi la directory di un’applicazione viene letta solo tramite la sua configurazione radice — le configurazioni nominate dai suoi sotto-agenti raggiungono l’importatore solo sotto il with.sources della sua associazione — e non vengono mai letti né il suo codice né il suo file di ambiente. Una firma che non nomina alcun file — quelle degli importatori Langflow, Flowise e n8n, quella dell’importatore MCP per una descrizione di server del registry, quella dell’importatore LangGraph per una configurazione che nomina il proprio schema, quella dell’importatore Dify e quella dell’importatore Agent Framework — si applica a ogni file importato da solo: un’importazione che non nomina alcun formato legge un file di questo tipo come JSON, e come YAML, per provare entrambi, qualunque sia l’importatore a cui è destinato, tramite quegli stessi parser — il compilatore li porta entrambi con sé, quindi non viene scaricato nulla per nessuno dei due. Un file che contiene un commento o una virgola finale non si analizza come JSON, quindi nessuna firma che legge JSON lo riconosce; le firme dell’importatore CrewAI per crew.jsonc, agents/<name>.jsonc e le loro varianti .json, e quella dell’importatore MCP per .vscode/mcp.json, leggono JSON con commenti, tramite il parser che il compilatore porta con sé per quella sintassi dove il tuo catalogo non ne serve alcuno.

Una sorgente che il suo parser rifiuta — per gli importatori Langflow, Flowise, n8n e LangGraph una che non è JSON, per l’importatore MCP una che non è JSON con commenti oppure, a meno che non elenchi i propri server sotto servers, non è JSON, per gli importatori Compose, Dify e Agent Framework una che non è YAML, per l’importatore CrewAI una dichiarazione che non è YAML o non è JSON con commenti, e per l’importatore Google ADK una configurazione che non è YAML — arresta l’importazione con parse-failed, il cui messaggio riporta il motivo fornito dal parser stesso. Nominare il formato non cambia nulla: l’importatore chiede l’albero della sorgente, e il rifiuto del parser è la risposta che riceve.

Come viene denominata una bozza

Ogni importer dà all’Aggregate che genera in bozza, e alla Release accanto a esso quando ne genera una, il nome <target_namespace>/<name>. La prima parte è l’impostazione target_namespace, imported a meno che tu non ne imposti un’altra. <name> è il primo dei seguenti che non sia vuoto:

  • il nome che la sorgente dà a sé stessa, nel campo in cui il suo formato lo dichiara:

    ImporterIl nome che legge
    importer/langflowil name del flusso
    importer/flowisenessuno: un export non porta un nome proprio
    importer/n8nil name del workflow
    importer/mcpil name della descrizione di un server di registry; la configurazione di un client non ne porta alcuno
    importer/composeil name di primo livello del progetto, quello di un file di override al posto di quello del file che sovrascrive, come li unisce Compose
    importer/difyil name dell’applicazione, sotto app
    importer/crewaiil name della crew in crew.jsonc o crew.json; config/agents.yaml e config/tasks.yaml non ne portano alcuno, poiché un progetto classico nomina la sua crew nel proprio programma
    importer/langgraphl’id del grafo che la configurazione dichiara, poiché una configurazione non porta un nome proprio
    importer/google-adkil name dell’agente radice
    importer/agent-frameworkil name dell’agente; il suo displayName non viene letto
  • il nome della directory passata all’importazione, per intero — my.project mantiene il suo punto, scritto my-project — come Compose nomina un progetto in base alla directory che lo contiene; aggrega import . nomina la directory in cui viene eseguito;

  • il nome del file passato da solo all’importazione, senza la sua estensione;

  • flow.

Una bozza ricavata da più sorgenti — più progetti Compose, configurazioni, alberi di agenti o server, oppure una configurazione che dichiara più grafi — prende il loro nome solo se ciascuna di esse dà un nome a sé stessa e tutti sono scritti allo stesso modo; altrimenti prende il successivo. Un nome si scrive in minuscolo, ogni sequenza di caratteri diversi dalle lettere e dalle cifre ASCII come un solo trattino, eliminando i trattini alle due estremità: Basic Prompting si scrive basic-prompting, e SupportAgent supportagent. La stessa sorgente riceve lo stesso nome a ogni importazione. Un Manifest che un’importazione genera in bozza per un target prende il nome della Release, o quello dell’Aggregate quando non viene generata alcuna Release in bozza, come descrive Cosa aggiunge un target.

Che cosa legge l’importatore Langflow

  • I nodi e gli archi sotto l’oggetto data di primo livello del flusso, data.nodes e data.edges.
  • Per ogni nodo, il suo tipo da data.type del nodo, e i suoi campi dalle voci di data.node.template il cui valore è un oggetto che porta un type. Le altre voci del template non sono campi.
  • Un campo il cui oggetto porta password: true viene generato in bozza come slot di credenziale, e ogni altro campo come campo di valore. Il nome del campo non ha alcun ruolo, e generare in bozza un nodo come Component non legge il valore di alcun campo.
  • Una nota fissata sul canvas, un nodo di tipo noteNode, non viene importata, e un arco verso un nodo che non viene importato viene scartato.
  • Generare in bozza la piattaforma che porta il flusso legge anche, dal flusso: il suo id di primo livello; il valore di ogni campo contrassegnato con password: true; il campo mcp_server di un nodo MCP Tools — il server MCP che nomina e la configurazione di quel server — oppure i campi in cui conserva invece il proprio server; ogni input che Langflow non contrassegna come credenziale ma che può contenerne una, come li elenca Valori di credenziali contenuti nel flusso; il campo in cui un nodo nomina il proprio modello, e il provider del modello su cui gira; e i campi tramite cui un nodo raggiunge l’indirizzo e la chiave di una parte, che riscrive. Che cosa generano in bozza dice che cosa diventa ciascuno.

Che cosa legge l’importatore Flowise

  • I nodi e gli archi al primo livello del flusso, nodes e edges.
  • Per ogni nodo, il suo tipo da data.name del nodo; i suoi slot di credenziale dalle voci di data.inputParams il cui type è credential, in base al loro name; e i suoi campi di valore dalle chiavi di data.inputs, tranne quelle che data.inputAnchors nomina — dove un altro nodo si collega in ingresso, cosa che l’arco tra i due registra — e tranne le credenziali.
  • Generare in bozza un nodo come Component non legge il valore di alcun campo, e il nome di una credenziale non ha alcun ruolo nel fatto che sia una credenziale.
  • Una nota fissata sul canvas, un nodo di tipo stickyNote, non viene importata, e un arco verso un nodo che non viene importato viene scartato.
  • Generare in bozza la piattaforma che porta il chatflow legge anche, da esso: il suo id di primo livello, dove è un UUID; la credenziale che un nodo conserva in data.credential; il valore di ogni input che i suoi inputParams dichiarano di tipo password; FLOWISE_CREDENTIAL_ID tra gli input di un nodo, e credential o FLOWISE_CREDENTIAL_ID all’interno di un oggetto di configurazione a qualsiasi profondità di essi; la configurazione del server nell’input mcpServerConfig di un nodo; ogni input che Flowise non contrassegna come credenziale ma che può contenerne una, come li elenca Valori di credenziali contenuti nel flusso, e il membro in cui la configurazione di un agentflow nomina il modello o lo strumento che seleziona; l’input modelName di un nodo; e il Base Path di un nodo OpenAI, il suo input basepath. Che cosa generano in bozza dice che cosa diventa ciascuno.

Che cosa legge l’importatore n8n

  • I nodes del workflow e le sue connections, al primo livello dell’esportazione.
  • Per ogni nodo, il suo name, che lo identifica — le connessioni di n8n nominano per nome i nodi che uniscono, e i nomi dei nodi di un workflow sono univoci — e il suo type, scritto per intero, con il suo package: @n8n/n8n-nodes-langchain.lmChatOpenAi, per esempio, o n8n-nodes-base.httpRequest. Un nodo senza nome è identificato dal suo id.
  • Ogni connessione che il workflow elenca è un arco, dal nodo da cui esce al nodo in cui entra, qualunque sia il suo tipo: una connessione main porta i dati da un nodo al successivo, e una connessione AI — ai_languageModel, ai_tool, ai_vectorStore, ai_embedding, ai_memory e le altre — consegna al nodo in cui entra il modello, lo strumento, lo store o la memoria che il nodo da cui esce rappresenta. In entrambi i casi il nodo in cui una connessione entra consuma il nodo da cui esce.
  • Ogni tipo di credenziale che i credentials di un nodo nominano, e ogni parametro di primo livello che n8n contrassegna come password, viene generato in bozza come slot di credenziale; ogni altro parametro di primo livello del nodo è un campo di valore. Generare in bozza un nodo come Component non legge il valore di alcun campo.
  • Una nota fissata sul canvas, un nodo di tipo n8n-nodes-base.stickyNote, non viene importata, e una connessione verso un nodo che non viene importato viene scartata.
  • Generare in bozza la piattaforma che porta il workflow legge anche, da esso: il suo id di primo livello; ogni credenziale che un nodo seleziona; ogni parametro che n8n contrassegna come password; l’indirizzo che un nodo client MCP chiama; gli header e i parametri di query che un nodo invia con una richiesta che il workflow compone, come li elenca Valori di credenziali contenuti nel flusso; e il parametro in cui un nodo modello nomina il proprio modello. Che cosa generano in bozza dice che cosa diventa ciascuno.

Che cosa generano in bozza

Ogni nodo viene valutato rispetto ai Components del catalogo del workspace stesso e a nient’altro, come descrive il socket importatore, e ogni importatore porta con sé una breve tabella che mappa i tipi di nodo comuni del suo formato — modelli di chat e di embedding, retrieval, richieste HTTP e, su Langflow, il nodo MCP Tools MCPTools, che è mappato su core/ai-tool/mcp — su Components della libreria standard. La tabella di Langflow mappa inoltre il suo componente Language Model, LanguageModelComponent, il modello di chat che i suoi flussi iniziali chiamano, su core/ai-model/openai, il modello servito dalla connessione del modello della piattaforma Langflow: il nodo gira sul provider di modelli che il suo campo provider nomina, OpenAI per impostazione predefinita, e un nodo che nomina un altro provider non viene mai collegato a quella connessione, come descrive Quali nodi diventano parti. La tabella dell’importatore n8n mappa i modelli di chat e di embedding di n8n, il suo strumento client MCP su core/ai-tool/mcp, i suoi strumenti di richiesta HTTP, il suo strumento SerpApi, i suoi vector store Qdrant, PGVector, Chroma, Milvus e Weaviate, e le sue memorie di chat Postgres e Redis. Un nodo che n8n esegue all’interno del workflow stesso — un agente, una chain, un trigger, una memoria che il workflow conserva nel proprio processo, uno strumento di codice — appartiene al workflow, e nessuna riga lo mappa. Una riga di quella tabella conta ai fini di una corrispondenza solo dove il catalogo del workspace contiene il Component che nomina. Il comando riporta una riga per ogni nodo che ha mappato, indicando che cosa ha scelto, il livello di corrispondenza e il punteggio del candidato migliore, e una riga che recita made no choice for <node id> (<node type>) per un nodo a cui non dà alcun Component proprio. Un nodo che fa riferimento a un Component del catalogo, anziché essere generato in bozza, non ha un file proprio: l’Aggregate in bozza nomina il Component.

La disposizione della bozza spetta all’impostazione layout. platform, il valore predefinito, genera in bozza la piattaforma che esegue il flusso, portando il flusso così come è stato esportato, e dà un Component proprio solo a ciascuna parte del flusso che un socket della piattaforma accetta — sulle piattaforme della libreria standard, un modello, un server MCP o un altro strumento raggiunto via HTTP, e un vector store. nodes genera in bozza ogni nodo come Component proprio.

La piattaforma che porta il flusso

Per impostazione predefinita un’importazione scrive:

  • aggregate.yaml — un Aggregate in bozza che prende il nome dal flusso, come descrive Come viene denominata una bozza. Contiene un’istanza della piattaforma che esegue il flusso — core/ai-agent/langflow, sotto la chiave langflow, per un flusso Langflow, core/ai-agent/flowise, sotto la chiave flowise, per uno Flowise, e core/ai-agent/n8n, sotto la chiave n8n, per un workflow n8n — che fa riferimento al Component del catalogo con quel nome. L’istanza porta il flusso in values.flow_definition e lo nomina nel suo valore identificativo, flow_id su Langflow, chatflow_id su Flowise e workflow_id su n8n. Ogni parte del flusso è una voce a sé accanto a essa, collegata alla piattaforma sotto gli uses dell’istanza.
  • release.yaml — una Release in bozza con lo stesso nome, che indica quell’Aggregate, con una voce per la piattaforma e una per ogni parte, che porta l’immagine della piattaforma e associa per riferimento ogni segreto di cui la bozza ha bisogno, come descrive Cosa la bozza lascia alla Release.
  • un file sotto components/ per ogni parte che genera in bozza anziché farvi riferimento, scritto come il layout nodo per nodo scrive un nodo generato in bozza.

Dato un target, l’import genera in bozza manifest.yaml accanto a essi, come descrive Cosa aggiunge un target.

Ogni nodo che non è una parte resta all’interno del flusso che la piattaforma porta e non diventa alcun Component. La sua decisione registra i candidati rispetto a cui è stato valutato e non sceglie nulla, e la sua motivazione recita kept in the flow <platform> carries, with no Component of its own:, seguita dal perché — per esempio, che nessuna riga di mapping nomina il suo tipo e che il suo candidato più vicino ha ottenuto solo un certo punteggio. Il flusso conserva gli archi tra i nodi; la bozza non ne scrive di propri.

Il chatflow Multiple Documents QnA di Flowise, esportato come Multiple Documents QnA.json e importato senza alcuna impostazione e senza target su un catalogo che contiene la piattaforma Flowise della libreria standard e i suoi Components di modello e di strumento di retrieval, viene generato in bozza come questo Aggregate, con la maggior parte del flusso omessa qui e indicata con ...:

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

Il suo modello di chat è l’unica parte collegata; i suoi due modelli di embedding restano nel flusso, poiché il socket del modello ammette una sola connessione, e i suoi strumenti retriever restano nel flusso, poiché nessun socket della piattaforma li accetta. L’importazione riporta ciascuno.

L’identificativo del flusso è quello che gli dà l’esportazione — per un flusso Langflow il suo id di primo livello, per un chatflow Flowise il suo id di primo livello dove è un UUID, e per un workflow n8n il suo id di primo livello — dove questo è composto da una a 128 lettere, cifre, ., -, _ o : e inizia con una lettera o una cifra. Dove l’esportazione non ne dà alcuno, o ne dà uno contenente qualsiasi altro carattere, la bozza scrive un UUID basato su nome derivato dal nome del formato e dal flusso così come è portato, così un flusso produce sempre un unico identificativo, e un commento sopra il valore dice che è stato derivato. Un chatflow esportato dall’editor di Flowise non porta alcun id, quindi gliene viene dato uno derivato.

Dove il catalogo del workspace non contiene alcun Component con il nome della piattaforma, la bozza nomina comunque la piattaforma e non vi collega alcuna parte: ogni nodo che sarebbe stato una parte resta nel flusso, viene riportato, e l’importazione avvisa che il catalogo non contiene un tale Component.

Quali nodi diventano parti, e dove viene collegato ciascuno

Un nodo è una parte del flusso dove una riga della tabella di mapping dell’importatore, o una voce mapping_overrides, mappa il suo tipo, oppure dove il suo candidato migliore è almeno una corrispondenza di livello medio. Un nodo MCP Tools di Langflow è una parte qualunque siano i suoi punteggi: nomina il server MCP che chiama, e quel server è la parte. Una parte diventa un Component proprio, a cui si fa riferimento o generato in bozza esattamente come decide reuse_mode, e viene collegata al primo socket della piattaforma — nell’ordine in cui la voce di catalogo della piattaforma dichiara i suoi socket — il cui selettore di label è soddisfatto dal Component della parte: le label del Component a cui fa riferimento o, per una parte che genera in bozza, quelle del suo candidato migliore dove quel candidato è almeno una corrispondenza di livello medio. Una parte il cui Component non soddisfa il selettore di alcun socket, o che non ha alcun Component da cui leggere le label, resta nel flusso, e l’importazione la riporta.

Queste regole lo restringono:

  • Un modello Langflow che nomina un altro provider non riceve alcuna connessione del modello. Un nodo LanguageModelComponent o EmbeddingModel gira sul provider di modelli che il suo campo provider nomina oppure, dove questo è vuoto, sul provider del modello che il suo campo model seleziona. La piattaforma fornisce la propria connessione del modello per un client compatibile con OpenAI, quindi un nodo che nomina un provider diverso da OpenAI — qualunque cosa vi mappino una riga di mappatura o un override — non viene mai collegato al socket model: viene collegato al socket successivo che il suo Component soddisfa, oppure resta nel flusso, con la sua decisione che non sceglie nulla e senza alcun Component generato in bozza per esso, e l’importazione lo segnala indicando il provider su cui gira. Un nodo che non seleziona alcun provider, che lo nomina tramite una variabile globale o che prende il proprio modello da un altro nodo viene collegato come qualsiasi altra parte.
  • Un socket che ammette una sola connessione è occupato da una sola parte. Su ogni piattaforma il socket model ammette una connessione, che le Recipes della piattaforma forniscono come un unico OPENAI_BASE_URL e un unico OPENAI_API_KEY. Dove vi sono collocate più parti, lo occupa la prima il cui Component porta model.aggrega.ai/capability: generative — la prima parte, dove nessuna lo porta — e ogni altra resta nel flusso, riportata insieme alla parte che occupa la connessione e a come il flusso la raggiunge così come il suo nodo è scritto.
  • Langflow raggiunge una connessione tools solo tramite un nodo MCP Tools che la nomina. La piattaforma scrive l’indirizzo di una connessione tools nella configurazione del server del nodo MCP Tools il cui campo mcp_server nomina la connessione, quindi un nodo il cui template non porta alcun campo mcp_server — qualunque sia il suo tipo, e qualunque cosa a cui una riga di mapping o una sovrascrittura lo mappi — non viene mai collegato al socket tools: viene collegato al socket successivo che il suo Component soddisfa, oppure resta nel flusso, riportato. Un nodo MCP Tools che non nomina alcun server non viene collegato ad alcun socket e viene riportato. Lo stesso vale per uno la cui configurazione del server avvia un server proprio — porta un command, o imposta la modalità Stdio — e la segnalazione che lo riguarda dice che cosa rimuovere, poiché la build della piattaforma si arresta su un nodo che nomina un server a cui nessuna connessione tools risponde.
  • Un server MCP viene collegato con il nome che il flusso gli dà. I nodi di un flusso che nominano uno stesso server raggiungono una sola parte, generata in bozza una sola volta, tramite una sola connessione. L’alias della connessione è il nome del server dove l’alias di una connessione può assumerlo — lettere, cifre, trattini e trattini bassi — e nessun’altra connessione di quel socket fornisce valori sotto lo stesso nome di variabile, cioè il suo alias in maiuscolo con ogni altro carattere scritto come trattino basso. Altrimenti la connessione assume un alias derivato dalla chiave della parte, il server del nodo viene rinominato con quell’alias nel flusso che la bozza porta, e la decisione della parte lo dice.

La decisione di una parte collegata dice a quale socket della piattaforma è collegata e tramite quale connessione, e nomina ogni socket per cui è stata scartata e il perché.

Come il flusso portato raggiunge ciascuna parte

Dove il formato lo consente, il flusso che la piattaforma porta raggiunge ciascuna parte collegata tramite la sua connessione, e la bozza scrive nel flusso ciò che glielo fa fare — il nome di una variabile, un indirizzo svuotato, oppure ciò che il nodo invierebbe al posto di ciò che la connessione fornisce, svuotato, e mai un valore. Si tratta di collegamento, non della rimozione di un valore di credenziale: la bozza lo scrive qualunque cosa dica l’impostazione empty_credentials, poiché un valore mantenuto lì sovrascriverebbe ciò che la connessione fornisce.

  • Un nodo MCP Tools di Langflow. La piattaforma scrive l’indirizzo che la sua connessione fornisce nella configurazione del server del nodo e, dove la connessione porta una credenziale, il nome della variabile che la contiene sotto l’header che lo strumento pubblica. La bozza scrive vuoto l’indirizzo che l’esportazione conteneva lì, così il flusso non ne conserva alcuna copia, e lascia l’indirizzo del server — infra.endpoint della parte — alla Release. Langflow invia il campo headers del nodo stesso con precedenza sugli header della configurazione del suo server, quindi la bozza scrive vuoto l’intero valore di quel campo mantenendone il tipo — un oggetto come {}, una lista come [], un testo come stringa vuota — poiché un header mantenuto con il valore svuotato verrebbe comunque inviato, mentre un oggetto o una lista vuoti non sovrascrivono nulla.

  • Un nodo di modello o di vector store di Langflow. La piattaforma fornisce una connessione del modello come OPENAI_BASE_URL e OPENAI_API_KEY, e una connessione di vector store come variabili denominate in base al suo alias, che Langflow legge tramite un campo che nomina una variabile globale: un campo il cui oggetto porta load_from_db: true contiene come valore il nome della variabile, e Langflow legge la variabile globale con quel nome, oppure la variabile d’ambiente con quel nome dove non ne è memorizzata alcuna. La bozza scrive ciascuno di questi campi con il nome della variabile e load_from_db: true:

    • il campo openai_api_base di un nodo OpenAIModel, come OPENAI_BASE_URL, e il suo api_key, come OPENAI_API_KEY;
    • il campo openai_api_base di un nodo OpenAIEmbeddings, come OPENAI_BASE_URL, e il suo openai_api_key, come OPENAI_API_KEY;
    • il campo api_key di un nodo LanguageModelComponent, come OPENAI_API_KEY;
    • il campo api_base di un nodo EmbeddingModel, come OPENAI_BASE_URL, e il suo api_key, come OPENAI_API_KEY;
    • il campo pg_server_url di un nodo pgvector, come AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING, dove <ALIAS> è l’alias della connessione in maiuscolo, con ogni carattere diverso da una lettera o da una cifra scritto come trattino basso.

    Un nodo LanguageModelComponent o EmbeddingModel gira su uno tra diversi provider di modelli — quello che il suo campo provider nomina oppure, dove questo è vuoto, il provider del modello che il suo campo model seleziona — e consegna la sua chiave a quel provider. La piattaforma fornisce la connessione del modello per un client compatibile con OpenAI, quindi un nodo di questo tipo viene scritto con le variabili solo dove gira su OpenAI. Uno che gira su un altro provider non viene mai collegato, come sopra; uno che non ne seleziona alcuno, che nomina il proprio provider tramite una variabile globale o che prende il proprio modello da un altro nodo viene scritto senza nessuna di esse, così la bozza non indirizza mai un altro provider verso la chiave della connessione. Dove nessun campo di un nodo di questo tipo fornisce l’indirizzo della sua API — un nodo LanguageModelComponent non ne contiene alcuno per OpenAI, e il campo api_base di un nodo EmbeddingModel può mancare, o essere vuoto dove non può nominare una variabile — il client OpenAI su cui gira prende OPENAI_BASE_URL dall’ambiente, quindi il nodo raggiunge comunque l’indirizzo che la piattaforma fornisce.

    Il client di un nodo OpenAIEmbeddings invia i suoi default_headers con precedenza su quelli che costruisce dalla chiave, e unisce il suo default_query alla query dell’indirizzo che chiama, con precedenza su di essa, quindi su un nodo di questo tipo che la bozza collega l’intero valore di ciascuno viene scritto vuoto mantenendone il tipo, come lo sono gli headers di un nodo MCP Tools.

    Un campo che l’esportazione scrive senza entrambi quei membri non viene riscritto — un campo di credenziale tra questi viene portato com’è scritto, oppure scritto vuoto dove l’impostazione lo chiede, come più sotto. Dove quel campo è quello che porta l’indirizzo della parte — e, per un nodo LanguageModelComponent o EmbeddingModel, ne fornisce uno —, dove un nodo di questo tipo non gira su OpenAI, o dove il nodo è di qualsiasi altro tipo, l’importazione riporta la parte come raggiunta all’indirizzo che il flusso o i valori predefiniti del suo componente forniscono.

  • Un nodo OpenAI di Flowise. Il client OpenAI su cui Flowise esegue un nodo chatOpenAI o openAIEmbeddings legge OPENAI_BASE_URL e OPENAI_API_KEY dall’ambiente dove il Base Path del nodo è vuoto e il nodo non seleziona alcuna credenziale, quindi la bozza scrive vuoto un Base Path che l’esportazione contiene, e scrive vuota anche la credenziale che il nodo seleziona, in data.credential. Quel client invia gli header predefiniti del nodo, i suoi baseOptions, con precedenza sull’header che costruisce dalla chiave, quindi la bozza ne scrive vuoto l’intero valore mantenendone il tipo. Un nodo di modello di qualsiasi altro tipo viene riportato come raggiunto all’indirizzo che il chatflow o i suoi valori predefiniti forniscono.

  • Uno strumento o un vector store di Flowise. Un chatflow legge l’indirizzo che la piattaforma fornisce per uno di essi — AGGREGA_TOOL_<ALIAS>_URL o AGGREGA_VECTOR_STORE_<ALIAS>_URL — solo tramite una variabile Runtime con quel nome, che nulla crea all’avvio. La bozza non scrive nulla per esso, e l’importazione riporta il passaggio che fa sì che il chatflow lo legga: creare la variabile Runtime nella pagina Variables di Flowise e leggerla nel nodo come $vars.<name>.

  • Qualsiasi nodo n8n. La piattaforma fornisce una connessione del modello come OPENAI_BASE_URL e OPENAI_API_KEY, e una connessione tools o di vector store come AGGREGA_TOOL_<ALIAS>_URL o AGGREGA_VECTOR_STORE_<ALIAS>_URL, mentre un nodo n8n raggiunge un modello, uno store o un servizio all’indirizzo fornito dalla credenziale memorizzata che seleziona, o all’indirizzo contenuto nei suoi parametri, e un workflow legge una variabile d’ambiente solo tramite un’espressione che legge $env, che la piattaforma rifiuta a meno che l’Aggregate non imposti values.allow_env_access_in_nodes a true. La bozza lascia quel valore al suo valore predefinito, false, poiché impostarlo permette a ogni workflow, e a ogni utente che può modificarne uno, di leggere ogni variabile dell’ambiente della piattaforma, comprese le credenziali fornite. Quindi la bozza non scrive nulla nel workflow per una connessione, e ogni parte collegata viene riportata come raggiunta in un modo diverso che tramite essa. Un nodo client MCP raggiunge il suo server all’indirizzo che il workflow contiene — come l’esportazione lo ha scritto, o nessuno dove l’impostazione empty_credentials lo scrive vuoto, come più sotto — e l’indirizzo del server stesso — infra.endpoint della parte — viene lasciato alla Release.

Dove il flusso viene portato, ogni parte collegata viene riportata con quale di questi casi vale: part-reads-connection dove il flusso raggiunge la parte tramite la sua connessione, e part-address-in-flow dove la raggiunge in un modo diverso che tramite la sua connessione — a un indirizzo che il flusso contiene, o a uno fornito dai valori predefiniti del suo componente. La decisione della parte dice lo stesso.

Un nodo che la bozza non collega ad alcun socket può comunque essere raggiunto da una connessione che la bozza collega, così come il nodo è scritto: un client OpenAI senza un indirizzo e una chiave propri legge dal proprio ambiente le variabili OPENAI_BASE_URL e OPENAI_API_KEY che la piattaforma fornisce per la connessione del modello. Dove ciò avviene, la bozza scrive il nodo come scriverebbe un nodo collegato, così nulla di ciò che contiene viene inviato al posto di ciò che la connessione fornisce, e lo riporta con part-reads-connection:

  • un nodo OpenAIEmbeddings di Langflow il cui campo di indirizzo nomina la variabile OPENAI_BASE_URL che la piattaforma fornisce, letta come variabile globale, mentre una parte è collegata al socket del modello: i suoi default_headers e default_query;
  • un nodo chatOpenAI o openAIEmbeddings di Flowise il cui Base Path è vuoto e che non seleziona alcuna credenziale, e la configurazione di un tale modello che un nodo di agentflow conserva tra i suoi input, mentre una parte è collegata al socket del modello: i suoi baseOptions.

Su qualsiasi altro nodo questi valori non sono collegamento: vengono portati come sono scritti, oppure scritti vuoti dove l’impostazione lo chiede, come dice la sezione successiva.

Valori di credenziali contenuti nel flusso

Prima che il flusso venga portato, l’importazione individua ogni valore al suo interno che può contenere una credenziale, nei punti elencati più sotto, ciascuno di uno di tre tipi: ciò che un formato contrassegna come credenziale; un membro della configurazione di un server MCP, ovunque un formato ne conservi una; e un input che un formato contrassegna come non credenziale ma che può comunque contenerne una — header di richiesta, parametri di query, un’intera richiesta scritta come riga di comando, un input che contiene una credenziale sotto il nome di una credenziale.

Per impostazione predefinita l’importazione non ne scrive vuoto nessuno: il flusso viene portato così com’è stato esportato, e ogni valore individuato che contiene qualcosa — non una stringa vuota e non null — viene nominato in un avviso credential-carried, tramite il suo nodo e il suo campo — un header o un parametro di query tramite il suo nome — mai tramite il suo valore o una qualsiasi parte di esso, insieme al valore dell’impostazione empty_credentials che lo scrive vuoto. L’impostazione attiva la rimozione: marked scrive vuoto ciò che un formato contrassegna come credenziale e ogni membro della configurazione di un server MCP; all scrive vuoti anche gli input contrassegnati come non credenziali. Ogni valore che scrive vuoto viene riportato con credential-emptied, tramite il suo nodo e il suo campo, mai tramite il suo valore; un valore già vuoto, o null, viene lasciato com’è e non viene riportato. Un valore che l’impostazione non accetta arresta l’importazione, che non genera nulla in bozza, anziché valere come none.

Un valore individuato che è un riferimento a una variabile e nient’altro non contiene alcun valore proprio: il nome nudo di una variabile, ${NAME} — compresa una variabile predefinita come ${workspaceFolder} o ${userHome} — oppure una delle forme che i client MCP definiscono, ${env:NAME} e ${input:id}. Qualunque cosa dica l’impostazione, viene portato com’è scritto e non viene nominato in alcun avviso, in qualunque formato sia il flusso, come ne scrive uno l’importatore MCP. Lo stesso vale per un membro che è un unico riferimento all’interno di un valore che un formato conserva come testo, come un mcpServerConfig di Flowise scritto come testo JSON, oppure header e parametri di query contenuti come oggetto JSON in un testo su Flowise e n8n: scritto vuoto, il testo mantiene quel membro com’è scritto.

Un riferimento che porta del testo dopo un operatore contiene quel testo, che può essere una chiave, che l’operatore sia preceduto o meno da due punti: un valore predefinito, ${NAME:-value} o ${NAME-value}; un’alternativa, ${NAME:+value} o ${NAME+value}; un messaggio, ${NAME:?message} o ${NAME?message}; un’assegnazione, ${NAME:=value} o ${NAME=value}. Viene individuato come qualsiasi altro valore — portato e nominato in un avviso credential-carried per impostazione predefinita, scritto vuoto dove l’impostazione lo chiede per il suo tipo — e lo stesso vale per qualsiasi altro testo all’interno di ${…}, come ${config:name}, e per il testo accanto a un riferimento, come --key=${NAME}.

Ciò che la bozza scrive affinché un nodo raggiunga la sua connessione — un indirizzo scritto vuoto, il nome di una variabile, una credenziale selezionata o header predefiniti scritti vuoti, come descrive Come il flusso portato raggiunge ciascuna parte — è collegamento: viene scritto qualunque cosa dica l’impostazione, riportato con il modo in cui il nodo raggiunge la sua connessione, e mai riportato come valore di credenziale. Ciò che si trova al di fuori di ogni punto elencato più sotto spetta all’autore da rivedere, come dice la fine di questa sezione.

Ciò che un formato contrassegna come credenziale — scritto vuoto con marked e all:

  • Langflow — il valore di ciascun campo del template contrassegnato con password: true, compreso un campo che contiene il nome di una variabile globale, a meno che la bozza non scriva quel campo con il nome della variabile che la piattaforma fornisce, come sopra.
  • Flowise — la credenziale che un nodo conserva in data.credential, che il suo parametro di credenziale seleziona; il valore di ciascun input che i suoi inputParams dichiarano di tipo password; e FLOWISE_CREDENTIAL_ID tra gli input di un nodo, e credential o FLOWISE_CREDENTIAL_ID all’interno di un oggetto di configurazione a qualsiasi profondità di essi, come un agentflow conserva quello di un modello o di uno strumento.
  • n8n — l’id di ciascuna credenziale memorizzata che un nodo seleziona, in credentials.<type>.id. Un’esportazione n8n conserva una credenziale come riferimento, mai il suo valore, e il name del riferimento non viene individuato: n8n, importando il workflow su un’altra istanza, risolve una credenziale il cui id non possiede tramite il suo tipo e il suo nome. Una credenziale che un’esportazione più vecchia seleziona solo tramite il nome nomina una credenziale e non ne contiene alcuna, e non viene individuata. E il valore di ciascun parametro che n8n contrassegna come password nelle definizioni dei suoi nodi di base — il secret del nodo Crypto, per esempio, o la password dei nodi che creano un utente — ovunque si trovi tra i parametri del nodo, con un nodo usato come strumento di un agente letto come il nodo che è.

La configurazione di un server MCP — scritta vuota con marked e all:

  • La configurazione mcp_server di un nodo MCP Tools di Langflow, e il mcpServerConfig di un nodo Flowise, scritti come testo JSON o come oggetto: ciascun valore di header, che gli header siano un oggetto, righe di una chiave e un valore oppure oggetti uniti per intero, con un elemento di qualsiasi altro tipo individuato per intero; ciascun valore d’ambiente; l’indirizzo del server; il comando; e ogni argomento. Nessuno dei due formati contrassegna un indirizzo, un comando o un argomento come credenziale, e ciascuno può contenere una chiave — un indirizzo nella sua parte utente, nel suo percorso o nella sua query — quindi vengono individuati anche tutti e tre, su entrambi i formati. Scritti vuoti, il comando e ciascun argomento mantengono i propri membri, così una configurazione che avvia un proprio server viene ancora letta come tale. Dove un nodo MCP Tools di Langflow è collegato a una connessione tools, il suo indirizzo è collegamento, come sopra, e non viene mai riportato come valore di credenziale. Una configurazione Flowise scritta come testo che non si legge come oggetto JSON viene individuata per intero, poiché nulla al suo interno può essere individuato.
  • Un nodo MCP Tools di Langflow che non porta alcun campo mcp_server conserva invece il proprio server in campi propri — l’indirizzo in sse_url, gli header in headers_input, l’ambiente in env e l’intera riga di comando, argomenti compresi, in command — e Langflow non contrassegna nemmeno nessuno di essi come credenziale, quindi ciascun valore di header, ciascuna voce di env, l’indirizzo e la riga di comando vengono individuati, mantenendo i loro campi e le loro voci quando vengono scritti vuoti. Dove env è una lista, ciascuna voce viene riportata tramite la sua posizione, poiché il nome di una variabile e il suo valore condividono un unico testo. Un nodo di questo tipo non nomina alcun server MCP, quindi non viene mai collegato a una connessione tools.
  • Il campo headers proprio di un nodo MCP Tools di Langflow, che Langflow invia al server con precedenza sugli header della sua configurazione, su un nodo che la bozza non collega: il suo intero valore, scritto vuoto mantenendone il tipo, come su un nodo collegato, e riportato una sola volta, come headers.
  • I componenti MCP Tools (SSE) e MCP Tools (stdio) di Langflow, che Langflow contrassegna come deprecati, conservano il proprio server in un unico campo ciascuno — un nodo MCPSse il suo indirizzo in url, un nodo MCPStdio la sua intera riga di comando, argomenti compresi, in command — individuato per intero. Nessuno dei due nomina un server MCP, quindi nessuno dei due viene collegato a una connessione tools.
  • Un nodo client MCP di n8n — l’MCP Client Tool che un agente chiama, il nodo MCP Client, o un client di un server che il registry di n8n elenca — conserva l’indirizzo del server nel suo parametro endpointUrl, o sseEndpoint nella sua prima versione, e i suoi header solo come credenziali che seleziona; l’indirizzo viene individuato per intero, collegato o meno.

Un input che un formato contrassegna come non credenziale — scritto vuoto solo con all:

  • Header di richiesta — su Langflow, gli headers di un nodo APIRequest, URLComponent, CloudflareWorkersAIEmbeddings o ConfluentKafkaProducer e gli api_headers di un nodo DoclingRemote; su Flowise, gli headers di un nodo httpAgentflow, getApiChain, postApiChain, openApiChain, apiLoader, openAPIToolkit o searXNG, i requestsGetHeaders, requestsPostHeaders, requestsPutHeaders e requestsDeleteHeaders degli strumenti Requests, e i baseOptions — gli header predefiniti che il client di un modello invia — di un nodo azureChatOpenAI, azureOpenAIEmbeddings, chatCerebras, chatOpenAICustom, openAIEmbeddingsCustom, chatOpenRouter, chatSambanova o openAI; su n8n, i headerParameters, jsonHeaders, headerParametersUi e headerParametersJson di un nodo n8n-nodes-base.httpRequest — la sua versione attuale conserva i primi due, le sue versioni precedenti gli altri due — e dello stesso nodo usato come strumento di un agente, i parametersHeaders e jsonHeaders di un nodo @n8n/n8n-nodes-langchain.toolHttpRequest, e i headerParametersUi di un nodo n8n-nodes-base.graphql. Il nome di un header non porta alcun segreto, quindi viene individuato il valore di ciascun header e ne viene mantenuto il nome, qualunque forma assumano gli header: un oggetto di nomi associati a valori, righe di una chiave e un valore — su n8n, righe di un name e un value — oppure oggetti che Langflow unisce per intero agli header. Ciascun header viene riportato tramite il suo nome. Un elemento di una lista che non è una riga di header viene individuato per intero e riportato tramite la sua posizione. Gli header scritti come testo vengono individuati per intero, tranne su Flowise e n8n dove il testo contiene gli header come oggetto JSON: lì, scritto vuoto, il testo viene riscritto sul posto, con ogni valore vuoto, e riportato una sola volta con i nomi degli header che contiene. Un testo n8n che inizia con = è un’espressione che n8n valuta quando il workflow viene eseguito, e viene individuato per intero. Quando vengono scritti vuoti, lo sono tutti i valori, compresi quelli degli header che non contengono alcun segreto come User-Agent, quindi una richiesta importata viene inviata con essi vuoti finché il suo autore non li ripristina.
  • Parametri di query — su Langflow, i query_params di un nodo APIRequest o GoogleSerperAPI e i search_params di un nodo SerpAPI, Serp, SearchAPI o SearchComponent; su Flowise, i queryParams di un nodo httpAgentflow e i customParameters di un loader searchApi; su n8n, i queryParameters, jsonQuery, queryParametersUi e queryParametersJson di un nodo n8n-nodes-base.httpRequest, usato come strumento o meno, i parametersQuery e jsonQuery di un nodo @n8n/n8n-nodes-langchain.toolHttpRequest, e i queryParameters e queryParametersJson che un nodo n8n-nodes-base.facebookGraphApi conserva tra le sue options. Ciascuno viene inviato come query di una richiesta, e un parametro di query può contenere una chiave — alcune API di ricerca accettano la propria come api_key nella query — quindi ciascuno viene individuato come gli header: ciascun valore, mantenendone il nome, qualunque forma assumano i parametri, e ciascuno riportato tramite il suo nome; i parametri scritti come testo vengono individuati per intero, tranne su Flowise e n8n dove il testo li contiene come oggetto JSON, che, scritto vuoto, viene riscritto sul posto e riportato una sola volta con i nomi che contiene. Quando vengono scritti vuoti, lo sono tutti i valori, compresi quelli dei parametri che non contengono alcun segreto, quindi una richiesta importata viene inviata con essi vuoti — oppure, da un nodo HTTP di Flowise, che non invia alcun parametro il cui valore è vuoto, senza di essi — finché il suo autore non li ripristina.
  • Header predefiniti e una query predefinita su un nodo OpenAI che nessuna connessione raggiunge — i default_headers e il default_query di un nodo OpenAIEmbeddings di Langflow, e i baseOptions di un nodo chatOpenAI o openAIEmbeddings di Flowise, ovunque si trovi il nodo, compresa la configurazione del modello che un agentflow seleziona, dove la bozza non collega il nodo né trova una connessione che lo raggiunga così come è scritto; dove invece lo fa, sono collegamento, come sopra. Ciascuno viene individuato per intero e, scritto vuoto, mantiene il proprio tipo — un oggetto come {}, una lista come [], un testo come stringa vuota — e viene riportato una sola volta.
  • Un’intera richiesta scritta come riga di comando — il curl_input di un nodo APIRequest di Langflow e il curl di un nodo Webhook, individuati per intero, compreso il valore predefinito del Webhook. Nessuno dei due viene letto quando il flusso viene eseguito: il primo si limita a compilare i campi del nodo nell’editor, il secondo mostra un esempio.
  • Un input che contiene una credenziale sotto il nome di una credenziale — l’api_key di un nodo OlivyaComponent di Langflow, il verification_token di ogni componente Composio e il mem0_config di un nodo mem0_chat_memory, il cui intero valore mantiene il proprio tipo quando viene scritto vuoto; e il webhookSecret e il callbackSecret di un nodo startAgentflow di Flowise e il bearerToken di un nodo teradataMCP. Ciascuno viene individuato per intero. Un input il cui nome somiglia soltanto a una credenziale — il nome di una chiave memorizzata altrove, un nome utente o un’opzione che il componente dichiara come non segreta — non viene individuato.

A parte i valori che l’impostazione scrive vuoti, ciò che la bozza scrive affinché il flusso raggiunga le sue parti, gli handle di un arco di Langflow, scritti come li scrive l’editor di Langflow, e i ritorni a capo scritti come avanzamenti di riga descritti più sotto, il flusso viene portato così com’è stato esportato: senza nulla di tutto ciò, byte per byte.

Una connessione nella bozza non porta alcun valore di credenziale: la Release in bozza associa per riferimento quella che ciascuna connessione presenta, come descrive Cosa la bozza lascia alla Release.

Ogni valore che l’impostazione lascia com’è scritto raggiunge la bozza, e l’autore lo rivede, guidato dagli avvisi credential-carried. Nemmeno il resto di un flusso è raggiunto da alcuna regola su un campo, quindi l’autore rivede anche questo prima di condividere una bozza: il codice proprio di un componente, che il flusso porta e in cui un componente personalizzato può contenere una chiave; gli input che l’editor aggiunge a un nodo oltre a quelli che il suo componente dichiara; il corpo con cui viene inviata una richiesta, come quello di un nodo APIRequest o httpAgentflow, che può contenere un token; gli argomenti che un nodo passa al client del suo modello o a un loader come un unico oggetto proprio, come i model_kwargs di un nodo EmbeddingModel di Langflow o gli additionalInputs di un nodo replicate di Flowise, che possono contenere una chiave sotto qualsiasi nome; un indirizzo diverso da quello di un server MCP, che può contenere una chiave nella sua parte utente o nella sua query; il codice di un nodo Code di n8n, e gli header o la query di un nodo che invia una richiesta che l’importatore non elenca sopra; e il testo libero come un prompt o un messaggio.

Ciò che la bozza lascia alla Release

La Release in bozza porta, sulla voce della piattaforma e su quella di ogni parte, ciò che il flusso non può fornire:

  • L’immagine della piattaforma, come infra.image: l’immagine scelta dall’importer stesso, alla versione che le Recipes del catalogo per la piattaforma notoriamente eseguono — langflowai/langflow:1.6.0, flowiseai/flowise:3.1.3 e n8nio/n8n:1.110.1 — sotto un commento che lo dice. L’import non la alza né la abbassa mai per seguire la sorgente; dove l’export indica una versione diversa della piattaforma, come fa il last_tested_version di un flusso Langflow, il commento la nomina.
  • La porta su cui è pubblicata la piattaforma, come infra.published_port, solo con --target compose: 7860 per Langflow, 3000 per Flowise e 5678 per n8n, le porte su cui ciascuna serve, che la sua Recipe Compose pubblica sull’indirizzo di loopback dell’host, 127.0.0.1. Il commento sopra di essa dice che la porta è raggiungibile solo da questa macchina, da qualsiasi processo in esecuzione su di essa, e che eliminare la riga mantiene il servizio interno. Un secondo flusso di uno stesso import prende la porta successiva non presa da uno precedente. Con qualsiasi altro target, o senza target, non viene scritta.
  • Il segreto proprio della piattaforma e la credenziale di ogni connessione a un modello, associati per riferimento e mai come valore: su Langflow, lo slot admin_password, letto finché values.require_authentication resta true; su Flowise, lo slot owner_password, obbligatorio finché values.flow_definition è impostato; e, dove una parte è collegata al socket model della piattaforma, la credential su quella connessione. La piattaforma n8n non accetta alcun segreto proprio. Il modo in cui ciascuno viene associato dipende dal target, come descrive Segreti, per ogni target.
  • Ogni valore che nessuna sorgente contiene, scritto come stringa vuota sotto un commento che dice di che cosa si tratta: su Flowise, infra.owner_email, l’email dell’account del proprietario, obbligatoria finché values.flow_definition è impostato; e l’indirizzo di ogni server MCP collegato alla piattaforma, infra.endpoint della sua parte. Ciascuno è un valore che l’import deve, a cui si risponde come descrive Il file delle risposte dell’import.

La credenziale che presenta una connessione a uno strumento o a un vector store non viene generata in bozza: la credenziale di una tale connessione arresta la build dove lo strumento non pubblica alcun header in cui inviarla, quindi un commento sopra la voce della piattaforma la nomina, perché tu la associ dove lo strumento ne accetta una.

Segreti, per ciascun target

Con --target helm, ciascun segreto è un core/referenced-secret il cui origin è il nome di un Secret Kubernetes già presente nel namespace, che contiene il valore sotto la chiave dati value. Il nome non spetta ad alcuna sorgente fornirlo, quindi viene scritto vuoto sotto un commento che dice che cosa contiene, e rientra tra i valori dovuti dall’importazione; il Manifest generato in bozza mappa core/referenced-secret su helm/k8s-existing-secret.

Su ogni altro target, e senza target, ciascun segreto è un core/secret-value il cui origin è un riferimento a una variabile — ${LANGFLOW_ADMIN_PASSWORD}, ${FLOWISE_OWNER_PASSWORD} e ${OPENAI_API_KEY} per la credenziale della connessione a un modello — che un target che sostituisce i riferimenti a variabili, come fa Docker Compose all’avvio dello stack, legge dall’ambiente, così nessun file contiene il valore e non è dovuto nulla per esso. Il chatflow di Flowise visto sopra, importato senza target, viene generato in bozza con questa Release:

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

Senza target deve due valori, spec.manifest e infra.owner_email; con --target compose, la sola email del proprietario; con --target helm, l’email del proprietario e i nomi dei due Secret Kubernetes.

Sul target compose, un segreto che la sola Release associa arriva sotto un’unica chiave, value, quindi la password del proprietario o dell’amministratore e la credenziale di una connessione arriverebbero entrambe sotto di essa. Per questo l’Aggregate dichiara ciascuna con una chiave propria dove la piattaforma ammette una connessione: owner_password con la chiave OWNER_PASSWORD su Flowise, admin_password con la chiave LANGFLOW_SUPERUSER_PASSWORD su Langflow e la credential della connessione al modello con la chiave OPENAI_API_KEY su tutte e tre le piattaforme, ciascuna sotto un commento che ne spiega il motivo. Con --target compose queste righe vengono scritte attive; senza target vengono scritte commentate, come nell’esempio sopra, perché tu tolga il commento se esegui la build per compose; con qualsiasi altro target non vengono scritte. La Release associa l’origine di ciascuno slot, nominando lo stesso tipo o nessuno.

Con l’impostazione attach_egress_allowlist a true, l’istanza della piattaforma dichiara anche la Feature core/egress-allowlist della libreria standard sotto features, come egress-allowlist, così la piattaforma si connette solo ai componenti che le sue connessioni raggiungono, ai propri pod e al DNS del cluster — la controparte in uscita di un arco uses come chiamata dichiarata. L’Aggregate dichiara il tipo dell’associazione e nient’altro, poiché l’associazione di un Aggregate non porta alcun infra, e la Release generata in bozza non ne scrive nulla: il commento sopra la voce della piattaforma nomina, sotto features.egress-allowlist.infra, control_plane_present, che l’operatore imposta a true per affermare che il plugin di rete del cluster applica la policy di rete, senza la quale affermazione la build si arresta; admitted_destinations, un elenco che contiene, per ogni connessione la cui destinazione il cluster non esegue, come un modello ospitato, una voce che nomina la destinazione e un intervallo di indirizzi, senza il quale la build si arresta nominando quella connessione; e aggrega.ai/namespace per il confine che contiene la piattaforma, poiché la policy viene collocata nel namespace dei suoi carichi di lavoro e la build si arresta dove questi non vengono emessi in alcun namespace. Nessuna di queste chiavi viene scritta vuota, quindi nessuna è tra i valori dovuti dall’importazione. La decisione di ciascuna parte collegata dice che l’associazione ammette la sua connessione, e l’importazione riporta l’associazione come feature-attached. Compose non ha policy di rete, quindi una build compose di una bozza di questo tipo si arresta nominando l’associazione; dove la piattaforma ammette una connessione, le righe compose descritte sopra vengono scritte all’interno del blocco features dell’istanza, senza una seconda chiave features.

Il modello che una parte serve

Una parte a cui la bozza fa riferimento il cui Component dichiara un valore chiamato model — come fa, e richiede, ogni Component di modello della libreria standard — viene scritta con il nome del modello che il suo nodo seleziona, come values.model:

  • Langflow — il model_name di un nodo OpenAIModel o AnthropicModel; il model di un nodo OpenAIEmbeddings; e la sovrascrittura model_name di un nodo LanguageModelComponent o EmbeddingModel dove è impostata, e altrimenti il modello che il suo campo model seleziona.
  • Flowise — il modelName di un nodo chatOpenAI, chatAnthropic o openAIEmbeddings.
  • n8n — il parametro model di un nodo di chat, di completion o di embedding che la tabella dell’importatore mappa, oppure il suo modelName sui nodi Google Gemini e Vertex, scritto come nome o come valore del selettore in cui lo conservano i nodi più recenti di n8n. n8n omette da un’esportazione un parametro impostato al suo valore predefinito, quindi un nodo che mantiene il modello predefinito non ne nomina alcuno nell’esportazione.

Una Release non può scrivere un valore. Quindi, dove il nodo non nomina alcun modello che la bozza possa scrivere — non ne seleziona alcuno, lo nomina tramite una variabile globale o un’espressione letta solo quando il flusso viene eseguito, lo prende da un altro nodo collegato a esso, oppure è di un tipo il cui campo del modello l’importatore non legge — un commento all’interno della parte lascia values.model all’autore, e l’importazione lo riporta con model-not-named. Una parte generata in bozza viene scritta senza alcun valore.

Come il flusso viene scritto nella bozza

Il flusso viene scritto come blocco letterale YAML il cui chomping mantiene le interruzioni di riga finali, così values.flow_definition si rilegge come il testo stesso del flusso. Il testo di un Aggregate viene letto come template, quindi ogni {{ che il flusso contiene — un chatflow Flowise scrive {{<node id>.data.instance}} per ogni connessione tra due nodi — viene scritto come {{"{{"}}, che l’interpolazione riconverte nelle due graffe, come descrive Testo che contiene le proprie doppie graffe. Il nome di un modello viene scritto allo stesso modo.

Un blocco letterale non può portare ogni carattere così come è scritto:

  • Un ritorno a capo — di una coppia CR LF, o isolato — viene scritto come un unico avanzamento di riga. Un documento JSON ne contiene uno solo tra i suoi token, dove qualsiasi spazio bianco si legge allo stesso modo, quindi la piattaforma legge lo stesso flusso. L’importazione riporta quanti sono con carriage-returns-rewritten.
  • Qualsiasi altro carattere che un blocco letterale non può portare impedisce che il flusso venga portato: un carattere di interruzione di riga — U+0085, U+2028 o U+2029; un carattere di controllo diverso dalla tabulazione e dall’avanzamento di riga — da U+0000 a U+001F, U+007F e da U+0080 a U+009F; i non-caratteri U+FFFE e U+FFFF; e un byte che non fa parte di una sequenza UTF-8. values.flow_definition viene allora lasciato non impostato, con un commento che lo dice, il resto viene generato in bozza, e l’importazione riporta definition-not-carried per ogni tipo di carattere, con quanti ne contiene il flusso e la riga e la colonna del primo.

Il flusso non viene portato nemmeno dove un valore che la bozza scrive vuoto o di nuovo non si trova nei byte dell’esportazione nel punto in cui il suo albero analizzato lo contiene, e l’importazione riporta definition-not-carried nominando la posizione di quel valore. L’identificativo del flusso è allora il suo proprio, dove la bozza può portarlo, e altrimenti uno derivato dagli identificativi dei nodi del flusso.

Nodo per nodo

Con layout: nodes, un’importazione genera in bozza ogni nodo del flusso come Component proprio, e scrive:

  • aggregate.yaml — un Aggregate in bozza che prende il nome dal flusso, come descrive Come viene denominata una bozza, e che compone i nodi del flusso: una voce per ciascuno, e ogni arco del flusso come connessione uses del nodo che alimenta, con il socket e l’alias chiamati entrambi come la chiave del nodo che la alimenta, così un nodo alimentato da più nodi dà a ogni connessione un alias proprio.
  • un file sotto components/ per ogni nodo che genera in bozza — un Component in bozza chiamato <target_namespace>/<category>/<name>, con il nome preso dal tipo del nodo, alla versione 0.1.0, con i suoi campi di valore come campi stringa di un oggetto values chiuso e i suoi campi di credenziale come slot di credenziale obbligatori la cui consegna è decisa da una Recipe.
  • release.yaml — una Release in bozza con lo stesso nome, che nomina quell’Aggregate, con una voce per ciascun nodo.

Il flusso stesso non viene portato, e non viene letto il valore di alcun campo.

Portare il flusso esportato stesso

La bozza predefinita porta il flusso: l’istanza della piattaforma accetta l’esportazione come values.flow_definition, scritta come descrive Come il flusso viene scritto nella bozza. Un autore che scrive a mano un flusso in un Aggregate — in una bozza disposta nodo per nodo, o in un proprio Aggregate — lo scrive allo stesso modo. Un Component che esegue un flusso così come è stato creato accetta l’esportazione come valore — flow_definition su core/ai-agent/langflow e core/ai-agent/flowise della libreria standard — e il testo di un Aggregate viene letto come template, quindi le doppie graffe che l’esportazione contiene verrebbero lette come azioni di template: un chatflow Flowise scrive {{<node id>.data.instance}} per ogni connessione tra due nodi, un prompt Flowise nomina una variabile come {{question}}, e un’esportazione Langflow porta il codice sorgente dei suoi componenti, dove le graffe possono comparire anch’esse. Scrivi ogni {{ dell’esportazione come {{"{{"}}, all’interno di uno scalare a blocco, e l’interpolazione ripristina il testo dell’esportazione prima che le Recipes del Component lo leggano; Testo che contiene le proprie doppie graffe descrive il perché. Un valore di credenziale che l’esportazione contiene va in un segreto che la Release associa, non nell’Aggregate: scrivilo vuoto, come fa la bozza dove l’impostazione empty_credentials glielo chiede.

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

L’importatore MCP

importer/mcp legge i server MCP che la configurazione di un client MCP elenca, oppure l’unico server che la descrizione di un server del registry MCP descrive, e genera in bozza ciascun server come istanza dello strumento MCP della libreria standard, core/ai-tool/mcp. Ogni server è uno strumento di questo tipo, quindi l’importatore non valuta alcun candidato e non riporta alcuna decisione di mapping.

Che cosa legge

  • La configurazione di un client. Il .mcp.json di Claude Code, il claude_desktop_config.json di Claude Desktop e il .cursor/mcp.json di Cursor elencano i propri server per nome sotto mcpServers; il .vscode/mcp.json di Visual Studio Code li elenca sotto servers, e un file che elenca server sotto entrambi viene letto prima sotto mcpServers. Un server il cui type è stdio, o che non nomina alcun type e porta un command, viene avviato da una riga di comando — il suo command e i suoi args — con il suo env come ambiente. Un server il cui type è http, streamable-http o sse, o che non nomina né un type né un command e porta un url, viene raggiunto al suo url e riceve i suoi headers.
  • La descrizione di un server del registry. Il server.json che il registry MCP pubblica: il suo name, e il suo primo pacchetto oppure, dove non ne elenca alcuno, il suo primo remoto. Un pacchetto npm o PyPI viene avviato dalla riga di comando composta dal suo launcher — il suo runtimeHint, oppure npx per npm e uvx per PyPI —, dai suoi runtimeArguments, dal pacchetto con la sua versione, scritto <identifier>@<version> per npm e <identifier>==<version> per PyPI, e dai suoi packageArguments, con le sue environmentVariables come ambiente. Un argomento posizionale è il suo value, oppure il suo default; un argomento nominato viene scritto <name>=<value> dove ha l’uno o l’altro, e come il suo name dove non ha nessuno dei due. Un pacchetto OCI viene eseguito dall’immagine che il suo identifier nomina. Un remoto viene raggiunto al suo url e riceve i suoi headers. Ogni altro pacchetto e remoto che la descrizione elenca viene nominato in un commento, poiché un’istanza ne esegue uno solo.

Ogni altro membro di un server — cwd, envFile, l’auth di Cursor, o un membro che il suo tipo di server non legge, come l’url di un server avviato da una riga di comando — non viene scritto da nessuna parte, e viene nominato in un commento sopra la voce del server nella Release, poiché nessuna chiave di infrastruttura di core/ai-tool/mcp lo accetta. Gli inputs di una configurazione, che descrivono ciò che Visual Studio Code chiede all’utente e non contengono alcun valore, non vengono letti. I server, il loro ambiente e i loro header mantengono l’ordine in cui la sorgente li scrive, tranne in una configurazione letta come JSON con commenti, che mantiene l’ordine in cui li scrive il suo albero analizzato: l’ordine dei nomi (vedi Una configurazione che contiene commenti).

Una directory viene letta tramite le configurazioni client che contiene — ogni file con il nome di una delle quattro, a qualsiasi profondità — nell’ordine dei loro percorsi, e ogni server di ogni file viene generato in bozza in un unico Aggregate.

Che cosa diventa un server

aggregate.yaml è un Aggregate in bozza che prende il nome dalla sorgente, come descrive Come viene chiamata una bozza, e che contiene un’istanza di core/ai-tool/mcp per server. Un’istanza ha come chiave il nome del suo server, in minuscolo, con ogni sequenza di caratteri diversi da lettere e cifre scritta come un unico trattino, e un suffisso numerico dove un server precedente ha preso la chiave. Dove la chiave non è il nome del server come scritto, o l’importazione ha letto più file, un commento sopra l’istanza nomina il server e il file da cui proviene. Nessun agente viene generato in bozza per usarli.

Accanto a esso, release.yaml è una Release in bozza con lo stesso nome, il cui spec.aggregate nomina l’Aggregate, che porta per ciascuna istanza gli input operativi che la sorgente indica:

  • per un server avviato da una riga di comando, infra.stdio_command, il suo comando e poi ciascun argomento, un elemento ciascuno; e infra.stdio_runtime, l’ecosistema del launcher, npm dove il comando è npx, npm o node, pypi dove è uvx, uv, python o python3 e, per un pacchetto del registry, il suo registry, npm o pypi;
  • per un server raggiunto a un indirizzo, infra.endpoint: l’indirizzo senza la sua parte utente, la sua query e il suo frammento, poiché il Component accetta l’indirizzo senza alcuna parte che porti una chiave; ciascuna parte che tralascia viene scritta nel commento sopra la voce, accanto all’indirizzo, come descrive Valori di credenziali contenuti in un server;
  • per un pacchetto OCI, infra.image;
  • per nessun server, su alcun target, infra.published_port: la bozza non pubblica mai un server sull’host;
  • per l’ambiente di un server, lo slot server_env, associato per riferimento in base al target dell’importazione. Con --target helm è un core/referenced-secret che nomina un Secret Kubernetes già presente nel namespace che contiene una chiave dati per variabile, ciascuna con il nome della variabile che contiene; il nome del Secret viene scritto vuoto, sotto un commento che nomina le chiavi dati, e rientra tra i valori dovuti dall’importazione. Su ogni altro target, e senza target, è un core/referenced-secret-set con una voce sotto infra.entries per variabile, con il nome della variabile come chiave e il suo valore come lo scrive la sorgente, così un riferimento a variabile come ${GITHUB_TOKEN} resta tale, e un target che sostituisce i riferimenti a variabili lo legge dall’ambiente.

Ciò che la sorgente non indica viene scritto vuoto, sotto un commento che dice che cosa è: un comando il cui launcher non è presente in nessuna delle due immagini bridge lascia vuoto infra.stdio_runtime, che rientra tra i valori dovuti dall’importazione; un argomento che una descrizione del registry lascia al suo utente viene scritto come elemento vuoto, e una variabile il cui valore la sorgente non scrive come voce con valore vuoto, ciascuno nominato nel commento sopra la voce.

Come ogni Release generata in bozza, scrive metadata.environment come development, sotto un commento che dice che è un valore predefinito della bozza da cambiare, e, senza target, spec.manifest come stringa vuota dovuta dall’importazione. Dato un target, l’importatore genera in bozza il Manifest stesso, poiché il catalogo realizza core/ai-tool/mcp tramite diverse Recipes e solo l’importatore sa come viene eseguito ciascun server: mappa ciascun server tramite la sua chiave, sotto mappings.components.name, sulla realizzazione del target per il modo in cui il server viene eseguito — mcp-stdio-bridge per una riga di comando, mcp-remote per un indirizzo, mcp per un’immagine, come helm/mcp-stdio-bridge o compose/mcp-remote — e il tipo di segreto con cui è associato l’ambiente sulla sua realizzazione, helm/k8s-existing-secret su helm e compose/dotenv-secret-set su compose. L’importazione completa quel Manifest e lo nomina nella Release, come descrive Che cosa aggiunge un target.

Un .mcp.json di Claude Code che elenca un server raggiunto via HTTP e uno avviato con 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}" }
}
}
}

viene generato in bozza come:

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

Importata con --target helm, la Release della stessa configurazione associa l’ambiente come il Secret che nomina, e il Manifest che l’importatore genera in bozza mappa ciascun server tramite la sua chiave:

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

Valori di credenziali contenuti in un server

Ogni valore della configurazione di un server che la Release scrive — il valore di ciascun header, ciascun elemento della sua riga di comando, il suo indirizzo, ciascuna parte dell’indirizzo che infra.endpoint tralascia e ciascun valore d’ambiente — può contenere una chiave, e nessun client ne contrassegna uno come credenziale, quindi l’importazione individua ciascuno come membro della configurazione di un server MCP; un input del registry contrassegnato con isSecret viene individuato come valore che il suo formato contrassegna come credenziale. Un input del registry — una variabile d’ambiente o l’header di un remoto — viene letto come il suo value, oppure il suo default dove non ne scrive alcuno. Per impostazione predefinita ciascuno viene portato com’è scritto nella Release e nominato in un avviso credential-carried tramite il suo server e la sua collocazione — headers.<header>, infra.stdio_command.<position>, infra.endpoint o server_env.<variable>, e una parte dell’indirizzo tramite l’url in cui è scritta e il nome della parte, come in «url of node remote-search is carried with its query as written (l’url del nodo remote-search è portato con la sua query com’è scritta)» — mai tramite il suo valore. Con l’impostazione empty_credentials a marked o all, ciascuno viene scritto vuoto e riportato con credential-emptied: un elemento della riga di comando come elemento vuoto e un valore d’ambiente come valore vuoto, ciascuno nominato nel commento sopra la voce; un indirizzo come infra.endpoint vuoto, che rientra tra i valori dovuti dall’importazione; e il valore di un header o una parte dell’indirizzo tralasciati dal commento, che nomina solo l’header o la parte. L’infra.stdio_runtime di un client viene letto dal comando così come la Release lo scrive, quindi un comando scritto vuoto lascia vuoto anche quello, e rientra tra i valori dovuti dall’importazione. Con --target helm la Release non scrive alcun valore d’ambiente: li contiene il Secret che lo slot server_env nomina.

Un valore che è un riferimento a una variabile e nient’altro — il nome nudo ${NAME}, tra cui una variabile predefinita come ${workspaceFolder}, ${env:NAME} o ${input:id} — non contiene alcun valore proprio: viene scritto come il testo che è, qualunque cosa dica l’impostazione, e non viene nominato in alcun avviso, come accade a un riferimento in un flusso. Una variabile d’ambiente il cui valore è un riferimento di questo tipo viene scritta come valore della voce, e il riferimento resta tale, e un header o una parte dell’indirizzo il cui valore è un riferimento di questo tipo viene elencato con il riferimento da cui legge. Un riferimento che porta del testo dopo un operatore — un valore predefinito, un’alternativa, un messaggio o un’assegnazione, come ${NAME:-value} o ${NAME-value}, con o senza due punti — contiene quel testo, e lo stesso vale per il testo accanto a un riferimento; ciascuno viene individuato come qualsiasi altro valore.

Nessuna chiave di infrastruttura di core/ai-tool/mcp accetta il valore di un header: la credenziale di un server remoto è detenuta da ciascun consumatore, sulla sua connessione allo strumento, e l’importazione non genera in bozza alcun consumatore. Così il commento sopra la voce del server elenca ciascun header che la sorgente gli invia, accanto al suo valore come scritto — una stringa tra virgolette doppie che si rilegge esattamente come il testo della sorgente — affinché tu lo sposti sulla connessione del consumatore che lo presenta. Un header il cui valore la sorgente non scrive, come un input header del registry senza né un valore né un valore predefinito, viene elencato come privo di valore. L’immagine che un pacchetto OCI nomina viene scritta così com’è, e non è un valore che l’impostazione raggiunge.

infra.endpoint accetta l’indirizzo senza alcuna parte che porti una chiave, quindi le parti dell’indirizzo scritte dalla sorgente che esso tralascia — la parte utente prima di @, la query dopo ? e il frammento dopo #, essendo frammento tutto ciò che segue il primo # — vengono elencate nello stesso commento, ciascuna accanto al suo nome e come scritta, senza il @, il ? o il # che la separa. Un consumatore che legge la propria chiave dall’indirizzo fornisce l’intero indirizzo sulla propria connessione allo strumento. Un server raggiunto a https://user:pw@api.example.com/mcp?key=k, senza alcuna impostazione, viene generato in bozza come:

# 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"

e con empty_credentials a marked, infra.endpoint viene lasciato alla Release e il commento elenca user part e query, ciascuno con il suo valore tralasciato.

Una configurazione che contiene commenti

Visual Studio Code legge .vscode/mcp.json come JSON con commenti, e così fa l’importatore MCP: la sua firma per quel file lo legge tramite il parser che serve parse:jsonc, quindi una configurazione che contiene commenti // e /* */ e virgole finali viene riconosciuta senza che venga nominato alcun formato, e l’importatore legge ogni sorgente che elenca i propri server sotto servers tramite quel parser. Una configurazione di questo tipo viene generata in bozza esattamente come la stessa configurazione senza i suoi commenti e le sue virgole finali. Il parser scrive i membri di un oggetto nell’ordine dei nomi, quindi i server di una tale configurazione, il loro ambiente e i loro header vengono generati in bozza nell’ordine dei nomi, che contenga o meno un commento; una riga di comando mantiene il proprio ordine. Gli altri client e il registry leggono i propri file come JSON, e così fa l’importatore: un .mcp.json, claude_desktop_config.json, .cursor/mcp.json o server.json che contiene un commento non viene riconosciuto da alcuna firma e, importato nominando --format mcp, si arresta con parse-failed e il motivo del parser. Un commento aperto con /* e mai chiuso viene lasciato come scritto, e il parser rifiuta il file.

Le impostazioni che legge

L’importatore MCP legge target_namespace e empty_credentials, come li descrive Impostazioni, e nessun’altra impostazione.

L’importatore Compose

importer/compose legge i servizi e i modelli che un file Compose dichiara. Genera in bozza ciascun servizio come istanza del Component del catalogo a cui corrisponde la sua immagine, oppure del server generico della libreria standard, core/compute/server, che esegue la sua immagine; ciascun modello come istanza del runtime Docker Model Runner della libreria standard, core/ai-model/docker-model-runner, dove il tuo catalogo lo contiene, e come Component di modello a sé dove non lo contiene; e, accanto a essi, una Release che porta ciò che ciascun servizio indica per il proprio funzionamento.

Che cosa legge

  • I file. Un file importato da solo viene letto da solo. Una directory viene letta come la legge Compose: in ciascuna directory che contiene file Compose, nell’ordine dei percorsi delle directory, il primo presente tra compose.yaml, compose.yml, docker-compose.yml e docker-compose.yaml è il file Compose, e il primo presente tra compose.override.yml, compose.override.yaml, docker-compose.override.yml e docker-compose.override.yaml viene unito sopra di esso. Nessun altro di quei file viene letto. In una directory che contiene file di sovrascrittura e nessun file Compose viene letto da solo il suo primo file di sovrascrittura. Un commento in apertura dell’Aggregate in bozza nomina i file letti, nell’ordine in cui vengono uniti, e i file non letti. Ogni servizio e ogni modello di ogni directory viene generato in bozza in un unico Aggregate.
  • L’unione. Un file di sovrascrittura viene unito come lo unisce Compose: image viene sostituito; le ports vengono unite in base al loro indirizzo, alla porta pubblicata, alla porta del container e al protocollo, i volumes in base al loro percorso nel container e environment in base al nome della variabile, con una voce successiva che prende il posto di una precedente e una nuova che si aggiunge in coda; expose viene accodato; depends_on e i models di un servizio vengono uniti, con endpoint_var e model_var di una voce che prendono ciascuno il posto di quello indicato da un file precedente. Di un modello, model e context_size vengono sostituiti e runtime_flags accodato. I tag !reset e !override di Compose non vengono rispettati: un valore che ne porta uno viene unito come lo legge il parser YAML.
  • Un servizio. La sua image, e se ne costruisce una sotto build; le sue ports, expose, volumes e environment — una mappa, oppure una lista di elementi NAME=value, dove un nome senza valore prende il proprio valore dall’ambiente in cui Compose viene eseguito; depends_on, una lista o una mappa; e i suoi models, una lista di nomi di modelli oppure una mappa le cui voci possono nominare, sotto endpoint_var e model_var, le variabili con cui l’indirizzo e l’identificativo del modello raggiungono il servizio. Ogni altro membro — command, healthcheck, secrets, env_file e il resto — non viene scritto da nessuna parte, e viene nominato in un commento sopra la voce del servizio nella Release.
  • Un modello. Ogni voce dei models di primo livello: il suo model, l’identificativo OCI del modello, il suo context_size e i suoi runtime_flags, portati come sono scritti in un’istanza di core/ai-model/docker-model-runner dove il tuo catalogo lo contiene, e di un Component di modello generato in bozza per esso dove non lo contiene; la decisione del modello dice quale dei due, e perché. Ogni altro membro viene nominato in un commento sopra la sua istanza.
  • Il resto. Gli altri membri di primo livello — name, networks, volumes, secrets, configs — non vengono letti, e il commento in apertura dell’Aggregate li nomina.

I servizi, i modelli e l’ambiente di un servizio mantengono l’ordine in cui il file li scrive. L’albero del parser scrive i membri di una mappa ordinati, quindi quell’ordine viene letto dal testo del file, dove sono scritti come mappa a blocchi; una mappa scritta in stile flow mantiene l’ordinamento.

Quale Component è un servizio

L’importatore trova la corrispondenza di un servizio in base al repository che la sua immagine nomina: il riferimento senza il suo tag e il suo digest, con un riferimento Docker Hub scritto nella sua forma breve — postgres per docker.io/library/postgres:16. Trova la corrispondenza del repository tramite la sua tabella delle immagini, una tabella che va dal repository di un’immagine al Component del catalogo per cui una Recipe Compose del catalogo standard esegue un’immagine di quel repository. La tabella viene generata dalle Recipes Compose e dai Components del catalogo standard quando l’importatore viene costruito, e compilata al suo interno, quindi nessuna Recipe viene letta quando un’importazione viene eseguita e la tabella contiene le label del catalogo standard, qualunque cosa contenga il tuo catalogo; l’entità Plugin dell’importatore nomina, nella sua descrizione, la revisione dell’hub da cui la tabella è stata generata. Di ciascuna Recipe, la tabella legge il Component che la Recipe implementa e l’immagine del suo container chiamato main, dove quell’immagine scrive il proprio repository nel proprio testo, o è una voce di locals che lo fa. Una Recipe che esegue l’immagine che la Release nomina per intero, o una che il suo template compone in altro modo, non aggiunge alcuna riga, e nemmeno un’immagine che una Recipe esegue accanto al suo container principale. Due Recipes che nominano uno stesso repository per Components diversi impediscono la generazione della tabella, così una riga non nomina mai uno di due. Del Component che una riga nomina, la tabella legge le label così come vengono consegnate a un’importazione — alla versione a cui si risolve un riferimento che nomina il Component senza versione, con quelle che eredita tramite extends — e scrive ogni label tranne component.aggrega.ai/category nella riga come suoi tratti. Anche una Recipe che implementa un Component che il catalogo standard non contiene impedisce la generazione della tabella.

Una riga viene letta come la riga della tabella di un importatore di flussi: il Component, la categoria in cui lo colloca il suo nome, i suoi tratti, e l’ultimo segmento del suo nome come suo fornitore. L’impostazione mapping_overrides si sovrappone alla tabella sotto il formato compose, con il repository come chiave, e una voce per un repository che la tabella mappa prende il posto della riga. Così un’immagine che le Recipes del catalogo standard non nominano — la tua, o una che un Component del catalogo esegue sotto un altro repository — viene mappata da una voce:

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

Un servizio la cui immagine è mappata da una riga viene deciso come gli importatori di flussi decidono un nodo: valutato rispetto ai Components del tuo catalogo, referenziato dove reuse_mode è auto-apply-above-threshold, il valore predefinito, e il suo candidato migliore è una corrispondenza di livello alto pari o superiore a reuse_threshold, e generato in bozza come Component a sé altrimenti, con il file del Component generato in bozza che si apre con un commento che nomina il Component a cui somiglia. Una riga porta le label del Component che nomina, quindi dove il tuo catalogo contiene quel Component con le label che gli dà il catalogo standard, un servizio mappato dalla riga è per esso una corrispondenza di livello alto, con punteggio 0.90, e auto-apply-above-threshold vi fa riferimento al reuse_threshold predefinito. Un Component le cui label il tuo catalogo ha cambiato ottiene un punteggio inferiore, in proporzione alla quota dei tratti della riga che non porta più, e viene referenziato solo finché resta nel livello alto; la categoria viene valutata una sola volta, nel proprio segnale, e non di nuovo come tratto. I servizi che generano in bozza uno stesso Component ne condividono l’unico file. Un servizio la cui immagine non è mappata da alcuna riga, la cui immagine non nomina alcun repository che l’importatore legge, o che costruisce la propria immagine, è un’istanza di core/compute/server, qualunque cosa contenga il tuo catalogo. La decisione di ciascun servizio viene riportata come quella di ciascun nodo.

Che cosa diventa un servizio

aggregate.yaml è un Aggregate in bozza che prende il nome dal progetto, come descrive Come viene chiamata una bozza, e che contiene un’istanza per servizio, del Component scelto dalla sua decisione, con la chiave assegnata come l’importatore MCP assegna la chiave a un server, e un commento sopra di essa che nomina il servizio e il file da cui proviene dove la chiave non è il nome del servizio o l’importazione ha letto più directory. Ogni servizio che il depends_on di un servizio nomina è una connessione, uses: <key>: <key>: {target: <key>}, scritta sotto un socket e un alias che prendono entrambi il nome dalla chiave della destinazione. Un componente legge ciascuna delle sue connessioni tramite il suo alias, qualunque sia il socket a cui è collegata, quindi ogni connessione di un servizio ha un alias proprio. Anche una variabile dell’ambiente di un servizio può dar luogo a una connessione, che consegna la variabile a partire da ciò che pubblica il servizio che raggiunge, come descrive Che cosa diventano l’ambiente e l’immagine di un servizio. Ogni modello è un’istanza di core/ai-model/docker-model-runner dove il catalogo del workspace lo contiene, qualunque cosa dica reuse_mode, e per esso non viene generato in bozza alcun Component: l’istanza scrive model e runtime_flags come li indica la sorgente, e il context_size della sorgente come context_window, il valore che il runtime dichiara per la lunghezza del contesto di un modello, che la sua Recipe Compose riscrive come context_size di Compose. Dove il catalogo non contiene alcun core/ai-model/docker-model-runner, il modello viene generato in bozza come <target_namespace>/ai-model/<key>, un Component della categoria ai-model i cui valori dichiarano model, context_size e runtime_flags, e la sua istanza scrive ciascuno di quelli che la sorgente indica. Ogni modello ha una decisione che dice quale dei due — mapped llm (model) to core/ai-model/docker-model-runner as a reference, NONE, oppure una bozza la cui decisione registra che il catalogo del workspace non contiene alcun core/ai-model/docker-model-runner — e ciascun servizio che nomina il modello vi è collegato in entrambi i casi, come a un servizio da cui dipende. Un servizio che nomina il modello nella forma lunga, con endpoint_var o model_var, nomina le variabili con cui il suo indirizzo e il suo identificativo raggiungono il servizio. Nessuna chiave della bozza contiene il nome di una variabile — la connessione è scritta su un socket che prende il nome dal modello, che non dichiara alcun valore, e a un importatore non viene consegnata alcuna chiave di infrastruttura di un Component — quindi un commento sopra la connessione nomina ciascuna, come la scrive la voce, e la decisione del servizio registra la stessa frase:

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

Un servizio che nomina il modello nella forma breve, o senza nessuna delle due variabili, vi è collegato senza alcun commento.

Accanto a esso, release.yaml è una Release in bozza con lo stesso nome, il cui spec.aggregate nomina l’Aggregate. Per un’istanza di core/compute/server scrive infra.image, l’immagine come scritta, e infra.port, la porta su cui il container è in ascolto nella prima voce di ports, oppure di expose dove ports non ne contiene alcuna. Con --target compose scrive anche infra.published_port, la porta host che la stessa voce di ports pubblica, come la indica la sorgente, sotto il commento che dice che è raggiungibile solo da questa macchina, da qualsiasi processo in esecuzione su di essa, e che eliminando la riga il servizio resta interno; una porta host inferiore a 1024, che published_port non accetta, non viene scritta, e un commento sopra la voce la nomina. Un commento sopra la voce di ciascun servizio scrive ciò che la sorgente indica e che nessuna chiave della bozza porta — l’immagine di un servizio abbinato a un altro Component il cui tag la bozza non traduce, le sue ports, expose, volumes, e ciascuna variabile del suo environment che la bozza non traduce — affinché tu lo porti dove il Component lo accetta. Ciò che la bozza lascia alla Release — l’immagine di un servizio che non ne nomina alcuna, come fa uno che costruisce la propria, e una porta che non è un unico numero — viene scritto vuoto sotto un commento che dice perché. Una build colloca solo le istanze che una Release nomina, quindi l’istanza di ciascun modello ha una voce vuota, <key>: {}, dopo quelle dei servizi: sia un’istanza di core/ai-model/docker-model-runner, che su Compose non accetta alcun input privo di un valore predefinito, sia un modello generato in bozza come Component a sé, così il modello generato in bozza è già collocato e la build riesce non appena scrivi la Recipe che lo realizza. Una porta che il Component non accetta, come una al di sotto della soglia minima di 1024 di core/compute/server, viene scritta come la indica la sorgente, e la build si arresta nominandola. La Release scrive metadata.environment e, senza target, uno spec.manifest vuoto, come fa quella dell’importatore MCP; dato un target, l’importazione genera in bozza il Manifest, come descrive Che cosa aggiunge un target, mappando ciascun Component alla Recipe che lo realizza su quel target — core/compute/server a compose/server o helm/server, e core/ai-model/docker-model-runner a compose/docker-model-runner o helm/docker-model-runner.

Un compose.yaml che esegue PostgreSQL e una propria API che dipende da esso:

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

viene generato in bozza, senza alcuna impostazione, su un catalogo che contiene il core/datastore/postgres della libreria standard, importato da solo e chiamato come il file, dato che il progetto non porta alcun name, come:

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

L’importazione riporta mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9. Il progetto non contiene alcun servizio cache, quindi CACHE_URL non dà luogo ad alcuna connessione e resta nel commento. Con reuse_mode: hints-only, db è invece type: imported/datastore/postgres, generato in bozza in components/imported-datastore-postgres.yaml, che si apre con # resembles core/datastore/postgres (score 0.9000); reference it by setting type: core/datastore/postgres; la sua immagine e il suo ambiente vengono allora scritti nel commento sopra la sua voce, poiché un Component generato in bozza non dichiara nessuno dei valori che le Recipes del catalogo leggono. Con --target compose, il Manifest mappa core/datastore/postgres a compose/postgres e core/compute/server a compose/server; con --target helm, a helm/postgres e helm/server.

Che cosa diventano l’ambiente e l’immagine di un servizio

Dove un servizio è un’istanza del Component di catalogo nominato dalla riga della sua immagine, e il catalogo del workspace contiene quel Component, l’importatore legge la sua immagine e il suo ambiente come li leggono le Recipes Compose del catalogo standard per quel Component, da ciò che la tabella delle immagini registra di ciascuna Recipe, e li traduce nelle bozze:

  • Il tag dell’immagine è la chiave di infrastruttura da cui la Recipe costruisce il riferimento all’immagine, come engine_version — 16 per postgres:16 — scritta nella Release sotto un commento che nomina l’immagine della sorgente.
  • Una variabile che la Recipe imposta da uno dei valori del Component — POSTGRES_DB, POSTGRES_USER — il cui valore contiene testo, è quel valore dell’istanza, database o user, dove il Component del catalogo lo dichiara, scritto nell’Aggregate sotto un commento che nomina le variabili.
  • Una variabile da cui la Recipe legge una password, come POSTGRES_PASSWORD, il cui valore è un unico riferimento a una variabile, è un segreto collegato su quello slot, letto dalla variabile che il riferimento nomina e dichiarato con la chiave con cui la Recipe lo legge.

E, per ogni servizio, ciascuna variabile del suo ambiente non letta in questo modo:

  • Un valore che è il nome di un altro servizio del progetto, dove la riga di quel servizio nomina la chiave provides che pubblica il suo nome host, dà luogo a una connessione a quel servizio, il cui blocco inject consegna la variabile da quella chiave — CACHE_HOST: cache è CACHE_HOST dall’host della cache.
  • Un valore uguale a un valore che un altro servizio imposta per il suo Component e che il Component pubblica — DATABASE_USER: notes accanto a un servizio PostgreSQL che imposta POSTGRES_USER: notes — dà luogo a una connessione che consegna la variabile da quella chiave provides. Dove più servizi o chiavi contengono il valore, viene letto quello la cui chiave, o la cui variabile, termina come termina il nome della variabile e, in mancanza, quello da cui le altre variabili del servizio non sono già state lette; altrimenti la variabile non viene letta.
  • Un valore che è un unico riferimento a una variabile che nomina una variabile da cui viene letto il segreto di un altro servizio — DATABASE_PASSWORD: ${POSTGRES_PASSWORD} — è, su un’istanza di core/compute/server, un segreto proprio, collegato sotto il nome della variabile in minuscolo e letto dalla stessa variabile, dove il target scrive il segreto come un valore che il server accetta. helm/server rifiuta un core/referenced-secret, quindi con --target helm una tale variabile resta nel commento.

Ogni altra variabile viene lasciata nel commento sopra la voce del servizio, come la scrive la sorgente. La guida passo passo all’importazione Compose mostra un progetto la cui API raggiunge in questo modo il suo database e la sua cache, compilato ed eseguito così come generato in bozza.

Valori di credenziali contenuti in un servizio

Compose non contrassegna alcun valore d’ambiente come credenziale, e l’importatore non legge il nome di alcuna variabile per ciò che significa, quindi ogni valore d’ambiente che contiene qualcosa viene individuato come un input che il suo formato contrassegna come non credenziale ma che può contenerne una. Per impostazione predefinita ciascuno viene portato com’è scritto nelle bozze — nel valore in cui viene tradotto, oppure nel commento sopra la voce del suo servizio nella Release — e nominato in un avviso credential-carried tramite il suo servizio e la sua variabile — environment.<variable> — mai tramite il suo valore. Con l’impostazione empty_credentials a all, ciascuno viene scritto vuoto e riportato con credential-emptied: il commento nomina la sua variabile senza valore. Con marked nessuno viene scritto vuoto, poiché Compose non ne contrassegna alcuno. Un valore che è un riferimento a una variabile che Compose interpola e nient’altro — ${NAME} o $NAME — non contiene alcun valore proprio: viene scritto come il testo che è, e non viene nominato in alcun avviso. Un riferimento che porta un valore predefinito o un messaggio, come ${NAME:-value}, contiene quel testo, e viene individuato come qualsiasi altro valore. Un valore che Compose legge da altrove — un env_file, il file di un segreto — non viene letto.

Le impostazioni che legge

L’importatore Compose legge target_namespace, reuse_mode, reuse_threshold, emit_hints, render_mode, mapping_overrides e empty_credentials, come li descrive Impostazioni, e nessun’altra impostazione. Il suggerimento che emit_hints governa viene scritto solo nel file del Component generato in bozza; l’Aggregate in bozza non ne porta alcuno.

L’importatore Dify

importer/dify legge un’applicazione esportata da Dify nel suo DSL, il documento YAML che Dify scrive per un’applicazione, e genera in bozza un Aggregate che compone l’installazione Dify della libreria standard, core/dify, con l’applicazione portata nel parametro app_definition dell’installazione. L’installazione la importa al momento della distribuzione, tramite il passaggio che la Recipe del suo server API renderizza per essa.

Che cosa legge

  • L’applicazione. kind, che è app; version, la versione del DSL in cui è scritta l’applicazione; e app, con il suo mode.
  • Un workflow o un chatflow — mode workflow o advanced-chat — conserva il proprio grafo sotto workflow: ogni nodo di workflow.graph.nodes che nomina il proprio tipo sotto data.type è un nodo dell’applicazione, nell’ordine in cui il grafo li elenca, e workflow.environment_variables contiene le variabili che legge.
  • Un’applicazione chat, agent chat o completion conserva la propria configurazione sotto model_config: il suo model, ogni knowledge base sotto dataset_configs.datasets.datasets e ogni strumento sotto agent_mode.tools è un nodo dell’applicazione, nominato in base alla sua posizione lì, come model_config.model. Un’applicazione della modalità agent è un unico nodo, agent.
  • I plugin di cui ha bisogno. Anche ogni voce di dependencies è un nodo, chiamato dependencies.<n>, del tipo che la voce nomina, come marketplace.

Nient’altro decide che cosa viene generato in bozza: viene portata l’intera applicazione.

Che cosa diventa un’applicazione

aggregate.yaml è un Aggregate in bozza che prende il nome dall’applicazione, come descrive Come viene chiamata una bozza, e che compone una voce di core/dify, con chiave dify, il cui parametro app_definition porta l’applicazione com’è scritta — come descrive Come il flusso viene scritto nella bozza per un flusso, così i riferimenti {{#…#}} propri di Dify raggiungono l’installazione così come sono stati esportati. L’installazione collega da sé ogni connessione del suo server API — il suo database, la sua cache, il suo vector store, la sua sandbox, il suo runtime dei plugin e il suo proxy di uscita — quindi la bozza non genera in bozza alcun Component e non collega nulla: ogni nodo resta nell’applicazione, e la sua decisione lo dice. Accanto a esso, release.yaml è una Release in bozza con lo stesso nome, che colloca l’installazione in un confine, platform, e porta ciò che l’applicazione non può fornire.

Un’importazione vede i Components del catalogo del workspace e nessuno dei suoi Aggregates, quindi non verifica che il catalogo contenga core/dify, e un commento sopra la voce lo dice. Dove il catalogo non contiene core/ai-agent/dify, il server API che core/dify esegue, l’importazione emette l’avviso platform-not-in-catalog e genera comunque la voce in bozza.

Il segreto applicativo dell’installazione, la chiave con cui Dify firma i propri cookie di sessione e con cui cifra le credenziali dei fornitori di modelli che memorizza, è il parametro secret_key di core/dify, che non ha un valore predefinito. Per questo la bozza dichiara un proprio parametro secret_key — una stringa, obbligatoria, lunga almeno un carattere e senza valore predefinito — e lo trasmette a ogni voce core/dify che scrive, perché la Release lo soddisfi sotto i propri parameters; un build la cui Release lo lascia non impostato si arresta nominandolo.

L’applicazione viene importata con l’account del proprietario dell’installazione, che la Release nomina nella propria voce di instradamento per l’installazione: infra.owner_email sul componente api dell’installazione e lo slot owner_password su quel componente, associato come core/referenced-secret, senza i quali la build si arresta. L’email del proprietario non è qualcosa che una sorgente possa fornire, quindi viene scritta vuota sotto un commento che dice che cos’è, e l’importazione la riporta come dovuta.

Su ogni target, la stessa voce di instradamento imposta infra.marketplace_enabled a true sui componenti api, worker e scheduler dell’installazione, ciascuno sotto un commento che spiega perché: l’installazione non raggiunge nulla del fornitore di Dify a meno che la Release non lo consenta, ciascuno dei tre legge la propria impostazione, e Dify installa il plugin che serve il modello di un’applicazione, come quello di OpenAI, dal proprio marketplace dei plugin.

Il segreto applicativo e la password del proprietario sono segreti, generati in bozza per riferimento per il target dell’importazione:

  • Con --target helm, ciascuno nomina un Secret Kubernetes già presente nel namespace: secret_key il nome del Secret, che core/dify legge sotto la chiave di dati secret-key, e owner_password un Secret che contiene la password sotto la chiave di dati value. Nessuno dei due nomi è qualcosa che una sorgente possa fornire, quindi ciascuno viene scritto vuoto sotto un commento che dice che cos’è, e l’importazione li riporta entrambi come dovuti; il Manifest generato in bozza mappa core/referenced-secret su helm/k8s-existing-secret.
  • Su ogni altro target, e senza target, ciascuno è un riferimento a una variabile — secret_key come "${DIFY_SECRET_KEY}" e la password del proprietario come "${DIFY_OWNER_PASSWORD}", i nomi che leggono le Recipes Dify per Compose del catalogo standard — che Docker Compose legge dall’ambiente all’avvio dello stack, quindi per nessuno dei due resta qualcosa di dovuto; con --target compose il Manifest generato in bozza mappa core/referenced-secret su compose/dotenv-referenced-secret.

Dato un target, il Manifest mappa il tipo di ogni componente che l’installazione compone, oltre a quello della bozza stessa, come descrive Che cosa aggiunge un target.

L’applicazione workflow scritta a mano che i test di questo importatore importano, chiamata Support Answers, viene generata in bozza, senza alcuna impostazione, come:

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

Importata con --target helm, la sua Release generata in bozza soddisfa secret_key, e nomina il proprietario e attiva il marketplace dei plugin nella voce di instradamento che colloca l’installazione, con ogni valore dovuto scritto vuoto:

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

L’importazione riporta come dovuti i tre valori vuoti. Importata con --target compose, la stessa Release scrive secret_key: "${DIFY_SECRET_KEY}" e origin: "${DIFY_OWNER_PASSWORD}", e riporta come dovuta solo l’email del proprietario; scrive anche infra.published_port sul componente api, 5001, e sul front end, il componente console, 3001, ciascuno sotto il commento che dice che è raggiungibile solo da questa macchina, da qualsiasi processo in esecuzione su di essa, e che eliminare la riga mantiene il servizio interno, e, sotto la porta del componente api, infra.console_url con l’indirizzo a cui è pubblicata la console, "http://127.0.0.1:3001", che il server Dify assume come indirizzo della console. La procedura guidata di importazione di Dify esegue la build di un’applicazione per entrambi i target e la esegue su Kubernetes.

Che cosa Dify configura da sé

Dify configura al proprio interno i provider dei modelli e degli strumenti che un’applicazione chiama, e core/ai-agent/dify non dichiara alcun socket per un modello, quindi la bozza non ne collega nessuno. Ogni nodo che ne nomina uno viene riportato con part-configured-in-platform, e nella sua decisione, in base a ciò che nomina:

  • un nodo llm, question-classifier o parameter-extractor, e il model_config.model di un’applicazione chat: il modello, tramite il suo nome e il suo provider;
  • un nodo tool, e lo strumento di un’applicazione chat: lo strumento, tramite il suo nome e il suo provider;
  • un nodo agent: la strategia dell’agente e il plugin che la fornisce;
  • un nodo knowledge-retrieval, e la knowledge base di un’applicazione chat: le knowledge base da cui recupera, e il modello con cui instrada una query o con cui riordina i risultati, dove ne nomina uno. Un’applicazione nomina una knowledge base tramite un identificativo dell’installazione da cui è stata esportata, e non porta nessuno dei suoi documenti né alcun archivio, quindi ciascuna viene creata all’interno di Dify, nel vector store che l’installazione collega al suo server API;
  • una dipendenza: il plugin, tramite l’identificativo con cui Dify lo installa, e il luogo da cui Dify lo installa.

Ogni altro nodo viene mantenuto nell’applicazione senza che nulla venga riportato.

Valori di credenziali contenuti in un’applicazione

L’importatore individua, nell’ordine in cui l’applicazione li scrive:

  • il valore di ciascuna variabile d’ambiente il cui value_type è secret, che Dify contrassegna come credenziale. L’esportazione di Dify lo scrive vuoto a meno che l’esportazione non includa i segreti;
  • l’authorization.config.api_key di un nodo di richiesta HTTP, che Dify contrassegna come credenziale ed esporta com’è scritto;
  • la credenziale memorizzata che un nodo tool, o uno strumento di un nodo agent, seleziona sotto credential_id, che Dify contrassegna come credenziale e scrive solo dove l’esportazione include i segreti;
  • gli headers e i params di un nodo di richiesta HTTP, che Dify non contrassegna come credenziale e che possono contenerne una, ciascuno per intero.

Per impostazione predefinita ciascuno che contiene un valore viene portato com’è scritto nell’applicazione e nominato in un avviso credential-carried tramite il suo nodo — workflow per una variabile d’ambiente — e il suo campo, mai tramite il suo valore. Con l’impostazione empty_credentials a marked, ogni valore che Dify contrassegna come credenziale viene scritto vuoto, e a all anche gli header e i parametri di query, ciascuno riportato con credential-emptied. Un valore che è un riferimento a una variabile e nient’altro non ne contiene alcuno, e viene portato com’è scritto qualunque cosa dica l’impostazione e non viene nominato in alcun avviso, come in un flusso. Un valore viene scritto vuoto nel testo stesso dell’applicazione: lo scalare dopo la sua chiave viene sostituito da '', e nient’altro viene cambiato. L’applicazione viene portata solo dove il parser che serve parse:yaml rilegge il risultato come l’applicazione esportata con esattamente quei valori svuotati; altrimenti non viene portata, app_definition viene lasciato non impostato con un commento, e definition-not-carried dice perché — come per un’applicazione in cui un alias YAML legge il valore di un segreto, che scrivere vuoto quel valore cambierebbe anch’esso. Un valore che l’impostazione lascia com’è scritto non viene mai riscritto, quindi non impedisce mai che l’applicazione venga portata.

La versione del DSL

Dove un’applicazione è scritta in una versione del DSL più recente di 0.7.0, la versione che scrive Dify 1.17.0 — la versione che core/ai-agent/dify esegue per impostazione predefinita —, l’importazione emette l’avviso dsl-version-newer. Dify trattiene l’importazione di un’applicazione di questo tipo in attesa di una conferma, che il passaggio che la importa al momento della distribuzione fornisce, quindi verifica l’applicazione rispetto alla versione di Dify che la Release esegue.

Le impostazioni che legge

L’importatore Dify legge target_namespace, empty_credentials, layout, attach_egress_allowlist e render_mode, come li descrive Impostazioni, e reuse_mode, reuse_threshold, emit_hints e mapping_overrides, che non cambiano nulla di ciò che la disposizione predefinita genera in bozza: ogni nodo resta nell’applicazione. attach_egress_allowlist non associa nulla, poiché una voce di un Aggregate composto accetta parametri e nessuna Feature, e con esso a true l’importazione emette l’avviso feature-not-attached. layout: nodes genera in bozza ogni nodo come Component proprio, come descrive Nodo per nodo, e non porta alcuna applicazione.

L’importatore CrewAI

importer/crewai legge gli agenti e i task che un progetto CrewAI dichiara nei suoi file di configurazione, e genera in bozza un Aggregate che contiene un’istanza dell’agente CrewAI della libreria standard, core/ai-agent/crewai, per agente, ciascuna collegata al modello che la sua configurazione nomina, e una Release accanto a esso.

Che cosa legge

CrewAI conserva il comportamento di una crew in un programma e ne dichiara gli agenti e i task in file di configurazione, in una di due strutture, e l’importatore legge l’una o l’altra:

  • Un progetto classico — config/agents.yaml, con ciascun agente che ha come chiave il proprio nome, e config/tasks.yaml, con ciascun task che ha come chiave il proprio nome, entrambi letti come YAML. Gli agenti vengono letti nell’ordine in cui agents.yaml li scrive.
  • Un progetto nella struttura JSON-first — crew.jsonc, che elenca gli agenti della crew per nome sotto agents e i suoi task sotto tasks, e agents/<name>.jsonc, un file per agente, tutti letti come JSON con commenti, così i loro commenti e le loro virgole finali vengono letti come li legge CrewAI. Gli agenti vengono letti nell’ordine in cui crew.jsonc li elenca, seguiti dal file di ogni altro agente nell’ordine dei nomi; un agente che la crew elenca il cui file non è stato passato all’importazione viene nominato in un commento e non dà luogo ad alcuna bozza. La stessa struttura scritta in JSON rigoroso — crew.json e agents/<name>.json — viene letta allo stesso modo. Dove una crew o un agente è scritto in entrambe le grafie, il file .jsonc è quello che viene letto, come lo legge CrewAI, e il file .json viene nominato in un commento come non letto.

Di un agente legge il suo role, goal e backstory; allow_delegation e verbose, al livello superiore della sua dichiarazione o sotto settings, dove prevale settings, come li legge CrewAI; il suo llm; e i nomi dei suoi tools. Di un task legge il nome e l’agente a cui è assegnato. Ogni altro membro viene nominato in un commento e non viene portato da nessuna parte.

Una directory viene passata all’importatore come i file che le sue firme nominano e nessun altro, quindi il programma della crew — il crew.py di un progetto classico, il main.py di un flusso, uno strumento che un progetto definisce in Python — non viene mai letto. Un file importato da solo viene letto come la dichiarazione di cui ha la forma. La directory di un progetto può contenere più crew, ciascuna letta dalla propria directory.

Che cosa diventa un progetto

aggregate.yaml è un Aggregate in bozza che prende il nome dalla crew, come descrive Come viene chiamata una bozza, e che si apre con commenti che nominano le dichiarazioni lette, il fatto che il programma della crew non viene letto, e i task di ciascuna crew con l’agente a cui ciascuno è assegnato. Contiene, per agente e con il suo nome come chiave, un’istanza di core/ai-agent/crewai con:

  • role, goal e backstory come dichiarati;
  • allow_delegation come dichiarato, e false dove l’agente non ne dichiara alcuno;
  • log_level DEBUG per un agente dichiarato verbose, che racconta ogni passo del proprio ragionamento, e INFO per uno che non lo è, che riporta solo l’avanzamento e i problemi. Un verbose o un allow_delegation che non è né true né false viene lasciato al valore predefinito del Component e nominato in un commento;
  • la sua connessione model, collegata all’istanza del modello che il suo llm nomina.

Un llm scritto <provider>/<model>, o come oggetto che nomina il modello sotto model, model_name o deployment_name, nomina un provider e un modello. Il modello è un’istanza del Component del catalogo per quel provider — core/ai-model/<provider>, con un trattino basso nel nome del provider letto come trattino, e azure letto come azure-openai — con il nome del modello come chiave e il modello come suo values.model; gli agenti che nominano lo stesso provider e lo stesso modello condividono un’unica istanza. Dove il catalogo del workspace non contiene alcun Component con quel nome, ne viene generato uno in bozza, <target_namespace>/ai-model/<provider>, che dichiara il valore model, e la sua decisione lo dice; l’etichetta model.aggrega.ai/api con cui il socket model dell’agente seleziona un Component, e una Recipe che ne pubblichi l’endpoint e il modello, vengono lasciate a te, come dice un commento che lo apre. Un llm che non nomina alcun provider — un nome di modello nudo, per cui CrewAI risolve un provider quando il programma viene eseguito, o il nome di un llm che il programma definisce — un riferimento nel programma, e un agente che non dichiara alcun llm, che CrewAI legge allora dall’ambiente in cui il suo programma viene eseguito, non vengono collegati a nulla, e un commento sopra l’agente dice perché; la build si arresta nominando il socket model finché non ne viene collegato uno.

Un task è logica che il programma della crew esegue, e uno strumento è codice che il programma definisce o carica: nessuno dei due diventa un Component. Ciascuno viene riportato in una decisione che non sceglie nulla, e uno strumento il cui nome — senza un Tool finale, i suoi trattini e i suoi trattini bassi — è il nome di un Component di strumento che il catalogo contiene porta quel Component come suggerimento: search_tool e SearchTool suggeriscono entrambi core/ai-tool/search. core/ai-agent/crewai non dichiara alcun socket per uno strumento, quindi per esso non viene collegato nulla.

release.yaml, accanto a esso, è una Release in bozza con lo stesso nome che nomina quell’Aggregate. Scrive vuoto l’infra.image di ciascun agente — l’immagine che esegue il programma della crew, che nessuna dichiarazione nomina — sotto un commento che dice che cos’è, e l’importazione lo riporta come dovuto. Con --target compose la voce di ciascun agente scrive anche infra.published_port, 8000, la porta che l’infra.port del Component indica per il programma per impostazione predefinita, che la sua Recipe Compose pubblica sull’indirizzo di loopback dell’host, 127.0.0.1, sotto il commento che dice che è raggiungibile solo da questa macchina, da qualsiasi processo in esecuzione su di essa, e che eliminare la riga mantiene il servizio interno; un secondo agente prende la porta libera successiva, così i due agenti del progetto classico sono pubblicati su 8000 e 8001. Associa la credenziale che ciascun agente presenta al proprio modello sotto credential sulla sua connessione model, per riferimento e mai come valore: nessuna dichiarazione nomina una variabile per essa, quindi viene letta dalla variabile da cui le librerie client del fornitore leggono la propria chiave API — OPENAI_API_KEY per OpenAI — come riferimento ${…} su ogni target tranne helm, e su helm come nome di un Secret Kubernetes, scritto vuoto perché l’importazione lo riporti come dovuto; su compose, la connessione model dell’agente la dichiara con quella chiave. Anche ciascun modello ha una voce, che non contiene alcuna infrastruttura, così la Release lo colloca insieme agli agenti. Di un modello dichiarato come oggetto llm, ogni altro membro viene scritto come valore dell’istanza del modello dove il Component del catalogo dichiara un valore con quel nome, e altrimenti in un commento sopra la voce del modello nella Release, perché tu lo porti dove il Component lo accetta. Come ogni Release generata in bozza, scrive metadata.environment come development e, senza target, uno spec.manifest vuoto che l’importazione riporta come dovuto; dato un target, l’importazione genera in bozza il Manifest, come descrive Che cosa aggiunge un target.

Il progetto classico che i test di questo importatore importano, i cui due agenti nominano entrambi openai/gpt-4o, viene generato in bozza, senza alcuna impostazione, come segue; importato come la sua directory di progetto, market_brief — la directory in cui crewai create crew market_brief dispone un progetto del genere —, dato che le sue dichiarazioni non nominano alcuna crew, prende il nome da quella directory:

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

e la sua Release, generata in bozza senza target, come segue, con la voce del secondo agente omessa qui e indicata con ...; l’importazione riporta come dovuti spec.manifest e l’immagine di ciascun agente:

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

Ciascun agente viene quindi renderizzato in esecuzione sull’immagine che indichi nella risposta, ricevendo l’endpoint del modello e il nome del modello come OPENAI_BASE_URL e MODEL, le variabili da cui CrewAI li legge.

Valori di credenziali contenuti in una dichiarazione

Un llm scritto come oggetto può contenere una chiave — sotto api_key, in un indirizzo, negli header. Ciascuno dei suoi membri diverso da quello che nomina il modello che non è un numero o un booleano è un valore che può contenerne una, che CrewAI non contrassegna come credenziale. Per impostazione predefinita ciascuno che contiene un valore viene portato com’è scritto — come valore dell’istanza del modello dove il suo Component ne dichiara uno, e altrimenti nel commento sopra la voce del suo modello nella Release — e nominato in un avviso credential-carried tramite il suo agente e il suo membro, come llm.api_key, mai tramite il suo valore. Con l’impostazione empty_credentials a all, ciascuno viene scritto senza valore e riportato con credential-emptied; a marked ciascuno viene portato, poiché CrewAI non ne contrassegna alcuno. Il nome di un membro non viene letto per ciò che significa. Ogni altro membro che una dichiarazione contiene e che la bozza non porta — la configurazione di uno strumento, gli inputs di una crew — viene nominato, mai con il suo valore.

Le impostazioni che legge

L’importatore CrewAI legge target_namespace, empty_credentials e render_mode, come li descrive Impostazioni, e nessun’altra impostazione.

L’importatore LangGraph

importer/langgraph legge i grafi che la configurazione di un’applicazione LangGraph, langgraph.json, dichiara, e genera in bozza un Aggregate che contiene un’istanza dell’agente LangGraph della libreria standard, core/ai-agent/langgraph, per grafo, ciascuna collegata al datastore in cui il suo checkpointer conserva lo stato e a un modello, e una Release accanto a esso che porta l’ambiente che la configurazione indica. Legge quella configurazione, e mai il codice dei grafi.

Che cosa legge

Un’applicazione LangGraph conserva i propri grafi nel codice e li dichiara in langgraph.json: sotto graphs, l’id di ciascun grafo corrisponde al percorso di importazione del grafo nel codice dell’applicazione — ./src/agent/graph.py:graph, o module:attr — oppure a un oggetto che nomina quel percorso sotto path e descrive il grafo sotto description. L’importatore legge, nell’ordine in cui la configurazione li scrive:

  • graphs — l’id di ciascun grafo, il suo percorso di importazione e la sua descrizione;
  • checkpointer — il suo backend: default, che è PostgreSQL e ciò che LangGraph legge dove non ne viene nominato alcuno; mongo, un database che parla il protocollo di MongoDB; oppure custom, un checkpointer che il codice dell’applicazione definisce in path;
  • store — l’archivio di memoria, che non nomina alcun backend: LangGraph lo conserva nel database PostgreSQL che usa il suo server;
  • env — l’ambiente con cui l’applicazione viene eseguita: un oggetto che associa nomi di variabili a valori, oppure il percorso di un file di ambiente di righe KEY=VALUE.

I membri che configurano l’immagine del server di cui langgraph build esegue la build — dependencies, source, python_version, node_version, base_image, image_distro, dockerfile_lines, pip_config_file, pip_installer, keep_pkg_tools, api_version — vengono nominati in un commento e non vengono portati da nessuna parte, poiché l’immagine che la Release nomina è quella propria dell’applicazione; lo stesso vale per ogni altro membro, tra cui la configurazione propria del server come auth, http e webhooks, e per l’index e il ttl dell’archivio di memoria e il ttl e il serde del checkpointer.

Una directory viene passata all’importatore come langgraph.json e nessun altro file, quindi né il codice dell’applicazione né un file di ambiente vengono mai letti da essa. Un file di ambiente raggiunge l’importatore solo dove il with.sources dell’importatore lo passa, e non viene mai analizzato: di quello che l’env della configurazione nomina — abbinato in base all’ultimo segmento del percorso che nomina — vengono letti solo i nomi delle variabili, e un file di ambiente che nessuna configurazione nomina viene nominato in un commento come non letto. Dove all’importazione non viene passato il file che la configurazione nomina, l’Aggregate lo nomina come non passato e dice di nominarlo sotto il with.sources dell’importatore, e le sue variabili vengono lasciate alla Release:

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

Una configurazione importata da sola viene letta qualunque sia il suo nome. Una directory può contenere più applicazioni, ciascuna letta dalla propria directory.

Che cosa diventa un’applicazione

aggregate.yaml è un Aggregate in bozza che prende il nome dal grafo, come descrive Come viene chiamata una bozza, e che si apre con commenti che nominano le configurazioni lette, i file di ambiente letti solo per i loro nomi, il fatto che il codice dell’applicazione non viene letto, e ciò che la bozza non porta. Contiene, per grafo e con il suo id come chiave, un’istanza di core/ai-agent/langgraph con:

  • graph_entrypoint, il percorso di importazione del grafo, come lo scrive la configurazione;
  • description, la descrizione del grafo, dove la configurazione ne fornisce una;
  • la sua connessione checkpointer_db, collegata al datastore dell’applicazione;
  • la sua connessione model, collegata al modello dell’applicazione.

recursion_limit non viene scritto, quindi resta valido il valore predefinito del Component, 25. La configurazione non nomina alcun modello, quindi la bozza contiene un’istanza di core/ai-model/openai, con chiave model, che ogni grafo chiama: il modello che viene fornito al client OpenAI dell’agente. Il suo values.model viene scritto vuoto, sotto un commento che dice che la configurazione non ne nomina alcuno, e l’importazione lo riporta come dovuto.

Il backend del checkpointer è il datastore a cui è collegato ogni grafo dell’applicazione: default, o un checkpointer che non nomina alcun backend, è un’istanza di core/datastore/postgres, con chiave postgres. mongo è FerretDB, che parla il protocollo di MongoDB, su PostgreSQL con l’estensione DocumentDB: un’istanza di core/datastore/ferretdb, con chiave ferretdb, a cui è collegato ogni grafo, e una di core/datastore/documentdb, con chiave documentdb, che la connessione backend di FerretDB raggiunge, con il suo blocco inject che consegna ciò che DocumentDB pubblica sotto i nomi che FerretDB legge; un’unica password, letta dalla variabile FERRETDB_PASSWORD, è associata a DocumentDB, alla connessione di FerretDB verso di esso e alla connessione di ciascun grafo verso FerretDB. Dove il catalogo del workspace non contiene alcun Component con il nome del datastore PostgreSQL, ne viene generato uno in bozza, <target_namespace>/datastore/postgres, che dichiara l’host e la port che la connessione checkpointer_db dell’agente legge, e la sua decisione lo dice; una Recipe che esegua il datastore e li pubblichi viene lasciata a te, come dice un commento che lo apre. Dove non contiene alcun Component FerretDB o alcun Component DocumentDB, il checkpointer mongo non viene collegato ad alcun datastore. Un checkpointer custom, o un backend che l’importatore non mappa su alcun datastore, non collega nulla, e un commento sopra ciascun grafo e la decisione del checkpointer dicono perché; la build si arresta nominando il socket checkpointer_db finché non ne viene collegato uno. L’archivio di memoria viene riportato in una decisione che non sceglie nulla.

La password del datastore è un segreto che la bozza associa per riferimento, sullo slot password del datastore stesso e sulla connessione checkpointer_db di ciascun grafo, e lo stesso vale per la credenziale che ciascun grafo presenta al modello sulla sua connessione model: lette da POSTGRES_PASSWORD (o FERRETDB_PASSWORD) e da OPENAI_API_KEY, poiché la configurazione non nomina alcuna variabile per nessuna delle due, come riferimento ${…} su ogni target tranne helm, e su helm come nome di un Secret Kubernetes, scritto vuoto perché l’importazione lo riporti come dovuto. Su compose, l’Aggregate dichiara ciascuna con la chiave che la sua Recipe legge, come descrive Segreti, per ciascun target per una piattaforma.

release.yaml, accanto a esso, è una Release in bozza con lo stesso nome che nomina quell’Aggregate. Commenti sopra la voce del primo grafo dicono qual è l’immagine di ciascun grafo — quella propria dell’applicazione, il suo codice con LangGraph installato, non l’immagine del server di cui langgraph build esegue la build —, le variabili che riceve e quale blocco inject: sostituisce quale dei loro nomi. La voce di ciascun grafo scrive vuoto il suo infra.image, l’immagine che esegue l’applicazione, sotto un commento che dice che cos’è, e l’importazione lo riporta come dovuto; finché non è impostato, la Recipe Docker Compose esegue l’agente quickstart del catalogo stesso, che legge le variabili predefinite. Con --target compose la voce di ciascun grafo scrive anche infra.published_port, 8000, la porta che l’infra.port del Component indica per l’applicazione per impostazione predefinita, che la sua Recipe Compose pubblica sull’indirizzo di loopback dell’host, 127.0.0.1, sotto il commento che dice che è raggiungibile solo da questa macchina, da qualsiasi processo in esecuzione su di essa, e che eliminare la riga mantiene il servizio interno; un secondo grafo prende la porta libera successiva. Anche il datastore e il modello hanno delle voci, così la Release li colloca insieme ai grafi. Un commento sopra il primo grafo dell’applicazione indica l’ambiente che la sua configurazione dichiara, come descrive L’ambiente che una configurazione indica. Come ogni Release generata in bozza, scrive metadata.environment come development e, senza target, uno spec.manifest vuoto che l’importazione riporta come dovuto; dato un target, l’importazione genera in bozza il Manifest, come descrive Che cosa aggiunge un target.

L’applicazione Python che i test di questo importatore importano, che dichiara due grafi, un checkpointer che non nomina alcun backend, un archivio di memoria e un env scritto come oggetto, viene generata in bozza, senza alcuna impostazione, come segue; importata come la sua directory, support_desk — chiamata, come qui, come il package in cui sono definiti i suoi grafi —, con due grafi i cui id differiscono, prende il nome da quella directory:

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

L’importazione riporta come dovuti quattro valori: spec.manifest, l’immagine di ciascun grafo e il nome del modello. Una volta indicati, ciascun grafo viene renderizzato in esecuzione sull’immagine che indichi nella risposta, ricevendo l’indirizzo del suo datastore come LANGGRAPH_CHECKPOINTER_HOST e LANGGRAPH_CHECKPOINTER_PORT, l’utente e il database che il datastore pubblica come LANGGRAPH_CHECKPOINTER_USER e LANGGRAPH_CHECKPOINTER_DATABASE — PostgreSQL li pubblica entrambi, e per un datastore che non ne pubblica nessuno non viene renderizzata nessuna delle due variabili —, l’endpoint e il nome del modello come OPENAI_BASE_URL e OPENAI_MODEL, la chiave che la sua credenziale del modello consegna come OPENAI_API_KEY, il suo percorso di importazione come LANGGRAPH_GRAPH_ENTRYPOINT e il suo limite di passi come LANGGRAPH_DEFAULT_RECURSION_LIMIT. La credenziale associata alla sua connessione checkpointer_db gli fornisce anche la password del datastore come LANGGRAPH_CHECKPOINTER_PASSWORD.

L’ambiente che una configurazione indica

Ogni variabile che l’env della configurazione nomina è un input che la Release deve fornire, e nessuna viene generata in bozza come slot di credenziale: LangGraph non contrassegna alcuna variabile come segreto, e il nome di una variabile non viene letto per ciò che significa. core/ai-agent/langgraph non accetta alcun valore per l’ambiente, quindi la Release lo indica in un commento sopra il primo grafo dell’applicazione.

  • Un env scritto come oggetto fa parte della configurazione, quindi i suoi valori vengono portati così come sono scritti in quel commento, nell’ordine in cui la configurazione li scrive. Ciascun valore che contiene qualcosa può contenere una credenziale, che LangGraph non contrassegna come credenziale: per impostazione predefinita ciascuno viene portato com’è scritto e nominato in un avviso credential-carried tramite la sua configurazione e la sua variabile, come env.OPENAI_API_KEY, mai tramite il suo valore. Con l’impostazione empty_credentials a all, ciascuno viene scritto senza valore e riportato con credential-emptied; a marked ciascuno viene portato, poiché LangGraph non ne contrassegna alcuno.
  • Un env che nomina un file nomina un file a cui la configurazione si limita a puntare, che comunemente contiene segreti locali. Viene letto solo dove il with.sources dell’importatore lo passa. Il commento nomina ciascuna variabile che il file nomina, lasciata alla Release da fornire, e nessun valore del file viene letto: nessuno raggiunge una bozza, una decisione o una diagnostica, qualunque cosa dica l’impostazione. Un valore racchiuso tra virgolette su più righe è un unico valore, quindi una riga al suo interno non viene mai presa per una variabile, e una riga che non nomina alcuna variabile viene nominata tramite il suo numero. Dove all’importazione non è stato passato il file — sempre così per una directory, che non ne passa mai uno — l’Aggregate lo nomina come non passato, con il modo per passarlo, e le sue variabili vengono lasciate alla Release.

Le impostazioni che legge

L’importatore LangGraph legge target_namespace, empty_credentials e render_mode, come li descrive Impostazioni, e nessun’altra impostazione.

L’importatore Google ADK

importer/google-adk legge gli agenti che un’applicazione costruita sull’Agent Development Kit (ADK) di Google dichiara nei suoi file Agent Config — root_agent.yaml e le configurazioni che i suoi sotto-agenti nominano — e genera in bozza un Aggregate che contiene un’istanza dell’agente ADK della libreria standard, core/ai-agent/google-adk, per albero di agenti, collegata al modello che l’albero nomina quando ADK ne invia le richieste alla Gemini API, e una Release accanto a esso. Legge quelle configurazioni, e mai il codice dell’applicazione.

ADK dichiara che la sua funzionalità Agent Config è sperimentale. Il modello di un agente è un modello Gemini per impostazione predefinita; ADK serve per nome i modelli di alcuni altri fornitori tramite classi proprie, come claude-sonnet-4-5 e gpt-4o, e altri tramite una stringa di modello LiteLLM. Il socket model dell’agente ammette soltanto la Gemini API, quindi l’importer collega un modello che ADK invia alla Gemini API e lascia a te qualsiasi altro, come descrive Che cosa diventa un albero di agenti.

Che cosa legge

adk create --type=config di ADK scrive root_agent.yaml, la configurazione dell’agente radice di un’applicazione, e un file di ambiente accanto a essa. Una configurazione dichiara un agente:

  • name, description e agent_class — la classe con cui ADK costruisce l’agente, LlmAgent dove non ne nomina alcuna;
  • model — il modello che l’agente richiede — oppure model_code, un riferimento al codice che ne costruisce il modello;
  • tools — ciascuno strumento tramite name, con gli args che la sua configurazione gli passa;
  • generate_content_config — le opzioni delle richieste al modello dell’agente, tra cui http_options;
  • sub_agents — ciascuno un config_path, il percorso di un’altra configurazione a partire dalla directory della configurazione che lo nomina, oppure code, un agente che il codice dell’applicazione costruisce.

Una directory viene passata all’importatore come i suoi file root_agent.yaml e nessun altro file, e una configurazione importata da sola viene letta come radice, qualunque sia il suo nome. L’albero di ciascuna radice viene letto a partire dalla radice, con i sotto-agenti di ciascun agente nell’ordine in cui li elenca. La configurazione che una voce di sub_agents nomina tramite config_path viene letta solo dove il with.sources dell’importatore la passa, abbinata in base all’ultimo segmento del percorso; una che non è stata passata all’importazione viene nominata nell’Aggregate e nella sua decisione come non passata, con il modo per passarla, e il suo agente non viene letto:

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

Un config_path assoluto, o che porta fuori dalla directory della configurazione che lo nomina, non viene letto, poiché anche ADK lo rifiuta. Un file che with.sources passa e che nessuna configurazione nomina viene nominato in un commento come non letto, e nulla di esso viene letto; un file che passa viene letto solo come una configurazione che l’albero di una radice nomina, quindi un’importazione che non contiene alcun root_agent.yaml né alcun file importato da solo non legge alcun albero e riporta ciascun file sotto no-nodes. Il codice dell’applicazione — gli strumenti, le callback, gli schemi e gli agenti che una configurazione nomina tramite il loro codice — e il file di ambiente non vengono mai passati, e l’importatore non legge né l’uno né l’altro: l’applicazione carica da sé le proprie configurazioni, dall’immagine che la Release nomina. Una directory può contenere più applicazioni, ciascuna letta dal proprio root_agent.yaml.

Gli altri membri di una configurazione — tra cui l’instruction di un agente — vengono letti dall’applicazione dalla propria configurazione, quindi la bozza non ne porta nessuno.

Che cosa diventa un albero di agenti

ADK serve un’applicazione a partire dal suo agente radice, con ogni agente che le sue configurazioni nominano costruito al suo interno, e core/ai-agent/google-adk esegue una di tali applicazioni. Quindi aggregate.yaml, un Aggregate in bozza che prende il nome dall’agente radice, come descrive Come viene chiamata una bozza, contiene, per albero di agenti e con il nome del suo agente radice come chiave, un’istanza di core/ai-agent/google-adk con:

  • description, la descrizione dell’agente radice, dove la sua configurazione ne fornisce una;
  • la sua connessione model, collegata al modello che l’albero nomina, quando ADK invia le sue richieste alla Gemini API.

Commenti sopra di essa nominano gli altri agenti dell’albero, che non diventano un’istanza propria; ciascun sotto-agente che non viene letto, e perché — costruito dal codice dell’applicazione, una configurazione che non è stata passata all’importazione, o una che ADK rifiuta; gli strumenti che gli agenti dell’albero nominano, quelli che ADK fornisce e quelli che il codice dell’applicazione definisce; gli agenti la cui classe — LoopAgent, ParallelAgent o SequentialAgent — ADK depreca in favore di Workflow; e, dove il modello dell’albero è collegato, i modelli che altri agenti dell’albero richiedono, ciascuno con la famiglia tramite cui ADK lo serve. Ciascuno viene riportato in una decisione che non sceglie nulla.

Il primo agente dell’albero, a partire dalla radice, che nomina un modello o il codice che ne costruisce uno decide il modello dell’istanza. Un modello che nomina e le cui richieste ADK invia alla Gemini API — un nome di modello che ADK serve tramite la sua classe Gemini, come gemini-2.5-flash, diverso da un nome di risorsa Vertex AI, o uno che serve tramite la sua classe Gemma — è un’istanza di core/ai-model/gemini, che serve quel modello e ha quel modello come chiave, e gli alberi che nominano lo stesso modello condividono un’unica istanza. Dove il catalogo del workspace non contiene alcun core/ai-model/gemini, ne viene generato uno in bozza, <target_namespace>/ai-model/gemini, che porta l’etichetta model.aggrega.ai/api: gemini che il socket model dell’agente seleziona, e la sua decisione lo dice; una Recipe che ne pubblichi l’endpoint e il modello viene lasciata a te, come dice un commento che lo apre. Un modello che ADK serve in qualsiasi altro modo — una stringa di modello LiteLLM come openai/gpt-4o, un nome di risorsa Vertex AI, o un nome come claude-sonnet-4-5 o gpt-4o, che ADK serve tramite Anthropic o OpenAI — non viene collegato a nulla: il socket model dell’agente accetta un modello Gemini, e l’agente non legge alcun nome di modello dal proprio ambiente, quindi sei tu a collegarvi un modello Gemini e a nominare quel modello nella configurazione dell’agente. Il commento sopra l’istanza e la decisione dell’agente radice nominano il modello e la famiglia tramite cui ADK lo serve. Anche un modello che il codice dell’applicazione costruisce, o un albero che non ne nomina alcuno — ADK usa allora il proprio modello predefinito — non viene collegato a nulla, e un commento sopra l’istanza dice perché. Ovunque il modello non sia collegato a nulla, la build si arresta nominando il socket model finché non ne viene collegato uno. Tra i modelli che altri agenti di un albero richiedono, uno le cui richieste ADK invia alla Gemini API non ha bisogno di una connessione propria: il client Gemini di ADK ne invia le richieste con la chiave che la connessione dell’istanza fornisce. Se l’applicazione raggiunge Gemini tramite la Gemini API o tramite Vertex AI lo sceglie il suo ambiente, che l’importazione non legge; il socket model dell’agente ammette solo la Gemini API.

I test dell’importatore importano anche un agente radice isolato che nomina openai/gpt-4o, la cui istanza viene generata in bozza come:

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, accanto a esso, è una Release in bozza con lo stesso nome che nomina quell’Aggregate. La voce di ciascuna istanza scrive il suo infra.image — l’immagine che esegue l’applicazione costruita su ADK, che contiene le sue configurazioni — vuoto, sotto un commento che dice che cosa è, e l’importazione lo segnala come dovuto. Con --target compose la voce scrive anche infra.published_port, 8000, la porta su cui l’applicazione è in ascolto, che la sua Recipe Compose pubblica sull’indirizzo di loopback dell’host, 127.0.0.1, sotto il commento che dice che è raggiungibile solo da questa macchina, da qualsiasi processo in esecuzione su di essa, e che eliminare la riga mantiene il servizio interno; un secondo albero prende la porta libera successiva. Dove il suo modello è collegato, la voce associa la credenziale che l’istanza presenta a quel modello sotto credential sulla sua connessione model, per riferimento e mai come valore: nessuna configurazione nomina una variabile per essa, quindi viene letta da GOOGLE_API_KEY, la variabile da cui le librerie client della Gemini API di Google leggono la loro chiave, come riferimento ${…} su ogni target tranne helm, e su helm come nome di un Kubernetes Secret, scritto vuoto e segnalato come dovuto dall’importazione; su compose, la connessione model la dichiara con quella chiave. Anche un modello collegato ha una voce, che non contiene alcuna infrastruttura, così la Release lo colloca insieme all’istanza. I valori che le configurazioni dell’albero passano ai loro strumenti e alle loro richieste al modello vengono scritti in un commento sopra la voce, come descrive Valori di credenziali contenuti in una configurazione. Come ogni Release generata in bozza, scrive metadata.environment come development e, senza target, uno spec.manifest vuoto che l’importazione segnala come dovuto; dato un target, l’importazione genera in bozza il Manifest, come descrive Che cosa aggiunge un target.

L’applicazione che i test di questo importatore importano, un agente radice che nomina le configurazioni di due sotto-agenti e uno costruito dal codice, importata come la sua directory con le due configurazioni nominate sotto with.sources, viene generata in bozza, senza alcuna impostazione, con il nome del suo agente radice, tutor_root, come:

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

Un testo che la bozza copia da una configurazione nell’Aggregate, in un valore o in un commento, scrive ogni {{ come {{`{{`}}, un’azione il cui risultato sono le due graffe, così la descrizione, e un nome che contiene due graffe in un commento, vengono riletti come scritti una volta valutato l’Aggregate.

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

Una volta data la risposta per l’immagine, l’istanza viene renderizzata in esecuzione su di essa e riceve la credenziale come GOOGLE_API_KEY, che il client Gemini di ADK invia alla Gemini API, e il modello come un Service che raggiunge l’indirizzo della Gemini API.

Valori di credenziali contenuti in una configurazione

Una configurazione può passare una chiave a uno strumento, nei suoi args, o alle sue richieste al modello, nelle http_options della sua generate_content_config — i loro header, il loro indirizzo, gli argomenti del loro client. Ciascun membro degli args di uno strumento e di quelle opzioni HTTP viene scritto nel commento sopra la voce dell’istanza nella Release, come la sua configurazione lo scrive, e ciascuno che è un testo, un oggetto o una lista può contenere una credenziale, che ADK non contrassegna come credenziale: per impostazione predefinita ciascuno viene portato com’è scritto e nominato in un avviso credential-carried tramite il suo agente e il suo campo, come tools.tutor_tools.make_snippet_runner.args.api_key, mai tramite il suo valore. Con l’impostazione empty_credentials a all, ciascuno viene scritto senza valore e riportato con credential-emptied; a marked ciascuno viene portato, poiché ADK non ne contrassegna alcuno. Un numero o un booleano non contiene alcuna chiave, e viene scritto come la configurazione lo scrive. ADK non espande alcun riferimento a variabile in una configurazione, quindi ogni valore viene letto com’è scritto; il file di ambiente, che comunemente contiene la chiave che il client Gemini di ADK legge, non viene mai letto, qualunque cosa dica l’impostazione.

Le impostazioni che legge

L’importatore Google ADK legge target_namespace, empty_credentials e render_mode, come li descrive Impostazioni, e nessun’altra impostazione.

L’importatore Agent Framework

importer/agent-framework legge un agente dichiarativo di Microsoft Agent Framework — il documento YAML di tipo Prompt da cui un’applicazione costruita su Agent Framework carica un agente — e genera in bozza un Aggregate che contiene un’istanza dell’agente Agent Framework della libreria standard, core/ai-agent/agent-framework, collegata al modello OpenAI che nomina, e una Release accanto a esso. Legge agenti dichiarativi, e mai il codice dell’applicazione. Agent Framework pubblica i suoi pacchetti per agenti dichiarativi come prerelease.

Che cosa legge

Un agente dichiarativo dichiara:

  • name, displayName e description, le sue instructions e gli schemi del suo input e del suo output;
  • model — l’id del modello, il provider che lo serve, l’API a cui il suo client invia le richieste (apiType), le options delle sue richieste, e la sua connection: una connessione key che presenta una chiave, scritta sotto key o apiKey, a un endpoint; una connessione remote che raggiunge un endpoint; una connessione reference che ne nomina una che l’applicazione risolve; oppure una anonymous che non presenta nulla;
  • tools — ciascuno di un kind: una function il cui codice l’applicazione associa, uno strumento web_search, file_search o code_interpreter che il provider del modello esegue, oppure un server mcp raggiunto al suo url, con l’approvalMode che seguono le sue chiamate, gli allowedTools del server che l’agente può chiamare e una connection propria.

Un membro scritto come =Env.NAME viene letto da Agent Framework dalla variabile d’ambiente NAME solo dove l’applicazione carica l’agente dichiarativo con AgentFactory(safe_mode=False), l’impostazione di sicurezza propria di Agent Framework, ed è presente un runtime .NET, e altrimenti viene preso come il testo dell’espressione così com’è scritto; ogni altro membro che si apre con = è un’espressione che l’applicazione calcola. L’importatore non legge né l’uno né l’altra: nomina un riferimento tramite la sua variabile, e un’espressione come tale.

Un file importato da solo viene letto come un agente dichiarativo, qualunque sia il suo nome, e ogni file che il with.sources dell’importatore passa viene letto come un altro, così un’importazione ne genera in bozza diversi:

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

Una directory non viene mai passata all’importatore: la sua firma non nomina alcun file, quindi un’importazione di una directory che non nomina alcun formato non la riconosce, e una che nomina --format agent-framework viene rifiutata con An importer that declares no file patterns is handed a directory (A un importer che non dichiara pattern di file viene passata una directory) prima che venga aperto alcun suo file. Importa invece ciascun agente dichiarativo come file a sé. Una sorgente da cui Agent Framework non costruisce alcun agente prompt — una il cui kind non è né Prompt, in qualsiasi combinazione di maiuscole e minuscole, né Agent — viene riportata con no-nodes. Il codice dell’applicazione — il programma che carica ciascun agente dichiarativo e le funzioni che associa ai suoi strumenti — non è mai tra le sorgenti: l’applicazione carica da sé i propri agenti dichiarativi, dall’immagine che la Release nomina.

Che cosa diventa un agente dichiarativo

aggregate.yaml, un Aggregate in bozza che prende il nome dall’agente, come descrive Come viene chiamata una bozza, contiene, per agente dichiarativo e con il suo nome come chiave, un’istanza di core/ai-agent/agent-framework con:

  • display_name e description, il displayName e la description dell’agente, dove li indica;
  • la sua connessione model, collegata al modello che nomina, dove quel modello è collegato.

Le sue istruzioni, gli schemi del suo input e del suo output, il suo template, i suoi metadati e le opzioni delle sue richieste al modello vengono letti dall’applicazione dall’agente dichiarativo, e vengono nominati in un commento sopra l’istanza. Uno strumento funzione, uno strumento che il provider del modello esegue e uno strumento di qualsiasi altro tipo vengono anch’essi nominati in un commento, e riportati in una decisione che non sceglie nulla.

Un modello il cui provider è OpenAI e che nomina un id è un’istanza di core/ai-model/openai, che serve quell’id e ha quell’id come chiave: il socket model dell’agente ammette un modello che serve l’API OpenAI, e il runtime consegna l’indirizzo, il nome e la chiave di quel modello nelle variabili che i client OpenAI di Agent Framework leggono. Gli agenti che nominano uno stesso modello a uno stesso indirizzo condividono un’unica istanza. Dove il catalogo del workspace non contiene alcun core/ai-model/openai, ne viene generato uno in bozza, <target_namespace>/ai-model/openai, che porta l’etichetta model.aggrega.ai/api: openai che il socket model dell’agente seleziona, e la sua decisione lo dice; una Recipe che ne pubblichi l’endpoint e il modello viene lasciata a te, come dice un commento che lo apre. Un id scritto come riferimento lascia a te il values.model del modello, con un commento sopra il modello che nomina la variabile; la build si arresta nominandolo finché non viene impostato. Una connessione anonymous viene scritta come unauthenticated: true della connessione. Un modello di qualsiasi altro provider — AzureOpenAI, Anthropic —, uno che nomina il proprio provider come riferimento o non ne nomina alcuno, nel qual caso Agent Framework usa il provider predefinito che l’applicazione imposta, e uno che non nomina alcun id non vengono collegati a nulla, e un commento sopra l’istanza dice perché; la build si arresta nominando il socket model finché non ne viene collegato uno.

Uno strumento di tipo mcp non viene generato in bozza né come Component né come connessione: Agent Framework invia il server al provider del modello come strumento ospitato, ed è il provider, non l’applicazione, a raggiungerlo al suo url, che deve quindi essere raggiungibile dal provider, per cui nulla di ciò che la bozza distribuisce lo raggiunge. Un commento sopra l’istanza dell’agente nomina il server, lo dice, e nomina la descrizione, l’approvalMode e gli allowedTools che l’agente dichiarativo indica per esso; il suo url viene scritto, per intero, nel commento sopra la voce dell’agente nella Release, e la sua decisione non sceglie nulla.

release.yaml, accanto a esso, è una Release in bozza con lo stesso nome che nomina quell’Aggregate. La voce dell’agente scrive il suo infra.image — l’immagine che esegue l’applicazione costruita su Agent Framework, che contiene il suo agente dichiarativo — vuoto, sotto un commento che dice che cosa è, e l’importazione lo segnala come dovuto. Con --target compose la voce scrive anche infra.published_port, 8000, la porta che l’infra.port del Component indica per l’applicazione per impostazione predefinita, che la sua Recipe Compose pubblica sull’indirizzo di loopback dell’host, 127.0.0.1, sotto il commento che dice che è raggiungibile solo da questa macchina, da qualsiasi processo in esecuzione su di essa, e che eliminare la riga mantiene il servizio interno. Dove il suo modello è collegato, la voce associa la credenziale che l’agente presenta a quel modello sotto credential sulla sua connessione model, per riferimento e mai come valore: viene letta dalla variabile che l’agente dichiarativo nomina per la sua chiave, scritta =Env.NAME, e altrimenti da OPENAI_API_KEY, la variabile da cui le librerie client di OpenAI leggono la loro chiave; come riferimento ${…} su ogni target tranne helm, e su helm come nome di un Kubernetes Secret, scritto vuoto e segnalato come dovuto dall’importazione; su compose, la connessione model la dichiara con quella chiave. I valori che l’agente dichiarativo indica per il proprio modello e per i propri server MCP — le chiavi e l’url di ciascun server — vengono scritti in un commento sopra la voce dell’agente, come descrive Valori di credenziali contenuti in un agente dichiarativo. Ogni modello collegato ha una voce, così la Release lo colloca insieme all’agente. L’endpoint che la sua connessione indica viene scritto come infra.endpoint del modello, e uno scritto come riferimento viene nominato accanto alla sua voce, e finché non viene impostato si usa l’indirizzo proprio del Component; una connessione che non indica alcun endpoint lascia la voce priva di infrastruttura, e resta valido l’indirizzo proprio del Component. Come ogni Release generata in bozza, scrive metadata.environment come development e, senza target, uno spec.manifest vuoto che l’importazione segnala come dovuto; dato un target, l’importazione genera in bozza il Manifest, come descrive Che cosa aggiunge un target.

L’agente dichiarativo che i test di questo importatore importano, del provider OpenAI con una connessione a chiave, un server MCP che presenta una propria chiave, uno strumento funzione e una ricerca web, importato come file a sé, viene generato in bozza, senza alcuna impostazione, con il suo name, LearnAgent, come:

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

Un testo che la bozza copia da un agente dichiarativo nell’Aggregate, in un valore o in un commento, scrive ogni {{ come {{`{{`}}, così si rilegge com’è scritto una volta valutato l’Aggregate.

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

Una volta data la risposta per l’immagine, l’agente viene renderizzato in esecuzione su di essa, ricevendo l’endpoint del modello come OPENAI_BASE_URL, il suo id come OPENAI_MODEL e la sua credenziale come OPENAI_API_KEY, e il modello viene renderizzato come un Service che raggiunge il proprio host. Nessuna variabile porta l’indirizzo del server MCP: a raggiungerlo è il provider del modello, non l’applicazione.

Valori di credenziali contenuti in un agente dichiarativo

La chiave che una connessione key presenta — scritta sotto key o apiKey, sul modello o su un server MCP — è l’unico membro che Agent Framework contrassegna come credenziale: è l’unico valore che il suo loader oscura in ciò che registra nei log. Ogni chiave che un agente dichiarativo scrive come letterale viene scritta nel commento sopra la voce dell’agente nella Release, come la scrive l’agente dichiarativo, e per impostazione predefinita portata com’è scritta e nominata in un avviso credential-carried tramite il suo agente e il suo campo, come model.connection.key, mai tramite il suo valore. L’url di un server MCP, scritto per intero nello stesso commento e nominato tramite il suo campo — tools.microsoft_learn.url of node LearnAgent is carried as written — è un membro della configurazione di un server MCP, e l’endpoint di un modello collegato è un input che Agent Framework contrassegna come non credenziale. Con l’impostazione empty_credentials a marked, le chiavi e gli url dei server MCP vengono scritti senza valore — il commento nomina ciascuno solo tramite il suo campo — e riportati con credential-emptied, e l’endpoint del modello viene portato; a all, viene tralasciato anche l’infra.endpoint del modello, nominato nel commento sopra la sua voce come lasciato alla Release, e finché non viene impostato si usa l’indirizzo predefinito del Component. Un valore scritto come =Env.NAME non ne contiene alcuno, quindi viene nominato tramite la sua variabile, insieme alla condizione alla quale Agent Framework lo legge dall’ambiente — model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads … — qualunque cosa dica l’impostazione, e non viene riportato con nessuno dei due codici; un valore scritto come qualsiasi altra espressione viene nominato come tale e mai scritto.

Le impostazioni che legge

L’importatore Agent Framework legge target_namespace, empty_credentials e render_mode, come li descrive Impostazioni, e nessun’altra impostazione.

Che cosa aggiunge un target

Un’importazione a cui viene dato un target — --target su aggrega import, oppure target sullo strumento di importazione dell’assistente e sul metodo aggrega/import della sessione, che nomina una capacità di provider come compose o helm — passa quel target all’importatore, che quindi genera le bozze per esso: ogni segreto nella forma che quel target legge, e le righe che servono solo a quel target, scritte attive, mentre le righe che servono solo a un altro target vengono omesse. Su compose quelle righe includono infra.published_port ovunque l’importatore pubblichi un servizio sull’indirizzo di loopback dell’host, come dice la sezione di ciascun importatore; una porta scelta dall’importatore non prende mai un numero preso da un’altra porta della Release. L’importazione genera poi in bozza il Manifest accanto a ciò che l’importatore ha generato in bozza, qualunque importatore sia stato eseguito: manifest.yaml, accanto alla Release in bozza e con il suo stesso nome e la sua stessa versione — oppure, dove l’importatore non ha generato in bozza alcuna Release, accanto all’Aggregate in bozza e con il nome e la versione di quest’ultimo.

Per ciascun tipo di componente e ciascun tipo di feature di cui le bozze hanno bisogno — sui componenti dell’Aggregate in bozza, sulle loro connessioni e sui suoi sottosistemi, sugli Aggregates del catalogo che esso compone, come core/dify, e sulle associazioni della Release in bozza — il Manifest mappa il tipo sulla Recipe, o per un tipo di feature sulla feature recipe, di quella capacità che il catalogo del workspace offre per esso: quella che c’è, contando come una sola più versioni della stessa; oppure, dove ce ne sono diverse di nomi differenti, quella che porta il nome del tipo stesso, come helm/postgres per core/datastore/postgres. Un tipo che non ne ha nessuna, o ne ha diverse di cui nessuna ha quel nome, viene lasciato non mappato, un avviso lo nomina indicandone il motivo, e una build delle bozze si arresta nominando ciascuna sua istanza o associazione finché non lo mappi.

Dove solo l’importatore sa quale tra diverse Recipes si applica, genera in bozza il Manifest da sé — l’importatore MCP mappa ciascun server, tramite la sua chiave, sulla realizzazione del modo in cui il server viene eseguito, e un importatore che associa un segreto per nome mappa core/referenced-secret su helm/k8s-existing-secret — e l’importazione lo completa: ogni mappatura scritta dall’importatore che il catalogo offre per quel tipo e quella capacità viene mantenuta, ogni altra viene scartata con un avviso, e i tipi che lascia vengono mappati come sopra.

Lo spec.manifest della Release in bozza, scritto vuoto senza target, viene impostato sul nome del Manifest, il commento sopra di esso viene eliminato, e nient’altro nella Release cambia. aggrega import lo descrive per intero.

Impostazioni

A un importatore vengono passate le impostazioni della voce plugins.importer che lo associa, sotto with.settings, come descrive Quale importer trasforma una sorgente in bozze. Senza alcuna voce, o senza impostazioni, ogni impostazione assume il suo valore predefinito.

plugins:
importer:
- uri: importer/langflow:<version>
with:
settings:
target_namespace: payments
reuse_mode: hints-only
ImpostazionePredefinitoCosa fa
target_namespaceimportedIl namespace sotto cui sono nominate le entità generate in bozza: <target_namespace>/<category>/<name> per un Component e <target_namespace>/<name> per l’Aggregate e la Release, dove <name> è il nome proprio della sorgente, altrimenti il nome della sua directory o il nome del suo file senza l’estensione, altrimenti flow, scritto in minuscolo con ogni sequenza di caratteri diversi da lettere e cifre ASCII resa come un solo trattino, come descrive Come viene nominata una bozza.
reuse_modeauto-apply-above-thresholdauto-apply-above-threshold referenzia il Component del catalogo con la corrispondenza migliore per un nodo a cui la bozza dà un Component proprio, la cui corrispondenza è nel livello alto e ottiene un punteggio pari o superiore a reuse_threshold, e genera in bozza ogni altro. hints-only genera in bozza ogni nodo di questo tipo e non referenzia alcun Component del catalogo, registrando una corrispondenza forte come suggerimento. Qualsiasi altro valore viene letto come hints-only.
reuse_threshold0.85Il punteggio pari o superiore al quale auto-apply-above-threshold referenzia un Component. Letto solo in quella modalità; 0 viene letto come il valore predefinito.
emit_hintstrueSe il file di un Component generato in bozza si apre con un commento che nomina il Component del catalogo a cui somiglia, per una corrispondenza di livello alto o medio. L’Aggregate in bozza porta lo stesso commento sopra la voce di quel nodo, e sopra una voce referenziata uno che nomina il candidato successivo migliore con cui potrebbe essere scambiata, o che dice che nessuno ha ottenuto un punteggio superiore a zero. false tralascia i commenti.
render_modehumanhuman scrive le bozze descritte sopra. llm non scrive alcuna bozza, e scrive invece l’intero registro delle decisioni — ogni nodo, i candidati valutati e la scelta fatta — come un unico documento, import-decisions.json, che un altro strumento può leggere. Qualsiasi altro valore viene letto come human.
mapping_overridesnessunaMappature sovrapposte alla tabella propria dell’importatore, con il formato e poi il tipo di nodo come chiave — per l’importatore Compose, il repository dell’immagine. Ogni voce nomina il component su cui si mappa un nodo di quel tipo e, facoltativamente, la sua category, i traits — etichette e i loro valori — che un Component corrispondente porta, e una parola vendor che il suo nome porta. Una voce per un tipo di nodo che la tabella mappa già prende il posto della riga della tabella. Vengono lette solo le voci sotto il formato che si sta importando.
layoutplatformplatform genera in bozza la piattaforma che esegue il flusso, portando il flusso, con ciascuna sua parte come Component proprio collegato alla piattaforma, come descrive La piattaforma che porta il flusso. nodes genera in bozza ogni nodo come Component proprio, come descrive Nodo per nodo. Per l’importatore Dify, platform genera in bozza l’installazione Dify che porta l’applicazione, come descrive Che cosa diventa un’applicazione. Qualsiasi altro valore genera in bozza come platform, e l’importazione emette l’avviso unknown-layout.
empty_credentialsnoneQuali valori di credenziali vengono scritti vuoti nel flusso che la piattaforma porta, come li elenca Valori di credenziali contenuti nel flusso, quali nella Release che l’importatore MCP genera in bozza, come li elenca Valori di credenziali contenuti in un server, quali nella Release che l’importatore Compose genera in bozza, come li elenca Valori di credenziali contenuti in un servizio, quali nell’applicazione che l’importatore Dify porta, come li elenca Valori di credenziali contenuti in un’applicazione, quali nella Release che l’importatore CrewAI genera in bozza, come li elenca Valori di credenziali contenuti in una dichiarazione, quali nella Release che l’importatore LangGraph genera in bozza, come li elenca L’ambiente che una configurazione indica, quali nella Release che l’importatore Google ADK genera in bozza, come li elenca Valori di credenziali contenuti in una configurazione, e quali nella Release che l’importatore Agent Framework genera in bozza, come li elenca Valori di credenziali contenuti in un agente dichiarativo. none non ne scrive vuoto nessuno: ciascuno viene portato com’è scritto e nominato in un avviso credential-carried. marked scrive vuoto ciò che un formato contrassegna come credenziale e ogni membro della configurazione di un server MCP. all scrive vuoti anche gli input che un formato contrassegna come non credenziale ma che possono contenerne una — header delle richieste, parametri di query, una richiesta scritta come riga di comando, un input il cui nome indica una chiave. Ciò che la bozza scrive affinché un nodo raggiunga la propria connessione viene scritto qualunque cosa dica questa impostazione. Qualsiasi altro valore arresta l’importazione, che non genera in bozza nulla, con unknown-empty-credentials. Una bozza fatta nodo per nodo non legge alcun valore, e quindi non legge questa impostazione.
attach_egress_allowlistfalsetrue associa la Feature core/egress-allowlist della libreria standard a ciascuna istanza di piattaforma che la bozza scrive, come egress-allowlist, senza impostare nulla del suo infra, come descrive Ciò che la bozza lascia alla Release. false non associa nulla. Una bozza che non scrive alcuna piattaforma, con layout: nodes, e la bozza dell’importatore Dify, la cui voce per l’installazione Dify non accetta alcuna Feature, non associano nulla qualunque cosa dica questa impostazione, e con essa a true l’importazione emette l’avviso feature-not-attached. Qualsiasi valore che non sia un booleano viene letto come false.

Un’impostazione che un importatore non conosce viene ignorata.

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

Che cosa riporta un’importazione

Ciascun importatore core riporta come diagnostiche ciò che non è riuscito a fare e ciò che ha fatto per conto dell’autore. Il comando stampa ciascuna sullo standard error come <severity>: <message>, prima della riga di ciascun nodo; il metodo aggrega/import della sessione dell’editor e lo strumento import dell’assistente restituiscono ciascuna anche con il suo code.

CodiceSeveritàRiportata quando
parse-failedhaltLa sorgente non supera l’analisi: il suo parser la rifiuta, e il messaggio riporta il motivo indicato dal parser.
no-nodeswarnLa sorgente non contiene alcun nodo che l’importatore riconosce — per l’importatore MCP, nessun server, per l’importatore Compose, nessun servizio e nessun modello, per l’importatore CrewAI, una crew che non dichiara alcun agente, per l’importatore LangGraph, una configurazione che non dichiara alcun grafo, per l’importatore Google ADK, una configurazione radice che non dichiara alcun agente, oppure nessuno dei file che with.sources passa a un’importazione contiene una configurazione radice, e per l’importatore Agent Framework, una sorgente che non dichiara alcun agente prompt.
unknown-layoutwarnlayout non è né platform né nodes; il flusso viene generato in bozza come platform.
unknown-empty-credentialshaltempty_credentials contiene un valore diverso da none, marked o all, nominato insieme all’impostazione; l’importazione non genera nulla in bozza.
platform-not-in-catalogwarnIl catalogo del workspace non contiene alcun Component con il nome della piattaforma, quindi nessuna parte vi viene collegata; per l’importatore Dify, nessun core/ai-agent/dify, e core/dify viene assemblato comunque.
part-not-placedwarnUna parte del flusso non è collegata ad alcun socket della piattaforma, con il motivo; rimane nel flusso.
socket-selector-unreadablewarnIl selettore che un socket della piattaforma dichiara non è leggibile, quindi nessuna parte vi viene collegata; una volta per ciascun socket.
credential-carriedwarnUn valore di credenziale viene portato com’è scritto nel flusso che la bozza porta, o nella Release che l’importatore MCP, Compose, CrewAI, LangGraph, Google ADK o Agent Framework genera in bozza, nominato tramite il suo nodo — o il suo server, servizio, agente o configurazione — e il suo campo, mai tramite il suo valore, insieme al valore di empty_credentials che lo scrive vuoto.
credential-emptiedwarnUn valore di credenziale viene scritto vuoto nel flusso che la bozza porta, o nella Release che l’importatore MCP, Compose, CrewAI, LangGraph, Google ADK o Agent Framework genera in bozza, dove empty_credentials lo richiede, nominato tramite il suo nodo — o il suo server, servizio, agente o configurazione — e il suo campo.
carriage-returns-rewrittenwarnI ritorni a capo del flusso vengono scritti come avanzamenti di riga, indicando quanti sono.
definition-respelledwarnI valori del flusso vengono scritti nella grafia in cui li leggono gli strumenti propri della piattaforma, con gli stessi valori, indicando quali e perché: gli handle degli archi di un flusso Langflow, scritti come li scrive l’editor di Langflow. Un valore che la bozza scrive affinché il flusso raggiunga una parte, o uno che può contenere una credenziale, non viene mai riscritto in un’altra grafia — resta quello del collegamento, o quello di empty_credentials — e l’avviso conta ciascun valore non riscritto.
definition-not-carriedwarnIl flusso non viene portato in values.flow_definition, o l’applicazione dell’importatore Dify in parameters.app_definition, con il motivo.
part-reads-connectionwarnCome il flusso raggiunge una parte collegata attraverso la sua connessione, o come una connessione raggiunge, così com’è scritta, un nodo che la bozza non collega ad alcun socket.
part-address-in-flowwarnIl flusso raggiunge una parte collegata per una via diversa dalla sua connessione, indicando quale.
model-not-namedwarnvalues.model di una parte referenziata viene lasciato all’autore, con il motivo.
feature-attachedinfoattach_egress_allowlist ha associato core/egress-allowlist a una piattaforma generata in bozza, con ciò che di essa la Release imposta; una volta per ciascuna istanza di piattaforma.
feature-not-attachedwarnattach_egress_allowlist è true e la bozza non scrive alcuna piattaforma, oppure assembla l’installazione Dify, la cui voce non accetta alcuna Feature, quindi non viene associato nulla.
part-configured-in-platformwarnUn nodo di un’applicazione Dify nomina ciò che Dify configura per sé — un modello e il suo provider, uno strumento, una knowledge base, una strategia di agente, un plugin — quindi la bozza non collega alcuna parte per esso.
dsl-version-newerwarnUn’applicazione Dify è scritta in una versione del DSL più recente di quella che scrive la versione di Dify eseguita per impostazione predefinita da core/ai-agent/dify.

Un’importazione a cui viene dato un target riporta, dopo le diagnostiche dell’importatore, ciò che la generazione in bozza del Manifest ha rilevato: un warn che nomina ciascun tipo di componente o di feature che il Manifest lascia non mappato e il motivo, e un info dove la Release generata in bozza nomina già un Manifest o nessuna Release generata in bozza lo referenzia. Queste sono dell’importazione stessa anziché di un importatore, e non portano alcun codice; Che cosa aggiunge un target le descrive. Ogni importazione riporta poi, anche questi come propri, un warn per ciascun valore che le bozze devono ancora, che nomina il file in bozza, il percorso della chiave e la sua descrizione, e, con --offline, dove ha generato in bozza una Release e non deve nulla, un info che nomina l’aggrega pull da eseguire dopo, come descrive Il file delle risposte dell’importazione.

Pubblicati con ogni release del compilatore

Ogni release del compilatore compila i dieci importatori dai sorgenti con tag e genera le loro entità Plugin dagli importatori stessi, così la capacità, le firme di riconoscimento, le funzioni host e la descrizione di un’entità sono ciò che il suo importatore riporta. La release firma e pubblica tutti e dieci, importer/langflow, importer/flowise, importer/n8n, importer/mcp, importer/compose, importer/dify, importer/crewai, importer/langgraph, importer/google-adk e importer/agent-framework, alla versione della release, accanto agli altri plugin core, e registra le loro entità insieme alle entità degli altri plugin core per il catalogo standard.