Extensibilidad
Extensibilidad del ecosistema y salvaguardas del compilador
1. La interfaz universal de WebAssembly (Wasm)
Para garantizar la simetría arquitectónica en todo el ecosistema, Aggrega utiliza un contrato de ejecución estandarizado que se aplica de manera uniforme a cada socket Wasm de la pipeline del compilador.
La interfaz YAML para invocar cualquier plugin se basa en dos palabras clave elegidas de forma explícita: function y with.
function: Aggrega integra un runtime Wasm (el kit de herramientas Extism sobre el motor Wazero) y ejecuta Wasm directamente en memoria, de modo que no se inicia ningún proceso del sistema operativo.functionnombra el export que invoca el host de Go: una función exportada explícitamente desde el módulo Wasm.with: las entradas propias del plugin, separadas de losvaluesdel desarrollador y de losparametersque cumple una Release. La palabra clave sigue la convención de GitHub Actions (with:); cuando un plugin declara un JSON Schema para sus entradas, el host las valida contra él antes de la ejecución.
Los tipos de Plugins Wasm: Esta interfaz universal de function y with admite cada socket programable del compilador:
| Tipo de Plugin | Dónde se ejecuta | Propósito | Salida esperada |
|---|---|---|---|
Provider (provider) | Renderizado (generación) | Traduce la IR final en memoria a archivos físicos serializados como cadenas para un formato de destino (Helm, Terraform, Compose). | Un array de archivos serializados como cadenas. |
Paso de pipeline de FeatureRecipe (pipeline-step) | La pipeline de plugins de una Recipe o de una FeatureRecipe | Pasos secuenciales que obtienen secretos o inyectan sidecars en AST base. | patches RFC 6902 sobre el conjunto de documentos indexado por clave, más side_effects (emitir un nuevo documento o archivo), diagnostics y outputs que un paso posterior puede leer. La entrada del paso lleva ese conjunto de documentos indexado por clave y la entrada with renderizada del paso. |
Gobernanza (governance) | Antes de la expansión de anotaciones, construcción de la topología, análisis estático o etapa de renderizado | Cumple las funciones de gobernanza de la pipeline de build. Antes de la expansión de anotaciones inyecta anotaciones en los componentes resueltos, y en la construcción de la topología etiqueta automáticamente los nodos con etiquetas de cumplimiento o de entorno (un operador habilita uno explícitamente para una u otra función). En el análisis estático o en la etapa de renderizado actúa como Loud Guardrail: evalúa las aristas, las rutas y las etiquetas del grafo —o los artefactos renderizados— frente a los límites de seguridad. Lo que puede emitir lo determina la función a la que está vinculado, no su tipo. | Antes de la expansión de anotaciones, inyecciones de anotaciones. En la construcción de la topología, un array de JSONPatches dirigidos a metadata.labels. En el análisis estático o en la etapa de renderizado, veredictos de severidad halt, warn o info (una política Rego los reúne bajo deny, warn y audit); un halt detiene el build. |
Linter (linter) | Fuera de banda | Comprobaciones opcionales de FinOps o de higiene (p. ej., estimación de costes en la nube a partir de .infra) y disciplina en el momento de la publicación. | Cadenas de advertencia o detenciones fatales. |
Extensión de la CLI (cli) | Runtime (aggrega <command>) | Un comando de nivel superior listo para usar aportado por un plugin firmado y aislado en sandbox, sin ningún código Go por comando en el host. | Salida estándar y error estándar transmitidos en streaming, más el código de salida del invitado. |
Parser (parser) | Bajo demanda, dondequiera que se lea un formato externo | Convierte texto fuente externo (HCL, TOML, YAML, JSON, JSON con comentarios) en un árbol JSON canónico. | tree más diagnostics, y spans de origen opcionales. |
Importer (importer) | Bajo demanda, fuera de cualquier build (aggrega import, el editor y la herramienta import del asistente) | Convierte una fuente externa de infraestructura o de definición de agentes (Langflow, Flowise, n8n, una configuración MCP, una aplicación Compose, una aplicación Dify, los agentes declarados de un proyecto CrewAI, la configuración de una aplicación LangGraph, las configuraciones de agentes de una aplicación Google ADK, un agente declarativo de Agent Framework) en borradores de archivos de autoría de Aggrega, y anuncia los formatos que maneja como capabilities import:<format>. | Borradores de entidades Aggregate / Component / Release, o referencias a los Components del catálogo que reutiliza, las decisiones de mapeo en que se basan, diagnósticos y los archivos de scaffold que se deben escribir. |
El runtime host: un sandbox que deniega capabilities. Aggrega integra el host Wasm como el kit de herramientas Extism ejecutándose sobre el motor Wazero; el binario host sigue siendo Go puro sin dependencia de ninguna toolchain nativa, de modo que aggrega se compila de forma cruzada sin problemas. Cada socket se ejecuta detrás de un cortafuegos de pureza AOT: el host se niega a conceder a un plugin cualquier capability de acceso en tiempo de ejecución —ni red, ni sistema de archivos, ni reloj de pared, ni entorno, ni E/S estándar—, de modo que una llamada que usaría una de ellas falla, y un plugin que importa desde una superficie del host que el host no proporciona se rechaza al cargarse. Un plugin que no puede acceder a la red ni leer el reloj no puede romper la garantía ahead-of-time del compilador de que la misma entrada produce la misma salida. Los runtimes de lenguaje que necesitan algunos imports de arranque inocuos se ejecutan con una configuración de esos imports que deniega capabilities: el host fija el reloj observable, proporciona entropía real, descarta la E/S estándar y no concede acceso al sistema de archivos, a los argumentos ni al entorno, de modo que un plugin no puede alcanzar ninguna capability del host que varíe entre builds. La entropía se deja deliberadamente real en lugar de fijarla: fijarla estabilizaría la semilla de hash interna y el orden de iteración de los mapas del runtime de un lenguaje invitado, y ocultaría así un plugin cuya propia salida no es reproducible en lugar de dejar que eso aflore como salida divergente. Un plugin cuyo resultado depende de la entropía tiene un problema de determinismo a nivel de autoría, y esta configuración está diseñada para revelarlo en lugar de enmascararlo.
Desarrollar contra el host: el PDK. Los autores de plugins no escriben a mano la ABI de memoria de Wasm. Aggrega ofrece un Plugin Development Kit en tres lenguajes —Go, Rust y TypeScript—, envoltorios ligeros que presentan la entrada y la salida tipadas de cada socket para que el autor escriba funciones normales. La interfaz function / with anterior es lo que un Aggregate o una FeatureRecipe usa para invocar un plugin; el PDK es aquello contra lo que un autor de plugins desarrolla.
Dónde se ejecuta cada socket. Cada socket se ejecuta a través del mismo host: el publishing linter con aggrega lint; las funciones de gobernanza, los providers de renderizado y los pasos de pipeline de las Recipe y las FeatureRecipe durante aggrega build; los parsers dondequiera que se lea un formato externo; los importadores con aggrega import; y los plugins de CLI como comandos de nivel superior. Consulta Estado del lenguaje para ver el grado de preparación de cada socket.
Qué plugins quedan fijados y cuáles elige tu entorno. Aggrega clasifica los plugins según si cambian o no la salida que entregas. Los plugins que dan forma a la salida —los providers de renderizado, los plugins de gobernanza vinculados en una función de transformación (label-transform, annotation-transform) y los pasos de pipeline de las FeatureRecipe y las Recipe— quedan fijados en el lockfile de la release cuando ejecutas aggrega pull, y se reproducen idénticos byte a byte en aggrega build y aggrega serve a partir de ese lockfile únicamente. Dos tipos no se fijan, porque una build lee cada uno del mismo lugar en todas las ocasiones: un provider de renderizado servido desde el interior del binario del compilador, y un provider o un paso de pipeline cuya entidad Plugin está escrita en uno de tus propios directorios de catálogo. Para cambiar qué plugin que da forma a la salida se aplica, vuelves a hacer pull; un cambio en la configuración de tu workspace después de un pull no altera la salida de una build hasta el siguiente pull. Los plugins de control —policy y lint— juzgan una build sin cambiar sus bytes, por lo que se almacenan en caché en el pull (para que una build pueda seguir ejecutándolos sin conexión; uno que lleva el binario del compilador, o uno escrito en tu propio directorio de catálogo, se lee de ahí en su lugar) pero no se fijan: qué control se ejecuta lo elige tu entorno en el momento de la build, de modo que una división permisiva en desarrollo / estricta en CI es una elección de configuración normal en lugar de un nuevo pull, y cambiar de controles nunca altera la salida que emite una build que los supera. Los Plugins que actúan solo sobre la entrada de autoría, como los importadores y las extensiones de la CLI, no dan forma a ninguna salida de build y no se fijan ni forman parte del conjunto almacenado en caché de la build.
2. Pipelines de Plugin de FeatureRecipe
Las FeatureRecipes vinculan intenciones operativas abstractas (como la conexión de un proxy de seguridad o la inyección de un sidecar) a pipelines versionados de plugins WebAssembly (Wasm). Ops declara lo que una Feature necesita en un destino de provider concreto; el compilador ejecuta el pipeline declarado sobre el grafo IR plano.
Este vínculo tiene tres consecuencias para el ecosistema:
- Evolución desacoplada. El vocabulario de infraestructura crece mediante plugins Wasm externos sin necesidad de una nueva versión del núcleo del compilador Aggrega. Los nuevos providers, los nuevos sidecars y las nuevas integraciones de seguridad se distribuyen como binarios Wasm independientes sobre la ABI Wasm estable.
- Versionado semántico. Las FeatureRecipes hacen referencia a plugins Wasm por versión: exacta (
:1.0.0) o un rango caret (:^1.0.0, la versión más alta compatible con ella). Con el rango caret, Ops fija una versión mayor mientras incorpora sus versiones menores y de parche cada vez que el lockfile se vuelve a resolver conaggrega pull --upgrade. - Descarga de la complejidad. La generación de CRD específicas de un proveedor o el renderizado complejo (objetos de policy específicos de un proveedor, recursos de enrutamiento nativos del provider) residen en plugins Wasm puros que operan sobre el grafo IR plano, en lugar de pasar por declaraciones de esquema o lógica de plantillas dentro de las definiciones de componentes.
Encadenamiento de pipelines: separar responsabilidades entre plugins. Un pipeline de FeatureRecipe puede encadenar varios plugins Wasm de forma secuencial, cada uno de los cuales recibe del compilador el mismo contexto de nodo IR. El patrón estándar divide la responsabilidad para que un único plugin no cargue a la vez con la intención semántica de una funcionalidad y con el mecanismo físico de interceptación del tráfico de un entorno de destino concreto.
Una cadena canónica de dos plugins tiene este aspecto:
- Un plugin de configuración que emite las reglas semánticas de la funcionalidad (reglas de policy de seguridad, patrones de auditoría, umbrales de limitación de tasa). Entiende la intención de la funcionalidad; no entiende el tejido de interceptación del tráfico del entorno de destino.
- Un plugin de enrutamiento que emite la configuración física de la malla que transporta esas reglas (CRD de gateway, parches de inyección de sidecars, reglas de firewall). Entiende el tejido del entorno de destino; no entiende la intención semántica de la funcionalidad.
Ambos plugins reciben en secuencia del compilador el mismo contexto de nodo IR, por lo que se componen limpiamente sin un acoplamiento directo entre ellos. El compilador orquesta el pipeline; los plugins aportan el conocimiento del dominio.
3. Interceptación del tráfico: el destino HTTPRoute
El modelo de extensibilidad de Aggrega toma como objetivo el estándar HTTPRoute de la Kubernetes Gateway API como artefacto común a todos los providers para la interceptación del tráfico a nivel de malla. La biblioteca estándar emite objetos HTTPRoute mediante la Feature core/http-route, cuya FeatureRecipe de helm renderiza una ruta por cada componente vinculado; los entornos de destino que consumen la Gateway API traducen HTTPRoute a sus tejidos nativos.
4. Autonomía del Plugin: resolución de etiquetas
Cuando los plugins Wasm generan recursos físicos a partir del grafo IR, los SRE necesitan rastrear un Pod de Kubernetes en ejecución o un recurso en la nube hasta la intención semántica del desarrollador en el Aggregate. El modelo de extensibilidad de Aggrega sitúa esa traducción por completo bajo el control del autor del plugin Wasm.
El compilador pasa el diccionario labels completo del grafo IR al sandbox Wasm sin interpretarlo. A partir de ahí, el autor del plugin —Platform Ops— decide la lógica de correspondencia: pasar todas las etiquetas tal cual, filtrar por prefijos de dominio concretos (*.aggrega.ai/*) o hacer corresponder las etiquetas del grafo directamente con los esquemas de etiquetado nativos del provider (traduciendo una etiqueta IR a tags de AWS, annotations de Kubernetes o un mecanismo de metadatos específico de la nube). El compilador no impone ninguna restricción sobre cómo se etiquetan los artefactos generados.
Esta autonomía mantiene la inteligencia específica del dominio —qué etiquetas importan para la observabilidad, cuáles corresponden a convenciones de etiquetado nativas, cuáles son internas de la plataforma— dentro de la capa de plugins Wasm, donde el ecosistema evoluciona con independencia del ritmo de publicación del compilador Go.
5. Extensiones de la CLI: comandos en tiempo de ejecución
Los sockets anteriores se ejecutan dentro de una build: el compilador los invoca mientras analiza, transforma, valida y renderiza un Aggregate. El socket de extensiones de la CLI es de otra naturaleza: se ejecuta en el terminal, fuera de cualquier build, cuando un operador escribe aggrega <command>. Así es como la superficie de comandos de aggrega crece sin una nueva versión del núcleo.
Qué es una extensión de la CLI. Una extensión de la CLI es un aggrega <command> listo para usar aportado por un plugin Wasm firmado y ejecutado en un sandbox. Adopta el mismo enfoque drop-in, con la lógica en el invitado, que adopta el socket de renderizado: la lógica del dominio reside por completo en el invitado, y el host Go no aporta ningún código por comando. Añadir un nuevo comando de nivel superior requiere solo tres cosas: un binario .wasm, una entidad Plugin que declare pluginType: cli (consulta Plugin) y un aggrega plugin add cli explícito. El host descubre el comando a partir de la autodescripción del plugin instalado; ningún comando está compilado en el binario.
Por qué un socket de tiempo de ejecución puede hacer lo que un socket de build no puede. Como los sockets de tiempo de compilación se ejecutan durante una build, permanecen sin capacidades y deterministas: Aggrega es un compilador ahead-of-time, y la misma entrada debe producir siempre la misma salida (consulta Invariantes arquitectónicos). Por tanto, un plugin de renderizado o de policy no puede acceder a la red, leer el reloj ni transmitir al terminal: cualquier cosa que varíe entre ejecuciones rompería esa garantía. Una extensión de la CLI se ejecuta después y fuera de ese límite, dirigida por una persona ante un prompt en lugar de por el pipeline determinista. Precisamente por eso un plugin de la CLI puede transmitir la salida estándar y el error estándar mientras se ejecuta y devolver un código de salida del proceso: no existe ningún artefacto de build cuya estabilidad byte a byte puedan amenazar esos efectos.
Instalar, ejecutar y descubrir. aggrega plugin add cli <query> busca en el registro configurado un plugin cli coincidente, lo verifica frente a la política de confianza del registro y lo instala como comando de nivel superior, mostrando primero las capacidades declaradas del plugin para que el operador confirme exactamente lo que el comando puede hacer antes de que se instale. Una vez instalado, aggrega <command> lo ejecuta como cualquier comando integrado. Un plugin de la CLI declara sus comandos y sus flags en su autodescripción describe(), y el host muestra los flags de cada comando en aggrega help <command> exactamente igual que para un comando integrado, de modo que un operador descubre los --flags de un comando instalado de la misma manera. Para encontrar comandos instalables y contenido del catálogo, aggrega search consulta el índice local de los registros configurados: --kind plugin --plugin-type cli restringe los resultados a los plugins de la CLI instalables, y una búsqueda sin filtros abarca las entidades del catálogo; aggrega plugin list muestra lo que ya está instalado. Los flags y las formas de salida de cada comando se encuentran en esas páginas de referencia.
El modelo de capacidades. Una extensión de la CLI parte de una base fija que todo comando recibe sin ninguna declaración y sin ninguna solicitud de confirmación:
| Capacidad base | Concedida |
|---|---|
| Argumentos de línea de comandos de entrada | Siempre |
| Salida estándar y error estándar transmitidos | Siempre |
| Código de salida del proceso devuelto | Siempre |
Todo lo que va más allá de la base está desactivado de forma predeterminada. Un plugin que necesita más declara explícitamente cada capacidad adicional, y el host la concede solo después de mostrarla en el momento de la instalación para que el operador la confirme. Una clase de capacidades añadida más allá de la base —acceso al entorno, al sistema de archivos o a la red, entrada interactiva— se concede tras el mismo control de declaración y confirmación, de modo que un comando nunca pueda adquirir en silencio un alcance que el operador no haya aprobado.
Los comandos integrados siempre prevalecen. Un plugin instalado nunca puede ocultar un comando integrado. Una protección de nombres reservados respaldada por una lista de denegación protege los comandos integrados y un conjunto de nombres reservados para comandos integrados, y una colisión se rechaza en la instalación en lugar de permitir que sobrescriba el comportamiento del núcleo. La superficie de comandos de la que depende un operador permanece estable, independientemente de lo que se instale encima.
6. Plugins de análisis: lectura de formatos externos
El compilador necesita leer con frecuencia texto escrito en un formato del que no es autor: un módulo de Terraform en HCL, un archivo de configuración en TOML, un manifiesto en YAML o JSON. El socket de analizadores aporta esa capacidad de lectura sin enseñar al núcleo del compilador ningún formato concreto. Un analizador es un plugin sin estado que convierte un texto fuente externo en un árbol JSON estructurado: le pasas los bytes de un archivo HCL y devuelve el mismo contenido como un objeto JSON que el resto del pipeline ya sabe recorrer. Cualquier parte del compilador que necesite leer un formato que no analiza de forma nativa pide un árbol analizado y trabaja a partir de él.
Un formato es una capacidad, no una funcionalidad del compilador. Un analizador anuncia los formatos que maneja como capacidades —parse:hcl, parse:toml, etc.— y el host resuelve un analizador según el formato solicitado, lo ejecuta y devuelve el árbol. Es el mismo modelo drop-in, basado en capacidades anunciadas, que siguen los providers de renderizado y los plugins de la CLI: el núcleo del compilador no contiene ninguna lista integrada de formatos, de modo que añadir uno consiste en distribuir un nuevo plugin de análisis, nunca una nueva versión del núcleo. Los analizadores para HCL, TOML, YAML, JSON y JSON con comentarios se incluyen en el binario como conjunto inicial; una empresa que necesita otro formato distribuye un plugin de análisis que lo anuncie.
La selección del formato es declarativa, nunca adivinada. El host nunca inspecciona el contenido de un archivo para decidir qué es. Elige un formato mediante señales declaradas, en un orden de preferencia fijo. Un provider de renderizado puede declarar el formato de cada archivo que emite, y el host prefiere sin más ese formato declarado por el productor: el provider que escribió los bytes es la autoridad sobre cómo leerlos. Para un archivo que el productor no etiquetó, la alternativa es un mapa fijo de extensiones de archivo: .tf selecciona HCL, .toml selecciona TOML, .yaml selecciona YAML, .json selecciona JSON. Elegir según un formato declarado o una extensión fija mantiene el análisis determinista y legible: la misma entrada se dirige siempre al mismo analizador, y un operador puede saber qué analizador se ejecutará sin conocer los bytes del archivo. Inspeccionar el contenido haría que la elección dependiera de la carga útil, y Aggrega no lo hace.
Un analizador es puramente sintáctico. La salida es un árbol JSON más los diagnósticos y, de forma opcional, las ubicaciones en el código fuente de las que procede cada nodo. Un analizador no aporta ningún significado de Aggrega: informa de lo que el texto dice estructuralmente, y nada de lo que significa como Component, Recipe o cualquier otra entidad. Convertir un árbol analizado en entidades de Aggrega es una cuestión aparte que se resuelve en otro lugar; la única tarea del analizador es una traducción fiel de la sintaxis a JSON. La dirección de lectura es unidireccional con el mismo espíritu: un analizador lee un formato hacia un árbol, no vuelve a escribir un formato.
Un consumidor: policy sobre HCL de Terraform. Una policy de la etapa de renderizado que necesita inspeccionar el Terraform que produce una build no aprende HCL por sí misma. El host analiza el artefacto HCL a través del socket de analizadores y entrega al plugin de policy el árbol JSON que ya lee, de modo que la policy razona sobre datos estructurados con la forma que recibe cualquier otro socket. Los nuevos lectores de formatos externos se componen de la misma manera —pedir el árbol al host y luego trabajar en JSON—, de modo que la capacidad del compilador para entender un formato crece añadiendo plugins de análisis en lugar de hacer crecer el núcleo.
7. Plugins de importación: borradores de archivos de autoría a partir de fuentes externas
Un equipo rara vez parte de cero. Su arquitectura de agentes a menudo ya existe en otro lugar: un flow de Langflow o Flowise, un workflow de n8n, una aplicación de Dify, los servidores MCP con los que está configurado un cliente, una aplicación de Compose, los agentes que declara la configuración de un framework. El socket de importadores convierte esa fuente externa en un punto de partida concreto para la autoría en Aggrega: lee la fuente y genera entidades Aggregate y Component en primer borrador y, a partir de una configuración MCP, una aplicación de Compose o la configuración declarada de un framework, un borrador de Release, para que un autor lo revise y lo termine, de modo que un equipo traslada a Aggrega lo que ya tiene en lugar de reescribirlo a mano. Un importador hace corresponder el significado: lee qué es un nodo de la fuente y propone la entidad de Aggrega que lo representa, o lo deja dentro del flow que transporta la plataforma en borrador; el compilador transmite las entidades emitidas de forma opaca, exactamente igual que se mantiene agnóstico respecto a lo que produce cualquier plugin.
Un formato es una capacidad, no una funcionalidad del compilador. Un importador anuncia los formatos que maneja como capacidades —import:langflow, import:flowise, import:n8n, import:mcp, import:compose, import:dify, import:crewai, import:langgraph, import:google-adk, import:agent-framework, etc.— y el host resuelve un importador según el formato solicitado, lo ejecuta y recoge las entidades que ha generado como borrador. Es el mismo modelo drop-in, basado en capacidades anunciadas, que sigue el socket de analizadores con parse:<format>: el núcleo del compilador no contiene ninguna lista integrada de formatos importables, de modo que admitir uno nuevo consiste en distribuir un plugin de importación que lo anuncie, nunca una nueva versión del núcleo.
Un importador lee a través del socket de analizadores; no vuelve a analizar. Un importador necesita la forma estructurada de su fuente, pero no reimplementa la lectura de un formato que el ecosistema ya analiza. Cuando necesita el árbol, pide al host que ejecute el analizador correspondiente —el que el catálogo del workspace sirve para la sintaxis de la fuente o, donde el catálogo no sirve ninguno, el que lleva el propio compilador— mediante la misma capacidad de análisis mediada por el host que usa el resto del pipeline, y trabaja a partir del árbol JSON devuelto. Leer (de la sintaxis al árbol) sigue siendo tarea del analizador; hacer corresponder (del árbol a las entidades de Aggrega) es tarea del importador. Los dos sockets se componen sin duplicarse: un importador añade la inteligencia de correspondencia para una fuente y se apoya en el analizador existente para los bytes.
Un formato se reconoce por lo que declara su importador, nunca se adivina. Una importación puede nombrar directamente su formato de origen. Cuando no lo hace, el formato se reconoce por las firmas que cada importador declara en su autodescripción y que registra su entidad Plugin: la sintaxis en que se lee una fuente, los nombres de archivo a los que se aplica una firma y las rutas que el árbol analizado debe o no debe contener. El host no conoce ningún formato propio. Analiza la fuente mediante el analizador que el catálogo del workspace sirve para cada sintaxis que nombra una firma —o el del compilador, donde el catálogo no sirve ninguno—, evalúa los predicados declarados sobre el árbol devuelto y lee la fuente como el formato del único importador cuya firma coincide. Las firmas declaradas ocupan el lugar que ocupa un mapa fijo de extensiones de archivo para el socket de analizadores, porque los formatos que lee una importación pueden compartir extensión: una exportación de Langflow, una exportación de Flowise y un workflow de n8n son todos archivos JSON. Una fuente con la que no coincide ninguna firma se rechaza, pidiendo el formato y nombrando los formatos que anuncian los importadores —o, en el caso de un directorio, pidiendo uno de sus archivos por separado o un formato cuyo importador declara patrones de archivo, nombrando solo esos—; una fuente con la que coinciden firmas de más de un formato se rechaza, nombrándolos. El reconocimiento no lee nada más que la fuente y no accede a ninguna red, de modo que reconocer un nuevo formato es una declaración que distribuye el nuevo importador, nunca un cambio en el host. Las reglas para escribir una firma se encuentran en El socket de importadores.
Un directorio se lee a través de los archivos que declara su importador. Una fuente es un archivo o un directorio. Un archivo se entrega completo al importador. Un directorio se lee como fuentes con nombre —exactamente los archivos que seleccionan los patrones de archivo de las firmas del importador, cada uno nombrado por su ruta dentro del directorio, en orden— y no se abre ningún otro archivo del directorio; un enlace que llevaría la lectura fuera del directorio se rechaza antes de leer nada. Un importador que no declara patrones de archivo lee un solo archivo y rechaza un directorio, y también se rechaza un directorio que no contiene ningún archivo que seleccionen los patrones de un importador. Los importadores de Langflow, Flowise, n8n, Dify y Agent Framework del compilador no declaran ninguno, por lo que cada uno lee un único archivo exportado de flow, workflow o aplicación, o un único agente declarativo; su importador de MCP declara los nombres de archivo de las configuraciones de cliente MCP que lee, de modo que el directorio de un proyecto se lee a través de las configuraciones que contiene; su importador de Compose declara los nombres de archivo que Compose lee de forma predeterminada, de modo que el directorio de un proyecto se lee a través de su archivo de Compose y del archivo de override que Compose fusiona sobre él; y su importador de CrewAI declara los nombres de archivo bajo los que un proyecto de CrewAI declara sus agentes y tareas, de modo que el directorio de un proyecto se lee a través de esas declaraciones y su programa nunca se lee; y su importador de LangGraph declara langgraph.json, de modo que el directorio de una aplicación se lee solo a través de su configuración, sin leer nunca su código ni sus archivos de entorno, y un archivo de entorno que nombra la configuración llega al importador solo donde el with.sources de su conexión se lo entrega, y entonces solo para los nombres de las variables; y su importador de Google ADK declara root_agent.yaml, de modo que el directorio de una aplicación se lee solo a través de la configuración de su agente raíz, las configuraciones que nombran sus subagentes llegan al importador solo donde el with.sources de su conexión se las entrega, y nunca se leen ni su código ni su archivo de entorno.
La correspondencia es determinista, con puntuación de confianza y evaluada frente a tu propio catálogo. El host entrega al importador una vista de los Components que contiene el propio catálogo del workspace: el catálogo del que se seleccionó el importador —las carpetas de catálogo del workspace o, si no nombra ninguna, la instantánea del catálogo que publica su registro predeterminado—, los Components de un catálogo empresarial exactamente igual que los de la biblioteca estándar. La vista contiene el nombre, la versión y las etiquetas de cada Component, los nombres de clave que declaran sus values y provides, y los selectores de sus sockets, y nunca un valor, un valor predeterminado ni un secreto; no se descarga nada para construirla aparte de esa instantánea, y su orden es fijo, de modo que un catálogo produce una sola vista. Un importador construido sobre el paquete importer del PDK de Go —entre ellos los propios importadores de Langflow, Flowise, n8n y Compose del compilador— evalúa cada nodo de la fuente frente a esos Components y nada más, con un modelo de confianza determinista y sin modelos de IA, y registra la decisión —los candidatos que evaluó, el nivel de coincidencia que asignó y la elección que hizo— como sugerencias revisables que un autor puede leer y modificar. Un Component que el catálogo incorpora es un candidato en la siguiente importación, sin reconstruir ningún importador. El comportamiento predeterminado es solo sugerencias: la importación propone y el autor decide. Una coincidencia de alta confianza puede escribirse como referencia a un componente existente del catálogo en lugar de un cuerpo recién generado como borrador, pero solo cuando el operador lo activa expresamente, siempre como una sugerencia explícita y reversible que el autor aprueba, nunca como una reescritura silenciosa. Como la puntuación no usa ningún modelo ni ninguna consulta en tiempo de ejecución, la misma fuente evaluada frente al mismo catálogo produce siempre las mismas sugerencias.
Un flow se genera como borrador en forma de la plataforma que lo ejecuta. Un flow de Langflow, un chatflow de Flowise y un workflow de n8n se ejecutan sobre una plataforma, y de forma predeterminada una importación genera como borrador esa plataforma en lugar de los nodos del flow: una instancia del Component de plataforma de la biblioteca estándar —core/ai-agent/langflow, core/ai-agent/flowise o core/ai-agent/n8n— que transporta el flow tal como se exportó en su valor flow_definition, que la plataforma carga al desplegarse. Cada parte del flow que admite un socket de la plataforma —en las plataformas de la biblioteca estándar, un modelo, un servidor MCP u otra herramienta a la que se accede por HTTP, y un almacén vectorial— se convierte en un Component propio, referenciado o generado como borrador según decida la correspondencia, y se conecta a ese socket bajo el uses de la plataforma. Así, cada llamada que el flow hace a un modelo, una herramienta o un almacén es una conexión que declara el Aggregate: un plugin de gobernanza que juzga el grafo la ve como ve cualquier otra arista, y la allowlist de egress de la biblioteca estándar, que el ajuste attach_egress_allowlist conecta a la plataforma, permite que la plataforma se conecte solo a lo que alcanzan sus conexiones, a sus propios pods y al DNS del clúster. Donde el formato lo permite, el borrador escribe en el flow transportado lo que hace que el flow alcance cada parte a través de su conexión. Cualquier otro nodo —un agente, una cadena, un disparador— permanece dentro del flow transportado y no se convierte en ningún Component, y su decisión registra los candidatos frente a los que se evaluó. Una aplicación de Dify se genera como borrador de la misma manera, en la forma que adopta una instalación completa: una entrada de la instalación de Dify que ensambla la biblioteca estándar, core/dify, que transporta la aplicación en su parámetro app_definition, y la instalación conecta sus propias conexiones. El ajuste layout de la conexión del importador elige el borrador: platform, el predeterminado, o nodes, que genera como borrador cada nodo de la fuente como un Component propio, cada arista del flow como una conexión uses, y no transporta ningún flow. La plataforma que transporta el flow expone qué nodos se convierten en partes y dónde se conecta cada uno.
Un framework code-first se lee a través de su configuración declarada, nunca de su programa. CrewAI, LangGraph, Google ADK y Agent Framework mantienen el comportamiento de una aplicación en su programa y declaran sus agentes, grafos y modelos en una configuración junto a él. Sus importadores leen solo esas declaraciones —los archivos de agentes y tareas de un proyecto de CrewAI, el langgraph.json de una aplicación de LangGraph, las configuraciones de agentes de una aplicación de Google ADK, un agente declarativo de Agent Framework— y generan como borrador el agente de la biblioteca estándar para el framework en torno a un programa que nunca abren, conectado a lo que nombran las declaraciones: el modelo que pide un agente, allí donde el socket model del agente lo acepta, y el almacén de datos en el que un checkpointer de LangGraph guarda el estado. A un servidor MCP que nombra un agente de Agent Framework accede el proveedor del modelo, como herramienta alojada, por lo que el borrador lo nombra en comentarios y no conecta nada a él. El programa se ejecuta en la imagen que nombra la Release. Lo que solo dice el programa —la lógica de una tarea, una herramienta que define su código, un agente que construye su código— se nombra en los comentarios y decisiones del borrador y no se convierte en ningún Component; llevarlo a los archivos de autoría es trabajo del autor, a mano o con un asistente de IA que escribe en nombre del autor a través de aggrega mcp, que lee la referencia y genera y valida entidades.
Lo que una fuente indica sobre cómo se ejecutan sus partes acaba en un borrador de Release. Aportar las entradas operativas corresponde a la Release, por lo que los importadores de MCP, Compose, CrewAI, LangGraph, Google ADK y Agent Framework generan como borrador una Release junto al Aggregate, al que nombra su spec.aggregate: la Release contiene lo que indica la fuente —la línea de comandos o la dirección de un servidor, la imagen y el puerto de un servidor genérico, el endpoint de un modelo— y, en comentarios sobre cada entrada, lo que la fuente indica pero ninguna clave del Component en borrador admite, como los volúmenes de un servicio o el entorno de una configuración. Lo que ninguna fuente indica —la imagen que ejecuta el programa de un framework, la credencial que presenta una conexión, los metadata.environment y spec.manifest de la Release— se nombra en un comentario donde corresponde, para que el operador lo aporte, y la build se detiene nombrando cuál de la imagen, el entorno y el manifiesto sigue sin establecerse. Un borrador de plataforma no escribe ninguna Release: el comentario sobre la instancia de la plataforma nombra lo que aporta la Release: las entradas propias de la plataforma, como la imagen que ejecuta o su cuenta propietaria, la dirección de cada servidor MCP conectado y la credencial que presenta cada conexión.
Un valor de credencial que contiene una fuente se transporta tal como está escrito, salvo que se pida su eliminación. Un importador localiza cada valor de su fuente que puede contener una credencial, cada uno de una clase: lo que el formato marca como credencial, un miembro de la configuración de un servidor MCP, o una entrada que el formato marca como no credencial pero que aun así puede contener una, como las cabeceras de una solicitud. De forma predeterminada no se escribe ninguno vacío: cada valor que contiene algo se transporta tal como está escrito —en el flow o la aplicación que transporta la plataforma, o en el borrador de Release— y se nombra en una advertencia credential-carried por su ubicación —su nodo, servidor, servicio o agente, y su campo—, nunca por su valor, junto con el valor del ajuste que lo escribe vacío. El ajuste empty_credentials activa la eliminación, una clase cada vez: marked escribe vacío lo que un formato marca como credencial y cada miembro de la configuración de un servidor MCP, y all también las entradas marcadas como no credenciales, y cada valor escrito vacío se notifica con credential-emptied. Lo que el borrador escribe para que un flow alcance su conexión es cableado, escrito diga lo que diga el ajuste, y una conexión en el borrador no contiene ninguna credencial: la Release conecta la que presenta cada conexión. Un archivo al que una fuente solo apunta, como un archivo de entorno, se lee únicamente para los nombres de sus variables, cuando se lee, y un borrador hecho nodo a nodo no lee ningún valor. Lo que queda fuera de los lugares que localiza un importador —el código de un componente personalizado, un prompt— corresponde al autor revisarlo antes de compartir un borrador, como expone Valores de credencial que contiene el flow.
El comando, el editor y el asistente ejecutan una misma importación. aggrega import <file or directory> ejecuta una importación desde la terminal; el editor ejecuta la misma operación mediante la solicitud aggrega/import de su sesión, y un asistente de IA mediante la herramienta import expuesta por aggrega mcp. Los tres seleccionan el importador de la misma manera, entre los importadores que contiene el catálogo del espacio de trabajo y los importadores básicos del compilador: el que nombra una vinculación plugins.importer, cuando nombra uno que anuncia el formato, y en caso contrario la versión más alta del único importador que lo anuncia; importadores de dos nombres para un mismo formato, sin que ninguno esté vinculado, detienen la importación, que nombra a ambos, como expone Qué importador convierte una fuente en borradores. Los tres informan de las decisiones de mapeo junto a los borradores. El comando imprime en la salida de error estándar una línea por cada nodo mapeado, que nombra el Component o el borrador elegido para él, si se referencia o se genera como borrador, el nivel de coincidencia y, cuando el importador ha evaluado un candidato, la puntuación del mejor candidato; el editor muestra las mismas líneas, y el resultado de la sesión del editor y la respuesta del asistente incluyen cada decisión completa. Así, un autor ve dónde ha supuesto la importación, en cualquier superficie que la haya ejecutado, sin abrir los borradores. --format indica explícitamente el formato de la fuente —por ejemplo langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk o agent-framework— en lugar del reconocimiento. El comando deposita las entidades y cualquier archivo de andamiaje que haya producido la importación bajo la raíz del espacio de trabajo, o bajo el directorio que indica --output-dir; --dry-run hace todo lo que hace el comando salvo escribir, devolviendo los archivos generados como contenido e indicando el archivo al que corresponde cada uno, para que un autor pueda revisar el andamiaje antes de confirmar nada en el árbol de trabajo.
Los importadores del núcleo. Los importadores del núcleo que distribuye el compilador leen estos formatos, un importador para cada uno:
- Langflow: un flow exportado de Langflow, generado como borrador en forma de la plataforma Langflow de la biblioteca estándar que transporta el flow, con cada parte de él que admite un socket conectada a ese socket.
- Flowise: un chatflow o un agentflow exportado de Flowise, generado como borrador en forma de la plataforma Flowise de la biblioteca estándar que lo transporta, con cada parte de él que admite un socket conectada a ese socket.
- n8n: un workflow exportado de n8n, generado como borrador en forma de la plataforma n8n de la biblioteca estándar que lo transporta, con cada parte de él que admite un socket conectada a ese socket.
- Dify: una aplicación exportada de Dify, generada como borrador en forma de la instalación de Dify que ensambla la biblioteca estándar y que transporta la aplicación, con los modelos, herramientas y bases de conocimiento que nombra notificados como configurados dentro de Dify.
- MCP: la configuración de un cliente MCP o la descripción de servidor de un registro MCP, con cada servidor generado como borrador en forma de instancia de la herramienta MCP de la biblioteca estándar, y una
Releaseque contiene la línea de comandos, la dirección o la imagen de cada servidor. - Compose: un formato de infraestructura, con cada servicio de una aplicación de Compose generado como borrador en forma del Component del catálogo con el que coincide su imagen —mediante una tabla que lleva el importador, generada a partir de las Recipes y los Components de Compose del catálogo estándar cuando se construye— o como un servidor genérico que ejecuta su imagen, con una
Releaseque contiene la imagen y el puerto de cada servidor genérico y, en comentarios, los puertos, volúmenes y entorno que declara cada servicio. - CrewAI: los agentes que un proyecto de CrewAI declara en sus archivos de configuración, cada uno generado como borrador en forma del agente CrewAI de la biblioteca estándar que contiene su rol, su objetivo y su historia de fondo y está conectado al modelo que nombra, con las tareas y herramientas del proyecto notificadas como propias de su programa, el programa en sí nunca leído, y una
Releaseque deja al operador la tarea de nombrar la imagen que lo ejecuta. - LangGraph: los grafos que declara la configuración de una aplicación de LangGraph, cada uno generado como borrador en forma del agente LangGraph de la biblioteca estándar que contiene la ruta de importación de su grafo y está conectado al almacén de datos en el que su checkpointer guarda el estado, con una
Releaseque indica, en un comentario, el entorno que declara la configuración, y el código de los grafos nunca leído. - Google ADK: los árboles de agentes que declaran las configuraciones de agentes de una aplicación de Google ADK, cada uno generado como borrador en forma del agente ADK de la biblioteca estándar conectado al modelo que nombra cuando ADK envía las solicitudes de ese modelo a la API de Gemini, mientras que un modelo al que se accede de cualquier otra forma —mediante una cadena de modelo de LiteLLM, por ejemplo— se nombra en un comentario y su conexión se deja al autor, con una
Releaseque deja al operador la tarea de nombrar la imagen que ejecuta la aplicación, y el código de la aplicación nunca leído. - Agent Framework: un agente declarativo de Agent Framework, generado como borrador en forma del agente Agent Framework de la biblioteca estándar conectado al modelo de OpenAI que nombra, con cada servidor MCP que nombra escrito en comentarios, ya que el proveedor del modelo accede a él como herramienta alojada, con una
Releaseque contiene el endpoint del modelo y, en un comentario, la dirección de cada servidor, y el código de la aplicación nunca leído.
Son plugins de importación como cualquier otro —la inteligencia de correspondencia específica de cada formato reside en ellos, no en el núcleo—, construidos a partir del código fuente del compilador y publicados con cada versión del compilador con el número de esa versión. Ninguno está compilado en el binario: el binario lleva la entidad Plugin de cada uno y el digest del único módulo que acepta, de modo que cada uno sirve su formato en todos los workspaces sin ninguna entrada de catálogo. La primera importación que necesita uno que la máquina no tiene lo descarga del registro predeterminado del workspace, lo vincula a ese digest, lo verifica igual que un pull verifica un plugin que descarga —su firma según la política de confianza de ese registro, y las funciones del host que usa— y lo guarda en la caché de contenido del workspace; cada importación posterior lo lee de ahí, sin acceder a la red para él. Una importación no fija ningún importador: no se escribe nada más para él —ninguna entrada de lockfile ni ningún registro de plugins de confianza—, ningún pull lo almacena en caché y ninguna build lo lee. Un módulo que no supera la verificación se rechaza, y no se guarda nada. Donde el módulo no puede descargarse —el workspace está sin conexión, no se puede acceder a su registro o el registro no lo contiene—, la importación se detiene, nombrando el importador, su versión y lo que coloca su módulo en la máquina. La elección sigue siendo del workspace: un importador que su catálogo contiene con otro nombre para uno de estos formatos se ejecuta donde lo nombra una conexión plugins.importer, y uno con el mismo nombre y la misma versión que un importador del núcleo se ejecuta en su lugar.
Sembrar y hacer crecer un catálogo
Un catálogo no tiene que construirse desde cero. La mayor parte del trabajo de sembrar Recipes y plugins para un entorno nuevo consiste en andamiaje y reutilización, más que en escribir cada binario a mano.
Importar una fuente externa a borradores de archivos de autoría. aggrega import <file or directory> lee una fuente declarativa de definición de agentes —un flow de Langflow o Flowise, un workflow de n8n, o la configuración de un cliente MCP o la descripción de un servidor de un registro MCP—, una aplicación Compose, una aplicación Dify, los agentes que declara un proyecto CrewAI, los grafos que declara la configuración de una aplicación LangGraph, los agentes que declaran las configuraciones de agentes de una aplicación Google ADK, o un agente declarativo de Agent Framework, y genera un primer borrador de YAML Aggregate y Component, y, a partir de una fuente MCP, Compose, CrewAI, LangGraph, Google ADK o Agent Framework, un borrador de Release, para que un autor lo revise y lo termine, de modo que un equipo aproveche lo que ya tiene en lugar de volver a escribirlo a mano. Para cada nodo de un flow, y cada servicio de una aplicación Compose, puntúa los Components del propio catálogo del espacio de trabajo —el de un catálogo empresarial tanto como el de la biblioteca estándar— con un modelo de confianza determinista y sin modelo, y registra la decisión —los candidatos que evaluó, el nivel que asignó y la elección que hizo— como indicaciones revisables, de las que informan el comando, el editor y el asistente; una coincidencia de alta confianza puede escribirse como referencia al catálogo cuando el operador lo habilita, siempre como una sugerencia explícita y reversible que el autor aprueba y no como una reescritura silenciosa. Cada Component que gana un catálogo es un candidato que evalúa la siguiente importación. La inteligencia de mapeo específica de cada formato reside en un plugin importador: los importadores Langflow, Flowise, n8n, MCP, Compose, Dify, CrewAI, LangGraph, Google ADK y Agent Framework del compilador sirven esos formatos en cada espacio de trabajo, descargados y verificados en el primer uso, y un catálogo añade un formato al contener un plugin importador que lo anuncia. Una fuente de tipo directorio se lee a través de los patrones de archivo que declara su importador; los importadores Langflow, Flowise, n8n, Dify y Agent Framework no declaran ninguno, y cada uno lee un único archivo exportado o agente declarativo, mientras que el importador MCP lee las configuraciones de cliente que contiene un directorio, el importador Compose sus archivos Compose, fusionados como los fusiona Compose, el importador CrewAI las declaraciones de un proyecto, nunca su programa, el importador LangGraph la configuración de una aplicación, nunca su código ni un archivo de entorno —cuyos nombres solo lee cuando su vinculación le entrega el archivo—, y el importador Google ADK la configuración del agente raíz de una aplicación, nunca su código ni su archivo de entorno, y lee las configuraciones de sus subagentes cuando su vinculación se las entrega; una configuración que ADK declara experimental, cuyos agentes usan un modelo Gemini de forma predeterminada y llegan por su nombre a los modelos de otros proveedores mediante clases propias de ADK, o mediante una cadena de modelo LiteLLM.
La mayor parte del trabajo con plugins son plantillas, no código compilado. Una gran parte de las funcionalidades solo inyecta un sidecar estático, una variable de entorno o una etiqueta: un JSONPatch simple sin lógica condicional. Un único plugin patcher configurable, escrito una sola vez para tomar una plantilla JSONPatch declarativa como su entrada with, puede cubrir ese caso común sin un binario compilado propio para cada funcionalidad: el autor escribe una plantilla, y para muchos destinos de estilo CRD basta por sí sola una plantilla valuesMapping (que a menudo hace referencia a fragmentos compartidos en una entrada de MappingLibrary). Los plugins PDK escritos a medida son para el resto, realmente condicional.
Tomar como referencia herramientas consolidadas. Al escribir nueva lógica de plugin, los autores pueden consultar las formas de salida documentadas públicamente de herramientas de código abierto consolidadas —la estructura de los CRD, parches o plantillas que se sabe que esas herramientas emiten— como referencia de la forma de destino que debe producir un nuevo plugin, respetando la licencia de cada proyecto. Los webhooks de inyección de sidecars, las bibliotecas de constructos de alto nivel, los generadores de CRD para operadores y los catálogos de traits o de composición publican estructuras de salida que se corresponden estrechamente con lo que debe emitir una FeatureRecipe o un plugin comparable. El objetivo es ajustarse a un contrato de salida bien conocido, no copiar la implementación de ningún proyecto.