Importación
aggrega import lee un proyecto escrito en otro formato — un flujo exportado desde Langflow, la configuración de un cliente MCP, un archivo Compose y los demás formatos que se enumeran más abajo — y escribe a partir de él archivos Aggrega: un Aggregate, una Release y, para el destino que indica --target, un Manifest. Juntos forman un espacio de trabajo que se valida y se compila tal como está escrito, una vez respondidos los pocos valores que ninguna fuente puede contener: la importación pregunta cada uno de ellos una sola vez y guarda las respuestas en un archivo de respuestas. No despliega nada ni accede a ningún clúster ni cuenta en la nube. Los borradores son archivos normales en tu espacio de trabajo, y lo que ocurra con ellos después depende de ti.
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importborradores de archivos Aggrega
para que los revises y edites
Entra tu proyecto existente, salen borradores de archivos Aggrega. No se despliega nada; primero revisas los borradores.
Qué te aporta
- Tu proyecto llega a Aggrega sin reescribirlo a mano. El Aggregate, la Release y el Manifest generados son el mismo tipo de archivos que escribirías tú. Se compilan tal como están escritos para el destino que indica la importación, y cada política de gobernanza que tu espacio de trabajo adjunta juzga esa compilación como cualquier otra.
- Lo que la fuente indica se traslada. Un nodo o servicio para el que el catálogo contiene una coincidencia fuerte hace referencia a ese Component del catálogo, con los valores que la fuente le da, como el modelo que nombra un flujo. Una plataforma sobre la que se ejecuta la fuente se redacta con la imagen que ejecutan las Recipes del catálogo para ella. Un secreto se redacta como una referencia a su procedencia, nunca como su valor.
- Solo se te pide lo que ninguna fuente puede contener, una sola vez. Las respuestas se guardan en un archivo de respuestas junto a la fuente, de modo que la siguiente importación de la misma fuente no pregunta nada.
- Los borradores son tuyos. Son YAML sin más en tu espacio de trabajo, y no queda detrás nada de lo que dependa la compilación. Edítalos, renómbralos, haz commit de ellos.
- El borrador puede seguir a su fuente.
aggrega import --syncpone al día los borradores de una importación anterior con una fuente modificada, cambiando solo lo que escribió la importación. Donde la fuente cambió una parte que tú editaste, se detiene y nombra esa parte en lugar de sobrescribir tu edición.
Lo que no hace
Una importación redacta lo que la fuente indica y lo que tu catálogo determina, y pregunta el resto. Cada borrador dice, en un comentario junto al valor, de dónde procede un valor que ha redactado.
- No adivina lo que tu fuente no puede indicar. Ninguna fuente nombra el entorno en el que se despliega una Release, así que la Release redactada nombra
development, con un comentario que dice que es un valor predeterminado que hay que cambiar. Un valor que el catálogo requiere y que ninguna fuente contiene — el correo electrónico de la cuenta de un propietario, la imagen de una aplicación compilada a partir de tu propio código, el nombre de un Secret de Kubernetes — se redacta vacío y se pregunta, como describe Cómo se ejecuta una importación más abajo. - No lee código. El programa propio de un flujo o de un proyecto no se lee: el programa de una crew de CrewAI, el código del grafo de una aplicación LangGraph, el código fuente de un componente de Langflow, más allá de llevarlo dentro del flujo.
- No juzga lo que significa un valor. Cada nodo o servicio se compara con los Components del catálogo de tu espacio de trabajo — sus nombres, sus categorías, sus etiquetas y los nombres de los valores que declaran. Una coincidencia del nivel alto se referencia en el borrador; una más débil se escribe como un comentario que nombra el Component y su puntuación, para que tú elijas.
- No cambia la versión que ejecuta una plataforma para seguir a la fuente. La imagen de una plataforma se redacta en la versión que se sabe que ejecutan las Recipes del catálogo para ella, y donde la fuente nombra otra versión, un comentario junto a la imagen la nombra.
- No saca por ti las credenciales de tu fuente. Un valor que puede contener una clave — un valor de entorno, una cabecera, la línea de comandos de un servidor MCP — se lleva de forma predeterminada al borrador tal como está escrito, y la importación nombra cada uno en una advertencia
credential-carried, nunca por su valor. El ajusteempty_credentialsdel importador los escribe vacíos en su lugar (Configuración). Lee las advertencias antes de compartir un borrador. - No despliega ni ejecuta nada. Lee la fuente y tu catálogo, y escribe archivos. Compilar los borradores y ejecutar lo que escribe la compilación son pasos aparte que das tú.
Cómo se ejecuta una importación
Puedes ejecutar una importación con los comandos siguientes o pedir a tu asistente de IA que la ejecute por ti.
-
Parte de un espacio de trabajo. Una importación escribe sus borradores bajo la raíz del espacio de trabajo en el que se ejecuta — la carpeta que contiene un
.aggrega-config.yamlcon una claveworkspace— o bajo el directorio que indique--output-dir. Nunca sobrescribe un Aggregate que ya exista ahí. -
El catálogo con el que compara. La importación puntúa tu fuente frente a los Components del catálogo del espacio de trabajo, y nada más. Cuando el espacio de trabajo no nombra ninguna carpeta de catálogo propia, ese es el catálogo de la biblioteca estándar, leído del registro predeterminado del espacio de trabajo: cada publicación del catálogo publica una instantánea firmada del catálogo completo, y la primera importación obtiene esa instantánea, verifica su firma, la guarda en la caché de contenido del espacio de trabajo y la nombra por su digest en el archivo de registro que escribe junto a los borradores, de modo que una importación posterior de los mismos borradores lee el mismo catálogo sin volver a consultar el registro. Frente a él, un servicio PostgreSQL se asocia a
core/datastore/postgres, y--targetgenera un Manifest a partir de las Recipes del catálogo. Sin catálogo, la importación no tiene nada que asociar, y--targetse rechaza, ya que ninguna Recipe se vincula al destino.Un espacio de trabajo que nombra sus propias carpetas de catálogo importa frente a ellas en su lugar, y no obtiene ninguna instantánea: los directorios que enumera
workspace.catalog_dirs, una carpetacatalogen la raíz del espacio de trabajo o los directorios que indicaAGGREGA_CATALOG_DIRS. Los archivos propios del catálogo de la biblioteca estándar son la carpetaaggrega-catalogdel repositorioaggrega-hub, https://github.com/aggrega-ai/aggrega-hub, para un espacio de trabajo que los quiera como carpeta.--upgradeobtiene la instantánea más reciente que publica el registro e importa frente a ella a partir de entonces; con--offline, una importación que tendría que obtener una instantánea se detiene e indica qué ejecutar. -
Ejecuta la importación. Indica el archivo o el directorio:
Terminal window aggrega import compose.yaml --target composeEl formato se reconoce por el nombre y el contenido del archivo;
--formatlo indica donde no es así.--targetindica una capacidad de proveedor, comocomposeohelm, y genera un Manifest que asigna a cada tipo de componente y a cada tipo de funcionalidad que necesitan los borradores la Recipe de esa capacidad que tu catálogo ofrece para él: la que hay o, entre varias, la que lleva el nombre del tipo. La Release generada nombra ese Manifest, y lo que contienen los borradores sigue al destino: encompose, un secreto es una referencia a una variable que Docker Compose rellena desde tu shell; enhelm, el nombre de un Secret de Kubernetes. En la salida de error estándar, la importación nombra el formato que leyó, cada advertencia y una línea por cada nodo que asignó; en la salida estándar, enumera los archivos que escribió. -
Responde lo que ninguna fuente contiene. Un valor que el catálogo exige y que ninguna fuente puede contener —el correo electrónico de la cuenta de un propietario, la imagen de una aplicación compilada a partir de tu propio código, el nombre de un Secret de Kubernetes— se responde una sola vez. La importación lee las respuestas de
import-answers.yamljunto a la fuente, o del archivo que indica--answers; en una terminal pregunta por cada valor que aún falta, una pregunta a la vez, y escribe tus respuestas en ese archivo. Un secreto se responde con su procedencia —una variable o el nombre de un Secret—, nunca con su valor. Donde no se puede preguntar nada —en integración continua, a través de una tubería, desde el asistente o el editor—, la importación escribe el archivo de respuestas con la clave de cada valor que falta y una respuesta vacía, los enumera y termina con el estado 1; complétalos y vuelve a ejecutar la importación. Un solo archivo de respuestas sirve para todos los destinos: una respuesta que los borradores de un destino no necesitan se conserva en el archivo y queda sin usar. El archivo de respuestas de la importación describe el archivo por completo. -
La importación descarga lo que necesita la compilación. Cuando ya no falta nada, la importación descarga las dependencias de la Release generada, como hace
aggrega pull, y escriberelease.lockjunto a ella. Con--offlineno descarga nada e indica el comandoaggrega pullque hay que ejecutar. -
Valida y compila. En la carpeta que contiene los borradores:
Terminal window aggrega validate --release release.yamlaggrega build --release release.yamlCuando ambos pasan, la compilación ha escrito los archivos del destino en
dist/. Un rechazo nombra qué cambiar y dónde, en el documento que cambias. -
Ejecuta lo que escribió la compilación. Una compilación para Docker Compose escribe
dist/compose/docker-compose.yaml, y el archivo no nombra ningún proyecto de Compose, así que nombra uno con-p:Terminal window docker compose -p <name> -f dist/compose/docker-compose.yaml up -dSin
-p, Docker Compose da al proyecto el nombre de la carpeta que contiene el archivo,compose, de modo que dos espacios de trabajo iniciados así comparten un mismo proyecto. Los servicios están en una sola red, a la que Docker Compose da el nombre del proyecto,<name>_compose. A un servicio para el que la compilación no publica ningún puerto se accede desde dentro de esa red, condocker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, o desde un contenedor que inicies en esa red condocker run --network <name>_compose …. Las secciones «Ejecútalo» y «Pruébalo» de un recorrido guiado muestran los comandos de su propia compilación.Una ejecución responde sin una clave de OpenAI en cuanto su modelo
core/ai-model/openaiapunta a un modelo pequeño servido por Ollama en el mismo proyecto, con tres cambios en los archivos generados, una compilación con--auto-pull, que descarga lo que necesita el componente añadido, y un comando una vez iniciado el stack:- en el Aggregate, un componente más, conectado a nada:
local-model, de tipocore/ai-model/ollama, conmodel: qwen2.5:0.5ben susvalues; - en el Manifest, su Recipe de Compose:
core/ai-model/ollama: compose/ollama; - en la Release,
local-model: {}, y la claveendpointdel modelo de OpenAI, bajo suinfra, establecida en la dirección compatible con OpenAI de ese servidor,http://local-model:11434/v1; - una vez que la pila está en marcha, el modelo descargado copiado con el nombre de modelo que indica el modelo de OpenAI de la compilación,
<model>, comogpt-4o-miniogpt-4.1:docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.
OPENAI_API_KEYpuede entonces contener cualquier valor no vacío que elijas: el servidor local no comprueba ninguno. Un workflow de n8n lee la dirección y la clave del modelo de la credencial que selecciona su nodo de modelo, no de la dirección que entregaendpoint, así que da también a esa credencial la dirección del servidor, comourljunto aapiKeyen susdata. El servidor Ollama que ejecutacore/ai-model/ollamade forma predeterminada sirve la Responses API de OpenAI además de Chat Completions, así que un agente declarativo de Agent Framework que indicaapiType: Responsesllega a él tal como está escrito.Una compilación para Kubernetes, el destino
helm, escribe manifiestos simples en lugar de un chart, como describe el proveedor helm: endist/helm/o, para los componentes que una Release coloca en un límite, endist/boundaries/<boundary>/helm/, algunos de ellos en una carpeta propia debajo. Los archivos que no nombran ningún namespace, como los de las compilaciones de MCP y Dify, van al que nombra tu contexto dekubectl, o adefaultsi no nombra ninguno; crea allí primero los Secrets que leen y luego aplica la carpeta:Terminal window kubectl apply -R -f dist/helm/-Ralcanza los archivos de esas carpetas. Un ServiceClusterIP, el tipo que las compilaciones de MCP y Dify dan a los servidores que ejecutan, solo es accesible desde dentro del clúster: para acceder a uno desde tu máquina, redirige un puerto local hacia él conkubectl port-forward svc/<service> <local port>:<port>, que se ejecuta hasta que lo detengas. - en el Aggregate, un componente más, conectado a nada:
Junto a sus borradores, la importación escribe .aggrega-import.json, el registro de lo que escribió. Consérvalo mientras pienses ejecutar aggrega import --sync, que lo lee para distinguir tus ediciones de las suyas. Conserva también el archivo de respuestas: no contiene ningún secreto, así que puede estar en el control de versiones junto a la fuente, y cada importación posterior de esa fuente lo lee.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pega en él este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Llama a la herramienta `import` con `source` establecido en `compose.yaml` y `target` establecido en `compose`: escribe sus borradores en la carpeta Workspace. Si dice que aún faltan valores, dime cada uno y qué es, y espera mientras escribo mis respuestas junto a sus claves en el archivo de respuestas que nombra; luego llama de nuevo a la herramienta `import` de la misma forma. Después llama a la herramienta `validate` con `release` establecido en `release.yaml`, y a la herramienta `build` con `release` establecido en `release.yaml` y `write` establecido en true. Dime qué archivos escribió la compilación; están en `dist/` dentro de la carpeta Workspace.Ábrelo en VS Code
Con la extensión de Aggrega para Visual Studio Code instalada, abre en VS Code el espacio de trabajo en el que se ejecutó la importación —la carpeta que contiene su .aggrega-config.yaml—: los borradores están en él, en su raíz o en la carpeta que indicó --output-dir. Donde el espacio de trabajo contiene una Release, el editor la selecciona por ti; donde contiene más, Aggrega: Select Release… elige aquella con la que trabaja el editor. El editor comprueba los borradores con respecto a la Release seleccionada mientras los editas, marcando lo que encuentra en el archivo y en el panel Problemas. Aggrega: Show topology graph, en la paleta de comandos, dibuja los componentes de la Release seleccionada y las conexiones entre ellos. Aggrega: Build, Aggrega: Preview build y Aggrega: Pull actúan sobre la misma Release, y cada uno es también un botón del panel Commands de la vista Aggrega en la barra de actividades; Build escribe sus archivos en el dist/ del espacio de trabajo. Usar Aggrega en Visual Studio Code cubre el resto.
De dónde vienen los importadores
Cada formato lo lee un plugin importador. Los importadores básicos del compilador, uno por cada formato de la tabla siguiente, se publican con cada versión del compilador y sirven sus formatos en todos los espacios de trabajo, sin ninguna entrada en tu catálogo. La primera importación que necesita uno lo obtiene del registro predeterminado del espacio de trabajo, en la propia versión del compilador, lo verifica y lo guarda en la caché de contenido del espacio de trabajo, de modo que cada importación posterior lo lee desde ahí, sin necesitar la red para ello. Donde el módulo no se puede obtener en absoluto — porque el espacio de trabajo está sin conexión, por ejemplo — la importación se detiene y nombra las dos formas de ponerlo en la máquina. Importadores básicos describe cada importador por completo, y los ajustes que recibe un importador a través de una entrada plugins.importer.
Los formatos
| Formato | Qué lee | Recorrido guiado |
|---|---|---|
| Compose | un archivo Compose y su archivo de override, o un directorio que los contenga | Importar un proyecto Compose |
| Configuraciones de clientes MCP | .mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json o un server.json de un registro MCP | Importar la configuración de un cliente MCP |
| Langflow | un flujo exportado desde Langflow, en JSON | Importar un flujo de Langflow |
| Flowise | un chatflow o un agentflow exportado desde Flowise, en JSON | Importar un chatflow de Flowise |
| n8n | un flujo de trabajo exportado desde n8n, en JSON | Importar un workflow de n8n |
| Dify | una aplicación exportada desde Dify en su DSL, en YAML | Importar una aplicación de Dify |
| CrewAI | las declaraciones de agentes y tareas de un proyecto CrewAI | Importar un proyecto CrewAI |
| LangGraph | el langgraph.json de una aplicación LangGraph | Importar una aplicación LangGraph |
| Google ADK | los archivos Agent Config de una aplicación creada sobre Google ADK, a partir de root_agent.yaml | Importar un agente de Google ADK |
| Microsoft Agent Framework | un agente declarativo, un documento YAML de tipo Prompt | Importar un agente declarativo de Microsoft Agent Framework |
aggrega import es la referencia completa del comando: cada opción, cómo se reconoce una fuente, qué cambia --sync y qué rechaza. El archivo de respuestas de la importación describe el archivo de respuestas: dónde se encuentra, qué contiene y cómo se responde a un secreto.