Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

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 import

brouillons 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 --sync met à 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ètre empty_credentials de 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.

  1. 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.yaml avec une clé workspace — ou sous le répertoire que nomme --output-dir. Elle n’écrase jamais un Aggregate déjà présent.

  2. 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 --target rédige un Manifest à partir des Recipes du catalogue. Sans catalogue, l’importation n’a rien à mettre en correspondance, et --target est 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 dossier catalog à la racine de l’espace de travail, ou les répertoires que nomme AGGREGA_CATALOG_DIRS. Les fichiers propres du catalogue de la bibliothèque standard sont le dossier aggrega-catalog du dépôt aggrega-hub, https://github.com/aggrega-ai/aggrega-hub, pour un espace de travail qui les veut sous forme de dossier. --upgrade ré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.

  3. Lancez l’importation. Nommez le fichier ou le répertoire :

    Terminal window
    aggrega import compose.yaml --target compose

    Le format est reconnu d’après le nom et le contenu du fichier ; --format le nomme lorsqu’il ne l’est pas. --target nomme une capacité de fournisseur, comme compose ou helm, 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 : sur compose, un secret est une référence de variable que Docker Compose renseigne depuis votre shell ; sur helm, 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.

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

  5. 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 écrit release.lock à côté. Sous --offline, elle ne récupère rien et nomme la commande aggrega pull à exécuter.

  6. Validez et compilez. Dans le dossier contenant les brouillons :

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

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

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

    Sans -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, avec docker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, ou depuis un conteneur que vous démarrez sur ce réseau avec docker 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/openai pointe 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 type core/ai-model/ollama, avec model: qwen2.5:0.5b dans ses values ;
    • dans le Manifest, sa Recipe Compose : core/ai-model/ollama: compose/ollama ;
    • dans la Release, local-model: {}, et la clé endpoint du modèle OpenAI, sous son infra, 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 exemple gpt-4o-mini ou gpt-4.1 : docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.

    OPENAI_API_KEY peut 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 fournit endpoint ; donnez donc aussi à ces identifiants l’adresse du serveur, sous la forme d’un url à côté de apiKey dans leurs data. Le serveur Ollama qu’exécute par défaut core/ai-model/ollama sert la Responses API d’OpenAI ainsi que Chat Completions, si bien qu’un agent déclaratif Agent Framework qui indique apiType: Responses l’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 : sous dist/helm/ ou, pour les composants qu’une Release place dans une frontière, sous dist/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 contexte kubectl, ou dans default s’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/

    -R atteint les fichiers de ces dossiers. Un Service ClusterIP, 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 avec kubectl port-forward svc/<service> <local port>:<port>, qui s’exécute jusqu’à ce que vous l’arrêtiez.

À 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

FormatCe qu’il litTutoriel
Composeun fichier Compose et son fichier de surcharge, ou un répertoire qui les contientImporter 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 MCPImporter la configuration d’un client MCP
Langflowun flux exporté depuis Langflow, en JSONImporter un flux Langflow
Flowiseun chatflow ou un agentflow exporté depuis Flowise, en JSONImporter un chatflow Flowise
n8nun workflow exporté depuis n8n, en JSONImporter un workflow n8n
Difyune application exportée depuis Dify dans son DSL, en YAMLImporter une application Dify
CrewAIles déclarations d’agents et de tâches d’un projet CrewAIImporter un projet CrewAI
LangGraphle langgraph.json d’une application LangGraphImporter une application LangGraph
Google ADKles fichiers Agent Config d’une application construite sur Google ADK, à partir de root_agent.yamlImporter un agent Google ADK
Microsoft Agent Frameworkun agent déclaratif, un document YAML de type PromptImporter 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.