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

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 import

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

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

  2. 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 --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, 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_dirs lista, uma pasta catalog na raiz do espaço de trabalho ou os diretórios que AGGREGA_CATALOG_DIRS indica. Os ficheiros 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 pretenda como pasta. --upgrade obté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.

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

    Terminal window
    aggrega import compose.yaml --target compose

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

  4. 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.yaml junto à 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.

  5. 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 pull faz, e escreve release.lock junto a ela. Com --offline, não obtém 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, a compilação terá escrito os ficheiros do destino em dist/. Uma recusa indica o que alterar e onde, no documento que se altera.

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

    Sem -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, com docker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, ou a partir de um contentor iniciado nessa rede com docker 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/openai aponta 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 tipo core/ai-model/ollama, com model: qwen2.5:0.5b nos respetivos values;
    • no Manifest, a respetiva Recipe do Compose: core/ai-model/ollama: compose/ollama;
    • na Release, local-model: {}, e a chave endpoint do modelo da OpenAI, sob o respetivo infra, 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>, 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 à 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 que endpoint entrega, pelo que deve dar também a essa credencial o endereço do servidor, como um url ao lado de apiKey nos seus data. O servidor Ollama que core/ai-model/ollama executa por predefinição serve a Responses API da OpenAI, além de Chat Completions, pelo que um agente declarativo do Agent Framework que indica apiType: Responses o 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: em dist/helm/ ou, para os componentes que uma Release coloca numa fronteira, em dist/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 do kubectl indica, ou para default quando 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/

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

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

FormatoO que lêGuia passo a passo
Composeum ficheiro Compose e o seu ficheiro de substituição, ou um diretório que os contenhaImportar 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 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 na sua DSL, em YAMLImportar uma aplicação Dify
CrewAIas declarações de agentes e de tarefas de um projeto CrewAIImportar um projeto CrewAI
LangGrapho langgraph.json de uma aplicação LangGraphImportar uma aplicação LangGraph
Google ADKos ficheiros 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: 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.