Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Importadores core

El repositorio del compilador compila diez plugins importadores propios, uno para cada formato de origen, y los publica con cada versión del compilador:

PluginSirveLee
importer/langflowimport:langflowun flujo exportado desde Langflow, en JSON
importer/flowiseimport:flowiseun chatflow o un agentflow exportado desde Flowise, en JSON
importer/n8nimport:n8nun flujo de trabajo exportado desde n8n, en JSON
importer/mcpimport:mcpla configuración de un cliente MCP — .mcp.json, claude_desktop_config.json, .vscode/mcp.json o .cursor/mcp.json — o una descripción de servidor del registro MCP, server.json, en JSON
importer/composeimport:composeuna aplicación Compose — compose.yaml, docker-compose.yml y sus archivos de sobrescritura — en YAML
importer/difyimport:difyuna aplicación exportada desde Dify en su DSL, en YAML
importer/crewaiimport:crewailos agentes y las tareas que declara un proyecto CrewAI — config/agents.yaml y config/tasks.yaml, en YAML, o crew.jsonc y agents/<name>.jsonc, o sus variantes en JSON estricto crew.json y agents/<name>.json, en JSON con comentarios
importer/langgraphimport:langgraphla configuración de una aplicación LangGraph, langgraph.json, en JSON, y, de un archivo de entorno que la configuración nombra, solo los nombres de las variables, cuando a la importación se le entrega ese archivo bajo with.sources
importer/google-adkimport:google-adklos agentes declarados en los archivos Agent Config de una aplicación construida sobre Google ADK — root_agent.yaml y las configuraciones que nombran sus subagentes — en YAML
importer/agent-frameworkimport:agent-frameworkun agente declarativo de Microsoft Agent Framework, un documento de tipo Prompt con cualquier nombre, en YAML

Cada uno se compila a partir de las fuentes del propio compilador y se marca con la versión del compilador, de modo que los importadores publicados con el compilador en X.Y.Z informan de la versión X.Y.Z, y sus entidades Plugin la registran. A diferencia de los plugins enumerados en Plugins integrados, ninguno se compila dentro del binario. El binario lleva la entidad Plugin de cada uno y el digest del único módulo que acepta para él, de modo que cada uno sirve su formato en todo espacio de trabajo, sin ninguna entrada en su catálogo.

Los diez se basan en el paquete importer del kit de Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Para los importadores Langflow, Flowise y n8n, todo lo que hace un importador sea cual sea su formato — puntuar los Components del catálogo del espacio de trabajo frente a cada nodo, decidir si hacer referencia a uno de ellos o generar uno nuevo como borrador, disponer el borrador, trasladar los valores de credenciales que contiene o escribirlos vacíos según pida un ajuste, escribir los borradores y leer los ajustes descritos más abajo — corresponde a ese paquete, y solo leer el formato, y conocer la plataforma en la que se ejecutan sus flujos, es propio de cada importador. El importador MCP genera como borrador una instancia de un Component por servidor, así que no puntúa nada; comparte con el paquete la lectura de los ajustes que lee, su decisión sobre los valores de credenciales y las convenciones con las que se nombran y describen sus borradores, como describe El importador MCP. El importador Compose decide cada servicio con el que encuentra coincidencia como los importadores de flujos deciden un nodo, mediante el mismo paquete, renderiza sus borradores como ellos y comparte el resto como lo hace el importador MCP, como describe El importador Compose. El importador Dify genera como borrador la instalación de Dify que ensambla la biblioteca estándar, que lleva la aplicación, mediante el borrador de plataforma del mismo paquete en la forma que adopta para una plataforma que es una instalación completa, como describe El importador Dify. El importador CrewAI genera como borrador una instancia del agente CrewAI de la biblioteca estándar por cada agente que declara un proyecto, conectada al modelo que nombra ese agente, y comparte el resto como lo hace el importador MCP, como describe El importador CrewAI. El importador LangGraph genera como borrador una instancia del agente LangGraph de la biblioteca estándar por cada grafo que declara la configuración de una aplicación, conectada al almacén de datos en el que su checkpointer guarda el estado, y comparte el resto como lo hace el importador MCP, como describe El importador LangGraph. El importador Google ADK genera como borrador una instancia del agente ADK de la biblioteca estándar por cada árbol de agentes que declaran las configuraciones de una aplicación, conectada al modelo que nombra el árbol cuando ADK envía sus solicitudes a la API de Gemini, y comparte el resto como lo hace el importador MCP, como describe El importador Google ADK. El importador Agent Framework genera como borrador una instancia del agente Agent Framework de la biblioteca estándar por cada agente declarativo, conectada al modelo OpenAI que nombra ese agente — con cada servidor MCP que nombra escrito en comentarios, ya que el proveedor del modelo llega a él como una herramienta alojada — y comparte el resto como lo hace el importador MCP, como describe El importador Agent Framework. Cómo funciona el socket importador, y qué recibe, se describe en El socket importador.

Esta página es la referencia de lo que cada importador lee y genera como borrador. Para importar un proyecto propio y compilar el resultado, empieza en Importación, que lleva un proyecto desde su origen hasta una compilación, un formato cada vez.

Cómo una importación obtiene uno

aggrega import, el método aggrega/import de la sesión del editor y la herramienta import del asistente obtienen un importador core de la misma manera. Donde la máquina ya contiene su módulo — en la caché de contenido del espacio de trabajo —, la importación lo lee de ahí, sin necesidad de red para ello. Donde no lo contiene, la primera importación que lo necesita lo descarga del registro predeterminado del espacio de trabajo, en la versión del compilador, y:

  • lo contrasta con el digest que lleva el binario, de modo que solo se ejecuta el módulo que publicó la versión del compilador;
  • lo verifica como un pull verifica un plugin que descarga — su firma según la política de confianza de ese registro, y las funciones host que usa frente a las que registra su entidad Plugin;
  • lo conserva en la caché de contenido del espacio de trabajo, que es lo único que se escribe para él: ningún archivo de bloqueo, y ningún registro de plugins de confianza, porque una importación no fija ningún importador.

Cada importación posterior lo lee de la caché de contenido. Un módulo que no supera la verificación se rechaza, y no se conserva nada. En una carpeta que ningún espacio de trabajo marca no hay caché de contenido en la que conservarlo, así que allí se rechaza la descarga, nombrando la carpeta y cómo nombrar un espacio de trabajo o convertir la carpeta en uno. El módulo nunca se lee de junto a una entidad Plugin del mismo nombre en otra versión en una carpeta de catálogo: ese módulo pertenece a la otra entidad.

Donde el módulo no puede descargarse, la importación se detiene bajo A plugin’s .wasm is not on this machine (El archivo Wasm de un plugin no está en esta máquina), nombrando el importador y su versión, y dice qué pone su módulo en la máquina:

  • Ejecuta la importación una vez con la red disponible, donde el espacio de trabajo está sin conexión o no se pudo alcanzar su registro. Esa ejecución lo descarga y cada ejecución posterior es sin conexión.
  • Coloca su módulo junto a una entidad Plugin de ese importador en esa versión en una carpeta de catálogo, con el nombre que da el mensaje — importer--langflow.wasm para el importador Langflow. Una entidad de catálogo con el mismo nombre y la misma versión que un importador core se ejecuta en su lugar, con su módulo leído de junto a ella; una entidad que esté allí sin módulo junto a ella no lo hace, y el importador core se obtiene como se describe arriba. Donde el registro no contiene el módulo, o el espacio de trabajo no nombra ningún registro predeterminado, este es el único remedio que da el mensaje.

Cuál se ejecuta junto a tus propios importadores

Los importadores core son candidatos junto a los importadores que contiene el catálogo de tu espacio de trabajo, según las reglas por las que se selecciona todo importador, que expone Qué importador convierte un origen en borradores:

  • Dentro de un mismo nombre se ejecuta la versión más alta, o la versión que nombra una entrada plugins.importer.
  • Donde tu catálogo contiene un importador de otro nombre para langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk o agent-framework, dos importadores anuncian el formato, y una importación que no vincula ninguno de los dos se rechaza nombrando ambos, bajo A parse or import format is advertised by more than one plugin (Un formato de análisis o de importación lo anuncia más de un plugin). Una entrada plugins.importer que nombre el que quieres lo resuelve.
  • Un importador que tu catálogo contiene con el mismo nombre y la misma versión que un importador core, con su módulo junto a su entidad, es el que se ejecuta, leído desde allí.
  • Una entidad Plugin con el nombre de un importador core y sin módulo junto a ella en su carpeta de catálogo — un checkout de un catálogo que registra los importadores que publicó una versión, por ejemplo — es una que ninguna importación podría ejecutar, ya que su módulo no se lee de ningún otro sitio; por eso no es candidata a ejecutarse, aunque las firmas que registra siguen participando en el reconocimiento de una fuente. En la versión propia del compilador, el importador core se ejecuta en su lugar. En cualquier otra versión, anterior o posterior, se omite, y la elección se hace entre los importadores que pueden ejecutarse — salvo que una entrada plugins.importer nombre exactamente esa versión, o que ningún importador de ese nombre que pueda ejecutarse anuncie el formato solicitado, como cuando la entidad registra un formato que el importador propio del compilador no registra. Entonces sigue siendo candidata según las reglas anteriores, y una importación que la elige se detiene nombrando la carpeta donde va su módulo.

Sea cual sea el importador propio de tu catálogo que se elija, su módulo se lee de junto a su propia entidad, en su propia versión: un módulo colocado junto a una entidad del mismo nombre en otra versión pertenece a esa entidad.

Cómo se reconoce un origen

Una importación que no nombra su formato con --format se reconoce por las firmas que declara cada importador:

  • Langflow — un origen que se analiza como JSON y lleva un array en data.nodes.
  • Flowise — un origen que se analiza como JSON, lleva arrays en nodes y edges, y no lleva nada en data.nodes.
  • n8n — un origen que se analiza como JSON, lleva un array en nodes y un objeto en connections, y no lleva nada en edges ni en data.nodes.
  • MCP — un origen que se analiza como JSON, se llama .mcp.json, claude_desktop_config.json o .cursor/mcp.json y lleva un objeto en mcpServers; un origen que se analiza como JSON con comentarios, tal como lo lee Visual Studio Code, se llama .vscode/mcp.json y lleva un objeto en servers; o un origen de cualquier nombre que se analiza como JSON y cuyo $schema es un texto que empieza por https://static.modelcontextprotocol.io/schemas/, una descripción de servidor de registro. Un nombre se compara con el final de la ruta que se entrega a la importación, de modo que project/.vscode/mcp.json se reconoce, mientras que mcp.json entregado desde dentro de .vscode, o el archivo de un cliente con cualquier otro nombre, se importa nombrando --format mcp.
  • Compose — un origen que se analiza como YAML, tiene uno de los nombres con los que Compose lee por defecto un archivo Compose o su archivo de sobrescritura — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml, compose.override.yml, compose.override.yaml, docker-compose.override.yml o docker-compose.override.yaml — y lleva un objeto en services. Un archivo Compose con cualquier otro nombre se importa nombrando --format compose.
  • Dify — un origen de cualquier nombre que se analiza como YAML, lleva el texto app en kind, y lleva algo en app.mode y en version, como hace toda aplicación que exporta Dify.
  • CrewAI — un origen llamado config/agents.yaml o config/tasks.yaml que se analiza como YAML, un origen llamado crew.jsonc o crew.json que se analiza como JSON con comentarios y lleva una lista en agents, o un origen llamado agents/<name>.jsonc o agents/<name>.json que se analiza como JSON con comentarios y lleva algo en role. Un proyecto clásico identifica sus agentes y sus tareas por nombres que elige su autor, así que sus dos archivos se distinguen solo por su nombre.
  • LangGraph — un origen llamado langgraph.json que se analiza como JSON y lleva un objeto en graphs; o un origen de cualquier nombre que se analiza como JSON, lleva un objeto en graphs y cuyo $schema es el texto https://langgra.ph/schema.json, el esquema que LangGraph publica para su configuración. Una configuración con otro nombre que no nombra ningún esquema se importa nombrando --format langgraph. Ninguna firma de importador nombra un archivo de entorno, así que reconocer un directorio no abre ninguno.
  • Google ADK — un origen llamado root_agent.yaml que se analiza como YAML y lleva algo en name y en instruction, como hace la configuración de un LlmAgent, o un texto en agent_class y algo en name, como hace la de cualquier otro agente. Una configuración con otro nombre se importa nombrando --format google-adk. Ninguna firma nombra la configuración de un subagente, que puede llamarse de cualquier forma, así que reconocer un directorio no abre ningún archivo YAML salvo root_agent.yaml.
  • Agent Framework — un origen de cualquier nombre que se analiza como YAML, lleva el texto Prompt en kind y un objeto en model, como hace un agente declarativo que nombra su modelo; Agent Framework carga un agente declarativo desde el archivo que nombre su aplicación, sea cual sea, así que la firma no nombra ningún archivo. Un agente declarativo que no nombra ningún modelo, o que escribe su tipo con otra combinación de mayúsculas y minúsculas o como Agent, se importa nombrando --format agent-framework.

Un origen que coincide con dos de ellas se rechaza nombrando ambos formatos, y se importa nombrando el correcto con --format. Los importadores Langflow, Flowise, n8n y LangGraph leen su origen mediante el analizador que sirve parse:json; el importador MCP, una configuración que enumera sus servidores bajo servers mediante el que sirve parse:jsonc y cualquier otro origen mediante el que sirve parse:json; los importadores Compose, Dify, Google ADK y Agent Framework, mediante el que sirve parse:yaml; y el importador CrewAI, los archivos de un proyecto clásico mediante el que sirve parse:yaml y los demás mediante el que sirve parse:jsonc: el que sirve el catálogo de tu espacio de trabajo, donde sirve uno, y en otro caso el analizador que el propio compilador incluye para esa sintaxis (consulta Plugins integrados). Así, una importación mediante cualquiera de ellos no necesita ningún analizador en tu catálogo, y no se descarga nada para uno. Un analizador que tu catálogo sí sirve es el que se usa, y el del compilador no interviene. Los importadores Langflow, Flowise, n8n, Dify y Agent Framework no declaran ningún patrón de archivo, así que cada uno lee un único archivo y una importación de un directorio mediante cualquiera de ellos se rechaza; el importador MCP declara los cuatro nombres de archivo de los clientes, así que un directorio se lee a través de las configuraciones de cliente que contiene; el importador Compose declara los ocho nombres de archivo de Compose, así que un directorio se lee a través de los archivos Compose que contiene; el importador CrewAI declara los seis nombres de las declaraciones de un proyecto, así que el directorio de un proyecto se lee a través de sus declaraciones y nada más; el importador LangGraph declara langgraph.json, así que el directorio de una aplicación se lee solo a través de su configuración, y nunca se leen ni su código ni un archivo de entorno; y el importador Google ADK declara root_agent.yaml, así que el directorio de una aplicación se lee solo a través de su configuración raíz — las configuraciones que nombran sus subagentes llegan al importador solo bajo el with.sources de su vinculación — y nunca se leen ni su código ni su archivo de entorno. Una firma que no nombra ningún archivo — las de los importadores Langflow, Flowise y n8n, la del importador MCP para una descripción de servidor de registro, la del importador LangGraph para una configuración que nombra su esquema, la del importador Dify y la del importador Agent Framework — se aplica a todo archivo importado por sí solo: una importación que no nombra ningún formato lee un archivo así como JSON, y como YAML, para probar ambos, sea cual sea el importador al que esté destinado, mediante esos mismos analizadores — el compilador incluye ambos, así que no se descarga nada para ninguno de los dos. Un archivo que contiene un comentario o una coma final no se analiza como JSON, así que ninguna firma que lea JSON lo reconoce; las firmas del importador CrewAI para crew.jsonc, agents/<name>.jsonc y sus variantes .json, y la del importador MCP para .vscode/mcp.json, leen JSON con comentarios, mediante el analizador que el compilador incluye para esa sintaxis donde tu catálogo no sirve ninguno.

Un origen que su analizador rechaza — para los importadores Langflow, Flowise, n8n y LangGraph, uno que no es JSON; para el importador MCP, uno que no es JSON con comentarios o, salvo que enumere sus servidores bajo servers, no es JSON; para los importadores Compose, Dify y Agent Framework, uno que no es YAML; para el importador CrewAI, una declaración que no es YAML o no es JSON con comentarios; y para el importador Google ADK, una configuración que no es YAML — detiene la importación bajo parse-failed, cuyo mensaje lleva el motivo propio del analizador. Nombrar el formato no cambia eso: el importador pide el árbol del origen, y el rechazo del analizador es la respuesta que obtiene.

Cómo se nombra un borrador

Cada importador asigna al Aggregate que genera como borrador, y a la Release junto a él cuando genera una, el nombre <target_namespace>/<name>. La primera parte es el ajuste target_namespace, imported a menos que establezcas otro. <name> es el primero de los siguientes que no esté vacío:

  • el nombre que la fuente se da a sí misma, en el campo en el que su formato lo declara:

    ImportadorEl nombre que lee
    importer/langflowel name del flujo
    importer/flowiseninguno: una exportación no lleva un nombre propio
    importer/n8nel name del workflow
    importer/mcpel name de la descripción de un servidor de registro; la configuración de un cliente no lleva ninguno
    importer/composeel name de nivel superior del proyecto, el de un archivo de anulación en lugar del del archivo que anula, tal como Compose los combina
    importer/difyel name de la aplicación, bajo app
    importer/crewaiel name de la crew en crew.jsonc o crew.json; config/agents.yaml y config/tasks.yaml no llevan ninguno, ya que un proyecto clásico nombra su crew en su programa
    importer/langgraphel id del grafo que declara la configuración, ya que una configuración no lleva un nombre propio
    importer/google-adkel name del agente raíz
    importer/agent-frameworkel name del agente; su displayName no se lee
  • el nombre del directorio entregado a la importación, completo — my.project conserva su punto, escrito my-project — tal como Compose nombra un proyecto según el directorio que lo contiene; aggrega import . nombra el directorio en el que se ejecuta;

  • el nombre del archivo entregado por sí solo a la importación, sin su extensión;

  • flow.

Un borrador hecho a partir de varias fuentes — varios proyectos de Compose, configuraciones, árboles de agentes o servidores, o una configuración que declara varios grafos — toma su nombre solo si cada una de ellas se nombra a sí misma y todos se escriben igual; de lo contrario, toma el siguiente. Un nombre se escribe en minúsculas, cada secuencia de caracteres distintos de las letras y dígitos ASCII como un solo guion, y se eliminan los guiones de ambos extremos: Basic Prompting se escribe basic-prompting, y SupportAgent supportagent. La misma fuente recibe el mismo nombre en cada importación. Un Manifest que una importación genera como borrador para un destino toma el nombre de la Release, o el del Aggregate cuando no se genera ninguna Release, como describe Qué añade un destino.

Qué lee el importador Langflow

  • Los nodos y las aristas bajo el objeto data de nivel superior del flujo, data.nodes y data.edges.
  • Para cada nodo, su tipo a partir del data.type del nodo, y sus campos a partir de las entradas de data.node.template cuyo valor es un objeto que lleva un type. Las demás entradas de la plantilla no son campos.
  • Un campo cuyo objeto lleva password: true se incluye en el borrador como ranura de credencial, y cualquier otro campo como campo de valor. El nombre del campo no interviene, e incluir un nodo en el borrador como Component no lee el valor de ningún campo.
  • Una nota fijada al lienzo, un nodo de tipo noteNode, no se importa, y una arista hacia un nodo que no se importa se descarta.
  • Generar como borrador la plataforma que lleva el flujo lee también, del flujo: su id de nivel superior; el valor de cada campo marcado con password: true; el campo mcp_server de un nodo MCP Tools — el servidor MCP que nombra, y la configuración de ese servidor — o, en su lugar, los campos en los que guarda su servidor; cada entrada que Langflow no marca como credencial pero que puede llevar una, tal como las enumera Valores de credenciales que contiene el flujo; el campo en el que un nodo nombra su modelo, y el proveedor del modelo en el que se ejecuta; y los campos mediante los que un nodo llega a la dirección y la clave de una parte, que reescribe. Qué generan como borrador dice en qué se convierte cada uno.

Qué lee el importador Flowise

  • Los nodos y las aristas del nivel superior del flujo, nodes y edges.
  • Para cada nodo, su tipo a partir del data.name del nodo; sus ranuras de credencial a partir de las entradas de data.inputParams cuyo type es credential, por su name; y sus campos de valor a partir de las claves de data.inputs, menos las que nombra data.inputAnchors — donde otro nodo se conecta como entrada, lo que registra la arista entre ellos — y menos las credenciales.
  • Incluir un nodo en el borrador como Component no lee el valor de ningún campo, y el nombre de una credencial no interviene en que lo sea.
  • Una nota fijada al lienzo, un nodo de tipo stickyNote, no se importa, y una arista hacia un nodo que no se importa se descarta.
  • Generar como borrador la plataforma que lleva el chatflow lee también, de él: su id de nivel superior, donde es un UUID; la credencial que un nodo guarda en data.credential; el valor de cada entrada que sus inputParams declaran de tipo password; FLOWISE_CREDENTIAL_ID entre las entradas de un nodo, y credential o FLOWISE_CREDENTIAL_ID dentro de un objeto de configuración a cualquier profundidad de ellas; la configuración del servidor en la entrada mcpServerConfig de un nodo; cada entrada que Flowise no marca como credencial pero que puede llevar una, tal como las enumera Valores de credenciales que contiene el flujo, y el miembro en el que la configuración de un agentflow nombra el modelo o la herramienta que selecciona; la entrada modelName de un nodo; y el Base Path de un nodo OpenAI, su entrada basepath. Qué generan como borrador dice en qué se convierte cada uno.

Qué lee el importador n8n

  • Los nodes del workflow y sus connections, en el nivel superior de la exportación.
  • Para cada nodo, su name, que lo identifica — las conexiones de n8n nombran por su nombre los nodos que unen, y los nombres de los nodos de un workflow son únicos — y su type, escrito completo, con su paquete: @n8n/n8n-nodes-langchain.lmChatOpenAi, por ejemplo, o n8n-nodes-base.httpRequest. Un nodo sin nombre se identifica por su id.
  • Cada conexión que enumera el workflow es una arista, desde el nodo del que sale hasta el nodo en el que entra, sea cual sea su tipo: una conexión main lleva datos de un nodo al siguiente, y una conexión de IA — ai_languageModel, ai_tool, ai_vectorStore, ai_embedding, ai_memory y las demás — entrega al nodo en el que entra el modelo, la herramienta, el almacén o la memoria que representa el nodo del que sale. En cualquier caso, el nodo en el que entra una conexión consume el nodo del que sale.
  • Cada tipo de credencial que nombran las credentials de un nodo, y cada parámetro de nivel superior que n8n marca como contraseña, se incluye en el borrador como ranura de credencial; cualquier otro parámetro de nivel superior del nodo es un campo de valor. Incluir un nodo en el borrador como Component no lee el valor de ningún campo.
  • Una nota fijada al lienzo, un nodo de tipo n8n-nodes-base.stickyNote, no se importa, y una conexión hacia un nodo que no se importa se descarta.
  • Generar como borrador la plataforma que lleva el workflow lee también, de él: su id de nivel superior; cada credencial que selecciona un nodo; cada parámetro que n8n marca como contraseña; la dirección a la que llama un nodo cliente MCP; los encabezados y los parámetros de consulta que un nodo envía con una solicitud que compone el workflow, tal como los enumera Valores de credenciales que contiene el flujo; y el parámetro en el que un nodo de modelo nombra su modelo. Qué generan como borrador dice en qué se convierte cada uno.

Qué generan como borrador

Cada nodo se puntúa frente a los Components del propio catálogo del espacio de trabajo y nada más, como describe el socket importador, y cada importador lleva una breve tabla que mapea tipos de nodo comunes de su formato — modelos de chat y de embeddings, recuperación, solicitudes HTTP y, en Langflow, el nodo MCP Tools MCPTools, que se mapea a core/ai-tool/mcp — a Components de la biblioteca estándar. La tabla de Langflow también mapea su componente Language Model, LanguageModelComponent, el modelo de chat al que llaman sus flujos de inicio, a core/ai-model/openai, el modelo que sirve la conexión de modelo de la plataforma Langflow: el nodo se ejecuta en el proveedor de modelos que nombra su campo provider, OpenAI de forma predeterminada, y un nodo que nombra otro proveedor nunca se enlaza con esa conexión, como describe Qué nodos se convierten en partes. La tabla del importador n8n mapea los modelos de chat y de embeddings de n8n, su herramienta cliente MCP a core/ai-tool/mcp, sus herramientas de solicitud HTTP, su herramienta SerpApi, sus almacenes vectoriales Qdrant, PGVector, Chroma, Milvus y Weaviate, y sus memorias de chat Postgres y Redis. Un nodo que n8n ejecuta dentro del propio workflow — un agente, una cadena, un disparador, una memoria que el workflow guarda en su propio proceso, una herramienta de código — es del propio workflow, y ninguna fila lo mapea. Una fila de esa tabla cuenta para una coincidencia solo donde el catálogo del espacio de trabajo contiene el Component que nombra. El comando informa de una línea por cada nodo que mapeó, nombrando lo que eligió, el nivel de coincidencia y la puntuación del mejor candidato, y una línea que dice made no choice for <node id> (<node type>) para un nodo al que no da ningún Component propio. Un nodo que hace referencia a un Component del catálogo, en lugar de generarse como borrador, no tiene archivo propio: el Aggregate del borrador nombra el Component.

Cómo se dispone el borrador lo decide el ajuste layout. platform, el valor predeterminado, genera como borrador la plataforma que ejecuta el flujo, llevando el flujo tal como se exportó, y da un Component propio solo a cada parte del flujo que acepta 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 llega por HTTP, y un almacén vectorial. nodes genera como borrador cada nodo como un Component propio.

La plataforma que lleva el flujo

De forma predeterminada, una importación escribe:

  • aggregate.yaml — un Aggregate de borrador nombrado según el flujo, como describe Cómo se nombra un borrador. Contiene una instancia de la plataforma que ejecuta el flujo — core/ai-agent/langflow, bajo la clave langflow, para un flujo de Langflow, core/ai-agent/flowise, bajo la clave flowise, para uno de Flowise, y core/ai-agent/n8n, bajo la clave n8n, para un workflow de n8n — que hace referencia al Component del catálogo con ese nombre. La instancia lleva el flujo en values.flow_definition y lo nombra en su valor identificador, flow_id en Langflow, chatflow_id en Flowise y workflow_id en n8n. Cada parte del flujo es una entrada propia junto a ella, conectada a la plataforma bajo los uses de la instancia.
  • release.yaml — una Release borrador con el mismo nombre, que nombra ese Aggregate, con una entrada para la plataforma y una para cada parte, que lleva la imagen de la plataforma y vincula por referencia cada secreto que necesita el borrador, como describe Lo que el borrador deja para la Release.
  • un archivo bajo components/ por cada parte que genera como borrador en lugar de referenciarla, escrito como la disposición nodo por nodo escribe un nodo generado como borrador.

Dado un destino, la importación genera manifest.yaml junto a ellos, como describe Lo que añade un destino.

Todo nodo que no es una parte se queda dentro del flujo que lleva la plataforma y no se convierte en ningún Component. Su decisión registra los candidatos frente a los que se puntuó y no elige nada, y su justificación dice kept in the flow <platform> carries, with no Component of its own:, seguido del motivo — por ejemplo, que ninguna fila de mapeo nombra su tipo y que su candidato más cercano obtuvo solo cierta puntuación. El flujo conserva las aristas entre nodos; el borrador no escribe ninguna propia.

El chatflow Multiple Documents QnA de Flowise, exportado como Multiple Documents QnA.json e importado sin ningún ajuste y sin destino sobre un catálogo que contiene la plataforma Flowise de la biblioteca estándar y sus Components de modelo y de herramienta de recuperación, se genera como borrador como este Aggregate, con la mayor parte del flujo omitida aquí y marcada con ...:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/multiple-documents-qna
version: 0.1.0
description: Draft Aggregate imported from a source in the flowise format.
spec:
components:
flowise:
type: core/ai-agent/flowise
# For the compose target only, uncomment the lines below, which declare owner_password on flowise: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# owner_password:
# type: core/secret-value
# values:
# key: OWNER_PASSWORD
values:
# chatflow_id is derived from the exported flow, which gives no identifier of its own.
chatflow_id: '96da3b80-86d0-5f23-b4e7-2573ea1f76ad'
flow_definition: |
{
"description": "Tool agent that can retrieve answers from multiple sources using relevant Retriever Tools",
...
"embeddings": "{{"{{"}}openAIEmbeddings_0.data.instance}}",
...
}
uses:
model:
chatopenai-0:
target: chatopenai-0
# For the compose target only, uncomment the lines below, which declare credential on chatopenai-0: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: OPENAI_API_KEY
# swap to core/ai-model/azure-openai (score 0.4000) by setting type: core/ai-model/azure-openai
chatopenai-0:
type: core/ai-model/openai
values:
model: |-
gpt-3.5-turbo

Su modelo de chat es la única parte conectada; sus dos modelos de embeddings se quedan en el flujo, ya que el socket de modelo admite una sola conexión, y sus herramientas retriever se quedan en el flujo, ya que ningún socket de la plataforma las acepta. La importación informa de cada una.

El identificador del flujo es el que le da la exportación — el id de nivel superior de un flujo de Langflow, el id de nivel superior de un chatflow de Flowise donde es un UUID, y el id de nivel superior de un workflow de n8n — donde tiene de una a 128 letras, dígitos, ., -, _ o :, y empieza por una letra o un dígito. Donde la exportación no da ninguno, o da uno que contiene cualquier otro carácter, el borrador escribe un UUID basado en nombre derivado del nombre del formato y del flujo tal como se lleva, de modo que un flujo siempre produce un mismo identificador, y un comentario sobre el valor dice que se derivó. Un chatflow exportado desde el editor de Flowise no lleva ningún id, así que se le da uno derivado.

Donde el catálogo del espacio de trabajo no contiene ningún Component con el nombre de la plataforma, el borrador nombra la plataforma de todos modos y no le conecta ninguna parte: cada nodo que habría sido una parte se queda en el flujo, se informa de él, y la importación advierte de que el catálogo no contiene tal Component.

Qué nodos se convierten en partes, y dónde se conecta cada uno

Un nodo es una parte del flujo donde una fila de la tabla de mapeo del importador, o una entrada mapping_overrides, mapea su tipo, o donde su mejor candidato es al menos una coincidencia de nivel medio. Un nodo MCP Tools de Langflow es una parte sean cuales sean sus puntuaciones: nombra el servidor MCP al que llama, y ese servidor es la parte. Una parte se convierte en un Component propio, referenciado o generado como borrador exactamente como decide reuse_mode, y se conecta al primer socket de la plataforma — en el orden en que la entrada de catálogo de la plataforma declara sus sockets — cuyo selector de etiquetas satisface el Component de la parte: las etiquetas del Component al que hace referencia o, para una parte que genera como borrador, las de su mejor candidato donde ese candidato es al menos una coincidencia de nivel medio. Una parte cuyo Component no satisface el selector de ningún socket, o que no tiene ningún Component del que leer etiquetas, se queda en el flujo, y la importación informa de ella.

Estas reglas lo acotan:

  • Un modelo de Langflow que nombra otro proveedor no recibe ninguna conexión de modelo. Un nodo LanguageModelComponent o EmbeddingModel se ejecuta en el proveedor de modelos que nombra su campo provider o, donde este está vacío, en el proveedor del modelo que selecciona su campo model. La plataforma entrega su conexión de modelo para un cliente compatible con OpenAI, así que un nodo que nombra cualquier proveedor distinto de OpenAI — sea cual sea aquello a lo que lo mapee una fila de mapeo o una sobrescritura — nunca se enlaza con el socket model: se enlaza con el siguiente socket que satisface su Component, o permanece en el flujo, sin que su decisión elija nada y sin ningún Component generado como borrador para él, y la importación lo informa nombrando el proveedor en el que se ejecuta. Un nodo que no selecciona ningún proveedor, que lo nombra mediante una variable global o que toma su modelo de otro nodo se enlaza como cualquier otra parte.
  • Un socket que admite una sola conexión lo ocupa una sola parte. En toda plataforma, el socket model admite una conexión, que las Recipes de la plataforma entregan como un único OPENAI_BASE_URL y un único OPENAI_API_KEY. Donde se colocan varias partes en él, lo ocupa la primera cuyo Component lleva model.aggrega.ai/capability: generative — la primera parte, donde ninguna lo lleva — y cualquier otra se queda en el flujo, y se informa de ella junto con la parte que ocupa la conexión y con cómo la alcanza el flujo tal como está escrito su nodo.
  • Langflow llega a una conexión tools solo a través de un nodo MCP Tools que la nombra. La plataforma escribe la dirección de una conexión tools en la configuración de servidor del nodo MCP Tools cuyo campo mcp_server nombra la conexión, de modo que un nodo cuya plantilla no lleva ningún campo mcp_server — sea cual sea su tipo, y sea lo que sea a lo que lo mapee una fila de mapeo o una sobrescritura — nunca se conecta al socket tools: se conecta al siguiente socket que satisface su Component, o se queda en el flujo, y se informa de él. Un nodo MCP Tools que no nombra ningún servidor no se conecta a ningún socket y se informa de él. Lo mismo ocurre con uno cuya configuración de servidor inicia un servidor propio — lleva un command, o establece el modo Stdio — y su informe dice qué quitar, ya que la compilación de la plataforma se detiene ante un nodo que nombra un servidor al que no responde ninguna conexión tools.
  • Un servidor MCP se conecta por el nombre que le da el flujo. Los nodos de un flujo que nombran un mismo servidor llegan a una sola parte, generada como borrador una sola vez, a través de una sola conexión. El alias de la conexión es el nombre del servidor donde el alias de una conexión puede adoptarlo — letras, dígitos, guiones y guiones bajos — y ninguna otra conexión de ese socket entrega bajo el mismo nombre de variable, su alias en mayúsculas con cualquier otro carácter escrito como guion bajo. En otro caso, la conexión adopta un alias derivado de la clave de la parte, el servidor del nodo se renombra a ese alias en el flujo que lleva el borrador, y la decisión de la parte lo dice.

La decisión de una parte conectada dice a qué socket de la plataforma está conectada y a través de qué conexión, y nombra cada socket para el que se la descartó y por qué.

Cómo llega el flujo llevado a cada parte

Donde el formato lo permite, el flujo que lleva la plataforma llega a cada parte conectada a través de su conexión, y el borrador escribe en el flujo lo que hace que lo haga — el nombre de una variable, una dirección vaciada, o lo que el nodo enviaría en lugar de lo que suministra la conexión, vaciado, y nunca un valor. Esto es cableado, no la eliminación de un valor de credencial: el borrador lo escribe diga lo que diga el ajuste empty_credentials, ya que un valor que se mantuviera ahí sobrescribiría lo que entrega la conexión.

  • Un nodo MCP Tools de Langflow. La plataforma escribe la dirección que entrega su conexión en la configuración de servidor del nodo y, donde la conexión lleva una credencial, el nombre de la variable que la contiene bajo el encabezado que publica la herramienta. El borrador escribe vacía la dirección que la exportación contenía ahí, de modo que el flujo no guarda ninguna copia de ella, y deja la dirección del servidor — infra.endpoint de la parte — para la Release. Langflow envía el campo headers propio del nodo por encima de los encabezados de su configuración de servidor, así que el borrador escribe vacío el valor completo de ese campo conservando su tipo — un objeto como {}, una lista como [], el texto como una cadena vacía — ya que un encabezado que se mantuviera con su valor vaciado se seguiría enviando, mientras que un objeto o una lista vacíos no sobrescriben nada.

  • Un nodo de modelo o de almacén vectorial de Langflow. La plataforma entrega una conexión de modelo como OPENAI_BASE_URL y OPENAI_API_KEY, y una conexión de almacén vectorial como variables nombradas según su alias, que Langflow lee mediante un campo que nombra una variable global: un campo cuyo objeto lleva load_from_db: true contiene como valor el nombre de la variable, y Langflow lee la variable global de ese nombre, o la variable de entorno de ese nombre donde no hay ninguna almacenada. El borrador escribe cada uno de estos campos con el nombre de la variable y load_from_db: true:

    • el campo openai_api_base de un nodo OpenAIModel, como OPENAI_BASE_URL, y su api_key, como OPENAI_API_KEY;
    • el campo openai_api_base de un nodo OpenAIEmbeddings, como OPENAI_BASE_URL, y su openai_api_key, como OPENAI_API_KEY;
    • el campo api_key de un nodo LanguageModelComponent, como OPENAI_API_KEY;
    • el campo api_base de un nodo EmbeddingModel, como OPENAI_BASE_URL, y su api_key, como OPENAI_API_KEY;
    • el campo pg_server_url de un nodo pgvector, como AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING, donde <ALIAS> es el alias de la conexión en mayúsculas, con cada carácter que no sea una letra o un dígito escrito como guion bajo.

    Un nodo LanguageModelComponent o EmbeddingModel se ejecuta en uno de varios proveedores de modelos — el que nombra su campo provider o, donde este está vacío, el proveedor del modelo que selecciona su campo model — y entrega su clave a ese proveedor. La plataforma entrega la conexión de modelo para un cliente compatible con OpenAI, así que un nodo de este tipo se escribe con las variables solo donde se ejecuta en OpenAI. Uno que se ejecuta en otro proveedor nunca se enlaza, como se describe arriba; uno que no selecciona ninguno, que nombra su proveedor mediante una variable global o que toma su modelo de otro nodo se escribe sin ninguna de ellas, de modo que el borrador nunca dirige a otro proveedor hacia la clave de la conexión. Donde ningún campo de un nodo de este tipo da la dirección de su API — un nodo LanguageModelComponent no contiene ninguna para OpenAI, y el campo api_base de un nodo EmbeddingModel puede faltar, o estar vacío donde no puede nombrar una variable — el cliente de OpenAI en el que se ejecuta toma OPENAI_BASE_URL del entorno, así que el nodo llega igualmente a la dirección que entrega la plataforma.

    El cliente de un nodo OpenAIEmbeddings envía sus default_headers por encima de los que construye a partir de la clave, y fusiona su default_query por encima de la consulta de la dirección a la que llama, así que, en un nodo de este tipo que el borrador conecta, el valor completo de cada uno se escribe vacío conservando su tipo, como se escriben los headers de un nodo MCP Tools.

    Un campo que la exportación escribe sin esos dos miembros no se vuelve a escribir — un campo de credencial entre ellos se traslada tal como está escrito, o se escribe vacío donde el ajuste lo pide, como se indica más abajo. Donde ese campo es el que lleva la dirección de la parte — y, para un nodo LanguageModelComponent o EmbeddingModel, da una —, donde un nodo de este tipo no se ejecuta en OpenAI, o donde el nodo es de cualquier otro tipo, la importación informa de la parte como alcanzada en la dirección que dan el flujo o los valores predeterminados de su componente.

  • Un nodo OpenAI de Flowise. El cliente de OpenAI en el que Flowise ejecuta un nodo chatOpenAI u openAIEmbeddings lee OPENAI_BASE_URL y OPENAI_API_KEY del entorno donde el Base Path del nodo está vacío y no selecciona ninguna credencial, así que el borrador escribe vacío un Base Path que contiene la exportación, y vacía también la credencial que selecciona el nodo, en data.credential. Ese cliente envía los encabezados predeterminados del nodo, sus baseOptions, por encima del encabezado que construye a partir de la clave, así que el borrador escribe vacío su valor completo conservando su tipo. De un nodo de modelo de cualquier otro tipo se informa como alcanzado en la dirección que dan el chatflow o sus propios valores predeterminados.

  • Una herramienta o un almacén vectorial de Flowise. Un chatflow lee la dirección que la plataforma entrega para uno de ellos — AGGREGA_TOOL_<ALIAS>_URL o AGGREGA_VECTOR_STORE_<ALIAS>_URL — solo mediante una variable Runtime de ese nombre, que nada crea al arrancar. El borrador no escribe nada para ella, y la importación informa del paso que hace que el chatflow la lea: crear la variable Runtime en la página Variables de Flowise y leerla en el nodo como $vars.<name>.

  • Cualquier nodo de n8n. La plataforma entrega una conexión de modelo como OPENAI_BASE_URL y OPENAI_API_KEY, y una conexión tools o de almacén vectorial como AGGREGA_TOOL_<ALIAS>_URL o AGGREGA_VECTOR_STORE_<ALIAS>_URL, mientras que un nodo de n8n llega a un modelo, un almacén o un servicio en la dirección que da la credencial almacenada que selecciona, o en la dirección que contienen sus propios parámetros, y un workflow lee una variable de entorno solo mediante una expresión que lee $env, que la plataforma rechaza a menos que el Aggregate establezca values.allow_env_access_in_nodes en true. El borrador deja ese valor en su valor predeterminado, false, ya que establecerlo permite a cada workflow, y a cada usuario que puede editar uno, leer cada variable del entorno de la plataforma, incluidas las credenciales entregadas. Así que el borrador no escribe nada en el workflow para una conexión, y de cada parte conectada se informa como alcanzada de otro modo que a través de ella. Un nodo cliente MCP llega a su servidor en la dirección que contiene el workflow — tal como la escribió la exportación, o ninguna donde el ajuste empty_credentials la escribe vacía, como se indica más abajo — y la dirección propia del servidor — infra.endpoint de la parte — se deja para la Release.

Donde se lleva el flujo, de cada parte conectada se informa indicando cuál de estos casos se cumple: part-reads-connection donde el flujo llega a la parte a través de su conexión, y part-address-in-flow donde llega a la parte de otro modo que a través de su conexión — en una dirección que contiene el flujo, o en una que dan los valores predeterminados de su componente. La decisión de la parte dice lo mismo.

Un nodo que el borrador no conecta a ningún socket puede aun así ser alcanzado por una conexión que el borrador sí conecta, tal como está escrito el nodo: un cliente de OpenAI sin dirección ni clave propias lee de su entorno las OPENAI_BASE_URL y OPENAI_API_KEY que la plataforma entrega para la conexión de modelo. Donde así ocurre, el borrador escribe el nodo como escribiría uno conectado, de modo que nada de lo que contiene se envía en lugar de lo que suministra la conexión, e informa de él con part-reads-connection:

  • un nodo OpenAIEmbeddings de Langflow cuyo campo de dirección nombra la variable OPENAI_BASE_URL que entrega la plataforma, leída como variable global, mientras una parte está conectada al socket de modelo: sus default_headers y default_query;
  • un nodo chatOpenAI u openAIEmbeddings de Flowise cuyo Base Path está vacío y que no selecciona ninguna credencial, y la configuración de un modelo así que un nodo de agentflow guarda entre sus entradas, mientras una parte está conectada al socket de modelo: sus baseOptions.

En cualquier otro nodo estos valores no son cableado: se trasladan tal como están escritos, o se escriben vacíos donde el ajuste lo pide, como dice la sección siguiente.

Valores de credenciales que contiene el flujo

Antes de que se lleve el flujo, la importación localiza cada valor en él que puede llevar una credencial, en los lugares enumerados más abajo, cada uno de uno de tres tipos: lo que un formato marca como credencial; un miembro de la configuración de un servidor MCP, dondequiera que un formato guarde una; y una entrada que un formato marca como no credencial pero que aun así puede llevar una — encabezados de solicitud, parámetros de consulta, una solicitud completa escrita como línea de comandos, una entrada que contiene una credencial bajo el nombre de una credencial.

De forma predeterminada, la importación no escribe vacío ninguno de ellos: el flujo se lleva tal como se exportó, y cada valor localizado que contiene algo — ni una cadena vacía ni null — se nombra en una advertencia credential-carried, por su nodo y su campo — un encabezado o un parámetro de consulta por su nombre —, nunca por su valor ni por ninguna parte de él, junto con el valor del ajuste empty_credentials que lo escribe vacío. El ajuste activa la eliminación: marked escribe vacío lo que un formato marca como credencial y cada miembro de la configuración de un servidor MCP; all escribe vacías también las entradas marcadas como no credenciales. De cada valor que escribe vacío se informa con credential-emptied, por su nodo y su campo, nunca por su valor; un valor ya vacío, o null, se deja como está y no se informa de él. Un valor que el ajuste no admite detiene la importación, que no genera nada como borrador, en lugar de leerse como none.

Un valor localizado que es una referencia a una variable y nada más no contiene ningún valor propio: el nombre a secas de una variable, ${NAME} — incluida una variable predefinida como ${workspaceFolder} o ${userHome} — o una de las formas que definen los clientes MCP, ${env:NAME} y ${input:id}. Diga lo que diga el ajuste, se traslada tal como está escrito y no se nombra en ninguna advertencia, sea cual sea el formato del flujo, igual que escribe uno el importador MCP. Lo mismo ocurre con un miembro que es una sola referencia dentro de un valor que un formato guarda como texto, como un mcpServerConfig de Flowise escrito como texto JSON, o encabezados y parámetros de consulta guardados como objeto JSON en texto en Flowise y n8n: escrito vacío, el texto conserva ese miembro tal como está escrito.

Una referencia que lleva texto después de un operador contiene ese texto, que puede ser una clave, vaya o no precedido el operador de dos puntos: un valor predeterminado, ${NAME:-value} o ${NAME-value}; una alternativa, ${NAME:+value} o ${NAME+value}; un mensaje, ${NAME:?message} o ${NAME?message}; una asignación, ${NAME:=value} o ${NAME=value}. Se localiza como cualquier otro valor — trasladado y nombrado en una advertencia credential-carried de forma predeterminada, escrito vacío donde el ajuste lo pide para su tipo —, y lo mismo ocurre con cualquier otro texto dentro de ${…}, como ${config:name}, y con el texto junto a una referencia, como --key=${NAME}.

Lo que el borrador escribe para que un nodo llegue a su conexión — una dirección escrita vacía, el nombre de una variable, una credencial seleccionada o encabezados predeterminados escritos vacíos, como describe Cómo llega el flujo llevado a cada parte — es cableado: se escribe diga lo que diga el ajuste, se informa de ello indicando cómo llega el nodo a su conexión, y nunca se informa de ello como valor de credencial. Lo que queda fuera de todos los lugares de más abajo corresponde al autor revisarlo, como dice el final de esta sección.

Lo que un formato marca como credencial — escrito vacío con marked y all:

  • Langflow — el valor de cada campo de la plantilla marcado con password: true, incluido un campo que contiene el nombre de una variable global, a menos que el borrador escriba ese campo con el nombre de la variable que entrega la plataforma, como se indica más arriba.
  • Flowise — la credencial que un nodo guarda en data.credential, que selecciona su parámetro de credencial; el valor de cada entrada que sus inputParams declaran de tipo password; y FLOWISE_CREDENTIAL_ID entre las entradas de un nodo, y credential o FLOWISE_CREDENTIAL_ID dentro de un objeto de configuración a cualquier profundidad de ellas, como un agentflow guarda la de un modelo o una herramienta.
  • n8n — el id de cada credencial almacenada que selecciona un nodo, en credentials.<type>.id. Una exportación de n8n guarda una credencial como referencia, nunca su valor, y el name de la referencia no se localiza: n8n, al importar el workflow en otra instancia, resuelve una credencial cuyo id no tiene por su tipo y su nombre. Una credencial que una exportación más antigua selecciona solo por su nombre nombra una credencial y no contiene ninguna, y no se localiza. Y el valor de cada parámetro que n8n marca como contraseña en las definiciones de sus nodos base — el secret del nodo Crypto, por ejemplo, o el password de los nodos que crean un usuario —, dondequiera que esté entre los parámetros del nodo, leyéndose un nodo usado como herramienta de un agente como el nodo que es.

La configuración de un servidor MCP — escrita vacía con marked y all:

  • La configuración mcp_server de un nodo MCP Tools de Langflow, y el mcpServerConfig de un nodo de Flowise, escritos como texto JSON o como objeto: cada valor de encabezado, ya sean los encabezados un objeto, filas de una clave y un valor u objetos fusionados enteros, localizándose entero un elemento de cualquier otro tipo; cada valor de entorno; la dirección del servidor; el comando; y cada argumento. Ninguno de los dos formatos marca una dirección, un comando o un argumento como credencial, y cada uno puede llevar una clave — una dirección en su parte de usuario, su ruta o su consulta —, así que los tres se localizan también, en ambos formatos. Escritos vacíos, el comando y cada argumento conservan sus miembros, de modo que una configuración que inicia un servidor propio se sigue leyendo como tal. Donde un nodo MCP Tools de Langflow está conectado a una conexión tools, su dirección es cableado, como se indica más arriba, y nunca se informa de ella como valor de credencial. Una configuración de Flowise escrita como texto que no se lee como objeto JSON se localiza entera, ya que nada en su interior puede localizarse.
  • Un nodo MCP Tools de Langflow que no lleva ningún campo mcp_server guarda en cambio su servidor en campos propios — la dirección en sse_url, los encabezados en headers_input, el entorno en env y la línea de comandos completa, incluidos sus argumentos, en command — y Langflow tampoco marca ninguno de ellos como credencial, así que cada valor de encabezado, cada entrada de env, la dirección y la línea de comandos se localizan, conservándose sus campos y entradas cuando se escriben vacíos. Donde env es una lista, de cada entrada se informa por su posición, ya que el nombre de una variable y su valor comparten un mismo texto. Un nodo así no nombra ningún servidor MCP, así que nunca se conecta a una conexión tools.
  • El campo headers propio de un nodo MCP Tools de Langflow, que Langflow envía al servidor por encima de los encabezados de su configuración, en un nodo que el borrador no conecta: su valor completo, escrito vacío conservando su tipo, como en un nodo conectado, y del que se informa una sola vez, como headers.
  • Los componentes MCP Tools (SSE) y MCP Tools (stdio) de Langflow, que Langflow marca como obsoletos, guardan su servidor en un solo campo cada uno — un nodo MCPSse su dirección en url, un nodo MCPStdio su línea de comandos completa, incluidos sus argumentos, en command — localizado entero. Ninguno de los dos nombra un servidor MCP, así que ninguno de los dos se conecta a una conexión tools.
  • Un nodo cliente MCP de n8n — la MCP Client Tool a la que llama un agente, el nodo MCP Client, o un cliente de un servidor que enumera el registro de n8n — guarda la dirección del servidor en su parámetro endpointUrl, o sseEndpoint en su primera versión, y sus encabezados solo como credenciales que selecciona; la dirección se localiza entera, esté conectado o no.

Una entrada que un formato marca como no credencial — escrita vacía solo con all:

  • Encabezados de solicitud — en Langflow, los headers de un nodo APIRequest, URLComponent, CloudflareWorkersAIEmbeddings o ConfluentKafkaProducer y los api_headers de un nodo DoclingRemote; en Flowise, los headers de un nodo httpAgentflow, getApiChain, postApiChain, openApiChain, apiLoader, openAPIToolkit o searXNG, los requestsGetHeaders, requestsPostHeaders, requestsPutHeaders y requestsDeleteHeaders de las herramientas Requests, y los baseOptions — los encabezados predeterminados que envía el cliente de un modelo — de un nodo azureChatOpenAI, azureOpenAIEmbeddings, chatCerebras, chatOpenAICustom, openAIEmbeddingsCustom, chatOpenRouter, chatSambanova u openAI; en n8n, los headerParameters, jsonHeaders, headerParametersUi y headerParametersJson de un nodo n8n-nodes-base.httpRequest — su versión actual guarda los dos primeros, sus versiones anteriores los otros dos — y del mismo nodo usado como herramienta de un agente, los parametersHeaders y jsonHeaders de un nodo @n8n/n8n-nodes-langchain.toolHttpRequest, y los headerParametersUi de un nodo n8n-nodes-base.graphql. El nombre de un encabezado no lleva ningún secreto, así que se localiza el valor de cada encabezado y se conserva su nombre, sea cual sea la forma que adopten los encabezados: un objeto de nombres a valores, filas de una clave y un valor — en n8n, filas de un name y un value — u objetos que Langflow fusiona enteros en los encabezados. De cada encabezado se informa por su nombre. Un elemento de una lista que no es una fila de encabezado se localiza entero y se informa de él por su posición. Los encabezados escritos como texto se localizan enteros, salvo en Flowise y n8n, donde el texto contiene los encabezados como objeto JSON: ahí, escrito vacío, el texto se reescribe en su sitio, con cada valor vacío, y se informa de él una sola vez con los nombres de los encabezados que contiene. Un texto de n8n que empieza por = es una expresión que n8n evalúa cuando se ejecuta el workflow, y se localiza entero. Escritos vacíos, lo están todos los valores, incluidos los de los encabezados que no contienen ningún secreto, como User-Agent, así que una solicitud importada se envía con ellos vacíos hasta que su autor los restaura.
  • Parámetros de consulta — en Langflow, los query_params de un nodo APIRequest o GoogleSerperAPI y los search_params de un nodo SerpAPI, Serp, SearchAPI o SearchComponent; en Flowise, los queryParams de un nodo httpAgentflow y los customParameters de un loader searchApi; en n8n, los queryParameters, jsonQuery, queryParametersUi y queryParametersJson de un nodo n8n-nodes-base.httpRequest, usado como herramienta o no, los parametersQuery y jsonQuery de un nodo @n8n/n8n-nodes-langchain.toolHttpRequest, y los queryParameters y queryParametersJson que un nodo n8n-nodes-base.facebookGraphApi guarda entre sus options. Cada uno se envía como la consulta de una solicitud, y un parámetro de consulta puede llevar una clave — algunas API de búsqueda toman la suya como api_key en la consulta —, así que cada uno se localiza como los encabezados: cada valor, conservando su nombre, sea cual sea la forma que adopten los parámetros, y de cada uno se informa por su nombre; los parámetros escritos como texto se localizan enteros, salvo en Flowise y n8n, donde el texto los contiene como objeto JSON, que, escrito vacío, se reescribe en su sitio y del que se informa una sola vez con los nombres que contiene. Escritos vacíos, lo están todos los valores, incluidos los de los parámetros que no contienen ningún secreto, así que una solicitud importada se envía con ellos vacíos — o, desde un nodo HTTP de Flowise, que no envía ningún parámetro cuyo valor esté vacío, sin ellos — hasta que su autor los restaura.
  • Encabezados predeterminados y una consulta predeterminada en un nodo OpenAI al que no llega ninguna conexión — los default_headers y default_query de un nodo OpenAIEmbeddings de Langflow, y los baseOptions de un nodo chatOpenAI u openAIEmbeddings de Flowise, dondequiera que esté el nodo, incluida la configuración del modelo que selecciona un agentflow, donde el borrador ni conecta el nodo ni encuentra una conexión que llegue a él tal como está escrito; donde sí lo hace, son cableado, como se indica más arriba. Cada uno se localiza entero y, escrito vacío, conserva su tipo — un objeto como {}, una lista como [], el texto como una cadena vacía — y se informa de él una sola vez.
  • Una solicitud completa escrita como línea de comandos — el curl_input de un nodo APIRequest de Langflow y el curl de un nodo Webhook, localizados enteros, incluido el valor predeterminado del Webhook. Ninguno de los dos se lee cuando se ejecuta el flujo: el primero solo rellena los campos del nodo en el editor, el segundo muestra un ejemplo.
  • Una entrada que contiene una credencial bajo el nombre de una credencial — la api_key de un nodo OlivyaComponent de Langflow, el verification_token de cada componente de Composio y el mem0_config de un nodo mem0_chat_memory, cuyo valor completo conserva su tipo cuando se escribe vacío; y el webhookSecret y el callbackSecret de un nodo startAgentflow de Flowise y el bearerToken de un nodo teradataMCP. Cada uno se localiza entero. Una entrada cuyo nombre solo se parece al de una credencial — el nombre de una clave almacenada en otro lugar, un nombre de usuario o una opción que el componente declara como no secreta — no se localiza.

Aparte de los valores que el ajuste escribe vacíos, lo que el borrador escribe para que el flujo llegue a sus partes, los handles de una arista de Langflow, escritos como los escribe el editor de Langflow, y los retornos de carro escritos como saltos de línea que se describen más abajo, el flujo se lleva tal como se exportó: sin nada de esto, byte a byte.

Una conexión en el borrador no lleva ningún valor de credencial: la Release borrador vincula por referencia la que presenta cada conexión, como describe Lo que el borrador deja para la Release.

Cada valor que el ajuste deja tal como está escrito llega al borrador, y el autor lo revisa, guiado por las advertencias credential-carried. Tampoco llega ninguna regla sobre un campo al resto de un flujo, así que el autor también lo revisa antes de compartir un borrador: el código propio de un componente, que el flujo lleva y en el que un componente personalizado puede contener una clave; las entradas que el editor añade a un nodo además de las que declara su componente; el cuerpo con el que se envía una solicitud, como el de un nodo APIRequest o httpAgentflow, que puede llevar un token; los argumentos que un nodo pasa al cliente de su modelo o a un loader como un objeto propio, como los model_kwargs de un nodo EmbeddingModel de Langflow o los additionalInputs de un nodo replicate de Flowise, que pueden llevar una clave bajo cualquier nombre; una dirección distinta de la de un servidor MCP, que puede llevar una clave en su parte de usuario o en su consulta; el código de un nodo Code de n8n, y los encabezados o la consulta de un nodo que envía una solicitud que el importador no enumera más arriba; y el texto libre, como un prompt o un mensaje.

Lo que el borrador deja para la Release

La Release borrador lleva, en la entrada de la plataforma y en la de cada parte, lo que el flujo no puede suministrar:

  • La imagen de la plataforma, como infra.image: la imagen que elige el propio importador, en la versión con la que se sabe que funcionan las Recipes del catálogo para la plataforma — langflowai/langflow:1.6.0, flowiseai/flowise:3.1.3 y n8nio/n8n:1.110.1 —, bajo un comentario que lo indica. La importación nunca la sube ni la baja para seguir a la fuente; donde la exportación indica una versión distinta de la plataforma, como hace el last_tested_version de un flujo de Langflow, el comentario la nombra.
  • El puerto en el que se publica la plataforma, como infra.published_port, solo con --target compose: 7860 para Langflow, 3000 para Flowise y 5678 para n8n, los puertos en los que sirve cada una, que su Recipe de Compose publica en la dirección de loopback del host, 127.0.0.1. El comentario que lo precede dice que el puerto solo es accesible desde esta máquina, por cualquier proceso que se ejecute en ella, y que eliminar la línea mantiene el servicio interno. Un segundo flujo de una misma importación toma el siguiente puerto que ninguno anterior toma. Con cualquier otro destino, o sin ninguno, no se escribe.
  • El secreto propio de la plataforma y la credencial de cada conexión a un modelo, vinculados por referencia y nunca como valor: en Langflow, la ranura admin_password, leída mientras values.require_authentication siga siendo true; en Flowise, la ranura owner_password, obligatoria mientras values.flow_definition esté establecido; y, donde una parte está conectada al socket model de la plataforma, la credential de esa conexión. La plataforma n8n no toma ningún secreto propio. Cómo se vincula cada uno depende del destino, como describe Secretos, para cada destino.
  • Cada valor que ninguna fuente contiene, escrito como cadena vacía bajo un comentario que dice qué es: en Flowise, infra.owner_email, el correo electrónico de la cuenta del propietario, obligatorio mientras values.flow_definition esté establecido; y la dirección de cada servidor MCP conectado a la plataforma, infra.endpoint de su parte. Cada uno es un valor que la importación debe, que se responde como describe El archivo de respuestas de la importación.

La credencial que presenta una conexión a una herramienta o a un almacén vectorial no se genera en el borrador: la credencial de una conexión así detiene la compilación donde la herramienta no publica ninguna cabecera en la que enviarla, así que un comentario sobre la entrada de la plataforma la nombra, para que la vincules donde la herramienta acepte una.

Secretos, para cada destino

En --target helm, cada secreto es un core/referenced-secret cuyo origin es el nombre de un Secret de Kubernetes que ya está en el namespace y que contiene el valor bajo la clave de datos value. Ese nombre no le corresponde darlo a ningún origen, así que se escribe vacío bajo un comentario que dice qué contiene, y queda entre los valores que la importación debe; el Manifest generado como borrador mapea core/referenced-secret a helm/k8s-existing-secret.

En cualquier otro destino, y sin destino, cada secreto es un core/secret-value cuyo origin es una referencia a una variable — ${LANGFLOW_ADMIN_PASSWORD}, ${FLOWISE_OWNER_PASSWORD} y ${OPENAI_API_KEY} para la credencial de una conexión a un modelo — que un destino que sustituye referencias a variables, como hace Docker Compose al iniciarse la pila, lee del entorno, así que ningún archivo contiene el valor y no se debe nada por él. El chatflow de Flowise de más arriba, importado sin destino, se genera como borrador con esta Release:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/multiple-documents-qna
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the flowise format.
spec:
aggregate: imported/multiple-documents-qna
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
flowise:
infra:
# The image running core/ai-agent/flowise, at the version this importer drafts, which the catalog's Recipes for it are known to run; the import does not raise or lower it to follow the source.
image: "flowiseai/flowise:3.1.3"
# Left for the Release, since the source cannot supply it: infra.owner_email, the email address of the platform's owner account, required while values.flow_definition is set
owner_email: ""
features:
owner_password:
type: core/secret-value
infra:
# Attached by reference, never as a value: the owner account's password, required while values.flow_definition is set, read from the variable FLOWISE_OWNER_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${FLOWISE_OWNER_PASSWORD}"
uses:
model:
chatopenai-0:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential flowise presents to chatopenai-0 on its model connection, read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
chatopenai-0: {}

Sin destino debe dos valores, spec.manifest e infra.owner_email; con --target compose, solo el correo electrónico del propietario; con --target helm, el correo electrónico del propietario y los nombres de los dos Secrets de Kubernetes.

En el destino compose, un secreto que vincula la Release por sí sola llega bajo una única clave, value, así que la contraseña del propietario o del administrador y la credencial de una conexión llegarían ambas bajo ella. Por eso el Aggregate declara cada una con una clave propia donde la plataforma admite una conexión: owner_password con la clave OWNER_PASSWORD en Flowise, admin_password con la clave LANGFLOW_SUPERUSER_PASSWORD en Langflow, y la credential de la conexión al modelo con la clave OPENAI_API_KEY en las tres plataformas, cada una bajo un comentario que explica por qué. Con --target compose estas líneas se escriben activas; sin destino se escriben comentadas, como en el ejemplo de más arriba, para que les quites el comentario si compilas para compose; con cualquier otro destino no se escriben. La Release vincula el origen de cada ranura, nombrando el mismo tipo o ninguno.

Con el ajuste attach_egress_allowlist en true, la instancia de la plataforma declara además la Feature core/egress-allowlist de la biblioteca estándar bajo features, como egress-allowlist, de modo que la plataforma se conecta solo a los componentes a los que llegan sus conexiones, a sus propios pods y al DNS del clúster — la contrapartida de salida de una arista uses como llamada declarada. El Aggregate declara el tipo de la vinculación y nada más, ya que la vinculación de un Aggregate no lleva ningún infra, y la Release generada como borrador no escribe nada de ello: el comentario sobre la entrada de la plataforma nombra, bajo features.egress-allowlist.infra, control_plane_present, que el operador establece en true para afirmar que el plugin de red del clúster aplica la política de red, sin lo cual la compilación se detiene; admitted_destinations, una lista que contiene, para cada conexión cuyo destino no ejecuta el clúster, como un modelo alojado, una entrada que nombra el destino y un rango de direcciones, sin la cual la compilación se detiene nombrando esa conexión; y aggrega.ai/namespace para el límite que contiene la plataforma, ya que la política se coloca en el namespace de sus cargas de trabajo y la compilación se detiene donde estas no se emiten en ninguno. Ninguna de estas claves se escribe vacía, así que ninguna está entre los valores que la importación debe. La decisión de cada parte conectada dice que la vinculación admite su conexión, y la importación informa de la vinculación como feature-attached. Compose no tiene política de red, así que una compilación de compose de un borrador así se detiene nombrando la vinculación; donde la plataforma admite una conexión, las líneas de compose de más arriba se escriben dentro del bloque features de la instancia, sin una segunda clave features.

El modelo que sirve una parte

Una parte a la que el borrador hace referencia y cuyo Component declara un valor llamado model — como hace, y exige, cada Component de modelo de la biblioteca estándar — se escribe con el nombre del modelo que selecciona su nodo, como values.model:

  • Langflow — el model_name de un nodo OpenAIModel o AnthropicModel; el model de un nodo OpenAIEmbeddings; y la sobrescritura model_name de un nodo LanguageModelComponent o EmbeddingModel donde está establecida, y en caso contrario el modelo que selecciona su campo model.
  • Flowise — el modelName de un nodo chatOpenAI, chatAnthropic u openAIEmbeddings.
  • n8n — el parámetro model de un nodo de chat, de completion o de embeddings que mapea la tabla del importador, o su modelName en los nodos Google Gemini y Vertex, escrito como un nombre o como el valor del selector en el que lo guardan los nodos más recientes de n8n. n8n deja fuera de una exportación un parámetro establecido en su valor predeterminado, así que un nodo que mantiene el modelo predeterminado no nombra ninguno en la exportación.

Una Release no puede escribir un valor. Así que, donde el nodo no nombra ningún modelo que el borrador pueda escribir — no selecciona ninguno, lo nombra mediante una variable global o una expresión que solo se lee cuando se ejecuta el flujo, lo toma de otro nodo conectado a él, o es de un tipo cuyo campo de modelo el importador no lee —, un comentario dentro de la parte deja values.model para el autor, y la importación informa de ello con model-not-named. Una parte que el borrador genera como borrador se escribe sin ningún valor.

Cómo se escribe el flujo en el borrador

El flujo se escribe como un bloque literal de YAML cuyo chomping conserva sus saltos de línea finales, de modo que values.flow_definition se vuelve a leer como el propio texto del flujo. El texto de un Aggregate se lee como una plantilla, así que cada {{ que contiene el flujo — un chatflow de Flowise escribe {{<node id>.data.instance}} para cada conexión entre dos nodos — se escribe como {{"{{"}}, que la interpolación vuelve a convertir en las dos llaves, como describe Texto que contiene sus propias llaves dobles. El nombre de un modelo se escribe de la misma manera.

Un bloque literal no puede llevar todos los caracteres tal como están escritos:

  • Un retorno de carro — de un par CR LF, o aislado — se escribe como un solo salto de línea. Un documento JSON solo contiene uno entre sus tokens, donde cualquier espacio en blanco se lee igual, así que la plataforma lee el mismo flujo. La importación informa de cuántos hay con carriage-returns-rewritten.
  • Cualquier otro carácter que un bloque literal no pueda llevar impide que se lleve el flujo: un carácter de salto de línea — U+0085, U+2028 o U+2029; un carácter de control distinto del tabulador y del salto de línea — de U+0000 a U+001F, U+007F, y de U+0080 a U+009F; los no caracteres U+FFFE y U+FFFF; y un byte que no forma parte de una secuencia UTF-8. values.flow_definition se deja entonces sin establecer, con un comentario que lo indica, el resto se genera como borrador, y la importación informa de definition-not-carried para cada tipo de carácter, con cuántos contiene el flujo y la línea y la columna del primero.

El flujo tampoco se lleva donde un valor que el borrador escribe vacío o de nuevo no está en los bytes de la exportación donde lo contiene su árbol analizado, y la importación informa de definition-not-carried nombrando el lugar de ese valor. El identificador del flujo es entonces el suyo propio donde el borrador puede llevarlo, y en caso contrario uno derivado de los identificadores de los nodos del flujo.

Nodo por nodo

Con layout: nodes, una importación genera como borrador cada nodo del flujo como un Component propio, y escribe:

  • aggregate.yaml — un Aggregate de borrador nombrado según el flujo, como describe Cómo se nombra un borrador, que compone los nodos del flujo: una entrada para cada uno, y cada arista del flujo como una conexión uses del nodo al que alimenta, con su socket y su alias nombrados ambos según la clave del nodo que la alimenta, de modo que un nodo alimentado por varios da a cada conexión un alias propio.
  • un archivo bajo components/ por cada nodo que genera como borrador — un Component de borrador llamado <target_namespace>/<category>/<name>, con el nombre tomado del tipo del nodo, en la versión 0.1.0, con sus campos de valor como campos de cadena de un objeto values cerrado y sus campos de credencial como ranuras de credencial obligatorias cuya entrega decide una Recipe.
  • release.yaml — una Release en borrador con el mismo nombre, que nombra ese Aggregate, con una entrada para cada nodo.

El propio flujo no se lleva, y no se lee el valor de ningún campo.

Llevar el propio flujo exportado

El borrador predeterminado lleva el flujo: la instancia de la plataforma toma la exportación como values.flow_definition, escrita como describe Cómo se escribe el flujo en el borrador. Un autor que escribe un flujo a mano en un Aggregate — en un borrador dispuesto nodo por nodo, o en un Aggregate propio — lo escribe de la misma manera. Un Component que ejecuta un flujo tal como se creó toma la exportación como un valor — flow_definition en core/ai-agent/langflow y core/ai-agent/flowise de la biblioteca estándar — y el texto de un Aggregate se lee como una plantilla, así que las llaves dobles que contiene la exportación se leerían como acciones de plantilla: un chatflow de Flowise escribe {{<node id>.data.instance}} para cada conexión entre dos nodos, un prompt de Flowise nombra una variable como {{question}}, y una exportación de Langflow lleva el código fuente de sus componentes, donde las llaves también pueden aparecer. Escribe cada {{ de la exportación como {{"{{"}}, dentro de un escalar de bloque, y la interpolación restaura el texto de la exportación antes de que lo lean las Recipes del Component; Texto que contiene sus propias llaves dobles describe por qué. Un valor de credencial que contiene la exportación corresponde a un secreto que vincula la Release, no al Aggregate: escríbelo vacío, como hace el borrador donde el ajuste empty_credentials se lo pide.

# Aggregate fragment — a Flowise chatflow carried as exported
spec:
components:
chat:
type: core/ai-agent/flowise
values:
chatflow_id: 3f2b8c1e-7a4d-4e9b-8c2f-1a6d5e9b0c47
flow_definition: |
{
"nodes": [
{
"id": "llmChain_0",
"data": {
"name": "llmChain",
"inputs": {
"model": "{{"{{"}}chatOpenAI_0.data.instance}}",
"prompt": "{{"{{"}}promptTemplate_0.data.instance}}"
}
}
}
],
"edges": []
}

El importador MCP

importer/mcp lee los servidores MCP que enumera la configuración de un cliente MCP, o el único servidor que describe una descripción de servidor del registro MCP, y genera como borrador cada servidor como una instancia de la herramienta MCP de la biblioteca estándar, core/ai-tool/mcp. Todo servidor es una de ellas, así que el importador no puntúa ningún candidato y no informa de ninguna decisión de mapeo.

Qué lee

  • La configuración de un cliente. El .mcp.json de Claude Code, el claude_desktop_config.json de Claude Desktop y el .cursor/mcp.json de Cursor enumeran sus servidores por nombre bajo mcpServers; el .vscode/mcp.json de Visual Studio Code los enumera bajo servers, y un archivo que enumera servidores bajo ambos se lee primero bajo mcpServers. Un servidor cuyo type es stdio, o que no nombra ningún type y lleva un command, se inicia desde una línea de comandos — su command y sus args — con su env como entorno. Un servidor cuyo type es http, streamable-http o sse, o que no nombra ni type ni command y lleva una url, se alcanza en su url y recibe sus headers.
  • Una descripción de servidor del registro. El server.json que publica el registro MCP: su name, y su primer paquete o, donde no enumera ninguno, su primer remoto. Un paquete de npm o de PyPI se inicia desde la línea de comandos que forman su lanzador — su runtimeHint, o npx para npm y uvx para PyPI —, sus runtimeArguments, el paquete con su versión, escrito <identifier>@<version> para npm y <identifier>==<version> para PyPI, y sus packageArguments, con sus environmentVariables como entorno. Un argumento posicional es su value, o su default; un argumento con nombre se escribe <name>=<value> donde tiene uno de los dos, y como su name donde no tiene ninguno. Un paquete OCI se ejecuta a partir de la imagen que nombra su identifier. Un remoto se alcanza en su url y recibe sus headers. Cada otro paquete y remoto que enumera la descripción se nombra en un comentario, ya que una instancia ejecuta solo uno de ellos.

Cualquier otro miembro de un servidor — cwd, envFile, el auth de Cursor, o un miembro que su tipo de servidor no lee, como la url de un servidor iniciado desde una línea de comandos — no se escribe en ningún sitio, y se nombra en un comentario encima de la entrada del servidor en la Release, ya que ninguna clave de infraestructura de core/ai-tool/mcp lo acepta. Los inputs de una configuración, que describen lo que Visual Studio Code pide al usuario y no contienen ningún valor, no se leen. Los servidores, su entorno y sus encabezados conservan el orden en que el origen los escribe, salvo en una configuración leída como JSON con comentarios, que conserva el orden en que los escribe su árbol analizado: el orden de los nombres (véase Una configuración que contiene comentarios).

Un directorio se lee a través de las configuraciones de cliente que contiene — cada archivo con el nombre de una de las cuatro, a cualquier profundidad — en el orden de sus rutas, y cada servidor de cada archivo se genera como borrador en un único Aggregate.

En qué se convierte un servidor

aggregate.yaml es un Aggregate de borrador que lleva el nombre del origen, como describe Cómo se nombra un borrador, y que contiene una instancia de core/ai-tool/mcp por servidor. Una instancia tiene como clave el nombre de su servidor, en minúsculas, con cada secuencia de caracteres que no sean letras ni dígitos escrita como un solo guion, y un sufijo numérico donde un servidor anterior tomó la clave. Donde la clave no es el nombre del servidor tal como está escrito, o la importación leyó varios archivos, un comentario encima de la instancia nombra el servidor y el archivo del que procede. No se genera como borrador ningún agente que los use.

Junto a él, release.yaml es una Release de borrador con el mismo nombre, cuyo spec.aggregate nombra el Aggregate, que lleva para cada instancia las entradas operativas que indica el origen:

  • para un servidor iniciado desde una línea de comandos, infra.stdio_command, su comando y después cada argumento, un elemento cada uno; e infra.stdio_runtime, el ecosistema del lanzador, npm donde el comando es npx, npm o node, pypi donde es uvx, uv, python o python3 y, para un paquete del registro, su registro, npm o pypi;
  • para un servidor alcanzado en una dirección, infra.endpoint: la dirección sin su parte de usuario, su consulta y su fragmento, ya que el Component acepta la dirección sin ninguna parte que lleve una clave; cada parte que omite se escribe en el comentario encima de la entrada, junto a la dirección, como describe Valores de credenciales que contiene un servidor;
  • para un paquete OCI, infra.image;
  • para ningún servidor, en ningún destino, infra.published_port: el borrador nunca publica un servidor en el host;
  • para el entorno de un servidor, la ranura server_env, vinculada por referencia según el destino de la importación. En --target helm es un core/referenced-secret que nombra un Secret de Kubernetes que ya está en el namespace y que contiene una clave de datos por variable, cada una con el nombre de la variable que contiene; el nombre del Secret se escribe vacío, bajo un comentario que nombra las claves de datos, y queda entre los valores que la importación debe. En cualquier otro destino, y sin destino, es un core/referenced-secret-set con una entrada bajo infra.entries por variable, cuya clave es el nombre de la variable y cuyo valor es el que escribe el origen, así que una referencia a una variable como ${GITHUB_TOKEN} sigue siendo una referencia, que un destino que sustituye referencias a variables lee del entorno.

Lo que el origen no indica se escribe vacío, bajo un comentario que dice qué es: un comando cuyo lanzador no está en ninguna de las dos imágenes puente deja infra.stdio_runtime vacío, y queda entre los valores que la importación debe; un argumento que una descripción del registro deja a su usuario se escribe como un elemento vacío, y una variable cuyo valor no escribe el origen, como una entrada con un valor vacío, cada uno nombrado en el comentario encima de la entrada.

Como toda Release generada como borrador, escribe metadata.environment como development, bajo un comentario que dice que es un valor predeterminado del borrador que hay que cambiar, y, sin destino, spec.manifest como una cadena vacía que la importación debe. Dado un destino, el importador genera el propio Manifest como borrador, ya que el catálogo realiza core/ai-tool/mcp mediante varias Recipes y solo el importador sabe cómo se ejecuta cada servidor: mapea cada servidor por su clave, bajo mappings.components.name, a la realización del destino para la forma en que se ejecuta el servidor — mcp-stdio-bridge para una línea de comandos, mcp-remote para una dirección, mcp para una imagen, como helm/mcp-stdio-bridge o compose/mcp-remote — y el tipo de secreto como el que se vincula el entorno a su realización, helm/k8s-existing-secret en helm y compose/dotenv-secret-set en compose. La importación completa ese Manifest y lo nombra en la Release, como describe Qué añade un destino.

Un .mcp.json de Claude Code que enumera un servidor alcanzado por HTTP y otro iniciado con npx:

{
"mcpServers": {
"api-server": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer ${API_KEY}" }
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
}
}
}

se genera como borrador así:

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/mcp
version: 0.1.0
description: Draft Aggregate imported from a source in the mcp format.
spec:
components:
api-server:
type: core/ai-tool/mcp
github:
type: core/ai-tool/mcp
release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/mcp
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the mcp format.
spec:
aggregate: imported/mcp
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# The headers the source sends this server, which no infrastructure key of core/ai-tool/mcp takes, since a remote server's credential is held by each consumer, on its connection to the tool:
# - Authorization: "Bearer ${API_KEY}"
api-server:
infra:
endpoint: "https://api.example.com/mcp"
github:
infra:
stdio_command:
- "npx"
- "-y"
- "@modelcontextprotocol/server-github"
stdio_runtime: npm
features:
server_env:
type: core/referenced-secret-set
infra:
# Attached by reference wherever the source names a variable: the environment github is started with, one entry per variable, each written as the source writes it, so a variable reference stays one, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, and an empty value is one still owed.
entries:
- key: "GITHUB_PERSONAL_ACCESS_TOKEN"
value: "${GITHUB_TOKEN}"

Importada con --target helm, la Release de la misma configuración vincula el entorno como el Secret que nombra, y el Manifest que el importador genera como borrador mapea cada servidor por su clave:

# release.yaml, the github entry's environment
features:
server_env:
type: core/referenced-secret
infra:
# Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding the environment github is started with, one data key per variable, each named as the variable it holds: GITHUB_PERSONAL_ACCESS_TOKEN.
origin: ""
manifest.yaml
apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/mcp
version: 0.1.0
spec:
mappings:
components:
type: {}
name:
api-server: helm/mcp-remote
github: helm/mcp-stdio-bridge
features:
type:
core/referenced-secret: helm/k8s-existing-secret

Valores de credenciales que contiene un servidor

Cada valor de la configuración de un servidor que escribe la Release — el valor de cada encabezado, cada elemento de su línea de comandos, su dirección, cada parte de la dirección que omite infra.endpoint y cada valor de entorno — puede llevar una clave, y ningún cliente marca ninguno como credencial, así que la importación localiza cada uno como miembro de la configuración de un servidor MCP; una entrada del registro marcada con isSecret se localiza como un valor que su formato marca como credencial. Una entrada del registro — una variable de entorno o el encabezado de un remoto — se lee como su value, o su default donde no escribe ninguno. De forma predeterminada, cada uno se traslada tal como está escrito a la Release y se nombra en una advertencia credential-carried por su servidor y su lugar — headers.<header>, infra.stdio_command.<position>, infra.endpoint o server_env.<variable>, y una parte de la dirección por la url en la que está escrita y el nombre de la parte, como en «url of node remote-search is carried with its query as written (la url del nodo remote-search se traslada con su consulta tal como está escrita)» — nunca por su valor. Con el ajuste empty_credentials en marked o all, cada uno se escribe vacío y se informa de él con credential-emptied: un elemento de la línea de comandos como un elemento vacío y un valor de entorno como un valor vacío, cada uno nombrado en el comentario encima de la entrada; una dirección como un infra.endpoint vacío, que la importación debe; y el valor de un encabezado o una parte de la dirección omitidos del comentario, que nombra solo el encabezado o la parte. El infra.stdio_runtime de un cliente se lee del comando tal como lo escribe la Release, así que un comando escrito vacío también lo deja vacío, y la importación lo debe. En --target helm la Release no escribe ningún valor de entorno: los contiene el Secret que nombra la ranura server_env.

Un valor que es una referencia a una variable y nada más — el nombre a secas ${NAME}, entre ellos una variable predefinida como ${workspaceFolder}, ${env:NAME} o ${input:id} — no contiene ningún valor propio: se escribe como el texto que es, diga lo que diga el ajuste, y no se nombra en ninguna advertencia, como ocurre con una referencia en un flujo. Una variable de entorno cuyo valor es una de ellas se escribe como el valor de la entrada, y la referencia sigue siendo una referencia, y un encabezado o una parte de la dirección cuyo valor es una de ellas se enumera con la referencia de la que lee. Una referencia que lleva texto después de un operador — un valor predeterminado, una alternativa, un mensaje o una asignación, como ${NAME:-value} o ${NAME-value}, con o sin dos puntos — contiene ese texto, y lo mismo ocurre con el texto junto a una referencia; cada uno se localiza como cualquier otro valor.

Ninguna clave de infraestructura de core/ai-tool/mcp acepta el valor de un encabezado: la credencial de un servidor remoto la tiene cada consumidor, en su conexión a la herramienta, y la importación no genera ningún consumidor como borrador. Así que el comentario encima de la entrada del servidor enumera cada encabezado que el origen le envía, junto a su valor tal como está escrito — una cadena entre comillas dobles que se vuelve a leer exactamente como el texto del origen — para que lo traslades a la conexión del consumidor que lo presenta. Un encabezado cuyo valor no escribe el origen, como una entrada de encabezado del registro sin valor ni valor predeterminado, se enumera como sin valor. La imagen que nombra un paquete OCI se escribe tal cual, y no es un valor al que llegue el ajuste.

infra.endpoint acepta la dirección sin ninguna parte que lleve una clave, así que las partes de la dirección que escribe el origen y que omite — la parte de usuario antes de la @, la consulta después del ? y el fragmento después del #, siendo el fragmento todo lo que sigue al primer # — se enumeran en el mismo comentario, cada una junto a su nombre y tal como está escrita, sin la @, el ? o el # que la separa. Un consumidor que lee su clave de la dirección proporciona la dirección completa en su propia conexión a la herramienta. Un servidor alcanzado en https://user:pw@api.example.com/mcp?key=k, sin ningún ajuste, se genera como borrador así:

# The address's user part and query are not written in infra.endpoint, which holds the address without any part that carries a key; a consumer reading its key from the address supplies the whole address on its own connection to the tool:
# - user part: "user:pw"
# - query: "key=k"
api:
infra:
endpoint: "https://api.example.com/mcp"

y con empty_credentials en marked, infra.endpoint se deja para la Release y el comentario enumera user part y query, cada uno con su valor omitido.

Una configuración que contiene comentarios

Visual Studio Code lee .vscode/mcp.json como JSON con comentarios, y también el importador MCP: su firma para ese archivo lo lee mediante el analizador que sirve parse:jsonc, así que una configuración que contiene comentarios // y /* */ y comas finales se reconoce sin que se nombre ningún formato, y el importador lee cada origen que enumera sus servidores bajo servers mediante ese analizador. Una configuración así se genera como borrador exactamente como la misma configuración sin sus comentarios ni sus comas finales. El analizador escribe los miembros de un objeto en el orden de los nombres, así que los servidores de una configuración así, su entorno y sus encabezados se generan como borrador en el orden de los nombres, contenga o no un comentario; una línea de comandos conserva su orden. Los demás clientes y el registro leen sus archivos como JSON, y también el importador: un .mcp.json, claude_desktop_config.json, .cursor/mcp.json o server.json que contiene un comentario no lo reconoce ninguna firma, e importado nombrando --format mcp se detiene con parse-failed y el motivo del analizador. Un comentario abierto con /* y nunca cerrado se deja tal como está escrito, y el analizador rechaza el archivo.

Los ajustes que lee

El importador MCP lee target_namespace y empty_credentials, tal como los describe Ajustes, y ningún otro ajuste.

El importador Compose

importer/compose lee los servicios y los modelos que declara un archivo Compose. Genera como borrador cada servicio como una instancia del Component del catálogo con el que coincide su imagen, o del servidor genérico de la biblioteca estándar, core/compute/server, que ejecuta su imagen; cada modelo como una instancia del entorno de ejecución Docker Model Runner de la biblioteca estándar, core/ai-model/docker-model-runner, donde tu catálogo lo contiene, y como un Component de modelo propio donde no lo contiene; y, junto a ellos, una Release que lleva lo que cada servicio indica para su funcionamiento.

Qué lee

  • Los archivos. Un archivo importado por sí solo se lee solo. Un directorio se lee como lo lee Compose: en cada directorio que contiene archivos Compose, en el orden de las rutas de los directorios, el primero presente de compose.yaml, compose.yml, docker-compose.yml y docker-compose.yaml es el archivo Compose, y el primero presente de compose.override.yml, compose.override.yaml, docker-compose.override.yml y docker-compose.override.yaml se fusiona sobre él. Ningún otro de esos archivos se lee. En un directorio que contiene archivos de sobrescritura y ningún archivo Compose, se lee solo su primer archivo de sobrescritura. Un comentario al principio del Aggregate de borrador nombra los archivos leídos, en el orden en que se fusionan, y los archivos no leídos. Cada servicio y cada modelo de cada directorio se genera como borrador en un único Aggregate.
  • La fusión. Un archivo de sobrescritura se fusiona como lo fusiona Compose: image se reemplaza; los ports se fusionan por su dirección, su puerto publicado, su puerto del contenedor y su protocolo, los volumes por su ruta en el contenedor, y environment por nombre de variable, de modo que una entrada posterior ocupa el lugar de una anterior y una nueva se añade a continuación; expose se añade al final; depends_on y los models de un servicio se unen, y endpoint_var y model_var de una entrada ocupan cada uno el lugar del que indica un archivo anterior. De un modelo, model y context_size se reemplazan y runtime_flags se añade al final. Los tags !reset y !override de Compose no se respetan: un valor que lleva una de ellas se fusiona tal como lo lee el analizador YAML.
  • Un servicio. Su image, y si construye una bajo build; sus ports, expose, volumes y environment — un mapeo, o una lista de elementos NAME=value, donde un nombre sin valor toma su valor del entorno en el que se ejecuta Compose; depends_on, una lista o un mapeo; y sus models, una lista de nombres de modelos o un mapeo cuyas entradas pueden nombrar, bajo endpoint_var y model_var, las variables con las que la dirección y el identificador del modelo llegan al servicio. Cualquier otro miembro — command, healthcheck, secrets, env_file y el resto — no se escribe en ningún sitio, y se nombra en un comentario encima de la entrada del servicio en la Release.
  • Un modelo. Cada entrada de los models de nivel superior: su model, el identificador OCI del modelo, su context_size y sus runtime_flags, trasladados tal como están escritos a una instancia de core/ai-model/docker-model-runner donde tu catálogo lo contiene, y de un Component de modelo generado como borrador para él donde no lo contiene; la decisión del modelo dice cuál, y por qué. Cualquier otro miembro se nombra en un comentario encima de su instancia.
  • El resto. Los demás miembros de nivel superior — name, networks, volumes, secrets, configs — no se leen, y el comentario al principio del Aggregate los nombra.

Los servicios, los modelos y el entorno de un servicio conservan el orden en que el archivo los escribe. El árbol del analizador escribe los miembros de un mapeo ordenados, así que ese orden se lee del texto del archivo, donde están escritos como un mapeo de bloque; un mapeo escrito en estilo flow conserva la ordenación.

Qué Component es un servicio

El importador hace coincidir un servicio por el repositorio que nombra su imagen: la referencia sin su tag ni su digest, con una referencia de Docker Hub escrita en su forma corta — postgres para docker.io/library/postgres:16. Hace coincidir el repositorio mediante su tabla de imágenes, una tabla que va del repositorio de una imagen al Component del catálogo para el que una Recipe de Compose del catálogo estándar ejecuta una imagen de ese repositorio. La tabla se genera a partir de las Recipes de Compose y los Components del catálogo estándar cuando se construye el importador, y se compila en él, así que no se lee ninguna Recipe cuando se ejecuta una importación y la tabla contiene las etiquetas del catálogo estándar, contenga lo que contenga tu catálogo; la entidad Plugin del importador nombra, en su descripción, la revisión del hub a partir de la que se generó la tabla. De cada Recipe, la tabla lee el Component que implementa la Recipe y la imagen de su contenedor llamado main, donde esa imagen escribe su repositorio en su propio texto, o es una entrada de locals que lo hace. Una Recipe que ejecuta la imagen que la Release nombra entera, o una que su plantilla compone de otro modo, no añade ninguna fila, y tampoco una imagen que una Recipe ejecuta junto a su contenedor principal. Dos Recipes que nombran un mismo repositorio para Components distintos impiden que se genere la tabla, de modo que una fila nunca nombra uno de dos. Del Component que nombra una fila, la tabla lee sus etiquetas tal como se entregan a una importación — en la versión a la que se resuelve una referencia que nombra el Component sin versión, con las que hereda mediante extends — y escribe cada etiqueta salvo component.aggrega.ai/category en la fila como sus rasgos. Una Recipe que implementa un Component que el catálogo estándar no contiene también impide que se genere la tabla.

Una fila se lee como se lee la fila de la tabla de un importador de flujos: el Component, la categoría en la que lo sitúa su nombre, sus rasgos y el último segmento de su nombre como su fabricante. El ajuste mapping_overrides se superpone a la tabla bajo el formato compose, con el repositorio como clave, y una entrada para un repositorio que la tabla mapea ocupa el lugar de la fila. Así, una imagen que las Recipes del catálogo estándar no nombran — la tuya, o una que un Component del catálogo ejecuta bajo otro repositorio — se mapea mediante una entrada:

with:
settings:
mapping_overrides:
compose:
bitnami/redis:
component: core/datastore/redis
category: datastore
traits:
datastore.aggrega.ai/engine: kv
vendor: redis

Un servicio cuya imagen mapea una fila se decide como los importadores de flujos deciden un nodo: se puntúa frente a los Components de tu catálogo, se referencia donde reuse_mode es auto-apply-above-threshold, el valor predeterminado, y su mejor candidato es una coincidencia de nivel alto igual o superior a reuse_threshold, y en caso contrario se genera como borrador como un Component propio, y el archivo del Component generado como borrador empieza con un comentario que nombra el Component al que se parece. Una fila lleva las etiquetas del Component que nombra, así que donde tu catálogo contiene ese Component con las etiquetas que le da el catálogo estándar, un servicio que la fila mapea es una coincidencia de nivel alto para él, con una puntuación de 0.90, y auto-apply-above-threshold lo referencia con el reuse_threshold predeterminado. Un Component cuyas etiquetas ha cambiado tu catálogo obtiene una puntuación menor, en proporción a la parte de los rasgos de la fila que ya no lleva, y solo se referencia mientras permanece en el nivel alto; la categoría se puntúa una sola vez, en su propia señal, y no de nuevo como rasgo. Los servicios que generan como borrador un mismo Component comparten su único archivo. Un servicio cuya imagen no mapea ninguna fila, cuya imagen no nombra ningún repositorio que lea el importador, o que construye su imagen, es una instancia de core/compute/server, contenga lo que contenga tu catálogo. Se informa de la decisión de cada servicio como de la de cada nodo.

En qué se convierte un servicio

aggregate.yaml es un Aggregate de borrador que lleva el nombre del proyecto, como describe Cómo se nombra un borrador, y que contiene una instancia por servicio, del Component que eligió su decisión, con la clave asignada como el importador MCP asigna la clave a un servidor, y un comentario encima que nombra el servicio y el archivo del que procede donde la clave no es el nombre del servicio o la importación leyó varios directorios. Cada servicio que nombra el depends_on de un servicio es una conexión, uses: <key>: <key>: {target: <key>}, escrita bajo un socket y un alias que llevan ambos el nombre de la clave del destino. Un componente lee cada una de sus conexiones por su alias, sea cual sea el socket al que esté conectada, así que cada conexión de un servicio tiene un alias propio. Una variable del entorno de un servicio también puede dar lugar a una conexión, que entrega la variable a partir de lo que publica el servicio al que llega, como describe En qué se convierten el entorno y la imagen de un servicio. Cada modelo es una instancia de core/ai-model/docker-model-runner donde el catálogo del espacio de trabajo lo contiene, diga lo que diga reuse_mode, y no se genera como borrador ningún Component para él: la instancia escribe model y runtime_flags tal como los indica el origen, y el context_size del origen como context_window, el valor que el entorno de ejecución declara para la longitud de contexto de un modelo, que su Recipe de Compose vuelve a escribir como el context_size de Compose. Donde el catálogo no contiene ningún core/ai-model/docker-model-runner, el modelo se genera como borrador como <target_namespace>/ai-model/<key>, un Component de la categoría ai-model cuyos valores declaran model, context_size y runtime_flags, y su instancia escribe cada uno de los que indica el origen. Cada modelo tiene una decisión que dice cuál — mapped llm (model) to core/ai-model/docker-model-runner as a reference, NONE, o un borrador cuya decisión registra que el catálogo del espacio de trabajo no contiene ningún core/ai-model/docker-model-runner — y cada servicio que nombra el modelo se conecta a él en ambos casos, como a un servicio del que depende. Un servicio que nombra el modelo en la forma larga, con endpoint_var o model_var, nombra las variables con las que su dirección y su identificador llegan al servicio. Ninguna clave del borrador contiene el nombre de una variable — la conexión se escribe en un socket que lleva el nombre del modelo, que no declara ningún valor, y a un importador no se le entrega ninguna clave de infraestructura de un Component — así que un comentario encima de la conexión nombra cada una, tal como la escribe la entrada, y la decisión del servicio registra la misma frase:

search:
type: core/compute/server
uses:
# The service search reads the address of the model embedder as AI_MODEL_URL and its identifier as AI_MODEL_NAME, the names its models entry gives them; no key of the draft holds either name.
embedder:
embedder:
target: embedder

Un servicio que nombra el modelo en la forma corta, o sin ninguna de las dos variables, se conecta a él sin comentario.

Junto a él, release.yaml es una Release de borrador con el mismo nombre, cuyo spec.aggregate nombra el Aggregate. Para una instancia de core/compute/server escribe infra.image, la imagen tal como está escrita, e infra.port, el puerto en el que escucha el contenedor en la primera entrada de ports, o de expose donde ports no contiene ninguna. Con --target compose escribe también infra.published_port, el puerto del host que publica esa misma entrada de ports, tal como lo indica el origen, bajo el comentario que dice que solo es accesible desde esta máquina, por cualquier proceso que se ejecute en ella, y que eliminar la línea mantiene el servicio interno; un puerto del host inferior a 1024, que published_port no acepta, no se escribe, y un comentario encima de la entrada lo nombra. Un comentario encima de la entrada de cada servicio escribe lo que el origen indica y que no lleva ninguna clave del borrador — la imagen de un servicio que coincide con otro Component cuya etiqueta el borrador no traduce, sus ports, expose, volumes, y cada variable de su environment que el borrador no traduce — para que lo traslades donde el Component lo acepte. Lo que el borrador deja para la Release — la imagen de un servicio que no nombra ninguna, como hace uno que construye la suya, y un puerto que no es un único número — se escribe vacío bajo un comentario que explica por qué. Una compilación coloca solo las instancias que nombra una Release, así que la instancia de cada modelo tiene una entrada vacía, <key>: {}, después de las de los servicios: tanto una instancia de core/ai-model/docker-model-runner, que en Compose no acepta ninguna entrada que carezca de valor predeterminado, como un modelo generado como borrador como un Component propio, de modo que el modelo generado como borrador ya está colocado y compila en cuanto escribas la Recipe que lo realiza. Un puerto que el Component no acepta, como uno por debajo del mínimo de 1024 de core/compute/server, se escribe tal como lo indica el origen, y la compilación se detiene nombrándolo. La Release escribe metadata.environment y, sin destino, un spec.manifest vacío, como hace la del importador MCP; dado un destino, la importación genera como borrador el Manifest, como describe Qué añade un destino, asignando cada Component a la Recipe que lo realiza en ese destino — core/compute/server a compose/server o helm/server, y core/ai-model/docker-model-runner a compose/docker-model-runner o helm/docker-model-runner.

Un compose.yaml que ejecuta PostgreSQL y una API propia que depende de él:

services:
db:
image: postgres:16
environment:
POSTGRES_DB: shop
api:
image: ghcr.io/example/shop-api:1.4.2
depends_on:
- db
ports:
- "8080:8080"
environment:
CACHE_URL: redis://cache:6379/0

se genera como borrador, sin ningún ajuste, sobre un catálogo que contiene el core/datastore/postgres de la biblioteca estándar, importado por sí solo y con el nombre del archivo, ya que el proyecto no lleva ningún name, así:

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/compose
version: 0.1.0
description: Draft Aggregate imported from a source in the compose format.
spec:
components:
db:
type: core/datastore/postgres
# The values of core/datastore/postgres the source sets as POSTGRES_DB, the variables its Compose Recipes set from them.
values:
database: "shop"
api:
type: core/compute/server
uses:
db:
db:
target: db
release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/compose
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the compose format.
spec:
aggregate: imported/compose
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
db:
infra:
# The tag of the image the source runs, postgres:16, the engine_version of core/datastore/postgres its Compose Recipes run.
engine_version: "16"
# The source also states, for the Release to carry where core/compute/server takes it:
# ports:
# - "8080:8080"
# environment:
# CACHE_URL: "redis://cache:6379/0"
api:
infra:
image: "ghcr.io/example/shop-api:1.4.2"
port: 8080

La importación informa mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9. El proyecto no contiene ningún servicio cache, así que CACHE_URL no da lugar a ninguna conexión y permanece en el comentario. Con reuse_mode: hints-only, db es en cambio type: imported/datastore/postgres, generado como borrador en components/imported-datastore-postgres.yaml, que comienza con # resembles core/datastore/postgres (score 0.9000); reference it by setting type: core/datastore/postgres; su imagen y su entorno se escriben entonces en el comentario encima de su entrada, ya que un Component generado como borrador no declara ninguno de los valores que leen las Recipes del catálogo. Con --target compose, el Manifest asigna core/datastore/postgres a compose/postgres y core/compute/server a compose/server; con --target helm, a helm/postgres y helm/server.

En qué se convierten el entorno y la imagen de un servicio

Donde un servicio es una instancia del Component del catálogo que nombra la fila de su imagen, y el catálogo del espacio de trabajo contiene ese Component, el importador lee su imagen y su entorno como los leen las Recipes de Compose del catálogo estándar para ese Component, a partir de lo que la tabla de imágenes registra de cada Recipe, y los traduce a los borradores:

  • La etiqueta de la imagen es la clave de infraestructura a partir de la cual la Recipe construye la referencia de la imagen, como engine_version — 16 para postgres:16 — escrita en la Release bajo un comentario que nombra la imagen del origen.
  • Una variable que la Recipe establece a partir de uno de los valores del Component — POSTGRES_DB, POSTGRES_USER — cuyo valor contiene texto es ese valor de la instancia, database o user, donde el Component del catálogo lo declara, escrito en el Aggregate bajo un comentario que nombra las variables.
  • Una variable de la que la Recipe lee una contraseña, como POSTGRES_PASSWORD, cuyo valor es una única referencia a una variable, es un secreto adjuntado en esa ranura, leído de la variable que nombra la referencia y declarado con la clave con la que la Recipe lo lee.

Y, para cada servicio, cada variable de su entorno que no se lee así:

  • Un valor que es el nombre de otro servicio del proyecto, donde la fila de ese servicio nombra la clave provides que publica su nombre de host, da lugar a una conexión con ese servicio, cuyo bloque inject entrega la variable a partir de esa clave — CACHE_HOST: cache es CACHE_HOST a partir del host de la caché.
  • Un valor igual a un valor que otro servicio establece para su Component y que el Component publica — DATABASE_USER: notes junto a un servicio PostgreSQL que establece POSTGRES_USER: notes — da lugar a una conexión que entrega la variable a partir de esa clave provides. Donde varios servicios o claves contienen el valor, se lee aquel cuya clave, o cuya propia variable, termina como termina el nombre de la variable y, en su defecto, aquel del que aún no se han leído las demás variables del servicio; de lo contrario, la variable no se lee.
  • Un valor que es una única referencia a una variable que nombra una variable de la que se lee el secreto de otro servicio — DATABASE_PASSWORD: ${POSTGRES_PASSWORD} — es, en una instancia de core/compute/server, un secreto propio, adjuntado bajo el nombre de la variable en minúsculas y leído de la misma variable, donde el destino escribe el secreto como un valor que el servidor acepta. helm/server rechaza un core/referenced-secret, así que con --target helm esa variable permanece en el comentario.

Cualquier otra variable se deja en el comentario encima de la entrada del servicio, tal como la escribe el origen. El recorrido de la importación de Compose muestra un proyecto cuya API llega a su base de datos y a su caché de esta manera, compilado y ejecutado tal como se generó el borrador.

Valores de credenciales que contiene un servicio

Compose no marca ningún valor de entorno como credencial, y el importador no lee el nombre de ninguna variable por lo que significa, así que cada valor de entorno que contiene algo se localiza como una entrada que su formato marca como no credencial pero que puede llevar una. De forma predeterminada, cada uno se traslada tal como está escrito a los borradores — al valor al que se traduce, o al comentario encima de la entrada de su servicio en la Release — y se nombra en una advertencia credential-carried por su servicio y su variable — environment.<variable> — nunca por su valor. Con el ajuste empty_credentials en all, cada uno se escribe vacío y se informa de él con credential-emptied: el comentario nombra su variable sin valor. En marked ninguno se escribe vacío, ya que Compose no marca ninguno. Un valor que es una referencia a una variable que Compose interpola y nada más — ${NAME} o $NAME — no contiene ningún valor propio: se escribe como el texto que es, y no se nombra en ninguna advertencia. Una referencia que lleva un valor predeterminado o un mensaje, como ${NAME:-value}, contiene ese texto, y se localiza como cualquier otro valor. Un valor que Compose lee de otro sitio — un env_file, el archivo de un secreto — no se lee.

Los ajustes que lee

El importador Compose lee target_namespace, reuse_mode, reuse_threshold, emit_hints, render_mode, mapping_overrides y empty_credentials, tal como los describe Ajustes, y ningún otro ajuste. La sugerencia que rige emit_hints se escribe solo en el archivo del Component generado como borrador; el Aggregate de borrador no lleva ninguna.

El importador Dify

importer/dify lee una aplicación exportada de Dify en su DSL, el documento YAML que Dify escribe para una aplicación, y genera como borrador un Aggregate que compone la instalación de Dify de la biblioteca estándar, core/dify, con la aplicación trasladada en el parámetro app_definition de la instalación. La instalación la importa en el despliegue, mediante el paso que la Recipe de su servidor de API renderiza para ella.

Qué lee

  • La aplicación. kind, que es app; version, la versión del DSL en la que está escrita la aplicación; y app, con su mode.
  • Un workflow o un chatflow — mode workflow o advanced-chat — guarda su grafo bajo workflow: cada nodo de workflow.graph.nodes que nombra su tipo bajo data.type es un nodo de la aplicación, en el orden en que el grafo los enumera, y workflow.environment_variables contiene las variables que lee.
  • Una aplicación chat, agent chat o completion guarda su configuración bajo model_config: su model, cada base de conocimiento bajo dataset_configs.datasets.datasets y cada herramienta bajo agent_mode.tools es un nodo de la aplicación, nombrado por su lugar allí, como model_config.model. Una aplicación del modo agent es un único nodo, agent.
  • Los plugins que necesita. Cada entrada de dependencies es también un nodo, llamado dependencies.<n>, del tipo que nombra la entrada, como marketplace.

Nada más decide lo que se genera como borrador: se traslada la aplicación entera.

En qué se convierte una aplicación

aggregate.yaml es un Aggregate de borrador que lleva el nombre de la aplicación, como describe Cómo se nombra un borrador, y que compone una entrada de core/dify, con la clave dify, cuyo parámetro app_definition lleva la aplicación tal como está escrita — como describe Cómo se escribe el flujo en el borrador para un flujo, de modo que las referencias {{#…#}} propias de Dify llegan a la instalación tal como se exportaron. La instalación establece por sí misma cada conexión de su servidor de API — su base de datos, su caché, su almacén vectorial, su sandbox, su entorno de ejecución de plugins y su proxy de salida — así que el borrador no genera ningún Component como borrador y no conecta nada: cada nodo permanece en la aplicación, y su decisión lo dice. Junto a él, release.yaml es una Release de borrador con el mismo nombre, que coloca la instalación en un límite, platform, y lleva lo que la aplicación no puede aportar.

Una importación ve los Components del catálogo del workspace y ninguno de sus Aggregates, así que no comprueba que el catálogo contenga core/dify, y un comentario encima de la entrada lo dice. Donde el catálogo no contiene core/ai-agent/dify, el servidor de API que ejecuta core/dify, la importación advierte con platform-not-in-catalog y genera la entrada como borrador de todos modos.

El secreto de aplicación de la instalación, la clave con la que Dify firma sus cookies de sesión y con la que cifra las credenciales de los proveedores de modelos que almacena, es el parámetro secret_key de core/dify, que no tiene valor predeterminado. Por eso el borrador declara su propio parámetro secret_key — una cadena, obligatoria, de al menos un carácter y sin valor predeterminado — y lo transmite a cada entrada de core/dify que escribe, para que la Release lo cumpla bajo sus parameters; una compilación cuya Release lo deja sin definir se detiene nombrándolo.

La aplicación se importa con la cuenta del propietario de la instalación, que la Release nombra en su entrada de enrutamiento para la instalación: infra.owner_email en el componente api de la instalación, y la ranura owner_password en ese componente, adjunta como core/referenced-secret, sin los cuales la compilación se detiene. El correo electrónico del propietario no es algo que ninguna fuente pueda aportar, así que se escribe vacío bajo un comentario que dice qué es, y la importación lo señala como pendiente.

En todos los destinos, la misma entrada de enrutamiento establece infra.marketplace_enabled en true en los componentes api, worker y scheduler de la instalación, cada uno bajo un comentario que explica por qué: la instalación no alcanza nada del proveedor de Dify a menos que la Release lo permita, cada uno de los tres lee su propia configuración, y Dify instala el plugin que sirve el modelo de una aplicación, como el de OpenAI, desde su marketplace de plugins.

El secreto de aplicación y la contraseña del propietario son secretos, generados como borrador por referencia para el destino de la importación:

  • Con --target helm, cada uno nombra un Secret de Kubernetes que ya está en el namespace: secret_key el nombre del Secret, que core/dify lee bajo la clave de datos secret-key, y owner_password un Secret que contiene la contraseña bajo la clave de datos value. Ninguno de los dos nombres es algo que una fuente pueda aportar, así que cada uno se escribe vacío bajo un comentario que dice qué es, y la importación señala ambos como pendientes; el Manifest generado como borrador mapea core/referenced-secret a helm/k8s-existing-secret.
  • En cualquier otro destino, y sin destino, cada uno es una referencia a una variable — secret_key como "${DIFY_SECRET_KEY}" y la contraseña del propietario como "${DIFY_OWNER_PASSWORD}", los nombres que leen las Recipes de Dify para Compose del catálogo estándar — que Docker Compose lee del entorno cuando se inicia el stack, así que no queda nada pendiente para ninguno de los dos; con --target compose el Manifest generado como borrador mapea core/referenced-secret a compose/dotenv-referenced-secret.

Dado un destino, el Manifest mapea el tipo de cada componente que compone la instalación, así como el del propio borrador, como describe Qué añade un destino.

La aplicación workflow escrita a mano que importan las pruebas de este importador, llamada Support Answers, se genera como borrador, sin ningún ajuste, así:

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support-answers
version: 0.1.0
description: Draft Aggregate imported from a source in the dify format.
spec:
parameters:
secret_key:
type: string
required: true
minLength: 1
description: "Passed down to core/dify's secret_key parameter, which has no default; that parameter's description in core/dify says what the value is."
aggregates:
# An import sees the Components of the workspace's catalog and none of its Aggregates, so it does not check that the catalog holds core/dify.
dify:
type: core/dify
parameters:
secret_key: "{{ .parameters.secret_key }}"
app_definition: |
app:
description: Answers a support question from a knowledge base and files it.
...

Importada con --target helm, su Release generada como borrador cumple secret_key, y nombra al propietario y activa el marketplace de plugins en la entrada de enrutamiento que coloca la instalación, con cada valor pendiente escrito vacío:

release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/support-answers
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the dify format.
spec:
aggregate: imported/support-answers
manifest: imported/support-answers
parameters:
# Left for the Release, since the source cannot supply it: secret_key, which the drafted Aggregate declares and passes down to core/dify; that parameter's description there says what the value is
secret_key: ""
boundaries:
platform:
aggregates:
dify:
components:
api:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true
# Left for the Release, since the source cannot supply it: components.api.infra.owner_email, the email of the installation's owner account the application is imported under, on the api component of core/dify
owner_email: ""
features:
owner_password:
type: core/referenced-secret
infra:
# Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding, under the data key value, the owner account's password.
origin: ""
worker:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true
scheduler:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true

La importación señala como pendientes los tres valores vacíos. Importada con --target compose, la misma Release escribe secret_key: "${DIFY_SECRET_KEY}" y origin: "${DIFY_OWNER_PASSWORD}", y señala como pendiente solo el correo electrónico del propietario; también escribe infra.published_port en el componente api, 5001, y en el front end, el componente console, 3001, cada uno bajo el comentario que dice que solo es accesible desde esta máquina, por cualquier proceso que se ejecute en ella, y que eliminar la línea mantiene el servicio como interno, y, debajo del puerto del componente api, infra.console_url con la dirección en la que se publica la consola, "http://127.0.0.1:3001", que el servidor de Dify toma como dirección de la consola. La guía paso a paso de la importación de Dify compila una aplicación para ambos destinos y la ejecuta en Kubernetes.

Qué configura Dify por sí mismo

Dify configura dentro de sí mismo los proveedores de los modelos y de las herramientas que llama una aplicación, y core/ai-agent/dify no declara ningún socket para un modelo, así que el borrador no conecta ninguno. Se informa de cada nodo que nombra uno con part-configured-in-platform, y en su decisión, según lo que nombra:

  • un nodo llm, question-classifier o parameter-extractor, y el model_config.model de una aplicación chat: el modelo, por su nombre y su proveedor;
  • un nodo tool, y la herramienta de una aplicación chat: la herramienta, por su nombre y su proveedor;
  • un nodo agent: la estrategia del agente y el plugin que la proporciona;
  • un nodo knowledge-retrieval, y la base de conocimiento de una aplicación chat: las bases de conocimiento de las que recupera, y el modelo con el que enruta una consulta o con el que reordena, donde nombra uno. Una aplicación nombra una base de conocimiento por un identificador de la instalación de la que se exportó, y no lleva ninguno de sus documentos ni ningún almacén, así que cada una se crea dentro de Dify, en el almacén vectorial que la instalación conecta a su servidor de API;
  • una dependencia: el plugin, por el identificador con el que Dify lo instala, y el lugar desde el que Dify lo instala.

Cualquier otro nodo se mantiene en la aplicación sin que se informe de nada.

Valores de credenciales que contiene una aplicación

El importador localiza, en el orden en que la aplicación los escribe:

  • el valor de cada variable de entorno cuyo value_type es secret, que Dify marca como credencial. La exportación de Dify lo escribe vacío a menos que la exportación incluya los secretos;
  • el authorization.config.api_key de un nodo de solicitud HTTP, que Dify marca como credencial y exporta tal como está escrito;
  • la credencial almacenada que un nodo tool, o una herramienta de un nodo agent, selecciona bajo credential_id, que Dify marca como credencial y escribe solo donde la exportación incluye los secretos;
  • los headers y params de un nodo de solicitud HTTP, que Dify no marca como credencial y que pueden llevar una, cada uno entero.

De forma predeterminada, cada uno que contiene un valor se traslada tal como está escrito en la aplicación y se nombra en una advertencia credential-carried por su nodo — workflow para una variable de entorno — y su campo, nunca por su valor. Con el ajuste empty_credentials en marked, cada valor que Dify marca como credencial se escribe vacío, y en all también los encabezados y los parámetros de consulta, informándose de cada uno con credential-emptied. Un valor que es una referencia a una variable y nada más no contiene ninguno, y se traslada tal como está escrito diga lo que diga el ajuste y no se nombra en ninguna advertencia, como en un flujo. Un valor se escribe vacío en el propio texto de la aplicación: el escalar que sigue a su clave se sustituye por '', y no se cambia nada más. La aplicación se traslada solo donde el analizador que sirve parse:yaml vuelve a leer el resultado como la aplicación exportada con exactamente esos valores vaciados; de lo contrario no se traslada, app_definition se deja sin definir con un comentario, y definition-not-carried dice por qué — como en una aplicación en la que un alias de YAML lee el valor de un secreto, que escribir vacío ese valor también cambiaría. Un valor que el ajuste deja tal como está escrito nunca se reescribe, así que nunca impide que la aplicación se traslade.

La versión del DSL

Donde una aplicación está escrita en una versión del DSL más reciente que 0.7.0, la versión que escribe Dify 1.17.0 — la versión que core/ai-agent/dify ejecuta de forma predeterminada —, la importación advierte con dsl-version-newer. Dify retiene la importación de una aplicación así a la espera de una confirmación, que da el paso que la importa en el despliegue, así que comprueba la aplicación con la versión de Dify que ejecuta la Release.

Los ajustes que lee

El importador Dify lee target_namespace, empty_credentials, layout, attach_egress_allowlist y render_mode, tal como los describe Ajustes, y reuse_mode, reuse_threshold, emit_hints y mapping_overrides, que no cambian nada de lo que genera como borrador la disposición predeterminada: cada nodo permanece en la aplicación. attach_egress_allowlist no vincula nada, ya que una entrada de un Aggregate compuesto acepta parámetros y ninguna Feature, y con él en true la importación advierte con feature-not-attached. layout: nodes genera como borrador cada nodo como un Component propio, como describe Nodo por nodo, y no traslada ninguna aplicación.

El importador CrewAI

importer/crewai lee los agentes y las tareas que un proyecto de CrewAI declara en sus archivos de configuración, y genera como borrador un Aggregate que contiene una instancia del agente CrewAI de la biblioteca estándar, core/ai-agent/crewai, por agente, cada una conectada al modelo que nombra su configuración, y una Release junto a él.

Qué lee

CrewAI guarda el comportamiento de una crew en un programa y declara sus agentes y sus tareas en archivos de configuración, en una de dos estructuras, y el importador lee cualquiera de ellas:

  • Un proyecto clásico — config/agents.yaml, con cada agente con su nombre como clave, y config/tasks.yaml, con cada tarea con su nombre como clave, ambos leídos como YAML. Los agentes se leen en el orden en que agents.yaml los escribe.
  • Un proyecto en la estructura JSON-first — crew.jsonc, que enumera los agentes de la crew por nombre bajo agents y sus tareas bajo tasks, y agents/<name>.jsonc, un archivo por agente, todos leídos como JSON con comentarios, de modo que sus comentarios y sus comas finales se leen como los lee CrewAI. Los agentes se leen en el orden en que crew.jsonc los enumera, seguidos del archivo de cualquier otro agente en el orden de los nombres; un agente que la crew enumera cuyo archivo no se entregó a la importación se nombra en un comentario y no se genera nada como borrador para él. La misma estructura escrita en JSON estricto — crew.json y agents/<name>.json — se lee del mismo modo. Donde una crew o un agente está escrito en ambas grafías, el archivo .jsonc es el que se lee, como lo lee CrewAI, y el archivo .json se nombra en un comentario como no leído.

De un agente lee su role, goal y backstory; allow_delegation y verbose, en el nivel superior de su declaración o bajo settings, donde prevalece settings, como los lee CrewAI; su llm; y los nombres de sus tools. De una tarea lee su nombre y el agente al que está asignada. Cualquier otro miembro se nombra en un comentario y no se traslada a ningún sitio.

Un directorio se entrega al importador como los archivos que nombran sus firmas y ningún otro, así que el programa de la crew — el crew.py de un proyecto clásico, el main.py de un flujo, una herramienta que un proyecto define en Python — nunca se lee. Un archivo importado por sí solo se lee como la declaración cuya forma tiene. El directorio de un proyecto puede contener varias crews, cada una leída desde su propio directorio.

En qué se convierte un proyecto

aggregate.yaml es un Aggregate de borrador que lleva el nombre de la crew, como describe Cómo se nombra un borrador, y que empieza con comentarios que nombran las declaraciones leídas, que el programa de la crew no se lee, y las tareas de cada crew con el agente al que está asignada cada una. Contiene, por agente y con su nombre como clave, una instancia de core/ai-agent/crewai con:

  • role, goal y backstory tal como se declararon;
  • allow_delegation tal como se declaró, y false donde el agente no declara ninguno;
  • log_level DEBUG para un agente declarado verbose, que narra cada paso de su razonamiento, e INFO para uno que no lo es, que solo informa del progreso y de los problemas. Un verbose o un allow_delegation que no es ni true ni false se deja al valor predeterminado del Component y se nombra en un comentario;
  • su conexión model, conectada a la instancia del modelo que nombra su llm.

Un llm escrito <provider>/<model>, o como un objeto que nombra el modelo bajo model, model_name o deployment_name, nombra un proveedor y un modelo. El modelo es una instancia del Component del catálogo para ese proveedor — core/ai-model/<provider>, con un guion bajo en el nombre del proveedor leído como guion, y azure leído como azure-openai — con el nombre del modelo como clave y el modelo como su values.model; los agentes que nombran un mismo proveedor y modelo comparten una instancia. Donde el catálogo del workspace no contiene ningún Component con ese nombre, se genera uno como borrador, <target_namespace>/ai-model/<provider>, que declara el valor model, y su decisión lo dice; la etiqueta model.aggrega.ai/api por la que el socket model del agente selecciona un Component, y una Recipe que publique su endpoint y su modelo, quedan para ti, como dice un comentario al principio de él. Un llm que no nombra ningún proveedor — un nombre de modelo a secas, para el que CrewAI resuelve un proveedor cuando se ejecuta el programa, o el nombre de un llm que define el programa — una referencia dentro del programa, y un agente que no declara ningún llm, que CrewAI lee entonces del entorno en el que se ejecuta su programa, no se conectan a nada, y un comentario encima del agente dice por qué; la compilación se detiene nombrando el socket model hasta que se conecte uno.

Una tarea es lógica que ejecuta el programa de la crew, y una herramienta es código que el programa define o carga: ninguna de las dos se convierte en un Component. Se informa de cada una en una decisión que no elige nada, y una herramienta cuyo nombre — sin un Tool final, sin sus guiones y guiones bajos — es el nombre de un Component de herramienta que contiene el catálogo lleva ese Component como sugerencia: search_tool y SearchTool sugieren ambos core/ai-tool/search. core/ai-agent/crewai no declara ningún socket para una herramienta, así que no se conecta nada para ella.

release.yaml, junto a él, es una Release de borrador con el mismo nombre que nombra ese Aggregate. Escribe vacío el infra.image de cada agente — la imagen que ejecuta el programa de la crew, que ninguna declaración nombra — bajo un comentario que dice qué es, y la importación lo señala como pendiente. Con --target compose, la entrada de cada agente también escribe infra.published_port, 8000, el puerto que el infra.port del Component indica por defecto para el programa, que su Recipe de Compose publica en la dirección de loopback del host, 127.0.0.1, bajo el comentario que dice que solo es accesible desde esta máquina, por cualquier proceso que se ejecute en ella, y que eliminar la línea mantiene el servicio como interno; un segundo agente toma el siguiente puerto libre, así que los dos agentes del proyecto clásico se publican en 8000 y 8001. Adjunta la credencial que cada agente presenta a su modelo bajo credential en su conexión model, por referencia y nunca como valor: ninguna declaración nombra una variable para ella, así que se lee de la variable de la que las bibliotecas cliente del proveedor leen su clave de API — OPENAI_API_KEY para OpenAI — como una referencia ${…} en todos los destinos salvo helm, y en helm como el nombre de un Secret de Kubernetes, escrito vacío para que la importación lo señale como pendiente; en compose, la conexión model del agente la declara con esa clave. Cada modelo también tiene una entrada, que no contiene infraestructura, así que la Release lo coloca junto con los agentes. De un modelo declarado como objeto llm, cada uno de los demás miembros se escribe como un valor de la instancia del modelo donde el Component del catálogo declara un valor con ese nombre, y en caso contrario en un comentario encima de la entrada del modelo en la Release, para que lo traslades donde el Component lo acepte. Como toda Release generada como borrador, escribe metadata.environment como development y, sin destino, un spec.manifest vacío que la importación señala como pendiente; dado un destino, la importación genera el Manifest como borrador, como describe Qué añade un destino.

El proyecto clásico que importan las pruebas de este importador, cuyos dos agentes nombran ambos openai/gpt-4o, se genera como borrador, sin ningún ajuste, como se muestra a continuación; importado como su directorio de proyecto, market_brief — el directorio en el que crewai create crew market_brief dispone un proyecto así —, y dado que sus declaraciones no nombran ninguna crew, recibe el nombre de ese directorio:

aggregate.yaml
# CrewAI declarations read:
# - src/market_brief/config/agents.yaml
# - src/market_brief/config/tasks.yaml
# Not read: the crew's program, which runs its agents and its tasks and defines its tools; it runs in the image the Release names for each agent.
# Tasks the crew's program runs, drafted as no Component:
# - research_task, assigned to researcher
# - brief_task, assigned to brief_writer
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/market-brief
version: 0.1.0
description: Draft Aggregate imported from a source in the crewai format.
spec:
components:
# Tools the crew's program defines or loads for this agent, drafted as no Component: search_tool.
researcher:
type: core/ai-agent/crewai
values:
role: "{topic} Market Researcher\u000A"
goal: "Gather the facts about {topic} a buyer needs before a first meeting\u000A"
backstory: "You have briefed sales teams for years. ..."
allow_delegation: false
log_level: DEBUG
uses:
model:
gpt-4o:
target: gpt-4o
# For the compose target only, uncomment the lines below, which declare credential on gpt-4o: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: OPENAI_API_KEY
# The agent brief_writer.
# Not carried, since core/ai-agent/crewai takes no value for it: max_iter.
brief-writer:
type: core/ai-agent/crewai
...
# The model openai/gpt-4o.
gpt-4o:
type: core/ai-model/openai
values:
model: "gpt-4o"

y su Release, generada como borrador sin destino, como se muestra a continuación, con la entrada del segundo agente omitida aquí y marcada con ...; la importación señala como pendientes spec.manifest y la imagen de cada agente:

release.yaml
spec:
aggregate: imported/market-brief
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
researcher:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the crew's program
image: ""
uses:
model:
gpt-4o:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential researcher presents to gpt-4o on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
brief-writer:
...
gpt-4o: {}

Cada agente se renderiza entonces ejecutando la imagen que indiques en tu respuesta, y recibe el endpoint del modelo y el nombre del modelo como OPENAI_BASE_URL y MODEL, las variables de las que CrewAI los lee.

Valores de credenciales que contiene una declaración

Un llm escrito como objeto puede llevar una clave — bajo api_key, en una dirección, en encabezados. Cada uno de sus miembros distinto del que nombra el modelo que no es un número ni un booleano es un valor que puede llevar una, que CrewAI no marca como credencial. De forma predeterminada, cada uno que contiene un valor se traslada tal como está escrito — como un valor de la instancia del modelo donde su Component declara uno, y en caso contrario al comentario encima de la entrada de su modelo en la Release — y se nombra en una advertencia credential-carried por su agente y su miembro, como llm.api_key, nunca por su valor. Con el ajuste empty_credentials en all, cada uno se escribe sin valor y se informa de él con credential-emptied; en marked cada uno se traslada, ya que CrewAI no marca ninguno. El nombre de un miembro no se lee por lo que significa. Cualquier otro miembro que contiene una declaración y que el borrador no traslada — la configuración de una herramienta, los inputs de una crew — se nombra, nunca con su valor.

Los ajustes que lee

El importador CrewAI lee target_namespace, empty_credentials y render_mode, tal como los describe Ajustes, y ningún otro ajuste.

El importador LangGraph

importer/langgraph lee los grafos que declara la configuración de una aplicación LangGraph, langgraph.json, y genera como borrador un Aggregate que contiene una instancia del agente LangGraph de la biblioteca estándar, core/ai-agent/langgraph, por grafo, cada una conectada al almacén de datos en el que su checkpointer guarda el estado y a un modelo, y una Release junto a él que lleva el entorno que indica la configuración. Lee esa configuración, y nunca el código de los grafos.

Qué lee

Una aplicación LangGraph guarda sus grafos en código y los declara en langgraph.json: bajo graphs, el id de cada grafo se asigna a la ruta de importación del grafo en el código de la aplicación — ./src/agent/graph.py:graph, o module:attr — o a un objeto que nombra esa ruta bajo path y describe el grafo bajo description. El importador lee, en el orden en que la configuración los escribe:

  • graphs — el id de cada grafo, su ruta de importación y su descripción;
  • checkpointer — su backend: default, que es PostgreSQL y lo que LangGraph lee donde no se nombra ninguno; mongo, una base de datos que habla el protocolo de MongoDB; o custom, un checkpointer que el código de la aplicación define en path;
  • store — el almacén de memoria, que no nombra ningún backend: LangGraph lo guarda en la base de datos PostgreSQL que usa su servidor;
  • env — el entorno con el que se ejecuta la aplicación: un objeto de nombres de variables a valores, o la ruta de un archivo de entorno de líneas KEY=VALUE.

Los miembros que configuran la imagen de servidor que compila langgraph build — dependencies, source, python_version, node_version, base_image, image_distro, dockerfile_lines, pip_config_file, pip_installer, keep_pkg_tools, api_version — se nombran en un comentario y no se trasladan a ningún sitio, ya que la imagen que nombra la Release es la propia de la aplicación; lo mismo ocurre con cualquier otro miembro, entre ellos la configuración propia del servidor como auth, http y webhooks, y con el index y el ttl del almacén de memoria y el ttl y el serde del checkpointer.

Un directorio se entrega al importador como langgraph.json y ningún otro archivo, así que ni el código de la aplicación ni un archivo de entorno se leen nunca de él. Un archivo de entorno llega al importador solo donde el with.sources del importador lo entrega, y nunca se analiza: del que nombra el env de la configuración — emparejado por el último segmento de la ruta que nombra — solo se leen los nombres de las variables, y un archivo de entorno que ninguna configuración nombra se nombra en un comentario como no leído. Donde a la importación no se le entrega el archivo que nombra la configuración, el Aggregate lo nombra como no entregado y dice que se nombre bajo el with.sources del importador, y sus variables se dejan para la Release:

plugins:
importer:
- uri: importer/langgraph:<version>
with:
sources:
- ./local.env

Una configuración importada por sí sola se lee sea cual sea su nombre. Un directorio puede contener varias aplicaciones, cada una leída desde su propio directorio.

En qué se convierte una aplicación

aggregate.yaml es un Aggregate de borrador que lleva el nombre del grafo, como describe Cómo se nombra un borrador, y que empieza con comentarios que nombran las configuraciones leídas, los archivos de entorno leídos solo por sus nombres, que el código de la aplicación no se lee, y lo que el borrador no traslada. Contiene, por grafo y con su id como clave, una instancia de core/ai-agent/langgraph con:

  • graph_entrypoint, la ruta de importación del grafo, tal como la escribe la configuración;
  • description, la descripción del grafo, donde la configuración da una;
  • su conexión checkpointer_db, conectada al almacén de datos de la aplicación;
  • su conexión model, conectada al modelo de la aplicación.

recursion_limit no se escribe, así que se mantiene el valor predeterminado del Component, 25. La configuración no nombra ningún modelo, así que el borrador contiene una instancia de core/ai-model/openai, con la clave model, a la que llama cada grafo: el modelo que se entrega al cliente de OpenAI del agente. Su values.model se escribe vacío, bajo un comentario que dice que la configuración no nombra ninguno, y la importación lo señala como pendiente.

El backend del checkpointer es el almacén de datos al que se conecta cada grafo de la aplicación: default, o un checkpointer que no nombra ningún backend, es una instancia de core/datastore/postgres, con la clave postgres. mongo es FerretDB, que habla el protocolo de MongoDB, sobre PostgreSQL con la extensión DocumentDB: una instancia de core/datastore/ferretdb, con la clave ferretdb, a la que se conecta cada grafo, y una de core/datastore/documentdb, con la clave documentdb, a la que llega la conexión backend de FerretDB, cuyo bloque inject entrega lo que publica DocumentDB bajo los nombres que lee FerretDB; una única contraseña, leída de la variable FERRETDB_PASSWORD, se adjunta a DocumentDB, a la conexión de FerretDB con él y a la conexión de cada grafo con FerretDB. Donde el catálogo del workspace no contiene ningún Component con el nombre del almacén de datos PostgreSQL, se genera uno como borrador, <target_namespace>/datastore/postgres, que declara el host y el port que lee la conexión checkpointer_db del agente, y su decisión lo dice; una Recipe que ejecute el almacén de datos y los publique queda para ti, como dice un comentario al principio de él. Donde no contiene ningún Component de FerretDB o ninguno de DocumentDB, el checkpointer mongo no se conecta a ningún almacén de datos. Un checkpointer custom, o un backend que el importador no asigna a ningún almacén de datos, no conecta nada, y un comentario encima de cada grafo y la decisión del checkpointer dicen por qué; la compilación se detiene nombrando el socket checkpointer_db hasta que se conecte uno. Se informa del almacén de memoria en una decisión que no elige nada.

La contraseña del almacén de datos es un secreto que el borrador adjunta por referencia, en la ranura password del propio almacén de datos y en la conexión checkpointer_db de cada grafo, y lo mismo ocurre con la credencial que cada grafo presenta al modelo en su conexión model: leídas de POSTGRES_PASSWORD (o FERRETDB_PASSWORD) y de OPENAI_API_KEY, ya que la configuración no nombra ninguna variable para ninguna de las dos, como una referencia ${…} en todos los destinos salvo helm, y en helm como el nombre de un Secret de Kubernetes, escrito vacío para que la importación lo señale como pendiente. En compose, el Aggregate declara cada una con la clave que lee su Recipe, como describe Secretos, para cada destino para una plataforma.

release.yaml, junto a él, es una Release de borrador con el mismo nombre que nombra ese Aggregate. Unos comentarios encima de la entrada del primer grafo indican cuál es la imagen de cada grafo — la propia de la aplicación, su código con LangGraph instalado, no la imagen de servidor que compila langgraph build —, las variables que recibe y qué bloque inject: sustituye cuál de sus nombres. La entrada de cada grafo escribe vacío su infra.image, la imagen que ejecuta la aplicación, bajo un comentario que dice qué es, y la importación lo señala como pendiente; mientras no se define, la Recipe de Docker Compose ejecuta el agente quickstart del propio catálogo, que lee las variables predeterminadas. Con --target compose, la entrada de cada grafo también escribe infra.published_port, 8000, el puerto que el infra.port del Component indica por defecto para la aplicación, que su Recipe de Compose publica en la dirección de loopback del host, 127.0.0.1, bajo el comentario que dice que solo es accesible desde esta máquina, por cualquier proceso que se ejecute en ella, y que eliminar la línea mantiene el servicio como interno; un segundo grafo toma el siguiente puerto libre. El almacén de datos y el modelo también tienen entradas, por lo que la Release los coloca junto con los grafos. Un comentario encima del primer grafo de la aplicación indica el entorno que declara su configuración, como describe El entorno que indica una configuración. Como toda Release generada como borrador, escribe metadata.environment como development y, sin destino, un spec.manifest vacío que la importación señala como pendiente; dado un destino, la importación genera el Manifest como borrador, como describe Qué añade un destino.

La aplicación Python que importan las pruebas de este importador, que declara dos grafos, un checkpointer que no nombra ningún backend, un almacén de memoria y un env escrito como objeto, se genera como borrador, sin ningún ajuste, como se muestra a continuación; importada como su directorio, support_desk — que lleva, como aquí, el nombre del paquete en el que se definen sus grafos —, con dos grafos cuyos id difieren, recibe el nombre de ese directorio:

aggregate.yaml
# LangGraph configurations read:
# - langgraph.json
# Not read: the application's code, which defines each graph; it runs in the image the Release names for each graph.
# Not carried, since they configure the server image langgraph build builds, and the image the Release names is the application's own: dependencies, python_version.
# Not carried, since core/ai-agent/langgraph takes no value for them: http.
# The store configures the memory store, which LangGraph keeps in the PostgreSQL database its server uses; not carried, since core/ai-agent/langgraph takes no value for it: index, ttl.
# Not carried, since core/ai-agent/langgraph takes no value for them: checkpointer.ttl.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support-desk
version: 0.1.0
description: Draft Aggregate imported from a source in the langgraph format.
spec:
components:
triage:
type: core/ai-agent/langgraph
values:
graph_entrypoint: "./src/support_desk/triage.py:make_graph"
description: "Routes an incoming ticket to the {team} that owns it."
uses:
checkpointer_db:
postgres:
target: postgres
# For the compose target only, uncomment the lines below, which declare credential on postgres: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: POSTGRES_PASSWORD
model:
model:
target: model
# For the compose target only, uncomment the lines below, ...
support:
type: core/ai-agent/langgraph
...
# The database the configuration's checkpointer keeps each graph's state in, PostgreSQL.
postgres:
type: core/datastore/postgres
# For the compose target only, uncomment the lines below, ...
# The model every graph calls, which the configuration does not name.
model:
type: core/ai-model/openai
values:
# Left for the author, since the configuration names no model: values.model, the name of the model core/ai-model/openai serves.
model: ""
release.yaml
spec:
aggregate: imported/support-desk
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# Each graph's image is the application's own, not the server image langgraph build builds: its code, with LangGraph installed.
# It is handed, for its code to read, the graph to run as LANGGRAPH_GRAPH_ENTRYPOINT, the model's name as OPENAI_MODEL, the checkpointer store's host and port as LANGGRAPH_CHECKPOINTER_HOST and LANGGRAPH_CHECKPOINTER_PORT, its user and database, where the store publishes them, as LANGGRAPH_CHECKPOINTER_USER and LANGGRAPH_CHECKPOINTER_DATABASE, and a password attached on the checkpointer_db connection as LANGGRAPH_CHECKPOINTER_PASSWORD.
# It is also handed the model's address as OPENAI_BASE_URL and a key attached on the model connection as OPENAI_API_KEY, which the OpenAI client library reads, and recursion_limit as LANGGRAPH_DEFAULT_RECURSION_LIMIT, which LangGraph reads.
# An inject: block on the graph's own instance, through an entry reading graph_entrypoint alone, replaces LANGGRAPH_GRAPH_ENTRYPOINT with the name it writes; one on the model connection replaces OPENAI_MODEL, and one on the checkpointer_db connection the store's host, port, user and database, with the names it writes.
# The environment langgraph.json states for its application, for the Release to carry where core/ai-agent/langgraph takes it for each of its graphs:
# SUPPORT_QUEUE: "..."
# OPENAI_API_KEY: "..."
# MAX_TICKETS: "25"
triage:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application
image: ""
uses:
checkpointer_db:
postgres:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential triage presents to postgres on its checkpointer_db connection, the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${POSTGRES_PASSWORD}"
model:
model:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential triage presents to model on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
...
postgres:
features:
password:
type: core/secret-value
infra:
# Attached by reference, never as a value: the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${POSTGRES_PASSWORD}"
model: {}

La importación señala cuatro valores como pendientes: spec.manifest, la imagen de cada grafo y el nombre del modelo. Una vez respondidos, cada grafo se renderiza ejecutando la imagen que indiques en tu respuesta, y recibe la dirección de su almacén de datos como LANGGRAPH_CHECKPOINTER_HOST y LANGGRAPH_CHECKPOINTER_PORT, el usuario y la base de datos que publica el almacén de datos como LANGGRAPH_CHECKPOINTER_USER y LANGGRAPH_CHECKPOINTER_DATABASE — PostgreSQL publica ambos, y con un almacén de datos que no publica ninguno no se renderiza ninguna de las dos variables —, el endpoint y el nombre del modelo como OPENAI_BASE_URL y OPENAI_MODEL, la clave que entrega su credencial del modelo como OPENAI_API_KEY, su ruta de importación como LANGGRAPH_GRAPH_ENTRYPOINT y su límite de pasos como LANGGRAPH_DEFAULT_RECURSION_LIMIT. La credencial adjunta a su conexión checkpointer_db le proporciona también la contraseña del almacén de datos como LANGGRAPH_CHECKPOINTER_PASSWORD.

El entorno que indica una configuración

Cada variable que nombra el env de la configuración es una entrada que debe proporcionar la Release, y ninguna se genera como borrador como ranura de credencial: LangGraph no marca ninguna variable como secreto, y el nombre de una variable no se lee por lo que significa. core/ai-agent/langgraph no acepta ningún valor para el entorno, así que la Release lo indica en un comentario encima del primer grafo de la aplicación.

  • Un env escrito como objeto forma parte de la configuración, así que sus valores se trasladan tal como están escritos a ese comentario, en el orden en que la configuración los escribe. Cada valor que contiene algo puede llevar una credencial, que LangGraph no marca como credencial: de forma predeterminada, cada uno se traslada tal como está escrito y se nombra en una advertencia credential-carried por su configuración y su variable, como env.OPENAI_API_KEY, nunca por su valor. Con el ajuste empty_credentials en all, cada uno se escribe sin valor y se informa de él con credential-emptied; en marked cada uno se traslada, ya que LangGraph no marca ninguno.
  • Un env que nombra un archivo nombra un archivo al que la configuración solo apunta, que suele contener secretos locales. Se lee solo donde el with.sources del importador lo entrega. El comentario nombra cada variable que nombra el archivo, dejada para que la Release la proporcione, y no se lee ningún valor del archivo: ninguno llega a un borrador, a una decisión ni a un diagnóstico, diga lo que diga el ajuste. Un valor entrecomillado a lo largo de varias líneas es un único valor, así que una línea dentro de él nunca se toma por una variable, y una línea que no nombra ninguna variable se nombra por su número. Donde a la importación no se le entregó el archivo — siempre así para un directorio, que nunca entrega uno — el Aggregate lo nombra como no entregado, con cómo entregarlo, y sus variables se dejan para la Release.

Los ajustes que lee

El importador LangGraph lee target_namespace, empty_credentials y render_mode, tal como los describe Configuración, y ningún otro ajuste.

El importador Google ADK

importer/google-adk lee los agentes que una aplicación creada sobre el Agent Development Kit (ADK) de Google declara en sus archivos Agent Config — root_agent.yaml y las configuraciones que nombran sus subagentes — y genera como borrador un Aggregate que contiene una instancia del agente ADK de la biblioteca estándar, core/ai-agent/google-adk, por árbol de agentes, conectada al modelo que nombra el árbol cuando ADK envía sus solicitudes a la Gemini API, y una Release junto a él. Lee esas configuraciones, y nunca el código de la aplicación.

ADK indica que su función Agent Config es experimental. El modelo de un agente es por defecto un modelo Gemini; ADK sirve por nombre los modelos de algunos otros proveedores mediante clases propias, como claude-sonnet-4-5 y gpt-4o, y otros mediante una cadena de modelo de LiteLLM. El socket model del agente admite solo la Gemini API, por lo que el importador conecta un modelo que ADK envía a la Gemini API y te deja a ti cualquier otro, como describe En qué se convierte un árbol de agentes.

Qué lee

adk create --type=config de ADK escribe root_agent.yaml, la configuración del agente raíz de una aplicación, y un archivo de entorno junto a ella. Una configuración declara un agente:

  • name, description y agent_class — la clase como la que ADK construye el agente, LlmAgent donde no nombra ninguna;
  • model — el modelo que pide el agente — o model_code, una referencia a código que construye su modelo;
  • tools — cada herramienta por name, con los args que su configuración le entrega;
  • generate_content_config — las opciones de las solicitudes al modelo del agente, entre ellas http_options;
  • sub_agents — cada uno un config_path, la ruta de otra configuración desde el directorio de la configuración que lo nombra, o code, un agente que construye el código de la aplicación.

Un directorio se entrega al importador como sus archivos root_agent.yaml y ningún otro archivo, y una configuración importada por sí sola se lee como raíz, sea cual sea su nombre. El árbol de cada raíz se lee empezando por la raíz, los subagentes de cada agente en el orden en que los enumera. La configuración que una entrada de sub_agents nombra por config_path se lee solo donde el with.sources del importador la entrega, emparejada por el último segmento de la ruta; una que no se entregó a la importación se nombra en el Aggregate y en su decisión como no entregada, con cómo entregarla, y su agente no se lee:

plugins:
importer:
- uri: importer/google-adk:<version>
with:
sources:
- ./my_agent/code_tutor_agent.yaml
- ./my_agent/math_tutor_agent.yaml

Un config_path absoluto, o que sale del directorio de la configuración que lo nombra, no se lee, ya que ADK también lo rechaza. Un archivo que with.sources entrega y que ninguna configuración nombra se nombra en un comentario como no leído, y no se lee nada de él; un archivo que entrega se lee solo como una configuración que nombra el árbol de una raíz, así que una importación que no contiene ningún root_agent.yaml ni ningún archivo importado por sí solo no lee ningún árbol e informa de cada archivo bajo no-nodes. El código de la aplicación — las herramientas, callbacks, esquemas y agentes que una configuración nombra por su código — y el archivo de entorno nunca se entregan, y el importador no lee ninguno de los dos: la aplicación carga sus configuraciones ella misma, desde la imagen que nombra la Release. Un directorio puede contener varias aplicaciones, cada una leída desde su propio root_agent.yaml.

Los demás miembros de una configuración — entre ellos la instruction de un agente — los lee la aplicación desde su propia configuración, así que el borrador no traslada ninguno de ellos.

En qué se convierte un árbol de agentes

ADK sirve una aplicación desde su agente raíz, con cada agente que nombran sus configuraciones construido dentro de ella, y core/ai-agent/google-adk ejecuta una de esas aplicaciones. Así, aggregate.yaml, un Aggregate de borrador que lleva el nombre del agente raíz, como describe Cómo se nombra un borrador, contiene, por árbol de agentes y con el nombre de su agente raíz como clave, una instancia de core/ai-agent/google-adk con:

  • description, la descripción del agente raíz, donde su configuración da una;
  • su conexión model, conectada al modelo que nombra el árbol, cuando ADK envía sus solicitudes a la Gemini API.

Unos comentarios encima de ella nombran los demás agentes del árbol, que no se convierten en una instancia propia; cada subagente que no se lee, y por qué — construido por el código de la aplicación, una configuración que no se entregó a la importación, o una que ADK rechaza; las herramientas que nombran los agentes del árbol, las que incluye ADK y las que define el código de la aplicación; los agentes cuya clase — LoopAgent, ParallelAgent o SequentialAgent — ADK declara obsoleta en favor de Workflow; y, donde el modelo del árbol está conectado, los modelos que piden otros agentes del árbol, cada uno con la familia a través de la cual ADK lo sirve. Se informa de cada uno en una decisión que no elige nada.

El primer agente del árbol, empezando por la raíz, que nombra un modelo o el código que construye uno decide el modelo de la instancia. Un modelo que nombra y cuyas solicitudes ADK envía a la Gemini API — un nombre de modelo que ADK sirve a través de su clase Gemini, como gemini-2.5-flash, salvo un nombre de recurso de Vertex AI, o uno que sirve a través de su clase Gemma — es una instancia de core/ai-model/gemini, que sirve ese modelo y lo tiene como clave, y los árboles que nombran un mismo modelo comparten una instancia. Donde el catálogo del workspace no contiene ningún core/ai-model/gemini, se genera uno como borrador, <target_namespace>/ai-model/gemini, que lleva la etiqueta model.aggrega.ai/api: gemini que selecciona el socket model del agente, y su decisión lo dice; una Recipe que publique su endpoint y su modelo queda para ti, como dice un comentario al principio de él. Un modelo que ADK sirve de cualquier otra forma — una cadena de modelo de LiteLLM como openai/gpt-4o, un nombre de recurso de Vertex AI, o un nombre como claude-sonnet-4-5 o gpt-4o, que ADK sirve a través de Anthropic o de OpenAI — no se conecta a nada: el socket model del agente acepta un modelo Gemini, y el agente no lee ningún nombre de modelo de su entorno, así que eres tú quien conecta ahí un modelo Gemini y nombra ese modelo en la configuración del agente. El comentario encima de la instancia y la decisión del agente raíz nombran el modelo y la familia a través de la cual ADK lo sirve. Un modelo que construye el código de la aplicación, o un árbol que no nombra ninguno — ADK usa entonces su modelo predeterminado — tampoco se conecta a nada, y un comentario encima de la instancia dice por qué. Siempre que el modelo no esté conectado a nada, la compilación se detiene nombrando el socket model hasta que se conecte uno. De los modelos que piden otros agentes de un árbol, uno cuyas solicitudes ADK envía a la Gemini API no necesita ninguna conexión propia: el cliente Gemini de ADK envía sus solicitudes con la clave que entrega la conexión de la instancia. Si la aplicación llega a Gemini a través de la Gemini API o a través de Vertex AI lo elige su entorno, que la importación no lee; el socket model del agente solo admite la Gemini API.

Las pruebas del importador también importan un agente raíz aislado que nombra openai/gpt-4o, cuya instancia se genera como borrador así:

spec:
components:
# The agent tree of root_agent.yaml, served from its root agent routed_agent.
# The model connection is left for the author, since the model openai/gpt-4o, which routed_agent names, is one ADK serves through LiteLLM, not through the Gemini API, while core/ai-agent/google-adk takes a Gemini model on its model socket and reads no model name from its environment, so the author wires a Gemini model there and names that model in routed_agent's configuration; the build halts naming the socket until one is wired.
routed-agent:
type: core/ai-agent/google-adk
values:
description: "Answers questions with a model another provider serves."

release.yaml, junto a él, es una Release de borrador con el mismo nombre que nombra ese Aggregate. La entrada de cada instancia escribe su infra.image — la imagen que ejecuta la aplicación creada sobre ADK, que contiene sus configuraciones — vacío, bajo un comentario que dice qué es, y la importación lo marca como pendiente. Con --target compose la entrada escribe además infra.published_port, 8000, el puerto en el que escucha la aplicación, que su Recipe de Compose publica en la dirección de loopback del host, 127.0.0.1, bajo el comentario que dice que solo es accesible desde esta máquina, por cualquier proceso que se ejecute en ella, y que borrar la línea mantiene el servicio interno; un segundo árbol toma el siguiente puerto libre. Donde su modelo está conectado, la entrada vincula la credencial que la instancia presenta a ese modelo bajo credential en su conexión model, por referencia y nunca como valor: ninguna configuración nombra una variable para ella, así que se lee de GOOGLE_API_KEY, la variable de la que las bibliotecas cliente de la Gemini API de Google leen su clave, como referencia ${…} en todos los destinos salvo helm, y en helm como el nombre de un Kubernetes Secret, escrito vacío para que la importación lo marque como pendiente; en compose, la conexión model la declara con esa clave. Un modelo conectado también tiene una entrada, que no contiene infraestructura, por lo que la Release lo coloca junto con la instancia. Los valores que las configuraciones del árbol entregan a sus herramientas y a sus solicitudes al modelo se escriben en un comentario encima de la entrada, como describe Valores de credenciales que contiene una configuración. Como toda Release de borrador, escribe metadata.environment como development y, sin destino, un spec.manifest vacío que la importación marca como pendiente; con un destino, la importación genera el Manifest como borrador, como describe Qué añade un destino.

La aplicación que importan las pruebas de este importador, un agente raíz que nombra las configuraciones de dos subagentes y uno construido por código, importada como su directorio con las dos configuraciones nombradas bajo with.sources, se genera como borrador, sin ningún ajuste, con el nombre de su agente raíz, tutor_root, así:

aggregate.yaml
# Google ADK agent configurations read:
# - root_agent.yaml
# - code_tutor_agent.yaml
# - math_tutor_agent.yaml
# Not read: the application's code, which defines the tools, callbacks and agents a configuration names by their code, nor the environment file ADK's scaffold writes beside root_agent.yaml; the application runs in the image the Release names for each instance, and loads its configurations itself.
# ADK states that its Agent Config is experimental. An agent's model is a Gemini model by default; ADK serves some other providers' models by name through classes of its own, such as claude-sonnet-4-5 and gpt-4o, and others through a LiteLLM model string.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/tutor-root
version: 0.1.0
description: Draft Aggregate imported from a source in the google-adk format.
spec:
components:
# The agent tree of root_agent.yaml, served from its root agent tutor_root.
# Sub-agents ADK builds inside this application, drafted as no instance of their own: code_tutor_agent, math_tutor_agent.
# Not read: a sub-agent of tutor_root, which is built by the application's code at tutor_agents.review_agent, which the import does not read.
# Tools ADK ships, which run inside the application, drafted as no Component: google_search.
# Tools the application's code defines, drafted as no Component: tutor_tools.make_snippet_runner.
# Models other agents of the tree ask for, ...: gemini-pro-latest (math_tutor_agent, served through Gemini).
tutor-root:
type: core/ai-agent/google-adk
values:
description: "Learning assistant that tutors {{`{{`}} students }} in code and math."
uses:
model:
gemini-flash-latest:
target: gemini-flash-latest
# For the compose target only, uncomment the lines below, which declare credential on gemini-flash-latest: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: GOOGLE_API_KEY
# The model gemini-flash-latest.
gemini-flash-latest:
type: core/ai-model/gemini
values:
model: "gemini-flash-latest"

Un texto que el borrador copia de una configuración al Aggregate, en un valor o en un comentario, escribe cada {{ como {{`{{`}}, una acción cuyo resultado son las dos llaves, de modo que la descripción, y un nombre que contiene dos llaves en un comentario, se vuelven a leer tal como están escritos una vez evaluado el Aggregate.

release.yaml
spec:
aggregate: imported/tutor-root
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# The configurations also hand these values to their tools and their model requests, which the application reads from its own configurations, written here for review:
# code_tutor_agent tools.tutor_tools.make_snippet_runner.args.api_key: "..."
# code_tutor_agent tools.tutor_tools.make_snippet_runner.args.sandbox: "python3.12"
# code_tutor_agent tools.tutor_tools.make_snippet_runner.args.timeout_seconds: 20
# math_tutor_agent generate_content_config.http_options.headers: "..."
# math_tutor_agent generate_content_config.http_options.timeout: 30000
tutor-root:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on ADK, holding its configurations
image: ""
uses:
model:
gemini-flash-latest:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential tutor-root presents to gemini-flash-latest on its model connection (the source names no variable for it, so it is read from the one Google's Gemini API's client libraries read the API key from), read from the variable GOOGLE_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${GOOGLE_API_KEY}"
gemini-flash-latest: {}

Una vez respondida la imagen, la instancia se renderiza ejecutándola y recibe la credencial como GOOGLE_API_KEY, que el cliente Gemini de ADK envía a la Gemini API, y el modelo como un Service que llega a la dirección de la Gemini API.

Valores de credenciales que contiene una configuración

Una configuración puede entregar una clave a una herramienta, en sus args, o a sus solicitudes al modelo, en las http_options de su generate_content_config — sus encabezados, su dirección, los argumentos de su cliente. Cada miembro de los args de una herramienta y de esas opciones HTTP se escribe en el comentario encima de la entrada de la instancia en la Release, tal como lo escribe su configuración, y cada uno que es un texto, un objeto o una lista puede llevar una credencial, que ADK no marca como credencial: de forma predeterminada, cada uno se traslada tal como está escrito y se nombra en una advertencia credential-carried por su agente y su campo, como tools.tutor_tools.make_snippet_runner.args.api_key, nunca por su valor. Con el ajuste empty_credentials en all, cada uno se escribe sin valor y se informa de él con credential-emptied; en marked cada uno se traslada, ya que ADK no marca ninguno. Un número o un booleano no lleva ninguna clave, y se escribe tal como lo escribe la configuración. ADK no expande ninguna referencia a variables en una configuración, así que cada valor se lee tal como está escrito; el archivo de entorno, que suele contener la clave que lee el cliente Gemini de ADK, nunca se lee, diga lo que diga el ajuste.

Los ajustes que lee

El importador Google ADK lee target_namespace, empty_credentials y render_mode, tal como los describe Configuración, y ningún otro ajuste.

El importador Agent Framework

importer/agent-framework lee un agente declarativo de Microsoft Agent Framework — el documento YAML de tipo Prompt desde el que una aplicación construida sobre Agent Framework carga un agente — y genera como borrador un Aggregate que contiene una instancia del agente Agent Framework de la biblioteca estándar, core/ai-agent/agent-framework, conectada al modelo de OpenAI que nombra, y una Release junto a él. Lee agentes declarativos, y nunca el código de la aplicación. Agent Framework publica sus paquetes de agentes declarativos como versiones preliminares.

Qué lee

Un agente declarativo declara:

  • name, displayName y description, sus instructions y los esquemas de su entrada y de su salida;
  • model — el id del modelo, el provider que lo sirve, la API a la que su cliente envía solicitudes (apiType), las options de sus solicitudes, y su connection: una conexión key que presenta una clave, escrita bajo key o apiKey, a un endpoint; una conexión remote que alcanza un endpoint; una conexión reference que nombra una que la aplicación resuelve; o una anonymous que no presenta nada;
  • tools — cada una de un kind: una function cuyo código vincula la aplicación, una herramienta web_search, file_search o code_interpreter que ejecuta el proveedor del modelo, o un servidor mcp alcanzado en su url, con el approvalMode que siguen sus llamadas, los allowedTools del servidor que el agente puede llamar y una connection propia.

Un miembro escrito como =Env.NAME lo lee Agent Framework de la variable de entorno NAME solo donde la aplicación carga el agente declarativo con AgentFactory(safe_mode=False), el propio ajuste de seguridad de Agent Framework, y hay un entorno de ejecución de .NET presente, y en otro caso se toma como el texto de la expresión tal como está escrito; cualquier otro miembro que empiece por = es una expresión que calcula la aplicación. El importador no lee ninguno de los dos: nombra una referencia por su variable, y una expresión como tal.

Un archivo importado por sí solo se lee como un agente declarativo, se llame como se llame, y cada archivo que pasa el with.sources del importador se lee como otro, así que una importación genera varios como borrador:

plugins:
importer:
- uri: importer/agent-framework:<version>
with:
sources:
- ./agents/triage.yaml
- ./agents/writer.yaml

Nunca se pasa un directorio al importador: su firma no nombra ningún archivo, así que una importación de un directorio que no nombra ningún formato no lo reconoce, y una que nombra --format agent-framework se rechaza con An importer that declares no file patterns is handed a directory (A un importer que no declara patrones de archivo se le entrega un directorio) antes de que se abra ninguno de sus archivos. En su lugar, importa cada agente declarativo como un archivo propio. Un origen a partir del cual Agent Framework no construye ningún agente de prompt — uno cuyo kind no es ni Prompt, en cualquier combinación de mayúsculas y minúsculas, ni Agent — se informa con no-nodes. El código de la aplicación — el programa que carga cada agente declarativo y las funciones que vincula a sus herramientas — nunca está entre los orígenes: la aplicación carga ella misma sus agentes declarativos, desde la imagen que nombra la Release.

En qué se convierte un agente declarativo

aggregate.yaml, un Aggregate de borrador que lleva el nombre del agente, como describe Cómo se nombra un borrador, contiene, por agente declarativo y con su nombre como clave, una instancia de core/ai-agent/agent-framework con:

  • display_name y description, el displayName y la description del agente, donde los indica;
  • su conexión model, conectada al modelo que nombra, donde ese modelo está conectado.

Sus instrucciones, los esquemas de su entrada y de su salida, su plantilla, sus metadatos y las opciones de sus solicitudes al modelo los lee la aplicación del agente declarativo, y se nombran en un comentario encima de la instancia. Una herramienta de función, una herramienta que ejecuta el proveedor del modelo y una herramienta de cualquier otro tipo también se nombran en un comentario, y se informa de ellas en una decisión que no elige nada.

Un modelo cuyo provider es OpenAI y que nombra un id es una instancia de core/ai-model/openai, que sirve ese id y lo tiene como clave: el socket model del agente admite un modelo que sirve la API de OpenAI, y el entorno de ejecución entrega la dirección, el nombre y la clave de ese modelo en las variables que leen los clientes de OpenAI de Agent Framework. Los agentes que nombran un mismo modelo en una misma dirección comparten una instancia. Donde el catálogo del workspace no contiene ningún core/ai-model/openai, se genera uno como borrador, <target_namespace>/ai-model/openai, que lleva la etiqueta model.aggrega.ai/api: openai que selecciona el socket model del agente, y su decisión lo dice; una Recipe que publique su endpoint y su modelo queda para ti, como dice un comentario al principio de él. Un id escrito como referencia deja para ti el values.model del modelo, con un comentario encima del modelo que nombra la variable; la compilación se detiene nombrándolo hasta que se define. Una conexión anonymous se escribe como el unauthenticated: true de la conexión. Un modelo de cualquier otro proveedor — AzureOpenAI, Anthropic —, uno que nombra su proveedor como referencia o no nombra ninguno, en cuyo caso Agent Framework usa el proveedor predeterminado que define la aplicación, y uno que no nombra ningún id no se conectan a nada, y un comentario encima de la instancia dice por qué; la compilación se detiene nombrando el socket model hasta que se conecte uno.

Una herramienta de tipo mcp no se genera como borrador ni como Component ni como conexión: Agent Framework envía el servidor al proveedor del modelo como herramienta alojada, y es el proveedor, no la aplicación, quien lo alcanza en su url, que por tanto debe ser accesible desde el proveedor, de modo que nada de lo que despliega el borrador lo alcanza. Un comentario encima de la instancia del agente nombra el servidor, lo indica, y nombra la descripción, el approvalMode y los allowedTools que el agente declarativo indica para él; su url se escribe, completa, en el comentario encima de la entrada del agente en la Release, y su decisión no elige nada.

release.yaml, junto a él, es una Release de borrador con el mismo nombre que nombra ese Aggregate. La entrada del agente escribe su infra.image — la imagen que ejecuta la aplicación construida sobre Agent Framework, que contiene su agente declarativo — vacío, bajo un comentario que dice qué es, y la importación lo marca como pendiente. Con --target compose, la entrada también escribe infra.published_port, 8000, el puerto que el infra.port del Component indica por defecto para la aplicación, que su Recipe de Compose publica en la dirección de loopback del host, 127.0.0.1, bajo el comentario que dice que solo es accesible desde esta máquina, por cualquier proceso que se ejecute en ella, y que eliminar la línea mantiene el servicio como interno. Donde su modelo está conectado, la entrada vincula la credencial que el agente presenta a ese modelo bajo credential en su conexión model, por referencia y nunca como valor: se lee de la variable que el agente declarativo nombra para su clave, escrita =Env.NAME, y en otro caso de OPENAI_API_KEY, la variable de la que las bibliotecas cliente de OpenAI leen su clave; como referencia ${…} en todos los destinos salvo helm, y en helm como el nombre de un Kubernetes Secret, escrito vacío para que la importación lo marque como pendiente; en compose, la conexión model la declara con esa clave. Los valores que el agente declarativo indica para su modelo y sus servidores MCP — las claves y la url de cada servidor — se escriben en un comentario encima de la entrada del agente, como describe Valores de credenciales que contiene un agente declarativo. Cada modelo conectado tiene una entrada, por lo que la Release lo coloca junto con el agente. El endpoint que indica su conexión se escribe como el infra.endpoint del modelo, y uno escrito como referencia se nombra junto a su entrada, y se usa la dirección propia del Component hasta que se define; una conexión que no indica ningún endpoint deja la entrada sin infraestructura, y se mantiene la dirección propia del Component. Como toda Release de borrador, escribe metadata.environment como development y, sin destino, un spec.manifest vacío que la importación marca como pendiente; con un destino, la importación genera el Manifest como borrador, como describe Qué añade un destino.

El agente declarativo que importan las pruebas de este importador, del proveedor OpenAI con una conexión por clave, un servidor MCP que presenta una clave propia, una herramienta de función y una búsqueda web, importado como un archivo propio, se genera como borrador, sin ningún ajuste, con su name, LearnAgent, así:

aggregate.yaml
# Not read: the application's code, which loads each declarative agent and binds the functions of its function tools; the application runs in the image the Release names for each instance, and loads its declarative agents itself.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/learnagent
version: 0.1.0
description: Draft Aggregate imported from a source in the agent-framework format.
spec:
components:
# The declarative agent LearnAgent.
# Read by the application from the declarative agent, and taken by no key of core/ai-agent/agent-framework: instructions, outputSchema, the options of its model requests (temperature, topP).
# Function tools, whose code the application binds, drafted as no Component: GetRelease.
# Tools the model's provider runs, drafted as no Component: search.
# The MCP server microsoft_learn, drafted as no Component and no connection, since Agent Framework sends it to the model's provider as a hosted tool, and the provider, not the application, reaches it at its url, which must therefore be reachable from the provider; its url is written above learnagent's entry in the Release.
# Stated by the declarative agent for microsoft_learn: its description, "Get information from Microsoft Learn."; its approval mode, never; the tools of the server it allows, microsoft_docs_search, microsoft_docs_fetch.
learnagent:
type: core/ai-agent/agent-framework
values:
display_name: "Learn Assistant"
description: "Answers questions about {{`{{`}} product }} from the Microsoft Learn content."
uses:
model:
gpt-4-1-mini:
target: gpt-4-1-mini
# For the compose target only, uncomment the lines below, which declare credential on gpt-4-1-mini: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
# features:
# credential:
# type: core/secret-value
# values:
# key: OPENAI_API_KEY
# The model gpt-4.1-mini, which LearnAgent names with the OpenAI provider.
gpt-4-1-mini:
type: core/ai-model/openai
values:
model: "gpt-4.1-mini"

Un texto que el borrador copia de un agente declarativo al Aggregate, en un valor o en un comentario, escribe cada {{ como {{`{{`}}, de modo que se relee tal como está escrito una vez evaluado el Aggregate.

release.yaml
spec:
aggregate: imported/learnagent
# manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here.
manifest: ""
components:
# The declarative agent also states these values for its model and its MCP servers, written here for review:
# - model.connection.key: "..."
# - tools.microsoft_learn.url: "https://learn.microsoft.com/api/mcp?session=..."
# - tools.microsoft_learn.connection.key: "..."
learnagent:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on Agent Framework, holding its declarative agent
image: ""
uses:
model:
gpt-4-1-mini:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential learnagent presents to gpt-4-1-mini on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
gpt-4-1-mini:
infra:
endpoint: "https://llm-gateway.example.com/v1"

Una vez respondida la imagen, el agente se renderiza ejecutándola, y recibe el endpoint del modelo como OPENAI_BASE_URL, su id como OPENAI_MODEL y su credencial como OPENAI_API_KEY, y el modelo se renderiza como un Service que alcanza su host. Ninguna variable lleva la dirección del servidor MCP: lo alcanza el proveedor del modelo, no la aplicación.

Valores de credenciales que contiene un agente declarativo

La clave que presenta una conexión key — escrita bajo key o apiKey, en el modelo o en un servidor MCP — es el único miembro que Agent Framework marca como credencial: es el único valor que su cargador oculta en lo que registra. Cada clave que un agente declarativo escribe como literal se escribe en el comentario encima de la entrada del agente en la Release, tal como la escribe el agente declarativo, y de forma predeterminada se traslada tal como está escrita y se nombra en una advertencia credential-carried por su agente y su campo, como model.connection.key, nunca por su valor. La url de un servidor MCP, escrita completa en el mismo comentario y nombrada por su campo — tools.microsoft_learn.url of node LearnAgent is carried as written —, es un miembro de la configuración de un servidor MCP, y el endpoint de un modelo conectado es una entrada que Agent Framework marca como no credencial. Con el ajuste empty_credentials en marked, las claves y las url de los servidores MCP se escriben sin valor — el comentario nombra cada una solo por su campo — y se informa de ellas con credential-emptied, y el endpoint del modelo se traslada; en all, también se omite el infra.endpoint del modelo, que se nombra en el comentario encima de su entrada como pendiente para la Release, y se usa la dirección predeterminada del Component hasta que se define. Un valor escrito como =Env.NAME no contiene ninguno, así que se nombra por su variable, junto con la condición en la que Agent Framework lo lee del entorno — model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads … — diga lo que diga el ajuste, y no se informa de él con ninguno de los dos códigos; un valor escrito como cualquier otra expresión se nombra como tal y nunca se escribe.

Los ajustes que lee

El importador Agent Framework lee target_namespace, empty_credentials y render_mode, tal como los describe Configuración, y ningún otro ajuste.

Qué añade un destino

Una importación a la que se le da un destino — --target en aggrega import, o target en la herramienta de importación del asistente y en el método aggrega/import de la sesión, que nombra una capacidad de proveedor como compose o helm — entrega ese destino al importador, de modo que el importador genera los borradores para él: cada secreto en la forma que lee ese destino, y las líneas que solo ese destino necesita, escritas activas, mientras que las líneas que solo necesita otro destino se omiten. En compose esas líneas incluyen infra.published_port dondequiera que el importador publique un servicio en la dirección de loopback del host, como dice la sección de cada importador; un puerto que elige el importador nunca toma un número que toma otro puerto de la Release. La importación genera después el Manifest como borrador junto a lo que haya generado el importador, sea cual sea el importador que se ejecutó: manifest.yaml, junto a la Release de borrador y con su mismo nombre y versión — o, donde el importador no generó ninguna Release como borrador, junto al Aggregate de borrador y con el nombre y la versión de este.

Para cada tipo de componente y cada tipo de feature que necesitan los borradores — en los componentes del Aggregate de borrador, sus conexiones y sus subsistemas, en los Aggregates del catálogo que compone, como core/dify, y en las vinculaciones de la Release de borrador —, el Manifest mapea el tipo a la Recipe, o para un tipo de feature a la feature recipe, de esa capacidad que el catálogo del workspace ofrece para él: la que hay, contando como una varias versiones de una misma; o, donde hay varias de nombres distintos, la que lleva el nombre del propio tipo, como helm/postgres para core/datastore/postgres. Un tipo que no tiene ninguna, o que tiene varias de las que ninguna lleva ese nombre, se deja sin mapear, una advertencia lo nombra e indica por qué, y una compilación de los borradores se detiene nombrando cada instancia o vinculación suya hasta que lo mapees.

Donde solo el importador sabe cuál de varias Recipes se aplica, genera él mismo el Manifest como borrador — el importador MCP mapea cada servidor, por su clave, a la realización de cómo se ejecuta el servidor, y un importador que vincula un secreto por nombre mapea core/referenced-secret a helm/k8s-existing-secret — y la importación lo completa: cada mapeo escrito por el importador que el catálogo ofrece para ese tipo y esa capacidad se conserva, cualquier otro se descarta con una advertencia, y los tipos que deja se mapean como se indica arriba.

El spec.manifest de la Release de borrador, escrito vacío sin destino, se establece en el nombre del Manifest, el comentario que tiene encima se elimina, y nada más cambia en la Release. aggrega import lo describe por completo.

Configuración

A un importador se le pasan los ajustes de la entrada plugins.importer que lo vincula, bajo with.settings, como describe Qué importador convierte una fuente en borradores. Sin entrada, o sin ajustes, cada ajuste toma su valor predeterminado.

plugins:
importer:
- uri: importer/langflow:<version>
with:
settings:
target_namespace: payments
reuse_mode: hints-only
OpciónPredeterminadoQué hace
target_namespaceimportedEl espacio de nombres bajo el que se nombran las entidades generadas como borrador: <target_namespace>/<category>/<name> para un Component y <target_namespace>/<name> para el Aggregate y la Release, donde <name> es el nombre propio de la fuente, si no, el nombre de su directorio o el nombre de su archivo sin la extensión, y si no, flow, escrito en minúsculas y con cada secuencia de caracteres distintos de letras y dígitos ASCII convertida en un solo guion, como describe Cómo se nombra un borrador.
reuse_modeauto-apply-above-thresholdauto-apply-above-threshold referencia el Component del catálogo que mejor coincide para un nodo al que el borrador da un Component propio cuya coincidencia está en el nivel alto y obtiene una puntuación igual o superior a reuse_threshold, y genera como borrador todos los demás. hints-only genera como borrador cada uno de esos nodos y no referencia ningún Component del catálogo, registrando una coincidencia fuerte como sugerencia. Cualquier otro valor se lee como hints-only.
reuse_threshold0.85La puntuación igual o superior a la cual auto-apply-above-threshold referencia un Component. Se lee solo en ese modo; 0 se lee como el valor predeterminado.
emit_hintstrueSi el archivo de un Component generado como borrador empieza con un comentario que nombra el Component del catálogo al que se parece, para una coincidencia de nivel alto o medio. El Aggregate de borrador lleva el mismo comentario encima de la entrada de ese nodo, y encima de una entrada referenciada uno que nombra el siguiente mejor candidato por el que podría cambiarse, o que dice que ninguno obtuvo una puntuación superior a cero. false omite los comentarios.
render_modehumanhuman escribe los borradores descritos arriba. llm no escribe ningún borrador, y escribe en su lugar el registro completo de decisiones — cada nodo, los candidatos puntuados y la elección hecha — como un único documento, import-decisions.json, para que lo lea otra herramienta. Cualquier otro valor se lee como human.
mapping_overridesningunoMapeos superpuestos a la tabla propia del importador, con el formato y después el tipo de nodo como clave — para el importador Compose, el repositorio de la imagen. Cada entrada nombra el component al que se mapea un nodo de ese tipo y, opcionalmente, su category, los traits — etiquetas y sus valores — que lleva un Component coincidente, y una palabra vendor que lleva su nombre. Una entrada para un tipo de nodo que la tabla ya mapea ocupa el lugar de la fila de la tabla. Solo se leen las entradas bajo el formato que se importa.
layoutplatformplatform genera como borrador la plataforma que ejecuta el flujo, llevando el flujo, con cada una de sus partes como un Component propio conectado a la plataforma, como describe La plataforma que lleva el flujo. nodes genera como borrador cada nodo como un Component propio, como describe Nodo por nodo. Para el importador Dify, platform genera como borrador la instalación de Dify que lleva la aplicación, como describe En qué se convierte una aplicación. Cualquier otro valor genera el borrador como platform, y la importación advierte con unknown-layout.
empty_credentialsnoneQué valores de credenciales se escriben vacíos en el flujo que lleva la plataforma, como los enumera Valores de credenciales que contiene el flujo, en la Release que genera como borrador el importador MCP, como los enumera Valores de credenciales que contiene un servidor, en la Release que genera como borrador el importador Compose, como los enumera Valores de credenciales que contiene un servicio, en la aplicación que lleva el importador Dify, como los enumera Valores de credenciales que contiene una aplicación, en la Release que genera como borrador el importador CrewAI, como los enumera Valores de credenciales que contiene una declaración, en la Release que genera como borrador el importador LangGraph, como los enumera El entorno que indica una configuración, en la Release que genera como borrador el importador Google ADK, como los enumera Valores de credenciales que contiene una configuración, y en la Release que genera como borrador el importador Agent Framework, como los enumera Valores de credenciales que contiene un agente declarativo. none no escribe ninguno vacío: cada uno se traslada tal como está escrito y se nombra en una advertencia credential-carried. marked escribe vacío lo que un formato marca como credencial y cada miembro de la configuración de un servidor MCP. all escribe vacías también las entradas que un formato marca como no credencial pero que pueden llevar una — encabezados de solicitud, parámetros de consulta, una solicitud escrita como línea de comandos, una entrada con nombre de clave. Lo que el borrador escribe para que un nodo alcance su conexión se escribe diga lo que diga este ajuste. Cualquier otro valor detiene la importación, que no genera nada como borrador, con unknown-empty-credentials. Un borrador hecho nodo por nodo no lee ningún valor, y por tanto no lee este ajuste.
attach_egress_allowlistfalsetrue vincula la Feature core/egress-allowlist de la biblioteca estándar a cada instancia de plataforma que escribe el borrador, como egress-allowlist, sin definir nada de su infra, como describe Lo que el borrador deja para la Release. false no vincula nada. Un borrador que no escribe ninguna plataforma, con layout: nodes, y el borrador del importador Dify, cuya entrada para la instalación de Dify no acepta ninguna Feature, no vinculan nada diga lo que diga este ajuste, y con él en true la importación advierte con feature-not-attached. Cualquier valor que no sea un booleano se lee como false.

Un ajuste que un importador no conoce se ignora.

with:
settings:
mapping_overrides:
langflow:
AzureOpenAIModel:
component: acme/ai-model/azure-openai
category: ai-model
vendor: azure

Qué informa una importación

Cada importador core informa, como diagnósticos, de lo que no pudo hacer y de lo que hizo en nombre del autor. El comando imprime cada uno en el error estándar como <severity>: <message>, antes de la línea de cada nodo; el método aggrega/import de la sesión del editor y la herramienta import del asistente devuelven cada uno también con su code.

CódigoSeveridadSe informa cuando
parse-failedhaltLa fuente no se puede analizar: su analizador la rechaza, y el mensaje lleva el motivo del analizador.
no-nodeswarnLa fuente no lleva ningún nodo que el importador reconozca — para el importador MCP, ningún servidor, para el importador Compose, ningún servicio y ningún modelo, para el importador CrewAI, una crew que no declara ningún agente, para el importador LangGraph, una configuración que no declara ningún grafo, para el importador Google ADK, una configuración raíz que no declara ningún agente, o ninguno de los archivos que with.sources entrega a una importación contiene una configuración raíz, y para el importador Agent Framework, una fuente que no declara ningún agente de prompt.
unknown-layoutwarnlayout no es ni platform ni nodes; el flujo se genera como borrador como platform.
unknown-empty-credentialshaltempty_credentials contiene un valor distinto de none, marked o all, nombrado junto con el ajuste; la importación no genera nada como borrador.
platform-not-in-catalogwarnEl catálogo del workspace no contiene ningún Component con el nombre de la plataforma, así que no se conecta ninguna parte a ella; para el importador Dify, ningún core/ai-agent/dify, y core/dify se compone igualmente.
part-not-placedwarnUna parte del flujo no está conectada a ningún socket de la plataforma, con el motivo; permanece en el flujo.
socket-selector-unreadablewarnEl selector que declara un socket de la plataforma no se puede leer, así que no se conecta ninguna parte a él; una vez por cada socket.
credential-carriedwarnUn valor de credencial se traslada tal como está escrito en el flujo que lleva el borrador, o en la Release que genera como borrador el importador MCP, Compose, CrewAI, LangGraph, Google ADK o Agent Framework, nombrado por su nodo — o su servidor, servicio, agente o configuración — y su campo, nunca por su valor, junto con el valor de empty_credentials que lo escribe vacío.
credential-emptiedwarnUn valor de credencial se escribe vacío en el flujo que lleva el borrador, o en la Release que genera como borrador el importador MCP, Compose, CrewAI, LangGraph, Google ADK o Agent Framework, donde empty_credentials lo pide, nombrado por su nodo — o su servidor, servicio, agente o configuración — y su campo.
carriage-returns-rewrittenwarnLos retornos de carro del flujo se escriben como saltos de línea, indicando cuántos.
definition-respelledwarnLos valores del flujo se escriben en la grafía en que los leen las herramientas propias de la plataforma, con los mismos valores, indicando cuáles y por qué: los handles de las aristas de un flujo de Langflow, escritos como los escribe el editor de Langflow. Un valor que el borrador escribe para que el flujo llegue a una parte, o uno que puede llevar una credencial, nunca se reescribe — sigue siendo el del cableado, o el de empty_credentials — y la advertencia cuenta cada valor no reescrito.
definition-not-carriedwarnEl flujo no se lleva en values.flow_definition, o la aplicación del importador Dify en parameters.app_definition, con el motivo.
part-reads-connectionwarnCómo llega el flujo a una parte conectada a través de su conexión, o cómo llega una conexión, tal como está escrita, a un nodo que el borrador no conecta a ningún socket.
part-address-in-flowwarnEl flujo llega a una parte conectada por una vía distinta de su conexión, indicando cuál.
model-not-namedwarnvalues.model de una parte referenciada se deja al autor, con el motivo.
feature-attachedinfoattach_egress_allowlist vinculó core/egress-allowlist a una plataforma generada como borrador, con lo que de ella define la Release; una vez por cada instancia de plataforma.
feature-not-attachedwarnattach_egress_allowlist es true y el borrador no escribe ninguna plataforma, o compone la instalación de Dify, cuya entrada no acepta ninguna Feature, así que no se vincula nada.
part-configured-in-platformwarnUn nodo de una aplicación Dify nombra algo que Dify configura por sí mismo — un modelo y su proveedor, una herramienta, una base de conocimiento, una estrategia de agente, un plugin — así que el borrador no conecta ninguna parte para él.
dsl-version-newerwarnUna aplicación Dify está escrita en una versión del DSL más reciente que la que escribe la versión de Dify que core/ai-agent/dify ejecuta de forma predeterminada.

Una importación a la que se le da un destino informa, después de los diagnósticos del importador, de lo que encontró la generación del Manifest como borrador: un warn que nombra cada tipo de componente o de feature que el Manifest deja sin mapear y por qué, y un info donde la Release de borrador ya nombra un Manifest o ninguna Release de borrador lo referencia. Estos son de la propia importación y no de un importador, y no llevan ningún código; Qué añade un destino los describe. Toda importación informa después, también como propios, de un warn por cada valor que los borradores aún tienen pendiente, que nombra el archivo de borrador, la ruta de la clave y su descripción, y, con --offline, donde generó una Release como borrador y no tiene nada pendiente, de un info que nombra el aggrega pull que hay que ejecutar a continuación, como describe El archivo de respuestas de la importación.

Publicados con cada release del compilador

Cada release del compilador compila los diez importadores a partir de las fuentes con tag y genera sus entidades Plugin a partir de los propios importadores, de modo que la capacidad, las firmas de reconocimiento, las funciones del host y la descripción de una entidad son lo que informa su importador. La release firma y publica los diez, importer/langflow, importer/flowise, importer/n8n, importer/mcp, importer/compose, importer/dify, importer/crewai, importer/langgraph, importer/google-adk e importer/agent-framework, en la versión de la release, junto a los demás plugins core, y registra sus entidades con las entidades de los demás plugins core para el catálogo estándar.