Importação
aggrega import lê um projeto escrito em outro formato — um fluxo exportado do Langflow, a configuração de um cliente MCP, um arquivo Compose e os outros formatos listados abaixo — e grava a partir dele arquivos Aggrega: um Aggregate, uma Release e, para o destino que --target indica, um Manifest. Juntos, eles formam um espaço de trabalho que é validado e compilado como está escrito, depois que os poucos valores que nenhuma origem pode conter forem respondidos: a importação pergunta cada um deles uma única vez e guarda as respostas em um arquivo de respostas. Ele não implanta nada e não acessa nenhum cluster nem conta de nuvem. Os rascunhos são arquivos comuns no seu espaço de trabalho, e o que acontece com eles depois cabe a você decidir.
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importrascunhos de arquivos Aggrega
para você revisar e editar
Seu projeto existente entra, rascunhos de arquivos Aggrega saem. Nada é implantado; você revisa os rascunhos primeiro.
O que a importação oferece
- Seu projeto chega ao Aggrega sem ser reescrito à mão. O Aggregate, a Release e o Manifest rascunhados são o mesmo tipo de arquivo que você mesmo escreveria. Eles compilam como estão escritos para o destino que a importação indica, e toda política de governança que seu espaço de trabalho anexa avalia esse build como qualquer outro.
- O que a origem declara é transportado. Um nó ou serviço para o qual o catálogo tem uma correspondência forte referencia esse Component do catálogo, com os valores que a origem lhe dá, como o modelo que um fluxo indica. Uma plataforma em que a origem é executada é rascunhada com a imagem que as Recipes do catálogo para ela executam. Um segredo é rascunhado como uma referência à sua procedência, nunca como seu valor.
- Só é perguntado a você o que nenhuma origem pode conter, uma única vez. As respostas são guardadas em um arquivo de respostas ao lado da origem, de modo que a próxima importação da mesma origem não pergunta nada.
- Os rascunhos são seus. São YAML comum no seu espaço de trabalho, sem deixar para trás nada de que o build dependa. Edite-os, renomeie-os, faça commit deles.
- O rascunho pode acompanhar sua origem.
aggrega import --syncatualiza os rascunhos de uma importação anterior de acordo com uma origem alterada, mudando apenas o que a importação gravou. Onde a origem alterou uma parte que você editou, ele para e nomeia essa parte em vez de sobrescrever sua edição.
O que ela não faz
Uma importação rascunha o que a origem declara e o que seu catálogo determina, e pergunta o resto. Cada rascunho diz, em um comentário ao lado do valor, de onde veio um valor que ele rascunhou.
- Não adivinha o que sua origem não pode declarar. Nenhuma origem indica o ambiente em que uma Release é implantada; por isso, a Release rascunhada indica
development, com um comentário dizendo que é um padrão a ser alterado. Um valor que o catálogo exige e que nenhuma origem contém — o e-mail da conta de um proprietário, a imagem de uma aplicação construída a partir do seu próprio código, o nome de um Secret do Kubernetes — é rascunhado vazio e perguntado, como descreve Como uma importação é executada abaixo. - Não lê código. O próprio programa de um fluxo ou de um projeto não é lido: o programa de uma crew do CrewAI, o código do grafo de uma aplicação LangGraph, o código-fonte de um componente do Langflow, a não ser para transportá-lo dentro do fluxo.
- Não julga o que um valor significa. Cada nó ou serviço é comparado com os Components do catálogo do seu espaço de trabalho — seus nomes, suas categorias, seus rótulos e os nomes dos valores que declaram. Uma correspondência no nível alto é referenciada no rascunho; uma mais fraca é escrita como um comentário que indica o Component e sua pontuação, para você escolher.
- Não altera a versão que uma plataforma executa para acompanhar a origem. A imagem de uma plataforma é rascunhada na versão que se sabe que as Recipes do catálogo para ela executam e, onde a origem indica outra versão, um comentário ao lado da imagem a indica.
- Não retira as credenciais da sua origem por você. Um valor que pode conter uma chave — um valor de ambiente, um cabeçalho, a linha de comando de um servidor MCP — é levado para o rascunho tal como está escrito, por padrão, e a importação nomeia cada um em um aviso
credential-carried, nunca pelo seu valor. A configuraçãoempty_credentialsdo importador os grava vazios em vez disso (Configurações). Leia os avisos antes de compartilhar um rascunho. - Não implanta nem executa nada. Lê a origem e o seu catálogo, e grava arquivos. Compilar os rascunhos e executar o que o build grava são etapas separadas que você realiza.
Como uma importação é executada
Você pode executar uma importação com os comandos abaixo ou pedir ao seu assistente de IA que a execute para você.
-
Parta de um espaço de trabalho. Uma importação grava seus rascunhos sob a raiz do espaço de trabalho em que é executada — a pasta que contém um
.aggrega-config.yamlcom uma chaveworkspace— ou sob o diretório que--output-dirindica. Ela nunca sobrescreve um Aggregate que já esteja lá. -
O catálogo usado na comparação. A importação pontua sua origem em relação aos Components do catálogo do espaço de trabalho, e a nada mais. Quando o espaço de trabalho não indica nenhuma pasta de catálogo própria, esse é o catálogo da biblioteca padrão, lido do registro padrão do espaço de trabalho: cada publicação do catálogo publica um snapshot assinado do catálogo inteiro, e a primeira importação busca esse snapshot, verifica sua assinatura, guarda-o no cache de conteúdo do espaço de trabalho e o identifica pelo digest no arquivo de registro que grava ao lado dos rascunhos, de modo que uma importação posterior dos mesmos rascunhos lê o mesmo catálogo sem consultar de novo o registro padrão. Em relação a ele, um serviço PostgreSQL é associado a
core/datastore/postgres, e--targetrascunha um Manifest a partir das Recipes do catálogo. Sem catálogo, a importação não tem nada a associar, e--targeté recusado, já que nenhuma Recipe se vincula ao destino.Um espaço de trabalho que indica as próprias pastas de catálogo importa em relação a elas, e não busca nenhum snapshot: os diretórios que
workspace.catalog_dirslista, uma pastacatalogna raiz do espaço de trabalho ou os diretórios queAGGREGA_CATALOG_DIRSindica. Os arquivos do próprio catálogo da biblioteca padrão são a pastaaggrega-catalogdo repositórioaggrega-hub, https://github.com/aggrega-ai/aggrega-hub, para um espaço de trabalho que os queira como pasta.--upgradebusca o snapshot mais recente que o registro publica e passa a importar em relação a ele; com--offline, uma importação que precisaria buscar um snapshot para e indica o que executar. -
Execute a importação. Indique o arquivo ou o diretório:
Terminal window aggrega import compose.yaml --target composeO formato é reconhecido pelo nome e pelo conteúdo do arquivo;
--formato indica quando não é.--targetindica uma capacidade de provedor, comocomposeouhelm, e rascunha um Manifest que mapeia cada tipo de componente e cada tipo de funcionalidade de que os rascunhos precisam para a Recipe dessa capacidade que seu catálogo oferece para ele: a que existe ou, entre várias, a que leva o nome do tipo. A Release rascunhada indica esse Manifest, e o que os rascunhos contêm segue o destino: emcompose, um segredo é uma referência a uma variável que o Docker Compose preenche a partir do seu shell; emhelm, o nome de um Secret do Kubernetes. Na saída de erro padrão, a importação nomeia o formato que leu, cada aviso e uma linha para cada nó que mapeou; na saída padrão, lista os arquivos que gravou. -
Responda o que nenhuma origem contém. Um valor que o catálogo exige e que nenhuma origem pode conter — o e-mail da conta de um proprietário, a imagem de um aplicativo construído a partir do seu próprio código, o nome de um Secret do Kubernetes — é respondido uma única vez. A importação lê as respostas de
import-answers.yamlao lado da origem, ou do arquivo indicado por--answers; em um terminal, ela pergunta cada valor ainda ausente, uma pergunta por vez, e grava suas respostas nesse arquivo. Um segredo é respondido com sua procedência — uma variável ou o nome de um Secret —, nunca com seu valor. Onde nada pode ser perguntado — em integração contínua, por um pipe, a partir do assistente ou do editor —, a importação grava o arquivo de respostas com a chave de cada valor ausente e uma resposta vazia, lista-os e sai com status 1; preencha-os e execute a importação novamente. Um único arquivo de respostas serve a todos os destinos: uma resposta de que os rascunhos de um destino não precisam é mantida no arquivo e fica sem uso. O arquivo de respostas da importação descreve o arquivo por completo. -
A importação baixa o que o build precisa. Quando nada mais falta, a importação baixa as dependências da Release rascunhada, como faz
aggrega pull, e gravarelease.lockao lado dela. Com--offline, ela não baixa nada e indica o comandoaggrega pulla executar. -
Valide e compile. Na pasta que contém os rascunhos:
Terminal window aggrega validate --release release.yamlaggrega build --release release.yamlQuando ambos passam, o build terá gravado os arquivos do destino em
dist/. Uma recusa indica o que alterar e onde, no documento que você altera. -
Execute o que o build escreveu. Um build para Docker Compose escreve
dist/compose/docker-compose.yaml, e o arquivo não nomeia nenhum projeto do Compose, então nomeie um com-p:Terminal window docker compose -p <name> -f dist/compose/docker-compose.yaml up -dSem
-p, o Docker Compose dá ao projeto o nome da pasta que contém o arquivo,compose, de modo que dois espaços de trabalho iniciados assim compartilham um único projeto. Os serviços ficam em uma única rede, à qual o Docker Compose dá o nome do projeto,<name>_compose. Um serviço para o qual o build não publica nenhuma porta é acessado de dentro dessa rede, comdocker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, ou de um contêiner que você inicia nessa rede comdocker run --network <name>_compose …. As seções “Executar” e “Testar” de um passo a passo mostram os comandos do seu próprio build.Uma execução responde sem uma chave da OpenAI assim que seu modelo
core/ai-model/openaiaponta para um modelo pequeno servido pelo Ollama no mesmo projeto, com três alterações nos arquivos rascunhados, um build com--auto-pull, que baixa o que o componente adicionado precisa, e um comando depois que a stack estiver em execução:- no Aggregate, mais um componente, ligado a nada:
local-model, do tipocore/ai-model/ollama, commodel: qwen2.5:0.5bem seusvalues; - no Manifest, sua Recipe do Compose:
core/ai-model/ollama: compose/ollama; - na Release,
local-model: {}, e a chaveendpointdo modelo da OpenAI, sob seuinfra, definida como o endereço compatível com a OpenAI desse servidor,http://local-model:11434/v1; - depois que a stack estiver em execução, o modelo baixado copiado com o nome de modelo que o modelo OpenAI do build indica,
<model>, comogpt-4o-miniougpt-4.1:docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.
OPENAI_API_KEYpode então conter qualquer valor não vazio que você escolher: o servidor local não verifica nenhum. Um workflow do n8n lê o endereço e a chave do modelo na credencial que seu nó de modelo seleciona, não no endereço queendpointentrega, então dê também a essa credencial o endereço do servidor, como umurlao lado deapiKeyem seusdata. O servidor Ollama quecore/ai-model/ollamaexecuta por padrão atende a Responses API da OpenAI, além de Chat Completions, então um agente declarativo do Agent Framework que indicaapiType: Responseso alcança tal como está escrito.Um build para Kubernetes, o destino
helm, grava manifestos simples em vez de um chart, como descreve o provedor helm: emdist/helm/ou, para os componentes que uma Release coloca em uma fronteira, emdist/boundaries/<boundary>/helm/, alguns deles em uma pasta própria abaixo. Arquivos que não indicam nenhum namespace, como os dos builds do MCP e do Dify, vão para o que o seu contexto dokubectlindica, ou paradefaultquando ele não indica nenhum; crie lá primeiro os Secrets que eles leem e depois aplique a pasta:Terminal window kubectl apply -R -f dist/helm/-Ralcança os arquivos nessas pastas. Um ServiceClusterIP, o tipo que os builds do MCP e do Dify dão aos servidores que executam, só é acessível de dentro do cluster: para acessar um a partir da sua máquina, encaminhe uma porta local para ele comkubectl port-forward svc/<service> <local port>:<port>, que fica em execução até você interrompê-lo. - no Aggregate, mais um componente, ligado a nada:
Ao lado dos rascunhos, a importação grava .aggrega-import.json, o registro do que gravou. Mantenha-o enquanto pretender executar aggrega import --sync, que o lê para distinguir as suas edições das dela. Mantenha também o arquivo de respostas: ele não contém nenhum segredo, então pode ficar no controle de versão ao lado da origem, e toda importação posterior dessa origem o lê.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Chame a ferramenta `import` com `source` definido como `compose.yaml` e `target` definido como `compose`: ela grava seus rascunhos na pasta Workspace. Se ela disser que ainda faltam valores, diga-me cada um e o que ele é, e aguarde enquanto escrevo minhas respostas ao lado das chaves no arquivo de respostas que ela indicar; depois chame a ferramenta `import` novamente da mesma forma. Em seguida, chame a ferramenta `validate` com `release` definido como `release.yaml`, e a ferramenta `build` com `release` definido como `release.yaml` e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `dist/` na pasta Workspace.Abra no VS Code
Com a extensão do Aggrega para Visual Studio Code instalada, abra no VS Code o workspace em que a importação foi executada — a pasta que contém seu .aggrega-config.yaml: os rascunhos estão nele, na raiz ou na pasta indicada por --output-dir. Onde o workspace contém uma Release, o editor a seleciona para você; onde contém mais de uma, Aggrega: Select Release… escolhe aquela com que o editor trabalha. O editor verifica os rascunhos em relação à Release selecionada enquanto você os edita, marcando o que encontra no arquivo e no painel Problemas. Aggrega: Show topology graph, na Paleta de Comandos, desenha os componentes da Release selecionada e as conexões entre eles. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull atuam sobre a mesma Release, e cada um também é um botão no painel Commands da visualização Aggrega na barra de atividades; Build grava seus arquivos no dist/ do workspace. Usar o Aggrega no Visual Studio Code cobre o restante.
De onde vêm os importadores
Cada formato é lido por um plugin importador. Os importadores principais do compilador, um para cada formato da tabela abaixo, são publicados com cada versão do compilador e atendem seus formatos em todo espaço de trabalho, sem nenhuma entrada no seu catálogo. A primeira importação que precisa de um deles o busca no registro padrão do espaço de trabalho, na versão do próprio compilador, verifica-o e o guarda no cache de conteúdo do espaço de trabalho, de modo que toda importação posterior o lê dali, sem precisar da rede para isso. Quando o módulo não pode ser obtido de forma alguma — por exemplo, se o espaço de trabalho estiver offline —, a importação para e indica as duas maneiras de colocá-lo na máquina. Importadores principais descreve cada importador por completo, bem como as configurações que um importador recebe por meio de uma entrada plugins.importer.
Os formatos
| Formato | O que ele lê | Guia passo a passo |
|---|---|---|
| Compose | um arquivo Compose e seu arquivo de substituição, ou um diretório que os contém | Importar um projeto Compose |
| Configurações de clientes MCP | .mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json ou um server.json de um registro MCP | Importar uma configuração de cliente MCP |
| Langflow | um fluxo exportado do Langflow, em JSON | Importar um fluxo do Langflow |
| Flowise | um chatflow ou um agentflow exportado do Flowise, em JSON | Importar um chatflow do Flowise |
| n8n | um fluxo de trabalho exportado do n8n, em JSON | Importar um workflow do n8n |
| Dify | uma aplicação exportada do Dify em sua DSL, em YAML | Importar uma aplicação Dify |
| CrewAI | as declarações de agentes e tarefas de um projeto CrewAI | Importar um projeto CrewAI |
| LangGraph | o langgraph.json de uma aplicação LangGraph | Importar uma aplicação LangGraph |
| Google ADK | os arquivos Agent Config de uma aplicação criada com o Google ADK, a partir de root_agent.yaml | Importar um agente do Google ADK |
| Microsoft Agent Framework | um agente declarativo, um documento YAML do tipo Prompt | Importar um agente declarativo do Microsoft Agent Framework |
aggrega import é a referência completa do comando: cada flag, como uma origem é reconhecida, o que --sync altera e o que recusa. O arquivo de respostas da importação descreve o arquivo de respostas: onde ele fica, o que contém e como um segredo é respondido.