Importação
aggrega import lê um projeto escrito noutro formato — um fluxo exportado do Langflow, a configuração de um cliente MCP, um ficheiro Compose e os outros formatos listados abaixo — e escreve a partir dele ficheiros Aggrega: um Aggregate, uma Release e, para o destino que --target indica, um Manifest. Em conjunto, formam um espaço de trabalho que é validado e compilado tal como está escrito, depois de respondidos os poucos valores que nenhuma origem pode conter: a importação pergunta cada um deles uma única vez e guarda as respostas num ficheiro de respostas. Não implementa nada e não acede a nenhum cluster nem conta na nuvem. Os rascunhos são ficheiros simples no seu espaço de trabalho, e o que lhes acontece a seguir fica ao seu critério.
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importrascunhos de ficheiros Aggrega
para rever e editar
Entra o seu projeto existente, saem rascunhos de ficheiros Aggrega. Nada é implementado; os rascunhos são revistos primeiro.
O que a importação oferece
- O seu projeto chega ao Aggrega sem ser reescrito à mão. O Aggregate, a Release e o Manifest rascunhados são o mesmo tipo de ficheiros que escreveria por si próprio. Compilam tal como estão escritos para o destino que a importação indica, e todas as políticas de governação que o seu espaço de trabalho anexa avaliam essa compilação como qualquer outra.
- O que a origem declara é transportado. Um nó ou serviço para o qual o catálogo contém uma correspondência forte referencia esse Component do catálogo, com os valores que a origem lhe atribui, 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 proveniência, nunca como o seu valor.
- Só lhe é perguntado o que nenhuma origem pode conter, uma única vez. As respostas são guardadas num ficheiro de respostas ao lado da origem, pelo que a importação seguinte da mesma origem não pergunta nada.
- Os rascunhos são seus. São YAML simples no seu espaço de trabalho, sem deixar para trás nada de que a compilação dependa. Edite-os, mude-lhes o nome, faça commit deles.
- O rascunho pode acompanhar a 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 escreveu. Onde a origem alterou uma parte que editou, para e indica essa parte em vez de escrever por cima da sua edição.
O que não faz
Uma importação rascunha o que a origem declara e o que o seu catálogo determina, e pergunta o resto. Cada rascunho diz, num comentário ao lado do valor, de onde veio um valor que rascunhou.
- Não adivinha o que a sua origem não pode declarar. Nenhuma origem indica o ambiente em que uma Release é implementada; por isso, a Release rascunhada indica
development, com um comentário a dizer que se trata de um valor predefinido a alterar. 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 decorre uma importação 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 o transportar 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 — os seus nomes, as suas categorias, as suas etiquetas 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 a sua pontuação, para que escolha.
- 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, quando a origem indica outra versão, um comentário ao lado da imagem indica-a.
- Não retira as credenciais da sua origem por si. Um valor que pode conter uma chave — um valor de ambiente, um cabeçalho, a linha de comandos de um servidor MCP — é levado para o rascunho tal como está escrito, por predefinição, e a importação indica cada um num aviso
credential-carried, nunca pelo seu valor. A definiçãoempty_credentialsdo importador escreve-os vazios em vez disso (Definições). Leia os avisos antes de partilhar um rascunho. - Não implementa nem executa nada. Lê a origem e o seu catálogo, e escreve ficheiros. Compilar os rascunhos e executar o que a compilação escreve são passos separados que cabe a si dar.
Como decorre uma importação
É possível executar uma importação com os comandos abaixo ou pedir ao seu assistente de IA que a execute.
-
Parta de um espaço de trabalho. Uma importação escreve os 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. Nunca escreve por cima de um Aggregate que já lá esteja. -
O catálogo usado na comparação. A importação pontua a sua origem face 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 a partir do registo predefinido do espaço de trabalho: cada publicação do catálogo publica um snapshot assinado da sua totalidade, e a primeira importação obtém esse snapshot, verifica a sua assinatura, guarda-o na cache de conteúdo do espaço de trabalho e identifica-o pelo seu digest no ficheiro de registo que escreve junto aos rascunhos, pelo que uma importação posterior dos mesmos rascunhos lê o mesmo catálogo sem voltar a consultar o registo predefinido. Face 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, uma vez que nenhuma Recipe se vincula ao destino.Um espaço de trabalho que indica as suas próprias pastas de catálogo importa antes face a essas, e não obtém 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 ficheiros 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 pretenda como pasta.--upgradeobtém o snapshot mais recente que o registo publica e passa a importar face a ele a partir daí; com--offline, uma importação que teria de obter um snapshot para e indica o que executar. -
Execute a importação. Indique o ficheiro ou o diretório:
Terminal window aggrega import compose.yaml --target composeO formato é reconhecido pelo nome e pelo conteúdo do ficheiro;
--formatindica-o quando não o é.--targetindica uma capacidade de fornecedor, 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 o seu catálogo oferece para ele: a que existe ou, entre várias, a que tem o nome do tipo. A Release rascunhada indica esse Manifest, e o que os rascunhos contêm acompanha o destino: emcompose, um segredo é uma referência a uma variável que o Docker Compose preenche a partir da sua shell; emhelm, o nome de um Secret do Kubernetes. Na saída de erro padrão, a importação indica o formato que leu, cada aviso e uma linha por cada nó que mapeou; na saída padrão, lista os ficheiros que escreveu. -
Responder ao 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 uma aplicação construída 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.yamljunto à origem, ou do ficheiro indicado por--answers; num terminal, pergunta cada valor ainda em falta, uma pergunta de cada vez, e escreve as respostas nesse ficheiro. Um segredo é respondido com a sua proveniência — uma variável ou o nome de um Secret —, nunca com o seu valor. Onde nada pode ser perguntado — em integração contínua, através de um pipe, a partir do assistente ou do editor —, a importação escreve o ficheiro de respostas com a chave de cada valor em falta e uma resposta vazia, lista-os e termina com o estado 1; preencha-os e execute novamente a importação. Um único ficheiro de respostas serve todos os destinos: uma resposta de que os rascunhos para um destino não precisam é mantida no ficheiro e fica sem uso. O ficheiro de respostas da importação descreve o ficheiro na íntegra. -
A importação obtém o que a compilação precisa. Quando já nada falta, a importação obtém as dependências da Release rascunhada, tal como
aggrega pullfaz, e escreverelease.lockjunto a ela. Com--offline, não obtém 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, a compilação terá escrito os ficheiros do destino em
dist/. Uma recusa indica o que alterar e onde, no documento que se altera. -
Executar o que o build escreveu. Um build para Docker Compose escreve
dist/compose/docker-compose.yaml, e o ficheiro não nomeia nenhum projeto do Compose, pelo que é preciso nomear 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 ficheiro,compose, pelo que dois espaços de trabalho iniciados dessa forma partilham um único projeto. Os serviços ficam numa ú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 é acedido a partir do interior dessa rede, comdocker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, ou a partir de um contentor iniciado nessa rede comdocker run --network <name>_compose …. As secções «Executar» e «Testar» de um guia passo a passo mostram os comandos do seu próprio build.Uma execução responde sem uma chave da OpenAI assim que o respetivo modelo
core/ai-model/openaiaponta para um modelo pequeno servido pelo Ollama no mesmo projeto, com três alterações aos ficheiros rascunhados, uma compilação com--auto-pull, que obtém o que o componente acrescentado precisa, e um comando depois de a stack estar em execução:- no Aggregate, mais um componente, ligado a nada:
local-model, do tipocore/ai-model/ollama, commodel: qwen2.5:0.5bnos respetivosvalues; - no Manifest, a respetiva Recipe do Compose:
core/ai-model/ollama: compose/ollama; - na Release,
local-model: {}, e a chaveendpointdo modelo da OpenAI, sob o respetivoinfra, definida como o endereço compatível com a OpenAI desse servidor,http://local-model:11434/v1; - depois de a stack estar em execução, o modelo descarregado copiado com o nome de modelo indicado pelo modelo OpenAI do build,
<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 à escolha: o servidor local não verifica nenhum. Um workflow do n8n lê o endereço e a chave do modelo a partir da credencial que o seu nó de modelo seleciona, e não do endereço queendpointentrega, pelo que deve dar também a essa credencial o endereço do servidor, como umurlao lado deapiKeynos seusdata. O servidor Ollama quecore/ai-model/ollamaexecuta por predefinição serve a Responses API da OpenAI, além de Chat Completions, pelo que um agente declarativo do Agent Framework que indicaapiType: Responseso alcança tal como está escrito.Um build para Kubernetes, o destino
helm, escreve manifestos simples em vez de um chart, como descreve o fornecedor helm: emdist/helm/ou, para os componentes que uma Release coloca numa fronteira, emdist/boundaries/<boundary>/helm/, alguns deles numa pasta própria abaixo. Os ficheiros que não indicam nenhum namespace, como os dos builds do MCP e do Dify, vão para o que o contexto dokubectlindica, ou paradefaultquando este não indica nenhum; criam-se aí primeiro os Secrets que eles leem e, depois, aplica-se a pasta:Terminal window kubectl apply -R -f dist/helm/-Ralcança os ficheiros nessas pastas. Um ServiceClusterIP, o tipo que os builds do MCP e do Dify dão aos servidores que executam, só é acessível a partir do interior do cluster: para aceder a um a partir da máquina local, reencaminha-se uma porta local para ele, comkubectl port-forward svc/<service> <local port>:<port>, que fica em execução até ser interrompido. - no Aggregate, mais um componente, ligado a nada:
Ao lado dos rascunhos, a importação escreve .aggrega-import.json, o registo do que escreveu. Mantenha-o enquanto pretender executar aggrega import --sync, que o lê para distinguir as suas edições das dela. Mantenha também o ficheiro de respostas: não contém nenhum segredo, pelo que pode ficar no controlo de versões junto à origem, e cada importação posterior dessa origem lê-o.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole nele este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Chame a ferramenta `import` com `source` definido como `compose.yaml` e `target` definido como `compose`: escreve os seus rascunhos na pasta Workspace. Se indicar que ainda faltam valores, diga-me cada um e o que é, e aguarde enquanto escrevo as minhas respostas ao lado das respetivas chaves no ficheiro de respostas que indicar; depois chame novamente a ferramenta `import` 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 que ficheiros o build escreveu; estão em `dist/` na pasta Workspace.Abrir 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 o 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 seleciona-a automaticamente; onde contém mais, Aggrega: Select Release… escolhe aquela com que o editor trabalha. O editor verifica os rascunhos em relação à Release selecionada à medida que são editados, assinalando o que encontra no ficheiro e no painel Problemas. Aggrega: Show topology graph, na Paleta de Comandos, desenha os componentes da Release selecionada e as ligaçõ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 vista Aggrega na barra de atividade; Build escreve os seus ficheiros no dist/ do workspace. Utilizar o Aggrega no Visual Studio Code cobre o resto.
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 servem os seus formatos em todos os espaços de trabalho, sem nenhuma entrada no seu catálogo. A primeira importação que precisa de um deles obtém-no a partir do registo predefinido do espaço de trabalho, na versão do próprio compilador, verifica-o e guarda-o na cache de conteúdo do espaço de trabalho, pelo que todas as importações posteriores o leem daí, sem precisarem da rede para isso. Quando o módulo não pode de todo ser obtido — por exemplo, se o espaço de trabalho estiver offline —, a importação para e indica as duas formas de o colocar na máquina. Importadores principais descreve cada importador por completo, bem como as definições que um importador recebe através de uma entrada plugins.importer.
Os formatos
| Formato | O que lê | Guia passo a passo |
|---|---|---|
| Compose | um ficheiro Compose e o seu ficheiro de substituição, ou um diretório que os contenha | 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 registo 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 na sua DSL, em YAML | Importar uma aplicação Dify |
| CrewAI | as declarações de agentes e de 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 ficheiros 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: todas as flags, como uma origem é reconhecida, o que --sync altera e o que recusa. O ficheiro de respostas da importação descreve o ficheiro de respostas: onde se encontra, o que contém e como se responde a um segredo.