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

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 import

rascunhos 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 --sync atualiza 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ção empty_credentials do 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ê.

  1. 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.yaml com uma chave workspace — ou sob o diretório que --output-dir indica. Ela nunca sobrescreve um Aggregate que já esteja lá.

  2. 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 --target rascunha 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_dirs lista, uma pasta catalog na raiz do espaço de trabalho ou os diretórios que AGGREGA_CATALOG_DIRS indica. Os arquivos do próprio catálogo da biblioteca padrão são a pasta aggrega-catalog do repositório aggrega-hub, https://github.com/aggrega-ai/aggrega-hub, para um espaço de trabalho que os queira como pasta. --upgrade busca 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.

  3. Execute a importação. Indique o arquivo ou o diretório:

    Terminal window
    aggrega import compose.yaml --target compose

    O formato é reconhecido pelo nome e pelo conteúdo do arquivo; --format o indica quando não é. --target indica uma capacidade de provedor, como compose ou helm, 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: em compose, um segredo é uma referência a uma variável que o Docker Compose preenche a partir do seu shell; em helm, 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.

  4. 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.yaml ao 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.

  5. 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 grava release.lock ao lado dela. Com --offline, ela não baixa nada e indica o comando aggrega pull a executar.

  6. Valide e compile. Na pasta que contém os rascunhos:

    Terminal window
    aggrega validate --release release.yaml
    aggrega build --release release.yaml

    Quando 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.

  7. 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 -d

    Sem -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, com docker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, ou de um contêiner que você inicia nessa rede com docker 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/openai aponta 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 tipo core/ai-model/ollama, com model: qwen2.5:0.5b em seus values;
    • no Manifest, sua Recipe do Compose: core/ai-model/ollama: compose/ollama;
    • na Release, local-model: {}, e a chave endpoint do modelo da OpenAI, sob seu infra, 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>, como gpt-4o-mini ou gpt-4.1: docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.

    OPENAI_API_KEY pode 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 que endpoint entrega, então dê também a essa credencial o endereço do servidor, como um url ao lado de apiKey em seus data. O servidor Ollama que core/ai-model/ollama executa por padrão atende a Responses API da OpenAI, além de Chat Completions, então um agente declarativo do Agent Framework que indica apiType: Responses o 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: em dist/helm/ ou, para os componentes que uma Release coloca em uma fronteira, em dist/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 do kubectl indica, ou para default quando 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/

    -R alcança os arquivos nessas pastas. Um Service ClusterIP, 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 com kubectl port-forward svc/<service> <local port>:<port>, que fica em execução até você interrompê-lo.

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

FormatoO que ele lêGuia passo a passo
Composeum arquivo Compose e seu arquivo de substituição, ou um diretório que os contémImportar 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 MCPImportar uma configuração de cliente MCP
Langflowum fluxo exportado do Langflow, em JSONImportar um fluxo do Langflow
Flowiseum chatflow ou um agentflow exportado do Flowise, em JSONImportar um chatflow do Flowise
n8num fluxo de trabalho exportado do n8n, em JSONImportar um workflow do n8n
Difyuma aplicação exportada do Dify em sua DSL, em YAMLImportar uma aplicação Dify
CrewAIas declarações de agentes e tarefas de um projeto CrewAIImportar um projeto CrewAI
LangGrapho langgraph.json de uma aplicação LangGraphImportar uma aplicação LangGraph
Google ADKos arquivos Agent Config de uma aplicação criada com o Google ADK, a partir de root_agent.yamlImportar um agente do Google ADK
Microsoft Agent Frameworkum agente declarativo, um documento YAML do tipo PromptImportar 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.