Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Importadores core

O repositório do compilador compila dez plugins importadores próprios, um para cada formato de origem, e os publica a cada lançamento do compilador:

PluginServeLê
importer/langflowimport:langflowum fluxo exportado do Langflow, em JSON
importer/flowiseimport:flowiseum chatflow ou um agentflow exportado do Flowise, em JSON
importer/n8nimport:n8num fluxo de trabalho exportado do n8n, em JSON
importer/mcpimport:mcpa configuração de um cliente MCP — .mcp.json, claude_desktop_config.json, .vscode/mcp.json ou .cursor/mcp.json — ou uma descrição de servidor do registro MCP, server.json, em JSON
importer/composeimport:composeuma aplicação Compose — compose.yaml, docker-compose.yml e seus arquivos de sobrescrita — em YAML
importer/difyimport:difyuma aplicação exportada do Dify em sua DSL, em YAML
importer/crewaiimport:crewaios agentes e as tarefas que um projeto CrewAI declara — config/agents.yaml e config/tasks.yaml, em YAML, ou crew.jsonc e agents/<name>.jsonc, ou suas variantes em JSON estrito crew.json e agents/<name>.json, em JSON com comentários
importer/langgraphimport:langgrapha configuração de uma aplicação LangGraph, langgraph.json, em JSON, e, de um arquivo de ambiente que a configuração nomeia, apenas os nomes das variáveis, quando a importação recebe esse arquivo em with.sources
importer/google-adkimport:google-adkos agentes declarados nos arquivos Agent Config de uma aplicação construída sobre o Google ADK — root_agent.yaml e as configurações que seus subagentes nomeiam — em YAML
importer/agent-frameworkimport:agent-frameworkum agente declarativo do Microsoft Agent Framework, um documento do tipo Prompt com qualquer nome, em YAML

Cada um é compilado a partir das fontes do próprio compilador e marcado com a versão do compilador, de modo que os importadores lançados com o compilador na versão X.Y.Z relatam a versão X.Y.Z, e suas entidades Plugin a registram. Diferentemente dos plugins listados em Plugins embutidos, nenhum é compilado dentro do binário. O binário traz a entidade Plugin de cada um e o digest do único módulo que aceita para ele, de modo que cada um serve seu formato em todo espaço de trabalho, sem nenhuma entrada em seu catálogo.

Todos os dez são construídos sobre o pacote importer do kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Para os importadores Langflow, Flowise e n8n, tudo o que um importador faz, qualquer que seja seu formato — pontuar os Components do catálogo do espaço de trabalho em relação a cada nó, decidir se faz referência a um deles ou gera um novo como rascunho, organizar o rascunho, levar os valores de credenciais que ele contém ou escrevê-los vazios conforme uma configuração pede, escrever os rascunhos e ler as configurações descritas abaixo — cabe a esse pacote, e apenas ler o formato, e conhecer a plataforma em que seus fluxos são executados, é particular de cada importador. O importador MCP gera como rascunho uma instância de um Component por servidor, então não pontua nada; ele compartilha com o pacote a leitura das configurações que lê, a decisão sobre valores de credenciais e as convenções pelas quais seus rascunhos são nomeados e descritos, como descreve O importador MCP. O importador Compose decide cada serviço com que encontra correspondência como os importadores de fluxos decidem um nó, por meio do mesmo pacote, renderiza seus rascunhos como eles e compartilha o resto como o importador MCP faz, como descreve O importador Compose. O importador Dify gera como rascunho a instalação do Dify que a biblioteca padrão monta, levando a aplicação, por meio do rascunho de plataforma do mesmo pacote na forma que ele assume para uma plataforma que é uma instalação inteira, como descreve O importador Dify. O importador CrewAI gera como rascunho uma instância do agente CrewAI da biblioteca padrão para cada agente que um projeto declara, conectada ao modelo que esse agente nomeia, e compartilha o resto como o importador MCP faz, como descreve O importador CrewAI. O importador LangGraph gera como rascunho uma instância do agente LangGraph da biblioteca padrão para cada grafo que a configuração de uma aplicação declara, conectada ao armazenamento de dados em que seu checkpointer mantém o estado, e compartilha o resto como o importador MCP faz, como descreve O importador LangGraph. O importador Google ADK gera como rascunho uma instância do agente ADK da biblioteca padrão para cada árvore de agentes que as configurações de uma aplicação declaram, conectada ao modelo que a árvore nomeia quando o ADK envia suas requisições para a API do Gemini, e compartilha o resto como o importador MCP faz, como descreve O importador Google ADK. O importador Agent Framework gera como rascunho uma instância do agente Agent Framework da biblioteca padrão para cada agente declarativo, conectada ao modelo OpenAI que esse agente nomeia — com cada servidor MCP que ele nomeia escrito em comentários, já que o provedor do modelo o alcança como uma ferramenta hospedada — e compartilha o resto como o importador MCP faz, como descreve O importador Agent Framework. Como o socket importador funciona, e o que ele recebe, está descrito em O socket importador.

Esta página é a referência sobre o que cada importador lê e rascunha. Para importar um projeto seu e compilar o resultado, comece em Importação, que conduz um projeto da sua origem até um build, um formato por vez.

Como uma importação obtém um

aggrega import, o método aggrega/import da sessão do editor e a ferramenta import do assistente obtêm um importador core da mesma forma. Onde a máquina já contém seu módulo — no cache de conteúdo do espaço de trabalho —, a importação o lê dali, sem precisar de rede para isso. Onde não contém, a primeira importação que precisa dele o baixa do registro padrão do espaço de trabalho, na versão do compilador, e:

  • o confere com o digest que o binário traz, de modo que só é executado o módulo que o lançamento do compilador publicou;
  • o verifica como um pull verifica um plugin que baixa — sua assinatura segundo a política de confiança desse registro, e as funções host que ele usa em relação às que sua entidade Plugin registra;
  • o mantém no cache de conteúdo do espaço de trabalho, que é a única coisa escrita para ele: nenhum arquivo de bloqueio, e nenhum registro de plugins confiáveis, porque uma importação não fixa nenhum importador.

Toda importação posterior o lê do cache de conteúdo. Um módulo que não passa na verificação é recusado, e nada é mantido. Em uma pasta que nenhum espaço de trabalho marca não há cache de conteúdo em que mantê-lo, então o download é recusado ali, nomeando a pasta e como nomear um espaço de trabalho ou tornar a pasta um. O módulo nunca é lido de ao lado de uma entidade Plugin de mesmo nome em outra versão em uma pasta de catálogo: esse módulo pertence à outra entidade.

Onde o módulo não pode ser baixado, a importação é interrompida sob A plugin’s .wasm is not on this machine (O arquivo Wasm de um plugin não está nesta máquina), nomeando o importador e sua versão, e diz o que coloca seu módulo na máquina:

  • Execute a importação uma vez com a rede disponível, onde o espaço de trabalho está offline ou seu registro não pôde ser alcançado. Essa execução o baixa, e toda execução posterior é offline.
  • Coloque seu módulo ao lado de uma entidade Plugin desse importador nessa versão em uma pasta de catálogo, com o nome que a mensagem dá — importer--langflow.wasm para o importador Langflow. Uma entidade de catálogo com o mesmo nome e a mesma versão que um importador core é executada no lugar dele, com seu módulo lido de ao lado dela; uma entidade ali sem módulo ao lado dela não é executada no lugar dele, e o importador core é obtido como descrito acima. Onde o registro não contém o módulo, ou o espaço de trabalho não nomeia nenhum registro padrão, esta é a única solução que a mensagem dá.

Qual é executado ao lado dos seus próprios importadores

Os importadores core são candidatos ao lado dos importadores que o catálogo do seu espaço de trabalho contém, segundo as regras pelas quais todo importador é selecionado, que Qual importador transforma uma origem em rascunhos expõe:

  • Dentro de um mesmo nome, é executada a versão mais alta, ou a versão que uma entrada plugins.importer nomeia.
  • Onde seu catálogo contém um importador de outro nome para langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk ou agent-framework, dois importadores anunciam o formato, e uma importação que não vincula nenhum dos dois é recusada nomeando ambos, sob A parse or import format is advertised by more than one plugin (Um formato de análise ou de importação é anunciado por mais de um plugin). Uma entrada plugins.importer que nomeie o que você quer resolve a questão.
  • Um importador que seu catálogo contém com o mesmo nome e a mesma versão que um importador core, com seu módulo ao lado da sua entidade, é o que é executado, lido de lá.
  • Uma entidade Plugin com o nome de um importador core e sem módulo ao lado dela em sua pasta de catálogo — um checkout de um catálogo que registra os importadores que uma versão publicou, por exemplo — é uma que nenhuma importação poderia executar, já que seu módulo não é lido de nenhum outro lugar; por isso ela não é candidata à execução, embora as assinaturas que registra continuem participando do reconhecimento de uma fonte. Na versão do próprio compilador, o importador core é executado no lugar dela. Em qualquer outra versão, mais antiga ou mais nova, ela é ignorada, e a escolha é feita entre os importadores que podem ser executados — a menos que uma entrada plugins.importer nomeie exatamente essa versão, ou que nenhum importador desse nome que possa ser executado anuncie o formato solicitado, como quando a entidade registra um formato que o importador do próprio compilador não registra. Nesse caso, ela continua candidata segundo as regras acima, e uma importação que a escolhe é interrompida, nomeando a pasta onde seu módulo deve ser colocado.

Seja qual for o importador do seu catálogo escolhido, seu módulo é lido de ao lado da sua própria entidade, na sua própria versão: um módulo colocado ao lado de uma entidade de mesmo nome em outra versão pertence a essa entidade.

Como uma origem é reconhecida

Uma importação que não nomeia seu formato com --format é reconhecida pelas assinaturas que cada importador declara:

  • Langflow — uma origem que é analisada como JSON e traz um array em data.nodes.
  • Flowise — uma origem que é analisada como JSON, traz arrays em nodes e edges, e não traz nada em data.nodes.
  • n8n — uma origem que é analisada como JSON, traz um array em nodes e um objeto em connections, e não traz nada em edges nem em data.nodes.
  • MCP — uma origem que é analisada como JSON, se chama .mcp.json, claude_desktop_config.json ou .cursor/mcp.json e traz um objeto em mcpServers; uma origem que é analisada como JSON com comentários, como o Visual Studio Code a lê, se chama .vscode/mcp.json e traz um objeto em servers; ou uma origem de qualquer nome que é analisada como JSON e cujo $schema é um texto que começa com https://static.modelcontextprotocol.io/schemas/, uma descrição de servidor de registro. Um nome é comparado com o final do caminho que a importação recebe, então project/.vscode/mcp.json é reconhecido, enquanto mcp.json entregue de dentro de .vscode, ou o arquivo de um cliente com qualquer outro nome, é importado nomeando --format mcp.
  • Compose — uma origem que é analisada como YAML, tem um dos nomes com que o Compose lê por padrão um arquivo Compose ou seu arquivo de sobrescrita — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml, compose.override.yml, compose.override.yaml, docker-compose.override.yml ou docker-compose.override.yaml — e traz um objeto em services. Um arquivo Compose com qualquer outro nome é importado nomeando --format compose.
  • Dify — uma origem de qualquer nome que é analisada como YAML, traz o texto app em kind, e traz algo em app.mode e em version, como toda aplicação que o Dify exporta faz.
  • CrewAI — uma origem chamada config/agents.yaml ou config/tasks.yaml que é analisada como YAML, uma origem chamada crew.jsonc ou crew.json que é analisada como JSON com comentários e traz uma lista em agents, ou uma origem chamada agents/<name>.jsonc ou agents/<name>.json que é analisada como JSON com comentários e traz algo em role. Um projeto clássico identifica seus agentes e suas tarefas por nomes escolhidos pelo autor, então seus dois arquivos são distinguidos apenas pelos nomes.
  • LangGraph — uma origem chamada langgraph.json que é analisada como JSON e traz um objeto em graphs; ou uma origem de qualquer nome que é analisada como JSON, traz um objeto em graphs e cujo $schema é o texto https://langgra.ph/schema.json, o esquema que o LangGraph publica para sua configuração. Uma configuração com outro nome que não nomeia nenhum esquema é importada nomeando --format langgraph. Nenhuma assinatura de importador nomeia um arquivo de ambiente, então reconhecer um diretório não abre nenhum.
  • Google ADK — uma origem chamada root_agent.yaml que é analisada como YAML e traz algo em name e em instruction, como faz a configuração de um LlmAgent, ou um texto em agent_class e algo em name, como faz a de qualquer outro agente. Uma configuração com outro nome é importada nomeando --format google-adk. Nenhuma assinatura nomeia a configuração de um subagente, que pode se chamar de qualquer forma, então reconhecer um diretório não abre nenhum arquivo YAML além de root_agent.yaml.
  • Agent Framework — uma origem de qualquer nome que é analisada como YAML, traz o texto Prompt em kind e um objeto em model, como faz um agente declarativo que nomeia seu modelo; o Agent Framework carrega um agente declarativo de qualquer arquivo que sua aplicação nomeie, então a assinatura não nomeia nenhum arquivo. Um agente declarativo que não nomeia nenhum modelo, ou que escreve seu tipo com outra combinação de maiúsculas e minúsculas ou como Agent, é importado nomeando --format agent-framework.

Uma origem que corresponde a duas delas é recusada nomeando ambos os formatos, e é importada nomeando o correto com --format. Os importadores Langflow, Flowise, n8n e LangGraph leem sua origem por meio do analisador que serve parse:json; o importador MCP, uma configuração que lista seus servidores em servers por meio daquele que serve parse:jsonc e qualquer outra origem por meio daquele que serve parse:json; os importadores Compose, Dify, Google ADK e Agent Framework, por meio daquele que serve parse:yaml; e o importador CrewAI, os arquivos de um projeto clássico por meio daquele que serve parse:yaml e os demais por meio daquele que serve parse:jsonc: aquele que o catálogo do seu espaço de trabalho serve, onde serve um, e caso contrário o analisador que o próprio compilador traz para essa sintaxe (veja Plugins embutidos). Assim, uma importação por meio de qualquer um deles não precisa de nenhum analisador no seu catálogo, e nada é baixado para um. Um analisador que seu catálogo de fato serve é o usado, e o do compilador não tem papel algum. Os importadores Langflow, Flowise, n8n, Dify e Agent Framework não declaram nenhum padrão de arquivo, então cada um lê um único arquivo, e uma importação de um diretório por meio de qualquer um deles é recusada; o importador MCP declara os quatro nomes de arquivo dos clientes, então um diretório é lido por meio das configurações de cliente que contém; o importador Compose declara os oito nomes de arquivo do Compose, então um diretório é lido por meio dos arquivos Compose que contém; o importador CrewAI declara os seis nomes das declarações de um projeto, então o diretório de um projeto é lido por meio das suas declarações e de nada mais; o importador LangGraph declara langgraph.json, então o diretório de uma aplicação é lido apenas por meio da sua configuração, e nem seu código nem um arquivo de ambiente são lidos em momento algum; e o importador Google ADK declara root_agent.yaml, então o diretório de uma aplicação é lido apenas por meio da sua configuração raiz — as configurações que seus subagentes nomeiam chegam ao importador apenas no with.sources da sua vinculação — e nem seu código nem seu arquivo de ambiente são lidos em momento algum. Uma assinatura que não nomeia nenhum arquivo — as dos importadores Langflow, Flowise e n8n, a do importador MCP para uma descrição de servidor de registro, a do importador LangGraph para uma configuração que nomeia seu esquema, a do importador Dify e a do importador Agent Framework — se aplica a todo arquivo importado isoladamente: uma importação que não nomeia nenhum formato lê um arquivo assim como JSON, e como YAML, para tentar ambos, qualquer que seja o importador a que se destina, por meio desses mesmos analisadores — o compilador traz ambos, então nada é baixado para nenhum dos dois. Um arquivo que contém um comentário ou uma vírgula final não é analisado como JSON, então nenhuma assinatura que lê JSON o reconhece; as assinaturas do importador CrewAI para crew.jsonc, agents/<name>.jsonc e suas variantes .json, e a do importador MCP para .vscode/mcp.json, leem JSON com comentários, por meio do analisador que o compilador traz para essa sintaxe onde seu catálogo não serve nenhum.

Uma origem que seu analisador recusa — para os importadores Langflow, Flowise, n8n e LangGraph, uma que não é JSON; para o importador MCP, uma que não é JSON com comentários ou, a menos que liste seus servidores em servers, não é JSON; para os importadores Compose, Dify e Agent Framework, uma que não é YAML; para o importador CrewAI, uma declaração que não é YAML ou não é JSON com comentários; e para o importador Google ADK, uma configuração que não é YAML — interrompe a importação sob parse-failed, cuja mensagem traz o motivo do próprio analisador. Nomear o formato não muda isso: o importador pede a árvore da origem, e a recusa do analisador é a resposta que ele recebe.

Como um rascunho é nomeado

Todo importador atribui ao Aggregate que gera como rascunho, e à Release ao lado dele quando gera uma, o nome <target_namespace>/<name>. A primeira parte é a configuração target_namespace, imported a menos que você defina outra. <name> é o primeiro dos itens a seguir que não esteja vazio:

  • o nome que a fonte dá a si mesma, no campo em que o seu formato o declara:

    ImportadorO nome que ele lê
    importer/langflowo name do fluxo
    importer/flowisenenhum: uma exportação não carrega um nome próprio
    importer/n8no name do workflow
    importer/mcpo name da descrição de um servidor de registry; a configuração de um cliente não carrega nenhum
    importer/composeo name de nível superior do projeto, o de um arquivo de override no lugar do arquivo que ele sobrescreve, como o Compose os mescla
    importer/difyo name da aplicação, sob app
    importer/crewaio name da crew em crew.jsonc ou crew.json; config/agents.yaml e config/tasks.yaml não carregam nenhum, pois um projeto clássico nomeia a sua crew no seu programa
    importer/langgrapho id do grafo que a configuração declara, pois uma configuração não carrega um nome próprio
    importer/google-adko name do agente raiz
    importer/agent-frameworko name do agente; o seu displayName não é lido
  • o nome do diretório entregue à importação, inteiro — my.project mantém o seu ponto, escrito my-project — como o Compose nomeia um projeto conforme o diretório que o contém; aggrega import . nomeia o diretório em que é executado;

  • o nome do arquivo entregue sozinho à importação, sem a sua extensão;

  • flow.

Um rascunho feito a partir de várias fontes — vários projetos do Compose, configurações, árvores de agentes ou servidores, ou uma configuração que declara vários grafos — recebe o nome delas apenas quando cada uma delas se nomeia e todas são escritas da mesma forma; caso contrário, recebe o seguinte. Um nome é escrito em minúsculas, cada sequência de caracteres que não sejam letras e dígitos ASCII como um único hífen, e os hífens nas duas pontas são removidos: Basic Prompting é escrito basic-prompting, e SupportAgent supportagent. A mesma fonte recebe o mesmo nome em toda importação. Um Manifest que uma importação gera como rascunho para um destino recebe o nome da Release, ou o do Aggregate quando nenhuma Release é gerada, como descreve O que um destino adiciona.

O que o importador Langflow lê

  • Os nós e as arestas sob o objeto data de nível superior do fluxo, data.nodes e data.edges.
  • Para cada nó, seu tipo a partir do data.type do nó, e seus campos a partir das entradas de data.node.template cujo valor é um objeto que traz um type. As outras entradas do template não são campos.
  • Um campo cujo objeto traz password: true entra no rascunho como slot de credencial, e todo outro campo como campo de valor. O nome do campo não tem papel algum, e colocar um nó no rascunho como Component não lê o valor de nenhum campo.
  • Uma nota fixada na tela, um nó do tipo noteNode, não é importada, e uma aresta para um nó que não é importado é descartada.
  • Gerar como rascunho a plataforma que leva o fluxo também lê, do fluxo: seu id de nível superior; o valor de cada campo marcado com password: true; o campo mcp_server de um nó MCP Tools — o servidor MCP que ele nomeia, e a configuração desse servidor — ou, em vez dele, os campos em que mantém seu servidor; cada entrada que o Langflow não marca como credencial mas que pode conter uma, como Valores de credenciais que o fluxo contém as lista; o campo em que um nó nomeia seu modelo, e o provedor do modelo em que ele é executado; e os campos por meio dos quais um nó alcança o endereço e a chave de uma parte, que ele reescreve. O que geram como rascunho diz o que acontece com cada um.

O que o importador Flowise lê

  • Os nós e as arestas no nível superior do fluxo, nodes e edges.
  • Para cada nó, seu tipo a partir do data.name do nó; seus slots de credencial a partir das entradas de data.inputParams cujo type é credential, pelo seu name; e seus campos de valor a partir das chaves de data.inputs, exceto as que data.inputAnchors nomeia — onde outro nó se conecta como entrada, o que a aresta entre eles registra — e exceto as credenciais.
  • Colocar um nó no rascunho como Component não lê o valor de nenhum campo, e o nome de uma credencial não tem papel algum em ela ser uma credencial.
  • Uma nota fixada na tela, um nó do tipo stickyNote, não é importada, e uma aresta para um nó que não é importado é descartada.
  • Gerar como rascunho a plataforma que leva o chatflow também lê, dele: seu id de nível superior, onde é um UUID; a credencial que um nó mantém em data.credential; o valor de cada entrada que seus inputParams declaram do tipo password; FLOWISE_CREDENTIAL_ID entre as entradas de um nó, e credential ou FLOWISE_CREDENTIAL_ID dentro de um objeto de configuração em qualquer profundidade delas; a configuração do servidor na entrada mcpServerConfig de um nó; cada entrada que o Flowise não marca como credencial mas que pode conter uma, como Valores de credenciais que o fluxo contém as lista, e o membro em que a configuração de um agentflow nomeia o modelo ou a ferramenta que seleciona; a entrada modelName de um nó; e o Base Path de um nó OpenAI, sua entrada basepath. O que geram como rascunho diz o que acontece com cada um.

O que o importador n8n lê

  • Os nodes do workflow e suas connections, no nível superior da exportação.
  • Para cada nó, seu name, que o identifica — as conexões do n8n nomeiam pelo nome os nós que unem, e os nomes dos nós de um workflow são únicos — e seu type, escrito por inteiro, com seu pacote: @n8n/n8n-nodes-langchain.lmChatOpenAi, por exemplo, ou n8n-nodes-base.httpRequest. Um nó sem nome é identificado pelo seu id.
  • Cada conexão que o workflow lista é uma aresta, do nó de onde sai para o nó em que entra, qualquer que seja seu tipo: uma conexão main leva dados de um nó ao seguinte, e uma conexão de IA — ai_languageModel, ai_tool, ai_vectorStore, ai_embedding, ai_memory e as demais — entrega ao nó em que entra o modelo, a ferramenta, o armazenamento ou a memória que o nó de onde sai representa. De qualquer forma, o nó em que uma conexão entra consome o nó de onde ela sai.
  • Cada tipo de credencial que as credentials de um nó nomeiam, e cada parâmetro de nível superior que o n8n marca como senha, entra no rascunho como slot de credencial; todo outro parâmetro de nível superior do nó é um campo de valor. Colocar um nó no rascunho como Component não lê o valor de nenhum campo.
  • Uma nota fixada na tela, um nó do tipo n8n-nodes-base.stickyNote, não é importada, e uma conexão para um nó que não é importado é descartada.
  • Gerar como rascunho a plataforma que leva o workflow também lê, dele: seu id de nível superior; cada credencial que um nó seleciona; cada parâmetro que o n8n marca como senha; o endereço que um nó cliente MCP chama; os cabeçalhos e os parâmetros de consulta que um nó envia com uma requisição que o workflow compõe, como Valores de credenciais que o fluxo contém os lista; e o parâmetro em que um nó de modelo nomeia seu modelo. O que geram como rascunho diz o que acontece com cada um.

O que geram como rascunho

Cada nó é pontuado em relação aos Components do próprio catálogo do espaço de trabalho e a nada mais, como descreve o socket importador, e cada importador traz uma tabela curta que mapeia tipos de nó comuns do seu formato — modelos de chat e de embeddings, recuperação, requisições HTTP e, no Langflow, o nó MCP Tools MCPTools, que é mapeado para core/ai-tool/mcp — para Components da biblioteca padrão. A tabela do Langflow também mapeia seu componente Language Model, LanguageModelComponent, o modelo de chat que seus fluxos iniciais chamam, para core/ai-model/openai, o modelo que a conexão de modelo da plataforma Langflow atende: o nó é executado no provedor de modelos que seu campo provider nomeia, OpenAI por padrão, e um nó que nomeia outro provedor nunca é ligado a essa conexão, como descreve Quais nós se tornam partes. A tabela do importador n8n mapeia os modelos de chat e de embeddings do n8n, sua ferramenta cliente MCP para core/ai-tool/mcp, suas ferramentas de requisição HTTP, sua ferramenta SerpApi, seus armazenamentos vetoriais Qdrant, PGVector, Chroma, Milvus e Weaviate, e suas memórias de chat Postgres e Redis. Um nó que o n8n executa dentro do próprio workflow — um agente, uma chain, um gatilho, uma memória que o workflow mantém em seu próprio processo, uma ferramenta de código — pertence ao workflow, e nenhuma linha o mapeia. Uma linha dessa tabela conta para uma correspondência apenas onde o catálogo do espaço de trabalho contém o Component que ela nomeia. O comando relata uma linha para cada nó que mapeou, nomeando o que escolheu, o nível de correspondência e a pontuação do melhor candidato, e uma linha com o texto made no choice for <node id> (<node type>) para um nó ao qual não dá nenhum Component próprio. Um nó que faz referência a um Component do catálogo, em vez de ser gerado como rascunho, não tem arquivo próprio: o Aggregate do rascunho nomeia o Component.

Como o rascunho é organizado cabe à configuração layout. platform, o padrão, gera como rascunho a plataforma que executa o fluxo, levando o fluxo como foi exportado, e dá um Component próprio apenas a cada parte do fluxo que um socket da plataforma aceita — nas plataformas da biblioteca padrão, um modelo, um servidor MCP ou outra ferramenta alcançada via HTTP, e um armazenamento vetorial. nodes gera como rascunho cada nó como um Component próprio.

A plataforma que leva o fluxo

Por padrão, uma importação escreve:

  • aggregate.yaml — um Aggregate de rascunho com o nome do fluxo, como descreve Como um rascunho é nomeado. Ele contém uma instância da plataforma que executa o fluxo — core/ai-agent/langflow, sob a chave langflow, para um fluxo do Langflow, core/ai-agent/flowise, sob a chave flowise, para um do Flowise, e core/ai-agent/n8n, sob a chave n8n, para um workflow do n8n — que faz referência ao Component do catálogo com esse nome. A instância leva o fluxo em values.flow_definition e o nomeia em seu valor identificador, flow_id no Langflow, chatflow_id no Flowise e workflow_id no n8n. Cada parte do fluxo é uma entrada própria ao lado dela, conectada à plataforma sob os uses da instância.
  • release.yaml — uma Release rascunho com o mesmo nome, nomeando esse Aggregate, com uma entrada para a plataforma e uma para cada parte, levando a imagem da plataforma e vinculando por referência cada segredo de que o rascunho precisa, como descreve O que o rascunho deixa para a Release.
  • um arquivo sob components/ para cada parte que gera como rascunho em vez de referenciar, escrito como o layout nó a nó escreve um nó gerado como rascunho.

Dado um destino, a importação gera manifest.yaml ao lado deles, como descreve O que um destino adiciona.

Todo nó que não é uma parte permanece dentro do fluxo que a plataforma leva e não se torna nenhum Component. Sua decisão registra os candidatos em relação aos quais foi pontuado e não escolhe nada, e sua justificativa diz kept in the flow <platform> carries, with no Component of its own:, seguido do motivo — por exemplo, que nenhuma linha de mapeamento nomeia seu tipo e que seu candidato mais próximo obteve só determinada pontuação. O fluxo mantém as arestas entre os nós; o rascunho não escreve nenhuma própria.

O chatflow Multiple Documents QnA do Flowise, exportado como Multiple Documents QnA.json e importado sem nenhuma configuração e sem destino sobre um catálogo que contém a plataforma Flowise da biblioteca padrão e seus Components de modelo e de ferramenta de recuperação, é gerado como rascunho como este Aggregate, com a maior parte do fluxo omitida aqui e marcada com ...:

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

Seu modelo de chat é a única parte conectada; seus dois modelos de embeddings permanecem no fluxo, já que o socket de modelo aceita uma única conexão, e suas ferramentas retriever permanecem no fluxo, já que nenhum socket da plataforma as aceita. A importação relata cada um.

O identificador do fluxo é o que a exportação lhe dá — o id de nível superior de um fluxo do Langflow, o id de nível superior de um chatflow do Flowise onde é um UUID, e o id de nível superior de um workflow do n8n — onde ele tem de uma a 128 letras, dígitos, ., -, _ ou :, começando por uma letra ou um dígito. Onde a exportação não dá nenhum, ou dá um contendo qualquer outro caractere, o rascunho escreve um UUID baseado em nome derivado do nome do formato e do fluxo como é levado, de modo que um fluxo sempre produz um mesmo identificador, e um comentário acima do valor diz que ele foi derivado. Um chatflow exportado do editor do Flowise não traz nenhum id, então recebe um derivado.

Onde o catálogo do espaço de trabalho não contém nenhum Component com o nome da plataforma, o rascunho nomeia a plataforma mesmo assim e não conecta nenhuma parte a ela: cada nó que teria sido uma parte permanece no fluxo, é relatado, e a importação avisa que o catálogo não contém tal Component.

Quais nós se tornam partes, e onde cada um é conectado

Um nó é uma parte do fluxo onde uma linha da tabela de mapeamento do importador, ou uma entrada mapping_overrides, mapeia seu tipo, ou onde seu melhor candidato é pelo menos uma correspondência de nível médio. Um nó MCP Tools do Langflow é uma parte quaisquer que sejam suas pontuações: ele nomeia o servidor MCP que chama, e esse servidor é a parte. Uma parte se torna um Component próprio, referenciado ou gerado como rascunho exatamente como reuse_mode decide, e é conectada ao primeiro socket da plataforma — na ordem em que a entrada de catálogo da plataforma declara seus sockets — cujo seletor de rótulos o Component da parte satisfaz: os rótulos do Component que ela referencia ou, para uma parte que gera como rascunho, os do seu melhor candidato onde esse candidato é pelo menos uma correspondência de nível médio. Uma parte cujo Component não satisfaz o seletor de nenhum socket, ou que não tem nenhum Component do qual ler rótulos, permanece no fluxo, e a importação a relata.

Estas regras restringem isso:

  • Um modelo do Langflow que nomeia outro provedor não recebe nenhuma conexão de modelo. Um nó LanguageModelComponent ou EmbeddingModel é executado no provedor de modelos que seu campo provider nomeia ou, onde ele está vazio, no provedor do modelo que seu campo model seleciona. A plataforma entrega sua conexão de modelo para um cliente compatível com OpenAI, então um nó que nomeia qualquer provedor diferente de OpenAI — seja qual for o destino para o qual uma linha de mapeamento ou uma substituição o mapeie — nunca é ligado ao socket model: ele é ligado ao próximo socket que seu Component satisfaz, ou permanece no fluxo, com sua decisão sem escolher nada e nenhum Component gerado como rascunho para ele, e a importação o relata nomeando o provedor em que ele é executado. Um nó que não seleciona nenhum provedor, que o nomeia por meio de uma variável global ou que obtém seu modelo de outro nó é ligado como qualquer outra parte.
  • Um socket que aceita uma única conexão é ocupado por uma parte. Em toda plataforma, o socket model aceita uma conexão, que as Recipes da plataforma entregam como um único OPENAI_BASE_URL e um único OPENAI_API_KEY. Onde várias partes são colocadas nele, quem o ocupa é a primeira cujo Component traz model.aggrega.ai/capability: generative — a primeira parte, onde nenhuma traz — e toda outra permanece no fluxo, relatada com a parte que ocupa a conexão e com o modo como o fluxo a alcança conforme seu nó está escrito.
  • O Langflow alcança uma conexão tools apenas por meio de um nó MCP Tools que a nomeia. A plataforma escreve o endereço de uma conexão tools na configuração do servidor do nó MCP Tools cujo campo mcp_server nomeia a conexão, de modo que um nó cujo template não traz nenhum campo mcp_server — qualquer que seja seu tipo, e para o que quer que uma linha de mapeamento ou uma sobrescrita o mapeie — nunca é conectado ao socket tools: ele é conectado ao próximo socket que seu Component satisfaz, ou permanece no fluxo, relatado. Um nó MCP Tools que não nomeia nenhum servidor não é conectado a nenhum socket e é relatado. O mesmo vale para um cuja configuração do servidor inicia um servidor próprio — ele traz um command, ou define o modo Stdio — e seu relato diz o que remover, já que o build da plataforma é interrompido em um nó que nomeia um servidor ao qual nenhuma conexão tools responde.
  • Um servidor MCP é conectado pelo nome que o fluxo lhe dá. Os nós de um fluxo que nomeiam um mesmo servidor alcançam uma única parte, gerada como rascunho uma só vez, por meio de uma única conexão. O alias da conexão é o nome do servidor onde o alias de uma conexão pode assumi-lo — letras, dígitos, hifens e sublinhados — e nenhuma outra conexão desse socket entrega sob o mesmo nome de variável, seu alias em maiúsculas com todo outro caractere escrito como sublinhado. Caso contrário, a conexão assume um alias derivado da chave da parte, o servidor do nó é renomeado para esse alias no fluxo que o rascunho leva, e a decisão da parte diz isso.

A decisão de uma parte conectada diz a qual socket da plataforma ela está conectada e por meio de qual conexão, e nomeia cada socket para o qual foi preterida e por quê.

Como o fluxo levado alcança cada parte

Onde o formato permite, o fluxo que a plataforma leva alcança cada parte conectada por meio de sua conexão, e o rascunho escreve no fluxo o que faz com que isso aconteça — o nome de uma variável, um endereço esvaziado, ou o que o nó enviaria no lugar do que a conexão fornece, esvaziado, e nunca um valor. Isso é cabeamento, não a remoção de um valor de credencial: o rascunho o escreve independentemente do que diga a configuração empty_credentials, já que um valor mantido ali sobrescreveria o que a conexão entrega.

  • Um nó MCP Tools do Langflow. A plataforma escreve o endereço que sua conexão entrega na configuração do servidor do nó e, onde a conexão leva uma credencial, o nome da variável que a contém sob o cabeçalho que a ferramenta publica. O rascunho escreve vazio o endereço que a exportação continha ali, de modo que o fluxo não guarda nenhuma cópia dele, e deixa o endereço do servidor — infra.endpoint da parte — para a Release. O Langflow envia o próprio campo headers do nó por cima dos cabeçalhos da configuração de seu servidor, então o rascunho escreve vazio o valor inteiro desse campo mantendo seu tipo — um objeto como {}, uma lista como [], texto como uma string vazia — já que um cabeçalho mantido com o valor esvaziado ainda seria enviado, enquanto um objeto ou uma lista vazios não sobrescrevem nada.

  • Um nó de modelo ou de armazenamento vetorial do Langflow. A plataforma entrega uma conexão de modelo como OPENAI_BASE_URL e OPENAI_API_KEY, e uma conexão de armazenamento vetorial como variáveis nomeadas de acordo com seu alias, que o Langflow lê por meio de um campo que nomeia uma variável global: um campo cujo objeto traz load_from_db: true contém o nome da variável como seu valor, e o Langflow lê a variável global com esse nome, ou a variável de ambiente com esse nome onde nenhuma está armazenada. O rascunho escreve cada um desses campos com o nome da variável e load_from_db: true:

    • o campo openai_api_base de um nó OpenAIModel, como OPENAI_BASE_URL, e seu api_key, como OPENAI_API_KEY;
    • o campo openai_api_base de um nó OpenAIEmbeddings, como OPENAI_BASE_URL, e seu openai_api_key, como OPENAI_API_KEY;
    • o campo api_key de um nó LanguageModelComponent, como OPENAI_API_KEY;
    • o campo api_base de um nó EmbeddingModel, como OPENAI_BASE_URL, e seu api_key, como OPENAI_API_KEY;
    • o campo pg_server_url de um nó pgvector, como AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING, onde <ALIAS> é o alias da conexão em maiúsculas, com cada caractere que não seja uma letra ou um dígito escrito como sublinhado.

    Um nó LanguageModelComponent ou EmbeddingModel é executado em um entre vários provedores de modelos — o que seu campo provider nomeia ou, onde ele está vazio, o provedor do modelo que seu campo model seleciona — e entrega sua chave a esse provedor. A plataforma entrega a conexão de modelo para um cliente compatível com OpenAI, então um nó desse tipo é escrito com as variáveis apenas onde é executado em OpenAI. Um que é executado em outro provedor nunca é ligado, como descrito acima; um que não seleciona nenhum, que nomeia seu provedor por meio de uma variável global ou que obtém seu modelo de outro nó é escrito sem nenhuma delas, de modo que o rascunho nunca aponta outro provedor para a chave da conexão. Onde nenhum campo de um nó desse tipo fornece o endereço de sua API — um nó LanguageModelComponent não contém nenhum para OpenAI, e o campo api_base de um nó EmbeddingModel pode estar ausente, ou vazio onde não pode nomear uma variável — o cliente OpenAI em que ele é executado obtém OPENAI_BASE_URL do ambiente, então o nó alcança mesmo assim o endereço que a plataforma entrega.

    O cliente de um nó OpenAIEmbeddings envia seus default_headers por cima dos que constrói a partir da chave, e mescla seu default_query por cima da consulta do endereço que chama, então, em um nó desse tipo que o rascunho conecta, o valor inteiro de cada um é escrito vazio mantendo seu tipo, como são os headers de um nó MCP Tools.

    Um campo que a exportação escreve sem esses dois membros não é escrito de novo — um campo de credencial entre eles é levado como está escrito, ou escrito vazio onde a configuração pede, como abaixo. Onde esse campo é o que leva o endereço da parte — e, para um nó LanguageModelComponent ou EmbeddingModel, fornece um —, onde um nó desse tipo não é executado em OpenAI, ou onde o nó é de qualquer outro tipo, a importação relata a parte como alcançada no endereço que o fluxo ou os valores padrão de seu componente fornecem.

  • Um nó OpenAI do Flowise. O cliente OpenAI em que o Flowise executa um nó chatOpenAI ou openAIEmbeddings lê OPENAI_BASE_URL e OPENAI_API_KEY do ambiente onde o Base Path do nó está vazio e ele não seleciona nenhuma credencial, então o rascunho escreve vazio um Base Path que a exportação contém, e também a credencial que o nó seleciona, em data.credential. Esse cliente envia os cabeçalhos padrão do nó, seus baseOptions, por cima do cabeçalho que constrói a partir da chave, então o rascunho escreve vazio seu valor inteiro mantendo seu tipo. Um nó de modelo de qualquer outro tipo é relatado como alcançado no endereço que o chatflow ou seus próprios valores padrão fornecem.

  • Uma ferramenta ou um armazenamento vetorial do Flowise. Um chatflow lê o endereço que a plataforma entrega para um deles — AGGREGA_TOOL_<ALIAS>_URL ou AGGREGA_VECTOR_STORE_<ALIAS>_URL — apenas por meio de uma variável Runtime com esse nome, que nada cria na inicialização. O rascunho não escreve nada para ele, e a importação relata a etapa que faz o chatflow lê-lo: criar a variável Runtime na página Variables do Flowise e lê-la no nó como $vars.<name>.

  • Qualquer nó do n8n. A plataforma entrega uma conexão de modelo como OPENAI_BASE_URL e OPENAI_API_KEY, e uma conexão tools ou de armazenamento vetorial como AGGREGA_TOOL_<ALIAS>_URL ou AGGREGA_VECTOR_STORE_<ALIAS>_URL, enquanto um nó do n8n alcança um modelo, um armazenamento ou um serviço no endereço que a credencial armazenada que ele seleciona fornece, ou no endereço que seus próprios parâmetros contêm, e um workflow lê uma variável de ambiente apenas por meio de uma expressão que lê $env, que a plataforma recusa a menos que o Aggregate defina values.allow_env_access_in_nodes como true. O rascunho deixa esse valor em seu padrão, false, já que defini-lo permite que cada workflow, e cada usuário que pode editar um, leia cada variável do ambiente da plataforma, incluídas as credenciais entregues. Assim, o rascunho não escreve nada no workflow para uma conexão, e cada parte conectada é relatada como alcançada de outro modo que não por ela. Um nó cliente MCP alcança seu servidor no endereço que o workflow contém — como a exportação o escreveu, ou nenhum onde a configuração empty_credentials o escreve vazio, como abaixo — e o próprio endereço do servidor — infra.endpoint da parte — é deixado para a Release.

Onde o fluxo é levado, cada parte conectada é relatada com qual destes casos se aplica: part-reads-connection onde o fluxo alcança a parte por meio de sua conexão, e part-address-in-flow onde ele alcança a parte de outro modo que não por sua conexão — em um endereço que o fluxo contém, ou em um que os valores padrão de seu componente fornecem. A decisão da parte diz o mesmo.

Um nó que o rascunho não conecta a nenhum socket ainda pode ser alcançado por uma conexão que o rascunho de fato conecta, tal como o nó está escrito: um cliente OpenAI sem endereço e sem chave próprios lê de seu ambiente as OPENAI_BASE_URL e OPENAI_API_KEY que a plataforma entrega para a conexão de modelo. Onde isso acontece, o rascunho escreve o nó como escreveria um conectado, de modo que nada do que ele contém é enviado no lugar do que a conexão fornece, e o relata com part-reads-connection:

  • um nó OpenAIEmbeddings do Langflow cujo campo de endereço nomeia a variável OPENAI_BASE_URL que a plataforma entrega, lida como variável global, enquanto uma parte está conectada ao socket de modelo: seus default_headers e default_query;
  • um nó chatOpenAI ou openAIEmbeddings do Flowise cujo Base Path está vazio e que não seleciona nenhuma credencial, e a configuração de um modelo desse tipo que um nó de agentflow mantém entre suas entradas, enquanto uma parte está conectada ao socket de modelo: seus baseOptions.

Em qualquer outro nó esses valores não são cabeamento: são levados como estão escritos, ou escritos vazios onde a configuração pede, como diz a próxima seção.

Valores de credenciais que o fluxo contém

Antes de o fluxo ser levado, a importação localiza cada valor nele que pode conter uma credencial, nos lugares listados abaixo, cada um de um de três tipos: o que um formato marca como credencial; um membro da configuração de um servidor MCP, onde quer que um formato mantenha uma; e uma entrada que um formato marca como não credencial mas que pode conter uma mesmo assim — cabeçalhos de requisição, parâmetros de consulta, uma requisição inteira escrita como linha de comando, uma entrada que contém uma credencial sob o nome de uma credencial.

Por padrão, a importação não escreve nenhum deles vazio: o fluxo é levado como foi exportado, e cada valor localizado que contém algo — nem uma string vazia nem null — é nomeado em um aviso credential-carried, por seu nó e seu campo — um cabeçalho ou um parâmetro de consulta por seu nome —, nunca por seu valor nem por qualquer parte dele, junto com o valor da configuração empty_credentials que o escreve vazio. A configuração ativa a remoção: marked escreve vazio o que um formato marca como credencial e cada membro da configuração de um servidor MCP; all escreve vazias também as entradas marcadas como não credenciais. Cada valor que ela escreve vazio é relatado com credential-emptied, por seu nó e seu campo, nunca por seu valor; um valor já vazio, ou null, é deixado como está e não é relatado. Um valor que a configuração não aceita interrompe a importação, que não gera nada como rascunho, em vez de valer como none.

Um valor localizado que é uma referência a uma variável e nada mais não contém nenhum valor próprio: o nome simples de uma variável, ${NAME} — incluída uma variável predefinida como ${workspaceFolder} ou ${userHome} — ou uma das formas que os clientes MCP definem, ${env:NAME} e ${input:id}. Independentemente do que diga a configuração, ele é levado como está escrito e não é nomeado em nenhum aviso, qualquer que seja o formato do fluxo, assim como o importador MCP escreve um. O mesmo vale para um membro que é uma única referência dentro de um valor que um formato mantém como texto, como um mcpServerConfig do Flowise escrito como texto JSON, ou cabeçalhos e parâmetros de consulta mantidos como um objeto JSON em texto no Flowise e no n8n: escrito vazio, o texto mantém esse membro como está escrito.

Uma referência que traz texto após um operador contém esse texto, que pode ser uma chave, haja ou não dois-pontos antes do operador: um valor padrão, ${NAME:-value} ou ${NAME-value}; uma alternativa, ${NAME:+value} ou ${NAME+value}; uma mensagem, ${NAME:?message} ou ${NAME?message}; uma atribuição, ${NAME:=value} ou ${NAME=value}. Ela é localizada como qualquer outro valor — levada e nomeada em um aviso credential-carried por padrão, escrita vazia onde a configuração pede isso para seu tipo — e o mesmo vale para qualquer outro texto dentro de ${…}, como ${config:name}, e para texto ao lado de uma referência, como --key=${NAME}.

O que o rascunho escreve para que um nó alcance sua conexão — um endereço escrito vazio, o nome de uma variável, uma credencial selecionada ou cabeçalhos padrão escritos vazios, como descreve Como o fluxo levado alcança cada parte — é cabeamento: é escrito independentemente do que diga a configuração, relatado com o modo como o nó alcança sua conexão, e nunca relatado como valor de credencial. O que fica fora de todos os lugares abaixo cabe ao autor revisar, como diz o final desta seção.

O que um formato marca como credencial — escrito vazio com marked e all:

  • Langflow — o valor de cada campo do template marcado com password: true, incluído um campo que contém o nome de uma variável global, a menos que o rascunho escreva esse campo com o nome da variável que a plataforma entrega, como acima.
  • Flowise — a credencial que um nó mantém em data.credential, que seu parâmetro de credencial seleciona; o valor de cada entrada que seus inputParams declaram do tipo password; e FLOWISE_CREDENTIAL_ID entre as entradas de um nó, e credential ou FLOWISE_CREDENTIAL_ID dentro de um objeto de configuração em qualquer profundidade delas, como um agentflow mantém a de um modelo ou de uma ferramenta.
  • n8n — o id de cada credencial armazenada que um nó seleciona, em credentials.<type>.id. Uma exportação do n8n mantém uma credencial como referência, nunca seu valor, e o name da referência não é localizado: o n8n, ao importar o workflow em outra instância, resolve uma credencial cujo id ele não tem pelo seu tipo e nome. Uma credencial que uma exportação mais antiga seleciona apenas pelo nome nomeia uma credencial e não contém nenhuma, e não é localizada. E o valor de cada parâmetro que o n8n marca como senha nas definições de seus nós base — o secret do nó Crypto, por exemplo, ou o password dos nós que criam um usuário — onde quer que esteja entre os parâmetros do nó, sendo um nó usado como ferramenta de um agente lido como o nó que é.

A configuração de um servidor MCP — escrita vazia com marked e all:

  • A configuração mcp_server de um nó MCP Tools do Langflow, e o mcpServerConfig de um nó do Flowise, escritos como texto JSON ou como objeto: cada valor de cabeçalho, sejam os cabeçalhos um objeto, linhas de uma chave e um valor ou objetos mesclados inteiros, sendo um item de qualquer outro tipo localizado inteiro; cada valor de ambiente; o endereço do servidor; o comando; e cada argumento. Nenhum dos dois formatos marca um endereço, um comando ou um argumento como credencial, e cada um pode conter uma chave — um endereço em sua parte de usuário, seu caminho ou sua consulta —, então os três também são localizados, em ambos os formatos. Escritos vazios, o comando e cada argumento mantêm seus membros, de modo que uma configuração que inicia um servidor próprio ainda é lida como tal. Onde um nó MCP Tools do Langflow está conectado a uma conexão tools, seu endereço é cabeamento, como acima, e nunca é relatado como valor de credencial. Uma configuração do Flowise escrita como texto que não se lê como um objeto JSON é localizada inteira, já que nada dentro dela pode ser localizado.
  • Um nó MCP Tools do Langflow que não traz nenhum campo mcp_server mantém, em vez disso, seu servidor em campos próprios — o endereço em sse_url, os cabeçalhos em headers_input, o ambiente em env e a linha de comando inteira, incluídos seus argumentos, em command — e o Langflow também não marca nenhum deles como credencial, então cada valor de cabeçalho, cada entrada de env, o endereço e a linha de comando são localizados, mantendo seus campos e entradas quando escritos vazios. Onde env é uma lista, cada entrada é relatada por sua posição, já que o nome de uma variável e seu valor compartilham um mesmo texto. Um nó desse tipo não nomeia nenhum servidor MCP, então nunca é conectado a uma conexão tools.
  • O próprio campo headers de um nó MCP Tools do Langflow, que o Langflow envia ao servidor por cima dos cabeçalhos de sua configuração, em um nó que o rascunho não conecta: seu valor inteiro, escrito vazio mantendo seu tipo, como em um nó conectado, e relatado uma única vez, como headers.
  • Os componentes MCP Tools (SSE) e MCP Tools (stdio) do Langflow, que o Langflow marca como obsoletos, mantêm seu servidor em um único campo cada — um nó MCPSse seu endereço em url, um nó MCPStdio sua linha de comando inteira, incluídos seus argumentos, em command — localizado inteiro. Nenhum dos dois nomeia um servidor MCP, então nenhum dos dois é conectado a uma conexão tools.
  • Um nó cliente MCP do n8n — a MCP Client Tool que um agente chama, o nó MCP Client, ou um cliente de um servidor que o registro do n8n lista — mantém o endereço do servidor em seu parâmetro endpointUrl, ou sseEndpoint em sua primeira versão, e seus cabeçalhos apenas como credenciais que seleciona; o endereço é localizado inteiro, conectado ou não.

Uma entrada que um formato marca como não credencial — escrita vazia apenas com all:

  • Cabeçalhos de requisição — no Langflow, os headers de um nó APIRequest, URLComponent, CloudflareWorkersAIEmbeddings ou ConfluentKafkaProducer e os api_headers de um nó DoclingRemote; no Flowise, os headers de um nó httpAgentflow, getApiChain, postApiChain, openApiChain, apiLoader, openAPIToolkit ou searXNG, os requestsGetHeaders, requestsPostHeaders, requestsPutHeaders e requestsDeleteHeaders das ferramentas Requests, e os baseOptions — os cabeçalhos padrão que o cliente de um modelo envia — de um nó azureChatOpenAI, azureOpenAIEmbeddings, chatCerebras, chatOpenAICustom, openAIEmbeddingsCustom, chatOpenRouter, chatSambanova ou openAI; no n8n, os headerParameters, jsonHeaders, headerParametersUi e headerParametersJson de um nó n8n-nodes-base.httpRequest — sua versão atual mantém os dois primeiros, suas versões anteriores os outros dois — e do mesmo nó usado como ferramenta de um agente, os parametersHeaders e jsonHeaders de um nó @n8n/n8n-nodes-langchain.toolHttpRequest, e os headerParametersUi de um nó n8n-nodes-base.graphql. O nome de um cabeçalho não carrega nenhum segredo, então o valor de cada cabeçalho é localizado e seu nome mantido, qualquer que seja a forma dos cabeçalhos: um objeto de nomes para valores, linhas de uma chave e um valor — no n8n, linhas de um name e um value — ou objetos que o Langflow mescla inteiros nos cabeçalhos. Cada cabeçalho é relatado por seu nome. Um item de uma lista que não é uma linha de cabeçalho é localizado inteiro e relatado por sua posição. Cabeçalhos escritos como texto são localizados inteiros, exceto no Flowise e no n8n, onde o texto contém os cabeçalhos como um objeto JSON: ali, escrito vazio, o texto é reescrito no lugar, com cada valor vazio, e relatado uma única vez com os nomes dos cabeçalhos que contém. Um texto do n8n que começa com = é uma expressão que o n8n avalia quando o workflow é executado, e é localizado inteiro. Escritos vazios, todos os valores ficam vazios, incluídos os dos cabeçalhos que não contêm nenhum segredo, como User-Agent, então uma requisição importada é enviada com eles vazios até que seu autor os restaure.
  • Parâmetros de consulta — no Langflow, os query_params de um nó APIRequest ou GoogleSerperAPI e os search_params de um nó SerpAPI, Serp, SearchAPI ou SearchComponent; no Flowise, os queryParams de um nó httpAgentflow e os customParameters de um loader searchApi; no n8n, os queryParameters, jsonQuery, queryParametersUi e queryParametersJson de um nó n8n-nodes-base.httpRequest, usado como ferramenta ou não, os parametersQuery e jsonQuery de um nó @n8n/n8n-nodes-langchain.toolHttpRequest, e os queryParameters e queryParametersJson que um nó n8n-nodes-base.facebookGraphApi mantém entre suas options. Cada um é enviado como a consulta de uma requisição, e um parâmetro de consulta pode conter uma chave — algumas APIs de busca recebem a sua como api_key na consulta —, então cada um é localizado como os cabeçalhos: cada valor, com seu nome mantido, qualquer que seja a forma dos parâmetros, e cada um relatado por seu nome; parâmetros escritos como texto são localizados inteiros, exceto no Flowise e no n8n, onde o texto os contém como um objeto JSON, que, escrito vazio, é reescrito no lugar e relatado uma única vez com os nomes que contém. Escritos vazios, todos os valores ficam vazios, incluídos os dos parâmetros que não contêm nenhum segredo, então uma requisição importada é enviada com eles vazios — ou, a partir de um nó HTTP do Flowise, que não envia nenhum parâmetro cujo valor esteja vazio, sem eles — até que seu autor os restaure.
  • Cabeçalhos padrão e uma consulta padrão em um nó OpenAI que nenhuma conexão alcança — os default_headers e o default_query de um nó OpenAIEmbeddings do Langflow, e os baseOptions de um nó chatOpenAI ou openAIEmbeddings do Flowise, onde quer que o nó esteja, incluída a configuração do modelo que um agentflow seleciona, onde o rascunho nem conecta o nó nem encontra uma conexão que o alcance tal como está escrito; onde o faz, eles são cabeamento, como acima. Cada um é localizado inteiro e, escrito vazio, mantém seu tipo — um objeto como {}, uma lista como [], texto como uma string vazia — e é relatado uma única vez.
  • Uma requisição inteira escrita como linha de comando — o curl_input de um nó APIRequest do Langflow e o curl de um nó Webhook, localizados inteiros, incluído o valor padrão do Webhook. Nenhum dos dois é lido quando o fluxo é executado: o primeiro apenas preenche os campos do nó no editor, o segundo mostra um exemplo.
  • Uma entrada que contém uma credencial sob o nome de uma credencial — o api_key de um nó OlivyaComponent do Langflow, o verification_token de cada componente Composio e o mem0_config de um nó mem0_chat_memory, cujo valor inteiro mantém seu tipo quando escrito vazio; e o webhookSecret e o callbackSecret de um nó startAgentflow do Flowise e o bearerToken de um nó teradataMCP. Cada um é localizado inteiro. Uma entrada cujo nome apenas se parece com o de uma credencial — o nome de uma chave armazenada em outro lugar, um nome de usuário ou uma opção que o componente declara como não secreta — não é localizada.

Fora os valores que a configuração escreve vazios, o que o rascunho escreve para que o fluxo alcance suas partes, os handles de uma aresta do Langflow, escritos como o editor do Langflow os escreve, e os retornos de carro escritos como avanços de linha descritos abaixo, o fluxo é levado como foi exportado: sem nada disso, byte a byte.

Uma conexão no rascunho não leva nenhum valor de credencial: a Release rascunho vincula por referência a que cada conexão apresenta, como descreve O que o rascunho deixa para a Release.

Cada valor que a configuração deixa como está escrito chega ao rascunho, e o autor o revisa, guiado pelos avisos credential-carried. Nenhuma regra sobre um campo alcança tampouco o resto de um fluxo, então o autor também o revisa antes de compartilhar um rascunho: o próprio código de um componente, que o fluxo leva e no qual um componente personalizado pode conter uma chave; entradas que o editor adiciona a um nó além das que seu componente declara; o corpo com que uma requisição é enviada, como o de um nó APIRequest ou httpAgentflow, que pode conter um token; os argumentos que um nó passa ao cliente de seu modelo ou a um loader como um objeto próprio, como os model_kwargs de um nó EmbeddingModel do Langflow ou os additionalInputs de um nó replicate do Flowise, que podem conter uma chave sob qualquer nome; um endereço que não seja o de um servidor MCP, que pode conter uma chave em sua parte de usuário ou em sua consulta; o código de um nó Code do n8n, e os cabeçalhos ou a consulta de um nó que envia uma requisição que o importador não lista acima; e texto livre, como um prompt ou uma mensagem.

O que o rascunho deixa para a Release

A Release rascunho leva, na entrada da plataforma e na de cada parte, o que o fluxo não pode fornecer:

  • A imagem da plataforma, como infra.image: a escolha de imagem do próprio importador, na versão com que se sabe que as Recipes do catálogo para a plataforma rodam — langflowai/langflow:1.6.0, flowiseai/flowise:3.1.3 e n8nio/n8n:1.110.1 —, sob um comentário que diz isso. A importação nunca a sobe nem a desce para acompanhar a origem; onde a exportação declara uma versão diferente da plataforma, como faz o last_tested_version de um fluxo do Langflow, o comentário a nomeia.
  • A porta em que a plataforma é publicada, como infra.published_port, apenas com --target compose: 7860 para Langflow, 3000 para Flowise e 5678 para n8n, as portas em que cada uma atende, que sua Recipe do Compose publica no endereço de loopback do host, 127.0.0.1. O comentário acima dela diz que a porta só é acessível a partir desta máquina, por qualquer processo em execução nela, e que excluir a linha mantém o serviço interno. Um segundo fluxo de uma mesma importação recebe a próxima porta que nenhum anterior recebe. Com qualquer outro destino, ou sem nenhum, ela não é escrita.
  • O segredo próprio da plataforma e a credencial de cada conexão de modelo, vinculados por referência e nunca como valor: no Langflow, a ranhura admin_password, lida enquanto values.require_authentication continuar true; no Flowise, a ranhura owner_password, obrigatória enquanto values.flow_definition estiver definido; e, onde uma parte está conectada ao socket model da plataforma, a credential nessa conexão. A plataforma n8n não recebe nenhum segredo próprio. Como cada um é vinculado depende do destino, como descreve Segredos, para cada destino.
  • Cada valor que nenhuma origem contém, escrito como uma string vazia sob um comentário que diz o que ele é: no Flowise, infra.owner_email, o e-mail da conta do proprietário, obrigatório enquanto values.flow_definition estiver definido; e o endereço de cada servidor MCP conectado à plataforma, infra.endpoint de sua parte. Cada um é um valor que a importação deve, respondido como descreve O arquivo de respostas da importação.

A credencial que uma conexão com uma ferramenta ou um repositório vetorial apresenta não é gerada no rascunho: a credencial de tal conexão interrompe o build onde a ferramenta não publica nenhum cabeçalho para enviá-la, então um comentário acima da entrada da plataforma a nomeia, para que você a vincule onde a ferramenta aceitar uma.

Segredos, para cada destino

Em --target helm, cada segredo é um core/referenced-secret cujo origin é o nome de um Secret do Kubernetes que já está no namespace e que contém o valor sob a chave de dados value. Nenhuma origem pode fornecer esse nome, então ele é escrito vazio sob um comentário que diz o que ele contém, e fica entre os valores que a importação deve; o Manifest gerado como rascunho mapeia core/referenced-secret para helm/k8s-existing-secret.

Em qualquer outro destino, e sem destino, cada segredo é um core/secret-value cujo origin é uma referência a uma variável — ${LANGFLOW_ADMIN_PASSWORD}, ${FLOWISE_OWNER_PASSWORD} e ${OPENAI_API_KEY} para a credencial de uma conexão com um modelo — que um destino que substitui referências a variáveis, como faz o Docker Compose quando a stack é iniciada, lê do ambiente, de modo que nenhum arquivo contém o valor e nada é devido por ele. O chatflow do Flowise acima, importado sem destino, é gerado como rascunho com 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: {}

Sem destino, ela deve dois valores, spec.manifest e infra.owner_email; com --target compose, apenas o e-mail do proprietário; com --target helm, o e-mail do proprietário e os nomes dos dois Secrets do Kubernetes.

No destino compose, um segredo que a Release sozinha vincula chega sob uma única chave, value, então a senha do proprietário ou do administrador e a credencial de uma conexão chegariam ambas sob ela. Por isso o Aggregate declara cada uma com uma chave própria onde a plataforma aceita uma conexão: owner_password com a chave OWNER_PASSWORD no Flowise, admin_password com a chave LANGFLOW_SUPERUSER_PASSWORD no Langflow e a credential da conexão com o modelo com a chave OPENAI_API_KEY nas três plataformas, cada uma sob um comentário que explica o motivo. Com --target compose, essas linhas são escritas ativas; sem destino, são escritas comentadas, como no exemplo acima, para que você as descomente se fizer o build para compose; com qualquer outro destino, não são escritas. A Release vincula a origem de cada ranhura, nomeando o mesmo tipo ou nenhum.

Com a configuração attach_egress_allowlist em true, a instância da plataforma também declara a Feature core/egress-allowlist da biblioteca padrão sob features, como egress-allowlist, de modo que a plataforma se conecta apenas aos componentes que suas conexões alcançam, aos seus próprios pods e ao DNS do cluster — a contrapartida de saída de uma aresta uses como chamada declarada. O Aggregate declara o tipo da vinculação e nada mais, já que a vinculação de um Aggregate não leva nenhum infra, e a Release gerada como rascunho não escreve nada disso: o comentário acima da entrada da plataforma nomeia, sob features.egress-allowlist.infra, control_plane_present, que o operador define como true para afirmar que o plugin de rede do cluster aplica a política de rede, sem o que o build é interrompido; admitted_destinations, uma lista que contém, para cada conexão cujo destino o cluster não executa, como um modelo hospedado, uma entrada que nomeia o destino e um intervalo de endereços, sem a qual o build é interrompido nomeando essa conexão; e aggrega.ai/namespace para a fronteira que contém a plataforma, já que a política é colocada no namespace de suas cargas de trabalho e o build é interrompido onde elas não são emitidas em nenhum. Nenhuma dessas chaves é escrita vazia, então nenhuma está entre os valores que a importação deve. A decisão de cada parte conectada diz que a vinculação admite sua conexão, e a importação relata a vinculação como feature-attached. O Compose não tem política de rede, então um build de compose de um rascunho desse tipo é interrompido nomeando a vinculação; onde a plataforma aceita uma conexão, as linhas de compose acima são escritas dentro do bloco features da instância, sem uma segunda chave features.

O modelo que uma parte serve

Uma parte à qual o rascunho faz referência e cujo Component declara um valor chamado model — como faz, e exige, cada Component de modelo da biblioteca padrão — é escrita com o nome do modelo que seu nó seleciona, como values.model:

  • Langflow — o model_name de um nó OpenAIModel ou AnthropicModel; o model de um nó OpenAIEmbeddings; e a sobrescrita model_name de um nó LanguageModelComponent ou EmbeddingModel onde estiver definida, e, caso contrário, o modelo que seu campo model seleciona.
  • Flowise — o modelName de um nó chatOpenAI, chatAnthropic ou openAIEmbeddings.
  • n8n — o parâmetro model de um nó de chat, de completion ou de embeddings que a tabela do importador mapeia, ou seu modelName nos nós Google Gemini e Vertex, escrito como um nome ou como o valor do seletor em que os nós mais novos do n8n o mantêm. O n8n deixa de fora de uma exportação um parâmetro definido com seu valor padrão, então um nó que mantém o modelo padrão não nomeia nenhum na exportação.

Uma Release não pode escrever um valor. Assim, onde o nó não nomeia nenhum modelo que o rascunho possa escrever — não seleciona nenhum, o nomeia por meio de uma variável global ou de uma expressão lida apenas quando o fluxo é executado, o obtém de outro nó conectado a ele, ou é de um tipo cujo campo de modelo o importador não lê —, um comentário dentro da parte deixa values.model para o autor, e a importação o relata com model-not-named. Uma parte que o rascunho gera como rascunho é escrita sem nenhum valor.

Como o fluxo é escrito no rascunho

O fluxo é escrito como um bloco literal YAML cujo chomping mantém suas quebras de linha finais, de modo que values.flow_definition é lido de volta como o próprio texto do fluxo. O texto de um Aggregate é lido como um template, então cada {{ que o fluxo contém — um chatflow do Flowise escreve {{<node id>.data.instance}} para cada conexão entre dois nós — é escrito como {{"{{"}}, que a interpolação converte de volta nas duas chaves, como descreve Texto que contém suas próprias chaves duplas. O nome de um modelo é escrito da mesma forma.

Um bloco literal não pode levar todo caractere como está escrito:

  • Um retorno de carro — de um par CR LF, ou isolado — é escrito como um único avanço de linha. Um documento JSON só contém um entre seus tokens, onde qualquer espaço em branco é lido da mesma forma, então a plataforma lê o mesmo fluxo. A importação relata quantos há com carriage-returns-rewritten.
  • Qualquer outro caractere que um bloco literal não possa levar impede que o fluxo seja levado: um caractere de quebra de linha — U+0085, U+2028 ou U+2029; um caractere de controle que não seja a tabulação nem o avanço de linha — de U+0000 a U+001F, U+007F, e de U+0080 a U+009F; os não caracteres U+FFFE e U+FFFF; e um byte que não faz parte de uma sequência UTF-8. values.flow_definition é então deixado sem definição, com um comentário dizendo isso, o resto é gerado como rascunho, e a importação relata definition-not-carried para cada tipo de caractere, com quantos o fluxo contém e a linha e a coluna do primeiro.

O fluxo também não é levado onde um valor que o rascunho escreve vazio ou de novo não está nos bytes da exportação onde sua árvore analisada o contém, e a importação relata definition-not-carried nomeando o lugar desse valor. O identificador do fluxo é então o seu próprio onde o rascunho pode levá-lo e, caso contrário, um derivado dos identificadores dos nós do fluxo.

Nó a nó

Com layout: nodes, uma importação gera como rascunho cada nó do fluxo como um Component próprio, e escreve:

  • aggregate.yaml — um Aggregate de rascunho com o nome do fluxo, como descreve Como um rascunho é nomeado, que compõe os nós do fluxo: uma entrada para cada um, e cada aresta do fluxo como uma conexão uses do nó que ela alimenta, com seu socket e seu alias ambos nomeados de acordo com a chave do nó que a alimenta, de modo que um nó alimentado por vários dá a cada conexão um alias próprio.
  • um arquivo sob components/ para cada nó que gera como rascunho — um Component de rascunho chamado <target_namespace>/<category>/<name>, com o nome tirado do tipo do nó, na versão 0.1.0, com seus campos de valor como campos de string de um objeto values fechado e seus campos de credencial como ranhuras de credencial obrigatórias cuja entrega uma Recipe decide.
  • release.yaml — uma Release em rascunho com o mesmo nome, que nomeia esse Aggregate, com uma entrada para cada nó.

O próprio fluxo não é levado, e o valor de nenhum campo é lido.

Levar o próprio fluxo exportado

O rascunho padrão leva o fluxo: a instância da plataforma recebe a exportação como values.flow_definition, escrita como descreve Como o fluxo é escrito no rascunho. Um autor que escreve um fluxo à mão em um Aggregate — em um rascunho organizado nó a nó, ou em um Aggregate próprio — o escreve da mesma forma. Um Component que executa um fluxo como foi criado recebe a exportação como um valor — flow_definition em core/ai-agent/langflow e core/ai-agent/flowise da biblioteca padrão — e o texto de um Aggregate é lido como um template, então as chaves duplas que a exportação contém seriam lidas como ações de template: um chatflow do Flowise escreve {{<node id>.data.instance}} para cada conexão entre dois nós, um prompt do Flowise nomeia uma variável como {{question}}, e uma exportação do Langflow leva o código-fonte de seus componentes, onde as chaves também podem aparecer. Escreva cada {{ da exportação como {{"{{"}}, dentro de um escalar de bloco, e a interpolação restaura o texto da exportação antes que as Recipes do Component o leiam; Texto que contém suas próprias chaves duplas descreve por quê. Um valor de credencial que a exportação contém pertence a um segredo que a Release vincula, não ao Aggregate: escreva-o vazio, como faz o rascunho onde a configuração empty_credentials pede isso.

# 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": []
}

O importador MCP

importer/mcp lê os servidores MCP que a configuração de um cliente MCP lista, ou o único servidor que uma descrição de servidor do registro MCP descreve, e gera como rascunho cada servidor como uma instância da ferramenta MCP da biblioteca padrão, core/ai-tool/mcp. Todo servidor é uma delas, então o importador não pontua nenhum candidato e não relata nenhuma decisão de mapeamento.

O que ele lê

  • A configuração de um cliente. O .mcp.json do Claude Code, o claude_desktop_config.json do Claude Desktop e o .cursor/mcp.json do Cursor listam seus servidores por nome sob mcpServers; o .vscode/mcp.json do Visual Studio Code os lista sob servers, e um arquivo que lista servidores sob ambos é lido primeiro sob mcpServers. Um servidor cujo type é stdio, ou que não nomeia nenhum type e traz um command, é iniciado a partir de uma linha de comando — seu command e seus args — com seu env como ambiente. Um servidor cujo type é http, streamable-http ou sse, ou que não nomeia nem type nem command e traz uma url, é alcançado em sua url e recebe seus headers.
  • Uma descrição de servidor do registro. O server.json que o registro MCP publica: seu name, e seu primeiro pacote ou, onde não lista nenhum, seu primeiro remoto. Um pacote npm ou PyPI é iniciado a partir da linha de comando que seu lançador — seu runtimeHint, ou npx para npm e uvx para PyPI —, seus runtimeArguments, o pacote com sua versão, escrito <identifier>@<version> para npm e <identifier>==<version> para PyPI, e seus packageArguments formam, com suas environmentVariables como ambiente. Um argumento posicional é seu value, ou seu default; um argumento nomeado é escrito <name>=<value> onde tem um dos dois, e como seu name onde não tem nenhum. Um pacote OCI é executado a partir da imagem que seu identifier nomeia. Um remoto é alcançado em sua url e recebe seus headers. Cada outro pacote e remoto que a descrição lista é nomeado em um comentário, já que uma instância executa apenas um deles.

Qualquer outro membro de um servidor — cwd, envFile, o auth do Cursor, ou um membro que seu tipo de servidor não lê, como a url de um servidor iniciado a partir de uma linha de comando — não é escrito em lugar nenhum, e é nomeado em um comentário acima da entrada do servidor na Release, já que nenhuma chave de infraestrutura de core/ai-tool/mcp o aceita. Os inputs de uma configuração, que descrevem o que o Visual Studio Code pede ao usuário e não contêm nenhum valor, não são lidos. Os servidores, seu ambiente e seus cabeçalhos mantêm a ordem em que a origem os escreve, exceto em uma configuração lida como JSON com comentários, que mantém a ordem em que sua árvore analisada os escreve: a ordem dos nomes (veja Uma configuração que contém comentários).

Um diretório é lido por meio das configurações de cliente que contém — cada arquivo com o nome de uma das quatro, em qualquer profundidade — na ordem de seus caminhos, e cada servidor de cada arquivo é gerado como rascunho em um único Aggregate.

No que um servidor se torna

aggregate.yaml é um Aggregate de rascunho que leva o nome da origem, como Como um rascunho é nomeado descreve, e que contém uma instância de core/ai-tool/mcp por servidor. Uma instância tem como chave o nome de seu servidor, em minúsculas, com cada sequência de caracteres que não sejam letras e dígitos escrita como um único hífen, e um sufixo numérico onde um servidor anterior tomou a chave. Onde a chave não é o nome do servidor como está escrito, ou a importação leu vários arquivos, um comentário acima da instância nomeia o servidor e o arquivo de onde ele veio. Nenhum agente é gerado como rascunho para usá-los.

Ao lado dele, release.yaml é uma Release de rascunho com o mesmo nome, cujo spec.aggregate nomeia o Aggregate, levando para cada instância as entradas operacionais que a origem declara:

  • para um servidor iniciado a partir de uma linha de comando, infra.stdio_command, seu comando e depois cada argumento, um item cada; e infra.stdio_runtime, o ecossistema do lançador, npm onde o comando é npx, npm ou node, pypi onde é uvx, uv, python ou python3 e, para um pacote do registro, seu registro, npm ou pypi;
  • para um servidor alcançado em um endereço, infra.endpoint: o endereço sem sua parte de usuário, sua consulta e seu fragmento, já que o Component aceita o endereço sem nenhuma parte que contenha uma chave; cada parte que ele omite é escrita no comentário acima da entrada, ao lado do endereço, como descreve Valores de credenciais que um servidor contém;
  • para um pacote OCI, infra.image;
  • para nenhum servidor, em nenhum destino, infra.published_port: o rascunho nunca publica um servidor no host;
  • para o ambiente de um servidor, a ranhura server_env, vinculada por referência conforme o destino da importação. Em --target helm, é um core/referenced-secret que nomeia um Secret do Kubernetes que já está no namespace e que contém uma chave de dados por variável, cada uma com o nome da variável que contém; o nome do Secret é escrito vazio, sob um comentário que nomeia as chaves de dados, e fica entre os valores que a importação deve. Em qualquer outro destino, e sem destino, é um core/referenced-secret-set com uma entrada sob infra.entries por variável, cuja chave é o nome da variável e cujo valor é o que a origem escreve, de modo que uma referência a variável como ${GITHUB_TOKEN} continua sendo uma referência, que um destino que substitui referências a variáveis lê do ambiente.

O que a origem não declara é escrito vazio, sob um comentário que diz o que é: um comando cujo lançador não está em nenhuma das duas imagens de ponte deixa infra.stdio_runtime vazio, e ele fica entre os valores que a importação deve; um argumento que uma descrição do registro deixa para seu usuário é escrito como um item vazio, e uma variável cujo valor a origem não escreve, como uma entrada com valor vazio, cada um nomeado no comentário acima da entrada.

Como toda Release gerada como rascunho, ela escreve metadata.environment como development, sob um comentário que diz que é um valor padrão do rascunho a ser alterado, e, sem destino, spec.manifest como uma string vazia que a importação deve. Dado um destino, o importador gera o próprio Manifest como rascunho, já que o catálogo realiza core/ai-tool/mcp por meio de várias Recipes e só o importador sabe como cada servidor é executado: ele mapeia cada servidor pela sua chave, sob mappings.components.name, para a realização do destino para a forma como o servidor é executado — mcp-stdio-bridge para uma linha de comando, mcp-remote para um endereço, mcp para uma imagem, como helm/mcp-stdio-bridge ou compose/mcp-remote — e o tipo de segredo com que o ambiente é vinculado para sua realização, helm/k8s-existing-secret no helm e compose/dotenv-secret-set no compose. A importação completa esse Manifest e o nomeia na Release, como descreve O que um destino adiciona.

Um .mcp.json do Claude Code que lista um servidor alcançado via HTTP e outro iniciado com 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}" }
}
}
}

é gerado como rascunho assim:

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 com --target helm, a Release da mesma configuração vincula o ambiente como o Secret que ela nomeia, e o Manifest que o importador gera como rascunho mapeia cada servidor pela sua chave:

# 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 credenciais que um servidor contém

Cada valor da configuração de um servidor que a Release escreve — o valor de cada cabeçalho, cada item de sua linha de comando, seu endereço, cada parte do endereço que infra.endpoint omite e cada valor de ambiente — pode conter uma chave, e nenhum cliente marca nenhum como credencial, então a importação localiza cada um como membro da configuração de um servidor MCP; uma entrada do registro marcada com isSecret é localizada como um valor que seu formato marca como credencial. Uma entrada do registro — uma variável de ambiente ou o cabeçalho de um remoto — é lida como seu value, ou seu default onde não escreve nenhum. Por padrão, cada um é levado como está escrito para a Release e nomeado em um aviso credential-carried por seu servidor e seu lugar — headers.<header>, infra.stdio_command.<position>, infra.endpoint ou server_env.<variable>, e uma parte do endereço pela url em que está escrita e pelo nome da parte, como em “url of node remote-search is carried with its query as written (a url do nó remote-search é levada com sua consulta como está escrita)” — nunca por seu valor. Com a configuração empty_credentials em marked ou all, cada um é escrito vazio e relatado com credential-emptied: um item da linha de comando como um item vazio e um valor de ambiente como um valor vazio, cada um nomeado no comentário acima da entrada; um endereço como um infra.endpoint vazio, que a importação deve; e o valor de um cabeçalho ou uma parte do endereço omitidos do comentário, que nomeia apenas o cabeçalho ou a parte. O infra.stdio_runtime de um cliente é lido do comando como a Release o escreve, então um comando escrito vazio também o deixa vazio, e a importação o deve. Em --target helm, a Release não escreve nenhum valor de ambiente: o Secret que a ranhura server_env nomeia os contém.

Um valor que é uma referência a uma variável e nada mais — o nome simples ${NAME}, entre eles uma variável predefinida como ${workspaceFolder}, ${env:NAME} ou ${input:id} — não contém nenhum valor próprio: é escrito como o texto que é, independentemente do que diga a configuração, e não é nomeado em nenhum aviso, assim como uma referência em um fluxo. Uma variável de ambiente cujo valor é uma delas é escrita como o valor da entrada, e a referência continua sendo uma referência, e um cabeçalho ou uma parte do endereço cujo valor é uma delas é listado com a referência da qual lê. Uma referência que traz texto após um operador — um valor padrão, uma alternativa, uma mensagem ou uma atribuição, como ${NAME:-value} ou ${NAME-value}, com ou sem dois-pontos — contém esse texto, e o mesmo vale para texto ao lado de uma referência; cada um é localizado como qualquer outro valor.

Nenhuma chave de infraestrutura de core/ai-tool/mcp aceita o valor de um cabeçalho: a credencial de um servidor remoto é mantida por cada consumidor, em sua conexão com a ferramenta, e a importação não gera nenhum consumidor como rascunho. Então o comentário acima da entrada do servidor lista cada cabeçalho que a origem envia a ele, ao lado de seu valor como está escrito — uma string entre aspas duplas que é lida de volta exatamente como o texto da origem — para que você o mova para a conexão do consumidor que o apresenta. Um cabeçalho cujo valor a origem não escreve, como uma entrada de cabeçalho do registro sem valor nem valor padrão, é listado como não tendo nenhum. A imagem que um pacote OCI nomeia é escrita como está, e não é um valor que a configuração alcança.

infra.endpoint aceita o endereço sem nenhuma parte que contenha uma chave, então as partes do endereço que a origem escreve e que ele omite — a parte de usuário antes do @, a consulta depois do ? e o fragmento depois do #, sendo fragmento tudo o que vem após o primeiro # — são listadas no mesmo comentário, cada uma ao lado de seu nome e como está escrita, sem o @, o ? ou o # que a separa. Um consumidor que lê sua chave do endereço fornece o endereço inteiro em sua própria conexão com a ferramenta. Um servidor alcançado em https://user:pw@api.example.com/mcp?key=k, sem nenhuma configuração, é gerado como rascunho assim:

# 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"

e com empty_credentials em marked, infra.endpoint é deixado para a Release e o comentário lista user part e query, cada um com seu valor omitido.

Uma configuração que contém comentários

O Visual Studio Code lê .vscode/mcp.json como JSON com comentários, e o importador MCP também: sua assinatura para esse arquivo o lê por meio do analisador que serve parse:jsonc, então uma configuração que contém comentários // e /* */ e vírgulas finais é reconhecida sem que nenhum formato seja nomeado, e o importador lê cada origem que lista seus servidores sob servers por meio desse analisador. Uma configuração desse tipo é gerada como rascunho exatamente como a mesma configuração sem seus comentários e vírgulas finais. O analisador escreve os membros de um objeto na ordem dos nomes, então os servidores de uma configuração desse tipo, seu ambiente e seus cabeçalhos são gerados como rascunho na ordem dos nomes, contenha ela ou não um comentário; uma linha de comando mantém sua ordem. Os outros clientes e o registro leem seus arquivos como JSON, e o importador também: um .mcp.json, claude_desktop_config.json, .cursor/mcp.json ou server.json que contém um comentário não é reconhecido por nenhuma assinatura e, importado nomeando --format mcp, é interrompido com parse-failed e o motivo do analisador. Um comentário aberto com /* e nunca fechado é deixado como está escrito, e o analisador recusa o arquivo.

As configurações que ele lê

O importador MCP lê target_namespace e empty_credentials, como Configurações os descreve, e nenhuma outra configuração.

O importador Compose

importer/compose lê os serviços e os modelos que um arquivo Compose declara. Ele gera como rascunho cada serviço como uma instância do Component do catálogo ao qual sua imagem corresponde, ou do servidor genérico da biblioteca padrão, core/compute/server, executando sua imagem; cada modelo como uma instância do ambiente de execução Docker Model Runner da biblioteca padrão, core/ai-model/docker-model-runner, onde seu catálogo o contém, e como um Component de modelo próprio onde não o contém; e, ao lado deles, uma Release que leva o que cada serviço declara para sua operação.

O que ele lê

  • Os arquivos. Um arquivo importado sozinho é lido sozinho. Um diretório é lido como o Compose lê um: em cada diretório que contém arquivos Compose, na ordem dos caminhos dos diretórios, o primeiro presente entre compose.yaml, compose.yml, docker-compose.yml e docker-compose.yaml é o arquivo Compose, e o primeiro presente entre compose.override.yml, compose.override.yaml, docker-compose.override.yml e docker-compose.override.yaml é mesclado sobre ele. Nenhum outro desses arquivos é lido. Em um diretório que contém arquivos de sobrescrita e nenhum arquivo Compose, seu primeiro arquivo de sobrescrita é lido sozinho. Um comentário no início do Aggregate de rascunho nomeia os arquivos lidos, na ordem em que são mesclados, e os arquivos não lidos. Cada serviço e cada modelo de cada diretório é gerado como rascunho em um único Aggregate.
  • A mesclagem. Um arquivo de sobrescrita é mesclado como o Compose mescla um: image é substituído; as ports são mescladas por seu endereço, sua porta publicada, sua porta do contêiner e seu protocolo, os volumes por seu caminho no contêiner, e environment por nome de variável, com uma entrada posterior tomando o lugar de uma anterior e uma nova vindo em seguida; expose é acrescentado ao final; depends_on e os models de um serviço são unidos, com endpoint_var e model_var de uma entrada tomando cada um o lugar do que um arquivo anterior declara. De um modelo, model e context_size são substituídos e runtime_flags é acrescentado ao final. As tags !reset e !override do Compose não são respeitadas: um valor que traz uma delas é mesclado como o analisador YAML o lê.
  • Um serviço. Sua image, e se ele constrói uma sob build; suas ports, expose, volumes e environment — um mapeamento, ou uma lista de itens NAME=value, com um nome sem valor recebendo seu valor do ambiente em que o Compose é executado; depends_on, uma lista ou um mapeamento; e seus models, uma lista de nomes de modelos ou um mapeamento cujas entradas podem nomear, sob endpoint_var e model_var, as variáveis com as quais o endereço e o identificador do modelo chegam ao serviço. Qualquer outro membro — command, healthcheck, secrets, env_file e o resto — não é escrito em lugar nenhum, e é nomeado em um comentário acima da entrada do serviço na Release.
  • Um modelo. Cada entrada dos models de nível superior: seu model, o identificador OCI do modelo, seu context_size e seus runtime_flags, levados como estão escritos para uma instância de core/ai-model/docker-model-runner onde seu catálogo o contém, e de um Component de modelo gerado como rascunho para ele onde não o contém; a decisão do modelo diz qual, e por quê. Qualquer outro membro é nomeado em um comentário acima de sua instância.
  • O resto. Os outros membros de nível superior — name, networks, volumes, secrets, configs — não são lidos, e o comentário no início do Aggregate os nomeia.

Os serviços, os modelos e o ambiente de um serviço mantêm a ordem em que o arquivo os escreve. A árvore do analisador escreve os membros de um mapeamento em ordem classificada, então essa ordem é lida do texto do arquivo, onde eles estão escritos como um mapeamento em bloco; um mapeamento escrito em estilo flow mantém a ordem classificada.

Qual Component é um serviço

O importador encontra a correspondência de um serviço pelo repositório que sua imagem nomeia: a referência sem sua tag e seu digest, com uma referência do Docker Hub escrita em sua forma curta — postgres para docker.io/library/postgres:16. Ele encontra a correspondência do repositório por meio de sua tabela de imagens, uma tabela que vai do repositório de uma imagem ao Component do catálogo para o qual uma Recipe do Compose do catálogo padrão executa uma imagem desse repositório. A tabela é gerada a partir das Recipes do Compose e dos Components do catálogo padrão quando o importador é construído, e compilada nele, então nenhuma Recipe é lida quando uma importação é executada e a tabela contém os rótulos do catálogo padrão, independentemente do que seu catálogo contém; a entidade Plugin do importador nomeia, em sua descrição, a revisão do hub a partir da qual a tabela foi gerada. De cada Recipe, a tabela lê o Component que a Recipe implementa e a imagem de seu contêiner chamado main, onde essa imagem escreve seu repositório em seu próprio texto, ou é uma entrada de locals que o faz. Uma Recipe que executa a imagem que a Release nomeia por inteiro, ou uma que seu template compõe de outra forma, não acrescenta nenhuma linha, e uma imagem que uma Recipe executa ao lado de seu contêiner principal também não. Duas Recipes que nomeiam um mesmo repositório para Components diferentes impedem que a tabela seja gerada, de modo que uma linha nunca nomeia um de dois. Do Component que uma linha nomeia, a tabela lê seus rótulos como eles são entregues a uma importação — na versão para a qual se resolve uma referência que nomeia o Component sem versão, com os que ele herda por meio de extends — e escreve cada rótulo exceto component.aggrega.ai/category na linha como seus traços. Uma Recipe que implementa um Component que o catálogo padrão não contém também impede que a tabela seja gerada.

Uma linha é lida como é lida a linha da tabela de um importador de fluxos: o Component, a categoria em que seu nome o coloca, seus traços e o último segmento de seu nome como seu fornecedor. A configuração mapping_overrides se sobrepõe à tabela sob o formato compose, tendo o repositório como chave, e uma entrada para um repositório que a tabela mapeia toma o lugar da linha. Assim, uma imagem que as Recipes do catálogo padrão não nomeiam — a sua, ou uma que um Component do catálogo executa sob outro repositório — é mapeada por uma entrada:

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

Um serviço cuja imagem uma linha mapeia é decidido como os importadores de fluxos decidem um nó: pontuado em relação aos Components do seu catálogo, referenciado onde reuse_mode é auto-apply-above-threshold, o padrão, e seu melhor candidato é uma correspondência de nível alto igual ou superior a reuse_threshold, e gerado como rascunho como um Component próprio caso contrário, com o arquivo do Component gerado como rascunho começando com um comentário que nomeia o Component com o qual ele se parece. Uma linha traz os rótulos do Component que nomeia, então onde seu catálogo contém esse Component com os rótulos que o catálogo padrão lhe dá, um serviço que a linha mapeia é uma correspondência de nível alto para ele, com pontuação 0.90, e auto-apply-above-threshold o referencia no reuse_threshold padrão. Um Component cujos rótulos seu catálogo alterou obtém uma pontuação menor, em proporção à parcela dos traços da linha que ele não traz mais, e só é referenciado enquanto permanece no nível alto; a categoria é pontuada uma única vez, em seu próprio sinal, e não novamente como traço. Serviços que geram como rascunho um mesmo Component compartilham seu único arquivo. Um serviço cuja imagem nenhuma linha mapeia, cuja imagem não nomeia nenhum repositório que o importador lê, ou que constrói sua imagem, é uma instância de core/compute/server, independentemente do que seu catálogo contém. A decisão de cada serviço é relatada como a de cada nó.

No que um serviço se torna

aggregate.yaml é um Aggregate de rascunho que leva o nome do projeto, como Como um rascunho é nomeado descreve, e que contém uma instância por serviço, do Component que sua decisão escolheu, com a chave atribuída como o importador MCP atribui a chave a um servidor, e um comentário acima dela que nomeia o serviço e o arquivo de onde ele veio onde a chave não é o nome do serviço ou a importação leu vários diretórios. Cada serviço que o depends_on de um serviço nomeia é uma conexão, uses: <key>: <key>: {target: <key>}, escrita sob um socket e um alias, ambos com o nome da chave do destino. Um componente lê cada uma de suas conexões pelo seu alias, qualquer que seja o socket ao qual ela esteja ligada, então cada conexão de um serviço tem um alias próprio. Uma variável do ambiente de um serviço também pode gerar uma conexão, entregando a variável a partir do que o serviço que ela alcança publica, como descreve O que o ambiente e a imagem de um serviço se tornam. Cada modelo é uma instância de core/ai-model/docker-model-runner onde o catálogo do espaço de trabalho o contém, independentemente do que diga reuse_mode, e nenhum Component é gerado como rascunho para ele: a instância escreve model e runtime_flags como a origem os declara, e o context_size da origem como context_window, o valor que o ambiente de execução declara para o comprimento de contexto de um modelo, que sua Recipe do Compose escreve de volta como o context_size do Compose. Onde o catálogo não contém nenhum core/ai-model/docker-model-runner, o modelo é gerado como rascunho como <target_namespace>/ai-model/<key>, um Component da categoria ai-model cujos valores declaram model, context_size e runtime_flags, e sua instância escreve cada um dos que a origem declara. Todo modelo tem uma decisão que diz qual — mapped llm (model) to core/ai-model/docker-model-runner as a reference, NONE, ou um rascunho cuja decisão registra que o catálogo do espaço de trabalho não contém nenhum core/ai-model/docker-model-runner — e cada serviço que nomeia o modelo é conectado a ele em ambos os casos, como a um serviço do qual depende. Um serviço que nomeia o modelo na forma longa, com endpoint_var ou model_var, nomeia as variáveis com as quais seu endereço e seu identificador chegam ao serviço. Nenhuma chave do rascunho contém o nome de uma variável — a conexão é escrita em um socket com o nome do modelo, que não declara nenhum valor, e nenhuma chave de infraestrutura de um Component é entregue a um importador — então um comentário acima da conexão nomeia cada uma, como a entrada a escreve, e a decisão do serviço registra a mesma 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

Um serviço que nomeia o modelo na forma curta, ou sem nenhuma das duas variáveis, é conectado a ele sem comentário.

Ao lado dele, release.yaml é uma Release de rascunho com o mesmo nome, cujo spec.aggregate nomeia o Aggregate. Para uma instância de core/compute/server, ela escreve infra.image, a imagem como está escrita, e infra.port, a porta em que o contêiner escuta na primeira entrada de ports, ou de expose onde ports não contém nenhuma. Com --target compose, ela também escreve infra.published_port, a porta do host que essa mesma entrada de ports publica, como a origem a declara, sob o comentário que diz que ela só é acessível a partir desta máquina, por qualquer processo em execução nela, e que excluir a linha mantém o serviço interno; uma porta do host abaixo de 1024, que published_port não aceita, não é escrita, e um comentário acima da entrada a nomeia. Um comentário acima da entrada de cada serviço escreve o que a origem declara e nenhuma chave do rascunho leva — a imagem de um serviço que corresponde a outro Component cuja tag o rascunho não traduz, suas ports, expose, volumes, e cada variável de seu environment que o rascunho não traduz — para que você o leve para onde o Component o aceita. O que o rascunho deixa para a Release — a imagem de um serviço que não nomeia nenhuma, como faz um que constrói a sua própria, e uma porta que não é um único número — é escrito vazio sob um comentário que diz por quê. Um build coloca apenas as instâncias que uma Release nomeia, então a instância de cada modelo tem uma entrada vazia, <key>: {}, depois das dos serviços: tanto uma instância de core/ai-model/docker-model-runner, que no Compose não aceita nenhuma entrada sem valor padrão, quanto um modelo gerado como rascunho como um Component próprio, de modo que o modelo gerado como rascunho já está colocado e o build funciona assim que você escrever a Recipe que o realiza. Uma porta que o Component não aceita, como uma abaixo do mínimo de 1024 de core/compute/server, é escrita como a origem a declara, e o build é interrompido nomeando-a. A Release escreve metadata.environment e, sem destino, um spec.manifest vazio, como faz a do importador MCP; com um destino, a importação gera como rascunho o Manifest, como descreve O que um destino adiciona, mapeando cada Component para a Recipe que o realiza nesse destino — core/compute/server para compose/server ou helm/server, e core/ai-model/docker-model-runner para compose/docker-model-runner ou helm/docker-model-runner.

Um compose.yaml que executa o PostgreSQL e uma API própria que depende dele:

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

é gerado como rascunho, sem nenhuma configuração, sobre um catálogo que contém o core/datastore/postgres da biblioteca padrão, importado sozinho e com o nome do arquivo, já que o projeto não traz nenhum name, assim:

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

A importação relata mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9. O projeto não contém nenhum serviço cache, então CACHE_URL não gera nenhuma conexão e permanece no comentário. Com reuse_mode: hints-only, db passa a ser type: imported/datastore/postgres, gerado como rascunho em components/imported-datastore-postgres.yaml, que começa com # resembles core/datastore/postgres (score 0.9000); reference it by setting type: core/datastore/postgres; sua imagem e seu ambiente são então escritos no comentário acima de sua entrada, já que um Component gerado como rascunho não declara nenhum dos valores que as Recipes do catálogo leem. Com --target compose, o Manifest mapeia core/datastore/postgres para compose/postgres e core/compute/server para compose/server; com --target helm, para helm/postgres e helm/server.

O que o ambiente e a imagem de um serviço se tornam

Onde um serviço é uma instância do Component do catálogo que a linha de sua imagem nomeia, e o catálogo do espaço de trabalho contém esse Component, o importador lê sua imagem e seu ambiente como as Recipes do Compose do catálogo padrão para esse Component os leem, a partir do que a tabela de imagens registra de cada Recipe, e os traduz para os rascunhos:

  • A tag da imagem é a chave de infraestrutura a partir da qual a Recipe constrói a referência da imagem, como engine_version — 16 para postgres:16 — escrita na Release sob um comentário que nomeia a imagem da origem.
  • Uma variável que a Recipe define a partir de um dos valores do Component — POSTGRES_DB, POSTGRES_USER — cujo valor contém texto é esse valor da instância, database ou user, onde o Component do catálogo o declara, escrito no Aggregate sob um comentário que nomeia as variáveis.
  • Uma variável da qual a Recipe lê uma senha, como POSTGRES_PASSWORD, cujo valor é uma única referência a uma variável, é um segredo anexado nesse slot, lido da variável que a referência nomeia e declarado com a chave sob a qual a Recipe o lê.

E, para cada serviço, cada variável de seu ambiente que não é lida assim:

  • Um valor que é o nome de outro serviço do projeto, onde a linha desse serviço nomeia a chave provides que publica seu nome de host, gera uma conexão com esse serviço, cujo bloco inject entrega a variável a partir dessa chave — CACHE_HOST: cache é CACHE_HOST a partir do host do cache.
  • Um valor igual a um valor que outro serviço define para seu Component e que o Component publica — DATABASE_USER: notes ao lado de um serviço PostgreSQL que define POSTGRES_USER: notes — gera uma conexão que entrega a variável a partir dessa chave provides. Onde vários serviços ou chaves contêm o valor, é lido aquele cuja chave, ou cuja própria variável, termina como termina o nome da variável e, na falta disso, aquele do qual as outras variáveis do serviço ainda não foram lidas; caso contrário, a variável não é lida.
  • Um valor que é uma única referência a uma variável que nomeia uma variável da qual o segredo de outro serviço é lido — DATABASE_PASSWORD: ${POSTGRES_PASSWORD} — é, em uma instância de core/compute/server, um segredo próprio, anexado sob o nome da variável em minúsculas e lido da mesma variável, onde o destino escreve o segredo como um valor que o servidor aceita. helm/server recusa um core/referenced-secret, então com --target helm essa variável permanece no comentário.

Qualquer outra variável é deixada no comentário acima da entrada do serviço, como a origem a escreve. O passo a passo da importação do Compose mostra um projeto cuja API alcança seu banco de dados e seu cache dessa forma, construído e executado como gerado no rascunho.

Valores de credenciais que um serviço contém

O Compose não marca nenhum valor de ambiente como credencial, e o importador não lê o nome de nenhuma variável pelo que ele significa, então cada valor de ambiente que contém algo é localizado como uma entrada que seu formato marca como não credencial, mas que pode conter uma. Por padrão, cada um é levado como está escrito para os rascunhos — para o valor em que é traduzido, ou para o comentário acima da entrada de seu serviço na Release — e nomeado em um aviso credential-carried por seu serviço e sua variável — environment.<variable> — nunca por seu valor. Com a configuração empty_credentials em all, cada um é escrito vazio e relatado com credential-emptied: o comentário nomeia sua variável sem valor. Em marked, nenhum é escrito vazio, já que o Compose não marca nenhum. Um valor que é uma referência a uma variável que o Compose interpola e nada mais — ${NAME} ou $NAME — não contém nenhum valor próprio: é escrito como o texto que é, e não é nomeado em nenhum aviso. Uma referência que traz um valor padrão ou uma mensagem, como ${NAME:-value}, contém esse texto, e é localizada como qualquer outro valor. Um valor que o Compose lê de outro lugar — um env_file, o arquivo de um segredo — não é lido.

As configurações que ele lê

O importador Compose lê target_namespace, reuse_mode, reuse_threshold, emit_hints, render_mode, mapping_overrides e empty_credentials, como Configurações os descreve, e nenhuma outra configuração. A dica que emit_hints controla é escrita apenas no arquivo do Component gerado como rascunho; o Aggregate de rascunho não traz nenhuma.

O importador Dify

importer/dify lê uma aplicação exportada do Dify em sua DSL, o documento YAML que o Dify escreve para uma aplicação, e gera como rascunho um Aggregate que compõe a instalação do Dify da biblioteca padrão, core/dify, com a aplicação levada no parâmetro app_definition da instalação. A instalação a importa na implantação, por meio da etapa que a Recipe de seu servidor de API renderiza para ela.

O que ele lê

  • A aplicação. kind, que é app; version, a versão da DSL em que a aplicação está escrita; e app, com seu mode.
  • Um workflow ou um chatflow — mode workflow ou advanced-chat — mantém seu grafo sob workflow: cada nó de workflow.graph.nodes que nomeia seu tipo sob data.type é um nó da aplicação, na ordem em que o grafo os lista, e workflow.environment_variables contém as variáveis que ele lê.
  • Uma aplicação chat, agent chat ou completion mantém sua configuração sob model_config: seu model, cada base de conhecimento sob dataset_configs.datasets.datasets e cada ferramenta sob agent_mode.tools é um nó da aplicação, nomeado por seu lugar ali, como model_config.model. Uma aplicação do modo agent é um único nó, agent.
  • Os plugins de que ela precisa. Cada entrada de dependencies também é um nó, chamado dependencies.<n>, do tipo que a entrada nomeia, como marketplace.

Nada mais decide o que é gerado como rascunho: a aplicação inteira é levada.

No que uma aplicação se torna

aggregate.yaml é um Aggregate de rascunho que leva o nome da aplicação, como Como um rascunho é nomeado descreve, e que compõe uma entrada de core/dify, com a chave dify, cujo parâmetro app_definition leva a aplicação como está escrita — como Como o fluxo é escrito no rascunho descreve para um fluxo, de modo que as referências {{#…#}} próprias do Dify chegam à instalação como foram exportadas. A instalação estabelece ela mesma cada conexão de seu servidor de API — seu banco de dados, seu cache, seu armazenamento vetorial, sua sandbox, seu ambiente de execução de plugins e seu proxy de saída — então o rascunho não gera nenhum Component como rascunho e não conecta nada: cada nó permanece na aplicação, e sua decisão diz isso. Ao lado dele, release.yaml é uma Release de rascunho com o mesmo nome, que posiciona a instalação em uma fronteira, platform, e leva o que a aplicação não pode fornecer.

Uma importação vê os Components do catálogo do workspace e nenhum de seus Aggregates, então não verifica se o catálogo contém core/dify, e um comentário acima da entrada diz isso. Onde o catálogo não contém core/ai-agent/dify, o servidor de API que core/dify executa, a importação avisa com platform-not-in-catalog e gera a entrada como rascunho mesmo assim.

O segredo de aplicação da instalação, a chave com que o Dify assina seus cookies de sessão e com a qual criptografa as credenciais dos provedores de modelos que armazena, é o parâmetro secret_key de core/dify, que não tem valor padrão. Por isso o rascunho declara um parâmetro secret_key próprio — uma string, obrigatória, com pelo menos um caractere e sem valor padrão — e o repassa a cada entrada de core/dify que escreve, para que a Release o preencha em seus parameters; um build cuja Release o deixe sem definir é interrompido, nomeando-o.

A aplicação é importada com a conta do proprietário da instalação, que a Release nomeia em sua entrada de roteamento para a instalação: infra.owner_email no componente api da instalação, e a ranhura owner_password nesse componente, anexada como core/referenced-secret, sem os quais o build é interrompido. O e-mail do proprietário não é algo que alguma fonte possa fornecer, então ele é escrito vazio sob um comentário que diz o que ele é, e a importação o indica como pendente.

Em todos os destinos, a mesma entrada de roteamento define infra.marketplace_enabled como true nos componentes api, worker e scheduler da instalação, cada um sob um comentário que diz por quê: a instalação não alcança nada do fornecedor do Dify a menos que a Release o permita, cada um dos três lê sua própria configuração, e o Dify instala o plugin que serve o modelo de uma aplicação, como o da OpenAI, a partir de seu marketplace de plugins.

O segredo de aplicação e a senha do proprietário são segredos, gerados como rascunho por referência para o destino da importação:

  • Com --target helm, cada um nomeia um Secret do Kubernetes que já está no namespace: secret_key o nome do Secret, que core/dify lê sob a chave de dados secret-key, e owner_password um Secret que contém a senha sob a chave de dados value. Nenhum dos dois nomes é algo que uma fonte possa fornecer, então cada um é escrito vazio sob um comentário que diz o que ele é, e a importação indica ambos como pendentes; o Manifest gerado como rascunho mapeia core/referenced-secret para helm/k8s-existing-secret.
  • Em qualquer outro destino, e sem destino, cada um é uma referência a uma variável — secret_key como "${DIFY_SECRET_KEY}" e a senha do proprietário como "${DIFY_OWNER_PASSWORD}", os nomes que as Recipes do Dify para Compose do catálogo padrão leem — que o Docker Compose lê do ambiente quando a stack é iniciada, então nada fica pendente para nenhum dos dois; com --target compose o Manifest gerado como rascunho mapeia core/referenced-secret para compose/dotenv-referenced-secret.

Dado um destino, o Manifest mapeia o tipo de cada componente que a instalação compõe, assim como o do próprio rascunho, como descreve O que um destino adiciona.

A aplicação workflow escrita à mão que os testes deste importador importam, chamada Support Answers, é gerada como rascunho, sem nenhuma configuração, assim:

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 com --target helm, sua Release gerada como rascunho preenche secret_key, e nomeia o proprietário e ativa o marketplace de plugins na entrada de roteamento que posiciona a instalação, com cada valor pendente escrito vazio:

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

A importação indica como pendentes os três valores vazios. Importada com --target compose, a mesma Release escreve secret_key: "${DIFY_SECRET_KEY}" e origin: "${DIFY_OWNER_PASSWORD}", e indica como pendente apenas o e-mail do proprietário; ela também escreve infra.published_port no componente api, 5001, e no front-end, o componente console, 3001, cada um sob o comentário que diz que ele só pode ser acessado a partir desta máquina, por qualquer processo em execução nela, e que excluir a linha mantém o serviço interno, e, abaixo da porta do componente api, infra.console_url com o endereço em que o console é publicado, "http://127.0.0.1:3001", que o servidor do Dify usa como endereço do console. O passo a passo da importação do Dify faz o build de uma aplicação para os dois destinos e a executa no Kubernetes.

O que o Dify configura por conta própria

O Dify configura dentro de si mesmo os provedores dos modelos e das ferramentas que uma aplicação chama, e core/ai-agent/dify não declara nenhum socket para um modelo, então o rascunho não conecta nenhum. Cada nó que nomeia um deles é relatado com part-configured-in-platform, e em sua decisão, conforme o que nomeia:

  • um nó llm, question-classifier ou parameter-extractor, e o model_config.model de uma aplicação chat: o modelo, por seu nome e seu provedor;
  • um nó tool, e a ferramenta de uma aplicação chat: a ferramenta, por seu nome e seu provedor;
  • um nó agent: a estratégia do agente e o plugin que a fornece;
  • um nó knowledge-retrieval, e a base de conhecimento de uma aplicação chat: as bases de conhecimento das quais ele recupera, e o modelo com que ele roteia uma consulta ou com que reclassifica, onde nomeia um. Uma aplicação nomeia uma base de conhecimento por um identificador da instalação da qual foi exportada, e não leva nenhum de seus documentos nem nenhum armazenamento, então cada uma é criada dentro do Dify, no armazenamento vetorial que a instalação conecta ao seu servidor de API;
  • uma dependência: o plugin, pelo identificador com que o Dify o instala, e de onde o Dify o instala.

Qualquer outro nó é mantido na aplicação sem que nada seja relatado.

Valores de credenciais que uma aplicação contém

O importador localiza, na ordem em que a aplicação os escreve:

  • o valor de cada variável de ambiente cujo value_type é secret, que o Dify marca como credencial. A exportação do Dify o escreve vazio, a menos que a exportação inclua os segredos;
  • o authorization.config.api_key de um nó de requisição HTTP, que o Dify marca como credencial e exporta como está escrito;
  • a credencial armazenada que um nó tool, ou uma ferramenta de um nó agent, seleciona sob credential_id, que o Dify marca como credencial e escreve apenas onde a exportação inclui os segredos;
  • os headers e params de um nó de requisição HTTP, que o Dify não marca como credencial e que podem conter uma, cada um por inteiro.

Por padrão, cada um que contém um valor é levado como está escrito na aplicação e nomeado em um aviso credential-carried por seu nó — workflow para uma variável de ambiente — e seu campo, nunca por seu valor. Com a configuração empty_credentials em marked, cada valor que o Dify marca como credencial é escrito vazio, e em all também os cabeçalhos e os parâmetros de consulta, cada um relatado com credential-emptied. Um valor que é uma referência a uma variável e nada mais não contém nenhum, e é levado como está escrito independentemente do que diga a configuração e não é nomeado em nenhum aviso, assim como em um fluxo. Um valor é escrito vazio no próprio texto da aplicação: o escalar após sua chave é substituído por '', e nada mais é alterado. A aplicação é levada apenas onde o analisador que serve parse:yaml lê de volta o resultado como a aplicação exportada com exatamente esses valores esvaziados; caso contrário, ela não é levada, app_definition é deixado sem definição com um comentário, e definition-not-carried diz por quê — como para uma aplicação em que um alias YAML lê o valor de um segredo, que escrever esse valor vazio também alteraria. Um valor que a configuração deixa como está escrito nunca é reescrito, então nunca impede que a aplicação seja levada.

A versão da DSL

Onde uma aplicação está escrita em uma versão da DSL mais recente que 0.7.0, a versão que o Dify 1.17.0 — a versão que core/ai-agent/dify executa por padrão — escreve, a importação avisa com dsl-version-newer. O Dify retém a importação de uma aplicação desse tipo aguardando uma confirmação, que a etapa que a importa na implantação dá, então verifique a aplicação em relação à versão do Dify que a Release executa.

As configurações que ele lê

O importador Dify lê target_namespace, empty_credentials, layout, attach_egress_allowlist e render_mode, como Configurações os descreve, e reuse_mode, reuse_threshold, emit_hints e mapping_overrides, que não mudam nada do que o layout padrão gera como rascunho: cada nó permanece na aplicação. attach_egress_allowlist não vincula nada, já que uma entrada de um Aggregate composto aceita parâmetros e nenhuma Feature, e com ele em true a importação avisa com feature-not-attached. layout: nodes gera como rascunho cada nó como um Component próprio, como Nó a nó descreve, e não leva nenhuma aplicação.

O importador CrewAI

importer/crewai lê os agentes e as tarefas que um projeto CrewAI declara em seus arquivos de configuração, e gera como rascunho um Aggregate que contém uma instância do agente CrewAI da biblioteca padrão, core/ai-agent/crewai, por agente, cada uma conectada ao modelo que sua configuração nomeia, e uma Release ao lado dele.

O que ele lê

O CrewAI mantém o comportamento de uma crew em um programa e declara seus agentes e suas tarefas em arquivos de configuração, em uma de duas estruturas, e o importador lê qualquer uma delas:

  • Um projeto clássico — config/agents.yaml, com cada agente tendo seu nome como chave, e config/tasks.yaml, com cada tarefa tendo seu nome como chave, ambos lidos como YAML. Os agentes são lidos na ordem em que agents.yaml os escreve.
  • Um projeto na estrutura JSON-first — crew.jsonc, que lista os agentes da crew por nome sob agents e suas tarefas sob tasks, e agents/<name>.jsonc, um arquivo por agente, todos lidos como JSON com comentários, de modo que seus comentários e vírgulas finais são lidos como o CrewAI os lê. Os agentes são lidos na ordem em que crew.jsonc os lista, seguidos do arquivo de qualquer outro agente na ordem dos nomes; um agente que a crew lista cujo arquivo não foi entregue à importação é nomeado em um comentário e nada é gerado como rascunho para ele. A mesma estrutura escrita em JSON estrito — crew.json e agents/<name>.json — é lida da mesma forma. Onde uma crew ou um agente está escrito nas duas grafias, o arquivo .jsonc é o que é lido, como o CrewAI o lê, e o arquivo .json é nomeado em um comentário como não lido.

De um agente ele lê seu role, goal e backstory; allow_delegation e verbose, no nível superior de sua declaração ou sob settings, onde settings prevalece, como o CrewAI os lê; seu llm; e os nomes de suas tools. De uma tarefa ele lê seu nome e o agente ao qual está atribuída. Qualquer outro membro é nomeado em um comentário e não é levado a lugar nenhum.

Um diretório é entregue ao importador como os arquivos que suas assinaturas nomeiam e nenhum outro, então o programa da crew — o crew.py de um projeto clássico, o main.py de um fluxo, uma ferramenta que um projeto define em Python — nunca é lido. Um arquivo importado sozinho é lido como a declaração cuja forma ele tem. O diretório de um projeto pode conter várias crews, cada uma lida de seu próprio diretório.

No que um projeto se torna

aggregate.yaml é um Aggregate de rascunho que leva o nome da crew, como Como um rascunho é nomeado descreve, e que começa com comentários que nomeiam as declarações lidas, que o programa da crew não é lido, e as tarefas de cada crew com o agente ao qual cada uma está atribuída. Ele contém, por agente e com seu nome como chave, uma instância de core/ai-agent/crewai com:

  • role, goal e backstory como declarados;
  • allow_delegation como declarado, e false onde o agente não declara nenhum;
  • log_level DEBUG para um agente declarado verbose, que narra cada passo de seu raciocínio, e INFO para um que não é, que relata apenas o progresso e os problemas. Um verbose ou um allow_delegation que não é nem true nem false é deixado ao valor padrão do Component e nomeado em um comentário;
  • sua conexão model, conectada à instância do modelo que seu llm nomeia.

Um llm escrito <provider>/<model>, ou como um objeto que nomeia o modelo sob model, model_name ou deployment_name, nomeia um provedor e um modelo. O modelo é uma instância do Component do catálogo para esse provedor — core/ai-model/<provider>, com um sublinhado no nome do provedor lido como hífen, e azure lido como azure-openai — com o nome do modelo como chave e o modelo como seu values.model; agentes que nomeiam um mesmo provedor e modelo compartilham uma instância. Onde o catálogo do workspace não contém nenhum Component com esse nome, um é gerado como rascunho, <target_namespace>/ai-model/<provider>, declarando o valor model, e sua decisão diz isso; o rótulo model.aggrega.ai/api pelo qual o socket model do agente seleciona um Component, e uma Recipe que publique seu endpoint e seu modelo, ficam para você, como diz um comentário no início dele. Um llm que não nomeia nenhum provedor — um nome de modelo simples, para o qual o CrewAI resolve um provedor quando o programa é executado, ou o nome de um llm que o programa define — uma referência dentro do programa, e um agente que não declara nenhum llm, que o CrewAI então lê do ambiente em que seu programa é executado, não são conectados a nada, e um comentário acima do agente diz por quê; o build é interrompido nomeando o socket model até que um seja conectado.

Uma tarefa é lógica que o programa da crew executa, e uma ferramenta é código que o programa define ou carrega: nenhuma das duas se torna um Component. Cada uma é relatada em uma decisão que não escolhe nada, e uma ferramenta cujo nome — sem um Tool final, sem seus hífens e sublinhados — é o nome de um Component de ferramenta que o catálogo contém leva esse Component como dica: search_tool e SearchTool apontam ambos para core/ai-tool/search. core/ai-agent/crewai não declara nenhum socket para uma ferramenta, então nada é conectado para ela.

release.yaml, ao lado dele, é uma Release de rascunho com o mesmo nome que nomeia esse Aggregate. Ela escreve vazio o infra.image de cada agente — a imagem que executa o programa da crew, que nenhuma declaração nomeia — sob um comentário que diz o que ele é, e a importação o indica como pendente. Com --target compose, a entrada de cada agente também escreve infra.published_port, 8000, a porta que o infra.port do Component indica por padrão para o programa, que sua Recipe do Compose publica no endereço de loopback do host, 127.0.0.1, sob o comentário que diz que ele só pode ser acessado a partir desta máquina, por qualquer processo em execução nela, e que excluir a linha mantém o serviço interno; um segundo agente recebe a próxima porta livre, de modo que os dois agentes do projeto clássico são publicados em 8000 e 8001. Ela anexa a credencial que cada agente apresenta ao seu modelo sob credential em sua conexão model, por referência e nunca como valor: nenhuma declaração nomeia uma variável para ela, então ela é lida da variável da qual as bibliotecas cliente do provedor leem sua chave de API — OPENAI_API_KEY para a OpenAI — como uma referência ${…} em todos os destinos exceto helm, e no helm como o nome de um Secret do Kubernetes, escrito vazio para que a importação o indique como pendente; no compose, a conexão model do agente a declara com essa chave. Cada modelo também tem uma entrada, que não contém nenhuma infraestrutura, então a Release o posiciona junto com os agentes. De um modelo declarado como um objeto llm, cada um dos outros membros é escrito como um valor da instância do modelo onde o Component do catálogo declara um valor com esse nome, e caso contrário em um comentário acima da entrada do modelo na Release, para que você o leve onde o Component o aceita. Como toda Release gerada como rascunho, ela escreve metadata.environment como development e, sem destino, um spec.manifest vazio que a importação indica como pendente; dado um destino, a importação gera o Manifest como rascunho, como descreve O que um destino adiciona.

O projeto clássico que os testes deste importador importam, cujos dois agentes nomeiam ambos openai/gpt-4o, é gerado como rascunho, sem nenhuma configuração, como mostrado abaixo; importado como seu diretório de projeto, market_brief — o diretório em que crewai create crew market_brief organiza um projeto desse tipo —, e como suas declarações não nomeiam nenhuma crew, ele recebe o nome desse diretório:

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"

e sua Release, gerada como rascunho sem destino, como abaixo, com a entrada do segundo agente omitida aqui e marcada com ...; a importação indica como pendentes spec.manifest e a imagem 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 é então renderizado executando a imagem que você informar na resposta, recebendo o endpoint do modelo e o nome do modelo como OPENAI_BASE_URL e MODEL, as variáveis das quais o CrewAI os lê.

Valores de credenciais que uma declaração contém

Um llm escrito como um objeto pode conter uma chave — sob api_key, em um endereço, em cabeçalhos. Cada um de seus membros diferente daquele que nomeia o modelo que não é um número nem um booleano é um valor que pode conter uma, que o CrewAI não marca como credencial. Por padrão, cada um que contém um valor é levado como está escrito — como um valor da instância do modelo onde seu Component declara um, e caso contrário para o comentário acima da entrada de seu modelo na Release — e nomeado em um aviso credential-carried por seu agente e seu membro, como llm.api_key, nunca por seu valor. Com a configuração empty_credentials em all, cada um é escrito sem valor e relatado com credential-emptied; em marked cada um é levado, já que o CrewAI não marca nenhum. O nome de um membro não é lido pelo que significa. Qualquer outro membro que uma declaração contém e que o rascunho não leva — a configuração de uma ferramenta, os inputs de uma crew — é nomeado, nunca com seu valor.

As configurações que ele lê

O importador CrewAI lê target_namespace, empty_credentials e render_mode, como Configurações os descreve, e nenhuma outra configuração.

O importador LangGraph

importer/langgraph lê os grafos que a configuração de uma aplicação LangGraph, langgraph.json, declara, e gera como rascunho um Aggregate que contém uma instância do agente LangGraph da biblioteca padrão, core/ai-agent/langgraph, por grafo, cada uma conectada ao armazenamento de dados em que seu checkpointer mantém o estado e a um modelo, e uma Release ao lado dele que leva o ambiente que a configuração indica. Ele lê essa configuração, e nunca o código dos grafos.

O que ele lê

Uma aplicação LangGraph mantém seus grafos em código e os declara em langgraph.json: sob graphs, o id de cada grafo é mapeado para o caminho de importação do grafo no código da aplicação — ./src/agent/graph.py:graph, ou module:attr — ou para um objeto que nomeia esse caminho sob path e descreve o grafo sob description. O importador lê, na ordem em que a configuração os escreve:

  • graphs — o id de cada grafo, seu caminho de importação e sua descrição;
  • checkpointer — seu backend: default, que é PostgreSQL e o que o LangGraph lê onde nenhum é nomeado; mongo, um banco de dados que fala o protocolo do MongoDB; ou custom, um checkpointer que o código da aplicação define em path;
  • store — o armazenamento de memória, que não nomeia nenhum backend: o LangGraph o mantém no banco de dados PostgreSQL que seu servidor usa;
  • env — o ambiente com que a aplicação é executada: um objeto de nomes de variáveis para valores, ou o caminho de um arquivo de ambiente de linhas KEY=VALUE.

Os membros que configuram a imagem de servidor da qual langgraph build faz o build — dependencies, source, python_version, node_version, base_image, image_distro, dockerfile_lines, pip_config_file, pip_installer, keep_pkg_tools, api_version — são nomeados em um comentário e não são levados a lugar nenhum, já que a imagem que a Release nomeia é a própria da aplicação; o mesmo vale para qualquer outro membro, entre eles a configuração própria do servidor, como auth, http e webhooks, e para o index e o ttl do armazenamento de memória e o ttl e o serde do checkpointer.

Um diretório é entregue ao importador como langgraph.json e nenhum outro arquivo, então nem o código da aplicação nem um arquivo de ambiente são jamais lidos dele. Um arquivo de ambiente chega ao importador apenas onde o with.sources do importador o entrega, e nunca é analisado: daquele que o env da configuração nomeia — correspondido pelo último segmento do caminho que nomeia — apenas os nomes das variáveis são lidos, e um arquivo de ambiente que nenhuma configuração nomeia é nomeado em um comentário como não lido. Onde a importação não recebe o arquivo que a configuração nomeia, o Aggregate o nomeia como não entregue e diz para nomeá-lo sob o with.sources do importador, e suas variáveis ficam para a Release:

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

Uma configuração importada sozinha é lida qualquer que seja seu nome. Um diretório pode conter várias aplicações, cada uma lida de seu próprio diretório.

No que uma aplicação se torna

aggregate.yaml é um Aggregate de rascunho que leva o nome do grafo, como Como um rascunho é nomeado descreve, e que começa com comentários que nomeiam as configurações lidas, os arquivos de ambiente lidos apenas por seus nomes, que o código da aplicação não é lido, e o que o rascunho não leva. Ele contém, por grafo e com seu id como chave, uma instância de core/ai-agent/langgraph com:

  • graph_entrypoint, o caminho de importação do grafo, como a configuração o escreve;
  • description, a descrição do grafo, onde a configuração fornece uma;
  • sua conexão checkpointer_db, conectada ao armazenamento de dados da aplicação;
  • sua conexão model, conectada ao modelo da aplicação.

recursion_limit não é escrito, então o valor padrão do Component, 25, permanece. A configuração não nomeia nenhum modelo, então o rascunho contém uma instância de core/ai-model/openai, com a chave model, que cada grafo chama: o modelo entregue ao cliente OpenAI do agente. Seu values.model é escrito vazio, sob um comentário que diz que a configuração não nomeia nenhum, e a importação o indica como pendente.

O backend do checkpointer é o armazenamento de dados ao qual cada grafo da aplicação é conectado: default, ou um checkpointer que não nomeia nenhum backend, é uma instância de core/datastore/postgres, com a chave postgres. mongo é o FerretDB, que fala o protocolo do MongoDB, sobre PostgreSQL com a extensão DocumentDB: uma instância de core/datastore/ferretdb, com a chave ferretdb, à qual cada grafo é conectado, e uma de core/datastore/documentdb, com a chave documentdb, que a conexão backend do FerretDB alcança, com seu bloco inject entregando o que o DocumentDB publica sob os nomes que o FerretDB lê; uma única senha, lida da variável FERRETDB_PASSWORD, é anexada ao DocumentDB, à conexão do FerretDB com ele e à conexão de cada grafo com o FerretDB. Onde o catálogo do workspace não contém nenhum Component com o nome do armazenamento de dados PostgreSQL, um é gerado como rascunho, <target_namespace>/datastore/postgres, declarando o host e a port que a conexão checkpointer_db do agente lê, e sua decisão diz isso; uma Recipe que execute o armazenamento de dados e os publique fica para você, como diz um comentário no início dele. Onde ele não contém nenhum Component do FerretDB ou nenhum do DocumentDB, o checkpointer mongo não é conectado a nenhum armazenamento de dados. Um checkpointer custom, ou um backend que o importador não mapeia para nenhum armazenamento de dados, não conecta nada, e um comentário acima de cada grafo e a decisão do checkpointer dizem por quê; o build é interrompido nomeando o socket checkpointer_db até que um seja conectado. O armazenamento de memória é relatado em uma decisão que não escolhe nada.

A senha do armazenamento de dados é um segredo que o rascunho anexa por referência, na ranhura password do próprio armazenamento de dados e na conexão checkpointer_db de cada grafo, e o mesmo vale para a credencial que cada grafo apresenta ao modelo em sua conexão model: lidas de POSTGRES_PASSWORD (ou FERRETDB_PASSWORD) e de OPENAI_API_KEY, já que a configuração não nomeia nenhuma variável para nenhuma das duas, como uma referência ${…} em todos os destinos exceto helm, e no helm como o nome de um Secret do Kubernetes, escrito vazio para que a importação o indique como pendente. No compose, o Aggregate declara cada uma com a chave que sua Recipe lê, como Segredos, para cada destino descreve para uma plataforma.

release.yaml, ao lado dele, é uma Release de rascunho com o mesmo nome que nomeia esse Aggregate. Comentários acima da entrada do primeiro grafo dizem qual é a imagem de cada grafo — a própria da aplicação, seu código com o LangGraph instalado, não a imagem de servidor da qual langgraph build faz o build —, as variáveis que ela recebe e qual bloco inject: substitui qual de seus nomes. A entrada de cada grafo escreve vazio seu infra.image, a imagem que executa a aplicação, sob um comentário que diz o que ele é, e a importação o indica como pendente; enquanto ele não é definido, a Recipe do Docker Compose executa o agente quickstart do próprio catálogo, que lê as variáveis padrão. Com --target compose, a entrada de cada grafo também escreve infra.published_port, 8000, a porta que o infra.port do Component indica por padrão para a aplicação, que sua Recipe do Compose publica no endereço de loopback do host, 127.0.0.1, sob o comentário que diz que ele só pode ser acessado a partir desta máquina, por qualquer processo em execução nela, e que excluir a linha mantém o serviço interno; um segundo grafo recebe a próxima porta livre. O armazenamento de dados e o modelo também têm entradas, de modo que a Release os posiciona junto com os grafos. Um comentário acima do primeiro grafo da aplicação indica o ambiente que sua configuração declara, como descreve O ambiente que uma configuração indica. Como toda Release gerada como rascunho, ela escreve metadata.environment como development e, sem destino, um spec.manifest vazio que a importação indica como pendente; dado um destino, a importação gera o Manifest como rascunho, como descreve O que um destino adiciona.

A aplicação Python que os testes deste importador importam, que declara dois grafos, um checkpointer que não nomeia nenhum backend, um armazenamento de memória e um env escrito como um objeto, é gerada como rascunho, sem nenhuma configuração, como mostrado abaixo; importada como seu diretório, support_desk — nomeado, como aqui, a partir do pacote em que seus grafos são definidos —, com dois grafos cujos ids diferem, ela recebe o nome desse diretório:

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: {}

A importação indica quatro valores como pendentes: spec.manifest, a imagem de cada grafo e o nome do modelo. Depois que eles são respondidos, cada grafo é renderizado executando a imagem que você informar na resposta, recebendo o endereço de seu armazenamento de dados como LANGGRAPH_CHECKPOINTER_HOST e LANGGRAPH_CHECKPOINTER_PORT, o usuário e o banco de dados que o armazenamento de dados publica como LANGGRAPH_CHECKPOINTER_USER e LANGGRAPH_CHECKPOINTER_DATABASE — o PostgreSQL publica ambos, e um armazenamento de dados que não publica nenhum dos dois não tem nenhuma das duas variáveis renderizada —, o endpoint e o nome do modelo como OPENAI_BASE_URL e OPENAI_MODEL, a chave que sua credencial do modelo entrega como OPENAI_API_KEY, seu caminho de importação como LANGGRAPH_GRAPH_ENTRYPOINT e seu limite de passos como LANGGRAPH_DEFAULT_RECURSION_LIMIT. A credencial anexada à sua conexão checkpointer_db também lhe fornece a senha do armazenamento de dados como LANGGRAPH_CHECKPOINTER_PASSWORD.

O ambiente que uma configuração indica

Cada variável que o env da configuração nomeia é uma entrada que a Release deve fornecer, e nenhuma é gerada como rascunho como ranhura de credencial: o LangGraph não marca nenhuma variável como segredo, e o nome de uma variável não é lido pelo que significa. core/ai-agent/langgraph não aceita nenhum valor para o ambiente, então a Release o indica em um comentário acima do primeiro grafo da aplicação.

  • Um env escrito como um objeto faz parte da configuração, então seus valores são levados como estão escritos para esse comentário, na ordem em que a configuração os escreve. Cada valor que contém algo pode conter uma credencial, que o LangGraph não marca como credencial: por padrão, cada um é levado como está escrito e nomeado em um aviso credential-carried por sua configuração e sua variável, como env.OPENAI_API_KEY, nunca por seu valor. Com a configuração empty_credentials em all, cada um é escrito sem valor e relatado com credential-emptied; em marked cada um é levado, já que o LangGraph não marca nenhum.
  • Um env que nomeia um arquivo nomeia um arquivo para o qual a configuração apenas aponta, que comumente contém segredos locais. Ele é lido apenas onde o with.sources do importador o entrega. O comentário nomeia cada variável que o arquivo nomeia, deixada para a Release fornecer, e nenhum valor do arquivo é lido: nenhum chega a um rascunho, a uma decisão ou a um diagnóstico, independentemente do que diga a configuração. Um valor entre aspas ao longo de várias linhas é um único valor, então uma linha dentro dele nunca é tomada por uma variável, e uma linha que não nomeia nenhuma variável é nomeada por seu número. Onde a importação não recebeu o arquivo — sempre o caso para um diretório, que nunca entrega um — o Aggregate o nomeia como não entregue, com como entregá-lo, e suas variáveis ficam para a Release.

As configurações que ele lê

O importador LangGraph lê target_namespace, empty_credentials e render_mode, como Configurações os descreve, e nenhuma outra configuração.

O importador Google ADK

importer/google-adk lê os agentes que uma aplicação criada sobre o Agent Development Kit (ADK) do Google declara em seus arquivos Agent Config — root_agent.yaml e as configurações que seus subagentes nomeiam — e gera como rascunho um Aggregate que contém uma instância do agente ADK da biblioteca padrão, core/ai-agent/google-adk, por árvore de agentes, conectada ao modelo que a árvore nomeia quando o ADK envia as solicitações dele à Gemini API, e uma Release ao lado dele. Ele lê essas configurações, e nunca o código da aplicação.

O ADK afirma que seu recurso Agent Config é experimental. O modelo de um agente é, por padrão, um modelo Gemini; o ADK atende pelo nome os modelos de alguns outros provedores por meio de classes próprias, como claude-sonnet-4-5 e gpt-4o, e outros por meio de uma string de modelo do LiteLLM. O socket model do agente admite apenas a Gemini API, então o importador conecta um modelo que o ADK envia à Gemini API e deixa qualquer outro para você, como descreve O que uma árvore de agentes se torna.

O que ele lê

O adk create --type=config do ADK escreve root_agent.yaml, a configuração do agente raiz de uma aplicação, e um arquivo de ambiente ao lado dela. Uma configuração declara um agente:

  • name, description e agent_class — a classe como a qual o ADK constrói o agente, LlmAgent onde ela não nomeia nenhuma;
  • model — o modelo que o agente pede — ou model_code, uma referência a código que constrói seu modelo;
  • tools — cada ferramenta por name, com os args que sua configuração lhe entrega;
  • generate_content_config — as opções das requisições ao modelo do agente, entre elas http_options;
  • sub_agents — cada um um config_path, o caminho de outra configuração a partir do diretório da configuração que o nomeia, ou code, um agente que o código da aplicação constrói.

Um diretório é entregue ao importador como seus arquivos root_agent.yaml e nenhum outro arquivo, e uma configuração importada sozinha é lida como uma raiz, qualquer que seja seu nome. A árvore de cada raiz é lida começando pela raiz, os subagentes de cada agente na ordem em que ele os lista. A configuração que uma entrada de sub_agents nomeia por config_path é lida apenas onde o with.sources do importador a entrega, correspondida pelo último segmento do caminho; uma que não foi entregue à importação é nomeada no Aggregate e em sua decisão como não entregue, com como entregá-la, e seu agente não é lido:

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

Um config_path que é absoluto, ou que leva para fora do diretório da configuração que o nomeia, não é lido, já que o ADK também o recusa. Um arquivo que with.sources entrega e que nenhuma configuração nomeia é nomeado em um comentário como não lido, e nada dele é lido; um arquivo que ele entrega é lido apenas como uma configuração que a árvore de uma raiz nomeia, então uma importação que não contém nenhum root_agent.yaml nem nenhum arquivo importado sozinho não lê nenhuma árvore e relata cada arquivo sob no-nodes. O código da aplicação — as ferramentas, callbacks, esquemas e agentes que uma configuração nomeia por seu código — e o arquivo de ambiente nunca são entregues, e o importador não lê nenhum dos dois: a aplicação carrega suas configurações ela mesma, a partir da imagem que a Release nomeia. Um diretório pode conter várias aplicações, cada uma lida de seu próprio root_agent.yaml.

Os outros membros de uma configuração — entre eles a instruction de um agente — são lidos pela aplicação a partir de sua própria configuração, então o rascunho não leva nenhum deles.

No que uma árvore de agentes se torna

O ADK serve uma aplicação a partir de seu agente raiz, com cada agente que suas configurações nomeiam construído dentro dela, e core/ai-agent/google-adk executa uma dessas aplicações. Então aggregate.yaml, um Aggregate de rascunho que leva o nome do agente raiz, como Como um rascunho é nomeado descreve, contém, por árvore de agentes e com o nome de seu agente raiz como chave, uma instância de core/ai-agent/google-adk com:

  • description, a descrição do agente raiz, onde sua configuração fornece uma;
  • sua conexão model, conectada ao modelo que a árvore nomeia, quando o ADK envia as requisições dele para a Gemini API.

Comentários acima dela nomeiam os outros agentes da árvore, que não se tornam nenhuma instância própria; cada subagente que não é lido, e por quê — construído pelo código da aplicação, uma configuração que não foi entregue à importação, ou uma que o ADK recusa; as ferramentas que os agentes da árvore nomeiam, as que o ADK inclui e as que o código da aplicação define; os agentes cuja classe — LoopAgent, ParallelAgent ou SequentialAgent — o ADK descontinua em favor de Workflow; e, onde o modelo da árvore está conectado, os modelos que outros agentes da árvore pedem, cada um com a família pela qual o ADK o serve. Cada um é relatado em uma decisão que não escolhe nada.

O primeiro agente da árvore, começando pela raiz, que nomeia um modelo ou o código que constrói um decide o modelo da instância. Um modelo que ele nomeia e cujas requisições o ADK envia para a Gemini API — um nome de modelo que o ADK serve por meio de sua classe Gemini, como gemini-2.5-flash, exceto um nome de recurso da Vertex AI, ou um que ele serve por meio de sua classe Gemma — é uma instância de core/ai-model/gemini, que serve esse modelo e o tem como chave, e árvores que nomeiam um mesmo modelo compartilham uma instância. Onde o catálogo do workspace não contém nenhum core/ai-model/gemini, um é gerado como rascunho, <target_namespace>/ai-model/gemini, levando o rótulo model.aggrega.ai/api: gemini que o socket model do agente seleciona, e sua decisão diz isso; uma Recipe que publique seu endpoint e seu modelo fica para você, como diz um comentário no início dele. Um modelo que o ADK serve de qualquer outra forma — uma string de modelo do LiteLLM como openai/gpt-4o, um nome de recurso da Vertex AI, ou um nome como claude-sonnet-4-5 ou gpt-4o, que o ADK serve por meio da Anthropic ou da OpenAI — não é conectado a nada: o socket model do agente recebe um modelo Gemini, e o agente não lê nenhum nome de modelo do seu ambiente, então cabe a você conectar ali um modelo Gemini e nomear esse modelo na configuração do agente. O comentário acima da instância e a decisão do agente raiz nomeiam o modelo e a família pela qual o ADK o serve. Um modelo que o código da aplicação constrói, ou uma árvore que não nomeia nenhum — o ADK então usa seu modelo padrão — também não é conectado a nada, e um comentário acima da instância diz por quê. Sempre que o modelo não estiver conectado a nada, o build é interrompido nomeando o socket model até que um seja conectado. Dos modelos que outros agentes de uma árvore pedem, um cujas requisições o ADK envia para a Gemini API não precisa de nenhuma conexão própria: o cliente Gemini do ADK envia as requisições dele com a chave que a conexão da instância entrega. Se a aplicação alcança o Gemini pela Gemini API ou pela Vertex AI é escolhido por seu ambiente, que a importação não lê; o socket model do agente admite apenas a Gemini API.

Os testes do importador também importam um agente raiz isolado que nomeia openai/gpt-4o, cuja instância é gerada como rascunho assim:

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, ao lado dele, é uma Release de rascunho com o mesmo nome que nomeia esse Aggregate. A entrada de cada instância escreve seu infra.image — a imagem que executa a aplicação criada sobre o ADK, que contém suas configurações — vazio, sob um comentário que diz o que é, e a importação o marca como pendente. Com --target compose, a entrada também escreve infra.published_port, 8000, a porta em que a aplicação escuta, que sua Recipe do Compose publica no endereço de loopback do host, 127.0.0.1, sob o comentário que diz que ela só é acessível a partir desta máquina, por qualquer processo em execução nela, e que excluir a linha mantém o serviço interno; uma segunda árvore recebe a próxima porta livre. Onde seu modelo está conectado, a entrada vincula a credencial que a instância apresenta a esse modelo sob credential em sua conexão model, por referência e nunca como valor: nenhuma configuração nomeia uma variável para ela, então ela é lida de GOOGLE_API_KEY, a variável da qual as bibliotecas cliente da Gemini API do Google leem sua chave, como uma referência ${…} em todos os destinos exceto helm, e no helm como o nome de um Kubernetes Secret, escrito vazio para que a importação o marque como pendente; no compose, a conexão model a declara com essa chave. Um modelo conectado também tem uma entrada, que não contém infraestrutura, de modo que a Release o posiciona junto com a instância. Os valores que as configurações da árvore entregam às suas ferramentas e às suas requisições ao modelo são escritos em um comentário acima da entrada, como descreve Valores de credenciais que uma configuração contém. Como toda Release de rascunho, ela escreve metadata.environment como development e, sem destino, um spec.manifest vazio que a importação marca como pendente; com um destino, a importação gera o Manifest como rascunho, como descreve O que um destino adiciona.

A aplicação que os testes deste importador importam, um agente raiz que nomeia as configurações de dois subagentes e um construído por código, importada como seu diretório com as duas configurações nomeadas sob with.sources, é gerada como rascunho, sem nenhuma configuração, com o nome de seu agente raiz, tutor_root, assim:

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"

Um texto que o rascunho copia de uma configuração para o Aggregate, em um valor ou em um comentário, escreve cada {{ como {{`{{`}}, uma ação cujo resultado são as duas chaves, de modo que a descrição, e um nome que contém duas chaves em um comentário, são lidos de volta como escritos assim que o Aggregate é avaliado.

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: {}

Assim que a imagem é respondida, a instância é renderizada executando-a e recebe a credencial como GOOGLE_API_KEY, que o cliente Gemini do ADK envia à Gemini API, e o modelo como um Service que alcança o endereço da Gemini API.

Valores de credenciais que uma configuração contém

Uma configuração pode entregar uma chave a uma ferramenta, em seus args, ou às suas requisições ao modelo, nas http_options de sua generate_content_config — seus cabeçalhos, seu endereço, os argumentos de seu cliente. Cada membro dos args de uma ferramenta e dessas opções HTTP é escrito no comentário acima da entrada da instância na Release, como sua configuração o escreve, e cada um que é um texto, um objeto ou uma lista pode conter uma credencial, que o ADK não marca como credencial: por padrão, cada um é levado como está escrito e nomeado em um aviso credential-carried por seu agente e seu campo, como tools.tutor_tools.make_snippet_runner.args.api_key, nunca por seu valor. Com a configuração empty_credentials em all, cada um é escrito sem valor e relatado com credential-emptied; em marked cada um é levado, já que o ADK não marca nenhum. Um número ou um booleano não contém nenhuma chave, e é escrito como a configuração o escreve. O ADK não expande nenhuma referência a variável em uma configuração, então cada valor é lido como está escrito; o arquivo de ambiente, que comumente contém a chave que o cliente Gemini do ADK lê, nunca é lido, independentemente do que diga a configuração.

As configurações que ele lê

O importador Google ADK lê target_namespace, empty_credentials e render_mode, como Configurações os descreve, e nenhuma outra configuração.

O importador Agent Framework

importer/agent-framework lê um agente declarativo do Microsoft Agent Framework — o documento YAML do tipo Prompt a partir do qual uma aplicação construída sobre o Agent Framework carrega um agente — e gera como rascunho um Aggregate que contém uma instância do agente Agent Framework da biblioteca padrão, core/ai-agent/agent-framework, conectada ao modelo da OpenAI que ele nomeia, e uma Release ao lado dele. Ele lê agentes declarativos, e nunca o código da aplicação. O Agent Framework publica seus pacotes de agentes declarativos como pré-lançamentos.

O que ele lê

Um agente declarativo declara:

  • name, displayName e description, suas instructions e os esquemas de sua entrada e de sua saída;
  • model — o id do modelo, o provider que o serve, a API para a qual seu cliente envia requisições (apiType), as options de suas requisições, e sua connection: uma conexão key que apresenta uma chave, escrita sob key ou apiKey, a um endpoint; uma conexão remote que alcança um endpoint; uma conexão reference que nomeia uma que a aplicação resolve; ou uma anonymous que não apresenta nada;
  • tools — cada uma de um kind: uma function cujo código a aplicação vincula, uma ferramenta web_search, file_search ou code_interpreter que o provedor do modelo executa, ou um servidor mcp alcançado em sua url, com o approvalMode que suas chamadas seguem, as allowedTools do servidor que o agente pode chamar e uma connection própria.

Um membro escrito como =Env.NAME é lido pelo Agent Framework da variável de ambiente NAME somente onde a aplicação carrega o agente declarativo com AgentFactory(safe_mode=False), a própria configuração de segurança do Agent Framework, e um runtime .NET está presente, e caso contrário é tomado como o texto da expressão tal como está escrito; qualquer outro membro que comece com = é uma expressão que a aplicação calcula. O importador não lê nenhum dos dois: ele nomeia uma referência por sua variável, e uma expressão como tal.

Um arquivo importado sozinho é lido como um agente declarativo, qualquer que seja seu nome, e cada arquivo que o with.sources do importador passa é lido como outro, de modo que uma importação gera vários como rascunho:

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

Um diretório nunca é passado ao importador: sua assinatura não nomeia nenhum arquivo, então uma importação de um diretório que não nomeia nenhum formato não o reconhece, e uma que nomeia --format agent-framework é recusada com An importer that declares no file patterns is handed a directory (Um importer que não declara padrões de arquivo recebe um diretório) antes que qualquer arquivo dele seja aberto. Em vez disso, importe cada agente declarativo como um arquivo próprio. Uma origem a partir da qual o Agent Framework não constrói nenhum agente de prompt — uma cujo kind não é nem Prompt, em qualquer combinação de maiúsculas e minúsculas, nem Agent — é relatada com no-nodes. O código da aplicação — o programa que carrega cada agente declarativo e as funções que ele vincula às suas ferramentas — nunca está entre as origens: a aplicação carrega ela mesma seus agentes declarativos, a partir da imagem que a Release nomeia.

No que um agente declarativo se torna

aggregate.yaml, um Aggregate de rascunho que leva o nome do agente, como Como um rascunho é nomeado descreve, contém, por agente declarativo e tendo como chave seu nome, uma instância de core/ai-agent/agent-framework com:

  • display_name e description, o displayName e a description do agente, onde ele os declara;
  • sua conexão model, conectada ao modelo que ele nomeia, onde esse modelo está conectado.

Suas instruções, os esquemas de sua entrada e de sua saída, seu template, seus metadados e as opções de suas requisições ao modelo são lidos pela aplicação a partir do agente declarativo, e são nomeados em um comentário acima da instância. Uma ferramenta de função, uma ferramenta que o provedor do modelo executa e uma ferramenta de qualquer outro tipo também são nomeadas em um comentário, e relatadas em uma decisão que não escolhe nada.

Um modelo cujo provider é OpenAI e que nomeia um id é uma instância de core/ai-model/openai, que serve esse id e o tem como chave: o socket model do agente aceita um modelo que serve a API da OpenAI, e o ambiente de execução entrega o endereço, o nome e a chave desse modelo nas variáveis que os clientes OpenAI do Agent Framework leem. Agentes que nomeiam um mesmo modelo em um mesmo endereço compartilham uma instância. Onde o catálogo do workspace não contém nenhum core/ai-model/openai, um é gerado como rascunho, <target_namespace>/ai-model/openai, trazendo o rótulo model.aggrega.ai/api: openai que o socket model do agente seleciona, e sua decisão diz isso; uma Recipe que publique seu endpoint e seu modelo fica para você, como diz um comentário no início dele. Um id escrito como referência deixa para você o values.model do modelo, com um comentário acima do modelo nomeando a variável; o build é interrompido nomeando-o até que seja definido. Uma conexão anonymous é escrita como o unauthenticated: true da conexão. Um modelo de qualquer outro provedor — AzureOpenAI, Anthropic —, um que nomeia seu provedor como referência ou não nomeia nenhum, caso em que o Agent Framework usa o provedor padrão que a aplicação define, e um que não nomeia nenhum id não são conectados a nada, e um comentário acima da instância diz por quê; o build é interrompido nomeando o socket model até que um seja conectado.

Uma ferramenta do tipo mcp não é gerada como rascunho nem como Component nem como conexão: o Agent Framework envia o servidor ao provedor do modelo como uma ferramenta hospedada, e é o provedor, não a aplicação, que o alcança em sua url, que portanto deve ser acessível a partir do provedor, de modo que nada do que o rascunho implanta o alcança. Um comentário acima da instância do agente nomeia o servidor, informa isso e nomeia a descrição, o approvalMode e os allowedTools que o agente declarativo declara para ele; sua url é escrita, inteira, no comentário acima da entrada do agente na Release, e sua decisão não escolhe nada.

release.yaml, ao lado dele, é uma Release de rascunho com o mesmo nome que nomeia esse Aggregate. A entrada do agente escreve seu infra.image — a imagem que executa a aplicação construída sobre o Agent Framework, que contém seu agente declarativo — vazio, sob um comentário que diz o que é, e a importação o marca como pendente. Com --target compose, a entrada também escreve infra.published_port, 8000, a porta que o infra.port do Component indica por padrão para a aplicação, que sua Recipe do Compose publica no endereço de loopback do host, 127.0.0.1, sob o comentário que diz que ele só pode ser acessado a partir desta máquina, por qualquer processo em execução nela, e que excluir a linha mantém o serviço interno. Onde seu modelo está conectado, a entrada vincula a credencial que o agente apresenta a esse modelo sob credential em sua conexão model, por referência e nunca como valor: lida da variável que o agente declarativo nomeia para sua chave, escrita =Env.NAME, e, caso contrário, de OPENAI_API_KEY, a variável da qual as bibliotecas cliente da OpenAI leem sua chave; como uma referência ${…} em todos os destinos exceto helm, e no helm como o nome de um Kubernetes Secret, escrito vazio para que a importação o marque como pendente; no compose, a conexão model a declara com essa chave. Os valores que o agente declarativo declara para seu modelo e seus servidores MCP — as chaves e a url de cada servidor — são escritos em um comentário acima da entrada do agente, como descreve Valores de credenciais que um agente declarativo contém. Cada modelo conectado tem uma entrada, de modo que a Release o posiciona junto com o agente. O endpoint que sua conexão declara é escrito como o infra.endpoint do modelo, e um escrito como referência é nomeado ao lado de sua entrada, sendo usado o próprio endereço do Component até que seja definido; uma conexão que não declara nenhum endpoint deixa a entrada sem infraestrutura, e o próprio endereço do Component permanece. Como toda Release de rascunho, ela escreve metadata.environment como development e, sem destino, um spec.manifest vazio que a importação marca como pendente; com um destino, a importação gera o Manifest como rascunho, como descreve O que um destino adiciona.

O agente declarativo que os testes deste importador importam, do provedor OpenAI com uma conexão por chave, um servidor MCP que apresenta uma chave própria, uma ferramenta de função e uma pesquisa na web, importado como um arquivo próprio, é gerado como rascunho, sem nenhuma configuração, com seu name, LearnAgent, assim:

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"

Um texto que o rascunho copia de um agente declarativo para o Aggregate, em um valor ou em um comentário, escreve cada {{ como {{`{{`}}, de modo que ele é lido de volta como está escrito depois que o Aggregate é avaliado.

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"

Assim que a imagem é respondida, o agente é renderizado executando-a, recebendo o endpoint do modelo como OPENAI_BASE_URL, seu id como OPENAI_MODEL e sua credencial como OPENAI_API_KEY, e o modelo é renderizado como um Service que alcança seu host. Nenhuma variável carrega o endereço do servidor MCP: é o provedor do modelo, não a aplicação, que o alcança.

Valores de credenciais que um agente declarativo contém

A chave que uma conexão key apresenta — escrita sob key ou apiKey, no modelo ou em um servidor MCP — é o único membro que o Agent Framework marca como credencial: é o único valor que seu carregador oculta no que registra em log. Cada chave que um agente declarativo escreve como literal é escrita no comentário acima da entrada do agente na Release, como o agente declarativo a escreve, e por padrão levada como está escrita e nomeada em um aviso credential-carried por seu agente e seu campo, como model.connection.key, nunca por seu valor. A url de um servidor MCP, escrita inteira no mesmo comentário e nomeada por seu campo — tools.microsoft_learn.url of node LearnAgent is carried as written —, é um membro da configuração de um servidor MCP, e o endpoint de um modelo conectado é uma entrada que o Agent Framework marca como não credencial. Com a configuração empty_credentials em marked, as chaves e as url dos servidores MCP são escritas sem valor — o comentário nomeando cada uma apenas por seu campo — e relatadas com credential-emptied, e o endpoint do modelo é levado; em all, o infra.endpoint do modelo também é omitido, nomeado no comentário acima de sua entrada como deixado para a Release, e o endereço padrão do Component é usado até que seja definido. Um valor escrito como =Env.NAME não contém nenhum, então é nomeado por sua variável, junto com a condição sob a qual o Agent Framework o lê do ambiente — model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads … — independentemente do que diga a configuração, e não é relatado com nenhum dos dois códigos; um valor escrito como qualquer outra expressão é nomeado como tal e nunca escrito.

As configurações que ele lê

O importador Agent Framework lê target_namespace, empty_credentials e render_mode, como Configurações os descreve, e nenhuma outra configuração.

O que um destino adiciona

Uma importação que recebe um destino — --target em aggrega import, ou target na ferramenta de importação do assistente e no método aggrega/import da sessão, nomeando uma capacidade de provedor como compose ou helm — repassa esse destino ao importador, de modo que o importador gera os rascunhos para ele: cada segredo na forma que esse destino lê, e as linhas de que só esse destino precisa, escritas ativas, enquanto as linhas de que só outro destino precisa são omitidas. No compose, essas linhas incluem infra.published_port onde quer que o importador publique um serviço no endereço de loopback do host, como diz a seção de cada importador; uma porta que o importador escolhe nunca recebe um número que outra porta da Release já usa. A importação então gera o Manifest como rascunho ao lado do que o importador gerou, qualquer que seja o importador executado: manifest.yaml, ao lado da Release de rascunho e nomeado e versionado como ela — ou, onde o importador não gerou nenhuma Release como rascunho, ao lado do Aggregate de rascunho e nomeado e versionado como ele.

Para cada tipo de componente e cada tipo de feature de que os rascunhos precisam — nos componentes do Aggregate de rascunho, em suas conexões e em seus subsistemas, nos Aggregates do catálogo que ele compõe, como core/dify, e nos vínculos da Release de rascunho —, o Manifest mapeia o tipo para a Recipe, ou, para um tipo de feature, para a feature recipe, dessa capacidade que o catálogo do workspace oferece para ele: a que existe, contando várias versões de uma mesma como uma; ou, onde há várias de nomes diferentes, a que leva o nome do próprio tipo, como helm/postgres para core/datastore/postgres. Um tipo sem nenhuma, ou com várias das quais nenhuma tem esse nome, é deixado sem mapeamento, um aviso o nomeia e diz por quê, e um build dos rascunhos é interrompido nomeando cada instância ou vínculo dele até que você o mapeie.

Onde só o importador sabe qual de várias Recipes se aplica, ele mesmo gera o Manifest como rascunho — o importador MCP mapeia cada servidor, por sua chave, para a realização de como o servidor é executado, e um importador que vincula um segredo pelo nome mapeia core/referenced-secret para helm/k8s-existing-secret — e a importação o completa: cada mapeamento escrito pelo importador que o catálogo oferece para esse tipo e essa capacidade é mantido, qualquer outro é descartado com um aviso, e os tipos que ele deixa são mapeados como acima.

O spec.manifest da Release de rascunho, escrito vazio sem destino, é definido como o nome do Manifest, o comentário acima dele é removido, e nada mais na Release muda. aggrega import descreve isso por completo.

Configurações

Um importador recebe as configurações da entrada plugins.importer que o vincula, sob with.settings, como descreve Qual importador transforma uma fonte em rascunhos. Sem entrada, ou sem configurações, cada configuração assume seu valor padrão.

plugins:
importer:
- uri: importer/langflow:<version>
with:
settings:
target_namespace: payments
reuse_mode: hints-only
ConfiguraçãoPadrãoO que ele faz
target_namespaceimportedO namespace sob o qual as entidades geradas como rascunho são nomeadas: <target_namespace>/<category>/<name> para um Component e <target_namespace>/<name> para o Aggregate e a Release, sendo <name> o nome próprio da fonte, senão o nome do seu diretório ou o nome do seu arquivo sem a extensão, senão flow, escrito em minúsculas com cada sequência de caracteres que não sejam letras e dígitos ASCII convertida em um único hífen, como descreve Como um rascunho é nomeado.
reuse_modeauto-apply-above-thresholdauto-apply-above-threshold referencia o Component do catálogo com a melhor correspondência para um nó ao qual o rascunho dá um Component próprio cuja correspondência está no nível alto e tem pontuação igual ou superior a reuse_threshold, e gera como rascunho todos os outros. hints-only gera como rascunho cada um desses nós e não referencia nenhum Component do catálogo, registrando uma correspondência forte como dica. Qualquer outro valor é lido como hints-only.
reuse_threshold0.85A pontuação igual ou superior à qual auto-apply-above-threshold referencia um Component. Lida apenas nesse modo; 0 é lido como o valor padrão.
emit_hintstrueSe o arquivo de um Component gerado como rascunho começa com um comentário que nomeia o Component do catálogo com o qual se parece, para uma correspondência de nível alto ou médio. O Aggregate de rascunho traz o mesmo comentário acima da entrada desse nó, e acima de uma entrada referenciada um que nomeia o próximo melhor candidato pelo qual ela poderia ser trocada, ou que diz que nenhum pontuou acima de zero. false omite os comentários.
render_modehumanhuman escreve os rascunhos descritos acima. llm não escreve nenhum rascunho, e escreve em vez disso todo o registro de decisões — cada nó, os candidatos pontuados e a escolha feita — como um único documento, import-decisions.json, para outra ferramenta ler. Qualquer outro valor é lido como human.
mapping_overridesnenhumMapeamentos sobrepostos à tabela própria do importador, tendo como chave o formato e depois o tipo de nó — para o importador Compose, o repositório da imagem. Cada entrada nomeia o component para o qual um nó desse tipo é mapeado e, opcionalmente, sua category, os traits — rótulos e seus valores — que um Component correspondente traz, e uma palavra vendor que seu nome traz. Uma entrada para um tipo de nó que a tabela já mapeia toma o lugar da linha da tabela. Apenas as entradas sob o formato sendo importado são lidas.
layoutplatformplatform gera como rascunho a plataforma que executa o fluxo, levando o fluxo, com cada parte dele um Component próprio conectado à plataforma, como descreve A plataforma que leva o fluxo. nodes gera como rascunho cada nó como um Component próprio, como descreve Nó a nó. Para o importador Dify, platform gera como rascunho a instalação do Dify que leva a aplicação, como descreve No que uma aplicação se torna. Qualquer outro valor gera como platform, e a importação avisa com unknown-layout.
empty_credentialsnoneQuais valores de credenciais são escritos vazios no fluxo que a plataforma leva, como Valores de credenciais que o fluxo contém os lista, na Release que o importador MCP gera como rascunho, como Valores de credenciais que um servidor contém os lista, na Release que o importador Compose gera como rascunho, como Valores de credenciais que um serviço contém os lista, na aplicação que o importador Dify leva, como Valores de credenciais que uma aplicação contém os lista, na Release que o importador CrewAI gera como rascunho, como Valores de credenciais que uma declaração contém os lista, na Release que o importador LangGraph gera como rascunho, como O ambiente que uma configuração indica os lista, na Release que o importador Google ADK gera como rascunho, como Valores de credenciais que uma configuração contém os lista, e na Release que o importador Agent Framework gera como rascunho, como Valores de credenciais que um agente declarativo contém os lista. none não escreve nenhum vazio: cada um é levado como está escrito e nomeado em um aviso credential-carried. marked escreve vazio o que um formato marca como credencial e cada membro da configuração de um servidor MCP. all escreve vazias também as entradas que um formato marca como não credencial mas que podem conter uma — cabeçalhos de requisição, parâmetros de consulta, uma requisição escrita como linha de comando, uma entrada nomeada como uma chave. O que o rascunho escreve para que um nó alcance sua conexão é escrito independentemente do que esta configuração diga. Qualquer outro valor interrompe a importação, que não gera nada como rascunho, com unknown-empty-credentials. Um rascunho feito nó a nó não lê nenhum valor, e portanto não lê esta configuração.
attach_egress_allowlistfalsetrue vincula a Feature core/egress-allowlist da biblioteca padrão a cada instância de plataforma que o rascunho escreve, como egress-allowlist, sem definir nada de seu infra, como descreve O que o rascunho deixa para a Release. false não vincula nada. Um rascunho que não escreve nenhuma plataforma, com layout: nodes, e o rascunho do importador Dify, cuja entrada para a instalação do Dify não aceita nenhuma Feature, não vinculam nada independentemente do que esta configuração diga, e com ela em true a importação avisa com feature-not-attached. Qualquer valor que não seja um booleano é lido como false.

Uma configuração que um importador não conhece é ignorada.

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

O que uma importação relata

Cada importador core relata como diagnósticos o que não conseguiu fazer e o que fez em nome do autor. O comando imprime cada um na saída de erro padrão como <severity>: <message>, antes da linha de cada nó; o método aggrega/import da sessão do editor e a ferramenta import do assistente retornam cada um também com seu code.

CódigoSeveridadeRelatado quando
parse-failedhaltA fonte não pode ser analisada: seu analisador a recusa, e a mensagem traz o motivo do analisador.
no-nodeswarnA fonte não traz nenhum nó que o importador reconheça — para o importador MCP, nenhum servidor, para o importador Compose, nenhum serviço e nenhum modelo, para o importador CrewAI, uma crew que não declara nenhum agente, para o importador LangGraph, uma configuração que não declara nenhum grafo, para o importador Google ADK, uma configuração raiz que não declara nenhum agente, ou nenhum dos arquivos que with.sources entrega a uma importação contém uma configuração raiz, e para o importador Agent Framework, uma fonte que não declara nenhum agente de prompt.
unknown-layoutwarnlayout não é nem platform nem nodes; o fluxo é gerado como rascunho como platform.
unknown-empty-credentialshaltempty_credentials contém um valor diferente de none, marked ou all, nomeado junto com a configuração; a importação não gera nada como rascunho.
platform-not-in-catalogwarnO catálogo do workspace não contém nenhum Component com o nome da plataforma, então nenhuma parte é conectada a ela; para o importador Dify, nenhum core/ai-agent/dify, e core/dify é composto mesmo assim.
part-not-placedwarnUma parte do fluxo não está conectada a nenhum socket da plataforma, com o motivo; ela permanece no fluxo.
socket-selector-unreadablewarnO seletor que um socket da plataforma declara não pode ser lido, então nenhuma parte é conectada a ele; uma vez para cada socket.
credential-carriedwarnUm valor de credencial é levado como está escrito no fluxo que o rascunho leva, ou na Release que o importador MCP, Compose, CrewAI, LangGraph, Google ADK ou Agent Framework gera como rascunho, nomeado pelo seu nó — ou seu servidor, serviço, agente ou configuração — e seu campo, nunca pelo seu valor, junto com o valor de empty_credentials que o escreve vazio.
credential-emptiedwarnUm valor de credencial é escrito vazio no fluxo que o rascunho leva, ou na Release que o importador MCP, Compose, CrewAI, LangGraph, Google ADK ou Agent Framework gera como rascunho, onde empty_credentials o pede, nomeado pelo seu nó — ou seu servidor, serviço, agente ou configuração — e seu campo.
carriage-returns-rewrittenwarnOs retornos de carro do fluxo são escritos como avanços de linha, indicando quantos.
definition-respelledwarnOs valores do fluxo são escritos na grafia em que as próprias ferramentas da plataforma os leem, os mesmos valores, indicando quais e por quê: os handles das arestas de um fluxo do Langflow, escritos como o editor do Langflow os escreve. Um valor que o rascunho escreve para que o fluxo alcance uma parte, ou um que pode carregar uma credencial, nunca é reescrito — ele continua sendo o da conexão, ou o de empty_credentials — e o aviso conta cada valor não reescrito.
definition-not-carriedwarnO fluxo não é levado em values.flow_definition, ou a aplicação do importador Dify em parameters.app_definition, com o motivo.
part-reads-connectionwarnComo o fluxo alcança uma parte conectada por meio de sua conexão, ou como uma conexão alcança, como está escrita, um nó que o rascunho não conecta a nenhum socket.
part-address-in-flowwarnO fluxo alcança uma parte conectada por um caminho diferente de sua conexão, indicando qual.
model-not-namedwarnvalues.model de uma parte referenciada é deixado para o autor, com o motivo.
feature-attachedinfoattach_egress_allowlist vinculou core/egress-allowlist a uma plataforma gerada como rascunho, com o que a Release define dela; uma vez para cada instância de plataforma.
feature-not-attachedwarnattach_egress_allowlist é true e o rascunho não escreve nenhuma plataforma, ou compõe a instalação do Dify, cuja entrada não aceita nenhuma Feature, então nada é vinculado.
part-configured-in-platformwarnUm nó de uma aplicação Dify nomeia algo que o Dify configura por conta própria — um modelo e seu provedor, uma ferramenta, uma base de conhecimento, uma estratégia de agente, um plugin — então o rascunho não conecta nenhuma parte para ele.
dsl-version-newerwarnUma aplicação Dify está escrita em uma versão da DSL mais recente do que a que escreve a versão do Dify que core/ai-agent/dify executa por padrão.

Uma importação que recebe um destino relata, após os diagnósticos do importador, o que a geração do Manifest como rascunho encontrou: um warn que nomeia cada tipo de componente ou de feature que o Manifest deixa sem mapeamento e por quê, e um info quando a Release de rascunho já nomeia um Manifest ou nenhuma Release de rascunho o referencia. Esses são da própria importação, e não de um importador, e não trazem nenhum código; O que um destino adiciona os descreve. Toda importação relata então, também como seus, um warn para cada valor que os rascunhos ainda têm pendente, nomeando o arquivo de rascunho, o caminho da chave e sua descrição, e, sob --offline, quando gerou uma Release como rascunho e não tem nada pendente, um info que nomeia o aggrega pull a executar em seguida, como descreve O arquivo de respostas da importação.

Publicados com cada release do compilador

Cada release do compilador compila os dez importadores a partir das fontes com tag e gera suas entidades Plugin a partir dos próprios importadores, de modo que a capacidade, as assinaturas de reconhecimento, as funções do host e a descrição de uma entidade são o que seu importador relata. A release assina e publica todos os dez, importer/langflow, importer/flowise, importer/n8n, importer/mcp, importer/compose, importer/dify, importer/crewai, importer/langgraph, importer/google-adk e importer/agent-framework, na versão da release, ao lado dos outros plugins core, e registra suas entidades junto com as entidades dos outros plugins core para o catálogo padrão.