Importation
aggrega import lit un projet écrit dans un autre format — un flux exporté depuis Langflow, la configuration d’un client MCP, un fichier Compose et les autres formats listés ci-dessous — et en tire des fichiers Aggrega : un Aggregate, une Release et, pour la cible que nomme --target, un Manifest. Ensemble, ils forment un espace de travail qui se valide et se compile tel qu’il est écrit, une fois renseignées les quelques valeurs qu’aucune source ne peut contenir : l’importation demande chacune d’elles une seule fois et conserve les réponses dans un fichier de réponses. Il ne déploie rien et n’atteint aucun cluster ni aucun compte cloud. Les brouillons sont de simples fichiers dans votre espace de travail, et ce qu’il en advient ensuite ne dépend que de vous.
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importbrouillons de fichiers Aggrega
à relire et à modifier
Votre projet existant en entrée, des brouillons de fichiers Aggrega en sortie. Rien n’est déployé ; vous relisez d’abord les brouillons.
Ce qu’il vous apporte
- Votre projet arrive dans Aggrega sans être réécrit à la main. L’Aggregate, la Release et le Manifest rédigés sont le même type de fichiers que ceux que vous écririez vous-même. Ils se compilent tels qu’ils sont écrits pour la cible que nomme l’importation, et chaque politique de gouvernance que votre espace de travail attache juge cette compilation comme n’importe quelle autre.
- Ce que la source énonce est repris. Un nœud ou un service pour lequel le catalogue contient une correspondance forte référence ce Component du catalogue, avec les valeurs que la source lui donne, comme le modèle que nomme un flux. Une plateforme sur laquelle la source s’exécute est rédigée avec l’image qu’exécutent les Recipes du catalogue pour cette plateforme. Un secret est rédigé comme une référence à sa provenance, jamais comme sa valeur.
- Seul ce qu’aucune source ne peut contenir vous est demandé, une seule fois. Les réponses sont conservées dans un fichier de réponses à côté de la source, si bien que l’importation suivante de la même source ne demande rien.
- Les brouillons vous appartiennent. Ce sont de simples fichiers YAML dans votre espace de travail, et il ne reste derrière eux rien dont la compilation dépende. Modifiez-les, renommez-les, committez-les.
- Le brouillon peut suivre sa source.
aggrega import --syncmet à jour les brouillons d’une importation antérieure par rapport à une source modifiée, en ne changeant que ce que l’importation a écrit. Là où la source a changé une partie que vous avez modifiée, il s’arrête et nomme cette partie plutôt que d’écraser votre modification.
Ce qu’elle ne fait pas
Une importation rédige ce que la source énonce et ce que votre catalogue détermine, et demande le reste. Chaque brouillon indique, dans un commentaire à côté de la valeur, d’où provient une valeur qu’il a rédigée.
- Elle ne devine pas ce que votre source ne peut pas énoncer. Aucune source ne nomme l’environnement sur lequel une Release est déployée ; la Release rédigée nomme donc
development, avec un commentaire indiquant qu’il s’agit d’une valeur par défaut à modifier. Une valeur que le catalogue exige et qu’aucune source ne contient — l’adresse e-mail du compte d’un propriétaire, l’image d’une application construite à partir de votre propre code, le nom d’un Secret Kubernetes — est rédigée vide et demandée, comme le décrit Déroulement d’une importation ci-dessous. - Elle ne lit pas de code. Le programme propre d’un flux ou d’un projet n’est pas lu : le programme d’une crew CrewAI, le code du graphe d’une application LangGraph, le code source d’un composant Langflow, si ce n’est pour le transporter à l’intérieur du flux.
- Elle ne juge pas ce que signifie une valeur. Chaque nœud ou service est comparé aux Components du catalogue de votre espace de travail — leurs noms, leurs catégories, leurs étiquettes et les noms des valeurs qu’ils déclarent. Une correspondance du niveau élevé est référencée dans le brouillon ; une correspondance plus faible est écrite comme un commentaire nommant le Component et son score, pour que vous choisissiez.
- Elle ne change pas la version qu’exécute une plateforme pour suivre la source. L’image d’une plateforme est rédigée à la version que les Recipes du catalogue pour cette plateforme sont connues pour exécuter, et lorsque la source nomme une autre version, un commentaire à côté de l’image la nomme.
- Elle ne retire pas les identifiants de votre source à votre place. Une valeur susceptible de contenir une clé — une valeur d’environnement, un en-tête, la ligne de commande d’un serveur MCP — est reportée par défaut dans le brouillon telle qu’elle est écrite, et l’importation nomme chacune dans un avertissement
credential-carried, jamais par sa valeur. Le paramètreempty_credentialsde l’importateur les écrit vides à la place (Paramètres). Lisez les avertissements avant de partager un brouillon. - Elle ne déploie ni n’exécute rien. Elle lit la source et votre catalogue, et écrit des fichiers. Compiler les brouillons et exécuter ce que la compilation écrit sont des étapes distinctes que vous effectuez.
Déroulement d’une importation
Vous pouvez exécuter une importation avec les commandes ci-dessous, ou la faire exécuter par votre assistant IA.
-
Partez d’un espace de travail. Une importation écrit ses brouillons sous la racine de l’espace de travail dans lequel elle s’exécute — le dossier contenant un
.aggrega-config.yamlavec une cléworkspace— ou sous le répertoire que nomme--output-dir. Elle n’écrase jamais un Aggregate déjà présent. -
Le catalogue de comparaison. L’importation évalue votre source par rapport aux Components du catalogue de l’espace de travail, et à rien d’autre. Lorsque l’espace de travail ne nomme aucun dossier de catalogue qui lui soit propre, il s’agit du catalogue de la bibliothèque standard, lu depuis le registre par défaut de l’espace de travail : chaque publication du catalogue publie un instantané signé de sa totalité, et la première importation récupère cet instantané, vérifie sa signature, le conserve dans le cache de contenu de l’espace de travail et le nomme par son condensé dans l’enregistrement qu’elle écrit à côté des brouillons, de sorte qu’une importation ultérieure des mêmes brouillons lit le même catalogue sans interroger de nouveau le registre. Par rapport à lui, un service PostgreSQL est mis en correspondance avec
core/datastore/postgres, et--targetrédige un Manifest à partir des Recipes du catalogue. Sans catalogue, l’importation n’a rien à mettre en correspondance, et--targetest refusé, puisqu’aucune Recipe n’est liée à la cible.Un espace de travail qui nomme ses propres dossiers de catalogue importe plutôt par rapport à ceux-ci, et ne récupère aucun instantané : les répertoires que liste
workspace.catalog_dirs, un dossiercatalogà la racine de l’espace de travail, ou les répertoires que nommeAGGREGA_CATALOG_DIRS. Les fichiers propres du catalogue de la bibliothèque standard sont le dossieraggrega-catalogdu dépôtaggrega-hub, https://github.com/aggrega-ai/aggrega-hub, pour un espace de travail qui les veut sous forme de dossier.--upgraderécupère l’instantané le plus récent que publie le registre et importe par rapport à lui à partir de ce moment ; sous--offline, une importation qui devrait récupérer un instantané s’arrête et nomme ce qu’il faut exécuter. -
Lancez l’importation. Nommez le fichier ou le répertoire :
Terminal window aggrega import compose.yaml --target composeLe format est reconnu d’après le nom et le contenu du fichier ;
--formatle nomme lorsqu’il ne l’est pas.--targetnomme une capacité de fournisseur, commecomposeouhelm, et rédige un Manifest associant chaque type de composant et chaque type de fonctionnalité dont les brouillons ont besoin à la Recipe de cette capacité que votre catalogue propose pour lui : celle qui existe ou, parmi plusieurs, celle qui porte le nom du type. La Release rédigée nomme ce Manifest, et ce que contiennent les brouillons suit la cible : surcompose, un secret est une référence de variable que Docker Compose renseigne depuis votre shell ; surhelm, le nom d’un Secret Kubernetes. Sur la sortie d’erreur standard, l’importation nomme le format qu’elle a lu, chaque avertissement et une ligne pour chaque nœud qu’elle a mis en correspondance ; sur la sortie standard, elle liste les fichiers qu’elle a écrits. -
Répondez à ce qu’aucune source ne contient. Une valeur que le catalogue exige et qu’aucune source ne peut contenir — l’adresse e-mail du compte d’un propriétaire, l’image d’une application construite à partir de votre propre code, le nom d’un Secret Kubernetes — reçoit une réponse une seule fois. L’importation lit les réponses dans
import-answers.yamlà côté de la source, ou dans le fichier que nomme--answers; dans un terminal, elle demande chaque valeur encore manquante, une question à la fois, et écrit vos réponses dans ce fichier. À un secret, on répond par sa provenance — une variable ou le nom d’un Secret — jamais par sa valeur. Là où rien ne peut être demandé — en intégration continue, via un pipe, depuis l’assistant ou l’éditeur — l’importation écrit le fichier de réponses avec la clé de chaque valeur manquante et une réponse vide, les liste et se termine avec le statut 1 ; remplissez-les et exécutez de nouveau l’importation. Un seul fichier de réponses sert toutes les cibles : une réponse dont les brouillons d’une cible n’ont pas besoin est conservée dans le fichier et reste inutilisée. Le fichier de réponses de l’importation décrit le fichier en entier. -
L’importation récupère ce dont la compilation a besoin. Une fois que plus rien ne manque, l’importation récupère les dépendances de la Release rédigée, comme le fait
aggrega pull, et écritrelease.lockà côté. Sous--offline, elle ne récupère rien et nomme la commandeaggrega pullà exécuter. -
Validez et compilez. Dans le dossier contenant les brouillons :
Terminal window aggrega validate --release release.yamlaggrega build --release release.yamlLorsque les deux réussissent, la compilation a écrit les fichiers de la cible sous
dist/. Un refus nomme ce qu’il faut modifier et où, dans le document que vous modifiez. -
Exécutez ce que le build a écrit. Un build pour Docker Compose écrit
dist/compose/docker-compose.yaml, et le fichier ne nomme aucun projet Compose ; nommez-en donc un avec-p:Terminal window docker compose -p <name> -f dist/compose/docker-compose.yaml up -dSans
-p, Docker Compose nomme le projet d’après le dossier qui contient le fichier,compose, de sorte que deux espaces de travail démarrés ainsi partagent un même projet. Les services se trouvent sur un seul réseau, que Docker Compose nomme d’après le projet,<name>_compose. Un service pour lequel le build ne publie aucun port est joint depuis l’intérieur de ce réseau, avecdocker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, ou depuis un conteneur que vous démarrez sur ce réseau avecdocker run --network <name>_compose …. Les sections « Exécuter » et « Tester » d’un tutoriel pas à pas montrent les commandes de son propre build.Une exécution répond sans clé OpenAI dès que son modèle
core/ai-model/openaipointe vers un petit modèle servi par Ollama dans le même projet, avec trois modifications des fichiers rédigés, une compilation avec--auto-pull, qui récupère ce dont le composant ajouté a besoin, et une commande une fois la pile démarrée :- dans l’Aggregate, un composant de plus, relié à rien :
local-model, de typecore/ai-model/ollama, avecmodel: qwen2.5:0.5bdans sesvalues; - dans le Manifest, sa Recipe Compose :
core/ai-model/ollama: compose/ollama; - dans la Release,
local-model: {}, et la cléendpointdu modèle OpenAI, sous soninfra, définie sur l’adresse compatible OpenAI de ce serveur,http://local-model:11434/v1; - une fois la pile lancée, le modèle téléchargé copié sous le nom de modèle que désigne le modèle OpenAI du build,
<model>, par exemplegpt-4o-miniougpt-4.1:docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.
OPENAI_API_KEYpeut alors contenir n’importe quelle valeur non vide de votre choix : le serveur local n’en vérifie aucune. Un workflow n8n lit l’adresse et la clé du modèle dans les identifiants que sélectionne son nœud de modèle, et non dans l’adresse que fournitendpoint; donnez donc aussi à ces identifiants l’adresse du serveur, sous la forme d’unurlà côté deapiKeydans leursdata. Le serveur Ollama qu’exécute par défautcore/ai-model/ollamasert la Responses API d’OpenAI ainsi que Chat Completions, si bien qu’un agent déclaratif Agent Framework qui indiqueapiType: Responsesl’atteint tel qu’il est écrit.Un build pour Kubernetes, la cible
helm, écrit de simples manifestes plutôt qu’un chart, comme le décrit le fournisseur helm : sousdist/helm/ou, pour les composants qu’une Release place dans une frontière, sousdist/boundaries/<boundary>/helm/, certains d’entre eux dans un dossier propre en dessous. Les fichiers qui ne nomment aucun namespace, comme ceux des builds MCP et Dify, vont dans celui que nomme votre contextekubectl, ou dansdefaults’il n’en nomme aucun ; créez d’abord à cet endroit les Secrets qu’ils lisent, puis appliquez le dossier :Terminal window kubectl apply -R -f dist/helm/-Ratteint les fichiers de ces dossiers. Un ServiceClusterIP, le type que les builds MCP et Dify donnent aux serveurs qu’ils exécutent, n’est joignable que depuis l’intérieur du cluster : pour en joindre un depuis votre machine, redirigez-y un port local aveckubectl port-forward svc/<service> <local port>:<port>, qui s’exécute jusqu’à ce que vous l’arrêtiez. - dans l’Aggregate, un composant de plus, relié à rien :
À côté de ses brouillons, l’importation écrit .aggrega-import.json, l’enregistrement de ce qu’elle a écrit. Conservez-le aussi longtemps que vous comptez exécuter aggrega import --sync, qui le lit pour distinguer vos modifications des siennes. Conservez aussi le fichier de réponses : il ne contient aucun secret, il peut donc être versionné à côté de la source, et chaque importation ultérieure de cette source le lit.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-y ce prompt.
Utilise uniquement les outils Aggrega et ne crée aucun dossier toi-même. Appelle l’outil `import` avec `source` défini sur `compose.yaml` et `target` défini sur `compose` : il écrit ses brouillons dans le dossier Workspace. S’il indique que des valeurs sont encore dues, donne-moi chacune d’elles et ce qu’elle représente, et attends pendant que j’écris mes réponses à côté de leurs clés dans le fichier de réponses qu’il nomme ; puis appelle à nouveau l’outil `import` de la même façon. Appelle ensuite l’outil `validate` avec `release` défini sur `release.yaml`, et l’outil `build` avec `release` défini sur `release.yaml` et `write` défini sur true. Dis-moi quels fichiers le build a écrits ; ils se trouvent sous `dist/` dans le dossier Workspace.L’ouvrir dans VS Code
Avec l’extension Aggrega pour Visual Studio Code installée, ouvrez dans VS Code le workspace dans lequel l’importation a été exécutée — le dossier qui contient son .aggrega-config.yaml : les brouillons s’y trouvent, à sa racine ou dans le dossier nommé par --output-dir. Là où le workspace contient une seule Release, l’éditeur la sélectionne pour vous ; là où il en contient plusieurs, Aggrega: Select Release… choisit celle sur laquelle travaille l’éditeur. L’éditeur vérifie les brouillons par rapport à la Release sélectionnée pendant que vous les modifiez, en signalant ce qu’il trouve dans le fichier et dans le panneau Problèmes. Aggrega: Show topology graph, dans la palette de commandes, dessine les composants de la Release sélectionnée et les connexions entre eux. Aggrega: Build, Aggrega: Preview build et Aggrega: Pull agissent sur la même Release, et chacune est aussi un bouton du panneau Commands de la vue Aggrega dans la barre d’activité ; Build écrit ses fichiers dans le dist/ du workspace. Utiliser Aggrega dans Visual Studio Code couvre le reste.
D’où viennent les importateurs
Chaque format est lu par un plugin importateur. Les importateurs de base du compilateur, un pour chaque format du tableau ci-dessous, sont publiés avec chaque version du compilateur et servent leurs formats dans chaque espace de travail, sans entrée dans votre catalogue. La première importation qui en a besoin le récupère depuis le registre par défaut de l’espace de travail, dans la version même du compilateur, le vérifie et le conserve dans le cache de contenu de l’espace de travail, de sorte que chaque importation ultérieure le lit depuis ce cache, sans recourir au réseau pour lui. Lorsque le module ne peut pas être récupéré du tout — parce que l’espace de travail est hors ligne, par exemple — l’importation s’arrête et nomme les deux façons de le placer sur la machine. Importateurs de base décrit chaque importateur en détail, ainsi que les paramètres qu’un importateur reçoit via une entrée plugins.importer.
Les formats
| Format | Ce qu’il lit | Tutoriel |
|---|---|---|
| Compose | un fichier Compose et son fichier de surcharge, ou un répertoire qui les contient | Importer un projet Compose |
| Configurations de clients MCP | .mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json ou un server.json d’un registre MCP | Importer la configuration d’un client MCP |
| Langflow | un flux exporté depuis Langflow, en JSON | Importer un flux Langflow |
| Flowise | un chatflow ou un agentflow exporté depuis Flowise, en JSON | Importer un chatflow Flowise |
| n8n | un workflow exporté depuis n8n, en JSON | Importer un workflow n8n |
| Dify | une application exportée depuis Dify dans son DSL, en YAML | Importer une application Dify |
| CrewAI | les déclarations d’agents et de tâches d’un projet CrewAI | Importer un projet CrewAI |
| LangGraph | le langgraph.json d’une application LangGraph | Importer une application LangGraph |
| Google ADK | les fichiers Agent Config d’une application construite sur Google ADK, à partir de root_agent.yaml | Importer un agent Google ADK |
| Microsoft Agent Framework | un agent déclaratif, un document YAML de type Prompt | Importer un agent déclaratif Microsoft Agent Framework |
aggrega import est la référence complète de la commande : chaque option, la manière dont une source est reconnue, ce que --sync modifie et ce qu’il refuse. Le fichier de réponses de l’importation décrit le fichier de réponses : où il se trouve, ce qu’il contient et comment on répond à un secret.