Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler 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 publica-os em 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 registo MCP, server.json, em JSON
importer/composeimport:composeuma aplicação Compose — compose.yaml, docker-compose.yml e os respetivos ficheiros de substituição — em YAML
importer/difyimport:difyuma aplicação exportada do Dify na 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 as respetivas 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 ficheiro de ambiente que a configuração indica, apenas os nomes das variáveis, quando a importação recebe esse ficheiro em with.sources
importer/google-adkimport:google-adkos agentes declarados nos ficheiros Agent Config de uma aplicação construída sobre o Google ADK — root_agent.yaml e as configurações que os seus subagentes indicam — 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, pelo que os importadores lançados com o compilador na versão X.Y.Z comunicam a versão X.Y.Z, e as respetivas entidades Plugin registam-na. Ao contrário dos plugins listados em Plugins integrados, 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, pelo que cada um serve o seu formato em qualquer espaço de trabalho, sem nenhuma entrada no respetivo catálogo.

Os dez assentam no 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, seja qual for o seu formato — pontuar os Components do catálogo do espaço de trabalho face a cada nó, decidir se faz referência a um deles ou gera um novo como rascunho, dispor o rascunho, transportar os valores de credenciais que contém ou escrevê-los vazios conforme uma definição pede, escrever os rascunhos e ler as definições descritas abaixo — cabe a esse pacote, e apenas ler o formato, e conhecer a plataforma em que os seus fluxos são executados, é próprio de cada importador. O importador MCP gera como rascunho uma instância de um Component por servidor, pelo que não pontua nada; partilha com o pacote a leitura das definições que lê, a decisão sobre valores de credenciais e as convenções pelas quais os seus rascunhos são nomeados e descritos, como descreve O importador MCP. O importador Compose decide cada serviço a que faz corresponder como os importadores de fluxos decidem um nó, através do mesmo pacote, renderiza os seus rascunhos como eles e partilha o resto como o importador MCP, como descreve O importador Compose. O importador Dify gera como rascunho a instalação do Dify que a biblioteca padrão monta, que transporta a aplicação, através do rascunho de plataforma do mesmo pacote na forma que este 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 por cada agente que um projeto declara, ligada ao modelo que esse agente indica, e partilha o resto como o importador MCP, como descreve O importador CrewAI. O importador LangGraph gera como rascunho uma instância do agente LangGraph da biblioteca padrão por cada grafo que a configuração de uma aplicação declara, ligada ao armazenamento de dados em que o seu checkpointer guarda o estado, e partilha o resto como o importador MCP, como descreve O importador LangGraph. O importador Google ADK gera como rascunho uma instância do agente ADK da biblioteca padrão por cada árvore de agentes que as configurações de uma aplicação declaram, ligada ao modelo que a árvore indica quando o ADK envia os seus pedidos para a API do Gemini, e partilha o resto como o importador MCP, como descreve O importador Google ADK. O importador Agent Framework gera como rascunho uma instância do agente Agent Framework da biblioteca padrão por cada agente declarativo, ligada ao modelo OpenAI que esse agente indica — com cada servidor MCP que indica escrito em comentários, uma vez que o fornecedor do modelo o alcança como uma ferramenta alojada — e partilha o resto como o importador MCP, como descreve O importador Agent Framework. O funcionamento do socket importador, e o que lhe é entregue, está descrito em O socket importador.

Esta página é a referência sobre o que cada importador lê e esboça. Para importar um projeto seu e compilar o resultado, comece em Importação, que acompanha um projeto desde a sua origem até uma compilação, um formato de cada 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 o seu módulo — na cache de conteúdo do espaço de trabalho —, a importação lê-o daí, sem precisar de rede para isso. Onde não o contém, a primeira importação que precisa dele obtém-no do registo predefinido do espaço de trabalho, na versão do compilador, e:

  • confronta-o com o digest que o binário traz, pelo que só é executado o módulo que o lançamento do compilador publicou;
  • verifica-o como um pull verifica um plugin que obtém — a sua assinatura segundo a política de confiança desse registo, e as funções host que utiliza face às que a sua entidade Plugin regista;
  • guarda-o na cache de conteúdo do espaço de trabalho, que é a única coisa escrita para ele: nenhum ficheiro de bloqueio, e nenhum registo de plugins de confiança, porque uma importação não fixa nenhum importador.

Todas as importações posteriores leem-no da cache de conteúdo. Um módulo que não passa na verificação é recusado, e nada é guardado. Numa pasta que nenhum espaço de trabalho marca não existe cache de conteúdo onde guardá-lo, pelo que a obtenção é aí recusada, indicando a pasta e como nomear um espaço de trabalho ou tornar a pasta num. O módulo nunca é lido de ao lado de uma entidade Plugin com o mesmo nome noutra versão numa pasta de catálogo: esse módulo pertence à outra entidade.

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

  • Executar a importação uma vez com a rede disponível, onde o espaço de trabalho está offline ou o seu registo não pôde ser contactado. Essa execução obtém-no, e todas as execuções posteriores são offline.
  • Colocar o seu módulo ao lado de uma entidade Plugin desse importador nessa versão numa pasta de catálogo, com o nome que a mensagem indica — 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 o seu módulo lido de ao lado dela; uma entidade aí sem módulo ao lado não é executada no lugar dele, e o importador core é obtido como descrito acima. Onde o registo não contém o módulo, ou o espaço de trabalho não indica nenhum registo predefinido, esta é a única solução que a mensagem indica.

Qual é executado ao lado dos importadores próprios

Os importadores core são candidatos ao lado dos importadores que o catálogo do espaço de trabalho contém, segundo as regras pelas quais qualquer 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 indica.
  • Onde o catálogo contém um importador com 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 anexe nenhum dos dois é recusada indicando 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 indique aquele que se pretende resolve a questão.
  • Um importador que o catálogo contenha com o mesmo nome e a mesma versão que um importador core, com o seu módulo ao lado da sua entidade, é o que é executado, lido daí.
  • Uma entidade Plugin com o nome de um importador core e sem módulo ao lado dela na sua pasta de catálogo — um checkout de um catálogo que regista os importadores que uma versão publicou, por exemplo — é uma que nenhuma importação poderia executar, já que o seu módulo não é lido de nenhum outro lugar; por isso não é candidata à execução, embora as assinaturas que regista continuem a participar no reconhecimento de uma origem. Na versão do próprio compilador, o importador core é executado no lugar dela. Em qualquer outra versão, mais antiga ou mais recente, é ignorada, e a escolha faz-se entre os importadores que podem ser executados — a menos que uma entrada plugins.importer indique exatamente essa versão, ou que nenhum importador desse nome que possa ser executado anuncie o formato pedido, como quando a entidade regista um formato que o importador do próprio compilador não regista. Nesse caso, continua candidata segundo as regras acima, e uma importação que a escolha é interrompida, indicando a pasta onde o seu módulo deve ser colocado.

Seja qual for o importador do próprio catálogo escolhido, o 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 com o mesmo nome noutra versão pertence a essa entidade.

Como uma origem é reconhecida

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

  • Langflow — uma origem que é analisada como JSON e contém um array em data.nodes.
  • Flowise — uma origem que é analisada como JSON, contém arrays em nodes e edges, e não contém nada em data.nodes.
  • n8n — uma origem que é analisada como JSON, contém um array em nodes e um objeto em connections, e não contém 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 contém um objeto em mcpServers; uma origem que é analisada como JSON com comentários, tal como o Visual Studio Code a lê, se chama .vscode/mcp.json e contém um objeto em servers; ou uma origem de qualquer nome que é analisada como JSON e cujo $schema é um texto que começa por https://static.modelcontextprotocol.io/schemas/, uma descrição de servidor de registo. Um nome é comparado com o final do caminho que a importação recebe, pelo que project/.vscode/mcp.json é reconhecido, enquanto mcp.json entregue a partir de dentro de .vscode, ou o ficheiro de um cliente com qualquer outro nome, é importado indicando --format mcp.
  • Compose — uma origem que é analisada como YAML, tem um dos nomes com que o Compose lê por predefinição um ficheiro Compose ou o respetivo ficheiro de substituição — 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 contém um objeto em services. Um ficheiro Compose com qualquer outro nome é importado indicando --format compose.
  • Dify — uma origem de qualquer nome que é analisada como YAML, contém o texto app em kind, e contém algo em app.mode e em version, como acontece com qualquer aplicação que o Dify exporta.
  • 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 contém uma lista em agents, ou uma origem chamada agents/<name>.jsonc ou agents/<name>.json que é analisada como JSON com comentários e contém algo em role. Um projeto clássico identifica os seus agentes e as suas tarefas por nomes escolhidos pelo autor, pelo que os seus dois ficheiros se distinguem apenas pelos nomes.
  • LangGraph — uma origem chamada langgraph.json que é analisada como JSON e contém um objeto em graphs; ou uma origem de qualquer nome que é analisada como JSON, contém um objeto em graphs e cujo $schema é o texto https://langgra.ph/schema.json, o esquema que o LangGraph publica para a sua configuração. Uma configuração com outro nome que não indica nenhum esquema é importada indicando --format langgraph. Nenhuma assinatura de importador indica um ficheiro de ambiente, pelo que reconhecer um diretório não abre nenhum.
  • Google ADK — uma origem chamada root_agent.yaml que é analisada como YAML e contém algo em name e em instruction, como acontece com a configuração de um LlmAgent, ou um texto em agent_class e algo em name, como acontece com a de qualquer outro agente. Uma configuração com outro nome é importada indicando --format google-adk. Nenhuma assinatura indica a configuração de um subagente, que pode ter qualquer nome, pelo que reconhecer um diretório não abre nenhum ficheiro YAML além de root_agent.yaml.
  • Agent Framework — uma origem de qualquer nome que é analisada como YAML, contém o texto Prompt em kind e um objeto em model, como acontece com um agente declarativo que indica o seu modelo; o Agent Framework carrega um agente declarativo de qualquer ficheiro que a sua aplicação indique, pelo que a assinatura não indica nenhum ficheiro. Um agente declarativo que não indica nenhum modelo, ou que escreve o seu tipo com outra combinação de maiúsculas e minúsculas ou como Agent, é importado indicando --format agent-framework.

Uma origem que corresponda a duas delas é recusada indicando ambos os formatos, e é importada indicando o correto com --format. Os importadores Langflow, Flowise, n8n e LangGraph leem a sua origem através do analisador que serve parse:json; o importador MCP, uma configuração que lista os seus servidores em servers através daquele que serve parse:jsonc e qualquer outra origem através daquele que serve parse:json; os importadores Compose, Dify, Google ADK e Agent Framework, através daquele que serve parse:yaml; e o importador CrewAI, os ficheiros de um projeto clássico através daquele que serve parse:yaml e os restantes através daquele que serve parse:jsonc: aquele que o catálogo do espaço de trabalho serve, onde sirva um, e caso contrário o analisador que o próprio compilador inclui para essa sintaxe (ver Plugins integrados). Assim, uma importação através de qualquer um deles não precisa de nenhum analisador no catálogo, e nada é obtido para um. Um analisador que o catálogo efetivamente sirva é o utilizado, e o do compilador não tem qualquer papel. Os importadores Langflow, Flowise, n8n, Dify e Agent Framework não declaram nenhum padrão de ficheiro, pelo que cada um lê um único ficheiro, e uma importação de um diretório através de qualquer um deles é recusada; o importador MCP declara os quatro nomes de ficheiro dos clientes, pelo que um diretório é lido através das configurações de cliente que contém; o importador Compose declara os oito nomes de ficheiro do Compose, pelo que um diretório é lido através dos ficheiros Compose que contém; o importador CrewAI declara os seis nomes das declarações de um projeto, pelo que o diretório de um projeto é lido através das suas declarações e de nada mais; o importador LangGraph declara langgraph.json, pelo que o diretório de uma aplicação é lido apenas através da sua configuração, e nunca são lidos nem o seu código nem um ficheiro de ambiente; e o importador Google ADK declara root_agent.yaml, pelo que o diretório de uma aplicação é lido apenas através da sua configuração raiz — as configurações que os seus subagentes indicam chegam ao importador apenas no with.sources do seu anexo — e nunca são lidos nem o seu código nem o seu ficheiro de ambiente. Uma assinatura que não indica nenhum ficheiro — as dos importadores Langflow, Flowise e n8n, a do importador MCP para uma descrição de servidor de registo, a do importador LangGraph para uma configuração que indica o seu esquema, a do importador Dify e a do importador Agent Framework — aplica-se a qualquer ficheiro importado isoladamente: uma importação que não indica nenhum formato lê um ficheiro desses como JSON, e como YAML, para experimentar ambos, seja qual for o importador a que se destina, através desses mesmos analisadores — o compilador inclui ambos, pelo que nada é obtido para nenhum deles. Um ficheiro que contenha um comentário ou uma vírgula final não é analisado como JSON, pelo que nenhuma assinatura que leia JSON o reconhece; as assinaturas do importador CrewAI para crew.jsonc, agents/<name>.jsonc e as respetivas variantes .json, e a do importador MCP para .vscode/mcp.json, leem JSON com comentários, através do analisador que o compilador inclui para essa sintaxe onde o catálogo não sirva nenhum.

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

Como um rascunho é nomeado

Cada 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 definição target_namespace, imported a menos que seja definida outra. <name> é o primeiro dos seguintes que não esteja vazio:

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

    ImportadorO nome que lê
    importer/langflowo name do fluxo
    importer/flowisenenhum: uma exportação não traz um nome próprio
    importer/n8no name do workflow
    importer/mcpo name da descrição de um servidor de registo; a configuração de um cliente não traz nenhum
    importer/composeo name de nível superior do projeto, o de um ficheiro de override em vez do do ficheiro que este sobrepõe, tal como o Compose os funde
    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 trazem nenhum, já que um projeto clássico nomeia a sua crew no seu programa
    importer/langgrapho id do grafo que a configuração declara, já que uma configuração não traz 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, por inteiro — my.project mantém o seu ponto, escrito my-project — tal como o Compose dá a um projeto o nome do diretório que o contém; aggrega import . nomeia o diretório em que é executado;

  • o nome do ficheiro entregue isoladamente à 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 a si própria e todas são escritas da mesma forma; caso contrário, recebe o seguinte. Um nome escreve-se em minúsculas, cada sequência de caracteres que não sejam letras e algarismos ASCII como um único hífen, sendo removidos os hífenes em ambas as extremidades: Basic Prompting escreve-se basic-prompting, e SupportAgent supportagent. A mesma fonte recebe o mesmo nome em cada importação. Um Manifest que uma importação gera como rascunho para um destino recebe o nome da Release, ou o do Aggregate quando não é gerada nenhuma Release, como descreve O que um destino acrescenta.

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ó, o seu tipo a partir do data.type do nó, e os seus campos a partir das entradas de data.node.template cujo valor é um objeto que contém um type. As restantes entradas do template não são campos.
  • Um campo cujo objeto contém password: true entra no rascunho como ranhura de credencial, e qualquer outro campo como campo de valor. O nome do campo não tem qualquer papel, e colocar um nó no rascunho como Component não lê o valor de nenhum campo.
  • Uma nota afixada na área de desenho, 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 transporta o fluxo também lê, do fluxo: o 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 indica, e a configuração desse servidor — ou, em vez dele, os campos em que guarda o seu servidor; cada entrada que o Langflow não marca como credencial mas que pode conter uma, tal como Valores de credenciais que o fluxo contém as lista; o campo em que um nó indica o seu modelo, e o fornecedor do modelo em que é executado; e os campos através dos quais um nó alcança o endereço e a chave de uma parte, que reescreve. O que geram como rascunho diz o que acontece a 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ó, o seu tipo a partir do data.name do nó; as suas ranhuras de credencial a partir das entradas de data.inputParams cujo type é credential, pelo respetivo name; e os seus campos de valor a partir das chaves de data.inputs, excetuando as que data.inputAnchors indica — onde outro nó se liga como entrada, o que a aresta entre eles regista — e excetuando 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 qualquer papel em ela o ser.
  • Uma nota afixada na área de desenho, 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 transporta o chatflow também lê, deste: o seu id de nível superior, quando é um UUID; a credencial que um nó guarda em data.credential; o valor de cada entrada que os 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 a qualquer profundidade destas; 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, tal como Valores de credenciais que o fluxo contém as lista, e o membro em que a configuração de um agentflow indica o modelo ou a ferramenta que seleciona; a entrada modelName de um nó; e o Base Path de um nó OpenAI, a sua entrada basepath. O que geram como rascunho diz o que acontece a cada um.

O que o importador n8n lê

  • Os nodes do workflow e as suas connections, no nível superior da exportação.
  • Para cada nó, o seu name, que o identifica — as ligações do n8n indicam pelo nome os nós que unem, e os nomes dos nós de um workflow são únicos — e o seu type, escrito por inteiro, com o respetivo pacote: @n8n/n8n-nodes-langchain.lmChatOpenAi, por exemplo, ou n8n-nodes-base.httpRequest. Um nó sem nome é identificado pelo seu id.
  • Cada ligação que o workflow lista é uma aresta, do nó de onde sai para o nó em que entra, seja qual for o seu tipo: uma ligação main transporta dados de um nó para o seguinte, e uma ligação de IA — ai_languageModel, ai_tool, ai_vectorStore, ai_embedding, ai_memory e as restantes — entrega ao nó em que entra o modelo, a ferramenta, o armazenamento ou a memória que o nó de onde sai representa. Em qualquer dos casos, o nó em que uma ligação entra consome o nó de onde ela sai.
  • Cada tipo de credencial que as credentials de um nó indicam, e cada parâmetro de nível superior que o n8n marca como palavra-passe, entra no rascunho como ranhura de credencial; qualquer 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 afixada na área de desenho, um nó do tipo n8n-nodes-base.stickyNote, não é importada, e uma ligação para um nó que não é importado é descartada.
  • Gerar como rascunho a plataforma que transporta o workflow também lê, deste: o seu id de nível superior; cada credencial que um nó seleciona; cada parâmetro que o n8n marca como palavra-passe; o endereço que um nó cliente MCP chama; os cabeçalhos e os parâmetros de consulta que um nó envia com um pedido que o workflow compõe, tal como Valores de credenciais que o fluxo contém os lista; e o parâmetro em que um nó de modelo indica o seu modelo. O que geram como rascunho diz o que acontece a cada um.

O que geram como rascunho

Cada nó é pontuado face 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, pedidos 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 o seu componente Language Model, LanguageModelComponent, o modelo de chat que os seus fluxos iniciais chamam, para core/ai-model/openai, o modelo que a ligação de modelo da plataforma Langflow serve: o nó é executado no fornecedor de modelos que o seu campo provider indica, OpenAI por predefinição, e um nó que indica outro fornecedor nunca é associado a essa ligação, como descreve Que nós se tornam partes. A tabela do importador n8n mapeia os modelos de chat e de embeddings do n8n, a sua ferramenta cliente MCP para core/ai-tool/mcp, as suas ferramentas de pedido HTTP, a sua ferramenta SerpApi, os seus armazenamentos vetoriais Qdrant, PGVector, Chroma, Milvus e Weaviate, e as suas memórias de chat Postgres e Redis. Um nó que o n8n executa dentro do próprio workflow — um agente, uma chain, um acionador, uma memória que o workflow guarda no 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 quando o catálogo do espaço de trabalho contém o Component que indica. O comando comunica uma linha por cada nó que mapeou, indicando 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ó a que 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 ficheiro próprio: o Aggregate do rascunho indica o Component.

A forma como o rascunho é disposto cabe à definição layout. platform, a predefinição, gera como rascunho a plataforma que executa o fluxo, transportando o fluxo tal 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 por HTTP, e um armazenamento vetorial. nodes gera como rascunho cada nó como um Component próprio.

A plataforma que transporta o fluxo

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

  • aggregate.yaml — um Aggregate de rascunho com o nome do fluxo, como descreve Como um rascunho é nomeado. 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 transporta o fluxo em values.flow_definition e indica-o no 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, ligada à plataforma sob os uses da instância.
  • release.yaml — uma Release em rascunho com o mesmo nome, que indica esse Aggregate, com uma entrada para a plataforma e uma para cada parte, que transporta a imagem da plataforma e anexa por referência cada segredo de que o rascunho precisa, como descreve O que o rascunho deixa para a Release.
  • um ficheiro sob components/ por cada parte que gera como rascunho em vez de referenciar, escrito tal como o layout nó a nó escreve um nó gerado como rascunho.

Dado um destino, a importação gera manifest.yaml junto deles, como descreve O que um destino acrescenta.

Cada nó que não é uma parte fica dentro do fluxo que a plataforma transporta e não se torna nenhum Component. A sua decisão regista os candidatos face aos quais foi pontuado e não escolhe nada, e a sua justificação diz kept in the flow <platform> carries, with no Component of its own:, seguido do motivo — por exemplo, que nenhuma linha de mapeamento indica o seu tipo e que o seu candidato mais próximo obteve apenas 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 qualquer definição e sem destino sobre um catálogo que contém a plataforma Flowise da biblioteca padrão e os respetivos 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

O seu modelo de chat é a única parte ligada; os seus dois modelos de embeddings ficam no fluxo, uma vez que o socket de modelo aceita uma única ligação, e as suas ferramentas retriever ficam no fluxo, uma vez que nenhum socket da plataforma as aceita. A importação comunica 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 quando é um UUID, e o id de nível superior de um workflow do n8n — quando este tem de uma a 128 letras, dígitos, ., -, _ ou :, começando por uma letra ou um dígito. Quando a exportação não dá nenhum, ou dá um que contenha qualquer outro carácter, o rascunho escreve um UUID baseado em nome, derivado do nome do formato e do fluxo tal como é transportado, pelo que um fluxo produz sempre um mesmo identificador, e um comentário acima do valor diz que foi derivado. Um chatflow exportado a partir do editor do Flowise não contém nenhum id, pelo que lhe é dado um derivado.

Quando o catálogo do espaço de trabalho não contém nenhum Component com o nome da plataforma, o rascunho indica a plataforma mesmo assim e não lhe liga nenhuma parte: cada nó que teria sido uma parte fica no fluxo, é comunicado, e a importação avisa que o catálogo não contém tal Component.

Que nós se tornam partes, e onde cada um é ligado

Um nó é uma parte do fluxo quando uma linha da tabela de mapeamento do importador, ou uma entrada mapping_overrides, mapeia o seu tipo, ou quando o seu melhor candidato é pelo menos uma correspondência de nível médio. Um nó MCP Tools do Langflow é uma parte sejam quais forem as suas pontuações: indica o servidor MCP que chama, e esse servidor é a parte. Uma parte torna-se um Component próprio, referenciado ou gerado como rascunho exatamente como reuse_mode decide, e é ligada ao primeiro socket da plataforma — pela ordem em que a entrada de catálogo da plataforma declara os seus sockets — cujo seletor de etiquetas o Component da parte satisfaz: as etiquetas do Component que referencia ou, para uma parte que gera como rascunho, as do seu melhor candidato quando 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 etiquetas, fica no fluxo, e a importação comunica-a.

Estas regras restringem isto:

  • Um modelo do Langflow que indica outro fornecedor não recebe nenhuma ligação de modelo. Um nó LanguageModelComponent ou EmbeddingModel é executado no fornecedor de modelos que o seu campo provider indica ou, onde este está vazio, no fornecedor do modelo que o seu campo model seleciona. A plataforma entrega a sua ligação de modelo para um cliente compatível com OpenAI, pelo que um nó que indica qualquer fornecedor que não seja OpenAI — seja qual for o destino para o qual uma linha de mapeamento ou uma substituição o mapeie — nunca é associado ao socket model: é associado ao socket seguinte que o seu Component satisfaz, ou permanece no fluxo, com a sua decisão sem escolher nada e sem nenhum Component gerado como rascunho para ele, e a importação comunica-o indicando o fornecedor em que é executado. Um nó que não seleciona nenhum fornecedor, que o indica através de uma variável global ou que obtém o seu modelo de outro nó é associado como qualquer outra parte.
  • Um socket que aceita uma única ligação é ocupado por uma parte. Em todas as plataformas, o socket model aceita uma ligação, que as Recipes da plataforma entregam como um único OPENAI_BASE_URL e um único OPENAI_API_KEY. Quando várias partes são colocadas nele, ocupa-o a primeira cujo Component contém model.aggrega.ai/capability: generative — a primeira parte, quando nenhuma o contém — e qualquer outra fica no fluxo, comunicada com a parte que ocupa a ligação e com a forma como o fluxo a alcança tal como o seu nó está escrito.
  • O Langflow alcança uma ligação tools apenas através de um nó MCP Tools que a indique. A plataforma escreve o endereço de uma ligação tools na configuração do servidor do nó MCP Tools cujo campo mcp_server indica a ligação, pelo que um nó cujo template não contém nenhum campo mcp_server — seja qual for o seu tipo, e seja para o que for que uma linha de mapeamento ou uma substituição o mapeie — nunca é ligado ao socket tools: é ligado ao socket seguinte que o seu Component satisfaz, ou fica no fluxo, comunicado. Um nó MCP Tools que não indica nenhum servidor não é ligado a nenhum socket e é comunicado. O mesmo acontece com um cuja configuração do servidor inicia um servidor próprio — contém um command, ou define o modo Stdio — e a respetiva comunicação diz o que remover, uma vez que a compilação da plataforma é interrompida num nó que indica um servidor ao qual nenhuma ligação tools responde.
  • Um servidor MCP é ligado pelo nome que o fluxo lhe dá. Os nós de um fluxo que indicam um mesmo servidor alcançam uma única parte, gerada como rascunho uma só vez, através de uma única ligação. O alias da ligação é o nome do servidor quando o alias de uma ligação o pode assumir — letras, dígitos, hífenes e sublinhados — e nenhuma outra ligação desse socket entrega sob o mesmo nome de variável, o seu alias em maiúsculas com qualquer outro carácter escrito como sublinhado. Caso contrário, a ligação assume um alias derivado da chave da parte, o servidor do nó é renomeado para esse alias no fluxo que o rascunho transporta, e a decisão da parte di-lo.

A decisão de uma parte ligada diz a que socket da plataforma está ligada e através de que ligação, e indica cada socket para o qual foi preterida e porquê.

Como o fluxo transportado alcança cada parte

Onde o formato o permite, o fluxo que a plataforma transporta alcança cada parte ligada através da sua ligação, e o rascunho escreve no fluxo o que o leva a fazê-lo — o nome de uma variável, um endereço esvaziado, ou o que o nó enviaria em vez do que a ligação fornece, esvaziado, e nunca um valor. Isto é cablagem, não a remoção de um valor de credencial: o rascunho escreve-o seja o que for que diga a definição empty_credentials, uma vez que um valor mantido aí substituiria o que a ligação entrega.

  • Um nó MCP Tools do Langflow. A plataforma escreve o endereço que a sua ligação entrega na configuração do servidor do nó e, onde a ligação transporta 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 aí, pelo 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 do seu servidor, pelo que o rascunho escreve vazio o valor inteiro desse campo mantendo o seu tipo — um objeto como {}, uma lista como [], texto como uma cadeia vazia — uma vez que um cabeçalho mantido com o valor esvaziado continuaria a ser enviado, enquanto um objeto ou uma lista vazios não substituem nada.

  • Um nó de modelo ou de armazenamento vetorial do Langflow. A plataforma entrega uma ligação de modelo como OPENAI_BASE_URL e OPENAI_API_KEY, e uma ligação de armazenamento vetorial como variáveis com nomes baseados no seu alias, que o Langflow lê através de um campo que indica uma variável global: um campo cujo objeto contém load_from_db: true tem como valor o nome da variável, 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 destes 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 o seu api_key, como OPENAI_API_KEY;
    • o campo openai_api_base de um nó OpenAIEmbeddings, como OPENAI_BASE_URL, e o 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 o seu api_key, como OPENAI_API_KEY;
    • o campo pg_server_url de um nó pgvector, como AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING, em que <ALIAS> é o alias da ligação em maiúsculas, com cada carácter que não seja uma letra ou um dígito escrito como sublinhado.

    Um nó LanguageModelComponent ou EmbeddingModel é executado num de vários fornecedores de modelos — aquele que o seu campo provider indica ou, onde este está vazio, o fornecedor do modelo que o seu campo model seleciona — e entrega a sua chave a esse fornecedor. A plataforma entrega a ligação de modelo para um cliente compatível com OpenAI, pelo que um nó deste tipo só é escrito com as variáveis onde é executado em OpenAI. Um que é executado noutro fornecedor nunca é associado, como acima; um que não seleciona nenhum, que indica o seu fornecedor através de uma variável global ou que obtém o seu modelo de outro nó é escrito sem nenhuma delas, pelo que o rascunho nunca aponta outro fornecedor para a chave da ligação. Onde nenhum campo de um nó deste tipo indica o endereço da sua API — um nó LanguageModelComponent não contém nenhum para OpenAI, e o campo api_base de um nó EmbeddingModel pode faltar, ou estar vazio onde não pode indicar uma variável — o cliente OpenAI em que é executado obtém OPENAI_BASE_URL do ambiente, pelo que o nó alcança na mesma o endereço que a plataforma entrega.

    O cliente de um nó OpenAIEmbeddings envia os seus default_headers por cima dos que constrói a partir da chave, e funde o seu default_query por cima da consulta do endereço que chama, pelo que, num nó deste tipo que o rascunho liga, o valor inteiro de cada um é escrito vazio mantendo o seu tipo, tal como o 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 é transportado tal como está escrito, ou escrito vazio onde a definição o pede, como abaixo. Onde esse campo é o que contém o endereço da parte — e, para um nó LanguageModelComponent ou EmbeddingModel, indica um —, onde um nó deste tipo não é executado em OpenAI, ou onde o nó é de qualquer outro tipo, a importação comunica a parte como alcançada no endereço que o fluxo ou os valores predefinidos do seu componente indicam.

  • 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 este não seleciona nenhuma credencial, pelo que 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 predefinidos do nó, os seus baseOptions, por cima do cabeçalho que constrói a partir da chave, pelo que o rascunho escreve vazio o seu valor inteiro mantendo o seu tipo. Um nó de modelo de qualquer outro tipo é comunicado como alcançado no endereço que o chatflow ou os seus próprios valores predefinidos indicam.

  • 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 através de uma variável Runtime com esse nome, que nada cria no arranque. O rascunho não escreve nada para ele, e a importação comunica o passo que leva o chatflow a 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 ligação de modelo como OPENAI_BASE_URL e OPENAI_API_KEY, e uma ligaçã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 seleciona indica, ou no endereço que os seus próprios parâmetros contêm, e um workflow só lê uma variável de ambiente através 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 no seu valor predefinido, false, uma vez que defini-lo permite a cada workflow, e a cada utilizador que pode editar um, ler cada variável do ambiente da plataforma, incluindo as credenciais entregues. Assim, o rascunho não escreve nada no workflow para uma ligação, e cada parte ligada é comunicada como alcançada de outro modo que não através dela. Um nó cliente MCP alcança o seu servidor no endereço que o workflow contém — tal como a exportação o escreveu, ou nenhum onde a definiçã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 é transportado, cada parte ligada é comunicada com qual destes casos se verifica: part-reads-connection onde o fluxo alcança a parte através da sua ligação, e part-address-in-flow onde a alcança de outro modo que não através da sua ligação — num endereço que o fluxo contém, ou num que os valores predefinidos do seu componente indicam. A decisão da parte diz o mesmo.

Um nó que o rascunho não liga a nenhum socket pode ainda assim ser alcançado por uma ligação que o rascunho efetivamente liga, tal como o nó está escrito: um cliente OpenAI sem endereço nem chave próprios lê do seu ambiente as OPENAI_BASE_URL e OPENAI_API_KEY que a plataforma entrega para a ligação de modelo. Onde isso acontece, o rascunho escreve o nó como escreveria um ligado, pelo que nada do que contém é enviado em vez do que a ligação fornece, e comunica-o com part-reads-connection:

  • um nó OpenAIEmbeddings do Langflow cujo campo de endereço indica a variável OPENAI_BASE_URL que a plataforma entrega, lida como variável global, enquanto uma parte está ligada ao socket de modelo: os 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 guarda entre as suas entradas, enquanto uma parte está ligada ao socket de modelo: os seus baseOptions.

Em qualquer outro nó estes valores não são cablagem: são transportados tal como estão escritos, ou escritos vazios onde a definição o pede, como diz a secção seguinte.

Valores de credenciais que o fluxo contém

Antes de o fluxo ser transportado, a importação localiza cada valor nele que pode conter uma credencial, nos locais enumerados 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 guarde uma; e uma entrada que um formato marca como não sendo credencial mas que pode ainda assim conter uma — cabeçalhos de pedido, parâmetros de consulta, um pedido inteiro escrito como linha de comandos, uma entrada que contém uma credencial sob o nome de uma credencial.

Por predefinição, a importação não escreve nenhum deles vazio: o fluxo é transportado tal como foi exportado, e cada valor localizado que contém algo — nem uma cadeia vazia nem null — é indicado num aviso credential-carried, pelo seu nó e pelo seu campo — um cabeçalho ou um parâmetro de consulta pelo seu nome —, nunca pelo seu valor nem por qualquer parte dele, juntamente com o valor da definição empty_credentials que o escreve vazio. A definiçã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 sendo credenciais. Cada valor que escreve vazio é comunicado com credential-emptied, pelo seu nó e pelo seu campo, nunca pelo seu valor; um valor já vazio, ou null, é deixado como está e não é comunicado. Um valor que a definiçã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} — incluindo uma variável predefinida como ${workspaceFolder} ou ${userHome} — ou uma das formas que os clientes MCP definem, ${env:NAME} e ${input:id}. Seja o que for que diga a definição, é transportado tal como está escrito e não é indicado em nenhum aviso, seja qual for o formato do fluxo, tal como o importador MCP escreve um. O mesmo vale para um membro que é uma única referência dentro de um valor que um formato guarda como texto, como um mcpServerConfig do Flowise escrito como texto JSON, ou cabeçalhos e parâmetros de consulta guardados como objeto JSON em texto no Flowise e no n8n: escrito vazio, o texto mantém esse membro tal como está escrito.

Uma referência que contém 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 predefinido, ${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}. É localizada como qualquer outro valor — transportada e indicada num aviso credential-carried por predefinição, escrita vazia onde a definição o pede para o 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 a sua ligação — um endereço escrito vazio, o nome de uma variável, uma credencial selecionada ou cabeçalhos predefinidos escritos vazios, como descreve Como o fluxo transportado alcança cada parte — é cablagem: é escrito seja o que for que diga a definição, comunicado com o modo como o nó alcança a sua ligação, e nunca comunicado como valor de credencial. O que fica fora de todos os locais abaixo cabe ao autor rever, como diz o final desta secçã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, incluindo 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ó guarda em data.credential, que o seu parâmetro de credencial seleciona; o valor de cada entrada que os 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 a qualquer profundidade delas, tal como um agentflow guarda 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 guarda uma credencial como referência, nunca o seu valor, e o name da referência não é localizado: o n8n, ao importar o workflow noutra instância, resolve uma credencial cujo id não tem pelo seu tipo e nome. Uma credencial que uma exportação mais antiga seleciona apenas pelo nome indica uma credencial e não contém nenhuma, e não é localizada. E o valor de cada parâmetro que o n8n marca como palavra-passe nas definições dos seus nós base — o secret do nó Crypto, por exemplo, ou o password dos nós que criam um utilizador — onde quer que se encontre 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 fundidos por inteiro, sendo um item de qualquer outro tipo localizado por 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 na sua parte de utilizador, no seu caminho ou na sua consulta —, pelo que os três também são localizados, em ambos os formatos. Escritos vazios, o comando e cada argumento mantêm os seus membros, pelo que uma configuração que inicia um servidor próprio continua a ser lida como tal. Onde um nó MCP Tools do Langflow está ligado a uma ligação tools, o seu endereço é cablagem, como acima, e nunca é comunicado como valor de credencial. Uma configuração do Flowise escrita como texto que não se lê como um objeto JSON é localizada por inteiro, uma vez que nada no seu interior pode ser localizado.
  • Um nó MCP Tools do Langflow que não contém nenhum campo mcp_server guarda, em vez disso, o 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 comandos inteira, incluindo os seus argumentos, em command — e o Langflow também não marca nenhum deles como credencial, pelo que cada valor de cabeçalho, cada entrada de env, o endereço e a linha de comandos são localizados, mantendo os seus campos e entradas quando escritos vazios. Onde env é uma lista, cada entrada é comunicada pela sua posição, uma vez que o nome de uma variável e o seu valor partilham um mesmo texto. Um nó deste tipo não indica nenhum servidor MCP, pelo que nunca é ligado a uma ligaçã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 da sua configuração, num nó que o rascunho não liga: o seu valor inteiro, escrito vazio mantendo o seu tipo, como num nó ligado, e comunicado uma única vez, como headers.
  • Os componentes MCP Tools (SSE) e MCP Tools (stdio) do Langflow, que o Langflow marca como obsoletos, guardam o seu servidor num único campo cada — um nó MCPSse o seu endereço em url, um nó MCPStdio a sua linha de comandos inteira, incluindo os seus argumentos, em command — localizado por inteiro. Nenhum dos dois indica um servidor MCP, pelo que nenhum dos dois é ligado a uma ligaçã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 registo do n8n enumera — guarda o endereço do servidor no seu parâmetro endpointUrl, ou sseEndpoint na sua primeira versão, e os seus cabeçalhos apenas como credenciais que seleciona; o endereço é localizado por inteiro, ligado ou não.

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

  • Cabeçalhos de pedido — 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 predefinidos 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 — a sua versão atual guarda os dois primeiros, as 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 contém nenhum segredo, pelo que o valor de cada cabeçalho é localizado e o seu nome mantido, seja qual for a forma que os cabeçalhos assumam: 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 funde por inteiro nos cabeçalhos. Cada cabeçalho é comunicado pelo seu nome. Um item de uma lista que não é uma linha de cabeçalho é localizado por inteiro e comunicado pela sua posição. Os cabeçalhos escritos como texto são localizados por inteiro, exceto no Flowise e no n8n, onde o texto contém os cabeçalhos como objeto JSON: aí, escrito vazio, o texto é reescrito no local, com cada valor vazio, e comunicado uma única vez com os nomes dos cabeçalhos que contém. Um texto do n8n que começa por = é uma expressão que o n8n avalia quando o workflow é executado, e é localizado por inteiro. Escritos vazios, ficam vazios todos os valores, incluindo os dos cabeçalhos que não contêm nenhum segredo, como User-Agent, pelo que um pedido importado é enviado com eles vazios até que o seu autor os reponha.
  • 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 guarda entre as suas options. Cada um é enviado como a consulta de um pedido, e um parâmetro de consulta pode conter uma chave — algumas APIs de pesquisa recebem a sua como api_key na consulta —, pelo que cada um é localizado tal como os cabeçalhos: cada valor, mantendo o seu nome, seja qual for a forma que os parâmetros assumam, e cada um comunicado pelo seu nome; os parâmetros escritos como texto são localizados por inteiro, exceto no Flowise e no n8n, onde o texto os contém como objeto JSON, que, escrito vazio, é reescrito no local e comunicado uma única vez com os nomes que contém. Escritos vazios, ficam vazios todos os valores, incluindo os dos parâmetros que não contêm nenhum segredo, pelo que um pedido importado é enviado 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 o seu autor os reponha.
  • Cabeçalhos predefinidos e uma consulta predefinida num nó OpenAI que nenhuma ligaçã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ó se encontre, incluindo a configuração do modelo que um agentflow seleciona, onde o rascunho não liga o nó nem encontra uma ligação que o alcance tal como está escrito; onde o faz, são cablagem, como acima. Cada um é localizado por inteiro e, escrito vazio, mantém o seu tipo — um objeto como {}, uma lista como [], texto como uma cadeia vazia — e é comunicado uma única vez.
  • Um pedido inteiro escrito como linha de comandos — o curl_input de um nó APIRequest do Langflow e o curl de um nó Webhook, localizados por inteiro, incluindo o valor predefinido 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 o 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 por inteiro. Uma entrada cujo nome apenas se assemelha ao de uma credencial — o nome de uma chave armazenada noutro local, um nome de utilizador ou uma opção que o componente declara como não secreta — não é localizada.

Além dos valores que a definição escreve vazios, do que o rascunho escreve para que o fluxo alcance as suas partes, dos handles de uma aresta do Langflow, escritos como o editor do Langflow os escreve, e dos retornos de carro escritos como avanços de linha descritos abaixo, o fluxo é transportado tal como foi exportado: sem nada disto, byte a byte.

Uma ligação no rascunho não transporta nenhum valor de credencial: a Release em rascunho anexa por referência a que cada ligação apresenta, como descreve O que o rascunho deixa para a Release.

Cada valor que a definição deixa tal como está escrito chega ao rascunho, e o autor revê-o, guiado pelos avisos credential-carried. Também nenhuma regra sobre um campo alcança o resto de um fluxo, pelo que o autor também o revê antes de partilhar um rascunho: o próprio código de um componente, que o fluxo transporta e no qual um componente personalizado pode conter uma chave; as entradas que o editor acrescenta a um nó além das que o seu componente declara; o corpo com que um pedido é enviado, como o de um nó APIRequest ou httpAgentflow, que pode conter um token; os argumentos que um nó passa ao cliente do 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 na sua parte de utilizador ou na sua consulta; o código de um nó Code do n8n, e os cabeçalhos ou a consulta de um nó que envia um pedido que o importador não enumera acima; e texto livre, como um prompt ou uma mensagem.

O que o rascunho deixa para a Release

A Release em rascunho transporta, 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 funcionam — langflowai/langflow:1.6.0, flowiseai/flowise:3.1.3 e n8nio/n8n:1.110.1 —, sob um comentário que o indica. 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 indica-a.
  • A porta em que a plataforma é publicada, como infra.published_port, apenas com --target compose: 7860 para o Langflow, 3000 para o Flowise e 5678 para o n8n, as portas em que cada uma serve, que a respetiva Recipe do Compose publica no endereço de loopback do anfitrião, 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 eliminar a linha mantém o serviço interno. Um segundo fluxo de uma mesma importação recebe a porta seguinte que nenhum anterior recebe. Com qualquer outro destino, ou sem nenhum, não é escrita.
  • O segredo próprio da plataforma e a credencial de cada ligação de modelo, anexados por referência e nunca como valor: no Langflow, a ranhura admin_password, lida enquanto values.require_authentication se mantiver true; no Flowise, a ranhura owner_password, obrigatória enquanto values.flow_definition estiver definido; e, onde uma parte está ligada ao socket model da plataforma, a credential nessa ligação. A plataforma n8n não recebe nenhum segredo próprio. A forma como cada um é anexado depende do destino, como descreve Segredos, para cada destino.
  • Cada valor que nenhuma origem contém, escrito como uma cadeia vazia sob um comentário que diz o que é: 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 ligado à plataforma, infra.endpoint da respetiva parte. Cada um é um valor que a importação deve, respondido como descreve O ficheiro de respostas da importação.

A credencial que uma ligação a uma ferramenta ou a um repositório vetorial apresenta não é gerada no rascunho: a credencial de tal ligação interrompe a compilação onde a ferramenta não publica nenhum cabeçalho em que enviá-la, pelo que um comentário acima da entrada da plataforma a indica, para que a anexe 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á existe no namespace e que contém o valor sob a chave de dados value. Nenhuma origem pode fornecer esse nome, pelo que é escrito vazio sob um comentário que diz o que 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 ligação a um modelo — que um destino que substitui referências a variáveis, como faz o Docker Compose quando a stack arranca, lê do ambiente, pelo que nenhum ficheiro 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, 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 só a Release anexa chega sob uma única chave, value, pelo que a palavra-passe do proprietário ou do administrador e a credencial de uma ligação chegariam ambas sob ela. Por isso, o Aggregate declara cada uma com uma chave própria onde a plataforma aceita uma ligação: owner_password com a chave OWNER_PASSWORD no Flowise, admin_password com a chave LANGFLOW_SUPERUSER_PASSWORD no Langflow e a credential da ligação ao modelo com a chave OPENAI_API_KEY nas três plataformas, cada uma sob um comentário que explica porquê. Com --target compose, estas linhas são escritas ativas; sem destino, são escritas comentadas, como no exemplo acima, para que lhes possa retirar o comentário se compilar para compose; com qualquer outro destino, não são escritas. A Release anexa a origem de cada ranhura, indicando o mesmo tipo ou nenhum.

Com a definição attach_egress_allowlist a true, a instância da plataforma declara também a Feature core/egress-allowlist da biblioteca padrão sob features, como egress-allowlist, pelo que a plataforma só se liga aos componentes que as suas ligaçõ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 anexação e nada mais, uma vez que a anexação de um Aggregate não contém nenhum infra, e a Release gerada como rascunho não escreve nada disso: o comentário acima da entrada da plataforma indica, 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 a compilação é interrompida; admitted_destinations, uma lista que contém, para cada ligação cujo destino o cluster não executa, como um modelo alojado, uma entrada que indica o destino e um intervalo de endereços, sem a qual a compilação é interrompida indicando essa ligação; e aggrega.ai/namespace para a fronteira que contém a plataforma, uma vez que a política é colocada no namespace das suas cargas de trabalho e a compilação é interrompida quando estas não são emitidas em nenhum. Nenhuma destas chaves é escrita vazia, pelo que nenhuma está entre os valores que a importação deve. A decisão de cada parte ligada diz que a anexação admite a sua ligação, e a importação comunica a anexação como feature-attached. O Compose não tem política de rede, pelo que uma compilação de compose de um rascunho deste tipo é interrompida indicando a anexação; onde a plataforma aceita uma ligaçã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 a que 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 o seu nó seleciona, como values.model:

  • Langflow — o model_name de um nó OpenAIModel ou AnthropicModel; o model de um nó OpenAIEmbeddings; e a substituição model_name de um nó LanguageModelComponent ou EmbeddingModel onde estiver definida, e, caso contrário, o modelo que o 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 o 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 recentes do n8n o guardam. O n8n deixa de fora de uma exportação um parâmetro definido com o seu valor predefinido, pelo que um nó que mantém o modelo predefinido não indica nenhum na exportação.

Uma Release não pode escrever um valor. Assim, onde o nó não indica nenhum modelo que o rascunho possa escrever — não seleciona nenhum, indica-o através de uma variável global ou de uma expressão lida apenas quando o fluxo é executado, obtém-no de outro nó ligado 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 comunica-o 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 as suas quebras de linha finais, pelo que values.flow_definition é lido de volta como o próprio texto do fluxo. O texto de um Aggregate é lido como um template, pelo que cada {{ que o fluxo contém — um chatflow do Flowise escreve {{<node id>.data.instance}} para cada ligação entre dois nós — é escrito como {{"{{"}}, que a interpolação converte de volta nas duas chavetas, como descreve Texto que contém as suas próprias chavetas duplas. O nome de um modelo é escrito da mesma forma.

Um bloco literal não pode transportar todos os carácteres tal como estão escritos:

  • 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 os seus tokens, onde qualquer espaço em branco é lido da mesma forma, pelo que a plataforma lê o mesmo fluxo. A importação comunica quantos há com carriage-returns-rewritten.
  • Qualquer outro carácter que um bloco literal não possa transportar impede que o fluxo seja transportado: um carácter de quebra de linha — U+0085, U+2028 ou U+2029; um carácter de controlo 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 carácteres U+FFFE e U+FFFF; e um byte que não faz parte de uma sequência UTF-8. values.flow_definition fica então por definir, com um comentário que o diz, o resto é gerado como rascunho, e a importação comunica definition-not-carried para cada tipo de carácter, com quantos o fluxo contém e a linha e a coluna do primeiro.

O fluxo também não é transportado onde um valor que o rascunho escreve vazio ou de novo não está nos bytes da exportação no local onde a sua árvore analisada o contém, e a importação comunica definition-not-carried indicando o local desse valor. O identificador do fluxo é então o seu próprio onde o rascunho o pode transportar 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 ligação uses do nó que alimenta, com o seu socket e o seu alias ambos com o nome da chave do nó que a alimenta, pelo que um nó alimentado por vários dá a cada ligação um alias próprio.
  • um ficheiro sob components/ por cada nó que gera como rascunho — um Component de rascunho chamado <target_namespace>/<category>/<name>, com o nome retirado do tipo do nó, na versão 0.1.0, com os seus campos de valor como campos de cadeia de um objeto values fechado e os 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 indica esse Aggregate, com uma entrada para cada nó.

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

Transportar o próprio fluxo exportado

O rascunho predefinido transporta 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 escreva um fluxo à mão num Aggregate — num rascunho disposto nó a nó, ou num Aggregate próprio — escreve-o da mesma forma. Um Component que executa um fluxo tal 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, pelo que as chavetas 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 ligação entre dois nós, um prompt do Flowise indica uma variável como {{question}}, e uma exportação do Langflow contém o código-fonte dos seus componentes, onde as chavetas também podem aparecer. Cada {{ da exportação escreve-se como {{"{{"}}, dentro de um escalar de bloco, e a interpolação repõe o texto da exportação antes de as Recipes do Component o lerem; Texto que contém as suas próprias chavetas duplas descreve porquê. Um valor de credencial que a exportação contém pertence a um segredo que a Release anexa, não ao Aggregate: deve ser escrito vazio, tal como o rascunho faz onde a definição empty_credentials o pede.

# 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 enumera, ou o único servidor que uma descrição de servidor do registo MCP descreve, e gera como rascunho cada servidor como uma instância da ferramenta MCP da biblioteca padrão, core/ai-tool/mcp. Cada servidor é uma delas, pelo que o importador não pontua nenhum candidato e não comunica nenhuma decisão de mapeamento.

O que 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 enumeram os seus servidores por nome sob mcpServers; o .vscode/mcp.json do Visual Studio Code enumera-os sob servers, e um ficheiro que enumera servidores sob ambos é lido primeiro sob mcpServers. Um servidor cujo type é stdio, ou que não indica nenhum type e contém um command, é iniciado a partir de uma linha de comandos — o seu command e os seus args — com o seu env como ambiente. Um servidor cujo type é http, streamable-http ou sse, ou que não indica nem type nem command e contém um url, é alcançado no seu url e recebe os seus headers.
  • Uma descrição de servidor do registo. O server.json que o registo MCP publica: o seu name, e o seu primeiro pacote ou, quando não enumera nenhum, o seu primeiro remoto. Um pacote npm ou PyPI é iniciado a partir da linha de comandos formada pelo seu lançador — o seu runtimeHint, ou npx para npm e uvx para PyPI —, pelos seus runtimeArguments, pelo pacote com a sua versão, escrito <identifier>@<version> para npm e <identifier>==<version> para PyPI, e pelos seus packageArguments, com as suas environmentVariables como ambiente. Um argumento posicional é o seu value, ou o seu default; um argumento nomeado é escrito <name>=<value> quando tem um dos dois, e como o seu name quando não tem nenhum. Um pacote OCI é executado a partir da imagem que o seu identifier indica. Um remoto é alcançado no seu url e recebe os seus headers. Cada outro pacote e remoto que a descrição enumera é indicado num comentário, uma vez que uma instância executa apenas um deles.

Qualquer outro membro de um servidor — cwd, envFile, o auth do Cursor, ou um membro que o seu tipo de servidor não lê, como o url de um servidor iniciado a partir de uma linha de comandos — não é escrito em lado nenhum, e é indicado num comentário acima da entrada do servidor na Release, uma vez 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 utilizador e não contêm nenhum valor, não são lidos. Os servidores, o seu ambiente e os seus cabeçalhos mantêm a ordem em que a origem os escreve, exceto numa configuração lida como JSON com comentários, que mantém a ordem em que a sua árvore analisada os escreve: a ordem dos nomes (ver Uma configuração que contém comentários).

Um diretório é lido através das configurações de cliente que contém — cada ficheiro com o nome de uma das quatro, a qualquer profundidade — pela ordem dos seus caminhos, e cada servidor de cada ficheiro é gerado como rascunho num único Aggregate.

Em que se torna um servidor

aggregate.yaml é um Aggregate de rascunho que tem o nome da origem, como descreve Como é nomeado um rascunho, e que contém uma instância de core/ai-tool/mcp por servidor. Uma instância tem como chave o nome do 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 quando um servidor anterior ocupou a chave. Quando a chave não é o nome do servidor tal como está escrito, ou a importação leu vários ficheiros, um comentário acima da instância indica o servidor e o ficheiro de onde veio. Nenhum agente é gerado como rascunho para os utilizar.

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

  • para um servidor iniciado a partir de uma linha de comandos, infra.stdio_command, o seu comando e depois cada argumento, um item cada; e infra.stdio_runtime, o ecossistema do lançador, npm quando o comando é npx, npm ou node, pypi quando é uvx, uv, python ou python3 e, para um pacote do registo, o seu registo, npm ou pypi;
  • para um servidor alcançado num endereço, infra.endpoint: o endereço sem a sua parte de utilizador, a sua consulta e o seu fragmento, uma vez que o Component aceita o endereço sem nenhuma parte que contenha uma chave; cada parte que 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 anfitrião;
  • para o ambiente de um servidor, a ranhura server_env, anexada por referência conforme o destino da importação. Em --target helm, é um core/referenced-secret que indica um Secret do Kubernetes que já existe 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 indica 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, pelo que uma referência a variável como ${GITHUB_TOKEN} continua a ser 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 este fica entre os valores que a importação deve; um argumento que uma descrição do registo deixa ao seu utilizador é escrito como um item vazio, e uma variável cujo valor a origem não escreve, como uma entrada com valor vazio, cada um indicado no comentário acima da entrada.

Como qualquer Release gerada como rascunho, escreve metadata.environment como development, sob um comentário que diz que se trata de um valor predefinido do rascunho a alterar, e, sem destino, spec.manifest como uma cadeia vazia que a importação deve. Dado um destino, o importador gera o próprio Manifest como rascunho, uma vez que o catálogo realiza core/ai-tool/mcp através de várias Recipes e só o importador sabe como cada servidor é executado: mapeia cada servidor pela sua chave, sob mappings.components.name, para a realização do destino correspondente à forma como o servidor é executado — mcp-stdio-bridge para uma linha de comandos, 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 é anexado para a sua realização, helm/k8s-existing-secret no helm e compose/dotenv-secret-set no compose. A importação completa esse Manifest e indica-o na Release, como descreve O que um destino acrescenta.

Um .mcp.json do Claude Code que enumera um servidor alcançado por 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 anexa o ambiente como o Secret que indica, 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 da sua linha de comandos, o 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, pelo que a importação localiza cada um como membro da configuração de um servidor MCP; uma entrada do registo marcada com isSecret é localizada como um valor que o seu formato marca como credencial. Uma entrada do registo — uma variável de ambiente ou o cabeçalho de um remoto — é lida como o seu value, ou o seu default quando não escreve nenhum. Por predefinição, cada um é transportado tal como está escrito para a Release e indicado num aviso credential-carried pelo seu servidor e pelo seu lugar — headers.<header>, infra.stdio_command.<position>, infra.endpoint ou server_env.<variable>, e uma parte do endereço pelo url em que está escrita e pelo nome da parte, como em «url of node remote-search is carried with its query as written (o url do nó remote-search é transportado com a sua consulta tal como está escrita)» — nunca pelo seu valor. Com a definição empty_credentials em marked ou all, cada um é escrito vazio e comunicado com credential-emptied: um item da linha de comandos como um item vazio e um valor de ambiente como um valor vazio, cada um indicado 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 indica apenas o cabeçalho ou a parte. O infra.stdio_runtime de um cliente é lido a partir do comando tal como a Release o escreve, pelo que um comando escrito vazio também o deixa vazio, e a importação deve-o. Em --target helm, a Release não escreve nenhum valor de ambiente: é o Secret que a ranhura server_env indica que 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 é, seja o que for que diga a definição, e não é indicado em nenhum aviso, tal como uma referência num fluxo. Uma variável de ambiente cujo valor é uma delas é escrita como o valor da entrada, continuando a referência a ser uma referência, e um cabeçalho ou uma parte do endereço cujo valor é uma delas é enumerado com a referência a partir da qual lê. Uma referência que contém texto após um operador — um valor predefinido, 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 é detida por cada consumidor, na sua ligação à ferramenta, e a importação não gera nenhum consumidor como rascunho. Assim, o comentário acima da entrada do servidor enumera cada cabeçalho que a origem lhe envia, ao lado do seu valor tal como está escrito — uma cadeia entre aspas duplas que é lida de volta exatamente como o texto da origem — para que o mova para a ligação do consumidor que o apresenta. Um cabeçalho cujo valor a origem não escreve, como uma entrada de cabeçalho do registo sem valor nem valor predefinido, é enumerado como não tendo nenhum. A imagem que um pacote OCI indica é escrita tal como está, e não é um valor que a definição alcance.

infra.endpoint aceita o endereço sem nenhuma parte que contenha uma chave, pelo que as partes do endereço que a origem escreve e que ele omite — a parte de utilizador antes do @, a consulta depois do ? e o fragmento depois do #, sendo fragmento tudo o que se segue ao primeiro # — são enumeradas no mesmo comentário, cada uma ao lado do seu nome e tal como está escrita, sem o @, o ? ou o # que a separa. Um consumidor que lê a sua chave a partir do endereço fornece o endereço inteiro na sua própria ligação à ferramenta. Um servidor alcançado em https://user:pw@api.example.com/mcp?key=k, sem nenhuma definiçã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 fica para a Release e o comentário enumera user part e query, cada um com o 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: a sua assinatura para esse ficheiro lê-o através do analisador que serve parse:jsonc, pelo que uma configuração que contém comentários // e /* */ e vírgulas finais é reconhecida sem que nenhum formato seja indicado, e o importador lê cada origem que enumera os seus servidores sob servers através desse analisador. Uma configuração deste tipo é gerada como rascunho exatamente como a mesma configuração sem os seus comentários e vírgulas finais. O analisador escreve os membros de um objeto pela ordem dos nomes, pelo que os servidores de uma configuração deste tipo, o seu ambiente e os seus cabeçalhos são gerados como rascunho pela ordem dos nomes, quer contenha ou não um comentário; uma linha de comandos mantém a sua ordem. Os outros clientes e o registo leem os seus ficheiros como JSON, e o importador também: um .mcp.json, claude_desktop_config.json, .cursor/mcp.json ou server.json que contenha um comentário não é reconhecido por nenhuma assinatura e, importado indicando --format mcp, é interrompido com parse-failed e o motivo do analisador. Um comentário aberto com /* e nunca fechado é deixado tal como está escrito, e o analisador recusa o ficheiro.

As definições que lê

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

O importador Compose

importer/compose lê os serviços e os modelos que um ficheiro Compose declara. Gera como rascunho cada serviço como uma instância do Component do catálogo a que a sua imagem corresponde, ou do servidor genérico da biblioteca padrão, core/compute/server, que executa a 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, quando o seu catálogo o contém, e como um Component de modelo próprio quando não o contém; e, ao lado deles, uma Release que transporta o que cada serviço declara para o seu funcionamento.

O que lê

  • Os ficheiros. Um ficheiro importado isoladamente é lido sozinho. Um diretório é lido tal como o Compose lê um: em cada diretório que contém ficheiros Compose, pela ordem dos caminhos dos diretórios, o primeiro presente de entre compose.yaml, compose.yml, docker-compose.yml e docker-compose.yaml é o ficheiro Compose, e o primeiro presente de entre compose.override.yml, compose.override.yaml, docker-compose.override.yml e docker-compose.override.yaml é fundido por cima dele. Nenhum outro desses ficheiros é lido. Num diretório que contém ficheiros de substituição e nenhum ficheiro Compose, o seu primeiro ficheiro de substituição é lido sozinho. Um comentário no início do Aggregate de rascunho indica os ficheiros lidos, pela ordem em que são fundidos, e os ficheiros não lidos. Cada serviço e cada modelo de cada diretório é gerado como rascunho num único Aggregate.
  • A fusão. Um ficheiro de substituição é fundido tal como o Compose funde um: image é substituído; as ports são fundidas pelo seu endereço, pela porta publicada, pela porta do contentor e pelo protocolo, os volumes pelo seu caminho no contentor, e environment pelo nome da variável, ocupando uma entrada posterior o lugar de uma anterior e vindo uma nova a seguir; expose é acrescentado no fim; depends_on e os models de um serviço são unidos, ocupando endpoint_var e model_var de uma entrada, cada um, o lugar daquele que um ficheiro anterior declara. De um modelo, model e context_size são substituídos e runtime_flags é acrescentado no fim. As tags !reset e !override do Compose não são respeitadas: um valor que contenha uma delas é fundido tal como o analisador YAML o lê.
  • Um serviço. A sua image, e se constrói uma sob build; as suas ports, expose, volumes e environment — um mapeamento, ou uma lista de itens NAME=value, em que um nome sem valor recebe o seu valor do ambiente em que o Compose é executado; depends_on, uma lista ou um mapeamento; e os seus models, uma lista de nomes de modelos ou um mapeamento cujas entradas podem indicar, sob endpoint_var e model_var, as variáveis através das 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 lado nenhum, e é indicado num comentário acima da entrada do serviço na Release.
  • Um modelo. Cada entrada dos models de nível superior: o seu model, o identificador OCI do modelo, o seu context_size e os seus runtime_flags, transportados tal como estão escritos para uma instância de core/ai-model/docker-model-runner quando o seu catálogo o contém, e de um Component de modelo gerado como rascunho para ele quando não o contém; a decisão do modelo diz qual, e porquê. Qualquer outro membro é indicado num comentário acima da 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 indica-os.

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

Que Component é um serviço

O importador faz corresponder um serviço pelo repositório que a sua imagem indica: a referência sem a sua tag e o seu digest, sendo uma referência do Docker Hub escrita na sua forma curta — postgres para docker.io/library/postgres:16. Faz corresponder o repositório através da 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, pelo que nenhuma Recipe é lida quando uma importação é executada e a tabela contém as etiquetas do catálogo padrão, seja o que for que o seu catálogo contenha; a entidade Plugin do importador indica, na 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 do seu contentor chamado main, quando essa imagem escreve o seu repositório no seu próprio texto, ou é uma entrada de locals que o faz. Uma Recipe que executa a imagem que a Release indica por inteiro, ou uma que o seu template compõe de outra forma, não acrescenta nenhuma linha, e uma imagem que uma Recipe executa ao lado do seu contentor principal também não. Duas Recipes que indicam um mesmo repositório para Components diferentes impedem que a tabela seja gerada, pelo que uma linha nunca indica um de dois. Do Component que uma linha indica, a tabela lê as suas etiquetas tal como são entregues a uma importação — na versão para a qual se resolve uma referência que indica o Component sem versão, com as que herda através de extends — e escreve cada etiqueta exceto component.aggrega.ai/category na linha como os 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 tal como é lida a linha da tabela de um importador de fluxos: o Component, a categoria em que o seu nome o coloca, os seus traços e o último segmento do seu nome como o seu fabricante. A definição mapping_overrides sobrepõe-se à tabela sob o formato compose, tendo o repositório como chave, e uma entrada para um repositório que a tabela mapeia ocupa o lugar da linha. Assim, uma imagem que as Recipes do catálogo padrão não indicam — a sua própria, 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 tal como os importadores de fluxos decidem um nó: pontuado face aos Components do seu catálogo, referenciado quando reuse_mode é auto-apply-above-threshold, o valor predefinido, e o 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, começando o ficheiro do Component gerado como rascunho com um comentário que indica o Component com que se parece. Uma linha contém as etiquetas do Component que indica, pelo que, quando o seu catálogo contém esse Component com as etiquetas 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 faz-lhe referência com o reuse_threshold predefinido. Um Component cujas etiquetas o seu catálogo alterou obtém uma pontuação inferior, na proporção da parte dos traços da linha que já não contém, e só é referenciado enquanto se mantiver no nível alto; a categoria é pontuada uma única vez, no seu próprio sinal, e não novamente como traço. Os serviços que geram como rascunho um mesmo Component partilham o seu único ficheiro. Um serviço cuja imagem nenhuma linha mapeia, cuja imagem não indica nenhum repositório que o importador leia, ou que constrói a sua imagem, é uma instância de core/compute/server, seja o que for que o seu catálogo contenha. A decisão de cada serviço é comunicada tal como a de cada nó.

Em que se torna um serviço

aggregate.yaml é um Aggregate de rascunho que tem o nome do projeto, como descreve Como é nomeado um rascunho, e que contém uma instância por serviço, do Component que a sua decisão escolheu, com a chave atribuída tal como o importador MCP atribui a chave a um servidor, e um comentário acima dela que indica o serviço e o ficheiro de onde veio quando 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 indica é uma ligaçã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 das suas ligações pelo respetivo alias, seja qual for o socket a que esteja ligada, pelo que cada ligação de um serviço tem um alias próprio. Uma variável do ambiente de um serviço também pode dar origem a uma ligação, que entrega a variável a partir do que o serviço que alcança publica, como descreve Em que se tornam o ambiente e a imagem de um serviço. Cada modelo é uma instância de core/ai-model/docker-model-runner quando o catálogo do espaço de trabalho o contém, seja o que for que reuse_mode diga, e nenhum Component é gerado como rascunho para ele: a instância escreve model e runtime_flags tal 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 a sua Recipe do Compose volta a escrever como o context_size do Compose. Quando 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 a sua instância escreve cada um dos que a origem declara. Cada 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 regista 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 indica o modelo é ligado a ele em ambos os casos, tal como a um serviço de que depende. Um serviço que indica o modelo na forma longa, com endpoint_var ou model_var, indica as variáveis através das quais o seu endereço e o seu identificador chegam ao serviço. Nenhuma chave do rascunho contém o nome de uma variável — a ligação é escrita num socket com o nome do modelo, que não declara nenhum valor, e a um importador não é entregue nenhuma chave de infraestrutura de um Component — pelo que um comentário acima da ligação indica cada uma, tal como a entrada a escreve, e a decisão do serviço regista 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 indica o modelo na forma curta, ou sem nenhuma das duas variáveis, é ligado a ele sem comentário.

Ao lado dele, release.yaml é uma Release de rascunho com o mesmo nome, cujo spec.aggregate indica o Aggregate. Para uma instância de core/compute/server, escreve infra.image, a imagem tal como está escrita, e infra.port, a porta em que o contentor escuta na primeira entrada de ports, ou de expose quando ports não contém nenhuma. Com --target compose, escreve também infra.published_port, a porta do anfitrião que essa mesma entrada de ports publica, tal como a origem a declara, sob o comentário que diz que só é acessível a partir desta máquina, por qualquer processo que nela se execute, e que eliminar a linha mantém o serviço interno; uma porta do anfitrião abaixo de 1024, que published_port não aceita, não é escrita, e um comentário acima da entrada indica-a. Um comentário acima da entrada de cada serviço escreve o que a origem declara e que nenhuma chave do rascunho transporta — a imagem de um serviço a que corresponde outro Component cuja etiqueta o rascunho não traduz, as suas ports, expose, volumes, e cada variável do seu environment que o rascunho não traduz — para que o transporte para onde o Component o aceite. O que o rascunho deixa para a Release — a imagem de um serviço que não indica 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 porquê. Uma compilação coloca apenas as instâncias que uma Release indica, pelo que 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 predefinido, como um modelo gerado como rascunho como um Component próprio, pelo que o modelo gerado como rascunho já está colocado e compila assim que se 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 tal como a origem a declara, e a compilação é interrompida indicando-a. A Release escreve metadata.environment e, sem destino, um spec.manifest vazio, tal como a do importador MCP; dado um destino, a importação gera como rascunho o Manifest, como descreve O que um destino acrescenta, fazendo corresponder cada Component à Recipe que o realiza nesse destino — core/compute/server a compose/server ou helm/server, e core/ai-model/docker-model-runner a 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 definição, sobre um catálogo que contém o core/datastore/postgres da biblioteca padrão, importado isoladamente e com o nome do ficheiro, uma vez que o projeto não tem 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 comunica mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9. O projeto não contém nenhum serviço cache, pelo que CACHE_URL não dá origem a nenhuma ligaçã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; a sua imagem e o seu ambiente são então escritos no comentário acima da sua entrada, uma vez que um Component gerado como rascunho não declara nenhum dos valores que as Recipes do catálogo leem. Com --target compose, o Manifest faz corresponder core/datastore/postgres a compose/postgres e core/compute/server a compose/server; com --target helm, a helm/postgres e helm/server.

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

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

  • A etiqueta 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 indica 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, quando o Component do catálogo o declara, escrito no Aggregate sob um comentário que indica as variáveis.
  • Uma variável a partir da qual a Recipe lê uma palavra-passe, 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 indica e declarado com a chave sob a qual a Recipe o lê.

E, para cada serviço, cada variável do seu ambiente que não é lida desta forma:

  • Um valor que é o nome de outro serviço do projeto, quando a linha desse serviço indica a chave provides que publica o seu nome de anfitrião, dá origem a uma ligação a esse serviço, cujo bloco inject entrega a variável a partir dessa chave — CACHE_HOST: cache é CACHE_HOST a partir do host da cache.
  • Um valor igual a um valor que outro serviço define para o seu Component e que o Component publica — DATABASE_USER: notes ao lado de um serviço PostgreSQL que define POSTGRES_USER: notes — dá origem a uma ligação que entrega a variável a partir dessa chave provides. Quando 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 deste, aquele a partir 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 indica uma variável a partir da qual é lido o segredo de outro serviço — DATABASE_PASSWORD: ${POSTGRES_PASSWORD} — é, numa 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, quando o destino escreve o segredo como um valor que o servidor aceita. helm/server recusa um core/referenced-secret, pelo que com --target helm essa variável permanece no comentário.

Qualquer outra variável é deixada no comentário acima da entrada do serviço, tal como a origem a escreve. O guia passo a passo da importação do Compose mostra um projeto cuja API alcança a sua base de dados e a sua cache desta forma, compilado e executado tal 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 significa, pelo que cada valor de ambiente que contém algo é localizado como uma entrada que o seu formato marca como não credencial, mas que pode conter uma. Por predefinição, cada um é transportado tal como está escrito para os rascunhos — para o valor em que é traduzido, ou para o comentário acima da entrada do seu serviço na Release — e indicado num aviso credential-carried pelo seu serviço e pela sua variável — environment.<variable> — nunca pelo seu valor. Com a definição empty_credentials em all, cada um é escrito vazio e comunicado com credential-emptied: o comentário indica a sua variável sem valor. Em marked, nenhum é escrito vazio, uma vez 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 é indicado em nenhum aviso. Uma referência que contém um valor predefinido ou uma mensagem, como ${NAME:-value}, contém esse texto, e é localizada como qualquer outro valor. Um valor que o Compose lê de outro lado — um env_file, o ficheiro de um segredo — não é lido.

As definições que lê

O importador Compose lê target_namespace, reuse_mode, reuse_threshold, emit_hints, render_mode, mapping_overrides e empty_credentials, tal como Definições os descreve, e nenhuma outra definição. A sugestão que emit_hints controla é escrita apenas no ficheiro do Component gerado como rascunho; o Aggregate de rascunho não contém nenhuma.

O importador Dify

importer/dify lê uma aplicação exportada do Dify na 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 transportada no parâmetro app_definition da instalação. A instalação importa-a na implementação, através do passo que a Recipe do seu servidor de API renderiza para ela.

O que lê

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

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

Em que se torna uma aplicação

aggregate.yaml é um Aggregate de rascunho que tem o nome da aplicação, como descreve Como é nomeado um rascunho, e que compõe uma entrada de core/dify, com a chave dify, cujo parâmetro app_definition transporta a aplicação tal como está escrita — como descreve Como o fluxo é escrito no rascunho para um fluxo, pelo que as referências {{#…#}} próprias do Dify chegam à instalação tal como foram exportadas. A instalação estabelece ela própria cada ligação do seu servidor de API — a sua base de dados, a sua cache, o seu armazenamento vetorial, a sua sandbox, o seu ambiente de execução de plugins e o seu proxy de saída — pelo que o rascunho não gera nenhum Component como rascunho e não liga nada: cada nó permanece na aplicação, e a sua decisão di-lo. Ao lado dele, release.yaml é uma Release de rascunho com o mesmo nome, que coloca a instalação numa fronteira, platform, e transporta aquilo que a aplicação não consegue fornecer.

Uma importação vê os Components do catálogo do workspace e nenhum dos seus Aggregates, pelo que não verifica se o catálogo contém core/dify, e um comentário acima da entrada di-lo. Quando 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 na mesma.

O segredo de aplicação da instalação, a chave com que o Dify assina os seus cookies de sessão e sob a qual cifra as credenciais dos fornecedores de modelos que armazena, é o parâmetro secret_key de core/dify, que não tem valor predefinido. Por isso, o rascunho declara um parâmetro secret_key próprio — uma cadeia de caracteres, obrigatória, com pelo menos um carácter e sem valor predefinido — e passa-o a cada entrada de core/dify que escreve, para que a Release o preencha nos seus parameters; uma compilação cuja Release o deixe por definir é interrompida, indicando-o.

A aplicação é importada com a conta do proprietário da instalação, que a Release indica na sua entrada de encaminhamento 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 a compilação é interrompida. O e-mail do proprietário não é algo que alguma origem possa fornecer, pelo que é escrito vazio sob um comentário que diz o que é, e a importação indica-o como pendente.

Em todos os destinos, a mesma entrada de encaminhamento define infra.marketplace_enabled como true nos componentes api, worker e scheduler da instalação, cada um sob um comentário que explica porquê: 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ê a sua própria definição, e o Dify instala o plugin que serve o modelo de uma aplicação, como o da OpenAI, a partir do seu marketplace de plugins.

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

  • Com --target helm, cada um indica um Secret do Kubernetes já existente 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 palavra-passe sob a chave de dados value. Nenhum dos nomes é algo que uma origem possa fornecer, pelo que cada um é escrito vazio sob um comentário que diz o que é, e a importação indica ambos como pendentes; o Manifest gerado como rascunho faz corresponder core/referenced-secret a 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 palavra-passe 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 arranca, pelo que nada fica pendente para nenhum dos dois; com --target compose, o Manifest gerado como rascunho faz corresponder core/referenced-secret a compose/dotenv-referenced-secret.

Dado um destino, o Manifest faz corresponder o tipo de cada componente que a instalação compõe, bem como o do próprio rascunho, como descreve O que um destino acrescenta.

A aplicação workflow escrita à mão que os testes deste importador importam, chamada Support Answers, é gerada como rascunho, sem nenhuma definiçã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, a sua Release gerada como rascunho preenche secret_key, e indica o proprietário e ativa o marketplace de plugins na entrada de encaminhamento que coloca 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; escreve também infra.published_port no componente api, 5001, e no front-end, o componente console, 3001, cada um sob o comentário que diz que só é acessível a partir desta máquina, por qualquer processo em execução nela, e que eliminar a linha mantém o serviço interno, e, por baixo da porta do componente api, infra.console_url com o endereço em que a consola é publicada, "http://127.0.0.1:3001", que o servidor do Dify toma como endereço da consola. O guia passo a passo da importação do Dify compila uma aplicação para ambos os destinos e executa-a no Kubernetes.

O que o Dify configura por si próprio

O Dify configura dentro de si próprio os fornecedores dos modelos e das ferramentas que uma aplicação chama, e core/ai-agent/dify não declara nenhum socket para um modelo, pelo que o rascunho não liga nenhum. Cada nó que indica um deles é comunicado com part-configured-in-platform, e na sua decisão, consoante o que indica:

  • um nó llm, question-classifier ou parameter-extractor, e o model_config.model de uma aplicação chat: o modelo, pelo seu nome e pelo seu fornecedor;
  • um nó tool, e a ferramenta de uma aplicação chat: a ferramenta, pelo seu nome e pelo seu fornecedor;
  • 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 a partir das quais recupera, e o modelo com que encaminha uma consulta ou com que reordena, quando indica um. Uma aplicação indica uma base de conhecimento por um identificador da instalação a partir da qual foi exportada, e não transporta nenhum dos seus documentos nem nenhum armazenamento, pelo que cada uma é criada dentro do Dify, no armazenamento vetorial que a instalação liga 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 comunicado.

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

O importador localiza, pela 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 escreve-o vazio, a menos que a exportação inclua os segredos;
  • o authorization.config.api_key de um nó de pedido HTTP, que o Dify marca como credencial e exporta tal 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 quando a exportação inclui os segredos;
  • os headers e params de um nó de pedido HTTP, que o Dify não marca como credencial e que podem conter uma, cada um por inteiro.

Por predefinição, cada um que contém um valor é transportado tal como está escrito na aplicação e indicado num aviso credential-carried pelo seu nó — workflow para uma variável de ambiente — e pelo seu campo, nunca pelo seu valor. Com a definiçã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 comunicado com credential-emptied. Um valor que é uma referência a uma variável e nada mais não contém nenhum, e é transportado tal como está escrito, seja o que for que diga a definição, e não é indicado em nenhum aviso, tal como num fluxo. Um valor é escrito vazio no próprio texto da aplicação: o escalar que se segue à sua chave é substituído por '', e nada mais é alterado. A aplicação só é transportada quando o analisador que serve parse:yaml lê de volta o resultado como a aplicação exportada com exatamente esses valores esvaziados; caso contrário, não é transportada, app_definition fica por definir com um comentário, e definition-not-carried diz porquê — como numa 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 definição deixa tal como está escrito nunca é reescrito, pelo que nunca impede que a aplicação seja transportada.

A versão da DSL

Quando uma aplicação está escrita numa versão da DSL mais recente do que 0.7.0, a versão que o Dify 1.17.0 — a versão que core/ai-agent/dify executa por predefinição — escreve, a importação avisa com dsl-version-newer. O Dify retém a importação de uma aplicação deste tipo a aguardar confirmação, que o passo que a importa na implementação dá, pelo que convém verificar a aplicação face à versão do Dify que a Release executa.

As definições que lê

O importador Dify lê target_namespace, empty_credentials, layout, attach_egress_allowlist e render_mode, tal como Definições os descreve, e reuse_mode, reuse_threshold, emit_hints e mapping_overrides, que não alteram nada do que a disposição predefinida gera como rascunho: cada nó permanece na aplicação. attach_egress_allowlist não anexa nada, uma vez 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 descreve Nó a nó, e não transporta nenhuma aplicação.

O importador CrewAI

importer/crewai lê os agentes e as tarefas que um projeto CrewAI declara nos seus ficheiros 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 ligada ao modelo que a sua configuração indica, e uma Release ao lado dele.

O que lê

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

  • Um projeto clássico — config/agents.yaml, com cada agente a ter o seu nome como chave, e config/tasks.yaml, com cada tarefa a ter o seu nome como chave, ambos lidos como YAML. Os agentes são lidos pela ordem em que agents.yaml os escreve.
  • Um projeto na estrutura JSON-first — crew.jsonc, que enumera os agentes da crew por nome sob agents e as suas tarefas sob tasks, e agents/<name>.jsonc, um ficheiro por agente, todos lidos como JSON com comentários, pelo que os seus comentários e vírgulas finais são lidos tal como o CrewAI os lê. Os agentes são lidos pela ordem em que crew.jsonc os enumera, seguidos do ficheiro de qualquer outro agente pela ordem dos nomes; um agente que a crew enumera cujo ficheiro não foi entregue à importação é indicado num 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. Quando uma crew ou um agente está escrito nas duas grafias, o ficheiro .jsonc é o que é lido, tal como o CrewAI o lê, e o ficheiro .json é indicado num comentário como não lido.

De um agente lê o seu role, goal e backstory; allow_delegation e verbose, no nível superior da sua declaração ou sob settings, prevalecendo settings, tal como o CrewAI os lê; o seu llm; e os nomes das suas tools. De uma tarefa lê o seu nome e o agente a que está atribuída. Qualquer outro membro é indicado num comentário e não é transportado para lado nenhum.

Um diretório é entregue ao importador como os ficheiros que as suas assinaturas indicam e nenhum outro, pelo que 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 ficheiro importado por si só é lido como a declaração cuja forma tem. O diretório de um projeto pode conter várias crews, cada uma lida a partir do seu próprio diretório.

Em que se torna um projeto

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

  • role, goal e backstory tal como declarados;
  • allow_delegation tal como declarado, e false quando o agente não declara nenhum;
  • log_level DEBUG para um agente declarado verbose, que narra cada passo do seu raciocínio, e INFO para um que não o é, que comunica apenas o progresso e os problemas. Um verbose ou um allow_delegation que não é nem true nem false fica com o valor predefinido do Component e é indicado num comentário;
  • a sua ligação model, ligada à instância do modelo que o seu llm indica.

Um llm escrito <provider>/<model>, ou como um objeto que indica o modelo sob model, model_name ou deployment_name, indica um fornecedor e um modelo. O modelo é uma instância do Component do catálogo para esse fornecedor — core/ai-model/<provider>, com um sublinhado no nome do fornecedor lido como hífen, e azure lido como azure-openai — com o nome do modelo como chave e o modelo como o seu values.model; os agentes que indicam um mesmo fornecedor e modelo partilham uma instância. Quando o catálogo do workspace não contém nenhum Component com esse nome, é gerado um como rascunho, <target_namespace>/ai-model/<provider>, que declara o valor model, e a sua decisão di-lo; a etiqueta model.aggrega.ai/api pela qual o socket model do agente seleciona um Component, e uma Recipe que publique o seu endpoint e o seu modelo, ficam a cargo do utilizador, como diz um comentário no início dele. Um llm que não indica nenhum fornecedor — um nome de modelo simples, para o qual o CrewAI resolve um fornecedor 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 o seu programa é executado, não são ligados a nada, e um comentário acima do agente diz porquê; a compilação é interrompida indicando o socket model até que um seja ligado.

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 é comunicada numa decisão que não escolhe nada, e uma ferramenta cujo nome — sem um Tool final, sem os seus hífenes e sublinhados — é o nome de um Component de ferramenta que o catálogo contém transporta esse Component como sugestão: search_tool e SearchTool sugerem ambos core/ai-tool/search. core/ai-agent/crewai não declara nenhum socket para uma ferramenta, pelo que nada é ligado para ela.

release.yaml, ao lado dele, é uma Release de rascunho com o mesmo nome que indica esse Aggregate. Escreve vazio o infra.image de cada agente — a imagem que executa o programa da crew, que nenhuma declaração indica — sob um comentário que diz o que é, e a importação indica-o como pendente. Com --target compose, a entrada de cada agente escreve também infra.published_port, 8000, a porta que o infra.port do Component indica por predefinição para o programa, que a sua Recipe do Compose publica no endereço de loopback do anfitrião, 127.0.0.1, sob o comentário que diz que só é acessível a partir desta máquina, por qualquer processo em execução nela, e que eliminar a linha mantém o serviço interno; um segundo agente fica com a porta livre seguinte, pelo que os dois agentes do projeto clássico são publicados em 8000 e 8001. Anexa a credencial que cada agente apresenta ao seu modelo sob credential na sua ligação model, por referência e nunca como valor: nenhuma declaração indica uma variável para ela, pelo que é lida da variável a partir da qual as bibliotecas cliente do fornecedor leem a 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 ligação model do agente declara-a com essa chave. Cada modelo também tem uma entrada, que não contém nenhuma infraestrutura, pelo que a Release o coloca juntamente 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 quando o Component do catálogo declara um valor com esse nome, e caso contrário num comentário acima da entrada do modelo na Release, para ser transportado para onde o Component o aceita. Como qualquer Release gerada como rascunho, 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 acrescenta.

O projeto clássico que os testes deste importador importam, cujos dois agentes indicam ambos openai/gpt-4o, é gerado como rascunho, sem nenhuma definição, como se mostra abaixo; importado como o seu diretório de projeto, market_brief — o diretório em que crewai create crew market_brief organiza um projeto deste tipo —, e uma vez que as suas declarações não indicam nenhuma crew, 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 a 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 a executar a imagem indicada na resposta, recebendo o endpoint do modelo e o nome do modelo como OPENAI_BASE_URL e MODEL, as variáveis a partir 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, num endereço, em cabeçalhos. Cada um dos seus membros, além daquele que indica o modelo, que não seja um número nem um booleano é um valor que pode conter uma, que o CrewAI não marca como credencial. Por predefinição, cada um que contém um valor é transportado tal como está escrito — como um valor da instância do modelo quando o seu Component declara um, e caso contrário para o comentário acima da entrada do seu modelo na Release — e indicado num aviso credential-carried pelo seu agente e pelo seu membro, como llm.api_key, nunca pelo seu valor. Com a definição empty_credentials em all, cada um é escrito sem valor e comunicado com credential-emptied; em marked cada um é transportado, uma vez 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 transporta — a configuração de uma ferramenta, os inputs de uma crew — é indicado, nunca com o seu valor.

As definições que lê

O importador CrewAI lê target_namespace, empty_credentials e render_mode, tal como Definições os descreve, e nenhuma outra definiçã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 ligada ao armazenamento de dados em que o seu checkpointer guarda o estado e a um modelo, e uma Release ao lado dele que transporta o ambiente que a configuração estabelece. Lê essa configuração, e nunca o código dos grafos.

O que lê

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

  • graphs — o id de cada grafo, o seu caminho de importação e a sua descrição;
  • checkpointer — o seu backend: default, que é PostgreSQL e o que o LangGraph lê quando nenhum é indicado; mongo, uma base 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 indica nenhum backend: o LangGraph guarda-o na base de dados PostgreSQL que o seu servidor utiliza;
  • env — o ambiente com que a aplicação é executada: um objeto de nomes de variáveis para valores, ou o caminho de um ficheiro de ambiente de linhas KEY=VALUE.

Os membros que configuram a imagem de servidor que langgraph build compila — dependencies, source, python_version, node_version, base_image, image_distro, dockerfile_lines, pip_config_file, pip_installer, keep_pkg_tools, api_version — são indicados num comentário e não são transportados para lado nenhum, uma vez que a imagem que a Release indica é a da própria aplicação; o mesmo acontece com qualquer outro membro, entre eles a configuração própria do servidor, como auth, http e webhooks, e com 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 ficheiro, pelo que nem o código da aplicação nem um ficheiro de ambiente são alguma vez lidos a partir dele. Um ficheiro de ambiente só chega ao importador quando o with.sources do importador o entrega, e nunca é analisado: daquele que o env da configuração indica — correspondido pelo último segmento do caminho que indica — só os nomes das variáveis são lidos, e um ficheiro de ambiente que nenhuma configuração indica é indicado num comentário como não lido. Quando a importação não recebe o ficheiro que a configuração indica, o Aggregate indica-o como não entregue e diz para o indicar sob o with.sources do importador, e as suas variáveis ficam para a Release:

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

Uma configuração importada por si só é lida seja qual for o seu nome. Um diretório pode conter várias aplicações, cada uma lida a partir do seu próprio diretório.

Em que se torna uma aplicação

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

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

recursion_limit não é escrito, pelo que o valor predefinido do Component, 25, se mantém. A configuração não indica nenhum modelo, pelo que 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. O seu values.model é escrito vazio, sob um comentário que diz que a configuração não indica nenhum, e a importação indica-o como pendente.

O backend do checkpointer é o armazenamento de dados ao qual cada grafo da aplicação é ligado: default, ou um checkpointer que não indica 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 é ligado, e uma de core/datastore/documentdb, com a chave documentdb, que a ligação backend do FerretDB alcança, com o seu bloco inject a entregar o que o DocumentDB publica sob os nomes que o FerretDB lê; uma única palavra-passe, lida da variável FERRETDB_PASSWORD, é anexada ao DocumentDB, à ligação do FerretDB a este e à ligação de cada grafo ao FerretDB. Quando o catálogo do workspace não contém nenhum Component com o nome do armazenamento de dados PostgreSQL, é gerado um como rascunho, <target_namespace>/datastore/postgres, que declara o host e a port que a ligação checkpointer_db do agente lê, e a sua decisão di-lo; uma Recipe que execute o armazenamento de dados e os publique fica a cargo do utilizador, como diz um comentário no início dele. Quando não contém nenhum Component do FerretDB ou nenhum do DocumentDB, o checkpointer mongo não é ligado a nenhum armazenamento de dados. Um checkpointer custom, ou um backend que o importador não faz corresponder a nenhum armazenamento de dados, não liga nada, e um comentário acima de cada grafo e a decisão do checkpointer dizem porquê; a compilação é interrompida indicando o socket checkpointer_db até que um seja ligado. O armazenamento de memória é comunicado numa decisão que não escolhe nada.

A palavra-passe do armazenamento de dados é um segredo que o rascunho anexa por referência, na ranhura password do próprio armazenamento de dados e na ligação checkpointer_db de cada grafo, e o mesmo se aplica à credencial que cada grafo apresenta ao modelo na sua ligação model: lidas de POSTGRES_PASSWORD (ou FERRETDB_PASSWORD) e de OPENAI_API_KEY, uma vez que a configuração não indica nenhuma variável para nenhuma delas, 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 a sua Recipe lê, como descreve Segredos, para cada destino para uma plataforma.

release.yaml, ao lado dele, é uma Release de rascunho com o mesmo nome que indica esse Aggregate. Comentários acima da entrada do primeiro grafo dizem qual é a imagem de cada grafo — a da própria aplicação, o seu código com o LangGraph instalado, e não a imagem de servidor que langgraph build compila —, as variáveis que lhe são passadas e que bloco inject: substitui qual dos seus nomes. A entrada de cada grafo escreve vazio o seu infra.image, a imagem que executa a aplicação, sob um comentário que diz o que é, e a importação indica-o como pendente; enquanto não estiver definido, a Recipe do Docker Compose executa o agente quickstart do próprio catálogo, que lê as variáveis predefinidas. Com --target compose, a entrada de cada grafo escreve também infra.published_port, 8000, a porta que o infra.port do Component indica por predefinição para a aplicação, que a sua Recipe do Compose publica no endereço de loopback do anfitrião, 127.0.0.1, sob o comentário que diz que só é acessível a partir desta máquina, por qualquer processo em execução nela, e que eliminar a linha mantém o serviço interno; um segundo grafo fica com a porta livre seguinte. O armazenamento de dados e o modelo também têm entradas, pelo que a Release os coloca junto dos grafos. Um comentário acima do primeiro grafo da aplicação apresenta o ambiente que a sua configuração declara, como descreve O ambiente que uma configuração estabelece. Como qualquer Release gerada como rascunho, 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 acrescenta.

A aplicação Python que os testes deste importador importam, que declara dois grafos, um checkpointer que não indica nenhum backend, um armazenamento de memória e um env escrito como um objeto, é gerada como rascunho, sem nenhuma definição, como se mostra abaixo; importada como o seu diretório, support_desk — com o nome, como aqui, do pacote em que os seus grafos são definidos —, com dois grafos cujos ids diferem, 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 de respondidos, cada grafo é renderizado a executar a imagem indicada na resposta, recebendo o endereço do seu armazenamento de dados como LANGGRAPH_CHECKPOINTER_HOST e LANGGRAPH_CHECKPOINTER_PORT, o utilizador e a base 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 publique 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 a sua credencial do modelo entrega como OPENAI_API_KEY, o seu caminho de importação como LANGGRAPH_GRAPH_ENTRYPOINT e o seu limite de passos como LANGGRAPH_DEFAULT_RECURSION_LIMIT. A credencial anexada à sua ligação checkpointer_db também lhe fornece a palavra-passe do armazenamento de dados como LANGGRAPH_CHECKPOINTER_PASSWORD.

O ambiente que uma configuração estabelece

Cada variável que o env da configuração indica é 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, pelo que a Release o apresenta num comentário acima do primeiro grafo da aplicação.

  • Um env escrito como um objeto faz parte da configuração, pelo que os seus valores são transportados tal como estão escritos para esse comentário, pela 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 predefinição, cada um é transportado tal como está escrito e indicado num aviso credential-carried pela sua configuração e pela sua variável, como env.OPENAI_API_KEY, nunca pelo seu valor. Com a definição empty_credentials em all, cada um é escrito sem valor e comunicado com credential-emptied; em marked cada um é transportado, uma vez que o LangGraph não marca nenhum.
  • Um env que indica um ficheiro indica um ficheiro para o qual a configuração apenas aponta, que habitualmente contém segredos locais. Só é lido quando o with.sources do importador o entrega. O comentário indica cada variável que o ficheiro indica, deixada para a Release fornecer, e nenhum valor do ficheiro é lido: nenhum chega a um rascunho, a uma decisão ou a um diagnóstico, seja o que for que diga a definição. Um valor entre aspas ao longo de várias linhas é um único valor, pelo que uma linha dentro dele nunca é tomada por uma variável, e uma linha que não indica nenhuma variável é indicada pelo seu número. Quando a importação não recebeu o ficheiro — sempre assim para um diretório, que nunca entrega nenhum — o Aggregate indica-o como não entregue, com a forma de o entregar, e as suas variáveis ficam para a Release.

As definições que lê

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

O importador Google ADK

importer/google-adk lê os agentes que uma aplicação construída sobre o Agent Development Kit (ADK) da Google declara nos seus ficheiros Agent Config — root_agent.yaml e as configurações que os seus subagentes indicam — 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, ligada ao modelo que a árvore indica quando o ADK envia os pedidos desse modelo para a Gemini API, e uma Release ao lado dele. Lê essas configurações, e nunca o código da aplicação.

O ADK declara que a sua funcionalidade Agent Config é experimental. O modelo de um agente é, por predefinição, um modelo Gemini; o ADK serve pelo nome os modelos de alguns outros fornecedores através de classes próprias, como claude-sonnet-4-5 e gpt-4o, e outros através de uma cadeia de modelo do LiteLLM. O socket model do agente admite apenas a Gemini API, pelo que o importador liga um modelo que o ADK envia para a Gemini API e deixa qualquer outro ao cuidado do utilizador, como descreve O que se torna uma árvore de agentes.

O que lê

O adk create --type=config do ADK escreve root_agent.yaml, a configuração do agente raiz de uma aplicação, e um ficheiro 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 quando não indica nenhuma;
  • model — o modelo que o agente pede — ou model_code, uma referência a código que constrói o seu modelo;
  • tools — cada ferramenta por name, com os args que a sua configuração lhe entrega;
  • generate_content_config — as opções dos pedidos 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 indica, ou code, um agente que o código da aplicação constrói.

Um diretório é entregue ao importador como os seus ficheiros root_agent.yaml e nenhum outro ficheiro, e uma configuração importada por si só é lida como uma raiz, seja qual for o seu nome. A árvore de cada raiz é lida a começar pela raiz, os subagentes de cada agente pela ordem em que este os enumera. A configuração que uma entrada de sub_agents indica por config_path só é lida quando o with.sources do importador a entrega, correspondida pelo último segmento do caminho; uma que não foi entregue à importação é indicada no Aggregate e na sua decisão como não entregue, com a forma de a entregar, e o 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 conduz para fora do diretório da configuração que o indica, não é lido, uma vez que o ADK também o recusa. Um ficheiro que with.sources entrega e que nenhuma configuração indica é indicado num comentário como não lido, e nada dele é lido; um ficheiro que entrega só é lido como uma configuração que a árvore de uma raiz indica, pelo que uma importação que não contém nenhum root_agent.yaml nem nenhum ficheiro importado por si só não lê nenhuma árvore e comunica cada ficheiro sob no-nodes. O código da aplicação — as ferramentas, callbacks, esquemas e agentes que uma configuração indica pelo seu código — e o ficheiro de ambiente nunca são entregues, e o importador não lê nenhum dos dois: a aplicação carrega ela própria as suas configurações, a partir da imagem que a Release indica. Um diretório pode conter várias aplicações, cada uma lida a partir do 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 da sua própria configuração, pelo que o rascunho não transporta nenhum deles.

Em que se torna uma árvore de agentes

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

  • description, a descrição do agente raiz, quando a sua configuração fornece uma;
  • a sua ligação model, ligada ao modelo que a árvore indica, quando o ADK envia os pedidos desse modelo para a Gemini API.

Comentários acima dela indicam os outros agentes da árvore, que não se tornam nenhuma instância própria; cada subagente que não é lido, e porquê — 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 indicam, 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, quando o modelo da árvore está ligado, os modelos que outros agentes da árvore pedem, cada um com a família através da qual o ADK o serve. Cada um é comunicado numa decisão que não escolhe nada.

O primeiro agente da árvore, a começar pela raiz, que indica um modelo ou o código que constrói um decide o modelo da instância. Um modelo que indica e cujos pedidos o ADK envia para a Gemini API — um nome de modelo que o ADK serve através da sua classe Gemini, como gemini-2.5-flash, exceto um nome de recurso da Vertex AI, ou um que serve através da sua classe Gemma — é uma instância de core/ai-model/gemini, que serve esse modelo e o tem como chave, e as árvores que indicam um mesmo modelo partilham uma instância. Quando o catálogo do workspace não contém nenhum core/ai-model/gemini, é gerado um como rascunho, <target_namespace>/ai-model/gemini, que transporta a etiqueta model.aggrega.ai/api: gemini que o socket model do agente seleciona, e a sua decisão di-lo; uma Recipe que publique o seu endpoint e o seu modelo fica a cargo do utilizador, como diz um comentário no início dele. Um modelo que o ADK serve de qualquer outra forma — uma cadeia 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 através da Anthropic ou da OpenAI — não é ligado a nada: o socket model do agente aceita um modelo Gemini, e o agente não lê nenhum nome de modelo do seu ambiente, pelo que cabe ao utilizador ligar aí um modelo Gemini e indicar esse modelo na configuração do agente. O comentário acima da instância e a decisão do agente raiz indicam o modelo e a família através da qual o ADK o serve. Um modelo que o código da aplicação constrói, ou uma árvore que não indica nenhum — o ADK usa então o seu modelo predefinido — também não é ligado a nada, e um comentário acima da instância diz porquê. Sempre que o modelo não está ligado a nada, a compilação é interrompida indicando o socket model até que um seja ligado. Dos modelos que outros agentes de uma árvore pedem, um cujos pedidos o ADK envia para a Gemini API não precisa de nenhuma ligação própria: o cliente Gemini do ADK envia os pedidos desse modelo com a chave que a ligação da instância entrega. Se a aplicação chega ao Gemini através da Gemini API ou através da Vertex AI é escolhido pelo 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 indica 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 indica esse Aggregate. A entrada de cada instância escreve o seu infra.image — a imagem que executa a aplicação construída sobre o ADK, que contém as suas configurações — vazio, sob um comentário que diz o que é, e a importação assinala-o como em falta. Com --target compose, a entrada escreve também infra.published_port, 8000, a porta em que a aplicação escuta, que a sua Recipe do Compose publica no endereço de loopback do anfitrião, 127.0.0.1, sob o comentário que diz que só é acessível a partir desta máquina, por qualquer processo que nela seja executado, e que eliminar a linha mantém o serviço interno; uma segunda árvore recebe a porta livre seguinte. Quando o seu modelo está ligado, a entrada anexa a credencial que a instância apresenta a esse modelo sob credential na sua ligação model, por referência e nunca como valor: nenhuma configuração indica uma variável para ela, pelo que é lida de GOOGLE_API_KEY, a variável de onde as bibliotecas cliente da Gemini API da Google leem a sua chave, como 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 assinale como em falta; no compose, a ligação model declara-a com essa chave. Um modelo ligado também tem uma entrada, que não contém infraestrutura, pelo que a Release o coloca junto da instância. Os valores que as configurações da árvore entregam às suas ferramentas e aos seus pedidos ao modelo são escritos num comentário acima da entrada, como descreve Valores de credenciais que uma configuração contém. Como todas as Releases de rascunho, escreve metadata.environment como development e, sem destino, um spec.manifest vazio que a importação assinala como em falta; com um destino, a importação gera o Manifest como rascunho, como descreve O que um destino acrescenta.

A aplicação que os testes deste importador importam, um agente raiz que indica as configurações de dois subagentes e um construído por código, importada como o seu diretório com as duas configurações indicadas sob with.sources, é gerada como rascunho, sem nenhuma definição, com o nome do 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, num valor ou num comentário, escreve cada {{ como {{`{{`}}, uma ação cujo resultado são as duas chavetas, pelo que a descrição, e um nome que contém duas chavetas num comentário, são lidos de volta tal 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: {}

Uma vez respondida a imagem, a instância é renderizada a executá-la 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, nos seus args, ou aos seus pedidos ao modelo, nas http_options da sua generate_content_config — os seus cabeçalhos, o seu endereço, os argumentos do 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, tal como a 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 predefinição, cada um é transportado tal como está escrito e indicado num aviso credential-carried pelo seu agente e pelo seu campo, como tools.tutor_tools.make_snippet_runner.args.api_key, nunca pelo seu valor. Com a definição empty_credentials em all, cada um é escrito sem valor e comunicado com credential-emptied; em marked cada um é transportado, uma vez que o ADK não marca nenhum. Um número ou um booleano não contém nenhuma chave, e é escrito tal como a configuração o escreve. O ADK não expande nenhuma referência a variável numa configuração, pelo que cada valor é lido tal como está escrito; o ficheiro de ambiente, que habitualmente contém a chave que o cliente Gemini do ADK lê, nunca é lido, seja o que for que diga a definição.

As definições que lê

O importador Google ADK lê target_namespace, empty_credentials e render_mode, tal como Definições os descreve, e nenhuma outra definiçã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, ligada ao modelo da OpenAI que indica, e uma Release ao lado dele. Lê agentes declarativos, e nunca o código da aplicação. O Agent Framework publica os seus pacotes de agentes declarativos como pré-lançamentos.

O que lê

Um agente declarativo declara:

  • name, displayName e description, as suas instructions e os esquemas da sua entrada e da sua saída;
  • model — o id do modelo, o provider que o serve, a API para a qual o seu cliente envia pedidos (apiType), as options dos seus pedidos, e a sua connection: uma ligação key que apresenta uma chave, escrita sob key ou apiKey, a um endpoint; uma ligação remote que alcança um endpoint; uma ligação reference que indica 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 associa, uma ferramenta web_search, file_search ou code_interpreter que o fornecedor do modelo executa, ou um servidor mcp alcançado no seu url, com o approvalMode que as 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 a partir da variável de ambiente NAME apenas quando a aplicação carrega o agente declarativo com AgentFactory(safe_mode=False), a própria definição de segurança do Agent Framework, e está presente um runtime .NET, sendo caso contrário tomado como o texto da expressão tal como está escrito; qualquer outro membro que comece por = é uma expressão que a aplicação calcula. O importador não lê nenhum dos dois: indica uma referência pela sua variável, e uma expressão como tal.

Um ficheiro importado isoladamente é lido como um agente declarativo, seja qual for o seu nome, e cada ficheiro que o with.sources do importador passa é lido como outro, pelo 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: a sua assinatura não indica nenhum ficheiro, pelo que uma importação de um diretório que não indica nenhum formato não o reconhece, e uma que indica --format agent-framework é recusada com An importer that declares no file patterns is handed a directory (Um importador que não declara padrões de ficheiro recebe um diretório) antes de qualquer ficheiro dele ser aberto. Em vez disso, cada agente declarativo deve ser importado como um ficheiro 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 — é comunicada com no-nodes. O código da aplicação — o programa que carrega cada agente declarativo e as funções que associa às suas ferramentas — nunca está entre as origens: a aplicação carrega ela própria os seus agentes declarativos, a partir da imagem que a Release indica.

Em que se torna um agente declarativo

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

  • display_name e description, o displayName e a description do agente, quando os declara;
  • a sua ligação model, ligada ao modelo que indica, quando esse modelo está ligado.

As suas instruções, os esquemas da sua entrada e da sua saída, o seu template, os seus metadados e as opções dos seus pedidos ao modelo são lidos pela aplicação a partir do agente declarativo, e são indicados num comentário acima da instância. Uma ferramenta de função, uma ferramenta que o fornecedor do modelo executa e uma ferramenta de qualquer outro tipo também são indicadas num comentário, e comunicadas numa decisão que não escolhe nada.

Um modelo cujo provider é OpenAI e que indica 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. Os agentes que indicam um mesmo modelo num mesmo endereço partilham uma instância. Quando o catálogo do workspace não contém nenhum core/ai-model/openai, é gerado um como rascunho, <target_namespace>/ai-model/openai, que contém a etiqueta model.aggrega.ai/api: openai que o socket model do agente seleciona, e a sua decisão di-lo; uma Recipe que publique o seu endpoint e o seu modelo fica a cargo do utilizador, como diz um comentário no início dele. Um id escrito como referência deixa o values.model do modelo a cargo do utilizador, com um comentário acima do modelo que indica a variável; a compilação é interrompida indicando-o até ser definido. Uma ligação anonymous é escrita como o unauthenticated: true da ligação. Um modelo de qualquer outro fornecedor — AzureOpenAI, Anthropic —, um que indica o seu fornecedor como referência ou não indica nenhum, caso em que o Agent Framework usa o fornecedor predefinido que a aplicação define, e um que não indica nenhum id não são ligados a nada, e um comentário acima da instância diz porquê; a compilação é interrompida indicando o socket model até que um seja ligado.

Uma ferramenta do tipo mcp não é gerada como rascunho nem como Component nem como ligação: o Agent Framework envia o servidor ao fornecedor do modelo como uma ferramenta alojada, e é o fornecedor, não a aplicação, que o alcança no seu url, que tem portanto de ser acessível a partir do fornecedor, pelo que nada do que o rascunho implanta o alcança. Um comentário acima da instância do agente indica o servidor, di-lo, e indica a descrição, o approvalMode e os allowedTools que o agente declarativo declara para ele; o seu url é escrito, por inteiro, no comentário acima da entrada do agente na Release, e a sua decisão não escolhe nada.

release.yaml, ao lado dele, é uma Release de rascunho com o mesmo nome que indica esse Aggregate. A entrada do agente escreve o seu infra.image — a imagem que executa a aplicação construída sobre o Agent Framework, que contém o seu agente declarativo — vazio, sob um comentário que diz o que é, e a importação assinala-o como em falta. Com --target compose, a entrada escreve também infra.published_port, 8000, a porta que o infra.port do Component indica por predefinição para a aplicação, que a sua Recipe do Compose publica no endereço de loopback do anfitrião, 127.0.0.1, sob o comentário que diz que só é acessível a partir desta máquina, por qualquer processo em execução nela, e que eliminar a linha mantém o serviço interno. Quando o seu modelo está ligado, a entrada anexa a credencial que o agente apresenta a esse modelo sob credential na sua ligação model, por referência e nunca como valor: lida da variável que o agente declarativo indica para a sua chave, escrita =Env.NAME, e caso contrário de OPENAI_API_KEY, a variável de onde as bibliotecas cliente da OpenAI leem a sua chave; como 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 assinale como em falta; no compose, a ligação model declara-a com essa chave. Os valores que o agente declarativo declara para o seu modelo e os seus servidores MCP — as chaves e o url de cada servidor — são escritos num comentário acima da entrada do agente, como descreve Valores de credenciais que um agente declarativo contém. Cada modelo ligado tem uma entrada, pelo que a Release o coloca junto do agente. O endpoint que a sua ligação declara é escrito como o infra.endpoint do modelo, e um escrito como referência é indicado ao lado da sua entrada, sendo usado o próprio endereço do Component até ser definido; uma ligação que não declara nenhum endpoint deixa a entrada sem infraestrutura, mantendo-se o próprio endereço do Component. Como todas as Releases de rascunho, escreve metadata.environment como development e, sem destino, um spec.manifest vazio que a importação assinala como em falta; com um destino, a importação gera o Manifest como rascunho, como descreve O que um destino acrescenta.

O agente declarativo que os testes deste importador importam, do fornecedor OpenAI com uma ligaçã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 ficheiro próprio, é gerado como rascunho, sem nenhuma definição, com o 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, num valor ou num comentário, escreve cada {{ como {{`{{`}}, de modo que é relido tal como está escrito depois de o Aggregate ser 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"

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

Valores de credenciais que um agente declarativo contém

A chave que uma ligação key apresenta — escrita sob key ou apiKey, no modelo ou num servidor MCP — é o único membro que o Agent Framework marca como credencial: é o único valor que o seu carregador oculta naquilo que regista. Cada chave que um agente declarativo escreve como literal é escrita no comentário acima da entrada do agente na Release, tal como o agente declarativo a escreve, e por predefinição transportada tal como está escrita e indicada num aviso credential-carried pelo seu agente e pelo seu campo, como model.connection.key, nunca pelo seu valor. O url de um servidor MCP, escrito por inteiro no mesmo comentário e indicado pelo 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 ligado é uma entrada que o Agent Framework marca como não credencial. Com a definição empty_credentials em marked, as chaves e os url dos servidores MCP são escritos sem valor — o comentário indicando cada um apenas pelo seu campo — e comunicados com credential-emptied, e o endpoint do modelo é transportado; em all, o infra.endpoint do modelo também é omitido, indicado no comentário acima da sua entrada como deixado para a Release, e o endereço predefinido do Component é usado até ser definido. Um valor escrito como =Env.NAME não contém nenhum, pelo que é indicado pela sua variável, juntamente com a condição em que o Agent Framework o lê a partir do ambiente — model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads … — seja o que for que a definição diga, e não é comunicado com nenhum dos dois códigos; um valor escrito como qualquer outra expressão é indicado como tal e nunca escrito.

As definições que lê

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

O que um destino acrescenta

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, que indica uma capacidade de fornecedor como compose ou helm — passa esse destino ao importador, pelo 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 sempre que o importador publica um serviço no endereço de loopback do anfitrião, como indica a secção de cada importador; uma porta que o importador escolhe nunca recebe um número que outra porta da Release já utiliza. A importação gera então o Manifest como rascunho ao lado do que o importador gerou, seja qual for o importador executado: manifest.yaml, ao lado da Release de rascunho e com o mesmo nome e a mesma versão que ela — ou, quando o importador não gerou nenhuma Release como rascunho, ao lado do Aggregate de rascunho e com o mesmo nome e a mesma versão que este.

Para cada tipo de componente e cada tipo de feature de que os rascunhos precisam — nos componentes do Aggregate de rascunho, nas suas ligações e nos seus subsistemas, nos Aggregates do catálogo que ele compõe, como core/dify, e nos anexos 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, quando há várias de nomes diferentes, a que tem 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, fica por mapear, um aviso indica-o e diz porquê, e uma compilação dos rascunhos é interrompida indicando cada instância ou anexo dele até ser mapeado.

Quando só o importador sabe qual de várias Recipes se aplica, ele próprio gera o Manifest como rascunho — o importador MCP mapeia cada servidor, pela sua chave, para a realização do modo como o servidor é executado, e um importador que anexa um segredo pelo nome mapeia core/referenced-secret para helm/k8s-existing-secret — e a importação completa-o: 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 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 muda na Release. aggrega import descreve-o por completo.

Definições

Um importador recebe as definições da entrada plugins.importer que o anexa, sob with.settings, como descreve Que importador transforma uma origem em rascunhos. Sem entrada, ou sem definições, cada definição assume o seu valor predefinido.

plugins:
importer:
- uri: importer/langflow:<version>
with:
settings:
target_namespace: payments
reuse_mode: hints-only
DefiniçãoPredefiniçãoO que 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, caso contrário o nome do seu diretório ou o nome do seu ficheiro sem a extensão, caso contrário flow, escrito em minúsculas, com cada sequência de caracteres que não sejam letras e dígitos ASCII convertida num único hífen, como descreve Como é nomeado um rascunho.
reuse_modeauto-apply-above-thresholdauto-apply-above-threshold referencia o Component do catálogo com a melhor correspondência para um nó a que 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, registando uma correspondência forte como sugestão. 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 predefinido.
emit_hintstrueSe o ficheiro de um Component gerado como rascunho começa com um comentário que indica o Component do catálogo com que se parece, para uma correspondência de nível alto ou médio. O Aggregate de rascunho contém o mesmo comentário acima da entrada desse nó, e acima de uma entrada referenciada um que indica o candidato seguinte melhor pelo qual poderia ser trocada, ou que diz que nenhum obteve pontuação 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 registo 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 indica o component para o qual um nó desse tipo é mapeado e, opcionalmente, a sua category, os traits — etiquetas e os seus valores — que um Component correspondente contém, e uma palavra vendor que o seu nome contém. Uma entrada para um tipo de nó que a tabela já mapeia ocupa o lugar da linha da tabela. Só são lidas as entradas sob o formato que está a ser importado.
layoutplatformplatform gera como rascunho a plataforma que executa o fluxo, transportando o fluxo, sendo cada parte dele um Component próprio ligado à plataforma, como descreve A plataforma que transporta 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 transporta a aplicação, como descreve Em que se torna uma aplicação. 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 transporta, 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 transporta, 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 estabelece 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 é transportado tal como está escrito e indicado num 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 pedidos, parâmetros de consulta, um pedido escrito como linha de comandos, uma entrada com o nome de uma chave. O que o rascunho escreve para que um nó alcance a sua ligação é escrito seja o que for que esta definiçã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 definição.
attach_egress_allowlistfalsetrue anexa 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 do seu infra, como descreve O que o rascunho deixa para a Release. false não anexa 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 anexam nada seja o que for que esta definiçã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 definiçã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 comunica

Cada importador core comunica, 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 devolvem cada um também com o seu code.

CódigoSeveridadeComunicado quando
parse-failedhaltA origem não pode ser analisada: o seu analisador recusa-a, e a mensagem contém o motivo do analisador.
no-nodeswarnA origem não contém 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 ficheiros que with.sources entrega a uma importação contém uma configuração raiz, e para o importador Agent Framework, uma origem 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, indicado juntamente com a definiçã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, pelo que nenhuma parte lhe é ligada; para o importador Dify, nenhum core/ai-agent/dify, e core/dify é composto na mesma.
part-not-placedwarnUma parte do fluxo não está ligada a nenhum socket da plataforma, com o motivo; permanece no fluxo.
socket-selector-unreadablewarnO seletor que um socket da plataforma declara não pode ser lido, pelo que nenhuma parte lhe é ligada; uma vez por cada socket.
credential-carriedwarnUm valor de credencial é transportado tal como está escrito no fluxo que o rascunho transporta, ou na Release que o importador MCP, Compose, CrewAI, LangGraph, Google ADK ou Agent Framework gera como rascunho, indicado pelo seu nó — ou pelo seu servidor, serviço, agente ou configuração — e pelo seu campo, nunca pelo seu valor, juntamente com o valor de empty_credentials que o escreve vazio.
credential-emptiedwarnUm valor de credencial é escrito vazio no fluxo que o rascunho transporta, ou na Release que o importador MCP, Compose, CrewAI, LangGraph, Google ADK ou Agent Framework gera como rascunho, onde empty_credentials o pede, indicado pelo seu nó — ou pelo seu servidor, serviço, agente ou configuração — e pelo seu campo.
carriage-returns-rewrittenwarnOs retornos de carro do fluxo são escritos como avanços de linha, com a indicação de quantos são.
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 porquê: 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 transportar uma credencial, nunca é reescrito — continua a ser o da ligação, ou o de empty_credentials — e o aviso conta cada valor não reescrito.
definition-not-carriedwarnO fluxo não é transportado 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 ligada através da sua ligação, ou como uma ligação alcança, tal como está escrita, um nó que o rascunho não liga a nenhum socket.
part-address-in-flowwarnO fluxo alcança uma parte ligada por uma via diferente da sua ligação, com a indicação de qual.
model-not-namedwarnvalues.model de uma parte referenciada fica a cargo do autor, com o motivo.
feature-attachedinfoattach_egress_allowlist anexou core/egress-allowlist a uma plataforma gerada como rascunho, com o que a Release define dela; uma vez por 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, pelo que nada é anexado.
part-configured-in-platformwarnUm nó de uma aplicação Dify indica algo que o Dify configura por si próprio — um modelo e o seu fornecedor, uma ferramenta, uma base de conhecimento, uma estratégia de agente, um plugin — pelo que o rascunho não liga nenhuma parte para ele.
dsl-version-newerwarnUma aplicação Dify está escrita numa versão da DSL mais recente do que aquela que escreve a versão do Dify que core/ai-agent/dify executa por predefinição.

Uma importação que recebe um destino comunica, após os diagnósticos do importador, o que a geração do Manifest como rascunho encontrou: um warn que indica cada tipo de componente ou de feature que o Manifest deixa por mapear e porquê, e um info quando a Release de rascunho já indica um Manifest ou nenhuma Release de rascunho o referencia. Estes são da própria importação, e não de um importador, e não contêm nenhum código; O que um destino acrescenta descreve-os. Todas as importações comunicam depois, também como seus, um warn para cada valor que os rascunhos ainda têm em falta, indicando o ficheiro de rascunho, o caminho da chave e a sua descrição, e, sob --offline, quando gerou uma Release como rascunho e não tem nada em falta, um info que indica o aggrega pull a executar a seguir, como descreve O ficheiro 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 as respetivas entidades Plugin a partir dos próprios importadores, pelo que a capacidade, as assinaturas de reconhecimento, as funções host e a descrição de uma entidade são o que o seu importador comunica. 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 regista as respetivas entidades juntamente com as entidades dos outros plugins core para o catálogo padrão.