가져오기
aggrega import는 다른 형식으로 작성된 프로젝트 — Langflow에서 내보낸 플로, MCP 클라이언트의 구성, Compose 파일, 그리고 아래에 나열된 다른 형식 — 를 읽고, 이로부터 Aggrega 파일을 작성합니다. 즉 Aggregate 하나, Release 하나, 그리고 --target이 지정하는 대상에 대한 Manifest 하나입니다. 어떤 소스도 담을 수 없는 몇 가지 값에 답하고 나면, 이들은 함께 작성된 그대로 검증되고 빌드되는 작업 공간이 됩니다. 가져오기는 각 값을 한 번만 묻고 답을 답변 파일에 보관합니다. 아무것도 배포하지 않으며 어떤 클러스터나 클라우드 계정에도 접근하지 않습니다. 초안은 작업 공간에 있는 일반 파일이며, 이후에 어떻게 할지는 사용자가 결정합니다.
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importAggrega 초안 파일
검토하고 편집할 수 있도록
기존 프로젝트를 넣으면 Aggrega 초안 파일이 나옵니다. 아무것도 배포되지 않으며, 먼저 초안을 검토합니다.
제공하는 것
- 프로젝트를 손으로 다시 작성하지 않고도 Aggrega로 가져올 수 있습니다. 초안으로 작성된 Aggregate, Release, Manifest는 직접 작성하는 것과 같은 종류의 파일입니다. 이들은 작성된 그대로 가져오기가 지정하는 대상에 대해 빌드되며, 작업 공간에 연결된 모든 거버넌스 정책이 다른 빌드와 마찬가지로 그 빌드를 판정합니다.
- 소스가 명시하는 것은 그대로 옮겨집니다. 카탈로그에 강한 일치 항목이 있는 노드나 서비스는 해당 카탈로그 Component를 참조하며, 플로가 지정하는 모델처럼 소스가 부여한 값을 함께 가집니다. 소스가 실행되는 플랫폼은 그 플랫폼에 대한 카탈로그의 Recipes가 실행하는 이미지로 초안이 작성됩니다. 시크릿은 그 값이 아니라 항상 출처에 대한 참조로 초안이 작성됩니다.
- 어떤 소스도 담을 수 없는 것만, 한 번만 묻습니다. 답은 소스 옆의 답변 파일에 보관되므로, 같은 소스를 다음에 가져올 때는 아무것도 묻지 않습니다.
- 초안은 사용자의 것입니다. 작업 공간에 있는 일반 YAML이며, 빌드가 의존하는 어떤 것도 남기지 않습니다. 편집하고, 이름을 바꾸고, 커밋하십시오.
- 초안은 소스를 따라갈 수 있습니다.
aggrega import --sync는 이전 가져오기의 초안을 변경된 소스에 맞게 갱신하며, 가져오기가 작성한 부분만 변경합니다. 사용자가 편집한 부분을 소스가 변경한 경우에는 편집 내용을 덮어쓰지 않고 중단하며 해당 부분을 지목합니다.
하지 않는 일
가져오기는 소스가 명시하는 것과 카탈로그가 결정하는 것의 초안을 작성하고, 나머지는 묻습니다. 각 초안은 값 옆의 주석으로, 초안에 작성한 값이 어디에서 왔는지 알려 줍니다.
- 소스가 명시할 수 없는 것을 추측하지 않습니다. Release가 배포되는 환경을 지정하는 소스는 없으므로, 초안으로 작성된 Release는
development를 지정하며, 이것이 변경해야 할 기본값이라는 주석이 붙습니다. 카탈로그가 요구하지만 어떤 소스에도 없는 값 — 소유자 계정의 이메일, 직접 작성한 코드로 빌드한 애플리케이션의 이미지, Kubernetes Secret의 이름 — 은 빈 값으로 초안이 작성되고, 아래의 가져오기 실행 방식에서 설명하는 대로 질문됩니다. - 코드를 읽지 않습니다. 플로나 프로젝트 자체의 프로그램은 읽히지 않습니다. CrewAI crew의 프로그램, LangGraph 애플리케이션의 그래프 코드, Langflow 컴포넌트의 소스(플로 안에 담아 옮기는 것 외에는)가 그렇습니다.
- 값의 의미를 판단하지 않습니다. 각 노드나 서비스는 작업 공간 카탈로그의 Components — 그 이름, 범주, 레이블, 선언한 값의 이름 — 와 비교하여 평가됩니다. 상위 등급의 일치는 초안에서 참조되고, 그보다 약한 일치는 해당 Component와 점수를 알려 주는 주석으로 작성되어 사용자가 선택하게 됩니다.
- 소스를 따르기 위해 플랫폼이 실행하는 버전을 바꾸지 않습니다. 플랫폼의 이미지는 그 플랫폼에 대한 카탈로그의 Recipes가 실행하는 것으로 알려진 버전으로 초안이 작성되며, 소스가 다른 버전을 지정하는 경우 이미지 옆의 주석이 그 버전을 알려 줍니다.
- 소스에서 자격 증명을 대신 옮겨 주지 않습니다. 키를 담을 수 있는 값 — 환경 값, 헤더, MCP 서버의 명령줄 — 은 기본적으로 작성된 그대로 초안에 옮겨지며, 가져오기는
credential-carried경고에서 각각을 지목하되 결코 그 값으로 지목하지 않습니다. 임포터의empty_credentials설정을 사용하면 대신 빈 값으로 작성됩니다(설정). 초안을 공유하기 전에 경고를 읽으십시오. - 아무것도 배포하거나 실행하지 않습니다. 소스와 카탈로그를 읽고 파일을 작성할 뿐입니다. 초안을 빌드하는 일과 빌드가 작성한 것을 실행하는 일은 사용자가 별도로 수행하는 단계입니다.
가져오기 실행 방식
아래 명령으로 가져오기를 실행하거나, AI 어시스턴트가 대신 실행하게 할 수 있습니다.
-
작업 공간에서 시작합니다. 가져오기는 실행되는 작업 공간의 루트 —
workspace키가 있는.aggrega-config.yaml을 담은 폴더 — 아래나,--output-dir이 지정하는 디렉터리 아래에 초안을 작성합니다. 이미 있는 Aggregate를 덮어쓰지 않습니다. -
비교 대상 카탈로그. 가져오기는 작업 공간 카탈로그의 Components에 대해서만 소스를 채점하며, 그 밖의 것은 사용하지 않습니다. 작업 공간이 자체 카탈로그 폴더를 지정하지 않으면, 그것은 작업 공간의 기본 레지스트리에서 읽는 표준 라이브러리 카탈로그입니다. 카탈로그를 게시할 때마다 카탈로그 전체의 서명된 스냅샷이 게시되며, 첫 가져오기는 그 스냅샷을 가져와 서명을 검증하고 작업 공간의 콘텐츠 캐시에 보관한 뒤, 초안 옆에 쓰는 기록에서 다이제스트로 그 스냅샷을 지정합니다. 따라서 같은 초안을 나중에 가져올 때는 레지스트리에 다시 묻지 않고 같은 카탈로그를 읽습니다. 이 카탈로그에 대해 PostgreSQL 서비스는
core/datastore/postgres에 매칭되고,--target은 카탈로그의 Recipes에서 Manifest 초안을 작성합니다. 카탈로그가 없으면 가져오기는 매칭할 대상이 없으며, 대상에 바인딩되는 Recipe가 없으므로--target은 거부됩니다.자체 카탈로그 폴더를 지정한 작업 공간은 대신 그 폴더들에 대해 가져오며 스냅샷을 가져오지 않습니다. 그 폴더는
workspace.catalog_dirs가 나열하는 디렉터리, 작업 공간 루트의catalog폴더, 또는AGGREGA_CATALOG_DIRS가 지정하는 디렉터리입니다. 표준 라이브러리 카탈로그 자체의 파일은, 이를 폴더로 원하는 작업 공간을 위해aggrega-hub저장소(https://github.com/aggrega-ai/aggrega-hub)의aggrega-catalog폴더에 있습니다.--upgrade는 레지스트리가 게시하는 최신 스냅샷을 가져와 그 이후로는 그것에 대해 가져옵니다.--offline에서는 스냅샷을 가져와야 하는 가져오기가 중지되고 실행할 명령을 알려 줍니다. -
가져오기를 실행합니다. 파일이나 디렉터리를 지정합니다:
Terminal window aggrega import compose.yaml --target compose형식은 파일의 이름과 내용으로 인식되며, 인식되지 않는 경우
--format으로 지정합니다.--target은compose나helm같은 프로바이더 기능을 지정하며, 초안에 필요한 각 컴포넌트 유형과 피처 유형을 카탈로그가 해당 유형에 제공하는 그 기능의 Recipe에 매핑하는 Manifest 초안을 작성합니다. 해당 Recipe가 하나뿐이면 그것을, 여러 개이면 유형 이름을 딴 것을 사용합니다. 초안으로 작성된 Release는 그 Manifest를 지정하며, 초안에 담기는 내용은 대상을 따릅니다.compose에서 시크릿은 Docker Compose가 셸에서 채우는 변수 참조이고,helm에서는 Kubernetes Secret의 이름입니다. 가져오기는 표준 오류에 읽은 형식, 각 경고, 매핑한 각 노드마다 한 줄을 출력하고, 표준 출력에는 작성한 파일을 나열합니다. -
어떤 소스에도 없는 값에 답합니다. 카탈로그가 요구하지만 어떤 소스도 담을 수 없는 값 — 소유자 계정의 이메일, 직접 작성한 코드로 빌드한 애플리케이션의 이미지, Kubernetes Secret의 이름 — 은 한 번만 답합니다. 가져오기는 소스 옆의
import-answers.yaml또는--answers가 지정하는 파일에서 답을 읽습니다. 터미널에서는 아직 누락된 각 값을 한 번에 하나씩 묻고, 답을 그 파일에 씁니다. 시크릿에는 값이 아니라 출처 — 변수 또는 Secret의 이름 — 로 답합니다. 아무것도 물을 수 없는 경우 — 지속적 통합, 파이프, 어시스턴트나 편집기에서 실행하는 경우 — 가져오기는 누락된 각 값의 키와 빈 답을 담은 답변 파일을 작성하고, 그 목록을 표시한 뒤 상태 1로 종료합니다. 값을 채우고 가져오기를 다시 실행하십시오. 하나의 답변 파일이 모든 대상에 사용됩니다. 어떤 대상의 초안에 필요하지 않은 답은 파일에 유지되며 사용되지 않습니다. 가져오기 답변 파일에서 이 파일을 자세히 설명합니다. -
가져오기는 빌드에 필요한 것을 가져옵니다. 누락된 것이 없으면 가져오기는
aggrega pull처럼 초안 Release의 종속성을 가져오고, 그 옆에release.lock을 작성합니다.--offline에서는 아무것도 가져오지 않고 실행할aggrega pull명령을 알려 줍니다. -
검증하고 빌드합니다. 초안이 있는 폴더에서:
Terminal window aggrega validate --release release.yamlaggrega build --release release.yaml둘 다 통과하면 빌드가 대상의 파일을
dist/아래에 작성한 상태입니다. 거부는 변경할 문서 안에서 무엇을 어디에서 변경해야 하는지 지목합니다. -
빌드가 작성한 것을 실행합니다. Docker Compose용 빌드는
dist/compose/docker-compose.yaml을 작성하는데, 이 파일은 Compose 프로젝트 이름을 지정하지 않으므로-p로 이름을 지정합니다:Terminal window docker compose -p <name> -f dist/compose/docker-compose.yaml up -d-p가 없으면 Docker Compose는 파일이 들어 있는 폴더의 이름인compose를 프로젝트 이름으로 사용하므로, 이렇게 시작한 두 워크스페이스는 하나의 프로젝트를 공유합니다. 서비스들은 하나의 네트워크에 있으며, Docker Compose는 이 네트워크의 이름을 프로젝트 이름을 따서<name>_compose로 짓습니다. 빌드가 포트를 게시하지 않는 서비스는 그 네트워크 안에서docker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …로 접근하거나, 그 네트워크에서 시작한 컨테이너에서docker run --network <name>_compose …로 접근합니다. 워크스루의 “실행하기” 및 “테스트하기” 섹션에 해당 워크스루 자체 빌드를 위한 명령이 나와 있습니다.실행의
core/ai-model/openai모델이 같은 프로젝트에서 Ollama가 제공하는 작은 모델을 가리키게 하면 OpenAI 키 없이 응답합니다. 이를 위해 초안 파일을 세 군데 변경하고, 추가한 컴포넌트에 필요한 것을 가져오는--auto-pull로 빌드한 뒤, 스택이 실행되면 명령을 하나 실행합니다:- Aggregate에 아무것에도 연결하지 않은 컴포넌트 하나 추가: 유형이
core/ai-model/ollama이고values에model: qwen2.5:0.5b를 둔local-model; - Manifest에 해당 Compose Recipe 추가:
core/ai-model/ollama: compose/ollama; - Release에
local-model: {}를 추가하고, OpenAI 모델의infra아래endpoint를 해당 서버의 OpenAI 호환 주소인http://local-model:11434/v1로 설정; - 스택이 실행된 후, 가져온 모델을 빌드의 OpenAI 모델이 지정하는 모델 이름
<model>(예:gpt-4o-mini또는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에는 비어 있지 않은 임의의 값을 직접 넣어도 됩니다. 로컬 서버는 어떤 값도 확인하지 않습니다. n8n 워크플로는 모델의 주소와 키를endpoint가 전달하는 주소가 아니라 모델 노드가 선택하는 자격 증명에서 읽으므로, 그 자격 증명에도 서버 주소를data안의apiKey옆에url로 지정하십시오.core/ai-model/ollama가 기본으로 실행하는 Ollama 서버는 Chat Completions뿐 아니라 OpenAI의 Responses API도 제공하므로,apiType: Responses를 지정하는 Agent Framework 선언적 에이전트는 작성된 그대로 이 서버에 연결합니다.Kubernetes용 빌드, 즉
helm대상은 helm 프로바이더가 설명하는 대로 차트가 아니라 일반 매니페스트를 작성합니다. 위치는dist/helm/아래이거나, Release가 경계에 배치하는 컴포넌트의 경우dist/boundaries/<boundary>/helm/아래이며, 그중 일부는 그 아래의 자체 폴더에 있습니다. MCP 및 Dify 빌드의 파일처럼 네임스페이스를 지정하지 않는 파일은kubectl컨텍스트가 지정하는 네임스페이스로, 지정하지 않으면default로 들어갑니다. 먼저 그곳에 파일이 읽는 Secrets를 만든 다음 폴더를 적용합니다:Terminal window kubectl apply -R -f dist/helm/-R은 그 폴더들 안의 파일까지 처리합니다. MCP 및 Dify 빌드가 실행하는 서버에 부여하는 종류인ClusterIPService는 클러스터 내부에서만 접근할 수 있습니다. 로컬 머신에서 접근하려면kubectl port-forward svc/<service> <local port>:<port>로 로컬 포트를 해당 서비스로 전달합니다. 이 명령은 중지할 때까지 실행됩니다. - Aggregate에 아무것에도 연결하지 않은 컴포넌트 하나 추가: 유형이
가져오기는 초안 옆에 작성한 내용의 기록인 .aggrega-import.json을 작성합니다. aggrega import --sync를 실행할 계획이 있는 동안에는 이 파일을 보관하십시오. 이 명령은 이 파일을 읽어 사용자의 편집과 가져오기 자체가 작성한 내용을 구분합니다. 답변 파일도 보관하십시오. 이 파일에는 시크릿이 없으므로 소스 옆에서 버전 관리에 둘 수 있으며, 그 소스를 이후에 가져올 때마다 이 파일을 읽습니다.
AI 어시스턴트 사용
Aggrega의 도구로 설정된 AI 어시스턴트도 같은 일을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고, 직접 폴더를 만들지 마세요. `source`를 `compose.yaml`로, `target`을 `compose`로 설정하여 `import` 도구를 호출하세요. 이 도구는 초안을 Workspace 폴더에 작성합니다. 아직 필요한 값이 있다고 하면 각 값과 그것이 무엇인지 알려 주고, 도구가 지정한 답변 파일에서 제가 각 키 옆에 답을 적는 동안 기다리세요. 그런 다음 같은 방식으로 `import` 도구를 다시 호출하세요. 이어서 `release`를 `release.yaml`로 설정하여 `validate` 도구를 호출하고, `release`를 `release.yaml`로, `write`를 true로 설정하여 `build` 도구를 호출하세요. 빌드가 작성한 파일을 알려 주세요. 그 파일들은 Workspace 폴더의 `dist/` 아래에 있습니다.VS Code에서 열기
Visual Studio Code용 Aggrega 확장을 설치한 상태에서, 가져오기를 실행한 작업 영역(그 .aggrega-config.yaml이 있는 폴더)을 VS Code에서 엽니다. 초안은 그 루트 또는 --output-dir로 지정한 폴더에 있습니다. 작업 영역에 Release가 하나 있으면 편집기가 자동으로 선택하고, 여러 개 있으면 **Aggrega: Select Release…**로 편집기가 작업할 것을 선택합니다. 편집기는 편집하는 동안 선택된 Release에 대해 초안을 검사하고, 발견한 내용을 파일과 문제 패널에 표시합니다. 명령 팔레트의 Aggrega: Show topology graph는 선택된 Release의 컴포넌트와 그 사이의 연결을 그립니다. Aggrega: Build, Aggrega: Preview build, Aggrega: Pull은 같은 Release에 작용하며, 각각 활동 표시줄에 있는 Aggrega 보기의 Commands 패널에서 버튼으로도 사용할 수 있습니다. Build는 파일을 작업 영역의 dist/에 작성합니다. 나머지는 Visual Studio Code에서 Aggrega 사용하기에서 다룹니다.
임포터의 출처
각 형식은 임포터 플러그인이 읽습니다. 컴파일러의 코어 임포터는 아래 표의 형식마다 하나씩 있으며, 모든 컴파일러 릴리스와 함께 게시되고, 카탈로그에 항목이 없어도 모든 작업 공간에서 해당 형식을 처리합니다. 임포터가 필요한 첫 가져오기는 작업 공간의 기본 레지스트리에서 컴파일러 자체 버전의 임포터를 가져와 검증한 뒤 작업 공간의 콘텐츠 캐시에 보관하므로, 이후의 모든 가져오기는 그곳에서 읽으며 이를 위해 네트워크에 접근하지 않습니다. 모듈을 아예 가져올 수 없는 경우 — 예를 들어 작업 공간이 오프라인인 경우 — 가져오기는 중단되고 모듈을 머신에 두는 두 가지 방법을 안내합니다. 코어 임포터에서 각 임포터와 plugins.importer 항목을 통해 임포터에 제공되는 설정을 자세히 설명합니다.
형식
| 형식 | 읽는 내용 | 단계별 안내 |
|---|---|---|
| Compose | Compose 파일과 그 오버라이드 파일, 또는 이들을 담은 디렉터리 | Compose 프로젝트 가져오기 |
| MCP 클라이언트 구성 | .mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json, 또는 MCP 레지스트리 server.json | MCP 클라이언트 구성 가져오기 |
| Langflow | Langflow에서 JSON으로 내보낸 플로 | Langflow 플로 가져오기 |
| Flowise | Flowise에서 JSON으로 내보낸 chatflow 또는 agentflow | Flowise chatflow 가져오기 |
| n8n | n8n에서 JSON으로 내보낸 워크플로 | n8n 워크플로 가져오기 |
| Dify | Dify에서 해당 DSL로 내보낸 애플리케이션(YAML 형식) | Dify 애플리케이션 가져오기 |
| CrewAI | CrewAI 프로젝트의 에이전트 및 태스크 선언 | CrewAI 프로젝트 가져오기 |
| LangGraph | LangGraph 애플리케이션의 langgraph.json | LangGraph 애플리케이션 가져오기 |
| Google ADK | Google ADK로 구축된 애플리케이션의 Agent Config 파일(root_agent.yaml부터) | Google ADK 에이전트 가져오기 |
| Microsoft Agent Framework | 선언적 에이전트, 즉 kind가 Prompt인 YAML 문서 | Microsoft Agent Framework 선언적 에이전트 가져오기 |
aggrega import는 이 명령의 전체 레퍼런스입니다. 모든 플래그, 소스를 인식하는 방법, --sync가 무엇을 변경하고 무엇을 거부하는지를 다룹니다. 가져오기 응답 파일은 응답 파일이 어디에 있는지, 무엇을 담고 있는지, 시크릿에 어떻게 응답하는지를 설명합니다.