확장성
생태계 확장성과 컴파일러 가드레일
1. 범용 WebAssembly (Wasm) 인터페이스
생태계 전반에 걸친 아키텍처 대칭성을 보장하기 위해, Aggrega는 컴파일러 파이프라인의 모든 Wasm 소켓에 균일하게 적용되는 표준화된 실행 계약을 사용합니다.
모든 플러그인을 호출하는 YAML 인터페이스는 명시적으로 선택된 두 키워드 function과 with에 의존합니다.
function: Aggrega는 Wasm 런타임(Wazero 엔진 위에서 동작하는 Extism 툴킷)을 내장하여 Wasm을 메모리에서 직접 실행하므로, 운영 체제 프로세스는 시작되지 않습니다.function은 Go 호스트가 호출하는 export, 즉 Wasm 모듈에서 명시적으로 export된 함수를 지정합니다.with: 플러그인 자체의 입력으로, Developer의values및 Release가 충족하는parameters와 분리되어 있습니다. 이 키워드는 GitHub Actions 관례(with:)를 따르며, 플러그인이 입력에 대한 JSON Schema를 선언한 경우 호스트는 실행 전에 그 스키마로 입력을 검증합니다.
Wasm Plugins의 유형:
이 보편적인 function 및 with 인터페이스는 컴파일러의 모든 프로그래밍 가능한 소켓을 지원합니다:
| Plugin 유형 | 실행 위치 | 목적 | 예상 출력 |
|---|---|---|---|
Provider (provider) | 렌더링(생성) | 최종 인메모리 IR을 대상 형식(Helm, Terraform, Compose)의 물리적 문자열 파일로 변환합니다. | 문자열 파일의 배열. |
FeatureRecipe 파이프라인 단계 (pipeline-step) | Recipe 또는 FeatureRecipe의 플러그인 파이프라인 | 시크릿을 가져오거나 기본 AST에 사이드카를 주입하는 순차적 단계. | 키가 지정된 문서 집합에 대한 RFC 6902 patches, 그리고 side_effects(새 문서 또는 파일 생성), diagnostics, 이후 단계가 읽을 수 있는 outputs. 단계 입력에는 해당 키가 지정된 문서 집합과 단계의 렌더링된 with 입력이 담깁니다. |
거버넌스 (governance) | 어노테이션 확장 전, 토폴로지 구성, 정적 분석 또는 렌더 단계 | 빌드 파이프라인의 거버넌스 역할을 수행합니다. 어노테이션 확장 전에는 해석된 컴포넌트에 어노테이션을 주입하고, 토폴로지 구성 시에는 노드에 규정 준수 또는 환경 레이블을 자동으로 태깅합니다(운영자가 각각 옵트인). 정적 분석 또는 렌더 단계에서는 Loud Guardrail로 동작하여 그래프 간선, 경로, 레이블 또는 렌더링된 아티팩트를 보안 경계에 대해 평가합니다. 무엇을 출력할 수 있는지는 종류가 아니라 연결된 역할이 결정합니다. | 어노테이션 확장 전에는 어노테이션 주입. 토폴로지 구성 시에는 metadata.labels를 대상으로 하는 JSONPatch 배열. 정적 분석 또는 렌더 단계에서는 halt, warn 또는 info 심각도의 판정(Rego 정책은 이를 deny, warn, audit 아래에 수집)이며, halt는 빌드를 중단시킵니다. |
린터 (linter) | 대역 외 | 선택적 FinOps 또는 위생 점검(예: .infra로부터의 클라우드 비용 추정) 및 게시 시점의 규율. | 경고 문자열 또는 치명적 중단. |
CLI 확장 (cli) | 런타임(aggrega <command>) | 서명되고 샌드박스화된 플러그인이 제공하는 드롭인 최상위 명령으로, 호스트에 명령별 Go 코드가 전혀 필요하지 않습니다. | 스트리밍되는 표준 출력과 표준 오류, 그리고 게스트의 종료 코드. |
파서 (parser) | 외부 형식을 읽는 곳마다 필요 시 실행 | 외부 소스 텍스트(HCL, TOML, YAML, JSON, 주석이 포함된 JSON)를 정규 JSON 트리로 변환합니다. | tree와 diagnostics, 그리고 선택적 소스 spans. |
임포터 (importer) | 빌드 외부에서 필요 시 실행(aggrega import, 에디터, 어시스턴트의 import 도구) | 외부 인프라 또는 에이전트 정의 소스(Langflow, Flowise, n8n, MCP 구성, Compose 애플리케이션, Dify 애플리케이션, CrewAI 프로젝트에 선언된 에이전트, LangGraph 애플리케이션의 구성, Google ADK 애플리케이션의 에이전트 구성, Agent Framework 선언적 에이전트)를 Aggrega 작성 파일 초안으로 변환하며, 처리하는 형식을 import:<format> 기능으로 알립니다. | 초안 Aggregate / Component / Release 엔티티 또는 재사용하는 카탈로그 Components에 대한 참조, 그 배후의 매핑 결정, 진단, 작성할 스캐폴드 파일. |
호스트 런타임: 기능을 거부하는 샌드박스. Aggrega는 Wasm 호스트를 Wazero 엔진 위에서 동작하는 Extism 툴킷으로 내장합니다. 호스트 바이너리는 네이티브 툴체인 의존성이 없는 순수 Go로 유지되므로 aggrega는 깔끔하게 크로스 컴파일됩니다. 모든 소켓은 AOT 순수성 방화벽 뒤에서 실행됩니다. 호스트는 플러그인에 런타임 접근 기능을 일절 부여하지 않으므로(네트워크, 파일 시스템, 벽시계 시간, 환경, 표준 I/O 모두 불가), 이를 사용하려는 호출은 실패하고, 호스트가 제공하지 않는 호스트 인터페이스에서 import하는 플러그인은 로드 시점에 거부됩니다. 네트워크에 접근하거나 시계를 읽을 수 없는 플러그인은 같은 입력이 같은 출력을 만든다는 컴파일러의 사전(ahead-of-time) 보장을 깨뜨릴 수 없습니다. 몇 가지 무해한 시작용 import가 필요한 언어 런타임은 해당 import의 기능 거부 구성에서 실행됩니다. 호스트는 관찰 가능한 벽시계 시간을 고정하고, 실제 엔트로피를 제공하며, 표준 I/O를 폐기하고, 파일 시스템·인수·환경 접근을 부여하지 않습니다. 따라서 플러그인은 빌드마다 달라지는 호스트 기능에 접근할 수 없습니다. 엔트로피는 의도적으로 고정하지 않고 실제 값으로 둡니다. 이를 고정하면 게스트 언어 런타임의 내부 해시 시드와 맵 순회 순서가 안정화되어, 자체 출력이 재현 불가능한 플러그인이 서로 다른 출력으로 드러나지 않고 숨겨지기 때문입니다. 결과가 엔트로피에 의존하는 플러그인은 작성 수준의 결정성 문제이며, 이 구성은 그것을 가리지 않고 드러내도록 만들어졌습니다.
호스트에 맞춘 작성: PDK. 플러그인 작성자는 Wasm 메모리 ABI를 직접 작성하지 않습니다. Aggrega는 Go, Rust, TypeScript 세 언어로 Plugin Development Kit를 제공합니다. 이는 각 소켓의 타입이 지정된 입력과 출력을 제공하는 얇은 래퍼로, 작성자는 평범한 함수를 작성하면 됩니다. 위의 function / with 인터페이스는 Aggregate나 FeatureRecipe가 플러그인을 호출하는 데 사용하는 것이고, PDK는 플러그인 작성자가 빌드 대상으로 삼는 것입니다.
각 소켓이 실행되는 곳. 모든 소켓은 같은 호스트를 통해 실행됩니다. 게시 린터는 aggrega lint 아래에서, 거버넌스 역할과 렌더 프로바이더, Recipe 및 FeatureRecipe 파이프라인 단계는 aggrega build 중에, 파서는 외부 형식을 읽는 모든 곳에서, 임포터는 aggrega import 아래에서, CLI 플러그인은 최상위 명령으로 실행됩니다. 소켓별 준비 상태는 언어 현황을 참조하십시오.
어떤 플러그인이 고정되고, 어떤 플러그인을 환경이 선택하는가. Aggrega는 출하하는 출력을 변경하는지 여부에 따라 플러그인을 구분합니다. 출력을 형성하는 플러그인(렌더 프로바이더, 변환 역할로 연결된 거버넌스 플러그인(label-transform, annotation-transform), FeatureRecipe 및 Recipe 파이프라인 단계)은 aggrega pull 시 릴리스 lockfile에 고정되며, aggrega build 및 aggrega serve에서 해당 lockfile만으로 바이트 단위까지 동일하게 재현됩니다. 두 종류는 고정되지 않습니다. 빌드가 매번 같은 위치에서 각각을 읽기 때문입니다. 컴파일러 바이너리 내부에서 제공되는 렌더 프로바이더, 그리고 Plugin 엔터티가 사용자 자신의 카탈로그 디렉터리 중 하나에 작성된 프로바이더나 파이프라인 단계가 그것입니다. 적용되는 출력 형성 플러그인을 변경하려면 다시 pull합니다. pull 이후 워크스페이스 구성을 변경해도 다음 pull 전까지는 빌드의 출력이 바뀌지 않습니다. 게이트 플러그인(정책 및 lint)은 빌드의 바이트를 변경하지 않고 빌드를 판정하므로, pull 시 캐시되지만(따라서 빌드가 오프라인에서도 이를 실행할 수 있으며, 컴파일러 바이너리에 포함된 것이나 사용자 자신의 카탈로그 디렉터리에 작성된 것은 대신 그곳에서 읽습니다) 고정되지는 않습니다. 어떤 게이트가 실행될지는 빌드 시점에 환경이 선택하므로, 개발 환경은 관대하게 / CI는 엄격하게 나누는 구성은 다시 pull하는 일이 아니라 일반적인 구성 선택이며, 게이트를 전환해도 통과한 빌드가 내보내는 출력은 결코 바뀌지 않습니다. 임포터와 CLI 확장처럼 작성 입력에만 작용하는 Plugins는 빌드 출력을 형성하지 않으며, 고정되지도 않고 빌드의 캐시 집합에 포함되지도 않습니다.
2. FeatureRecipe Plugin 파이프라인
FeatureRecipes는 추상적인 운영 의도(보안 프록시 연결이나 사이드카 주입 등)를 버전이 지정된 WebAssembly(Wasm) 플러그인 파이프라인에 바인딩합니다. 운영팀은 구체적인 프로바이더 대상에서 Feature에 필요한 것을 선언하고, 컴파일러는 선언된 파이프라인을 평면 IR 그래프에 대해 실행합니다.
이 바인딩은 생태계에 세 가지 결과를 가져옵니다.
- 진화의 분리. 인프라 어휘는 Aggrega 컴파일러의 코어 릴리스 없이도 외부 Wasm 플러그인을 통해 확장됩니다. 새로운 프로바이더, 새로운 사이드카, 새로운 보안 통합은 안정적인 Wasm ABI를 기반으로 하는 독립적인 Wasm 바이너리로 배포됩니다.
- 시맨틱 버저닝. FeatureRecipes는 버전으로 Wasm 플러그인을 참조합니다. 정확한 버전(
:1.0.0) 또는 캐럿 범위(:^1.0.0, 그와 호환되는 가장 높은 버전)입니다. 캐럿 범위를 사용하면 운영팀은 메이저 버전을 고정하면서,aggrega pull --upgrade로 lockfile을 다시 해석할 때마다 그 마이너 및 패치 릴리스를 받아들입니다. - 복잡성의 분담. 벤더별 CRD 생성이나 복잡한 렌더링(벤더별 정책 객체, 프로바이더 고유의 라우팅 리소스)은 컴포넌트 정의 안의 스키마 선언이나 템플릿 로직을 거치는 대신, 평면 IR 그래프에서 동작하는 순수 Wasm 플러그인에 둡니다.
파이프라인 체이닝 — 플러그인 간 관심사 분리. FeatureRecipe 파이프라인은 여러 Wasm 플러그인을 순차적으로 연결할 수 있으며, 각 플러그인은 컴파일러로부터 동일한 IR 노드 컨텍스트를 받습니다. 표준 패턴은 책임을 나누어, 하나의 플러그인이 기능의 의미적 의도와 특정 대상 환경의 물리적 트래픽 가로채기 메커니즘을 함께 떠안지 않도록 합니다.
대표적인 두 플러그인 체인은 다음과 같습니다.
- 기능의 의미적 규칙(보안 정책 규칙, 감사 패턴, 속도 제한 임계값)을 내보내는 구성 플러그인. 이 플러그인은 기능의 의도를 이해하지만, 대상 환경의 트래픽 가로채기 패브릭은 이해하지 않습니다.
- 그 규칙을 실어 나르는 물리적 메시 구성(게이트웨이 CRD, 사이드카 주입 패치, 방화벽 규칙)을 내보내는 라우팅 플러그인. 이 플러그인은 대상 환경의 패브릭을 이해하지만, 기능의 의미적 의도는 이해하지 않습니다.
두 플러그인은 컴파일러로부터 동일한 IR 노드 컨텍스트를 차례로 받으므로, 서로 직접 결합하지 않고도 깔끔하게 조합됩니다. 컴파일러는 파이프라인을 조율하고, 플러그인은 도메인 지식을 담당합니다.
3. 트래픽 가로채기: HTTPRoute 대상
Aggrega의 확장성 모델은 메시 수준 트래픽 가로채기를 위한 프로바이더 간 공통 아티팩트로 Kubernetes Gateway API HTTPRoute 표준을 대상으로 합니다. 표준 라이브러리는 core/http-route Feature를 통해 HTTPRoute 객체를 내보내며, 그 helm FeatureRecipe는 연결된 컴포넌트마다 라우트 하나를 렌더링합니다. Gateway API를 사용하는 대상 환경은 HTTPRoute를 자체 고유 패브릭으로 변환합니다.
4. Plugin 자율성: 레이블 해석
Wasm 플러그인이 IR 그래프에서 물리적 리소스를 생성할 때, SRE는 실행 중인 Kubernetes Pod나 클라우드 리소스를 Aggregate에 담긴 개발자의 의미적 의도까지 추적할 수 있어야 합니다. Aggrega의 확장성 모델은 그 변환을 전적으로 Wasm 플러그인 작성자의 통제 아래에 둡니다.
컴파일러는 IR 그래프의 labels 딕셔너리 전체를 해석 없이 Wasm 샌드박스로 전달합니다. 그 이후의 매핑 로직은 플러그인 작성자인 플랫폼 운영팀이 결정합니다. 모든 레이블을 그대로 전달하거나, 특정 도메인 접두사(*.aggrega.ai/*)로 필터링하거나, 그래프 레이블을 프로바이더 고유의 태깅 스키마에 직접 매핑할 수 있습니다(IR 레이블을 AWS tags, Kubernetes annotations 또는 클라우드별 메타데이터 메커니즘으로 변환). 컴파일러는 생성된 아티팩트에 태그를 붙이는 방식에 아무런 제한도 두지 않습니다.
이러한 자율성 덕분에 도메인별 지식 — 어떤 레이블이 관측성에 중요한지, 어떤 레이블이 고유 태깅 관례에 매핑되는지, 어떤 레이블이 플랫폼 내부용인지 — 은 Wasm 플러그인 계층 안에 머물며, 이 계층에서 생태계는 Go 컴파일러의 릴리스 주기와 무관하게 발전합니다.
5. CLI 확장: 런타임 명령
위의 소켓들은 빌드 내부에서 실행됩니다. 컴파일러는 Aggregate를 파싱하고, 변경하고, 검증하고, 렌더링하는 과정에서 이 소켓들을 호출합니다. CLI 확장 소켓은 성격이 다릅니다. 이 소켓은 운영자가 aggrega <command>를 입력할 때 어떤 빌드와도 무관하게 터미널에서 실행됩니다. 이것이 코어 릴리스 없이 aggrega 명령 표면 자체를 확장하는 방법입니다.
CLI 확장이란. CLI 확장은 서명되고 샌드박스화된 Wasm 플러그인이 제공하는 드롭인 방식의 aggrega <command>입니다. 렌더링 소켓과 마찬가지로 게스트가 소유하는 드롭인 방식을 취합니다. 도메인 로직은 전적으로 게스트에 있으며, Go 호스트는 명령별 코드를 전혀 제공하지 않습니다. 새 최상위 명령을 추가하는 데에는 세 가지만 필요합니다. .wasm 바이너리, pluginType: cli를 선언하는 Plugin 엔터티 하나(Plugin 참조), 그리고 명시적인 aggrega plugin add cli입니다. 호스트는 설치된 플러그인의 자체 보고로부터 명령을 발견하며, 바이너리에 컴파일되어 들어간 명령은 없습니다.
런타임 소켓이 빌드 소켓이 할 수 없는 일을 할 수 있는 이유. 컴파일 타임 소켓은 빌드 중에 실행되므로 기능이 차단된 상태로 결정론적으로 유지됩니다. Aggrega는 AOT(ahead-of-time) 컴파일러이며, 같은 입력은 항상 같은 출력을 생성해야 합니다(아키텍처 불변 조건 참조). 따라서 렌더 플러그인이나 정책 플러그인은 네트워크에 접근하거나, 시계를 읽거나, 터미널로 스트리밍할 수 없습니다. 실행마다 달라지는 것은 무엇이든 그 보장을 깨뜨리기 때문입니다. CLI 확장은 그 경계의 이후, 그리고 바깥에서 실행되며, 결정론적 파이프라인이 아니라 프롬프트 앞의 사람이 구동합니다. 바로 그 때문에 CLI 플러그인은 실행 중에 표준 출력과 표준 오류를 스트리밍하고 프로세스 종료 코드를 반환할 수 있습니다. 그러한 효과가 바이트 단위의 안정성을 위협할 빌드 산출물이 없기 때문입니다.
설치, 실행, 발견. aggrega plugin add cli <query>는 구성된 레지스트리에서 일치하는 cli 플러그인을 검색하고, 레지스트리의 신뢰 정책에 따라 검증한 뒤, 최상위 명령으로 설치합니다. 이때 플러그인이 선언한 기능을 먼저 출력하므로, 운영자는 명령이 설치되기 전에 그 명령에 허용되는 작업을 정확히 확인합니다. 설치되면 aggrega <command>는 다른 내장 명령처럼 실행됩니다. CLI 플러그인은 describe() 자체 보고에서 명령과 그 플래그를 선언하며, 호스트는 내장 명령과 똑같이 aggrega help <command>에서 각 명령의 플래그를 렌더링하므로, 운영자는 설치된 명령의 --flags도 같은 방식으로 발견합니다. 설치 가능한 명령과 카탈로그 콘텐츠를 찾으려면 aggrega search가 구성된 레지스트리의 로컬 인덱스를 조회합니다. --kind plugin --plugin-type cli은 결과를 설치 가능한 CLI 플러그인으로 좁히고, 필터 없는 검색은 카탈로그 엔터티를 대상으로 합니다. aggrega plugin list는 이미 설치된 항목을 보여 줍니다. 명령별 플래그와 출력 형태는 해당 참조 페이지에 있습니다.
기능 모델. CLI 확장은 모든 명령이 선언이나 확인 요청 없이 받는 고정된 기본 기능에서 시작합니다.
| 기본 기능 | 부여 |
|---|---|
| 명령줄 인수 입력 | 항상 |
| 스트리밍되는 표준 출력과 표준 오류 | 항상 |
| 프로세스 종료 코드 출력 | 항상 |
기본 기능을 넘어서는 모든 것은 기본적으로 꺼져 있습니다. 더 많은 기능이 필요한 플러그인은 추가 기능을 각각 명시적으로 선언하며, 호스트는 설치 시 이를 표시하여 운영자가 확인한 후에만 부여합니다. 기본 기능을 넘어 추가되는 기능 범주(환경, 파일 시스템 또는 네트워크 접근, 대화형 입력)는 동일한 선언 및 확인 관문을 거쳐 부여되므로, 명령이 운영자가 승인하지 않은 접근 범위를 몰래 얻는 일은 결코 없습니다.
내장 명령이 항상 우선합니다. 설치된 플러그인은 내장 명령을 결코 가릴 수 없습니다. 거부 목록에 기반한 예약 이름 보호 장치가 내장 명령과 내장 명령용으로 예약된 이름 집합을 보호하며, 충돌은 코어 동작을 재정의하도록 허용되지 않고 설치 시점에 거부됩니다. 운영자가 의존하는 명령 표면은 그 위에 무엇이 설치되든 안정적으로 유지됩니다.
6. Parser Plugins: 외부 형식 읽기
컴파일러는 자신이 작성하지 않은 형식으로 쓰인 텍스트를 읽어야 할 때가 많습니다. HCL로 된 Terraform 모듈, TOML로 된 구성 파일, YAML이나 JSON으로 된 매니페스트 등입니다. 파서 소켓은 컴파일러 코어에 특정 형식을 가르치지 않고도 그러한 읽기 기능을 제공합니다. 파서는 외부 소스 텍스트를 구조화된 JSON 트리로 변환하는 상태 없는 플러그인입니다. HCL 파일의 바이트를 넘겨주면, 파이프라인의 나머지 부분이 이미 탐색할 줄 아는 JSON 객체로 같은 내용을 반환합니다. 기본적으로 파싱하지 않는 형식을 읽어야 하는 컴파일러의 모든 부분은 파싱된 트리를 요청하고 그것을 바탕으로 작업합니다.
형식은 컴파일러 기능이 아니라 기능(capability)입니다. 파서는 자신이 처리하는 형식을 parse:hcl, parse:toml 등의 기능으로 알리며, 호스트는 요청된 형식으로 파서를 찾아 실행하고 트리를 돌려줍니다. 이는 렌더 공급자와 CLI 플러그인이 따르는 것과 같은 드롭인 방식의 기능 공지 모델입니다. 컴파일러 코어에는 내장된 형식 목록이 없으므로, 형식을 추가하는 것은 새 파서 플러그인을 배포하는 일이지 결코 코어 릴리스가 아닙니다. HCL, TOML, YAML, JSON, 주석이 있는 JSON용 파서는 시작 세트로 바이너리에 포함되어 제공됩니다. 다른 형식이 필요한 기업은 그 형식을 알리는 파서 플러그인을 배포합니다.
형식 선택은 선언적이며, 결코 추측하지 않습니다. 호스트는 파일이 무엇인지 판단하기 위해 파일 내용을 검사하지 않습니다. 고정된 우선순위에 따라 선언된 신호로 형식을 고릅니다. 렌더 공급자는 자신이 출력하는 각 파일의 형식을 선언할 수 있으며, 호스트는 이 생성자가 선언한 형식을 무조건 우선합니다. 바이트를 쓴 공급자가 그것을 읽는 방법에 대한 권위자이기 때문입니다. 생성자가 태그를 지정하지 않은 파일에는 고정된 파일 확장자 매핑이 대안으로 쓰입니다. .tf는 HCL, .toml은 TOML, .yaml은 YAML, .json은 JSON을 선택합니다. 선언된 형식이나 고정된 확장자로 선택하면 파싱이 결정론적이고 알기 쉽게 유지됩니다. 같은 입력은 항상 같은 파서로 전달되며, 운영자는 파일 안의 바이트를 몰라도 어떤 파서가 실행될지 알 수 있습니다. 내용 스니핑은 선택이 페이로드에 좌우되게 만들므로 Aggrega는 이를 하지 않습니다.
파서는 순수하게 구문적입니다. 출력은 JSON 트리와 진단, 그리고 선택적으로 각 노드가 유래한 소스 위치입니다. 파서는 Aggrega의 의미를 전혀 담지 않습니다. 텍스트가 구조적으로 무엇을 말하는지 보고할 뿐, 그것이 Component나 Recipe, 또는 다른 엔터티로서 무엇을 의미하는지는 다루지 않습니다. 파싱된 트리를 Aggrega 엔터티로 바꾸는 것은 다른 곳에 있는 별개의 관심사이며, 파서의 유일한 일은 구문을 JSON으로 충실하게 변환하는 것입니다. 같은 취지로 읽기 방향은 단방향입니다. 파서는 형식을 트리로 읽을 뿐, 형식을 다시 써내지 않습니다.
소비자 예: Terraform HCL에 대한 정책. 빌드가 생성한 Terraform을 검사해야 하는 렌더 단계 정책은 HCL을 직접 배우지 않습니다. 호스트가 파서 소켓을 통해 HCL 산출물을 파싱하고, 정책 플러그인이 이미 읽을 줄 아는 JSON 트리를 넘겨주므로, 정책은 다른 모든 소켓이 받는 형태의 구조화된 데이터를 바탕으로 판단합니다. 외부 형식을 읽는 새로운 소비자도 같은 방식으로 구성됩니다. 호스트에 트리를 요청한 다음 JSON으로 작업합니다. 따라서 형식을 이해하는 컴파일러의 능력은 코어를 키우는 것이 아니라 파서 플러그인을 추가함으로써 확장됩니다.
7. Importer Plugins: 외부 소스로부터 작성 파일 초안 만들기
팀이 빈 페이지에서 시작하는 경우는 드뭅니다. 팀의 에이전트 아키텍처는 이미 다른 곳에 존재하는 경우가 많습니다. Langflow나 Flowise 플로, n8n 워크플로, Dify 애플리케이션, 클라이언트에 구성된 MCP 서버, Compose 애플리케이션, 프레임워크의 구성이 선언하는 에이전트 등입니다. 임포터 소켓은 이러한 외부 소스를 Aggrega 작성의 출발점으로 바꿉니다. 임포터는 소스를 읽어 초안 Aggregate 및 Component 엔터티를 스캐폴딩하고, MCP 구성, Compose 애플리케이션 또는 프레임워크의 선언된 구성으로부터는 초안 Release도 스캐폴딩하여 작성자가 검토하고 완성하도록 합니다. 이로써 팀은 이미 가진 것을 손으로 다시 작성하지 않고 Aggrega로 가져올 수 있습니다. 임포터는 의미를 매핑합니다. 즉, 소스 노드가 무엇인지 읽고 그것을 나타내는 Aggrega 엔터티를 제안하거나, 초안 플랫폼이 운반하는 플로 안에 그대로 둡니다. 컴파일러는 어떤 플러그인이 생성하는 내용에도 구애받지 않는 것과 똑같이, 출력된 엔터티를 불투명하게 그대로 전달합니다.
형식은 컴파일러 기능이 아니라 기능(capability)입니다. 임포터는 자신이 처리하는 형식을 기능으로 광고합니다. import:langflow, import:flowise, import:n8n, import:mcp, import:compose, import:dify, import:crewai, import:langgraph, import:google-adk, import:agent-framework 등입니다. 호스트는 요청된 형식으로 임포터를 확인하고 실행한 뒤, 임포터가 초안으로 작성한 엔터티를 돌려받습니다. 이는 파서 소켓이 parse:<format>으로 취하는 것과 같은 드롭인 방식의 기능 광고 모델입니다. 컴파일러 코어는 가져올 수 있는 형식의 기본 제공 목록을 갖지 않으므로, 새 형식을 지원하는 것은 그 형식을 광고하는 임포터 플러그인을 배포하는 일이며 코어 릴리스가 필요하지 않습니다.
임포터는 파서 소켓을 통해 읽으며, 다시 파싱하지 않습니다. 임포터는 소스의 구조화된 형태가 필요하지만, 생태계가 이미 파싱하는 형식의 읽기를 다시 구현하지 않습니다. 트리가 필요하면 호스트에 일치하는 파서를 실행하도록 요청합니다. 이 파서는 워크스페이스의 카탈로그가 소스의 구문에 대해 제공하는 파서이거나, 카탈로그가 아무것도 제공하지 않는 경우 컴파일러 자체가 포함하는 파서입니다. 요청은 파이프라인의 나머지 부분이 사용하는 것과 같은 호스트 중개 파싱 기능을 통해 이루어지며, 임포터는 반환된 JSON 트리를 바탕으로 작업합니다. 읽기(구문에서 트리로)는 파서의 일로 남고, 매핑(트리에서 Aggrega 엔터티로)은 임포터의 일입니다. 두 소켓은 서로 중복되지 않고 조합됩니다. 임포터는 소스에 대한 매핑 지능을 더하고, 바이트 처리는 기존 파서에 맡깁니다.
형식은 임포터가 선언하는 내용으로 인식되며, 추측하지 않습니다. 가져오기는 소스 형식을 직접 지정할 수 있습니다. 지정하지 않는 경우, 형식은 각 임포터가 자체 보고에서 선언하고 그 Plugin 엔터티가 기록하는 시그니처로 인식됩니다. 시그니처에는 소스를 읽는 구문, 시그니처가 적용되는 파일 이름, 그리고 파싱된 트리가 반드시 포함하거나 포함하지 않아야 하는 경로가 담깁니다. 호스트는 자체적으로 아는 형식이 없습니다. 호스트는 시그니처가 지정하는 각 구문에 대해 워크스페이스의 카탈로그가 제공하는 파서(카탈로그가 아무것도 제공하지 않으면 컴파일러 자체의 파서)로 소스를 파싱하고, 반환된 트리에 대해 선언된 술어를 평가한 뒤, 시그니처가 일치하는 단 하나의 임포터의 형식으로 소스를 읽습니다. 선언된 시그니처는 파서 소켓에서 고정된 파일 확장자 맵이 하는 역할을 대신합니다. 가져오기가 읽는 형식들은 확장자를 공유할 수 있기 때문입니다. Langflow 내보내기, Flowise 내보내기, n8n 워크플로는 모두 JSON 파일입니다. 어떤 시그니처와도 일치하지 않는 소스는 거부되며, 형식을 요청하고 임포터가 광고하는 형식을 나열합니다. 디렉터리인 경우에는 그 안의 파일 하나를 단독으로 지정하거나 파일 패턴을 선언하는 임포터의 형식을 지정하도록 요청하고, 그러한 형식만 나열합니다. 둘 이상의 형식의 시그니처와 일치하는 소스도 거부되며, 해당 형식을 나열합니다. 인식은 소스 외에는 아무것도 읽지 않고 네트워크에도 접근하지 않으므로, 새 형식을 인식하게 하는 것은 새 임포터가 함께 배포하는 선언이며 호스트를 변경하는 일이 아닙니다. 시그니처 작성 규칙은 임포터 소켓에 있습니다.
디렉터리는 임포터가 선언하는 파일을 통해 읽힙니다. 소스는 파일 또는 디렉터리입니다. 파일은 통째로 임포터에 전달됩니다. 디렉터리는 이름이 붙은 소스들로 읽힙니다. 즉, 임포터 시그니처의 파일 패턴이 선택하는 디렉터리 내 파일만 정확히, 각각 디렉터리 내부 경로로 이름이 붙어 정렬된 순서로 읽히며, 디렉터리의 다른 파일은 열리지 않습니다. 읽기를 디렉터리 밖으로 이끄는 링크는 무엇이든 읽기 전에 거부됩니다. 파일 패턴을 선언하지 않는 임포터는 파일 하나를 읽고 디렉터리를 거부하며, 임포터의 패턴이 선택하는 파일이 하나도 없는 디렉터리도 거부됩니다. 컴파일러의 Langflow, Flowise, n8n, Dify 및 Agent Framework 임포터는 패턴을 선언하지 않으므로, 각각 내보낸 플로, 워크플로 또는 애플리케이션 파일 하나, 또는 선언적 에이전트 하나를 읽습니다. MCP 임포터는 자신이 읽는 MCP 클라이언트 구성의 파일 이름을 선언하므로, 프로젝트 디렉터리는 그 안에 있는 구성을 통해 읽힙니다. Compose 임포터는 Compose가 기본적으로 읽는 파일 이름을 선언하므로, 프로젝트 디렉터리는 Compose 파일과 Compose가 그 위에 병합하는 오버라이드 파일을 통해 읽힙니다. CrewAI 임포터는 CrewAI 프로젝트가 에이전트와 태스크를 선언하는 파일 이름을 선언하므로, 프로젝트 디렉터리는 그 선언을 통해 읽히며 프로그램은 절대 읽히지 않습니다. LangGraph 임포터는 langgraph.json을 선언하므로, 애플리케이션 디렉터리는 그 구성만을 통해 읽히고 코드와 환경 파일은 읽히지 않습니다. 구성이 지정하는 환경 파일은 어태치먼트의 with.sources가 전달하는 경우에만 임포터에 도달하며, 그때도 변수 이름만 읽힙니다. Google ADK 임포터는 root_agent.yaml을 선언하므로, 애플리케이션 디렉터리는 루트 에이전트의 구성만을 통해 읽힙니다. 하위 에이전트가 지정하는 구성은 어태치먼트의 with.sources가 전달하는 경우에만 임포터에 도달하며, 코드와 환경 파일은 절대 읽히지 않습니다.
매핑은 결정론적이고, 신뢰도 점수가 매겨지며, 자신의 카탈로그와 비교됩니다. 호스트는 워크스페이스 자체 카탈로그가 보유한 Components의 뷰를 임포터에 전달합니다. 이 카탈로그는 임포터가 선택된 카탈로그, 즉 워크스페이스의 카탈로그 폴더이거나, 워크스페이스가 이를 지정하지 않은 경우에는 기본 레지스트리가 게시하는 카탈로그 스냅샷이며, 엔터프라이즈 카탈로그의 Components도 표준 라이브러리의 것과 똑같이 포함됩니다. 뷰에는 각 Component의 이름, 버전, 레이블, 그 values와 provides가 선언하는 키 이름, 소켓의 셀렉터가 담기며, 값, 기본값 또는 시크릿은 절대 담기지 않습니다. 뷰를 위해 그 스냅샷 외에는 가져오는 것이 없고 순서가 고정되어 있으므로, 하나의 카탈로그는 하나의 뷰를 만듭니다. Go PDK의 임포터 패키지로 빌드된 임포터(컴파일러 자체의 Langflow, Flowise, n8n 및 Compose 임포터 포함)는 소스의 각 노드를 그 Components와만 비교하며, 결정론적이고 모델을 쓰지 않는 신뢰도 모델을 사용합니다. 그리고 그 결정(비교한 후보, 부여한 일치 등급, 내린 선택)을 작성자가 읽고 수정할 수 있는 검토 가능한 힌트로 기록합니다. 카탈로그에 새로 추가된 Component는 임포터를 다시 빌드하지 않아도 다음 가져오기에서 후보가 됩니다. 기본값은 힌트만 제공하는 것입니다. 가져오기는 제안하고, 작성자가 결정합니다. 신뢰도가 높은 일치는 새로 작성한 본문 대신 기존 카탈로그 component에 대한 참조로 작성될 수 있지만, 이는 운영자가 옵트인한 경우에만 해당하며, 항상 작성자가 승인하는 명시적이고 되돌릴 수 있는 제안이고 결코 조용한 재작성이 아닙니다. 점수 산정에는 모델도 런타임 조회도 없으므로, 같은 카탈로그에 대해 점수를 매긴 같은 소스는 항상 같은 힌트를 만듭니다.
flow는 그것을 실행하는 플랫폼으로 초안이 작성됩니다. Langflow flow, Flowise chatflow, n8n workflow는 플랫폼 위에서 실행되며, 기본적으로 import는 flow의 노드가 아니라 그 플랫폼의 초안을 작성합니다. 즉 표준 라이브러리의 플랫폼 Component — core/ai-agent/langflow, core/ai-agent/flowise 또는 core/ai-agent/n8n — 의 인스턴스 하나가 내보낸 그대로의 flow를 flow_definition 값에 담으며, 플랫폼은 배포 시 이를 로드합니다. 플랫폼의 소켓이 받는 flow의 각 부분 — 표준 라이브러리의 플랫폼에서는 모델, MCP 서버 또는 HTTP로 접근하는 그 밖의 도구, 그리고 벡터 저장소 — 은 각각 별도의 Component가 되어 매핑의 결정에 따라 참조되거나 초안으로 작성되고, 플랫폼의 uses 아래에서 해당 소켓에 연결됩니다. 따라서 flow가 모델, 도구 또는 저장소에 대해 수행하는 각 호출은 Aggregate가 선언하는 연결이 됩니다. 그래프를 판정하는 거버넌스 플러그인은 이를 다른 모든 엣지와 똑같이 보며, attach_egress_allowlist 설정이 플랫폼에 연결하는 표준 라이브러리의 egress 허용 목록은 플랫폼이 자신의 연결이 닿는 대상, 자신의 pod, 클러스터의 DNS에만 접속하도록 합니다. 형식이 허용하는 경우, 초안은 담긴 flow가 각 부분에 해당 연결을 통해 닿도록 하는 내용을 flow에 기록합니다. 그 밖의 모든 노드 — 에이전트, 체인, 트리거 — 는 담긴 flow 안에 남고 Component가 되지 않으며, 그 결정에는 비교 대상이 된 후보가 기록됩니다. Dify 애플리케이션도 같은 방식으로, 설치 전체가 취하는 형태로 초안이 작성됩니다. 표준 라이브러리가 조립하는 Dify 설치 core/dify의 항목 하나가 app_definition 매개변수에 애플리케이션을 담고, 설치가 자체 연결을 구성합니다. 임포터 attachment의 layout 설정이 초안을 선택합니다. 기본값인 platform, 또는 소스의 모든 노드를 각각 별도의 Component로, flow의 각 엣지를 uses 연결로 초안 작성하고 flow를 담지 않는 nodes입니다. flow를 담는 플랫폼에서 어떤 노드가 부분이 되며 각각이 어디에 연결되는지 설명합니다.
코드 우선 프레임워크는 프로그램이 아니라 선언된 구성을 통해 읽습니다. CrewAI, LangGraph, Google ADK, Agent Framework는 애플리케이션의 동작을 프로그램에 두고, 에이전트·그래프·모델은 그 옆의 구성에 선언합니다. 이들의 임포터는 그 선언 — CrewAI 프로젝트의 에이전트 및 태스크 파일, LangGraph 애플리케이션의 langgraph.json, Google ADK 애플리케이션의 에이전트 구성, Agent Framework 선언형 에이전트 — 만 읽고, 한 번도 열지 않는 프로그램을 둘러싸는 해당 프레임워크용 표준 라이브러리 에이전트의 초안을 작성하여 선언이 지정하는 대상에 연결합니다. 에이전트가 요청하는 모델(에이전트의 model 소켓이 이를 받아들이는 경우)과 LangGraph checkpointer가 상태를 보관하는 데이터 저장소가 그 대상입니다. Agent Framework 에이전트가 지정하는 MCP 서버는 모델 제공자가 호스팅된 도구로서 접근하므로, 초안은 이를 주석에 명시하고 아무것도 연결하지 않습니다. 프로그램은 Release가 지정하는 이미지에서 실행됩니다. 프로그램만이 말하는 것 — 태스크의 로직, 코드가 정의하는 도구, 코드가 구성하는 에이전트 — 은 초안의 주석과 결정에 명시되며 Component가 되지 않습니다. 이를 작성 파일로 옮기는 것은 작성자의 몫으로, 직접 하거나 레퍼런스를 읽고 엔터티를 스캐폴딩하고 검증하는 aggrega mcp를 통해 작성자 대신 작성하는 AI 어시스턴트와 함께 할 수 있습니다.
소스가 그 부분들의 실행 방식에 대해 명시하는 내용은 초안 Release에 들어갑니다. 운영 입력은 Release가 제공할 몫이므로, MCP, Compose, CrewAI, LangGraph, Google ADK, Agent Framework 임포터는 Aggregate 옆에 Release의 초안을 작성하며, 그 spec.aggregate가 Aggregate를 지정합니다. Release는 소스가 명시하는 내용 — 서버의 명령줄이나 주소, 범용 서버의 이미지와 포트, 모델의 엔드포인트 — 을 담고, 각 항목 위의 주석에는 소스가 명시하지만 초안 Component의 어떤 키도 받지 않는 내용, 예를 들어 서비스의 볼륨이나 구성의 환경을 담습니다. 어떤 소스도 명시하지 않는 것 — 프레임워크의 프로그램을 실행하는 이미지, 연결이 제시하는 자격 증명, Release의 metadata.environment와 spec.manifest — 은 운영자가 제공하도록 해당 위치의 주석에 명시되며, 빌드는 이미지, 환경, manifest 중 아직 설정되지 않은 것을 지목하며 중단됩니다. 플랫폼 초안은 Release를 작성하지 않습니다. 플랫폼 인스턴스 위의 주석이 Release가 제공하는 것 — 실행하는 이미지나 소유자 계정 같은 플랫폼 자체의 입력, 연결된 각 MCP 서버의 주소, 각 연결이 제시하는 자격 증명 — 을 명시합니다.
소스가 보유한 자격 증명 값은 제거를 요청하지 않는 한 작성된 그대로 옮겨집니다. 임포터는 소스에서 자격 증명을 담을 수 있는 모든 값을 찾아내며, 각 값은 하나의 분류에 속합니다. 형식이 자격 증명으로 표시하는 것, MCP 서버 구성의 멤버, 또는 형식이 자격 증명이 아니라고 표시하지만 그럼에도 자격 증명을 담을 수 있는 입력(예: 요청의 헤더)입니다. 기본적으로 어느 것도 비워지지 않습니다. 내용이 있는 각 값은 작성된 그대로 — 플랫폼이 담는 flow나 애플리케이션, 또는 초안 Release에 — 옮겨지며, credential-carried 경고에서 값이 아니라 위치 — 노드, 서버, 서비스 또는 에이전트, 그리고 필드 — 로 지목되고, 그 값을 비우는 설정 값이 함께 안내됩니다. empty_credentials 설정은 분류 단위로 제거를 켭니다. marked는 형식이 자격 증명으로 표시하는 것과 MCP 서버 구성의 모든 멤버를 비우고, all은 자격 증명이 아니라고 표시된 입력까지 비우며, 비워진 각 값은 credential-emptied로 보고됩니다. flow가 연결에 닿도록 초안이 기록하는 내용은 연결 구성이므로 설정과 관계없이 기록되며, 초안의 연결은 자격 증명을 담지 않습니다. 각 연결이 제시하는 자격 증명은 Release가 붙입니다. 환경 파일처럼 소스가 가리키기만 하는 파일은 읽히는 경우에도 변수 이름만 읽히며, 노드 단위로 작성된 초안은 어떤 값도 읽지 않습니다. 임포터가 찾아내는 위치 밖에 있는 것 — 사용자 정의 컴포넌트의 코드, 프롬프트 — 은 flow가 보유한 자격 증명 값에서 설명하듯, 초안을 공유하기 전에 작성자가 검토해야 합니다.
명령, 편집기, 어시스턴트는 하나의 가져오기를 실행합니다. aggrega import <file or directory>는 터미널에서 가져오기를 실행합니다. 편집기는 세션의 aggrega/import 요청을 통해, AI 어시스턴트는 aggrega mcp의 import 도구를 통해 같은 작업을 실행합니다. 세 가지 모두 워크스페이스의 카탈로그가 보유한 임포터와 컴파일러의 코어 임포터 가운데에서 같은 방식으로 임포터를 선택합니다. plugins.importer 첨부가 해당 형식을 지원한다고 알리는 임포터를 지정하면 그 임포터를, 그렇지 않으면 해당 형식을 알리는 유일한 임포터의 가장 높은 버전을 선택합니다. 한 형식에 대해 이름이 다른 두 임포터가 있고 어느 쪽도 첨부되지 않았다면 가져오기는 두 이름을 모두 밝히며 중단되며, 이는 Which importer turns a source into drafts에서 설명합니다. 세 가지 모두 초안과 함께 매핑 결정을 보고합니다. 명령은 매핑된 노드마다 표준 오류에 한 줄씩 출력하며, 해당 노드에 선택된 Component 또는 초안, 참조되었는지 초안으로 작성되었는지, 일치 등급, 그리고 임포터가 후보를 평가한 경우 최상위 후보의 점수를 밝힙니다. 편집기는 같은 줄을 표시하고, 편집기 세션의 결과와 어시스턴트의 응답은 각 결정을 전부 담습니다. 따라서 작성자는 초안을 열지 않고도, 어느 화면에서 실행했든 가져오기가 추측한 지점을 확인할 수 있습니다. --format은 인식 대신 소스 형식을 명시적으로 지정합니다. 예를 들면 langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk, agent-framework입니다. 명령은 가져오기가 생성한 엔터티와 스캐폴드 파일을 워크스페이스 루트 아래, 또는 --output-dir이 지정한 디렉터리 아래에 배치합니다. --dry-run은 쓰기를 제외한 명령의 모든 작업을 수행하며, 초안 파일을 내용으로 돌려주고 각 내용이 어느 파일용인지 밝히므로, 작성자는 작업 트리에 아무것도 커밋하기 전에 스캐폴드를 검토할 수 있습니다.
코어 임포터. 컴파일러가 제공하는 코어 임포터는 다음 형식을 형식마다 임포터 하나씩으로 읽습니다.
- Langflow — Langflow에서 내보낸 플로로, 플로를 담은 표준 라이브러리의 Langflow 플랫폼으로 초안이 작성되며, 소켓이 받는 플로의 각 부분은 그 소켓에 연결됩니다.
- Flowise — Flowise에서 내보낸 챗플로 또는 에이전트플로로, 이를 담은 표준 라이브러리의 Flowise 플랫폼으로 초안이 작성되며, 소켓이 받는 각 부분은 그 소켓에 연결됩니다.
- n8n — n8n에서 내보낸 워크플로로, 이를 담은 표준 라이브러리의 n8n 플랫폼으로 초안이 작성되며, 소켓이 받는 각 부분은 그 소켓에 연결됩니다.
- Dify — Dify에서 내보낸 애플리케이션으로, 애플리케이션을 담은, 표준 라이브러리가 조립하는 Dify 설치로 초안이 작성되며, 애플리케이션이 지정하는 모델, 도구, 지식 베이스는 Dify 내부에서 구성된 것으로 보고됩니다.
- MCP — MCP 클라이언트의 구성 또는 MCP 레지스트리 서버 설명으로, 각 서버는 표준 라이브러리의 MCP 도구 인스턴스로 초안이 작성되며, 각 서버의 명령줄, 주소 또는 이미지를 담은
Release가 함께 작성됩니다. - Compose — 인프라 형식으로, Compose 애플리케이션의 각 서비스는 이미지가 일치하는 카탈로그 Component로 초안이 작성되거나(임포터가 담고 있는, 빌드 시 표준 카탈로그의 Compose Recipes와 Components에서 생성된 표를 통해), 해당 이미지를 실행하는 범용 서버로 초안이 작성됩니다. 각 범용 서버의 이미지와 포트, 그리고 주석으로 각 서비스가 선언한 포트, 볼륨, 환경을 담은
Release가 함께 작성됩니다. - CrewAI — CrewAI 프로젝트가 구성 파일에서 선언한 에이전트로, 각각은 역할, 목표, 배경 이야기를 담고 지정한 모델에 연결된 표준 라이브러리의 CrewAI 에이전트로 초안이 작성됩니다. 프로젝트의 작업과 도구는 프로그램의 것으로 보고되고 프로그램 자체는 결코 읽지 않으며, 이를 실행하는 이미지를 운영자가 지정하도록 남겨 둔
Release가 함께 작성됩니다. - LangGraph — LangGraph 애플리케이션의 구성이 선언한 그래프로, 각각은 그래프의 임포트 경로를 담고 체크포인터가 상태를 보관하는 데이터스토어에 연결된 표준 라이브러리의 LangGraph 에이전트로 초안이 작성됩니다. 구성이 선언한 환경을 주석으로 밝히는
Release가 함께 작성되며, 그래프의 코드는 결코 읽지 않습니다. - Google ADK — Google ADK 애플리케이션의 에이전트 구성이 선언한 에이전트 트리로, 각각은 표준 라이브러리의 ADK 에이전트로 초안이 작성되며, ADK가 해당 모델의 요청을 Gemini API로 보내는 경우에는 지정한 모델에 연결됩니다. 다른 방식으로 — 예를 들어 LiteLLM 모델 문자열을 통해 — 접근하는 모델은 주석에 명시되고 그 연결은 작성자에게 맡겨집니다. 애플리케이션을 실행하는 이미지를 운영자가 지정하도록 남겨 둔
Release가 함께 작성되며, 애플리케이션의 코드는 결코 읽지 않습니다. - Agent Framework — Agent Framework 선언적 에이전트로, 지정한 OpenAI 모델에 연결된 표준 라이브러리의 Agent Framework 에이전트로 초안이 작성됩니다. 지정한 각 MCP 서버는 모델 제공자가 호스팅된 도구로서 접근하므로 주석에 기록됩니다. 모델의 엔드포인트와, 주석으로 각 서버의 주소를 담은
Release가 함께 작성되며, 애플리케이션의 코드는 결코 읽지 않습니다.
이들은 다른 임포터 플러그인과 다르지 않습니다. 형식별 매핑 로직은 코어가 아니라 이들 안에 있으며, 컴파일러의 소스에서 빌드되어 모든 컴파일러 릴리스와 함께 그 릴리스의 버전으로 게시됩니다. 어느 것도 바이너리에 컴파일되어 들어가지 않습니다. 바이너리는 각각의 Plugin 엔터티와 받아들이는 단 하나의 모듈의 다이제스트를 담으므로, 각 임포터는 카탈로그 항목 없이도 모든 워크스페이스에서 자기 형식을 처리합니다. 머신에 없는 임포터가 필요한 첫 가져오기는 워크스페이스의 기본 레지스트리에서 이를 가져와 그 다이제스트에 고정하고, pull이 가져온 플러그인을 검증하는 방식대로, 즉 해당 레지스트리의 신뢰 정책에 따른 서명과 사용하는 호스트 함수를 검증한 뒤, 워크스페이스의 콘텐츠 캐시에 보관합니다. 이후의 모든 가져오기는 거기서 읽으며, 이를 위해 네트워크에 접근하지 않습니다. 가져오기는 임포터를 고정하지 않습니다. 임포터를 위해 다른 것은 기록되지 않으며(잠금 파일 항목도, 신뢰된 플러그인 기록도 없음), pull이 이를 캐시하거나 빌드가 이를 읽지도 않습니다. 검증되지 않는 모듈은 거부되며 아무것도 보관되지 않습니다. 모듈을 가져올 수 없는 경우, 즉 워크스페이스가 오프라인이거나 레지스트리에 연결할 수 없거나 레지스트리에 모듈이 없는 경우, 가져오기는 임포터와 그 버전, 그리고 그 모듈을 머신에 두는 방법을 밝히며 중단됩니다. 선택은 여전히 워크스페이스의 몫입니다. 카탈로그가 이 형식 중 하나에 대해 다른 이름으로 보유한 임포터는 plugins.importer 첨부가 이를 지정하는 곳에서 실행되며, 코어 임포터와 같은 이름과 버전의 임포터는 코어 임포터 대신 실행됩니다.
카탈로그 시드 구성과 확장
카탈로그를 처음부터 만들 필요는 없습니다. 새 환경을 위한 Recipes와 플러그인을 시드로 구성하는 작업의 대부분은 모든 바이너리를 직접 작성하는 것이 아니라 스캐폴딩과 재사용입니다.
외부 소스를 초안 작성 파일로 가져오기. aggrega import <file or directory>는 선언적 에이전트 정의 소스(Langflow 또는 Flowise 플로, n8n 워크플로, MCP 클라이언트의 구성 또는 레지스트리 서버 설명), Compose 애플리케이션, Dify 애플리케이션, CrewAI 프로젝트가 선언하는 에이전트, LangGraph 애플리케이션의 구성이 선언하는 그래프, Google ADK 애플리케이션의 에이전트 구성이 선언하는 에이전트, 또는 Agent Framework 선언적 에이전트를 읽고, 작성자가 검토하고 마무리할 첫 초안 Aggregate 및 Component YAML을 스캐폴딩하며, MCP, Compose, CrewAI, LangGraph, Google ADK 또는 Agent Framework 소스에서는 초안 Release도 스캐폴딩합니다. 따라서 팀은 이미 가진 것을 직접 다시 작성하지 않고 그대로 이어 갈 수 있습니다. 플로의 각 노드와 Compose 애플리케이션의 각 서비스에 대해, 명령은 워크스페이스 자체 카탈로그(표준 라이브러리의 카탈로그뿐 아니라 엔터프라이즈 카탈로그도 포함)의 Components를 모델을 사용하지 않는 결정적 신뢰도 모델로 점수를 매기고, 그 결정(검토한 후보, 부여한 등급, 내린 선택)을 검토 가능한 힌트로 기록하며, 이는 명령, 편집기, 어시스턴트가 모두 보고합니다. 신뢰도가 높은 일치는 운영자가 옵트인하면 카탈로그 참조로 작성될 수 있으며, 이는 항상 조용한 재작성이 아니라 작성자가 승인하는 명시적이고 되돌릴 수 있는 제안입니다. 카탈로그가 얻는 모든 Component는 다음 가져오기가 검토하는 후보가 됩니다. 형식별 매핑 지능은 importer 플러그인에 있습니다. 컴파일러 자체의 Langflow, Flowise, n8n, MCP, Compose, Dify, CrewAI, LangGraph, Google ADK, Agent Framework importer는 모든 워크스페이스에서 해당 형식을 처리하며, 처음 사용할 때 가져와 검증됩니다. 카탈로그는 해당 형식을 알리는 importer 플러그인을 보유함으로써 형식을 추가합니다. 디렉터리 소스는 해당 importer가 선언하는 파일 패턴을 통해 읽힙니다. Langflow, Flowise, n8n, Dify, Agent Framework importer는 패턴을 선언하지 않으며 각각 내보낸 파일 하나 또는 선언적 에이전트 하나를 읽습니다. 반면 MCP importer는 디렉터리가 보유한 클라이언트 구성을, Compose importer는 디렉터리의 Compose 파일을 Compose가 병합하는 방식대로 병합하여, CrewAI importer는 프로젝트의 선언을(프로그램은 읽지 않음), LangGraph importer는 애플리케이션의 구성을(코드나 환경 파일은 읽지 않으며, 환경 파일의 이름은 attachment가 해당 파일을 넘겨줄 때만 읽음), Google ADK importer는 애플리케이션의 루트 에이전트 구성을(코드나 환경 파일은 읽지 않으며, 하위 에이전트의 구성은 attachment가 넘겨줄 때 읽음) 읽습니다. 이 구성은 ADK가 실험적이라고 명시한 구성으로, 그 에이전트는 기본적으로 Gemini 모델을 사용하며 다른 제공자의 모델에는 ADK 자체 클래스를 통해 이름으로, 또는 LiteLLM 모델 문자열을 통해 연결합니다.
대부분의 플러그인 작업은 컴파일된 코드가 아니라 템플릿입니다. 상당수의 기능은 정적 사이드카, 환경 변수 또는 레이블만 주입합니다. 즉 조건부 로직이 없는 단순한 JSONPatch입니다. 선언적 JSONPatch 템플릿을 with 입력으로 받도록 한 번 작성된 구성 가능한 패처 플러그인 하나로, 기능마다 고유한 컴파일된 바이너리 없이 이러한 일반적인 경우를 처리할 수 있습니다. 작성자는 템플릿을 작성하며, 많은 CRD 스타일 대상에서는 valuesMapping 템플릿(흔히 MappingLibrary 항목의 공유 조각을 참조함)만으로도 충분합니다. 목적에 맞게 작성된 PDK 플러그인은 실제로 조건부인 나머지 경우를 위한 것입니다.
기존 도구 참조하기. 새 플러그인 로직을 작성할 때 작성자는 기존 오픈 소스 도구의 공개 문서화된 출력 형태(해당 도구가 내보내는 것으로 알려진 CRD, 패치 또는 템플릿의 구조)를 새 플러그인이 생성해야 하는 대상 형태의 참고 자료로 삼을 수 있으며, 이때 각 프로젝트의 라이선스를 존중해야 합니다. 사이드카 주입 웹훅, 상위 수준 구성 요소 라이브러리, 오퍼레이터 CRD 생성기, 트레이트 또는 컴포지션 카탈로그는 모두 비슷한 FeatureRecipe나 플러그인이 내보내야 하는 것과 밀접하게 대응하는 출력 구조를 공개합니다. 목표는 어떤 프로젝트의 구현을 복사하는 것이 아니라 잘 알려진 출력 계약에 맞추는 것입니다.