Skip to content
AggregaAggrega
Select language: English

Import

aggrega import reads a project written in another format — a flow exported from Langflow, an MCP client’s configuration, a Compose file, and the other formats listed below — and writes Aggrega files from it: an Aggregate, a Release, and, for the target --target names, a Manifest. Together they are a workspace that validates and builds as written, once the few values no source can hold are answered: the import asks for each of them once and keeps the answers in an answers file. It deploys nothing and reaches no cluster or cloud account. The drafts are plain files in your workspace, and what happens to them next is up to you.

  • LangGraph
  • CrewAI
  • n8n
  • Dify
  • Langflow
  • Flowise
  • Google ADK
  • Microsoft Agent Framework
  • MCP client configurations
  • Compose
aggrega import

draft Aggrega files

for you to review and edit

Your existing project in, draft Aggrega files out. Nothing is deployed; you review the drafts first.

What it gives you

  • Your project reaches Aggrega without being rewritten by hand. The drafted Aggregate, Release and Manifest are the same kind of files you would write yourself. They build for the target the import names as they are written, and every governance policy your workspace attaches judges that build like any other.
  • What the source states is carried over. A node or service the catalog holds a strong match for references that catalog Component, with the values the source gives it, such as the model a flow names. A platform the source runs on is drafted with the image the catalog’s Recipes for it run. A secret is drafted as a reference to where it comes from, never as its value.
  • You are asked only for what no source can hold, once. The answers are kept in an answers file beside the source, so the next import of the same source asks nothing.
  • The drafts are yours. They are plain YAML in your workspace, with nothing left behind that the build depends on. Edit them, rename them, commit them.
  • The draft can follow its source. aggrega import --sync brings an earlier import’s drafts up to date with a changed source, changing only what the import wrote. Where the source changed a part you edited, it stops and names the part rather than writing over your edit.

What it does not do

An import drafts what the source states and what your catalog determines, and asks for the rest. Each draft says, in a comment beside the value, where a value it drafted came from.

  • It does not guess what your source cannot state. No source names the environment a Release deploys to, so the drafted Release names development, with a comment saying it is a default to change. A value the catalog requires and no source holds — an owner account’s email, the image of an application built from your own code, the name of a Kubernetes Secret — is drafted empty and asked for, as How an import runs below describes.
  • It does not read code. A flow’s or a project’s own program is not read: a CrewAI crew’s program, a LangGraph application’s graph code, a Langflow component’s source beyond carrying it inside the flow.
  • It does not judge what a value means. Each node or service is weighed against the Components of your workspace’s catalog — their names, their categories, their labels and the names of the values they declare. A match in the high tier is referenced in the draft; a weaker one is written as a comment naming the Component and its score, for you to choose.
  • It does not change the version a platform runs to follow the source. A platform’s image is drafted at the version the catalog’s Recipes for it are known to run, and where the source names another version, a comment beside the image names it.
  • It does not move credentials out of your source for you. A value that can carry a key — an environment value, a header, an MCP server’s command line — is carried into the draft as written by default, and the import names each one in a credential-carried warning, never by its value. The importer’s empty_credentials setting writes them empty instead (Settings). Read the warnings before you share a draft.
  • It does not deploy or run anything. It reads the source and your catalog, and writes files. Building the drafts, and running what the build writes, are separate steps you take.

How an import runs

You can run an import with the commands below, or have your AI assistant run it for you.

  1. Start from a workspace. An import writes its drafts beneath the root of the workspace it runs in — the folder holding an .aggrega-config.yaml with a workspace key — or beneath the directory --output-dir names. It never writes over an Aggregate already there.

  2. The catalog it weighs against. The import scores your source against the Components of the workspace’s catalog, and nothing else. Where the workspace names no catalog folder of its own, that is the standard-library catalog, read from the workspace’s default registry: every publish of the catalog publishes a signed snapshot of the whole of it, and the first import fetches that snapshot, verifies its signature, keeps it in the workspace’s content cache and names it by its digest in the record it writes beside the drafts, so a later import of the same drafts reads the same catalog without asking the registry again. Against it, a PostgreSQL service is matched to core/datastore/postgres, and --target drafts a Manifest from the catalog’s Recipes. With no catalog, the import has nothing to match, and --target is refused, since no Recipe binds to the target.

    A workspace that names its own catalog folders imports against those instead, and fetches no snapshot: the directories workspace.catalog_dirs lists, a catalog folder at the workspace root, or the directories AGGREGA_CATALOG_DIRS names. The standard-library catalog’s own files are the aggrega-catalog folder of the aggrega-hub repository, https://github.com/aggrega-ai/aggrega-hub, for a workspace that wants them as a folder. --upgrade fetches the newest snapshot the registry publishes and imports against it from then on; under --offline, an import that would have to fetch a snapshot stops and names what to run.

  3. Run the import. Name the file or the directory:

    Terminal window
    aggrega import compose.yaml --target compose

    The format is recognised from the file’s name and contents; --format names it where it is not. --target names a provider capability, such as compose or helm, and drafts a Manifest mapping each component type and feature type the drafts need to the Recipe of that capability your catalog offers for it: the one there is, or, among several, the one named after the type. The drafted Release names that Manifest, and what the drafts carry follows the target: on compose a secret is a variable reference Docker Compose fills from your shell, on helm the name of a Kubernetes Secret. On standard error the import names the format it read, each warning, and one line for each node it mapped; on standard output it lists the files it wrote.

  4. Answer what no source holds. A value the catalog requires that no source can hold — an owner account’s email, the image of an application built from your own code, the name of a Kubernetes Secret — is answered once. The import reads the answers from import-answers.yaml beside the source, or from the file --answers names; at a terminal it asks for each value still missing, one question at a time, and writes your answers into that file. A secret is answered with where it comes from — a variable or a Secret’s name — never with its value. Where nothing can be asked — in continuous integration, through a pipe, from the assistant or the editor — the import writes the answers file with each missing value’s key and an empty answer, lists them, and exits with status 1; fill them in and run the import again. One answers file serves every target: an answer the drafts for one target do not need is kept in the file and left unused. The import answers file describes the file in full.

  5. The import pulls what the build needs. Once nothing is missing, the import pulls the drafted Release’s dependencies, as aggrega pull does, and writes release.lock beside it. Under --offline it pulls nothing and names the aggrega pull command to run.

  6. Validate and build. In the folder holding the drafts:

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

    When both pass, the build has written the target’s files under dist/. A refusal names what to change and where, in the document you change.

  7. Run what the build wrote. A build for Docker Compose writes dist/compose/docker-compose.yaml, and the file names no Compose project, so name one with -p:

    Terminal window
    docker compose -p <name> -f dist/compose/docker-compose.yaml up -d

    Without -p, Docker Compose names the project after the folder holding the file, compose, so two workspaces started that way share one project. The services sit on one network, which Docker Compose names after the project, <name>_compose. A service the build publishes no port for is reached from inside it, with docker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, or from a container you start on that network with docker run --network <name>_compose …. A walkthrough’s “Run it” and “Test it” sections show the commands for its own build.

    A run answers without an OpenAI key once its core/ai-model/openai model points at a small model served by Ollama in the same project, with three changes to the drafted files, a build with --auto-pull, which pulls what the added component needs, and one command once the stack runs:

    • in the Aggregate, one more component, wired to nothing: local-model, of type core/ai-model/ollama, with model: qwen2.5:0.5b in its values;
    • in the Manifest, its Compose Recipe: core/ai-model/ollama: compose/ollama;
    • in the Release, local-model: {}, and the OpenAI model’s endpoint, under its infra, set to that server’s OpenAI-compatible address, http://local-model:11434/v1;
    • once the stack runs, the pulled model copied under the model name the build’s OpenAI model names, <model>, such as gpt-4o-mini or 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 may then hold any non-empty value of your own: the local server checks none. An n8n workflow reads the model’s address and key from the credential its model node selects, not from the address endpoint delivers, so give that credential the server’s address too, as a url beside apiKey in its data. The Ollama server core/ai-model/ollama runs by default serves OpenAI’s Responses API as well as Chat Completions, so an Agent Framework declarative agent that names apiType: Responses reaches it as written.

    A build for Kubernetes, the helm target, writes plain manifests rather than a chart, as the helm provider describes: under dist/helm/, or, for the components a Release places in a boundary, under dist/boundaries/<boundary>/helm/, some of them in a folder of their own beneath. Files that name no namespace, as the MCP and Dify builds’ do, go to the one your kubectl context names, or to default where it names none; create the Secrets they read there first, then apply the folder:

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

    -R reaches the files in those folders. A ClusterIP Service, the kind the MCP and Dify builds give the servers they run, is reachable from inside the cluster only: reach one from your machine by forwarding a local port to it, with kubectl port-forward svc/<service> <local port>:<port>, which runs until you stop it.

Beside its drafts, the import writes .aggrega-import.json, the record of what it wrote. Keep it for as long as you mean to run aggrega import --sync, which reads it to tell your edits from its own. Keep the answers file too: it holds no secret, so it can live in version control beside the source, and every later import of that source reads it.

With an AI assistant

An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.

Use the Aggrega tools only, and create no folder yourself. Call the `import` tool with `source` set to `compose.yaml` and `target` set to `compose`: it writes its drafts into the Workspace folder. If it says values are still owed, tell me each one and what it is, and wait while I write my answers beside their keys in the answers file it names; then call the `import` tool again the same way. Then call the `validate` tool with `release` set to `release.yaml`, and the `build` tool with `release` set to `release.yaml` and `write` set to true. Tell me which files the build wrote; they are under `dist/` in the Workspace folder.

Open it in VS Code

With the Aggrega extension for Visual Studio Code installed, open the workspace the import ran in — the folder holding its .aggrega-config.yaml — in VS Code: the drafts are in it, at its root or in the folder --output-dir named. Where the workspace holds one Release, the editor selects it for you; where it holds more, Aggrega: Select Release… chooses the one the editor works on. The editor checks the drafts against the selected Release as you edit them, marking what it finds in the file and in the Problems panel. Aggrega: Show topology graph, in the Command Palette, draws the selected Release’s components and the connections between them. Aggrega: Build, Aggrega: Preview build and Aggrega: Pull act on the same Release, and each is also a button on the Commands panel of the Aggrega view in the activity bar; Build writes its files into the workspace’s dist/. Use Aggrega in Visual Studio Code covers the rest.

Where the importers come from

Each format is read by an importer plugin. The compiler’s core importers, one for each format in the table below, are published with every compiler release and serve their formats in every workspace, with no entry in your catalog. The first import that needs one fetches it from the workspace’s default registry, at the compiler’s own version, verifies it and keeps it in the workspace’s content cache, so every later import reads it from there, with no network for it. Where the module cannot be fetched at all — the workspace is offline, say — the import stops and names the two ways to put it on the machine. Core importers describes each importer in full, and the settings an importer is given through a plugins.importer entry.

The formats

FormatWhat it readsWalkthrough
Composea Compose file and its override file, or a directory holding themImport a Compose project
MCP client configurations.mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json, or an MCP registry server.jsonImport an MCP client configuration
Langflowa flow exported from Langflow, as JSONImport a Langflow flow
Flowisea chatflow or an agentflow exported from Flowise, as JSONImport a Flowise chatflow
n8na workflow exported from n8n, as JSONImport an n8n workflow
Difyan application exported from Dify in its DSL, as YAMLImport a Dify application
CrewAIa CrewAI project’s agent and task declarationsImport a CrewAI project
LangGrapha LangGraph application’s langgraph.jsonImport a LangGraph application
Google ADKthe Agent Config files of an application built on Google ADK, from root_agent.yamlImport a Google ADK agent
Microsoft Agent Frameworka declarative agent, a YAML document of kind PromptImport a Microsoft Agent Framework declarative agent

aggrega import is the command’s full reference: every flag, how a source is recognised, what --sync changes and what it refuses. The import answers file describes the answers file: where it lives, what it holds, and how a secret is answered.