코어 임포터
컴파일러 저장소는 소스 형식마다 하나씩, 자체 임포터 플러그인 10개를 빌드하여 컴파일러 릴리스마다 함께 게시합니다.
| Plugin | 담당 | 읽는 내용 |
|---|---|---|
importer/langflow | import:langflow | Langflow에서 JSON으로 내보낸 플로 |
importer/flowise | import:flowise | Flowise에서 JSON으로 내보낸 chatflow 또는 agentflow |
importer/n8n | import:n8n | n8n에서 JSON으로 내보낸 워크플로 |
importer/mcp | import:mcp | MCP 클라이언트의 구성(.mcp.json, claude_desktop_config.json, .vscode/mcp.json 또는 .cursor/mcp.json) 또는 MCP 레지스트리 서버 설명 server.json(JSON 형식) |
importer/compose | import:compose | Compose 애플리케이션(compose.yaml, docker-compose.yml 및 해당 오버라이드 파일)(YAML 형식) |
importer/dify | import:dify | Dify에서 해당 DSL로 내보낸 애플리케이션(YAML 형식) |
importer/crewai | import:crewai | CrewAI 프로젝트가 선언하는 에이전트와 태스크: YAML 형식의 config/agents.yaml 및 config/tasks.yaml, 또는 주석이 포함된 JSON 형식의 crew.jsonc 및 agents/<name>.jsonc, 혹은 그 엄격한 JSON 표기인 crew.json 및 agents/<name>.json |
importer/langgraph | import:langgraph | LangGraph 애플리케이션의 구성 langgraph.json(JSON 형식), 그리고 이 구성이 지정하는 환경 파일에서는, 임포트가 with.sources 아래로 그 파일을 전달받은 경우 변수 이름만 |
importer/google-adk | import:google-adk | Google ADK 기반 애플리케이션의 Agent Config 파일에 선언된 에이전트(root_agent.yaml 및 그 하위 에이전트가 지정하는 구성)(YAML 형식) |
importer/agent-framework | import:agent-framework | Microsoft Agent Framework 선언적 에이전트, 즉 이름과 관계없이 kind가 Prompt인 문서(YAML 형식) |
각 임포터는 컴파일러 자체 소스로 빌드되고 컴파일러 버전이 찍히므로, X.Y.Z 컴파일러와 함께
릴리스된 임포터는 버전 X.Y.Z를 보고하며, 해당 Plugin 엔터티에도 이 버전이 기록됩니다. 임베디드 플러그인에 나열된 플러그인과 달리, 어느 것도 바이너리에
컴파일되어 들어가지 않습니다. 바이너리는 각 임포터의 Plugin 엔터티와, 그에 대해 허용하는 단 하나의 모듈의 다이제스트를 담고 있으므로, 각 임포터는 카탈로그에 항목이 없어도 모든 워크스페이스에서 자신의 형식을 담당합니다.
10개 모두 Go 키트의 임포터 패키지 github.com/aggrega-ai/aggrega-pdk/go/pkg/importer를 기반으로 빌드됩니다. Langflow, Flowise, n8n 임포터의 경우, 형식과 관계없이 임포터가 하는 모든 일, 즉 각 노드에 대해 워크스페이스 카탈로그의 Components를 점수화하고, 기존 것을 참조할지 새로 초안을 작성할지 결정하고, 초안을 배치하고, 담고 있는 자격 증명 값을 그대로 옮기거나 설정에 따라 비워서 쓰고, 초안을 작성하고 아래 설정을 읽는 일은 그 패키지가 맡으며, 형식을 읽는 일과 플로가 실행되는 플랫폼을 아는 일만 각 임포터에 고유합니다. MCP 임포터는 서버마다 하나의 Component 인스턴스 초안을 작성하므로 아무것도 점수화하지 않습니다. MCP 임포터에서 설명하듯이, 이 임포터는 읽는 설정에 대한 패키지의 해석, 자격 증명 값에 대한 결정, 그리고 초안의 이름과 설명을 정하는 관례를 패키지와 공유합니다. Compose 임포터에서 설명하듯이, Compose 임포터는 일치하는 각 서비스를 플로 임포터가 노드를 결정하는 방식대로 같은 패키지를 통해 결정하고, 초안도 그들과 같이 렌더링하며, 나머지는 MCP 임포터와 같이 공유합니다. Dify 임포터에서 설명하듯이, Dify 임포터는 표준 라이브러리가 조립하는 Dify 설치를, 애플리케이션을 담아, 같은 패키지의 플랫폼 초안 중 설치 전체인 플랫폼에 대해 취하는 형태를 통해 초안으로 작성합니다. CrewAI 임포터에서 설명하듯이, CrewAI 임포터는 프로젝트가 선언하는 에이전트마다 표준 라이브러리의 CrewAI 에이전트 인스턴스 초안을 작성하고, 지정된 모델에 연결하며, 나머지는 MCP 임포터와 같이 공유합니다. LangGraph 임포터에서 설명하듯이, LangGraph 임포터는 애플리케이션 구성이 선언하는 그래프마다 표준 라이브러리의 LangGraph 에이전트 인스턴스 초안을 작성하고, 체크포인터가 상태를 보관하는 데이터스토어에 연결하며, 나머지는 MCP 임포터와 같이 공유합니다. Google ADK 임포터에서 설명하듯이, Google ADK 임포터는 애플리케이션 구성이 선언하는 에이전트 트리마다 표준 라이브러리의 ADK 에이전트 인스턴스 초안을 작성하고, ADK가 Gemini API로 요청을 보내는 경우에는 트리가 지정하는 모델에 연결하며, 나머지는 MCP 임포터와 같이 공유합니다. Agent Framework 임포터에서 설명하듯이, Agent Framework 임포터는 선언적 에이전트마다 표준 라이브러리의 Agent Framework 에이전트 인스턴스 초안을 작성하고, 지정된 OpenAI 모델에 연결하며(지정된 각 MCP 서버는 주석으로 작성됩니다. 모델의 공급자가 호스팅된 도구로서 이에 접근하기 때문입니다), 나머지는 MCP 임포터와 같이 공유합니다. 임포터 소켓의 작동 방식과 전달받는 내용은 임포터 소켓에서 설명합니다.
이 페이지는 각 임포터가 무엇을 읽고 무엇을 초안으로 작성하는지에 대한 참조입니다. 자신의 프로젝트를 가져와 결과를 빌드하려면 가져오기에서 시작하십시오. 이 문서는 형식별로 하나씩 프로젝트를 소스에서 빌드까지 안내합니다.
임포트가 코어 임포터를 얻는 방법
aggrega import, 편집기 세션의 aggrega/import 메서드, 어시스턴트의 import 도구는 모두 같은 방식으로 코어 임포터를 얻습니다. 머신이 이미 그 모듈을 워크스페이스의 콘텐츠 캐시에 보유하고 있으면, 임포트는 그곳에서 모듈을 읽으며 이를 위해 네트워크를 사용하지 않습니다. 그렇지 않으면 그 모듈이 필요한 첫 임포트가 워크스페이스의 기본 레지스트리에서 컴파일러의 버전으로 모듈을 가져온 뒤 다음을 수행합니다.
- 바이너리가 보유한 다이제스트에 모듈을 대조하여, 컴파일러의 릴리스가 게시한 모듈만 실행되도록 합니다.
- pull이 가져오는 플러그인을 검증하는 방식대로 모듈을 검증합니다. 즉 해당 레지스트리의 신뢰 정책에 따라 서명을 검증하고, 모듈이 사용하는 호스트 함수를 그 Plugin 엔티티가 기록한 호스트 함수와 대조합니다.
- 모듈을 워크스페이스의 콘텐츠 캐시에 보관하며, 이것이 모듈을 위해 기록되는 유일한 것입니다. 임포트는 어떤 임포터도 고정하지 않으므로 lockfile도, 신뢰된 플러그인의 기록도 작성되지 않습니다.
이후의 모든 임포트는 콘텐츠 캐시에서 모듈을 읽습니다. 검증되지 않는 모듈은 거부되며, 아무것도 보관되지 않습니다. 워크스페이스로 표시되지 않은 폴더에는 모듈을 보관할 콘텐츠 캐시가 없으므로, 그곳에서는 가져오기가 거부되며 해당 폴더와 함께 워크스페이스를 지정하거나 그 폴더를 워크스페이스로 만드는 방법을 알려 줍니다. 모듈은 카탈로그 폴더에서 같은 이름의 다른 버전 Plugin 엔티티 옆에 있는 것을 읽지 않습니다. 그 모듈은 다른 엔티티에 속하기 때문입니다.
모듈을 가져올 수 없는 경우 import는
A plugin’s .wasm is not on this machine (플러그인의 .wasm 파일이 이 머신에 없음)
오류로 중단되며, 해당 importer와 그 버전을 명시하고 그 모듈을 머신에 두는 방법을 안내합니다.
- 네트워크를 사용할 수 있는 상태에서 임포트를 한 번 실행합니다. 워크스페이스가 오프라인이거나 레지스트리에 접근할 수 없었던 경우에 해당합니다. 그 실행이 모듈을 가져오며, 이후의 모든 실행은 오프라인으로 이루어집니다.
- 카탈로그 폴더에서 해당 임포터의 해당 버전 Plugin 엔티티 옆에 모듈을 둡니다. 파일 이름은 메시지가 알려 주는 이름을 사용합니다. Langflow 임포터라면
importer--langflow.wasm입니다. 코어 임포터와 같은 이름과 버전의 카탈로그 엔티티는 코어 임포터 대신 실행되며, 그 모듈은 엔티티 옆에서 읽힙니다. 옆에 모듈이 없는 그러한 엔티티는 대신 실행되지 않으며, 코어 임포터는 위에서 설명한 대로 얻습니다. 레지스트리가 모듈을 보유하지 않거나 워크스페이스가 기본 레지스트리를 지정하지 않은 경우, 메시지가 안내하는 해결책은 이것 하나뿐입니다.
직접 작성한 importer와 함께 있을 때 어느 것이 실행되는가
core importer는 워크스페이스의 카탈로그가 보유한 importer와 나란히 후보가 되며, 모든 importer가 선택되는 규칙을 따릅니다. 이 규칙은 Which importer turns a source into drafts (어떤 importer가 소스를 초안으로 변환하는가)에서 설명합니다.
- 하나의 이름 안에서는 가장 높은 버전, 또는
plugins.importer항목이 지정한 버전이 실행됩니다. - 카탈로그가
langflow,flowise,n8n,mcp,compose,dify,crewai,langgraph,google-adk또는agent-framework에 대해 다른 이름의 importer를 보유하고 있으면 두 importer가 해당 형식을 알리게 되며, 둘 중 어느 것도 연결하지 않은 import는 두 importer의 이름을 함께 표시하며 A parse or import format is advertised by more than one plugin (parse 또는 import 형식을 둘 이상의 플러그인이 알림)에 따라 거부됩니다. 원하는 importer를 지정하는plugins.importer항목으로 이를 해결할 수 있습니다. - 카탈로그가 코어 임포터와 같은 이름과 버전으로 보유하고 그 엔터티 옆에 모듈이 있는 임포터가 실행되며, 그 모듈은 그곳에서 읽힙니다.
- 코어 임포터의 이름을 가지면서 카탈로그 폴더에서 옆에 모듈이 없는 Plugin 엔터티 — 예를 들어 어떤 릴리스가 게시한 임포터를 기록하는 카탈로그 체크아웃에 있는 것 — 는 그 모듈을 다른 어디에서도 읽지 않으므로 어떤 가져오기도 실행할 수 없는 엔터티입니다. 따라서 실행 후보가 아니지만, 그것이 기록하는 시그니처는 여전히 소스 인식에 참여합니다. 컴파일러 자체의 버전에서는 코어 임포터가 대신 실행됩니다. 그 밖의 버전에서는 더 오래되었든 더 새롭든 건너뛰어지고, 실행할 수 있는 임포터들 사이에서 선택이 이루어집니다 — 다만
plugins.importer항목이 정확히 그 버전을 지정하거나, 실행할 수 있는 그 이름의 임포터 중 요청된 형식을 알리는 것이 없는 경우(엔터티가 컴파일러 자체 임포터가 기록하지 않는 형식을 기록하는 경우처럼)는 예외입니다. 그러면 위 규칙에 따라 후보로 남으며, 그것을 선택한 가져오기는 모듈을 둘 폴더를 알려 주며 중단됩니다.
카탈로그 자체의 임포터 중 어느 것이 선택되든, 그 모듈은 자신의 엔터티 옆에서 자신의 버전으로 읽힙니다. 다른 버전의 같은 이름 엔터티 옆에 놓인 모듈은 그 엔터티에 속합니다.
소스를 인식하는 방법
--format으로 형식을 지정하지 않은 가져오기는 각 임포터가
선언하는 시그니처로 인식됩니다:
- Langflow — JSON으로 파싱되고
data.nodes에 배열을 가진 소스. - Flowise — JSON으로 파싱되고,
nodes와edges에 배열을 가지며,data.nodes에는 아무것도 없는 소스. - n8n — JSON으로 파싱되고,
nodes에 배열을,connections에 객체를 가지며,edges나data.nodes에는 아무것도 없는 소스. - MCP — JSON으로 파싱되고, 이름이
.mcp.json,claude_desktop_config.json또는.cursor/mcp.json이며mcpServers에 객체를 가진 소스; Visual Studio Code가 읽는 방식대로 주석이 있는 JSON으로 파싱되고, 이름이.vscode/mcp.json이며servers에 객체를 가진 소스; 또는 이름과 관계없이 JSON으로 파싱되고$schema가https://static.modelcontextprotocol.io/schemas/로 시작하는 텍스트인 소스, 즉 레지스트리 서버 설명. 이름은 가져오기에 전달된 경로의 끝과 대조되므로project/.vscode/mcp.json은 인식되지만,.vscode내부에서 전달된mcp.json이나 다른 이름의 클라이언트 파일은--format mcp를 지정하여 가져옵니다. - Compose — YAML로 파싱되고, Compose가 기본적으로 Compose 파일이나 그 오버라이드
파일로 읽는 이름 —
compose.yaml,compose.yml,docker-compose.yml,docker-compose.yaml,compose.override.yml,compose.override.yaml,docker-compose.override.yml또는docker-compose.override.yaml— 을 가지며,services에 객체를 가진 소스. 다른 이름의 Compose 파일은--format compose를 지정하여 가져옵니다. - Dify — 이름과 관계없이 YAML로 파싱되고,
kind에 텍스트app을 가지며, Dify가 내보내는 모든 애플리케이션처럼app.mode와version에 값을 가진 소스. - CrewAI — YAML로 파싱되는
config/agents.yaml또는config/tasks.yaml이라는 이름의 소스, 주석이 있는 JSON으로 파싱되고agents에 목록을 가진crew.jsonc또는crew.json이라는 이름의 소스, 또는 주석이 있는 JSON으로 파싱되고role에 값을 가진agents/<name>.jsonc또는agents/<name>.json이라는 이름의 소스. 클래식 프로젝트는 에이전트와 태스크를 작성자가 고른 이름으로 키를 지정하므로, 그 두 파일은 이름만으로 구별됩니다. - LangGraph — JSON으로 파싱되고
graphs에 객체를 가진langgraph.json이라는 이름의 소스; 또는 이름과 관계없이 JSON으로 파싱되고,graphs에 객체를 가지며,$schema가 LangGraph가 구성용으로 게시하는 스키마인 텍스트https://langgra.ph/schema.json인 소스. 스키마를 지정하지 않은 다른 이름의 구성은--format langgraph를 지정하여 가져옵니다. 어떤 임포터의 시그니처도 환경 파일을 지정하지 않으므로, 디렉터리를 인식할 때 환경 파일은 열리지 않습니다. - Google ADK — YAML로 파싱되고, LlmAgent의 구성처럼
name과instruction에 값을 가지거나, 다른 모든 에이전트의 구성처럼agent_class에 텍스트를,name에 값을 가진root_agent.yaml이라는 이름의 소스. 다른 이름의 구성은--format google-adk를 지정하여 가져옵니다. 하위 에이전트의 구성은 어떤 이름이든 될 수 있으므로 어떤 시그니처도 이를 지정하지 않으며, 따라서 디렉터리를 인식할 때root_agent.yaml외의 YAML 파일은 열리지 않습니다. - Agent Framework — 이름과 관계없이 YAML로 파싱되고, 모델을 지정하는 선언적 에이전트처럼
kind에 텍스트Prompt를,model에 객체를 가진 소스; Agent Framework는 애플리케이션이 지정하는 어떤 파일에서든 선언적 에이전트를 로드하므로, 시그니처는 파일을 지정하지 않습니다. 모델을 지정하지 않거나, kind를 다른 대소문자로 또는Agent로 쓴 선언적 에이전트는--format agent-framework를 지정하여 가져옵니다.
이 중 두 가지와 일치하는 소스는 두 형식을 모두 지명하며 거부되고, --format으로 그중 하나를 지정하면 가져올 수 있습니다. Langflow, Flowise, n8n, LangGraph 임포터는 소스를 parse:json을 제공하는 파서로 읽고, MCP 임포터는 서버를 servers 아래에 나열하는 구성을 parse:jsonc를 제공하는 파서로, 그 밖의 모든 소스를 parse:json을 제공하는 파서로 읽으며, Compose, Dify, Google ADK, Agent Framework 임포터는 parse:yaml을 제공하는 파서로 읽고, CrewAI 임포터는 클래식 프로젝트의 파일을 parse:yaml을 제공하는 파서로, 그 밖의 파일을 parse:jsonc를 제공하는 파서로 읽습니다. 이 파서는 워크스페이스의 카탈로그가 제공하는 경우 그 파서이고, 그렇지 않으면 컴파일러 자체가 해당 구문용으로 내장한 파서입니다(Embedded plugins 참조). 따라서 이들 중 어느 것을 통한 가져오기든 카탈로그에 파서가 필요하지 않으며, 파서를 위해 아무것도 가져오지 않습니다. 카탈로그가 파서를 제공하면 그 파서가 사용되고, 컴파일러의 파서는 관여하지 않습니다. Langflow, Flowise, n8n, Dify, Agent Framework 임포터는 파일 패턴을 선언하지 않으므로 각각 하나의 파일을 읽으며, 이들 중 어느 것을 통한 디렉터리 가져오기는 거부됩니다. MCP 임포터는 네 가지 클라이언트 파일 이름을 선언하므로 디렉터리는 그 안에 있는 클라이언트 구성을 통해 읽힙니다. Compose 임포터는 여덟 가지 Compose 파일 이름을 선언하므로 디렉터리는 그 안에 있는 Compose 파일을 통해 읽힙니다. CrewAI 임포터는 프로젝트 선언의 여섯 가지 이름을 선언하므로 프로젝트 디렉터리는 그 선언만을 통해 읽히고 그 밖의 것은 읽히지 않습니다. LangGraph 임포터는 langgraph.json을 선언하므로 애플리케이션 디렉터리는 그 구성만을 통해 읽히며, 코드나 환경 파일은 절대 읽히지 않습니다. Google ADK 임포터는 root_agent.yaml을 선언하므로 애플리케이션 디렉터리는 그 루트 구성만을 통해 읽히며 — 하위 에이전트가 지정하는 구성은 첨부의 with.sources를 통해서만 임포터에 전달됩니다 — 코드나 환경 파일은 절대 읽히지 않습니다. 파일을 지정하지 않는 시그니처 — Langflow, Flowise, n8n 임포터의 시그니처, 레지스트리 서버 설명에 대한 MCP 임포터의 시그니처, 스키마를 지정하는 구성에 대한 LangGraph 임포터의 시그니처, Dify 임포터와 Agent Framework 임포터의 시그니처 — 는 단독으로 가져오는 모든 파일에 적용됩니다. 형식을 지정하지 않은 가져오기는 그러한 파일을 어떤 임포터를 위한 것이든 시험 삼아 JSON으로, 그리고 YAML로 같은 파서를 통해 읽습니다 — 컴파일러가 둘 다 내장하므로 어느 쪽을 위해서도 아무것도 가져오지 않습니다. 주석이나 후행 쉼표가 있는 파일은 JSON으로 파싱되지 않으므로 JSON을 읽는 어떤 시그니처도 이를 인식하지 않습니다. CrewAI 임포터의 crew.jsonc, agents/<name>.jsonc 및 그 .json 표기에 대한 시그니처와 MCP 임포터의 .vscode/mcp.json에 대한 시그니처는 주석이 있는 JSON을 읽으며, 카탈로그가 파서를 제공하지 않는 경우 컴파일러가 해당 구문용으로 내장한 파서를 통해 읽습니다.
파서가 거부하는 소스 — Langflow, Flowise, n8n, LangGraph 임포터의 경우
JSON이 아닌 소스, MCP 임포터의 경우 주석이 있는 JSON이 아니거나, 서버를
servers 아래에 나열하지 않는 한 JSON이 아닌 소스, Compose, Dify, Agent Framework 임포터의 경우
YAML이 아닌 소스, CrewAI 임포터의 경우 YAML이 아니거나 주석이 있는 JSON이 아닌 선언, 그리고
Google ADK 임포터의 경우 YAML이 아닌 구성 —
는 가져오기를
parse-failed로 중단시키며, 그 메시지에는 파서 자체의 사유가 담깁니다. 형식을 지정해도 이는 달라지지 않습니다.
임포터는 소스의 트리를 요청하고, 파서의 거부가 임포터가 받는 응답입니다.
초안의 이름을 정하는 방법
모든 임포터는 초안으로 작성하는 Aggregate와, Release도 초안으로 작성하는 경우 그 옆의 Release에 <target_namespace>/<name>이라는 이름을 붙입니다. 첫 부분은 target_namespace 설정이며, 다른 값을 설정하지 않으면 imported입니다. <name>은 다음 중 비어 있지 않은 첫 번째 항목입니다:
-
소스가 스스로에게 붙인 이름으로, 해당 형식이 이름을 선언하는 필드에서 읽습니다:
임포터 읽는 이름 importer/langflow플로의 nameimporter/flowise없음: 내보낸 파일에는 자체 이름이 없습니다 importer/n8n워크플로의 nameimporter/mcp레지스트리 서버 설명의 name; 클라이언트의 구성에는 이름이 없습니다importer/compose프로젝트의 최상위 name. Compose가 파일을 병합하는 방식대로, 재정의 파일의 이름이 그 파일이 재정의하는 파일의 이름 대신 사용됩니다importer/difyapp아래에 있는 애플리케이션의nameimporter/crewaicrew.jsonc또는crew.json에 있는 크루의name;config/agents.yaml과config/tasks.yaml에는 이름이 없습니다. 클래식 프로젝트는 크루의 이름을 프로그램 안에서 정하기 때문입니다importer/langgraph구성이 선언하는 그래프의 ID. 구성에는 자체 이름이 없기 때문입니다 importer/google-adk루트 에이전트의 nameimporter/agent-framework에이전트의 name;displayName은 읽지 않습니다 -
가져오기에 전달된 디렉터리의 이름 전체 —
my.project는 마침표를 유지하며my-project로 쓰입니다 — 로, Compose가 프로젝트에 그것이 들어 있는 디렉터리의 이름을 붙이는 것과 같습니다.aggrega import .는 자신이 실행되는 디렉터리를 가리킵니다; -
가져오기에 단독으로 전달된 파일의 이름(확장자 제외);
-
flow.
여러 소스(여러 Compose 프로젝트, 구성, 에이전트 트리 또는 서버, 혹은 여러 그래프를 선언하는 하나의 구성)로 만든 초안은 모든 소스가 스스로 이름을 붙이고 그 이름이 모두 같은 표기일 때만 그 이름을 사용하며, 그렇지 않으면 다음 항목을 사용합니다. 이름은 소문자로 쓰며, ASCII 문자와 숫자가 아닌 문자의 연속은 각각 하이픈 하나로 쓰고, 양 끝의 하이픈은 제거합니다. Basic Prompting은 basic-prompting으로, SupportAgent는 supportagent로 쓰입니다. 같은 소스는 가져올 때마다 같은 방식으로 이름이 붙습니다. 가져오기가 타깃용으로 초안을 작성하는 Manifest는 Release의 이름을 사용하며, Release가 초안으로 작성되지 않으면 Aggregate의 이름을 사용합니다. 이는 타깃이 추가하는 것에서 설명합니다.
Langflow 임포터가 읽는 것
- 플로의 최상위
data객체 아래에 있는 노드와 에지, 즉data.nodes와data.edges입니다. - 각 노드에 대해, 노드의
data.type에서 그 타입을 읽고, 값이type을 지닌 객체인data.node.template항목들에서 그 필드를 읽습니다. 템플릿의 다른 항목은 필드가 아닙니다. - 객체가
password: true를 지닌 필드는 자격 증명 슬롯으로 초안이 작성되고, 그 밖의 모든 필드는 값 필드로 작성됩니다. 필드의 이름은 아무 역할도 하지 않으며, 노드를 Component로 초안 작성할 때는 어떤 필드의 값도 읽지 않습니다. - 캔버스에 고정된 메모, 즉 타입이
noteNode인 노드는 가져오지 않으며, 가져오지 않는 노드로 향하는 에지는 버려집니다. - 플로를 실행하는 플랫폼의 초안을 작성할 때는 플로에서 다음도 읽습니다. 최상위
id,password: true로 표시된 각 필드의 값, MCP Tools 노드의mcp_server필드(그 필드가 지정하는 MCP 서버와 그 서버의 구성) 또는 대신 서버를 담아 두는 필드들, Langflow가 자격 증명이 아니라고 표시하지만 자격 증명을 담을 수 있는 각 입력( 플로가 보유한 자격 증명 값에 나열된 것), 노드가 모델을 지정하는 필드와 그 모델이 실행되는 모델 제공자, 그리고 노드가 파트의 주소와 키에 도달하는 데 쓰는 필드(임포터가 다시 작성합니다)입니다. 각각이 어떻게 되는지는 초안으로 작성되는 것에서 설명합니다.
Flowise 임포터가 읽는 내용
- 플로의 최상위 수준에 있는 노드와 엣지, 즉
nodes와edges입니다. - 각 노드에 대해, 노드의
data.name에서 타입을 읽고,data.inputParams의 항목 중type이credential인 항목에서 해당name으로 자격 증명 슬롯을 읽으며,data.inputs의 키에서 값 필드를 읽습니다. 이때data.inputAnchors가 지정하는 키(다른 노드가 연결되어 들어오는 곳으로, 둘 사이의 엣지가 이를 기록합니다)와 자격 증명은 제외합니다. - 노드를 Component로 초안 작성할 때는 어떤 필드의 값도 읽지 않으며, 자격 증명의 이름은 그것이 자격 증명이 되는지에 아무런 영향을 주지 않습니다.
- 캔버스에 고정된 메모, 즉
stickyNote타입의 노드는 임포트되지 않으며, 임포트되지 않는 노드로 향하는 엣지는 삭제됩니다. - 챗플로를 실행하는 플랫폼을 초안 작성할 때는 챗플로에서 다음 항목도 읽습니다. UUID인 경우의 최상위
id, 노드가data.credential에 보관하는 자격 증명, 노드의inputParams가password타입으로 선언하는 각 입력의 값, 노드 입력 중의FLOWISE_CREDENTIAL_ID와 그 입력의 어느 깊이에 있든 구성 객체 안의credential또는FLOWISE_CREDENTIAL_ID, 노드의mcpServerConfig입력에 있는 서버 구성, 플로가 보유한 자격 증명 값에 나열된 대로 Flowise가 자격 증명이 아니라고 표시하지만 자격 증명을 담을 수 있는 각 입력과 에이전트플로의 구성이 선택하는 모델이나 도구를 지정하는 멤버, 노드의modelName입력, 그리고 OpenAI 노드의 Base Path, 즉basepath입력입니다. 각 항목이 어떻게 되는지는 초안으로 작성되는 내용에서 설명합니다.
n8n 임포터가 읽는 내용
- 내보낸 파일의 최상위 수준에 있는 워크플로의
nodes와connections입니다. - 각 노드에 대해, 노드를 식별하는
name(n8n의 연결은 연결하는 노드를 이름으로 지정하며, 한 워크플로의 노드 이름은 고유합니다)과, 패키지를 포함해 전체가 기록된type을 읽습니다. 예를 들어@n8n/n8n-nodes-langchain.lmChatOpenAi또는n8n-nodes-base.httpRequest입니다. 이름이 없는 노드는id로 식별됩니다. - 워크플로가 나열하는 각 연결은 유형에 관계없이, 연결이 떠나는 노드에서 들어가는 노드로 향하는 하나의 엣지입니다.
main연결은 한 노드에서 다음 노드로 데이터를 전달하고, AI 연결 (ai_languageModel,ai_tool,ai_vectorStore,ai_embedding,ai_memory등)은 연결이 떠나는 노드가 나타내는 모델, 도구, 저장소 또는 메모리를 연결이 들어가는 노드에 넘겨줍니다. 어느 경우든 연결이 들어가는 노드가 연결이 떠나는 노드를 소비합니다. - 노드의
credentials가 지정하는 각 자격 증명 유형과, n8n이 비밀번호로 표시하는 각 최상위 매개변수는 자격 증명 슬롯으로 초안 작성되며, 노드의 그 밖의 각 최상위 매개변수는 값 필드입니다. 노드를 Component로 초안 작성할 때는 어떤 필드의 값도 읽지 않습니다. - 캔버스에 고정된 메모, 즉
n8n-nodes-base.stickyNote유형의 노드는 가져오지 않으며, 가져오지 않는 노드로 향하는 연결은 삭제됩니다. - 워크플로를 실행하는 플랫폼을 초안 작성할 때는 워크플로에서 다음도 읽습니다. 최상위
id, 노드가 선택하는 각 자격 증명, n8n이 비밀번호로 표시하는 각 매개변수, MCP 클라이언트 노드가 호출하는 주소, 흐름이 보유한 자격 증명 값에 나열된 대로 워크플로가 구성하는 요청과 함께 노드가 보내는 헤더와 쿼리 매개변수, 그리고 모델 노드가 모델을 지정하는 매개변수입니다. 각각이 어떻게 되는지는 초안 작성 내용에서 설명합니다.
초안으로 작성하는 내용
각 노드는 importer 소켓에서 설명하는 대로 워크스페이스 자체 카탈로그의 Components와만 비교되며, 각 importer는 해당 형식의 일반적인 노드 유형(채팅 및 임베딩 모델, 검색, HTTP 요청, 그리고 Langflow의 경우 core/ai-tool/mcp에 매핑되는 MCP Tools 노드 MCPTools)을 표준 라이브러리 Components에 매핑하는 짧은 표를 가지고 있습니다. Langflow의 표는 또한 Language Model 컴포넌트인 LanguageModelComponent, 즉 Langflow의 스타터 흐름이 호출하는 채팅 모델을 Langflow 플랫폼의 모델 연결이 제공하는 모델인 core/ai-model/openai에 매핑합니다. 이 노드는 provider 필드가 지정하는 모델 제공자(기본값은 OpenAI)에서 실행되며, 다른 제공자를 지정하는 노드는 어떤 노드가 파트가 되는가에서 설명하듯이 해당 연결에 배선되지 않습니다. n8n importer의 표는 n8n의 채팅 및 임베딩 모델, MCP 클라이언트 도구(core/ai-tool/mcp로), HTTP 요청 도구, SerpApi 도구, Qdrant, PGVector, Chroma, Milvus, Weaviate 벡터 스토어, 그리고 Postgres 및 Redis 채팅 메모리를 매핑합니다. n8n이 워크플로 자체 안에서 실행하는 노드(에이전트, 체인, 트리거, 워크플로가 자체 프로세스에 유지하는 메모리, 코드 도구)는 워크플로 고유의 것이며, 어떤 행도 이를 매핑하지 않습니다. 표의 행은 워크스페이스의 카탈로그가 그 행이 지정하는 Component를 보유한 경우에만 일치로 계산됩니다. 명령은 매핑한 각 노드에 대해 선택한 대상, 일치 등급, 최상위 후보의 점수를 나타내는 한 줄을 보고하고, 고유한 Component를 부여하지 않은 노드에 대해서는 made no choice for <node id> (<node type>)라는 줄을 보고합니다. 초안으로 작성되지 않고 카탈로그 Component를 참조하는 노드에는 고유한 파일이 없으며, 초안 Aggregate가 해당 Component를 지정합니다.
초안의 구성 방식은 layout 설정이 결정합니다. 기본값인 platform은 플로를 실행하는 플랫폼을 초안으로 작성하여 내보낸 그대로의 플로를 담고, 플랫폼의 소켓이 받는 플로의 각 부분(표준 라이브러리의 플랫폼에서는 모델, MCP 서버 또는 HTTP로 접근하는 기타 도구, 벡터 스토어)에만 고유한 Component를 부여합니다. nodes는 모든 노드를 각각 고유한 Component로 초안 작성합니다.
플로를 담는 플랫폼
기본적으로 가져오기는 다음을 작성합니다.
aggregate.yaml— 초안의 이름을 정하는 방법에서 설명하는 대로 플로의 이름을 딴 초안 Aggregate입니다. 여기에는 플로를 실행하는 플랫폼의 인스턴스 하나가 들어 있으며(Langflow 플로의 경우 키langflow아래의core/ai-agent/langflow, Flowise 플로의 경우 키flowise아래의core/ai-agent/flowise, n8n 워크플로의 경우 키n8n아래의core/ai-agent/n8n), 이 인스턴스는 같은 이름의 카탈로그 Component를 참조합니다. 인스턴스는values.flow_definition에 플로를 담고 식별자 값(Langflow에서는flow_id, Flowise에서는chatflow_id, n8n에서는workflow_id)으로 플로를 지정합니다. 플로의 각 부분은 그 옆에 별도의 항목으로 존재하며, 인스턴스의uses아래에서 플랫폼에 연결됩니다.release.yaml— 같은 이름의 초안 Release로, 해당 Aggregate를 지정하고, 플랫폼 항목과 각 파트 항목을 가지며, 플랫폼의 이미지를 담고, 초안에 필요한 모든 시크릿을 참조로 첨부합니다. 자세한 내용은 초안이 Release에 남기는 것에서 설명합니다.- 참조하지 않고 초안으로 작성하는 각 부분마다
components/아래의 파일 하나. 노드별 레이아웃이 초안 노드를 작성하는 방식대로 작성됩니다.
대상이 주어지면 가져오기는 그 옆에 manifest.yaml의 초안을 작성합니다. 자세한 내용은 대상이 추가하는 것에서 설명합니다.
부분이 아닌 모든 노드는 플랫폼이 담는 플로 안에 남으며 Component가 되지 않습니다. 해당 결정에는 비교한 후보가 기록되고 아무것도 선택되지 않으며, 근거는 kept in the flow <platform> carries, with no Component of its own: 뒤에 이유(예: 어떤 매핑 행도 그 유형을 지정하지 않으며 가장 가까운 후보의 점수가 얼마에 불과했다는 것)가 이어집니다. 노드 간 엣지는 플로가 유지하며, 초안은 자체 엣지를 작성하지 않습니다.
Multiple Documents QnA.json으로 내보낸 Flowise의 Multiple Documents QnA 챗플로를 표준 라이브러리의 Flowise 플랫폼과 그 모델 및 검색 도구 Components를 보유한 카탈로그에 대해 설정도 대상도 없이 가져오면 다음 Aggregate로 초안이 작성됩니다. 여기서는 플로의 대부분을 생략하고 ...로 표시했습니다:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/multiple-documents-qna version: 0.1.0 description: Draft Aggregate imported from a source in the flowise format.spec: components: flowise: type: core/ai-agent/flowise # For the compose target only, uncomment the lines below, which declare owner_password on flowise: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # owner_password: # type: core/secret-value # values: # key: OWNER_PASSWORD values: # chatflow_id is derived from the exported flow, which gives no identifier of its own. chatflow_id: '96da3b80-86d0-5f23-b4e7-2573ea1f76ad' flow_definition: | { "description": "Tool agent that can retrieve answers from multiple sources using relevant Retriever Tools", ... "embeddings": "{{"{{"}}openAIEmbeddings_0.data.instance}}", ... } uses: model: chatopenai-0: target: chatopenai-0 # For the compose target only, uncomment the lines below, which declare credential on chatopenai-0: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # credential: # type: core/secret-value # values: # key: OPENAI_API_KEY # swap to core/ai-model/azure-openai (score 0.4000) by setting type: core/ai-model/azure-openai chatopenai-0: type: core/ai-model/openai values: model: |- gpt-3.5-turbo채팅 모델이 연결된 유일한 부분입니다. 모델 소켓은 단일 연결을 받으므로 두 임베딩 모델은 플로에 남고, 플랫폼의 어떤 소켓도 받지 않으므로 검색 도구도 플로에 남습니다. 가져오기는 각각을 보고합니다.
플로의 식별자는 내보내기가 부여한 것(Langflow 플로의 최상위 id, UUID인 경우 Flowise 챗플로의 최상위 id, n8n 워크플로의 최상위 id)이며, 이는 문자나 숫자로 시작하는 1~128자의 문자, 숫자, ., -, _
또는 :로 이루어진 경우에 한합니다. 내보내기가 식별자를 부여하지 않았거나 다른 문자를 포함한 식별자를 부여한 경우, 초안은 형식 이름과 담긴 그대로의 플로에서 파생한 이름 기반 UUID를 작성하므로 하나의 플로는 항상 하나의 식별자를 산출하며, 값 위의 주석에 파생되었음을 명시합니다.
Flowise 편집기에서 내보낸 챗플로에는 id가 없으므로 파생된 식별자가 부여됩니다.
워크스페이스의 카탈로그에 플랫폼 이름의 Component가 없으면, 초안은 그래도 플랫폼을 지정하되 어떤 부분도 연결하지 않습니다. 부분이 되었을 각 노드는 플로에 남아 보고되며, 가져오기는 카탈로그에 그러한 Component가 없다고 경고합니다.
어떤 노드가 부분이 되며 각각 어디에 연결되는지
importer의 매핑 표의 행이나 mapping_overrides 항목이 노드의 유형을 매핑하거나, 최상위 후보가 최소 중간 등급 일치인 경우 그 노드는 플로의 부분입니다. Langflow MCP Tools 노드는 점수와 관계없이 부분입니다. 이 노드는 호출하는 MCP 서버를 지정하며, 그 서버가 부분입니다. 부분은 reuse_mode가 결정하는 대로 참조되거나 초안으로 작성되어 고유한 Component가 되며, 플랫폼의 첫 번째 소켓(플랫폼의 카탈로그 항목이 소켓을 선언하는 순서 기준) 중 부분의 Component가 레이블 셀렉터를 충족하는 소켓에 연결됩니다. 이때 레이블은 참조하는 Component의 레이블이거나, 초안으로 작성하는 부분의 경우 최상위 후보가 최소 중간 등급 일치일 때 그 후보의 레이블입니다. Component가 어떤 소켓의 셀렉터도 충족하지 않거나 레이블을 읽을 Component가 없는 부분은 플로에 남으며, 가져오기가 이를 보고합니다.
다음 규칙이 이를 좁힙니다.
- 다른 제공자를 지정하는 Langflow 모델은 모델 연결을 받지 않습니다.
LanguageModelComponent또는EmbeddingModel노드는provider필드가 지정하는 모델 제공자, 또는 그것이 비어 있으면model필드가 선택하는 모델의 제공자에서 실행됩니다. 플랫폼은 모델 연결을 OpenAI 호환 클라이언트용으로 전달하므로,OpenAI이외의 제공자를 지정하는 노드는 매핑 행이나 재정의가 무엇에 매핑하든model소켓에 배선되지 않습니다. 이러한 노드는 해당 Component가 충족하는 다음 소켓에 배선되거나, 흐름에 남아 그 결정은 아무것도 선택하지 않고 그 노드를 위한 Component도 초안으로 작성되지 않으며, 가져오기는 노드가 실행되는 제공자를 명시하여 이를 보고합니다. 제공자를 선택하지 않거나, 전역 변수로 제공자를 지정하거나, 다른 노드에서 모델을 가져오는 노드는 다른 파트와 마찬가지로 배선됩니다. - 단일 연결을 받는 소켓은 하나의 부분이 차지합니다. 모든 플랫폼에서
model소켓은 연결 하나를 받으며, 플랫폼의 Recipes는 이를OPENAI_BASE_URL하나와OPENAI_API_KEY하나로 전달합니다. 여러 부분이 배치되면 Component가model.aggrega.ai/capability: generative를 지닌 첫 번째 부분이 차지하고(아무것도 지니지 않으면 첫 번째 부분), 나머지는 모두 플로에 남아 연결을 차지한 부분 및 노드가 작성된 상태에서 플로가 그 부분에 도달하는 방식과 함께 보고됩니다. - Langflow는
tools연결을 그것을 지정하는 MCP Tools 노드를 통해서만 접근합니다. 플랫폼은 tools 연결의 주소를mcp_server필드가 그 연결을 지정하는 MCP Tools 노드의 서버 구성에 작성하므로, 템플릿에mcp_server필드가 없는 노드는 유형이 무엇이든, 매핑 행이나 재정의가 무엇에 매핑하든tools소켓에 연결되지 않습니다. 이 노드는 Component가 충족하는 다음 소켓에 연결되거나, 플로에 남아 보고됩니다. 서버를 지정하지 않는 MCP Tools 노드는 어떤 소켓에도 연결되지 않고 보고됩니다. 서버 구성이 자체 서버를 시작하는 노드(command를 지니거나Stdio모드를 설정하는 노드)도 마찬가지이며, 플랫폼의 빌드는 어떤 tools 연결도 응답하지 않는 서버를 지정하는 노드에서 중단되므로 그 보고에는 제거할 내용이 명시됩니다. - MCP 서버는 플로가 부여한 이름으로 연결됩니다. 하나의 서버를 지정하는 한 플로의 노드들은 한 번 초안으로 작성된 하나의 부분에 하나의 연결을 통해 도달합니다. 연결의 별칭은 연결 별칭이 받을 수 있는 경우(문자, 숫자, 하이픈, 밑줄) 그리고 해당 소켓의 다른 어떤 연결도 같은 변수 이름(별칭을 대문자로 바꾸고 그 외 모든 문자를 밑줄로 쓴 것)으로 전달하지 않는 경우 서버의 이름입니다. 그렇지 않으면 연결은 부분의 키에서 파생한 별칭을 받고, 초안이 담는 플로에서 노드의 서버 이름이 그 별칭으로 바뀌며, 부분의 결정에 그렇게 명시됩니다.
연결된 부분의 결정에는 플랫폼의 어느 소켓에 어떤 연결을 통해 연결되었는지가 명시되며, 건너뛴 각 소켓과 그 이유도 기록됩니다.
담긴 플로가 각 부분에 도달하는 방식
형식이 허용하는 경우, 플랫폼이 담는 흐름은 연결된 각 부분에 그 연결을 통해 도달하며, 초안은 그렇게 되도록 하는 내용을 흐름에 기록합니다. 즉 변수의 이름, 비워진 주소, 또는 연결이 제공하는 것 대신 노드가 보낼 내용을 비운 것이며, 값은 결코 기록하지 않습니다. 이것은 자격 증명 값의 제거가 아니라 연결 작업입니다. 그곳에 남은 값은 연결이 전달하는 것을 덮어쓰므로, 초안은 empty_credentials 설정과 관계없이 이를 기록합니다.
-
Langflow MCP Tools 노드. 플랫폼은 연결이 전달하는 주소를 노드의 서버 구성에 기록하고, 연결이 자격 증명을 담고 있으면 도구가 게시하는 헤더 아래에 그 자격 증명을 담은 변수의 이름을 기록합니다. 초안은 내보내기가 그곳에 담고 있던 주소를 비워 흐름에 그 사본이 남지 않도록 하고, 서버의 주소, 즉 부분의
infra.endpoint는 Release에 남겨 둡니다. Langflow는 노드 자체의headers필드를 서버 구성의 헤더보다 우선하여 보내므로, 초안은 그 필드의 값 전체를 종류를 유지한 채 비웁니다. 객체는{}, 목록은[], 텍스트는 빈 문자열로 기록합니다. 값만 비운 헤더는 여전히 전송되지만, 빈 객체나 목록은 아무것도 덮어쓰지 않기 때문입니다. -
Langflow 모델 또는 벡터 저장소 노드. 플랫폼은 모델 연결을
OPENAI_BASE_URL과OPENAI_API_KEY로, 벡터 저장소 연결을 별칭에 따라 이름 붙인 변수로 전달하며, Langflow는 이를 전역 변수를 지정하는 필드를 통해 읽습니다. 객체가load_from_db: true를 담은 필드는 변수의 이름을 값으로 가지며, Langflow는 그 이름의 전역 변수를 읽고, 저장된 것이 없으면 그 이름의 환경 변수를 읽습니다. 초안은 다음 각 필드를 변수의 이름과load_from_db: true로 기록합니다.OpenAIModel노드의openai_api_base는OPENAI_BASE_URL로,api_key는OPENAI_API_KEY로 기록합니다.OpenAIEmbeddings노드의openai_api_base는OPENAI_BASE_URL로,openai_api_key는OPENAI_API_KEY로 기록합니다.LanguageModelComponent노드의api_key는OPENAI_API_KEY로 기록합니다.EmbeddingModel노드의api_base는OPENAI_BASE_URL로,api_key는OPENAI_API_KEY로 기록합니다.pgvector노드의pg_server_url은AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING으로 기록하며, 여기서<ALIAS>는 연결의 별칭을 대문자로 바꾸고 문자나 숫자가 아닌 모든 문자를 밑줄로 기록한 것입니다.
LanguageModelComponent또는EmbeddingModel노드는 여러 모델 제공자 중 하나, 즉provider필드가 지정하는 제공자, 또는 그것이 비어 있으면model필드가 선택하는 모델의 제공자에서 실행되며, 그 제공자에게 키를 넘깁니다. 플랫폼은 모델 연결을 OpenAI 호환 클라이언트용으로 전달하므로, 그러한 노드는OpenAI에서 실행될 때만 변수로 기록됩니다. 다른 제공자에서 실행되는 노드는 위에서 설명한 대로 배선되지 않으며, 아무것도 선택하지 않거나, 전역 변수로 제공자를 지정하거나, 다른 노드에서 모델을 가져오는 노드는 어떤 변수로도 기록되지 않으므로, 초안은 다른 제공자가 연결의 키를 사용하도록 하지 않습니다. 그러한 노드의 어떤 필드도 API 주소를 제공하지 않는 경우(LanguageModelComponent노드는 OpenAI용 주소를 담지 않으며,EmbeddingModel노드의api_base는 없거나, 변수를 지정할 수 없으면 비어 있을 수 있습니다), 노드가 실행하는 OpenAI 클라이언트는 환경에서OPENAI_BASE_URL을 가져오므로 노드는 그래도 플랫폼이 전달하는 주소에 도달합니다.OpenAIEmbeddings노드의 클라이언트는default_headers를 키로 만든 헤더보다 우선하여 보내고,default_query를 호출하는 주소의 쿼리 위에 병합하므로, 초안이 연결하는 그러한 노드에서는 MCP Tools 노드의headers와 마찬가지로 각각의 값 전체를 종류를 유지한 채 비웁니다.내보내기가 이 두 멤버를 모두 갖추지 않은 채 기록한 필드는 새로 기록되지 않습니다. 그중 자격 증명 필드는 아래와 같이 기록된 그대로 담기거나, 설정이 요구하면 비워집니다. 그 필드가 부분의 주소를 담는 필드이고 (
LanguageModelComponent또는EmbeddingModel노드의 경우 주소를 제공하는 경우), 그러한 노드가OpenAI에서 실행되지 않거나, 노드가 다른 유형이면, 가져오기는 해당 부분을 흐름 또는 해당 컴포넌트의 기본값이 제공하는 주소에서 도달하는 것으로 보고합니다. -
Flowise OpenAI 노드. Flowise가
chatOpenAI또는openAIEmbeddings노드를 실행하는 OpenAI 클라이언트는 노드의 Base Path가 비어 있고 자격 증명을 선택하지 않으면 환경에서OPENAI_BASE_URL과OPENAI_API_KEY를 읽으므로, 초안은 내보내기가 담은 Base Path를 비우고, 노드가 선택한 자격 증명(data.credential)도 비웁니다. 그 클라이언트는 노드의 기본 헤더인baseOptions를 키로 만든 헤더보다 우선하여 보내므로, 초안은 그 값 전체를 종류를 유지한 채 비웁니다. 다른 유형의 모델 노드는 챗플로 또는 자체 기본값이 제공하는 주소에서 도달하는 것으로 보고됩니다. -
Flowise 도구 또는 벡터 저장소. 챗플로는 플랫폼이 이들을 위해 전달하는 주소(
AGGREGA_TOOL_<ALIAS>_URL또는AGGREGA_VECTOR_STORE_<ALIAS>_URL)를 그 이름의 Runtime 변수를 통해서만 읽으며, 시작 시 이 변수를 만드는 것은 없습니다. 초안은 이에 대해 아무것도 기록하지 않으며, 가져오기는 챗플로가 이를 읽게 하는 단계를 보고합니다. Flowise의 Variables 페이지에서 Runtime 변수를 만들고, 노드에서$vars.<name>으로 읽으십시오. -
모든 n8n 노드. 플랫폼은 모델 연결을
OPENAI_BASE_URL과OPENAI_API_KEY로, 도구 또는 벡터 저장소 연결을AGGREGA_TOOL_<ALIAS>_URL또는AGGREGA_VECTOR_STORE_<ALIAS>_URL로 전달하지만, n8n 노드는 선택한 저장된 자격 증명이 제공하는 주소나 자체 매개변수가 담은 주소에서 모델, 저장소 또는 서비스에 도달하며, 워크플로는$env를 읽는 표현식을 통해서만 환경 변수를 읽습니다. 플랫폼은 Aggregate가values.allow_env_access_in_nodes를true로 설정하지 않는 한 이를 거부합니다. 이를 설정하면 모든 워크플로와 워크플로를 편집할 수 있는 모든 사용자가 전달된 자격 증명을 포함하여 플랫폼 환경의 모든 변수를 읽을 수 있으므로, 초안은 그 값을 기본값인false로 둡니다. 따라서 초안은 연결에 대해 워크플로에 아무것도 기록하지 않으며, 연결된 모든 부분은 연결 이외의 방법으로 도달하는 것으로 보고됩니다. MCP 클라이언트 노드는 워크플로가 담은 주소(내보내기가 기록한 그대로, 또는 아래와 같이empty_credentials설정이 비우면 주소 없음)에서 서버에 도달하며, 서버 자체의 주소, 즉 부분의infra.endpoint는 Release에 남겨 둡니다.
흐름이 담기는 경우, 연결된 각 부분은 다음 중 어느 것에 해당하는지와 함께 보고됩니다.
흐름이 연결을 통해 부분에 도달하면 part-reads-connection, 흐름이 연결 이외의 방법, 즉 흐름이 담은 주소나 해당 컴포넌트의 기본값이 제공하는 주소에서 부분에 도달하면
part-address-in-flow입니다. 부분의 결정도 같은 내용을 기록합니다.
초안이 어떤 소켓에도 연결하지 않는 노드도, 노드가 기록된 방식에 따라 초안이 연결하는 연결을 통해 도달될 수 있습니다. 자체 주소와 키가 없는 OpenAI 클라이언트는 플랫폼이 모델 연결을 위해 전달하는 OPENAI_BASE_URL과
OPENAI_API_KEY를 환경에서 읽습니다. 그러한 경우 초안은 노드를 연결된 노드처럼 기록하여, 노드가 담은 어떤 것도 연결이 제공하는 것 대신 전송되지 않도록 하고, part-reads-connection으로 보고합니다.
- 부분이 모델 소켓에 연결되어 있는 동안, 주소 필드가 플랫폼이 전달하는 변수
OPENAI_BASE_URL을 전역 변수로 읽도록 지정하는 LangflowOpenAIEmbeddings노드: 그 노드의default_headers와default_query. - 부분이 모델 소켓에 연결되어 있는 동안, Base Path가 비어 있고 자격 증명을 선택하지 않는 Flowise
chatOpenAI또는openAIEmbeddings노드, 그리고 에이전트플로 노드가 입력 중에 담고 있는 그러한 모델의 구성: 그baseOptions.
그 밖의 노드에서는 이 값들이 연결 구성이 아닙니다. 다음 섹션에서 설명하듯이 작성된 그대로 전달되거나, 설정이 요구하는 경우 비워집니다.
플로가 보유한 자격 증명 값
플로를 전달하기 전에, 가져오기는 아래에 나열된 위치에서 자격 증명을 담을 수 있는 모든 값을 찾아냅니다. 각 값은 세 종류 중 하나입니다. 형식이 자격 증명으로 표시한 값, 형식이 MCP 서버 구성을 보관하는 모든 곳에서의 그 구성 멤버, 그리고 형식이 자격 증명이 아니라고 표시하지만 그럼에도 자격 증명을 담을 수 있는 입력(요청 헤더, 쿼리 매개변수, 명령줄로 작성된 요청 전체, 자격 증명의 이름 아래에 자격 증명을 보유하는 입력)입니다.
기본적으로 가져오기는 이 중 어느 것도 비우지 않습니다. 플로는 내보낸 그대로 전달되며, 무언가를 보유한(빈 문자열도 아니고 null도 아닌) 각 값은 credential-carried 경고에 그 노드와 필드(헤더나 쿼리 매개변수는 그 이름)로 명시되고, 그 값이나 값의 일부로는 절대 명시되지 않으며, 그 값을 비우는 empty_credentials 설정 값이 함께 표시됩니다. 이 설정은 제거를 켭니다. marked는 형식이 자격 증명으로 표시한 값과 MCP 서버 구성의 모든 멤버를 비우고, all은 자격 증명이 아니라고 표시된 입력까지 비웁니다. 설정이 비우는 각 값은 credential-emptied로 그 노드와 필드로 보고되며, 값으로는 절대 보고되지 않습니다. 이미 비어 있거나 null인 값은 그대로 두며 보고하지 않습니다. 설정이 받지 않는 값은 none으로 읽히지 않고 가져오기를 중단시키며, 이때 아무것도 초안으로 작성되지 않습니다.
찾아낸 값이 하나의 변수 참조일 뿐 다른 것이 없으면 그 자체의 값을 보유하지 않습니다. 변수의 이름만 있는 것, ${NAME}(${workspaceFolder}나 ${userHome} 같은 미리 정의된 변수 포함), 또는 MCP 클라이언트가 정의하는 형식인 ${env:NAME}와 ${input:id}가 이에 해당합니다. 설정이 무엇이든, 플로가 어떤 형식이든, 이런 값은 MCP importer가 작성하는 것처럼 작성된 그대로 전달되며 어떤 경고에도 명시되지 않습니다. JSON 텍스트로 작성된 Flowise mcpServerConfig나, Flowise와 n8n에서 텍스트 안의 JSON 객체로 보관되는 헤더와 쿼리 매개변수처럼, 형식이 텍스트로 보관하는 값 안에서 하나의 참조인 멤버도 마찬가지입니다. 비워지더라도 텍스트는 그 멤버를 작성된 그대로 유지합니다.
연산자 뒤에 텍스트가 있는 참조는 그 텍스트를 보유하며, 그 텍스트는 키일 수 있습니다. 연산자 앞에 콜론이 있든 없든 마찬가지입니다. 기본값 ${NAME:-value} 또는 ${NAME-value}, 대체값 ${NAME:+value} 또는 ${NAME+value}, 메시지 ${NAME:?message} 또는 ${NAME?message}, 할당 ${NAME:=value} 또는 ${NAME=value}가 그렇습니다. 이런 참조는 다른 값과 마찬가지로 찾아내어, 기본적으로는 전달되고 credential-carried 경고에 명시되며, 설정이 그 종류를 요구하는 경우 비워집니다. ${config:name}처럼 ${…} 안의 다른 모든 텍스트와, --key=${NAME}처럼 참조 옆의 텍스트도 마찬가지입니다.
노드가 연결에 도달하도록 초안이 작성하는 것, 즉 전달된 플로가 각 파트에 도달하는 방식에서 설명하는 비워진 주소, 변수의 이름, 비워진 선택 자격 증명이나 기본 헤더는 연결 구성입니다. 이는 설정과 관계없이 작성되고, 노드가 연결에 도달하는 방식과 함께 보고되며, 자격 증명 값으로는 절대 보고되지 않습니다. 아래의 모든 위치 밖에 있는 것은 이 섹션의 끝에서 설명하듯이 작성자가 검토해야 합니다.
형식이 자격 증명으로 표시한 값 — marked와 all에서 비워집니다.
- Langflow —
password: true로 표시된 각 템플릿 필드의 값이며, 전역 변수의 이름을 보유한 필드도 포함됩니다. 단, 위에서 설명한 대로 초안이 그 필드를 플랫폼이 전달하는 변수의 이름으로 작성하는 경우는 제외합니다. - Flowise — 노드가
data.credential에 보관하며 자격 증명 매개변수가 선택하는 자격 증명, 노드의inputParams가password타입으로 선언하는 각 입력의 값, 그리고 노드 입력 중의FLOWISE_CREDENTIAL_ID와, agentflow가 모델이나 도구의 구성을 보관하듯 입력의 어떤 깊이에 있는 구성 객체 안의credential또는FLOWISE_CREDENTIAL_ID입니다. - n8n — 노드가 선택하는 각 저장된 자격 증명의
id로,credentials.<type>.id에 있습니다. n8n 내보내기는 자격 증명을 참조로 보관하며 그 값은 절대 보관하지 않고, 참조의name은 찾아내지 않습니다. n8n은 다른 인스턴스에서 워크플로를 가져올 때, 보유하지 않은id의 자격 증명을 그 타입과 이름으로 확인하기 때문입니다. 이전 내보내기가 이름만으로 선택하는 자격 증명은 자격 증명을 가리킬 뿐 보유하지 않으므로 찾아내지 않습니다. 그리고 n8n이 기본 노드 정의에서 비밀번호로 표시하는 각 매개변수의 값(예: Crypto 노드의secret, 사용자를 생성하는 노드의password)도 노드 매개변수 중 어디에 있든 찾아내며, 에이전트의 도구로 사용된 노드는 원래 노드로 읽습니다.
MCP 서버의 구성 — marked와 all에서 비워집니다.
- Langflow MCP Tools 노드의
mcp_server구성과 Flowise 노드의mcpServerConfig(JSON 텍스트 또는 객체로 작성됨): 헤더가 객체이든, 키와 값의 행이든, 통째로 병합되는 객체이든 각 헤더 값(다른 종류의 항목은 통째로 찾아냄), 각 환경 값, 서버의 주소, 명령, 그리고 모든 인수입니다. 두 형식 모두 주소, 명령, 인수를 자격 증명으로 표시하지 않지만, 각각 키를 담을 수 있으므로(주소는 사용자 부분, 경로, 쿼리에) 두 형식 모두에서 이 세 가지도 찾아냅니다. 비워지더라도 명령과 각 인수는 멤버를 유지하므로, 자체 서버를 시작하는 구성은 여전히 그런 구성으로 읽힙니다. Langflow MCP Tools 노드가 도구 연결에 연결된 경우, 그 주소는 위에서 설명한 대로 연결 구성이며 자격 증명 값으로 절대 보고되지 않습니다. JSON 객체로 읽히지 않는 텍스트로 작성된 Flowise 구성은 그 안의 아무것도 찾아낼 수 없으므로 통째로 찾아냅니다. mcp_server필드가 없는 Langflow MCP Tools 노드는 대신 자체 필드에 서버를 보관합니다. 주소는sse_url에, 헤더는headers_input에, 환경은env에, 인수를 포함한 명령줄 전체는command에 있으며, Langflow는 이 중 어느 것도 자격 증명으로 표시하지 않습니다. 따라서 각 헤더 값,env의 각 항목, 주소, 명령줄을 찾아내며, 비워질 때 필드와 항목은 유지됩니다.env가 목록이면 변수의 이름과 값이 하나의 텍스트를 공유하므로 각 항목은 위치로 보고됩니다. 이런 노드는 MCP 서버를 지정하지 않으므로 도구 연결에 절대 연결되지 않습니다.- 초안이 연결하지 않는 노드에서, Langflow가 구성의 헤더보다 우선하여 서버에 보내는 Langflow MCP Tools 노드 자체의
headers필드: 연결된 노드에서처럼 그 값 전체가 종류를 유지한 채 비워지며,headers로 한 번 보고됩니다. - Langflow가 더 이상 사용되지 않음으로 표시한 Langflow의 MCP Tools (SSE) 및 MCP Tools (stdio) 컴포넌트는 각각 하나의 필드에 서버를 보관합니다.
MCPSse노드는 주소를url에,MCPStdio노드는 인수를 포함한 명령줄 전체를command에 보관하며, 이를 통째로 찾아냅니다. 둘 다 MCP 서버를 지정하지 않으므로 도구 연결에 연결되지 않습니다. - n8n MCP 클라이언트 노드(에이전트가 호출하는 MCP Client Tool, MCP Client 노드, 또는 n8n 레지스트리에 나열된 서버의 클라이언트)는 서버의 주소를
endpointUrl매개변수(첫 번째 버전에서는sseEndpoint)에 보관하고, 헤더는 선택하는 자격 증명으로만 보관합니다. 주소는 연결 여부와 관계없이 통째로 찾아냅니다.
형식이 자격 증명이 아니라고 표시한 입력 — all에서만 비워집니다.
- 요청 헤더 — Langflow에서는
APIRequest,URLComponent,CloudflareWorkersAIEmbeddings또는ConfluentKafkaProducer노드의headers와DoclingRemote노드의api_headers, Flowise에서는httpAgentflow,getApiChain,postApiChain,openApiChain,apiLoader,openAPIToolkit또는searXNG노드의headers, Requests 도구의requestsGetHeaders,requestsPostHeaders,requestsPutHeaders,requestsDeleteHeaders, 그리고azureChatOpenAI,azureOpenAIEmbeddings,chatCerebras,chatOpenAICustom,openAIEmbeddingsCustom,chatOpenRouter,chatSambanova또는openAI노드의baseOptions(모델 클라이언트가 보내는 기본 헤더), n8n에서는n8n-nodes-base.httpRequest노드의headerParameters,jsonHeaders,headerParametersUi,headerParametersJson(현재 버전은 앞의 두 개를, 이전 버전은 뒤의 두 개를 유지합니다)과 에이전트의 도구로 사용되는 같은 노드의 해당 필드,@n8n/n8n-nodes-langchain.toolHttpRequest노드의parametersHeaders와jsonHeaders, 그리고n8n-nodes-base.graphql노드의headerParametersUi입니다. 헤더의 이름에는 비밀이 담기지 않으므로, 헤더가 어떤 형태이든 각 헤더의 값을 찾고 이름은 유지합니다. 형태는 이름과 값의 객체, 키와 값의 행(n8n에서는name과value의 행), 또는 Langflow가 헤더에 통째로 병합하는 객체일 수 있습니다. 각 헤더는 이름으로 보고됩니다. 목록에서 헤더 행이 아닌 항목은 통째로 찾아 위치로 보고합니다. 텍스트로 작성된 헤더는 통째로 찾습니다. 단, Flowise와 n8n에서 텍스트가 헤더를 JSON 객체로 담고 있으면, 비울 때 텍스트를 제자리에서 다시 작성하여 각 값을 비우고, 담고 있는 헤더의 이름과 함께 한 번 보고합니다.=로 시작하는 n8n 텍스트는 워크플로가 실행될 때 n8n이 평가하는 표현식이므로 통째로 찾습니다. 비울 때는User-Agent처럼 비밀을 담지 않는 헤더의 값을 포함해 모든 값을 비우므로, 가져온 요청은 작성자가 값을 복원할 때까지 해당 값이 빈 채로 전송됩니다. - 쿼리 매개변수 — Langflow에서는
APIRequest또는GoogleSerperAPI노드의query_params와SerpAPI,Serp,SearchAPI또는SearchComponent노드의search_params, Flowise에서는httpAgentflow노드의queryParams와searchApi로더의customParameters, n8n에서는 도구로 사용되든 아니든n8n-nodes-base.httpRequest노드의queryParameters,jsonQuery,queryParametersUi,queryParametersJson,@n8n/n8n-nodes-langchain.toolHttpRequest노드의parametersQuery와jsonQuery, 그리고n8n-nodes-base.facebookGraphApi노드가options안에 유지하는queryParameters와queryParametersJson입니다. 각각은 요청의 쿼리로 전송되며, 쿼리 매개변수에는 키가 담길 수 있으므로(일부 검색 API는 키를 쿼리의api_key로 받습니다) 헤더와 같은 방식으로 찾습니다. 매개변수가 어떤 형태이든 각 값을 찾고 이름은 유지하며, 각각을 이름으로 보고합니다. 텍스트로 작성된 매개변수는 통째로 찾습니다. 단, Flowise와 n8n에서 텍스트가 매개변수를 JSON 객체로 담고 있으면, 비울 때 제자리에서 다시 작성하고 담고 있는 이름과 함께 한 번 보고합니다. 비울 때는 비밀을 담지 않는 매개변수의 값을 포함해 모든 값을 비우므로, 가져온 요청은 작성자가 값을 복원할 때까지 해당 값이 빈 채로 전송되거나, 값이 빈 매개변수를 보내지 않는 Flowise HTTP 노드에서는 해당 매개변수 없이 전송됩니다. - 어떤 연결도 닿지 않는 OpenAI 노드의 기본 헤더와 기본 쿼리 — Langflow
OpenAIEmbeddings노드의default_headers와default_query, 그리고 FlowisechatOpenAI또는openAIEmbeddings노드의baseOptions입니다. 노드가 어디에 있든 해당하며, agentflow가 선택하는 모델의 구성도 포함됩니다. 이는 초안이 노드를 연결하지 않고, 작성된 그대로 노드에 닿는 연결도 찾지 못하는 경우이며, 연결하거나 찾는 경우에는 위에서 설명한 대로 배선입니다. 각각은 통째로 찾고, 비울 때는 종류를 유지하며(객체는{}, 목록은[], 텍스트는 빈 문자열) 한 번 보고합니다. - 명령줄로 작성된 요청 전체 — Langflow
APIRequest노드의curl_input과Webhook노드의curl이며, Webhook의 기본값을 포함해 통째로 찾습니다. 둘 다 플로가 실행될 때 읽히지 않습니다. 앞의 것은 편집기에서 노드의 필드를 채우기만 하고, 뒤의 것은 예시를 보여 줍니다. - 자격 증명의 이름 아래 자격 증명을 담는 입력 — Langflow
OlivyaComponent노드의api_key, 모든 Composio 컴포넌트의verification_token, 그리고mem0_chat_memory노드의mem0_config(비울 때 전체 값의 종류를 유지합니다), 그리고 FlowisestartAgentflow노드의webhookSecret과callbackSecret,teradataMCP노드의bearerToken입니다. 각각은 통째로 찾습니다. 이름이 자격 증명과 비슷할 뿐인 입력(다른 곳에 저장된 키의 이름, 사용자 이름, 또는 컴포넌트가 비밀이 아니라고 선언한 옵션)은 찾지 않습니다.
설정이 비우는 값, 플로가 파트에 닿도록 초안이 작성하는 내용, Langflow 편집기가 쓰는 방식대로 작성되는 Langflow 에지의 핸들, 그리고 아래에서 설명하는 라인 피드로 작성되는 캐리지 리턴을 제외하면 플로는 내보낸 그대로 전달됩니다: 이 중 아무것도 없으면 바이트 단위로 그대로입니다.
초안의 연결에는 자격 증명 값이 담기지 않습니다: 각 연결이 제시하는 자격 증명은 초안 Release가 참조로 첨부합니다. 자세한 내용은 초안이 Release에 남기는 것에서 설명합니다.
설정이 작성된 그대로 두는 모든 값은 초안에 들어가며, 작성자는
credential-carried 경고를 참고해 이를 검토합니다. 필드에 관한 어떤 규칙도 플로의 나머지 부분에는 미치지 않으므로, 작성자는 초안을 공유하기 전에 그 부분도 검토합니다. 플로가 전달하며 사용자 정의 컴포넌트가 키를 담을 수 있는 컴포넌트 자체의 코드, 편집기가 컴포넌트가 선언한 것 외에 노드에 추가하는 입력, APIRequest 또는 httpAgentflow 노드의 본문처럼 토큰이 담길 수 있는 요청 본문, Langflow EmbeddingModel 노드의 model_kwargs나 Flowise replicate 노드의
additionalInputs처럼 노드가 모델의 클라이언트나 로더에 하나의 객체로 넘기며 어떤 이름으로든 키가 담길 수 있는 인수, 사용자 부분이나 쿼리에 키가 담길 수 있는 MCP 서버 외의 주소, n8n Code 노드의 코드와 위에 나열되지 않은 요청을 보내는 노드의 헤더나 쿼리, 그리고 프롬프트나 메시지 같은 자유 텍스트가 이에 해당합니다.
초안이 Release에 남기는 것
초안 Release는 플랫폼 항목과 각 파트 항목에 플로가 제공할 수 없는 것을 담습니다:
- 플랫폼의 이미지,
infra.image로: 가져오기 도구가 직접 선택한 이미지로, 카탈로그의 해당 플랫폼용 Recipes가 실행되는 것으로 알려진 버전(langflowai/langflow:1.6.0,flowiseai/flowise:3.1.3,n8nio/n8n:1.110.1)이며, 그렇다고 말하는 주석이 붙습니다. 가져오기는 소스를 따르기 위해 이를 올리거나 내리지 않습니다. 내보내기가 다른 플랫폼 버전을 명시하는 경우, 예를 들어 Langflow 플로의last_tested_version처럼, 주석이 그 버전을 알려 줍니다. - 플랫폼이 게시되는 포트,
infra.published_port로,--target compose일 때만: Langflow는 7860, Flowise는 3000, n8n은 5678로, 각 플랫폼이 서비스하는 포트이며, 그 Compose Recipe가 호스트의 루프백 주소 127.0.0.1에 게시합니다. 그 위의 주석은 이 포트가 이 머신에서만, 그 위에서 실행되는 모든 프로세스에 의해 접근 가능하며, 해당 줄을 삭제하면 서비스가 내부에 머문다고 알려 줍니다. 한 가져오기의 두 번째 플로는 앞선 플로가 사용하지 않는 다음 포트를 사용합니다. 다른 대상이거나 대상이 없으면 작성되지 않습니다. - 플랫폼 자체의 시크릿과 각 모델 연결의 자격 증명은 참조로 첨부되며 값으로는 절대 첨부되지 않습니다: Langflow에서는
admin_password슬롯으로,values.require_authentication이true인 동안 읽힙니다. Flowise에서는owner_password슬롯으로,values.flow_definition이 설정된 동안 필수입니다. 그리고 파트가 플랫폼의model소켓에 연결된 경우 그 연결의credential입니다. n8n 플랫폼은 자체 시크릿을 받지 않습니다. 각각을 첨부하는 방식은 대상에 따라 다르며, 대상별 시크릿에서 설명합니다. - 어떤 소스에도 없는 각 값은 그것이 무엇인지 말하는 주석 아래에 빈 문자열로 작성됩니다: Flowise에서는
infra.owner_email, 즉 소유자 계정의 이메일로,values.flow_definition이 설정된 동안 필수입니다. 그리고 플랫폼에 연결된 각 MCP 서버의 주소, 즉 해당 파트의infra.endpoint입니다. 각각은 가져오기에 필요한 값이며, 가져오기 답변 파일에서 설명하는 대로 답합니다.
도구나 벡터 저장소에 대한 연결이 제시하는 자격 증명은 초안으로 작성되지 않습니다: 그런 연결의 자격 증명은 도구가 이를 보낼 헤더를 게시하지 않는 경우 빌드를 중단시키므로, 플랫폼 항목 위의 주석이 이를 알려 주어 도구가 자격 증명을 받는 곳에 첨부할 수 있게 합니다.
대상별 시크릿
--target helm에서는 각 시크릿이 core/referenced-secret이며, 그 origin은 네임스페이스에 이미 있는 Kubernetes Secret의 이름으로, 이 Secret은 데이터 키 value 아래에 값을 보유합니다. 이 이름은 어떤 소스도 제공할 수 없으므로, 무엇을 보유하는지 설명하는 주석 아래에 비어 있는 채로 기록되며, 가져오기가 채워야 할 값이 됩니다. 초안으로 작성된 Manifest는 core/referenced-secret을 helm/k8s-existing-secret에 매핑합니다.
그 밖의 모든 대상에서, 그리고 대상이 없을 때, 각 시크릿은 core/secret-value이며, 그 origin은 변수에 대한 참조입니다. ${LANGFLOW_ADMIN_PASSWORD}, ${FLOWISE_OWNER_PASSWORD}, 그리고 모델 연결의 자격 증명에는 ${OPENAI_API_KEY}이며, 변수 참조를 치환하는 대상은 Docker Compose가 스택을 시작할 때 하듯이 이를 환경에서 읽습니다. 따라서 어떤 파일도 값을 담지 않으며, 이를 위해 채워야 할 값도 없습니다. 위의 Flowise chatflow를 대상 없이 가져오면 다음 Release로 초안이 작성됩니다.
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/multiple-documents-qna # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the flowise format.spec: aggregate: imported/multiple-documents-qna # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: flowise: infra: # The image running core/ai-agent/flowise, at the version this importer drafts, which the catalog's Recipes for it are known to run; the import does not raise or lower it to follow the source. image: "flowiseai/flowise:3.1.3" # Left for the Release, since the source cannot supply it: infra.owner_email, the email address of the platform's owner account, required while values.flow_definition is set owner_email: "" features: owner_password: type: core/secret-value infra: # Attached by reference, never as a value: the owner account's password, required while values.flow_definition is set, read from the variable FLOWISE_OWNER_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${FLOWISE_OWNER_PASSWORD}" uses: model: chatopenai-0: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential flowise presents to chatopenai-0 on its model connection, read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" chatopenai-0: {}대상이 없으면 가져오기는 spec.manifest와 infra.owner_email 두 값을 채워야 합니다. --target compose에서는 소유자의 이메일만, --target helm에서는 소유자의 이메일과 두 Kubernetes Secret의 이름을 채워야 합니다.
compose 대상에서는 Release만이 첨부하는 시크릿이 하나의 키 value 아래로 도착하므로, 소유자 또는 관리자의 비밀번호와 연결의 자격 증명이 모두 그 키 아래로 도착하게 됩니다. 그래서 플랫폼이 연결을 그리는 경우 Aggregate는 각각을 자체 키로 선언합니다. Flowise에서는 키 OWNER_PASSWORD를 가진 owner_password, Langflow에서는 키 LANGFLOW_SUPERUSER_PASSWORD를 가진 admin_password, 그리고 세 플랫폼 모두에서 키 OPENAI_API_KEY를 가진 모델 연결의 credential이며, 각각 그 이유를 설명하는 주석 아래에 있습니다. --target compose에서는 이 줄들이 활성 상태로 기록되고, 대상이 없으면 위 예시처럼 주석 처리된 상태로 기록되어 compose용으로 빌드할 때 주석을 해제하면 됩니다. 그 밖의 대상에서는 기록되지 않습니다. Release는 각 슬롯의 origin을 첨부하며, 같은 유형을 지정하거나 유형을 지정하지 않습니다.
attach_egress_allowlist 설정이 true이면, 플랫폼의 인스턴스는 표준 라이브러리의 core/egress-allowlist Feature도 features 아래에 egress-allowlist로 선언하여, 플랫폼이 연결이 도달하는 구성 요소, 자체 파드, 클러스터의 DNS에만 연결되도록 합니다. 이는 선언된 호출로서의 uses 엣지의 아웃바운드 대응물입니다. Aggregate의 첨부에는 infra가 없으므로 Aggregate는 첨부의 유형만 선언하며, 초안으로 작성된 Release도 그중 아무것도 기록하지 않습니다. 플랫폼 항목 위의 주석은 features.egress-allowlist.infra 아래에 다음을 명시합니다. control_plane_present는 클러스터의 네트워크 플러그인이 네트워크 정책을 적용한다는 것을 확인하기 위해 운영자가 true로 설정하는 값으로, 이것이 없으면 빌드가 중단됩니다. admitted_destinations는 호스팅된 모델처럼 클러스터가 실행하지 않는 대상을 가진 각 연결에 대해 대상과 주소 범위를 명시하는 항목을 담는 목록으로, 이것이 없으면 빌드가 해당 연결을 명시하며 중단됩니다. 그리고 플랫폼을 담는 경계에 대한 aggrega.ai/namespace로, 정책은 워크로드의 네임스페이스에 배치되고 워크로드가 어떤 네임스페이스에도 내보내지지 않으면 빌드가 중단되기 때문입니다. 어떤 키도 비어 있는 채로 기록되지 않으므로, 어느 것도 가져오기가 채워야 할 값에 속하지 않습니다. 연결된 각 부분의 결정은 첨부가 해당 연결을 허용한다고 말하며, 가져오기는 첨부를 feature-attached로 보고합니다. Compose에는 네트워크 정책이 없으므로 이러한 초안의 compose 빌드는 첨부를 명시하며 중단됩니다. 플랫폼이 연결을 그리는 경우, 위의 compose 줄은 두 번째 features 키 없이 인스턴스의 features 블록 안에 기록됩니다.
부분이 제공하는 모델
초안이 참조하는 부분 중 그 Component가 model이라는 값을 선언하는 부분은(표준 라이브러리의 각 모델 Component가 이를 선언하고 요구하듯이) 해당 노드가 선택하는 모델의 이름을 values.model로 하여 작성됩니다:
- Langflow —
OpenAIModel또는AnthropicModel노드의model_name;OpenAIEmbeddings노드의model; 그리고LanguageModelComponent또는EmbeddingModel노드의model_name재정의가 설정된 경우 그 값, 그렇지 않으면model필드가 선택하는 모델. - Flowise —
chatOpenAI,chatAnthropic또는openAIEmbeddings노드의modelName. - n8n — 가져오기 도구의 표가 매핑하는 채팅, 완성 또는 임베딩 노드의
model매개변수, 또는 Google Gemini 및 Vertex 노드의modelName으로, 이름으로 작성되거나 n8n의 최신 노드가 이를 담는 선택자의 값으로 작성됩니다. n8n은 기본값으로 설정된 매개변수를 내보내기에서 제외하므로, 기본 모델을 유지하는 노드는 내보내기에서 아무 모델도 명시하지 않습니다.
Release는 값을 작성할 수 없습니다. 따라서 노드가 초안이 작성할 수 있는 모델을 명시하지 않는 경우(아무것도 선택하지 않거나, 전역 변수 또는 흐름 실행 시에만 읽히는 표현식으로 명시하거나, 연결된 다른 노드에서 가져오거나, 가져오기 도구가 모델 필드를 읽지 않는 유형인 경우), 부분 내부의 주석이 values.model을 작성자에게 남기고, 가져오기는 이를 model-not-named로 보고합니다. 초안이 직접 초안을 작성하는 부분은 값 없이 작성됩니다.
흐름이 초안에 작성되는 방식
흐름은 끝의 줄바꿈을 유지하는 chomping을 가진 YAML 리터럴 블록으로 작성되므로, values.flow_definition은 흐름 자체의 텍스트로 다시 읽힙니다. Aggregate의 텍스트는 템플릿으로 읽히므로, 흐름이 담고 있는 각 {{(Flowise chatflow는 두 노드 사이의 모든 연결에 대해 {{<node id>.data.instance}}를 작성합니다)는 {{"{{"}}로 작성되며, 보간이 이를 다시 두 개의 중괄호로 되돌립니다. 이는
자체 이중 중괄호를 담은 텍스트에서
설명합니다. 모델의 이름도 같은 방식으로 작성됩니다.
리터럴 블록은 모든 문자를 작성된 그대로 담을 수는 없습니다:
- 캐리지 리턴은 CR LF 쌍의 일부이든 단독이든 하나의 라인 피드로 작성됩니다. JSON
문서는 토큰 사이에만 이를 담으며, 그곳에서는 어떤 공백이든 동일하게 읽히므로 플랫폼은 같은 흐름을 읽습니다. 가져오기는 그 개수를
carriage-returns-rewritten으로 보고합니다. - 리터럴 블록이 담을 수 없는 그 밖의 문자가 있으면 흐름이 전달되지 않습니다: 줄바꿈 문자인 U+0085, U+2028 또는 U+2029; 탭과 라인 피드 이외의 제어 문자인 U+0000
U+001F, U+007F, U+0080U+009F; 비문자 U+FFFE 및 U+FFFF; 그리고 UTF-8 시퀀스에 속하지 않는 바이트입니다. 이 경우values.flow_definition은 그렇다는 주석과 함께 설정되지 않은 채로 남고, 나머지는 초안으로 작성되며, 가져오기는 문자 종류마다 흐름에 담긴 개수와 첫 번째 문자의 줄 및 열과 함께definition-not-carried를 보고합니다.
초안이 비우거나 새로 작성하는 값이 파싱된 트리가 그 값을 담는 위치의 내보내기 바이트에 없는 경우에도 흐름은 전달되지 않으며, 가져오기는 해당 값의 위치를 명시하는 definition-not-carried를 보고합니다. 이 경우 흐름의 식별자는 초안이 전달할 수 있으면 흐름 자체의 식별자이고, 그렇지 않으면 흐름 노드들의 식별자에서 파생된 식별자입니다.
노드별
layout: nodes를 사용하면 가져오기는 흐름의 모든 노드를 각각 별도의 Component로 초안 작성하며, 다음을 작성합니다:
aggregate.yaml— 초안의 이름을 정하는 방법에서 설명하는 대로 흐름의 이름을 딴, 흐름의 노드를 구성하는 초안 Aggregate: 각 노드에 대한 항목, 그리고 흐름의 각 엣지는 해당 엣지가 공급하는 노드의uses연결이 되며, 그 소켓과 별칭은 모두 공급하는 노드의 키를 따서 명명되므로, 여러 노드로부터 공급받는 노드는 각 연결에 고유한 별칭을 부여합니다.- 초안으로 작성하는 각 노드에 대해
components/아래의 파일 하나 —<target_namespace>/<category>/<name>이라는 이름의 초안 Component로, 이름은 노드의 유형에서 가져오고, 버전은0.1.0이며, 값 필드는 닫힌values객체의 문자열 필드로, 자격 증명 필드는 전달 방식을 Recipe가 결정하는 필수 자격 증명 슬롯으로 작성됩니다. release.yaml— 같은 이름의 Release 초안으로, 그 Aggregate를 지정하며 각 노드에 대한 항목을 가집니다.
흐름 자체는 전달되지 않으며, 어떤 필드의 값도 읽히지 않습니다.
내보낸 flow 자체를 담기
기본 초안은 flow를 담습니다. 플랫폼의 인스턴스는 내보낸 내용을 values.flow_definition으로 받으며, How the flow is written into the draft에서 설명하는 방식으로 작성됩니다. Aggregate에 flow를 직접 작성하는 작성자도 — 노드별로 배치된 초안이든, 직접 만든 Aggregate든 — 같은 방식으로 작성합니다. 작성된 그대로 flow를 실행하는 Component는 내보낸 내용을 값으로 받습니다 — 표준 라이브러리의 core/ai-agent/langflow와 core/ai-agent/flowise에서는 flow_definition — 그리고 Aggregate의 텍스트는 템플릿으로 읽히므로, 내보낸 내용에 담긴 이중 중괄호는 템플릿 액션으로 읽히게 됩니다. Flowise chatflow는 두 노드 사이의 모든 연결에 대해 {{<node id>.data.instance}}를 기록하고, Flowise 프롬프트는 변수를 {{question}}으로 지칭하며, Langflow 내보내기는 구성 요소의 소스 코드를 담고 있어 그 안에도 중괄호가 나타날 수 있습니다. 내보낸 내용의 각 {{를 블록 스칼라 안에서 {{"{{"}}로 작성하면, Component의 Recipes가 읽기 전에 보간이 내보낸 내용의 텍스트를 복원합니다. 그 이유는 자체 이중 중괄호를 포함하는 텍스트에서 설명합니다. 내보낸 내용에 담긴 자격 증명 값은 Aggregate가 아니라 Release가 첨부하는 시크릿에 속합니다. empty_credentials 설정이 요청할 때 초안이 하듯이 비워 두고 작성합니다.
# Aggregate fragment — a Flowise chatflow carried as exportedspec: components: chat: type: core/ai-agent/flowise values: chatflow_id: 3f2b8c1e-7a4d-4e9b-8c2f-1a6d5e9b0c47 flow_definition: | { "nodes": [ { "id": "llmChain_0", "data": { "name": "llmChain", "inputs": { "model": "{{"{{"}}chatOpenAI_0.data.instance}}", "prompt": "{{"{{"}}promptTemplate_0.data.instance}}" } } } ], "edges": [] }MCP 임포터
importer/mcp는 MCP 클라이언트의 구성이 나열하는 MCP 서버들, 또는 MCP 레지스트리 서버 설명이 기술하는 하나의 서버를 읽고, 각 서버를 표준 라이브러리의 MCP 도구인 core/ai-tool/mcp의 인스턴스로 초안 작성합니다. 모든 서버가 이 하나에 해당하므로, 임포터는 후보를 비교하지 않으며 매핑 결정을 보고하지 않습니다.
읽는 내용
- 클라이언트의 구성. Claude Code의
.mcp.json, Claude Desktop의claude_desktop_config.json, Cursor의.cursor/mcp.json은 서버를 이름별로mcpServers아래에 나열합니다. Visual Studio Code의.vscode/mcp.json은 서버를servers아래에 나열하며, 두 곳 모두에 서버를 나열하는 파일은mcpServers를 먼저 읽습니다.type이stdio이거나,type을 지정하지 않고command를 가진 서버는 명령줄, 즉command와args로 시작되며env를 환경으로 사용합니다.type이http,streamable-http또는sse이거나,type도command도 지정하지 않고url을 가진 서버는url로 접속되며headers가 전송됩니다. - 레지스트리 서버 설명. MCP 레지스트리가 게시하는
server.json으로, 그name과 첫 번째 패키지, 또는 패키지를 나열하지 않는 경우 첫 번째 원격(remote)을 읽습니다. npm 또는 PyPI 패키지는 런처(runtimeHint, 또는 npm의 경우npx, PyPI의 경우uvx),runtimeArguments, 버전을 포함한 패키지(npm은<identifier>@<version>, PyPI는<identifier>==<version>로 작성), 그리고packageArguments가 구성하는 명령줄로 시작되며,environmentVariables를 환경으로 사용합니다. 위치 인수는 그value또는default입니다. 이름 있는 인수는 둘 중 하나가 있으면<name>=<value>로, 둘 다 없으면name으로 작성됩니다. OCI 패키지는identifier가 지정하는 이미지로 실행됩니다. 원격은url로 접속되며headers가 전송됩니다. 하나의 인스턴스는 그중 하나만 실행하므로, 설명이 나열하는 다른 모든 패키지와 원격은 주석에 이름이 기록됩니다.
서버의 다른 모든 멤버(cwd, envFile, Cursor의 auth, 또는 명령줄로 시작되는 서버의 url처럼 해당 종류가 읽지 않는 멤버)는 core/ai-tool/mcp의 어떤 인프라 키도 이를 받지 않으므로 어디에도 작성되지 않고, Release에서 서버 항목 위의 주석에 이름이 기록됩니다. Visual Studio Code가 입력을 요청하는 내용을 기술하며 값을 갖지 않는 구성의 inputs는 읽지 않습니다. 서버, 그 환경과 헤더는 소스가 작성한 순서를 유지합니다. 단, 주석이 있는 JSON으로 읽는 구성은 파싱된 트리가 작성하는 순서, 즉 이름 순서를 따릅니다(주석을 포함하는 구성 참조).
디렉터리는 그 안의 클라이언트 구성들(어떤 깊이에서든 네 가지 중 하나의 이름을 가진 모든 파일)을 경로 순서대로 읽으며, 모든 파일의 모든 서버가 하나의 Aggregate로 초안 작성됩니다.
서버가 되는 것
aggregate.yaml은 초안의 이름을 정하는 방식에서 설명하는 대로 소스의 이름을 딴 초안 Aggregate로, 서버마다 하나의 core/ai-tool/mcp 인스턴스를 가집니다. 인스턴스의 키는 서버 이름을 소문자로 바꾸고, 문자와 숫자 이외의 연속된 문자를 하이픈 하나로 바꾼 것이며, 앞선 서버가 이미 그 키를 사용한 경우 숫자 접미사가 붙습니다. 키가 작성된 서버 이름과 다르거나 임포트가 여러 파일을 읽은 경우, 인스턴스 위의 주석에 서버와 그 출처 파일이 기록됩니다. 이들을 사용하는 에이전트는 초안 작성되지 않습니다.
그 옆의 release.yaml은 같은 이름의 초안 Release로, spec.aggregate가 해당
Aggregate를 지정하며, 각 인스턴스에 대해 소스가 명시하는 운영 입력을 담습니다.
- 명령줄로 시작되는 서버의 경우
infra.stdio_command(명령, 이어서 각 인수를 항목 하나씩), 그리고 런처의 생태계인infra.stdio_runtime( 명령이npx,npm또는node이면npm,uvx,uv,python또는python3이면pypi, 레지스트리 패키지이면 그 레지스트리인npm또는pypi). - 주소로 접속되는 서버의 경우
infra.endpoint: 사용자 부분, 쿼리, 프래그먼트를 제외한 주소입니다. Component는 키를 담는 부분이 없는 주소를 받기 때문입니다. 제외된 각 부분은 서버가 보유한 자격 증명 값이 설명하는 대로, 항목 위의 주석에 주소와 함께 기록됩니다. - OCI 패키지의 경우
infra.image. - 어떤 대상에서도 어떤 서버에 대해서도
infra.published_port는 기록되지 않습니다. 초안은 결코 호스트에 서버를 게시하지 않습니다; - 서버의 환경에는 가져오기의 대상에 맞게 참조로 첨부되는
server_env슬롯이 기록됩니다.--target helm에서는 네임스페이스에 이미 있는 Kubernetes Secret을 지정하는core/referenced-secret이며, 이 Secret은 변수마다 하나의 데이터 키를 보유하고 각 키는 담고 있는 변수의 이름을 가집니다. Secret의 이름은 데이터 키를 명시하는 주석 아래에 비어 있는 채로 기록되며, 가져오기가 채워야 할 값이 됩니다. 그 밖의 모든 대상에서, 그리고 대상이 없을 때는core/referenced-secret-set이며, 변수마다infra.entries아래에 하나의 항목을 가지고, 키는 변수의 이름, 값은 소스가 기록한 그대로입니다. 따라서${GITHUB_TOKEN}같은 변수 참조는 참조로 남으며, 변수 참조를 치환하는 대상이 이를 환경에서 읽습니다.
소스가 명시하지 않는 것은 그것이 무엇인지 설명하는 주석 아래에 비어 있는 채로 기록됩니다. 어느 브리지 이미지도 런처를 갖추지 않은 명령은 infra.stdio_runtime을 비워 두며, 이는 가져오기가 채워야 할 값이 됩니다. 레지스트리 설명이 사용자에게 맡기는 인수는 빈 항목으로, 소스가 값을 기록하지 않은 변수는 값이 비어 있는 항목으로 기록되며, 각각 항목 위의 주석에 명시됩니다.
초안으로 작성되는 모든 Release와 마찬가지로, metadata.environment를 development로 기록하고 그 위에 변경해야 할 초안 기본값이라는 주석을 달며, 대상이 없으면 spec.manifest를 가져오기가 채워야 할 빈 문자열로 기록합니다. 대상이 주어지면 임포터가 Manifest 자체를 초안으로 작성합니다. 카탈로그는 여러 Recipes를 통해 core/ai-tool/mcp를 실현하며 각 서버가 어떻게 실행되는지는 임포터만 알기 때문입니다. 임포터는 각 서버를 그 키로 mappings.components.name 아래에서, 서버의 실행 방식에 해당하는 대상의 realization에 매핑합니다. 명령줄에는 mcp-stdio-bridge, 주소에는 mcp-remote, 이미지에는 mcp이며, 예를 들어 helm/mcp-stdio-bridge 또는 compose/mcp-remote입니다. 또한 환경이 첨부되는 시크릿 유형을 그 realization에 매핑하며, helm에서는 helm/k8s-existing-secret, compose에서는 compose/dotenv-secret-set입니다. 대상이 추가하는 것이 설명하듯이, 가져오기는 그 Manifest를 완성하고 Release에서 이를 지정합니다.
HTTP로 접속되는 서버와 npx로 시작되는 서버를 나열하는 Claude Code .mcp.json은:
{ "mcpServers": { "api-server": { "type": "http", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${API_KEY}" } }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } } }}다음과 같이 초안 작성됩니다.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/mcp version: 0.1.0 description: Draft Aggregate imported from a source in the mcp format.spec: components: api-server: type: core/ai-tool/mcp github: type: core/ai-tool/mcpapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/mcp # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the mcp format.spec: aggregate: imported/mcp # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: # The headers the source sends this server, which no infrastructure key of core/ai-tool/mcp takes, since a remote server's credential is held by each consumer, on its connection to the tool: # - Authorization: "Bearer ${API_KEY}" api-server: infra: endpoint: "https://api.example.com/mcp" github: infra: stdio_command: - "npx" - "-y" - "@modelcontextprotocol/server-github" stdio_runtime: npm features: server_env: type: core/referenced-secret-set infra: # Attached by reference wherever the source names a variable: the environment github is started with, one entry per variable, each written as the source writes it, so a variable reference stays one, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, and an empty value is one still owed. entries: - key: "GITHUB_PERSONAL_ACCESS_TOKEN" value: "${GITHUB_TOKEN}"--target helm으로 가져오면, 같은 구성의 Release는 환경을 그것이 지정하는 Secret으로 첨부하고, 임포터가 초안으로 작성하는 Manifest는 각 서버를 그 키로 매핑합니다.
# release.yaml, the github entry's environment features: server_env: type: core/referenced-secret infra: # Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding the environment github is started with, one data key per variable, each named as the variable it holds: GITHUB_PERSONAL_ACCESS_TOKEN. origin: ""apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/mcp version: 0.1.0spec: mappings: components: type: {} name: api-server: helm/mcp-remote github: helm/mcp-stdio-bridge features: type: core/referenced-secret: helm/k8s-existing-secret서버가 보유한 자격 증명 값
Release가 기록하는 서버 구성의 각 값 — 각 헤더의 값, 명령줄의 각 항목, 주소, infra.endpoint가 제외하는 주소의 각 부분, 각 환경 값 — 은 키를 담을 수 있으며, 어떤 클라이언트도 이를 자격 증명으로 표시하지 않으므로 가져오기는 각 값을 MCP 서버 구성의 멤버로 위치를 지정합니다. isSecret으로 표시된 레지스트리 입력은 그 형식이 자격 증명으로 표시하는 값으로 위치가 지정됩니다. 레지스트리 입력 — 환경 변수 또는 원격의 헤더 — 은 value로 읽히며, 이를 기록하지 않은 경우 default로 읽힙니다. 기본적으로 각 값은 기록된 그대로 Release에 담기고, credential-carried 경고에서 서버와 위치 — headers.<header>, infra.stdio_command.<position>, infra.endpoint 또는 server_env.<variable>, 그리고 주소의 일부는 그것이 기록된 url과 해당 부분의 이름으로, 예를 들어 “url of node remote-search is carried with its query as written(노드 remote-search의 url은 쿼리가 기록된 그대로 담깁니다)” — 로 명시되며, 값으로는 결코 명시되지 않습니다. empty_credentials 설정이 marked 또는 all이면 각 값은 비어 있는 채로 기록되고 credential-emptied로 보고됩니다. 명령줄의 항목은 빈 항목으로, 환경 값은 빈 값으로 기록되며 각각 항목 위의 주석에 명시됩니다. 주소는 빈 infra.endpoint로 기록되며 가져오기가 채워야 할 값이 됩니다. 헤더의 값이나 주소의 일부는 주석에서 제외되어 주석은 헤더나 해당 부분의 이름만 명시합니다. 클라이언트의 infra.stdio_runtime은 Release가 기록한 명령에서 읽히므로, 비어 있게 기록된 명령은 이 값도 비워 두며, 이는 가져오기가 채워야 할 값이 됩니다. --target helm에서는 Release가 환경 값을 전혀 기록하지 않습니다. server_env 슬롯이 지정하는 Secret이 그 값들을 보유합니다.
하나의 변수 참조만으로 이루어진 값 — 맨 이름 ${NAME}(${workspaceFolder} 같은 사전 정의 변수 포함), ${env:NAME} 또는 ${input:id} — 은 자체 값을 보유하지 않습니다. 이러한 값은 설정과 관계없이 있는 그대로의 텍스트로 기록되며, 플로에서 참조가 그렇듯 어떤 경고에서도 명시되지 않습니다. 값이 이러한 참조인 환경 변수는 항목의 값으로 기록되며 참조는 참조로 남습니다. 값이 이러한 참조인 헤더나 주소의 일부는 읽어 오는 참조와 함께 나열됩니다. 연산자 뒤에 텍스트를 담은 참조 — 기본값, 대안, 메시지 또는 할당, 예를 들어 콜론 유무와 관계없이 ${NAME:-value} 또는 ${NAME-value} — 는 그 텍스트를 보유하며, 참조 옆의 텍스트도 마찬가지입니다. 이들은 다른 값과 똑같이 위치가 지정됩니다.
core/ai-tool/mcp의 어떤 인프라 키도 헤더의 값을 받지 않습니다. 원격 서버의 자격 증명은 도구에 대한 연결에서 각 소비자가 보유하며, 가져오기는 소비자를 초안으로 작성하지 않습니다. 따라서 서버 항목 위의 주석은 소스가 서버에 보내는 각 헤더를 기록된 그대로의 값 — 다시 읽으면 정확히 소스의 텍스트가 되는 큰따옴표 문자열 — 과 함께 나열하여, 이를 제시하는 소비자의 연결로 옮길 수 있게 합니다. 값도 기본값도 없는 레지스트리 헤더 입력처럼 소스가 값을 기록하지 않은 헤더는 값이 없는 것으로 나열됩니다. OCI 패키지가 명시하는 이미지는 그대로 기록되며, 설정이 미치는 값이 아닙니다.
infra.endpoint는 키를 담는 부분을 제외한 주소를 받으므로, 소스가 기록한 주소 중 제외되는 부분 — @ 앞의 사용자 부분, ? 뒤의 쿼리, # 뒤의 프래그먼트(첫 번째 # 이후 전체가 프래그먼트) — 은 같은 주석에 각각 이름과 함께, 이를 구분하는 @, ? 또는 # 없이 기록된 그대로 나열됩니다. 주소에서 키를 읽는 소비자는 도구에 대한 자신의 연결에서 전체 주소를 공급합니다. 설정 없이 https://user:pw@api.example.com/mcp?key=k에서 접근하는 서버는 다음과 같이 초안으로 작성됩니다.
# The address's user part and query are not written in infra.endpoint, which holds the address without any part that carries a key; a consumer reading its key from the address supplies the whole address on its own connection to the tool: # - user part: "user:pw" # - query: "key=k" api: infra: endpoint: "https://api.example.com/mcp"그리고 empty_credentials가 marked이면 infra.endpoint는 Release에 맡겨지고, 주석은 user part와 query를 각각 값을 제외한 채 나열합니다.
주석을 포함한 구성
Visual Studio Code는 .vscode/mcp.json을 주석이 포함된 JSON으로 읽으며, MCP 가져오기 도구도 마찬가지입니다. 해당 파일에 대한 시그니처는 parse:jsonc를 처리하는 파서로 파일을 읽으므로, // 및 /* */ 주석과 후행 쉼표를 포함한 구성은 형식을 명시하지 않아도 인식되며, 가져오기 도구는 servers 아래에 서버를 나열하는 모든 소스를 그 파서로 읽습니다. 이러한 구성은 주석과 후행 쉼표가 없는 동일한 구성과 정확히 똑같이 초안으로 작성됩니다. 파서는 객체의 멤버를 이름 순서로 기록하므로, 이러한 구성의 서버, 그 환경과 헤더는 주석 포함 여부와 관계없이 이름 순서로 초안이 작성됩니다. 명령줄은 순서를 유지합니다. 다른 클라이언트와 레지스트리는 파일을 JSON으로 읽으며, 가져오기 도구도 마찬가지입니다. 주석을 포함한 .mcp.json, claude_desktop_config.json, .cursor/mcp.json 또는 server.json은 어떤 시그니처로도 인식되지 않으며, --format mcp를 명시하여 가져오면 파서의 사유와 함께 parse-failed로 중단됩니다. /*로 열고 닫지 않은 주석은 기록된 그대로 남으며, 파서는 파일을 거부합니다.
읽는 설정
MCP 가져오기 도구는 설정에서 설명하는 대로 target_namespace와 empty_credentials를 읽으며, 다른 설정은 읽지 않습니다.
Compose 임포터
importer/compose는 Compose 파일이 선언하는 서비스와 모델을 읽습니다. 각 서비스는 그 이미지가 일치하는 카탈로그 Component의 인스턴스로, 또는 그 이미지를 실행하는 표준 라이브러리의 범용 서버 core/compute/server의 인스턴스로 초안을 작성합니다. 각 모델은 카탈로그가 표준 라이브러리의 Docker Model Runner 런타임 core/ai-model/docker-model-runner를 보유한 경우 그 인스턴스로, 보유하지 않은 경우 자체 모델 Component로 초안을 작성합니다. 그리고 그 옆에 각 서비스가 운영을 위해 명시하는 내용을 담은 Release를 작성합니다.
읽는 내용
- 파일. 단독으로 임포트한 파일은 그 파일만 읽습니다. 디렉터리는 Compose가 읽는 방식대로 읽습니다.
Compose 파일을 담은 각 디렉터리에서, 디렉터리 경로 순서대로,
compose.yaml,compose.yml,docker-compose.yml,docker-compose.yaml중 처음 존재하는 것이 Compose 파일이 되고,compose.override.yml,compose.override.yaml,docker-compose.override.yml,docker-compose.override.yaml중 처음 존재하는 것이 그 위에 병합됩니다. 그 밖의 해당 파일은 읽지 않습니다. 오버라이드 파일만 있고 Compose 파일이 없는 디렉터리는 첫 번째 오버라이드 파일만 단독으로 읽습니다. 초안 Aggregate 맨 앞의 주석은 읽은 파일을 병합 순서대로, 그리고 읽지 않은 파일을 명시합니다. 모든 디렉터리의 모든 서비스와 모델은 하나의 Aggregate로 초안이 작성됩니다. - 병합. 오버라이드 파일은 Compose가 병합하는 방식대로 병합합니다.
image는 대체됩니다.ports는 주소, 공개 포트, 컨테이너 포트, 프로토콜을 기준으로,volumes는 컨테이너 내 경로를 기준으로,environment는 변수 이름을 기준으로 병합되며, 나중 항목이 이전 항목을 대신하고 새 항목은 뒤에 추가됩니다.expose는 뒤에 덧붙여집니다.depends_on과 서비스의models는 합쳐지며, 항목의endpoint_var와model_var는 각각 이전 파일이 명시한 값을 대신합니다. 모델의 경우model과context_size는 대체되고runtime_flags는 덧붙여집니다. Compose의!reset및!override태그는 반영되지 않습니다. 이 태그가 붙은 값은 YAML 파서가 읽는 그대로 병합됩니다. - 서비스.
image, 그리고build아래에서 이미지를 빌드하는지 여부,ports,expose,volumes,environment(매핑 또는NAME=value항목의 목록이며, 값이 없는 이름은 Compose가 실행되는 환경에서 값을 가져옵니다), 목록 또는 매핑인depends_on, 그리고models(모델 이름의 목록, 또는 항목이endpoint_var와model_var아래에 모델의 주소와 식별자가 서비스에 전달되는 변수를 명시할 수 있는 매핑)를 읽습니다. 그 밖의 모든 멤버(command,healthcheck,secrets,env_file등)는 어디에도 작성되지 않으며, Release의 해당 서비스 항목 위 주석에 명시됩니다. - 모델. 최상위
models의 각 항목에 대해model(모델의 OCI 식별자),context_size,runtime_flags를 읽고, 카탈로그가 보유한 경우core/ai-model/docker-model-runner의 인스턴스에, 보유하지 않은 경우 해당 모델용으로 초안이 작성된 모델 Component의 인스턴스에 작성된 그대로 담습니다. 어느 쪽인지와 그 이유는 모델의 결정이 알려 줍니다. 그 밖의 멤버는 해당 인스턴스 위 주석에 명시됩니다. - 나머지. 그 밖의 최상위 멤버(
name,networks,volumes,secrets,configs)는 읽지 않으며, Aggregate 맨 앞의 주석이 이를 명시합니다.
서비스, 모델, 서비스의 환경은 파일에 작성된 순서를 유지합니다. 파서의 트리는 매핑의 멤버를 정렬된 순서로 작성하므로, 블록 매핑으로 작성된 경우 그 순서를 파일의 텍스트에서 읽습니다. 플로 스타일로 작성된 매핑은 정렬된 순서를 유지합니다.
서비스가 어떤 Component인가
임포터는 서비스를 그 이미지가 명시하는 리포지토리로 매칭합니다. 리포지토리란 태그와
다이제스트를 제외한 참조이며, Docker Hub 참조는 짧은 형식으로 씁니다(docker.io/library/postgres:16에 대해 postgres). 임포터는 이미지 테이블을 통해 리포지토리를 매칭합니다. 이 테이블은 이미지
리포지토리에서, 표준 카탈로그의 Compose Recipe가 해당 리포지토리의 이미지를 실행하는 대상인 카탈로그 Component로의 테이블입니다. 테이블은 임포터를 빌드할 때 표준 카탈로그의 Compose Recipes와
Components로부터 생성되어 임포터에 컴파일되므로, 임포트 실행 시에는 Recipe를 읽지 않으며
카탈로그가 무엇을 보유하든 테이블은 표준 카탈로그의 레이블을 담습니다. 임포터의
Plugin 엔터티는 설명에서 테이블을 생성한 허브 리비전을 명시합니다. 테이블은 각
Recipe에서 해당 Recipe가 구현하는 Component와 main이라는 이름의 컨테이너 이미지를 읽습니다. 단, 그 이미지가 자체 텍스트에 리포지토리를 작성하거나, 그렇게 하는 locals 항목인 경우에 한합니다. Release가 명시하는 이미지 전체를 실행하는 Recipe나, 템플릿이 다른 방식으로 조합하는 이미지를 실행하는 Recipe는 행을 추가하지 않으며, Recipe가 메인 컨테이너 옆에서 실행하는 이미지도 마찬가지입니다. 두 Recipes가 하나의
리포지토리를 서로 다른 Components에 대해 명시하면 테이블 생성이 중단되므로, 행이 둘 중 하나를 명시하는 일은 없습니다.
테이블은 행이 명시하는 Component의 레이블을 임포트에 전달되는 그대로, 즉 버전 없이 Component를 명시하는 참조가 해석되는 버전에서
extends를 통해 상속하는 레이블을 포함하여 읽고, component.aggrega.ai/category를 제외한 모든 레이블을 그 행의 특성으로 작성합니다. 표준 카탈로그가 보유하지 않은 Component를 구현하는
Recipe도 테이블 생성을 중단시킵니다.
행은 플로 임포터의 테이블 행과 같은 방식으로 읽습니다. 즉 Component, 그 이름이 배치하는 카테고리,
특성, 그리고 이름의 마지막 세그먼트를 벤더로 읽습니다.
mapping_overrides 설정은 compose 형식 아래에서 리포지토리를 키로 하여 테이블 위에 겹쳐지며,
테이블이 매핑하는 리포지토리에 대한 항목은 그 행을 대신합니다. 따라서 표준 카탈로그의 Recipes가 명시하지 않는 이미지(직접 만든 이미지,
또는 카탈로그의 Component가 다른 리포지토리로 실행하는 이미지)는 항목으로 매핑합니다.
with: settings: mapping_overrides: compose: bitnami/redis: component: core/datastore/redis category: datastore traits: datastore.aggrega.ai/engine: kv vendor: redis행이 이미지를 매핑하는 서비스는 플로 임포터가 노드를 결정하는 방식대로 결정됩니다. 즉 카탈로그의 Components와 대조하여 점수를 매기고, reuse_mode가 기본값인 auto-apply-above-threshold이고 최상위 후보가 reuse_threshold 이상의 상위 등급 매치이면 참조하며, 그렇지 않으면 자체 Component로 초안을 작성하고, 초안 Component 파일은 그것과 유사한 Component를 명시하는 주석으로 시작합니다. 행은 그것이 명시하는 Component의 레이블을 담으므로, 카탈로그가 표준 카탈로그가 부여한 레이블 그대로 그 Component를 보유하면, 그 행이 매핑하는 서비스는 해당 Component에 대한 상위 등급 매치가 되어 0.90점을 받고, auto-apply-above-threshold는 기본 reuse_threshold에서 이를 참조합니다. 카탈로그에서 레이블을 변경한 Component는 더 이상 담지 않는 행의 특성 비율에 비례하여 점수가 낮아지며, 상위 등급에 머무는 동안에만 참조됩니다. 카테고리는 자체 신호에서 한 번만 평가되며, 특성으로 다시 평가되지 않습니다. 하나의 Component를 초안으로 작성하는 서비스들은 그 하나의 파일을 공유합니다. 어떤 행도 이미지를 매핑하지 않는 서비스, 이미지가 임포터가 읽는 리포지토리를 명시하지 않는 서비스, 또는 이미지를 빌드하는 서비스는 카탈로그가 무엇을 보유하든 core/compute/server의 인스턴스가 됩니다. 각 서비스의 결정은 각 노드의 결정과 같은 방식으로 보고됩니다.
서비스가 무엇이 되는가
aggregate.yaml은 초안의 이름을 정하는 방식에서 설명하는 대로 프로젝트의 이름을 딴 초안 Aggregate로, 서비스마다 그 결정이 선택한 Component의 인스턴스를 하나씩 담으며, MCP 임포터가 서버에 키를 붙이는 방식으로 키가 붙습니다. 키가 서비스 이름이 아니거나 임포트가 여러 디렉터리를 읽은 경우에는 인스턴스 위에 서비스와 그 서비스가 나온 파일을 명시하는 주석이 붙습니다. 서비스의 depends_on이 명시하는 각 서비스는 연결 uses: <key>: <key>: {target: <key>}이 되며, 이 연결은 둘 다 대상의 키를 따라 이름 붙은 소켓과 별칭 아래에 쓰입니다. 컴포넌트는 어떤 소켓에 연결되어 있든 각 연결을 그 별칭으로 읽으므로, 서비스의 각 연결은 저마다 고유한 별칭을 가집니다. 서비스 환경의 변수도 연결을 만들 수 있으며, 서비스의 환경과 이미지가 무엇이 되는지에서 설명하듯 그 변수가 가리키는 서비스가 게시하는 것에서 변수를 전달합니다. 각 모델은 워크스페이스의 카탈로그가 core/ai-model/docker-model-runner를 보유하는 경우 reuse_mode의 값과 관계없이 그 인스턴스가 되며, 모델을 위한 Component는 초안으로 작성되지 않습니다. 인스턴스는 model과 runtime_flags를 소스가 기술한 그대로 쓰고, 소스의 context_size를 context_window로 씁니다. 이 값은 런타임이 모델의 컨텍스트 길이로 선언하는 값이며, 런타임의 Compose Recipe가 이를 Compose의 context_size로 다시 씁니다. 카탈로그가 core/ai-model/docker-model-runner를 보유하지 않는 경우 모델은 <target_namespace>/ai-model/<key>로 초안이 작성됩니다. 이는 값이 model, context_size, runtime_flags를 선언하는 ai-model 카테고리의 Component이며, 그 인스턴스는 소스가 기술한 각 값을 씁니다. 모든 모델에는 어느 쪽인지를 말하는 결정이 있습니다. mapped llm (model) to core/ai-model/docker-model-runner as a reference, NONE이거나, 워크스페이스의 카탈로그가 core/ai-model/docker-model-runner를 보유하지 않는다고 결정에 기록된 초안입니다. 어느 경우든 모델을 명시하는 각 서비스는 의존하는 서비스와 마찬가지로 모델에 연결됩니다. 긴 형식으로 endpoint_var 또는 model_var를 사용해 모델을 명시하는 서비스는 모델의 주소와 식별자가 서비스에 전달되는 변수를 명시합니다. 초안의 어떤 키도 변수 이름을 담지 않으므로(연결은 값을 선언하지 않는, 모델 이름을 딴 소켓에 쓰이며, 임포터에는 어떤 Component의 인프라 키도 전달되지 않습니다) 연결 위의 주석이 항목이 쓴 그대로 각 변수를 명시하고, 서비스의 결정도 같은 문장을 기록합니다.
search: type: core/compute/server uses: # The service search reads the address of the model embedder as AI_MODEL_URL and its identifier as AI_MODEL_NAME, the names its models entry gives them; no key of the draft holds either name. embedder: embedder: target: embedder짧은 형식으로, 또는 어느 변수도 없이 모델을 명시하는 서비스는 주석 없이 모델에 연결됩니다.
그 옆의 release.yaml은 같은 이름의 초안 Release이며, 그 spec.aggregate가 Aggregate를 명시합니다. core/compute/server의 인스턴스에 대해서는 작성된 그대로의 이미지인 infra.image와, ports의 첫 항목에서, 또는 ports에 항목이 없으면 expose의 첫 항목에서 컨테이너가 수신하는 포트인 infra.port를 씁니다. --target compose를 사용하면 같은 ports 항목이 게시하는 호스트 포트인 infra.published_port도 소스가 기술한 그대로 쓰며, 이 포트는 이 머신에서만, 그 위에서 실행되는 모든 프로세스가 접근할 수 있고 그 줄을 삭제하면 서비스가 내부에 머문다는 주석을 붙입니다. published_port가 받지 않는 1024 미만의 호스트 포트는 쓰이지 않으며, 항목 위의 주석이 그 포트를 명시합니다. 각 서비스 항목 위의 주석은 소스가 기술하지만 초안의 어떤 키도 담지 않는 것, 즉 다른 Component에 일치되었으나 초안이 태그를 변환하지 않는 서비스의 이미지, 그 ports, expose, volumes, 그리고 초안이 변환하지 않는 environment의 각 변수를 써서 Component가 받는 곳에 옮길 수 있게 합니다. 초안이 Release에 남기는 것, 즉 자체 이미지를 빌드하는 서비스처럼 이미지를 명시하지 않는 서비스의 이미지와 하나의 숫자가 아닌 포트는 그 이유를 말하는 주석 아래에 비어 있는 채로 쓰입니다. 빌드는 Release가 명시하는 인스턴스만 배치하므로, 각 모델의 인스턴스에는 서비스 항목들 뒤에 빈 항목 <key>: {}가 있습니다. Compose에서 기본값이 없는 입력을 받지 않는 core/ai-model/docker-model-runner의 인스턴스도, 자체 Component로 초안이 작성된 모델도 마찬가지이므로, 초안으로 작성된 모델은 이미 배치되어 있으며 그것을 실현하는 Recipe를 작성하면 빌드됩니다. core/compute/server의 하한인 1024보다 낮은 포트처럼 Component가 받지 않는 포트는 소스가 기술한 그대로 쓰이며, 빌드는 그 포트를 명시하며 중단됩니다. Release는 MCP 임포터의 Release와 마찬가지로 metadata.environment를 쓰고, 타깃이 없으면 빈 spec.manifest를 씁니다. 타깃이 주어지면 임포트는 대상이 추가하는 것에서 설명하듯 Manifest를 초안으로 작성하여 각 Component를 그 타깃에서 실현하는 Recipe에 매핑합니다. core/compute/server는 compose/server 또는 helm/server에, core/ai-model/docker-model-runner는 compose/docker-model-runner 또는 helm/docker-model-runner에 매핑됩니다.
PostgreSQL과 그에 의존하는 자체 API를 실행하는 compose.yaml은 다음과 같습니다.
services: db: image: postgres:16 environment: POSTGRES_DB: shop api: image: ghcr.io/example/shop-api:1.4.2 depends_on: - db ports: - "8080:8080" environment: CACHE_URL: redis://cache:6379/0이는 단독으로 임포트되고 프로젝트에 name이 없으므로 파일의 이름을 따서, 설정 없이, 표준 라이브러리의 core/datastore/postgres를 담은 카탈로그에 대해 다음과 같이 초안이 작성됩니다.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/compose version: 0.1.0 description: Draft Aggregate imported from a source in the compose format.spec: components: db: type: core/datastore/postgres # The values of core/datastore/postgres the source sets as POSTGRES_DB, the variables its Compose Recipes set from them. values: database: "shop" api: type: core/compute/server uses: db: db: target: dbapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/compose # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the compose format.spec: aggregate: imported/compose # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: db: infra: # The tag of the image the source runs, postgres:16, the engine_version of core/datastore/postgres its Compose Recipes run. engine_version: "16" # The source also states, for the Release to carry where core/compute/server takes it: # ports: # - "8080:8080" # environment: # CACHE_URL: "redis://cache:6379/0" api: infra: image: "ghcr.io/example/shop-api:1.4.2" port: 8080임포트는 mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9를 보고합니다. 프로젝트에 cache 서비스가 없으므로 CACHE_URL은 연결을 만들지 않고 주석에 남습니다. reuse_mode: hints-only이면 db는 대신 type: imported/datastore/postgres가 되어 components/imported-datastore-postgres.yaml에 초안으로 작성되며, 이 파일은 # resembles core/datastore/postgres (score 0.9000); reference it by setting type: core/datastore/postgres로 시작합니다. 초안으로 작성된 Component는 카탈로그의 Recipes가 읽는 값을 하나도 선언하지 않으므로, 이때 그 이미지와 환경은 항목 위의 주석에 쓰입니다. --target compose가 주어지면 Manifest는 core/datastore/postgres를 compose/postgres에, core/compute/server를 compose/server에 매핑하고, --target helm이 주어지면 helm/postgres와 helm/server에 매핑합니다.
서비스의 환경과 이미지가 무엇이 되는지
서비스가 그 이미지의 행이 명시하는 카탈로그 Component의 인스턴스이고 워크스페이스의 카탈로그가 그 Component를 보유하는 경우, 임포터는 이미지 테이블이 각 Recipe에 대해 기록한 내용을 바탕으로, 표준 카탈로그에서 그 Component를 위한 Compose Recipes가 읽는 방식대로 이미지와 환경을 읽어 초안으로 변환합니다.
- 이미지의 태그는 Recipe가 이미지 참조를 만드는 데 쓰는 인프라 키로, 예를 들어
engine_version이며postgres:16의 경우16입니다. 이는 소스의 이미지를 명시하는 주석 아래 Release에 쓰입니다. - Recipe가 Component의 값 중 하나로 설정하는 변수(
POSTGRES_DB,POSTGRES_USER) 중 값에 텍스트가 담긴 것은, 카탈로그의 Component가 그 값을 선언하는 경우 인스턴스의 그 값인database또는user가 되며, 변수를 명시하는 주석 아래 Aggregate에 쓰입니다. - Recipe가 비밀번호를 읽는 변수(예:
POSTGRES_PASSWORD) 중 값이 하나의 변수 참조인 것은 그 슬롯에 연결되는 시크릿이 되며, 참조가 명시하는 변수에서 읽히고 Recipe가 그것을 읽는 키로 선언됩니다.
그리고 모든 서비스에 대해, 이렇게 읽히지 않은 환경의 각 변수는 다음과 같습니다.
- 프로젝트의 다른 서비스 이름인 값은, 그 서비스의 행이 호스트 이름을 게시하는
provides키를 명시하는 경우 그 서비스로의 연결을 만들며, 그 연결의inject블록이 그 키에서 변수를 전달합니다.CACHE_HOST: cache는 캐시의host에서 가져온CACHE_HOST가 됩니다. - 다른 서비스가 자신의 Component에 설정하고 그 Component가 게시하는 값과 같은 값(
POSTGRES_USER: notes를 설정하는 PostgreSQL 서비스 옆의DATABASE_USER: notes)은 그provides키에서 변수를 전달하는 연결을 만듭니다. 여러 서비스나 키가 그 값을 담고 있으면, 키나 자체 변수가 변수 이름의 끝과 같게 끝나는 것을 읽고, 그런 것이 없으면 서비스의 다른 변수들이 아직 읽히지 않은 것을 읽습니다. 그 밖의 경우 변수는 읽히지 않습니다. - 다른 서비스의 시크릿을 읽는 변수를 명시하는 하나의 변수 참조인 값(
DATABASE_PASSWORD: ${POSTGRES_PASSWORD})은core/compute/server의 인스턴스에서, 타깃이 시크릿을 서버가 받는 값으로 쓰는 경우 자체 시크릿이 되며, 소문자로 된 변수 이름으로 연결되고 같은 변수에서 읽힙니다.helm/server는core/referenced-secret을 거부하므로--target helm에서는 그러한 변수가 주석에 남습니다.
그 밖의 모든 변수는 소스가 쓴 그대로 서비스 항목 위의 주석에 남습니다. Compose 임포트 워크스루는 API가 이 방식으로 데이터베이스와 캐시에 접근하는 프로젝트를 초안 그대로 빌드하고 실행하는 과정을 보여 줍니다.
서비스가 보유하는 자격 증명 값
Compose는 어떤 환경 값도 자격 증명으로 표시하지 않고, 임포터는 어떤 변수의 이름도 그 의미를 위해 읽지 않으므로, 무언가를 담은 모든 환경 값은 그 형식이 자격 증명이 아니라고 표시하지만 자격 증명을 담을 수 있는 입력으로 찾아집니다. 기본적으로 각 값은 초안에 작성된 그대로 옮겨지고(변환된 값으로, 또는 Release의 해당 서비스 항목 위 주석으로), credential-carried 경고에 서비스와 변수(environment.<variable>)로 명시되며 값으로는 절대 명시되지 않습니다. empty_credentials 설정이 all이면 각 값은 비워져 쓰이고 credential-emptied로 보고되며, 주석은 값 없이 변수를 명시합니다. marked에서는 Compose가 아무것도 표시하지 않으므로 어떤 값도 비워지지 않습니다. Compose가 보간하는 변수 참조 하나뿐인 값(${NAME} 또는 $NAME)은 자체 값을 담지 않습니다. 그런 값은 있는 그대로의 텍스트로 쓰이며 어떤 경고에도 명시되지 않습니다. ${NAME:-value}처럼 기본값이나 메시지를 담은 참조는 그 텍스트를 담으며, 다른 값과 마찬가지로 찾아집니다. Compose가 다른 곳(env_file, 시크릿의 파일)에서 읽는 값은 읽지 않습니다.
읽는 설정
Compose 임포터는 Settings에서 설명하는 대로 target_namespace, reuse_mode, reuse_threshold, emit_hints,
render_mode, mapping_overrides, empty_credentials를 읽으며, 다른 설정은 읽지 않습니다. emit_hints가 제어하는 힌트는 초안으로 작성된 Component의 파일에만 쓰이며,
초안 Aggregate에는 담기지 않습니다.
Dify 임포터
importer/dify는 Dify에서 DSL(Dify가 애플리케이션에 대해 작성하는 YAML 문서)로 내보낸 애플리케이션을 읽고, 표준 라이브러리의 Dify 설치인 core/dify를 구성하는 Aggregate 초안을 작성합니다. 애플리케이션은 설치의 app_definition 매개변수에 담깁니다. 설치는 배포 시 API 서버의 Recipe가 렌더링하는 단계를 통해 애플리케이션을 가져옵니다.
읽는 내용
- 애플리케이션.
app인kind, 애플리케이션이 작성된 DSL의 버전인version, 그리고mode를 포함한app입니다. - 워크플로 또는 채트플로(
mode가workflow또는advanced-chat)는 그래프를workflow아래에 둡니다.workflow.graph.nodes의 각 노드 중data.type아래에 유형을 명시한 노드는 그래프가 나열한 순서대로 애플리케이션의 노드가 되며,workflow.environment_variables에는 애플리케이션이 읽는 변수가 담깁니다. - 채트, 에이전트 채트 또는 완성 애플리케이션은 구성을
model_config아래에 둡니다. 그model,dataset_configs.datasets.datasets아래의 각 지식 베이스,agent_mode.tools아래의 각 도구는 애플리케이션의 노드이며,model_config.model처럼 그 위치로 이름이 붙습니다.agent모드의 애플리케이션은 하나의 노드agent입니다. - 필요한 플러그인.
dependencies의 각 항목도dependencies.<n>이라는 이름의 노드이며, 유형은marketplace처럼 항목이 명시한 유형입니다.
초안 작성 내용을 결정하는 다른 요소는 없습니다. 애플리케이션 전체가 그대로 담깁니다.
애플리케이션이 변환되는 결과
aggregate.yaml은 초안의 이름을 정하는 방식에서 설명하는 대로 애플리케이션의 이름을 딴 Aggregate 초안으로, dify를 키로 하는 core/dify 항목 하나를 구성하며, 그 app_definition 매개변수는 애플리케이션을 작성된 그대로 담습니다. 이는 흐름이 초안에 기록되는 방식이 흐름에 대해 설명하는 방식과 같으므로, Dify 고유의 {{#…#}} 참조는 내보낸 그대로 설치에 전달됩니다. 설치는 API 서버의 모든 연결(데이터베이스, 캐시, 벡터 저장소, 샌드박스, 플러그인 런타임, 이그레스 프록시)을 스스로 연결하므로, 초안은 Component를 작성하지 않고 아무것도 연결하지 않습니다. 모든 노드는 애플리케이션 안에 남으며, 해당 결정이 이를 기록합니다. 그 옆의 release.yaml은 같은 이름의 Release 초안으로, 설치를 경계 platform에 배치하고 애플리케이션이 제공할 수 없는 것을 담습니다.
가져오기는 작업 공간 카탈로그의 Components는 볼 수 있지만 Aggregates는 볼 수 없으므로, 카탈로그에 core/dify가 있는지 확인하지 않으며, 항목 위의 주석이 이를 알립니다. 카탈로그에 core/dify가 실행하는 API 서버인 core/ai-agent/dify가 없으면, 가져오기는 platform-not-in-catalog로 경고하고 항목은 그대로 작성합니다.
설치의 애플리케이션 시크릿, 즉 Dify가 세션 쿠키에 서명하고 저장하는 모델 공급자 자격 증명을 암호화하는 데 쓰는 키는 core/dify의 secret_key 매개변수이며, 기본값이 없습니다. 따라서 초안은 자체 secret_key 매개변수(문자열, 필수, 최소 한 글자, 기본값 없음)를 선언하고, 작성하는 모든 core/dify 항목에 이를 전달하여 Release가 자신의 parameters 아래에서 채우도록 합니다. Release가 이를 설정하지 않은 빌드는 그 이름을 지정하며 중단됩니다.
애플리케이션은 설치의 소유자 계정으로 가져오며, 이 계정은 Release가 설치에 대한 라우팅 항목에서 지정합니다. 설치의 api 컴포넌트의 infra.owner_email과, 같은 컴포넌트의 owner_password 슬롯(core/referenced-secret로 첨부)이며, 이것들이 없으면 빌드가 중단됩니다. 소유자의 이메일은 어떤 소스도 제공할 수 없으므로, 그것이 무엇인지 설명하는 주석 아래에 비어 있는 채로 작성되며, 임포트는 이를 제공해야 할 값으로 보고합니다.
모든 대상에서 같은 라우팅 항목은 설치의 api, worker, scheduler 컴포넌트에 infra.marketplace_enabled를 true로 설정하며, 각각은 그 이유를 설명하는 주석 아래에 있습니다. Release가 허용하지 않는 한 설치는 Dify 공급업체의 어떤 것에도 접근하지 않고, 세 컴포넌트는 각자 자신의 설정을 읽으며, Dify는 애플리케이션의 모델(예: OpenAI의 모델)을 제공하는 플러그인을 자신의 플러그인 마켓플레이스에서 설치하기 때문입니다.
애플리케이션 시크릿과 소유자의 비밀번호는 시크릿이며, 임포트의 대상에 맞게 참조로 초안이 작성됩니다.
--target helm에서는 각각이 네임스페이스에 이미 있는 Kubernetes Secret을 지정합니다.secret_key는 Secret의 이름으로,core/dify는 이를 데이터 키secret-key아래에서 읽으며,owner_password는 데이터 키value아래에 비밀번호를 담은 Secret입니다. 두 이름 모두 어떤 소스도 제공할 수 없으므로, 각각 그것이 무엇인지 설명하는 주석 아래에 비어 있는 채로 작성되며, 임포트는 둘 다 제공해야 할 값으로 보고합니다. 초안으로 작성된 Manifest는core/referenced-secret를helm/k8s-existing-secret에 매핑합니다.- 그 밖의 모든 대상에서, 그리고 대상이 없을 때에도, 각각은 변수에 대한 참조입니다.
secret_key는"${DIFY_SECRET_KEY}"로, 소유자의 비밀번호는"${DIFY_OWNER_PASSWORD}"로 작성되며, 이는 표준 카탈로그의 Compose용 Dify Recipes가 읽는 이름입니다. Docker Compose는 스택이 시작될 때 이를 환경에서 읽으므로 둘 다 제공해야 할 값이 없습니다.--target compose에서는 초안으로 작성된 Manifest가core/referenced-secret를compose/dotenv-referenced-secret에 매핑합니다.
대상이 주어지면 Manifest는 대상이 추가하는 것에서 설명하는 대로 설치가 구성하는 각 컴포넌트의 타입과 초안 자체의 타입을 매핑합니다.
이 임포터의 테스트가 가져오는, Support Answers라는 이름의 작성된 워크플로 애플리케이션은 설정 없이 다음과 같이 초안이 작성됩니다.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/support-answers version: 0.1.0 description: Draft Aggregate imported from a source in the dify format.spec: parameters: secret_key: type: string required: true minLength: 1 description: "Passed down to core/dify's secret_key parameter, which has no default; that parameter's description in core/dify says what the value is." aggregates: # An import sees the Components of the workspace's catalog and none of its Aggregates, so it does not check that the catalog holds core/dify. dify: type: core/dify parameters: secret_key: "{{ .parameters.secret_key }}" app_definition: | app: description: Answers a support question from a knowledge base and files it. ...--target helm으로 가져오면, 초안으로 작성된 Release는 secret_key를 채우고 설치를 배치하는 라우팅 항목에서 소유자를 지정하고 플러그인 마켓플레이스를 켜며, 제공해야 할 각 값은 비어 있는 채로 작성됩니다.
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/support-answers # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the dify format.spec: aggregate: imported/support-answers manifest: imported/support-answers parameters: # Left for the Release, since the source cannot supply it: secret_key, which the drafted Aggregate declares and passes down to core/dify; that parameter's description there says what the value is secret_key: "" boundaries: platform: aggregates: dify: components: api: infra: # Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from. marketplace_enabled: true # Left for the Release, since the source cannot supply it: components.api.infra.owner_email, the email of the installation's owner account the application is imported under, on the api component of core/dify owner_email: "" features: owner_password: type: core/referenced-secret infra: # Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding, under the data key value, the owner account's password. origin: "" worker: infra: # Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from. marketplace_enabled: true scheduler: infra: # Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from. marketplace_enabled: true임포트는 비어 있는 세 값을 제공해야 할 값으로 보고합니다. --target compose로 가져오면, 같은 Release는 secret_key: "${DIFY_SECRET_KEY}"와 origin: "${DIFY_OWNER_PASSWORD}"를 작성하고, 소유자의 이메일만 제공해야 할 값으로 보고합니다. 또한 api 컴포넌트에 infra.published_port로 5001을, 프런트엔드인 console 컴포넌트에 3001을 작성하며, 각각은 이 머신에서 실행되는 모든 프로세스가 이 머신에서만 접근할 수 있고, 해당 줄을 삭제하면 서비스가 내부에 유지된다고 설명하는 주석 아래에 있습니다. 그리고 api 컴포넌트의 포트 아래에 콘솔이 게시되는 주소인 "http://127.0.0.1:3001"을 값으로 하는 infra.console_url을 작성하며, Dify 서버는 이를 콘솔의 주소로 사용합니다. Dify 임포트 연습은 두 대상 모두에 대해 애플리케이션을 빌드하고 Kubernetes에서 실행합니다.
Dify가 스스로 구성하는 것
Dify는 애플리케이션이 호출하는 모델과 도구의 공급자를 내부에서 구성하며, core/ai-agent/dify는 모델용 소켓을 선언하지 않으므로 초안은 아무것도 연결하지 않습니다. 이를 명시하는 각 노드는 part-configured-in-platform으로, 그리고 그 결정에서, 명시하는 대상에 따라 다음과 같이 보고됩니다.
llm,question-classifier또는parameter-extractor노드와 채트 애플리케이션의model_config.model: 모델을 이름과 공급자로;tool노드와 채트 애플리케이션의 도구: 도구를 이름과 공급자로;agent노드: 에이전트 전략과 이를 제공하는 플러그인;knowledge-retrieval노드와 채트 애플리케이션의 지식 베이스: 검색 대상 지식 베이스, 그리고 명시하는 경우 쿼리를 라우팅하거나 재순위화하는 모델. 애플리케이션은 내보낸 원본 설치의 식별자로 지식 베이스를 지정하며 문서나 저장소를 전혀 담지 않으므로, 각 지식 베이스는 Dify 내부에서, 설치가 API 서버에 연결하는 벡터 저장소에 생성됩니다;- 의존성: 플러그인을 Dify가 설치할 때 사용하는 식별자와 Dify가 설치하는 출처로.
그 밖의 모든 노드는 보고 없이 애플리케이션에 유지됩니다.
애플리케이션이 담고 있는 자격 증명 값
임포터는 애플리케이션이 작성한 순서대로 다음을 찾습니다.
value_type이secret인 각 환경 변수의 값으로, Dify가 자격 증명으로 표시합니다. Dify의 내보내기는 비밀을 포함하지 않는 한 이를 빈 값으로 기록합니다;- HTTP 요청 노드의
authorization.config.api_key로, Dify가 자격 증명으로 표시하고 작성된 그대로 내보냅니다; tool노드 또는agent노드의 도구가credential_id아래에서 선택하는 저장된 자격 증명으로, Dify가 자격 증명으로 표시하며 내보내기에 비밀이 포함된 경우에만 기록합니다;- HTTP 요청 노드의
headers와params각각 전체로, Dify가 자격 증명으로 표시하지 않지만 자격 증명을 담을 수 있습니다.
기본적으로 값을 담은 각 항목은 애플리케이션에 작성된 그대로 담기며, credential-carried 경고에서 노드(환경 변수의 경우 workflow)와 필드로 지정되고, 값으로는 결코 지정되지 않습니다. empty_credentials 설정이 marked이면 Dify가 자격 증명으로 표시한 각 값이 빈 값으로 기록되고, all이면 헤더와 쿼리 매개변수도 빈 값으로 기록되며, 각각 credential-emptied로 보고됩니다. 하나의 변수 참조만으로 이루어진 값은 값을 담지 않으므로, 설정과 관계없이 작성된 그대로 담기며 어떤 경고에도 지정되지 않습니다. 이는 흐름에서와 같습니다. 값은 애플리케이션 자체의 텍스트에서 빈 값으로 기록됩니다. 키 뒤의 스칼라가 ''로 바뀌고 다른 것은 변경되지 않습니다. 애플리케이션은 parse:yaml을 제공하는 파서가 결과를 정확히 해당 값만 비운 내보낸 애플리케이션으로 다시 읽는 경우에만 담깁니다. 그렇지 않으면 담기지 않고, app_definition은 주석과 함께 설정되지 않은 채로 남으며, definition-not-carried가 그 이유를 알립니다. 예를 들어 YAML 별칭이 비밀의 값을 읽는 애플리케이션은 그 값을 비우면 별칭도 바뀝니다. 설정이 작성된 그대로 두는 값은 다시 쓰이지 않으므로, 애플리케이션이 담기는 것을 막지 않습니다.
DSL 버전
애플리케이션이 core/ai-agent/dify가 기본으로 실행하는 Dify 1.17.0 버전이 작성하는 0.7.0보다 새로운 DSL 버전으로 작성된 경우, 가져오기는 dsl-version-newer로 경고합니다. Dify는 이러한 애플리케이션의 가져오기를 확인을 위해 보류하며, 배포 시 이를 가져오는 단계가 확인을 제공하므로, Release가 실행하는 Dify 버전에 대해 애플리케이션을 확인하십시오.
읽는 설정
Dify 임포터는 설정이 설명하는 대로 target_namespace, empty_credentials, layout, attach_egress_allowlist, render_mode를 읽으며, reuse_mode, reuse_threshold, emit_hints, mapping_overrides도 읽지만 이들은 기본 레이아웃이 작성하는 초안을 바꾸지 않습니다. 모든 노드는 애플리케이션 안에 남습니다. 구성된 Aggregate의 항목은 매개변수를 받고 Feature는 받지 않으므로 attach_egress_allowlist는 아무것도 첨부하지 않으며, 이 값이 true이면 가져오기는 feature-not-attached로 경고합니다. layout: nodes는 노드별이 설명하는 대로 각 노드를 개별 Component로 초안 작성하며 애플리케이션을 담지 않습니다.
CrewAI 임포터
importer/crewai는 CrewAI 프로젝트가 구성 파일에 선언한 에이전트와 태스크를 읽고, 에이전트마다 표준 라이브러리의 CrewAI 에이전트인
core/ai-agent/crewai의 인스턴스 하나를 담고 각각을 구성이 지정한 모델에 연결한 Aggregate와, 그 옆에 Release를
초안으로 작성합니다.
읽는 내용
CrewAI는 크루의 동작을 프로그램에 두고 에이전트와 태스크를 두 가지 레이아웃 중 하나로 구성 파일에 선언하며, 임포터는 어느 쪽이든 읽습니다.
- 클래식 프로젝트 — 각 에이전트를 이름을 키로 하는
config/agents.yaml과, 각 태스크를 이름을 키로 하는config/tasks.yaml이며, 둘 다 YAML로 읽습니다. 에이전트는agents.yaml이 작성한 순서로 읽습니다. - JSON 우선 레이아웃의 프로젝트 — 크루의 에이전트를
agents아래에 이름으로, 태스크를tasks아래에 나열하는crew.jsonc와, 에이전트마다 하나씩인agents/<name>.jsonc이며, 모두 주석이 있는 JSON으로 읽으므로 주석과 후행 쉼표를 CrewAI가 읽는 방식대로 읽습니다. 에이전트는crew.jsonc가 나열한 순서로 읽고, 그 뒤에 다른 에이전트 파일을 이름 순으로 읽습니다. 크루가 나열했지만 임포트에 파일이 전달되지 않은 에이전트는 주석에 이름이 기재되며 아무것도 초안으로 작성되지 않습니다. 같은 레이아웃을 엄격한 JSON으로 작성한 것 —crew.json과agents/<name>.json— 도 같은 방식으로 읽습니다. 크루나 에이전트가 두 표기 모두로 작성된 경우 CrewAI가 읽는 것처럼.jsonc파일을 읽고,.json파일은 읽지 않았다고 주석에 기재됩니다.
에이전트에서는 role, goal, backstory를 읽고, 선언의 최상위 또는 settings 아래에 있는
allow_delegation과 verbose를 CrewAI가 읽는 방식대로 settings를 우선하여 읽으며, llm과
tools의 이름을 읽습니다. 태스크에서는 이름과 할당된 에이전트를 읽습니다. 그 밖의 모든 멤버는
주석에 이름이 기재되며 어디에도 옮겨지지 않습니다.
디렉터리는 시그니처가 지정하는 파일만으로 임포터에 전달되므로, 크루의 프로그램 — 클래식
프로젝트의 crew.py, 플로의 main.py, 프로젝트가 Python으로 정의한 도구 — 은 결코 읽지 않습니다.
단독으로 임포트된 파일은 그 형태에 해당하는 선언으로 읽습니다. 프로젝트 디렉터리에는 여러 크루가
있을 수 있으며, 각각 자체 디렉터리에서 읽습니다.
프로젝트의 변환 결과
aggregate.yaml은 초안의 이름을 정하는 방식에서 설명하는 대로 크루의 이름을 딴 초안 Aggregate로, 읽은 선언, 크루의 프로그램을 읽지 않았다는 점, 각 크루의 태스크와 각 태스크가 할당된 에이전트를 기재하는 주석으로 시작합니다. 에이전트마다 그 이름을 키로 하여 다음을 갖는 core/ai-agent/crewai 인스턴스를 담습니다.
- 선언된 그대로의
role,goal,backstory. - 선언된 그대로의
allow_delegation, 에이전트가 선언하지 않은 경우false. verbose로 선언된 에이전트는 추론의 각 단계를 서술하는log_levelDEBUG, 그렇지 않은 에이전트는 진행 상황과 문제만 보고하는INFO.true도false도 아닌verbose또는allow_delegation은 Component의 기본값에 맡기고 주석에 기재합니다.llm이 지정하는 모델의 인스턴스에 연결된model연결.
<provider>/<model>로 작성되거나, model, model_name 또는 deployment_name 아래에 모델을
지정하는 객체로 작성된 llm은 프로바이더와 모델을 지정합니다. 모델은 해당 프로바이더에 대한 카탈로그의
Component — 프로바이더 이름의 밑줄을 하이픈으로 읽고 azure를 azure-openai로 읽은
core/ai-model/<provider> — 의 인스턴스로, 모델 이름을 키로 하고 모델을 values.model로 가집니다.
같은 프로바이더와 모델을 지정하는 에이전트들은 인스턴스 하나를 공유합니다. 워크스페이스의 카탈로그에
그 이름의 Component가 없으면 model 값을 선언하는 <target_namespace>/ai-model/<provider>가
초안으로 작성되고, 그 결정에 그렇게 기재됩니다. 에이전트의 model 소켓이 Component를 선택하는 기준인
model.aggrega.ai/api 레이블과, 엔드포인트와 모델을 게시하는 Recipe는 그 시작 부분의 주석이
말하듯 사용자에게 남겨집니다. 프로바이더를 지정하지 않는 llm — 프로그램 실행 시 CrewAI가
프로바이더를 결정하는 단순 모델 이름, 또는 프로그램이 정의한 llm의 이름 — 과 프로그램에 대한 참조,
그리고 llm을 선언하지 않아 CrewAI가 프로그램 실행 환경에서 읽게 되는 에이전트는 아무것에도
연결되지 않으며, 에이전트 위의 주석이 그 이유를 설명합니다. 하나가 연결될 때까지 빌드는
model 소켓을 지목하며 중단됩니다.
태스크는 크루의 프로그램이 실행하는 로직이고 도구는 프로그램이 정의하거나 로드하는 코드이므로,
둘 다 Component가 되지 않습니다. 각각은 아무것도 선택하지 않는 결정으로 보고되며, 이름에서
후행 Tool과 하이픈, 밑줄을 제거한 결과가 카탈로그에 있는 도구 Component의 이름과 같은 도구는
그 Component를 힌트로 가집니다. search_tool과 SearchTool은 모두
core/ai-tool/search를 가리킵니다. core/ai-agent/crewai는 도구용 소켓을 선언하지 않으므로
도구에는 아무것도 연결되지 않습니다.
그 옆의 release.yaml은 같은 이름으로 해당 Aggregate를 지정하는 초안 Release입니다. 각 에이전트의 infra.image(어떤 선언도 지정하지 않는, 크루의 프로그램을 실행하는 이미지)를 그것이 무엇인지 설명하는 주석 아래에 비어 있는 채로 작성하며, 임포트는 이를 제공해야 할 값으로 보고합니다. --target compose를 사용하면 각 에이전트의 항목은 infra.published_port로 8000도 작성합니다. 이는 Component의 infra.port가 프로그램에 대해 기본으로 지정하는 포트로, 그 Compose Recipe가 호스트의 루프백 주소 127.0.0.1에 게시하며, 이 머신에서 실행되는 모든 프로세스가 이 머신에서만 접근할 수 있고 해당 줄을 삭제하면 서비스가 내부에 유지된다고 설명하는 주석 아래에 있습니다. 두 번째 에이전트는 다음 빈 포트를 사용하므로 클래식 프로젝트의 두 에이전트는 8000과 8001에 게시됩니다. 각 에이전트가 모델에 제시하는 자격 증명은 model 연결의 credential 아래에 값이 아닌 참조로 첨부합니다. 어떤 선언도 이를 위한 변수를 지정하지 않으므로, 공급자의 클라이언트 라이브러리가 API 키를 읽는 변수(OpenAI의 경우 OPENAI_API_KEY)에서 읽으며, helm을 제외한 모든 대상에서는 ${…} 참조로, helm에서는 Kubernetes Secret의 이름으로 작성되고, 후자는 비어 있는 채로 작성되어 임포트가 제공해야 할 값으로 보고합니다. compose에서는 에이전트의 model 연결이 그 키로 이를 선언합니다. 각 모델에도 인프라를 담지 않는 항목이 있어 Release가 모델을 에이전트와 함께 배치합니다. llm 객체로 선언된 모델의 경우, 다른 각 멤버는 카탈로그의 Component가 그 이름의 값을 선언하면 모델 인스턴스의 값으로 작성되고, 그렇지 않으면 Release에서 모델 항목 위의 주석에 작성되어 Component가 이를 받는 곳으로 사용자가 옮길 수 있게 합니다. 초안으로 작성되는 모든 Release와 마찬가지로 metadata.environment를 development로 작성하고, 대상이 없으면 임포트가 제공해야 할 값으로 보고하는 빈 spec.manifest를 작성합니다. 대상이 주어지면 대상이 추가하는 것에서 설명하는 대로 임포트가 Manifest를 초안으로 작성합니다.
이 임포터의 테스트가 임포트하는, 두 에이전트가 모두 openai/gpt-4o를 지정하는 클래식 프로젝트는 설정 없이 아래와 같이 초안으로 작성됩니다. 프로젝트 디렉터리인 market_brief(crewai create crew market_brief가 이러한 프로젝트를 배치하는 디렉터리)로 임포트하면, 선언이 크루를 지정하지 않으므로 그 디렉터리의 이름을 따릅니다.
# CrewAI declarations read:# - src/market_brief/config/agents.yaml# - src/market_brief/config/tasks.yaml# Not read: the crew's program, which runs its agents and its tasks and defines its tools; it runs in the image the Release names for each agent.# Tasks the crew's program runs, drafted as no Component:# - research_task, assigned to researcher# - brief_task, assigned to brief_writerapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/market-brief version: 0.1.0 description: Draft Aggregate imported from a source in the crewai format.spec: components: # Tools the crew's program defines or loads for this agent, drafted as no Component: search_tool. researcher: type: core/ai-agent/crewai values: role: "{topic} Market Researcher\u000A" goal: "Gather the facts about {topic} a buyer needs before a first meeting\u000A" backstory: "You have briefed sales teams for years. ..." allow_delegation: false log_level: DEBUG uses: model: gpt-4o: target: gpt-4o # For the compose target only, uncomment the lines below, which declare credential on gpt-4o: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # credential: # type: core/secret-value # values: # key: OPENAI_API_KEY # The agent brief_writer. # Not carried, since core/ai-agent/crewai takes no value for it: max_iter. brief-writer: type: core/ai-agent/crewai ... # The model openai/gpt-4o. gpt-4o: type: core/ai-model/openai values: model: "gpt-4o"그리고 대상 없이 초안으로 작성된 그 Release는 아래와 같으며, 두 번째 에이전트의 항목은 여기서 생략하고 ...로 표시했습니다. 임포트는 spec.manifest와 각 에이전트의 이미지를 제공해야 할 값으로 보고합니다.
spec: aggregate: imported/market-brief # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: researcher: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the crew's program image: "" uses: model: gpt-4o: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential researcher presents to gpt-4o on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" brief-writer: ... gpt-4o: {}그러면 각 에이전트는 답변한 이미지를 실행하도록 렌더링되며, 모델의 엔드포인트와 모델 이름을 CrewAI가 읽는 변수인 OPENAI_BASE_URL과 MODEL로 받습니다.
선언이 담는 자격 증명 값
객체로 작성된 llm은 api_key 아래, 주소, 헤더 등에 키를 담을 수 있습니다. 모델을 지정하는 멤버를 제외한, 숫자나 불리언이 아닌 각 멤버는 키를 담을 수 있는 값이며, CrewAI는 이를 자격 증명으로 표시하지 않습니다. 기본적으로 값을 가진 각 멤버는 작성된 그대로 옮겨지며(Component가 값을 선언하는 경우 모델 인스턴스의 값으로, 그렇지 않으면 Release에서 모델 항목 위의 주석으로), credential-carried 경고에 값이 아니라 에이전트와 llm.api_key 같은 멤버로 기재됩니다. empty_credentials 설정이 all이면 각각 값 없이 작성되고 credential-emptied로 보고되며, marked이면 CrewAI가 아무것도 표시하지 않으므로 각각 옮겨집니다. 멤버의 이름은 그 의미로 해석되지 않습니다. 초안이 옮기지 않는, 선언이 담는 그 밖의 모든 멤버 — 도구의 구성, 크루의 inputs — 는 이름만 기재되고 값은 기재되지 않습니다.
읽는 설정
CrewAI 임포터는 설정에서 설명하는 target_namespace, empty_credentials,
render_mode를 읽으며, 그 밖의 설정은 읽지 않습니다.
LangGraph 임포터
importer/langgraph는 LangGraph 애플리케이션의 구성 파일인 langgraph.json이 선언하는 그래프를 읽고, 그래프마다 표준 라이브러리의 LangGraph 에이전트인 core/ai-agent/langgraph 인스턴스를 하나씩 담은 Aggregate를 초안으로 작성합니다. 각 인스턴스는 체크포인터가 상태를 보관하는 데이터 저장소와 모델에 연결되며, 구성이 명시하는 환경을 담은 Release가 그 옆에 함께 작성됩니다. 임포터는 그 구성을 읽으며, 그래프의 코드는 결코 읽지 않습니다.
읽는 내용
LangGraph 애플리케이션은 그래프를 코드에 두고 langgraph.json에서 선언합니다.
graphs 아래에서 각 그래프의 id는 애플리케이션 코드 안의 그래프 임포트 경로 —
./src/agent/graph.py:graph 또는 module:attr — 에 대응하거나, path 아래에 그 경로를 지정하고
description 아래에 그래프를 설명하는 객체에 대응합니다. 임포터는 구성이 작성한
순서대로 다음을 읽습니다.
graphs— 각 그래프의 id, 임포트 경로, 설명;checkpointer— 그backend: PostgreSQL이며 아무것도 지정되지 않았을 때 LangGraph가 읽는 값인default, MongoDB의 프로토콜을 사용하는 데이터베이스인mongo, 또는 애플리케이션 코드가path에 정의하는 체크포인터인custom;store— 백엔드를 지정하지 않는 메모리 저장소: LangGraph는 이를 서버가 사용하는 PostgreSQL 데이터베이스에 보관합니다;env— 애플리케이션이 실행되는 환경: 변수 이름을 값에 대응시키는 객체, 또는KEY=VALUE줄로 이루어진 환경 파일의 경로.
langgraph build가 빌드하는 서버 이미지를 구성하는 멤버 — dependencies, source, python_version, node_version, base_image, image_distro, dockerfile_lines, pip_config_file, pip_installer, keep_pkg_tools, api_version — 는 주석에 이름만 남고 어디에도 전달되지 않습니다. Release가 지정하는 이미지는 애플리케이션 자체의 이미지이기 때문입니다. auth, http, webhooks 같은 서버 자체의 구성을 포함한 그 밖의 모든 멤버도 마찬가지이며, 저장소의 index와 ttl, 체크포인터의 ttl과 serde도 마찬가지입니다.
디렉터리는 langgraph.json만 임포터에 전달되고 다른 파일은 전달되지 않으므로,
애플리케이션 코드도 환경 파일도 디렉터리에서 읽히지 않습니다. 환경 파일은
임포터의 with.sources가 전달하는 경우에만 임포터에 도달하며, 결코 파싱되지 않습니다.
구성의 env가 지정하는 파일 — 지정된 경로의 마지막 세그먼트로 매칭됩니다 — 에서는 변수의
이름만 읽히며, 어떤 구성도 지정하지 않는 환경 파일은 읽지 않았다고 주석에 명시됩니다.
구성이 지정하는 파일이 임포트에 전달되지 않은 경우, Aggregate는 그 파일을 전달되지 않았다고 명시하고
임포터의 with.sources 아래에 지정하라고 안내하며, 그 변수는 Release에 맡겨집니다.
plugins: importer: - uri: importer/langgraph:<version> with: sources: - ./local.env단독으로 임포트된 구성은 이름과 관계없이 읽힙니다. 디렉터리에는 여러 애플리케이션이 있을 수 있으며, 각각 자체 디렉터리에서 읽힙니다.
애플리케이션이 변환되는 결과
aggregate.yaml은 초안의 이름을 정하는 방식에서 설명하는 대로 그래프의 이름을 딴 초안 Aggregate이며, 읽은 구성, 이름만 읽은 환경 파일, 애플리케이션 코드는 읽지 않았다는 점, 초안이 담지 않는 내용을 명시하는 주석으로 시작합니다. 여기에는 그래프마다, 그 id를 키로 하는 core/ai-agent/langgraph 인스턴스가 다음과 함께 들어 있습니다.
graph_entrypoint: 구성이 작성한 그대로의 그래프 임포트 경로;description: 구성이 제공하는 경우 그래프의 설명;- 애플리케이션의 데이터 저장소에 연결된
checkpointer_db연결; - 애플리케이션의 모델에 연결된
model연결.
recursion_limit은 작성되지 않으므로 Component의 기본값인 25가 유지됩니다. 구성은 모델을 지정하지 않으므로, 초안은 model을 키로 하는 core/ai-model/openai 인스턴스 하나를 담으며, 모든 그래프가 이를 호출합니다. 이는 에이전트의 OpenAI 클라이언트에 전달되는 모델입니다. 그 values.model은 구성이 모델을 지정하지 않는다고 설명하는 주석 아래에 비어 있는 채로 작성되며, 임포트는 이를 제공해야 할 값으로 보고합니다.
체크포인터의 백엔드는 애플리케이션의 모든 그래프가 연결되는 데이터 저장소입니다. default 또는 백엔드를 지정하지 않는 체크포인터는 postgres를 키로 하는 core/datastore/postgres의 인스턴스입니다. mongo는 MongoDB의 프로토콜을 사용하는 FerretDB로, DocumentDB 확장이 있는 PostgreSQL 위에서 동작합니다. 즉 모든 그래프가 연결되는 ferretdb를 키로 하는 core/datastore/ferretdb의 인스턴스와, FerretDB의 backend 연결이 도달하는 documentdb를 키로 하는 core/datastore/documentdb의 인스턴스이며, 그 inject 블록은 DocumentDB가 게시하는 것을 FerretDB가 읽는 이름으로 전달합니다. 변수 FERRETDB_PASSWORD에서 읽는 비밀번호 하나가 DocumentDB, FerretDB에서 DocumentDB로의 연결, 그리고 각 그래프에서 FerretDB로의 연결에 첨부됩니다. 작업 공간의 카탈로그에 PostgreSQL 데이터 저장소 이름의 Component가 없으면 <target_namespace>/datastore/postgres이 초안으로 작성되어, 에이전트의 checkpointer_db 연결이 읽는 host와 port를 선언하며, 그 결정에 그렇게 명시됩니다. 데이터 저장소를 실행하고 이를 게시하는 Recipe는 그 첫머리의 주석이 안내하듯 사용자에게 맡겨집니다. 카탈로그에 FerretDB 또는 DocumentDB Component가 없으면 mongo 체크포인터는 어떤 데이터 저장소에도 연결되지 않습니다. custom 체크포인터 또는 임포터가 어떤 데이터 저장소에도 대응시키지 않는 백엔드는 아무것도 연결하지 않으며, 각 그래프 위의 주석과 체크포인터의 결정이 그 이유를 설명합니다. 하나가 연결될 때까지 빌드는 checkpointer_db 소켓을 명시하며 중단됩니다. 저장소는 아무것도 선택하지 않는 결정으로 보고됩니다.
데이터 저장소의 비밀번호는 초안이 참조로 첨부하는 시크릿으로, 데이터 저장소 자체의 password 슬롯과 각 그래프의 checkpointer_db 연결에 첨부되며, 각 그래프가 model 연결에서 모델에 제시하는 자격 증명도 마찬가지입니다. 구성이 둘 다 변수를 지정하지 않으므로 각각 POSTGRES_PASSWORD(또는 FERRETDB_PASSWORD)와 OPENAI_API_KEY에서 읽으며, helm을 제외한 모든 대상에서는 ${…} 참조로, helm에서는 Kubernetes Secret의 이름으로 작성되고, 후자는 비어 있는 채로 작성되어 임포트가 제공해야 할 값으로 보고합니다. compose에서는 대상별 시크릿이 플랫폼에 대해 설명하는 대로 Aggregate가 각각을 해당 Recipe가 읽는 키로 선언합니다.
그 옆의 release.yaml은 같은 이름으로 그 Aggregate를 지정하는 초안 Release입니다. 첫 번째 그래프 항목 위의 주석은 각 그래프의 이미지가 무엇인지 — 애플리케이션 자체의 이미지, 즉 LangGraph가 설치된 애플리케이션 코드이며 langgraph build가 빌드하는 서버 이미지가 아님 —, 그 이미지에 전달되는 변수, 그리고 어떤 inject: 블록이 그 변수 이름 중 어느 것을 대체하는지를 설명합니다. 각 그래프 항목은 그 infra.image, 즉 애플리케이션을 실행하는 이미지를 그것이 무엇인지 설명하는 주석 아래에 비어 있는 채로 작성하며, 임포트는 이를 제공해야 할 값으로 보고합니다. 이것이 설정되지 않은 동안 Docker Compose Recipe는 카탈로그 자체의 퀵스타트 에이전트를 실행하며, 이 에이전트는 기본 변수를 읽습니다. --target compose를 사용하면 각 그래프의 항목은 infra.published_port로 8000도 작성합니다. 이는 Component의 infra.port가 애플리케이션에 대해 기본으로 지정하는 포트로, 그 Compose Recipe가 호스트의 루프백 주소 127.0.0.1에 게시하며, 이 머신에서 실행되는 모든 프로세스가 이 머신에서만 접근할 수 있고 해당 줄을 삭제하면 서비스가 내부에 유지된다고 설명하는 주석 아래에 있습니다. 두 번째 그래프는 다음 빈 포트를 사용합니다. 데이터 저장소와 모델에도 항목이 있으므로 Release는 이를 그래프들과 함께 배치합니다. 애플리케이션의 첫 번째 그래프 위의 주석은 구성이 명시하는 환경에서 설명하듯 구성이 선언하는 환경을 명시합니다. 초안으로 작성되는 모든 Release와 마찬가지로 metadata.environment를 development로 작성하고, 대상이 없으면 임포트가 제공해야 할 값으로 보고하는 빈 spec.manifest를 작성합니다. 대상이 주어지면 대상이 추가하는 것에서 설명하는 대로 임포트가 Manifest를 초안으로 작성합니다.
이 임포터의 테스트가 임포트하는 Python 애플리케이션은 두 개의 그래프, 백엔드를 지정하지 않는 체크포인터, 저장소, 객체로 작성된 env를 선언하며, 설정 없이 아래와 같이 초안으로 작성됩니다. 디렉터리인 support_desk(여기서처럼 그래프가 정의된 패키지의 이름을 딴 디렉터리)로 임포트하면, id가 서로 다른 두 그래프가 있으므로 그 디렉터리의 이름을 따릅니다.
# LangGraph configurations read:# - langgraph.json# Not read: the application's code, which defines each graph; it runs in the image the Release names for each graph.# Not carried, since they configure the server image langgraph build builds, and the image the Release names is the application's own: dependencies, python_version.# Not carried, since core/ai-agent/langgraph takes no value for them: http.# The store configures the memory store, which LangGraph keeps in the PostgreSQL database its server uses; not carried, since core/ai-agent/langgraph takes no value for it: index, ttl.# Not carried, since core/ai-agent/langgraph takes no value for them: checkpointer.ttl.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/support-desk version: 0.1.0 description: Draft Aggregate imported from a source in the langgraph format.spec: components: triage: type: core/ai-agent/langgraph values: graph_entrypoint: "./src/support_desk/triage.py:make_graph" description: "Routes an incoming ticket to the {team} that owns it." uses: checkpointer_db: postgres: target: postgres # For the compose target only, uncomment the lines below, which declare credential on postgres: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # credential: # type: core/secret-value # values: # key: POSTGRES_PASSWORD model: model: target: model # For the compose target only, uncomment the lines below, ... support: type: core/ai-agent/langgraph ... # The database the configuration's checkpointer keeps each graph's state in, PostgreSQL. postgres: type: core/datastore/postgres # For the compose target only, uncomment the lines below, ... # The model every graph calls, which the configuration does not name. model: type: core/ai-model/openai values: # Left for the author, since the configuration names no model: values.model, the name of the model core/ai-model/openai serves. model: ""spec: aggregate: imported/support-desk # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: # Each graph's image is the application's own, not the server image langgraph build builds: its code, with LangGraph installed. # It is handed, for its code to read, the graph to run as LANGGRAPH_GRAPH_ENTRYPOINT, the model's name as OPENAI_MODEL, the checkpointer store's host and port as LANGGRAPH_CHECKPOINTER_HOST and LANGGRAPH_CHECKPOINTER_PORT, its user and database, where the store publishes them, as LANGGRAPH_CHECKPOINTER_USER and LANGGRAPH_CHECKPOINTER_DATABASE, and a password attached on the checkpointer_db connection as LANGGRAPH_CHECKPOINTER_PASSWORD. # It is also handed the model's address as OPENAI_BASE_URL and a key attached on the model connection as OPENAI_API_KEY, which the OpenAI client library reads, and recursion_limit as LANGGRAPH_DEFAULT_RECURSION_LIMIT, which LangGraph reads. # An inject: block on the graph's own instance, through an entry reading graph_entrypoint alone, replaces LANGGRAPH_GRAPH_ENTRYPOINT with the name it writes; one on the model connection replaces OPENAI_MODEL, and one on the checkpointer_db connection the store's host, port, user and database, with the names it writes. # The environment langgraph.json states for its application, for the Release to carry where core/ai-agent/langgraph takes it for each of its graphs: # SUPPORT_QUEUE: "..." # OPENAI_API_KEY: "..." # MAX_TICKETS: "25" triage: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the application image: "" uses: checkpointer_db: postgres: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential triage presents to postgres on its checkpointer_db connection, the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${POSTGRES_PASSWORD}" model: model: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential triage presents to model on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" ... postgres: features: password: type: core/secret-value infra: # Attached by reference, never as a value: the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${POSTGRES_PASSWORD}" model: {}임포트는 네 가지 값을 제공해야 할 값으로 보고합니다. spec.manifest, 각 그래프의 이미지, 그리고 모델의 이름입니다. 이에 답변하면 각 그래프는 답변한 이미지를 실행하도록 렌더링되며, 데이터 저장소의 주소를 LANGGRAPH_CHECKPOINTER_HOST와 LANGGRAPH_CHECKPOINTER_PORT로, 데이터 저장소가 게시하는 사용자와 데이터베이스를 LANGGRAPH_CHECKPOINTER_USER와 LANGGRAPH_CHECKPOINTER_DATABASE로(PostgreSQL은 둘 다 게시하며, 둘 다 게시하지 않는 데이터 저장소에서는 두 변수 모두 렌더링되지 않습니다), 모델의 엔드포인트와 이름을 OPENAI_BASE_URL과 OPENAI_MODEL로, 모델 자격 증명이 전달하는 키를 OPENAI_API_KEY로, 임포트 경로를 LANGGRAPH_GRAPH_ENTRYPOINT로, 단계 한도를 LANGGRAPH_DEFAULT_RECURSION_LIMIT로 전달받습니다. checkpointer_db 연결에 첨부된 자격 증명은 데이터 저장소의 비밀번호도 LANGGRAPH_CHECKPOINTER_PASSWORD로 전달합니다.
구성이 명시하는 환경
구성의 env가 지정하는 모든 변수는 Release가 제공할 입력이며, 어느 것도
자격 증명 슬롯으로 초안 작성되지 않습니다. LangGraph는 어떤 변수도 비밀로 표시하지 않으며, 변수의 이름은
그 의미로 해석되지 않습니다. core/ai-agent/langgraph는 환경에 대한 값을 받지 않으므로, Release는
애플리케이션의 첫 번째 그래프 위의 주석에 이를 명시합니다.
- **객체로 작성된
env**는 구성의 일부이므로, 그 값은 구성이 작성한 순서대로 작성된 그대로 그 주석에 담깁니다. 무언가를 담은 각 값은 자격 증명을 담을 수 있으며, LangGraph는 어느 것도 자격 증명으로 표시하지 않습니다. 기본적으로 각 값은 작성된 그대로 담기며,credential-carried경고에 그 구성과 변수로 — 예를 들어env.OPENAI_API_KEY— 명시되고, 값으로는 결코 명시되지 않습니다.empty_credentials설정이all이면 각 값은 값 없이 작성되고credential-emptied로 보고됩니다.marked이면 LangGraph가 아무것도 표시하지 않으므로 각 값이 담깁니다. - **파일을 지정하는
env**는 구성이 가리키기만 하는 파일을 지정하며, 이 파일에는 흔히 로컬 비밀이 담겨 있습니다. 이 파일은 임포터의with.sources가 전달하는 경우에만 읽힙니다. 주석은 파일이 지정하는 각 변수를 Release가 제공하도록 남겨 두고 명시하며, 파일의 어떤 값도 읽히지 않습니다. 설정이 무엇이든 어떤 값도 초안, 결정, 진단에 도달하지 않습니다. 여러 줄에 걸쳐 인용된 값은 하나의 값이므로 그 안의 줄은 결코 변수로 간주되지 않으며, 변수를 지정하지 않는 줄은 줄 번호로 명시됩니다. 파일이 임포트에 전달되지 않은 경우 — 파일을 전달하지 않는 디렉터리는 항상 그렇습니다 — Aggregate는 그 파일을 전달되지 않았다고 명시하며 전달하는 방법을 함께 안내하고, 그 변수는 Release에 맡겨집니다.
읽는 설정
LangGraph 임포터는 설정에서 설명하는 target_namespace, empty_credentials, render_mode를
읽으며, 그 밖의 설정은 읽지 않습니다.
Google ADK 임포터
importer/google-adk는 Google의 Agent Development Kit(ADK)로 구축된 애플리케이션이 Agent Config 파일 — root_agent.yaml과 그 하위 에이전트가 지정하는 구성 — 에 선언한 에이전트를 읽고, 에이전트 트리마다 표준 라이브러리의 ADK 에이전트 core/ai-agent/google-adk 인스턴스 하나를 담아 ADK가 그 요청을 Gemini API로 보내는 경우 트리가 지정하는 모델에 연결한 Aggregate와, 그 옆에 Release를 초안으로 작성합니다. 임포터는 이 구성을 읽으며, 애플리케이션의 코드는 읽지 않습니다.
ADK는 Agent Config 기능이 실험적이라고 명시합니다. 에이전트의 모델은 기본적으로 Gemini 모델입니다. ADK는 일부 다른 제공자의 모델을 claude-sonnet-4-5, gpt-4o처럼 자체 클래스를 통해 이름으로 제공하고, 그 밖의 모델은 LiteLLM 모델 문자열을 통해 제공합니다. 에이전트의 model 소켓은 Gemini API만 허용하므로, 임포터는 ADK가 Gemini API로 보내는 모델을 연결하고 그 밖의 모델은 사용자에게 맡깁니다. 이는 에이전트 트리가 무엇이 되는가에서 설명합니다.
읽는 내용
ADK의 adk create --type=config는 애플리케이션 루트 에이전트의 구성인 root_agent.yaml과
그 옆의 환경 파일을 작성합니다. 구성 하나는 에이전트 하나를 선언합니다.
name,description,agent_class— ADK가 에이전트를 빌드할 클래스이며, 지정하지 않으면LlmAgent입니다;model— 에이전트가 요청하는 모델 — 또는 모델을 빌드하는 코드에 대한 참조인model_code;tools— 각 도구를name으로, 구성이 넘기는args와 함께;generate_content_config— 에이전트 모델 요청의 옵션이며, 그중http_options가 있습니다;sub_agents— 각 항목은 이를 지정하는 구성의 디렉터리를 기준으로 한 다른 구성의 경로인config_path이거나, 애플리케이션 코드가 빌드하는 에이전트인code입니다.
디렉터리는 그 안의 root_agent.yaml 파일로만 임포터에 전달되며 다른 파일은 전달되지 않고,
단독으로 임포트된 구성은 이름과 관계없이 루트로 읽힙니다. 각 루트의 트리는 루트부터 읽히며, 각 에이전트의 하위 에이전트는 나열된 순서대로 읽힙니다. sub_agents 항목이
config_path로 지정하는 구성은 임포터의 with.sources가 전달하는 경우에만 읽히며, 경로의 마지막 세그먼트로 대조됩니다.
임포트에 전달되지 않은 구성은 Aggregate와 그 결정에 전달 방법과 함께 전달되지 않았다고 명시되며, 그 에이전트는 읽히지 않습니다.
plugins: importer: - uri: importer/google-adk:<version> with: sources: - ./my_agent/code_tutor_agent.yaml - ./my_agent/math_tutor_agent.yaml절대 경로이거나 이를 지정하는 구성의 디렉터리 밖으로 벗어나는 config_path는 ADK도 거부하므로
읽히지 않습니다. with.sources가 전달했지만 어떤 구성도 지정하지 않는 파일은 주석에 읽지 않았다고 명시되며,
그 내용은 전혀 읽히지 않습니다. 전달된 파일은 루트의 트리가 지정하는 구성으로만 읽히므로, root_agent.yaml도 단독으로 임포트된 파일도 없는 임포트는 트리를 읽지 않으며
각 파일을 no-nodes로 보고합니다. 애플리케이션의 코드 — 구성이 코드로 지정하는 도구, 콜백, 스키마, 에이전트 — 와
환경 파일은 전달되지 않으며 임포터는 어느 쪽도 읽지 않습니다. 애플리케이션은 Release가 지정하는 이미지에서 구성을 직접 로드합니다.
디렉터리는 여러 애플리케이션을 담을 수 있으며, 각각은 자체 root_agent.yaml에서 읽힙니다.
구성의 다른 멤버 — 그중 에이전트의 instruction — 는 애플리케이션이 자체 구성에서 읽으므로,
초안은 이들을 전혀 담지 않습니다.
에이전트 트리가 무엇이 되는가
ADK는 애플리케이션을 루트 에이전트에서 제공하며, 구성이 지정하는 모든 에이전트는 그 안에 빌드됩니다. core/ai-agent/google-adk는 그러한 애플리케이션 하나를 실행합니다. 따라서 초안의 이름을 정하는 방식에서 설명하는 대로 루트 에이전트의 이름을 딴 초안 Aggregate인 aggregate.yaml은 에이전트 트리마다, 루트 에이전트의 이름을 키로 하여, 다음을 갖춘 core/ai-agent/google-adk 인스턴스를 담습니다.
description: 구성이 제공하는 경우 루트 에이전트의 설명;- ADK가 그 요청을 Gemini API로 보내는 경우 트리가 지정하는 모델에 연결된
model연결.
그 위의 주석은 자체 인스턴스가 되지 않는 트리의 다른 에이전트, 읽히지 않은 각 하위 에이전트와 그 이유 — 애플리케이션 코드가 빌드함, 임포트에 전달되지 않은 구성, 또는 ADK가 거부하는 구성 —, 트리의 에이전트가 지정하는 도구 중 ADK가 제공하는 것과 애플리케이션 코드가 정의하는 것, ADK가 Workflow를 위해 폐기 예정으로 지정한 클래스 — LoopAgent, ParallelAgent, SequentialAgent — 의 에이전트, 그리고 트리의 모델이 연결된 경우 트리의 다른 에이전트가 요청하는 모델을 각각 ADK가 그 모델을 제공하는 패밀리와 함께 명시합니다. 각각은 아무것도 선택하지 않는 결정으로 보고됩니다.
루트부터 시작하여 모델 또는 모델을 빌드하는 코드를 지정하는 트리의 첫 번째 에이전트가 인스턴스의 모델을 결정합니다. 지정된 모델 중 ADK가 그 요청을 Gemini API로 보내는 모델 — ADK가 Gemini 클래스를 통해 제공하는 모델 이름(예: gemini-2.5-flash)으로서 Vertex AI 리소스 이름이 아닌 것, 또는 Gemma 클래스를 통해 제공하는 모델 이름 — 은 그 모델을 제공하고 그 모델을 키로 하는 core/ai-model/gemini 인스턴스이며, 같은 모델을 지정하는 트리는 인스턴스 하나를 공유합니다. 워크스페이스의 카탈로그에 core/ai-model/gemini가 없으면 에이전트의 model 소켓이 선택하는 model.aggrega.ai/api: gemini 레이블을 지닌 <target_namespace>/ai-model/gemini가 초안으로 작성되며, 그 결정이 이를 명시합니다. 엔드포인트와 모델을 게시하는 Recipe는 그 첫머리의 주석이 말하듯 직접 작성하도록 남겨집니다. ADK가 그 밖의 방식으로 제공하는 모델 — openai/gpt-4o 같은 LiteLLM 모델 문자열, Vertex AI 리소스 이름, 또는 ADK가 Anthropic이나 OpenAI를 통해 제공하는 claude-sonnet-4-5나 gpt-4o 같은 이름 — 은 아무것에도 연결되지 않습니다. 에이전트의 model 소켓은 Gemini 모델을 받으며 에이전트는 환경에서 모델 이름을 읽지 않으므로, 그곳에 Gemini 모델을 연결하고 에이전트의 구성에서 그 모델을 지정해야 합니다. 인스턴스 위의 주석과 루트 에이전트의 결정은 그 모델과 ADK가 그 모델을 제공하는 패밀리를 명시합니다. 애플리케이션의 코드가 빌드하는 모델이나 모델을 지정하지 않는 트리 — 이 경우 ADK는 기본 모델을 사용합니다 — 도 아무것에도 연결되지 않으며, 인스턴스 위의 주석이 그 이유를 설명합니다. 모델이 아무것에도 연결되지 않은 모든 경우, 연결될 때까지 빌드는 model 소켓을 명시하며 중단됩니다. 트리의 다른 에이전트가 요청하는 모델 중 ADK가 그 요청을 Gemini API로 보내는 모델에는 별도의 연결이 필요 없습니다. ADK의 Gemini 클라이언트는 인스턴스의 연결이 전달하는 키로 그 요청을 보냅니다. 애플리케이션이 Gemini API를 통해 Gemini에 접근할지 Vertex AI를 통해 접근할지는 임포트가 읽지 않는 환경에 의해 선택되며, 에이전트의 model 소켓은 Gemini API만 허용합니다.
이 임포터의 테스트는 openai/gpt-4o를 지정하는 단독 루트 에이전트도 임포트하며, 그 인스턴스는 다음과 같이 초안으로 작성됩니다:
spec: components: # The agent tree of root_agent.yaml, served from its root agent routed_agent. # The model connection is left for the author, since the model openai/gpt-4o, which routed_agent names, is one ADK serves through LiteLLM, not through the Gemini API, while core/ai-agent/google-adk takes a Gemini model on its model socket and reads no model name from its environment, so the author wires a Gemini model there and names that model in routed_agent's configuration; the build halts naming the socket until one is wired. routed-agent: type: core/ai-agent/google-adk values: description: "Answers questions with a model another provider serves."그 옆의 release.yaml은 그 Aggregate를 지정하는 같은 이름의 초안 Release입니다. 각 인스턴스의 항목은 infra.image — 구성을 담고 있는, ADK로 구축된 애플리케이션을 실행하는 이미지 — 를 그것이 무엇인지 알리는 주석 아래에 비워 두고 작성하며, 임포트는 이를 아직 필요한 값으로 남깁니다. --target compose를 지정하면 항목은 infra.published_port도 8000으로 작성합니다. 이는 애플리케이션이 수신 대기하는 포트로, 그 Compose Recipe가 호스트의 루프백 주소 127.0.0.1에 게시하며, 그 위의 주석은 이 포트가 이 머신에서만, 그 위에서 실행되는 모든 프로세스가 접근할 수 있고 이 줄을 삭제하면 서비스가 내부에 머문다는 것을 알립니다. 두 번째 트리는 다음 빈 포트를 받습니다. 모델이 연결된 경우 항목은 인스턴스가 그 모델에 제시하는 자격 증명을 model 연결의 credential 아래에 값이 아니라 항상 참조로 첨부합니다. 어떤 구성도 이를 위한 변수를 지정하지 않으므로, 자격 증명은 Google의 Gemini API 클라이언트 라이브러리가 키를 읽는 변수인 GOOGLE_API_KEY에서 읽으며, helm을 제외한 모든 대상에서는 ${…} 참조로, helm에서는 Kubernetes Secret의 이름으로 작성되고, 비워 둔 채 작성되어 임포트가 아직 필요한 값으로 남깁니다. compose에서는 model 연결이 그 키로 이를 선언합니다. 연결된 모델에도 항목이 있으며, 이 항목은 인프라를 담고 있지 않으므로 Release는 이를 인스턴스와 함께 배치합니다. 트리의 구성이 도구와 모델 요청에 넘기는 값은 구성이 담고 있는 자격 증명 값이 설명하듯 항목 위의 주석에 기록됩니다. 초안으로 작성되는 모든 Release와 마찬가지로 metadata.environment를 development로 작성하고, 대상이 없으면 임포트가 아직 필요한 값으로 남기는 빈 spec.manifest를 작성합니다. 대상이 주어지면 대상이 추가하는 것이 설명하듯 임포트가 Manifest를 초안으로 작성합니다.
이 임포터의 테스트가 임포트하는 애플리케이션, 즉 두 하위 에이전트의 구성과 코드로 빌드되는 하위 에이전트 하나를 지정하는 루트 에이전트를, 두 구성을 with.sources에 지정하여 디렉터리로 임포트하면 설정 없이 루트 에이전트의 이름인 tutor_root로 다음과 같이 초안이 작성됩니다.
# Google ADK agent configurations read:# - root_agent.yaml# - code_tutor_agent.yaml# - math_tutor_agent.yaml# Not read: the application's code, which defines the tools, callbacks and agents a configuration names by their code, nor the environment file ADK's scaffold writes beside root_agent.yaml; the application runs in the image the Release names for each instance, and loads its configurations itself.# ADK states that its Agent Config is experimental. An agent's model is a Gemini model by default; ADK serves some other providers' models by name through classes of its own, such as claude-sonnet-4-5 and gpt-4o, and others through a LiteLLM model string.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/tutor-root version: 0.1.0 description: Draft Aggregate imported from a source in the google-adk format.spec: components: # The agent tree of root_agent.yaml, served from its root agent tutor_root. # Sub-agents ADK builds inside this application, drafted as no instance of their own: code_tutor_agent, math_tutor_agent. # Not read: a sub-agent of tutor_root, which is built by the application's code at tutor_agents.review_agent, which the import does not read. # Tools ADK ships, which run inside the application, drafted as no Component: google_search. # Tools the application's code defines, drafted as no Component: tutor_tools.make_snippet_runner. # Models other agents of the tree ask for, ...: gemini-pro-latest (math_tutor_agent, served through Gemini). tutor-root: type: core/ai-agent/google-adk values: description: "Learning assistant that tutors {{`{{`}} students }} in code and math." uses: model: gemini-flash-latest: target: gemini-flash-latest # For the compose target only, uncomment the lines below, which declare credential on gemini-flash-latest: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # credential: # type: core/secret-value # values: # key: GOOGLE_API_KEY # The model gemini-flash-latest. gemini-flash-latest: type: core/ai-model/gemini values: model: "gemini-flash-latest"초안이 구성에서 Aggregate로 값이나 주석에 복사하는 텍스트는 각
{{를 결과가 두 중괄호인 액션 {{`{{`}}로 기록하므로, 설명과 주석 속 두 중괄호를 담은 이름은
Aggregate가 평가된 후 기록된 그대로 읽힙니다.
spec: aggregate: imported/tutor-root # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: # The configurations also hand these values to their tools and their model requests, which the application reads from its own configurations, written here for review: # code_tutor_agent tools.tutor_tools.make_snippet_runner.args.api_key: "..." # code_tutor_agent tools.tutor_tools.make_snippet_runner.args.sandbox: "python3.12" # code_tutor_agent tools.tutor_tools.make_snippet_runner.args.timeout_seconds: 20 # math_tutor_agent generate_content_config.http_options.headers: "..." # math_tutor_agent generate_content_config.http_options.timeout: 30000 tutor-root: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on ADK, holding its configurations image: "" uses: model: gemini-flash-latest: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential tutor-root presents to gemini-flash-latest on its model connection (the source names no variable for it, so it is read from the one Google's Gemini API's client libraries read the API key from), read from the variable GOOGLE_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${GOOGLE_API_KEY}" gemini-flash-latest: {}이미지에 대한 답변이 주어지면 인스턴스는 그 이미지를 실행하며 자격 증명을 GOOGLE_API_KEY로 받도록 렌더링되고, ADK의 Gemini 클라이언트가 이를 Gemini API로 보냅니다. 모델은 Gemini API의 주소에 접근하는 Service로 렌더링됩니다.
구성이 담고 있는 자격 증명 값
구성은 도구에 키를 args로 넘기거나, 모델 요청에 generate_content_config의 http_options로 넘길 수 있습니다. 이는 요청의 헤더, 주소, 클라이언트의 인수입니다. 도구의 args와 해당 HTTP 옵션의 각 멤버는 Release에서 인스턴스 항목 위의 주석에 구성이 작성한 그대로 기록되며, 텍스트, 객체 또는 리스트인 멤버는 각각 자격 증명을 담을 수 있지만 ADK는 그중 어느 것도 자격 증명으로 표시하지 않습니다. 기본적으로 각 멤버는 작성된 그대로 전달되고, credential-carried 경고에서 값이 아니라 해당 에이전트와 필드로, 예를 들어
tools.tutor_tools.make_snippet_runner.args.api_key처럼 명시됩니다.
empty_credentials 설정이 all이면 각 멤버는 값 없이 기록되고
credential-emptied로 보고됩니다. marked이면 ADK가 아무것도 표시하지 않으므로 각 멤버가 전달됩니다. 숫자나 불리언은 키를 담지 않으며, 구성이 작성한 그대로 기록됩니다. ADK는 구성 안의 변수 참조를 확장하지 않으므로 모든 값은 작성된 그대로 읽힙니다. ADK의 Gemini 클라이언트가 읽는 키를 흔히 담고 있는 환경 파일은 설정과 관계없이 절대 읽지 않습니다.
읽는 설정
Google ADK 임포터는 Settings에서 설명하는 target_namespace, empty_credentials, render_mode를 읽으며, 그 밖의 설정은 읽지 않습니다.
Agent Framework 임포터
importer/agent-framework는 Microsoft Agent Framework 선언적 에이전트, 즉 Agent Framework 기반 애플리케이션이 에이전트를 로드하는 Prompt 종류의 YAML 문서를 읽고, 표준 라이브러리의 Agent Framework 에이전트인 core/ai-agent/agent-framework의 인스턴스 하나를 담은 Aggregate를 초안으로 작성합니다. 이 인스턴스는 에이전트가 지정하는 OpenAI 모델에 연결되며, 그 옆에 Release도 함께 작성됩니다. 임포터는 선언적 에이전트를 읽으며, 애플리케이션의 코드는 절대 읽지 않습니다. Agent Framework는 선언적 에이전트 패키지를 프리릴리스로 게시합니다.
읽는 내용
선언적 에이전트는 다음을 선언합니다.
name,displayName,description,instructions, 그리고 입력과 출력의 스키마model— 모델의id, 모델을 제공하는provider, 클라이언트가 요청을 보내는 API (apiType), 요청의options, 그리고connection:endpoint에 키를 제시하는key연결(키는key또는apiKey아래에 작성),endpoint에 연결하는remote연결, 애플리케이션이 확인하는 연결을 지정하는reference연결, 또는 아무것도 제시하지 않는anonymous연결tools— 각각 하나의kind를 가집니다. 애플리케이션이 코드를 바인딩하는function, 모델의 provider가 실행하는web_search,file_search또는code_interpreter도구, 또는url에서 접근하는mcp서버입니다. 서버에는 호출에 적용되는approvalMode, 에이전트가 호출할 수 있는 서버의allowedTools, 그리고 자체connection이 함께 지정됩니다.
=Env.NAME으로 작성된 멤버는 애플리케이션이 Agent Framework 자체의 보안 설정인 AgentFactory(safe_mode=False)로 선언적 에이전트를 로드하고 .NET 런타임이 있는 경우에만 Agent Framework가 환경 변수 NAME에서 읽으며, 그렇지 않으면 작성된 그대로 표현식의 텍스트로 취급됩니다. =로 시작하는 그 밖의 멤버는 애플리케이션이 계산하는 표현식입니다. 임포터는 어느 쪽도 읽지 않습니다. 참조는 해당 변수로, 표현식은 표현식으로 명시합니다.
단독으로 가져온 파일은 이름과 관계없이 하나의 선언적 에이전트로 읽히며, 임포터의 with.sources가
넘기는 각 파일은 또 다른 선언적 에이전트로 읽히므로, 한 번의 가져오기로 여러 개의 초안이 작성됩니다.
plugins: importer: - uri: importer/agent-framework:<version> with: sources: - ./agents/triage.yaml - ./agents/writer.yaml디렉터리는 임포터에 절대 넘겨지지 않습니다. 임포터의 시그니처가 파일을 지정하지 않으므로, 형식을 지정하지 않은 디렉터리 가져오기는 이를 인식하지 않으며, --format agent-framework를 지정한 가져오기는 디렉터리의 파일을 열기 전에
An importer that declares no file patterns is handed a directory (파일 패턴을 선언하지 않은 임포터에 디렉터리가 넘겨짐)
로 거부됩니다. 대신 각 선언적 에이전트를 개별 파일로 가져오십시오. Agent Framework가 프롬프트 에이전트를 만들지 않는 소스, 즉 kind가 대소문자와 관계없이 Prompt도 아니고
Agent도 아닌 소스는 no-nodes로 보고됩니다. 애플리케이션의 코드, 즉 각
선언적 에이전트를 로드하는 프로그램과 도구에 바인딩하는 함수는 절대 소스에 포함되지 않습니다.
애플리케이션은 Release가 지정하는 이미지에서 선언적 에이전트를 직접 로드합니다.
선언적 에이전트가 변환되는 결과
초안의 이름을 정하는 방식에서 설명하는 대로 에이전트의 이름을 딴 초안 Aggregate인 aggregate.yaml은 선언적 에이전트마다 그 이름을 키로 하여 다음을 갖춘 core/ai-agent/agent-framework 인스턴스를 담습니다.
display_name과description: 에이전트가 명시하는 경우, 에이전트의displayName과descriptionmodel연결: 해당 모델이 연결되는 경우, 에이전트가 지정하는 모델에 연결됨.
지침, 입력과 출력의 스키마, 템플릿, 메타데이터, 모델 요청의 옵션은 애플리케이션이 선언적 에이전트에서 읽으며, 인스턴스 위의 주석에 명시됩니다. 함수 도구, 모델의 제공자가 실행하는 도구, 그 밖의 종류의 도구도 주석에 명시되며, 아무것도 선택하지 않는 결정으로 보고됩니다.
provider가 OpenAI이고 id를 지정하는 모델은 해당 id를 제공하고 그 id를 키로 하는 core/ai-model/openai 인스턴스가 됩니다. 에이전트의 model 소켓은 OpenAI API를 제공하는 모델을 허용하며, 런타임은 해당 모델의 주소, 이름, 키를 Agent Framework의 OpenAI 클라이언트가 읽는 변수로 전달합니다. 같은 주소의 같은 모델을 지정하는 에이전트들은 하나의 인스턴스를 공유합니다. 워크스페이스의 카탈로그에 core/ai-model/openai가 없으면 에이전트의 model 소켓이 선택하는
model.aggrega.ai/api: openai 레이블을 갖춘 <target_namespace>/ai-model/openai가 초안으로 작성되며, 그 결정에 이 사실이 명시됩니다. 엔드포인트와 모델을 게시하는 Recipe는 그 첫머리의 주석이 말하듯 직접 작성해야 합니다. 참조로 작성된 id는 모델의 values.model을 직접 설정하도록 남겨 두며, 모델 위의 주석에 해당 변수가 명시됩니다. 이 값이 설정될 때까지 빌드는 이를 명시하며 중단됩니다. anonymous 연결은 연결의 unauthenticated: true로 작성됩니다. 그 밖의 제공자(AzureOpenAI, Anthropic)의 모델, 제공자를 참조로 지정하거나 지정하지 않는 모델(이 경우 Agent Framework는 애플리케이션이 설정한 기본 제공자를 사용합니다), 그리고 id를 지정하지 않는 모델은 아무것에도 연결되지 않으며, 인스턴스 위의 주석에 그 이유가 명시됩니다. 모델이 연결될 때까지 빌드는 model 소켓을 명시하며 중단됩니다.
mcp 종류의 도구는 Component로도 연결로도 초안 작성되지 않습니다. Agent Framework는 서버를 호스팅된 도구로 모델의 제공자에게 보내며, 애플리케이션이 아니라 제공자가 그 url에서 서버에 연결합니다. 따라서 이 주소는 제공자에서 연결할 수 있어야 하며, 초안이 배포하는 어떤 것도 서버에 연결하지 않습니다. 에이전트 인스턴스 위의 주석은 서버를 명시하고, 그 사실을 밝히며, 선언적 에이전트가 서버에 대해 명시하는 설명, approvalMode, allowedTools를 명시합니다. 서버의 url은 Release에서 에이전트 항목 위의 주석에 전체가 기록되며, 그 결정은 아무것도 선택하지 않습니다.
그 옆의 release.yaml은 해당 Aggregate를 지정하는 같은 이름의 초안 Release입니다. 에이전트의 항목은 infra.image(선언적 에이전트를 담고 있는, Agent Framework 기반 애플리케이션을 실행하는 이미지)를 그것이 무엇인지 알리는 주석 아래에 비워 두고 작성하며, 임포트는 이를 아직 필요한 값으로 남깁니다. --target compose를 사용하면 항목은 infra.published_port로 8000도 작성합니다. 이는 Component의 infra.port가 애플리케이션에 대해 기본으로 지정하는 포트로, 그 Compose Recipe가 호스트의 루프백 주소 127.0.0.1에 게시하며, 이 머신에서 실행되는 모든 프로세스가 이 머신에서만 접근할 수 있고 해당 줄을 삭제하면 서비스가 내부에 유지된다고 설명하는 주석 아래에 있습니다. 모델이 연결된 경우 항목은 에이전트가 그 모델에 제시하는 자격 증명을 model 연결의 credential 아래에 값이 아니라 항상 참조로 첨부합니다. 자격 증명은 선언적 에이전트가 키에 대해 지정하는 변수(=Env.NAME로 작성)에서 읽고, 그렇지 않으면 OpenAI의 클라이언트 라이브러리가 키를 읽는 변수인 OPENAI_API_KEY에서 읽으며, helm을 제외한 모든 대상에서는 ${…} 참조로, helm에서는 Kubernetes Secret의 이름으로 작성되고, 비워 둔 채 작성되어 임포트가 아직 필요한 값으로 남깁니다. compose에서는 model 연결이 그 키로 이를 선언합니다. 선언적 에이전트가 모델과 MCP 서버에 대해 명시하는 값, 즉 키와 각 서버의 url은 선언적 에이전트가 담고 있는 자격 증명 값에서 설명하는 대로 에이전트 항목 위의 주석에 기록됩니다. 연결된 각 모델에는 항목이 있으므로 Release는 이를 에이전트와 함께 배치합니다. 그 연결이 명시하는 엔드포인트는 모델의 infra.endpoint로 작성되며, 참조로 작성된 엔드포인트는 항목 옆에 명시되고, 설정될 때까지 Component 자체의 주소가 사용됩니다. 엔드포인트를 명시하지 않는 연결은 항목이 인프라를 담지 않은 채로 두며, Component 자체의 주소가 그대로 유지됩니다. 초안으로 작성되는 모든 Release와 마찬가지로 metadata.environment를 development로 작성하고, 대상이 없으면 임포트가 아직 필요한 값으로 남기는 빈 spec.manifest를 작성합니다. 대상이 주어지면 대상이 추가하는 것에서 설명하듯 임포트가 Manifest를 초안으로 작성합니다.
이 임포터의 테스트가 가져오는 선언적 에이전트는 키 연결을 사용하는 OpenAI 제공자, 자체 키를 제시하는 MCP 서버, 함수 도구, 웹 검색을 갖추고 있으며, 개별 파일로 설정 없이 가져오면 그 name인 LearnAgent로 다음과 같이 초안으로 작성됩니다.
# Not read: the application's code, which loads each declarative agent and binds the functions of its function tools; the application runs in the image the Release names for each instance, and loads its declarative agents itself.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/learnagent version: 0.1.0 description: Draft Aggregate imported from a source in the agent-framework format.spec: components: # The declarative agent LearnAgent. # Read by the application from the declarative agent, and taken by no key of core/ai-agent/agent-framework: instructions, outputSchema, the options of its model requests (temperature, topP). # Function tools, whose code the application binds, drafted as no Component: GetRelease. # Tools the model's provider runs, drafted as no Component: search. # The MCP server microsoft_learn, drafted as no Component and no connection, since Agent Framework sends it to the model's provider as a hosted tool, and the provider, not the application, reaches it at its url, which must therefore be reachable from the provider; its url is written above learnagent's entry in the Release. # Stated by the declarative agent for microsoft_learn: its description, "Get information from Microsoft Learn."; its approval mode, never; the tools of the server it allows, microsoft_docs_search, microsoft_docs_fetch. learnagent: type: core/ai-agent/agent-framework values: display_name: "Learn Assistant" description: "Answers questions about {{`{{`}} product }} from the Microsoft Learn content." uses: model: gpt-4-1-mini: target: gpt-4-1-mini # For the compose target only, uncomment the lines below, which declare credential on gpt-4-1-mini: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. # features: # credential: # type: core/secret-value # values: # key: OPENAI_API_KEY # The model gpt-4.1-mini, which LearnAgent names with the OpenAI provider. gpt-4-1-mini: type: core/ai-model/openai values: model: "gpt-4.1-mini"초안이 선언적 에이전트에서 Aggregate로 값이나 주석에 복사하는 텍스트는 각 {{를 {{`{{`}}로 작성하므로, Aggregate가 평가된 후 작성된 그대로 읽힙니다.
spec: aggregate: imported/learnagent # manifest: left empty, since the import was given no target; an import given a target drafts the Manifest and names it here. manifest: "" components: # The declarative agent also states these values for its model and its MCP servers, written here for review: # - model.connection.key: "..." # - tools.microsoft_learn.url: "https://learn.microsoft.com/api/mcp?session=..." # - tools.microsoft_learn.connection.key: "..." learnagent: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on Agent Framework, holding its declarative agent image: "" uses: model: gpt-4-1-mini: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential learnagent presents to gpt-4-1-mini on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" gpt-4-1-mini: infra: endpoint: "https://llm-gateway.example.com/v1"이미지에 대한 답변이 주어지면 에이전트는 그 이미지를 실행하도록 렌더링되며, 모델의 엔드포인트를 OPENAI_BASE_URL로, id를 OPENAI_MODEL로, 자격 증명을 OPENAI_API_KEY로 받고, 모델은 호스트에 연결하는 Service로 렌더링됩니다. MCP 서버의 주소를 담는 변수는 없습니다. 서버에 연결하는 것은 애플리케이션이 아니라 모델의 제공자입니다.
선언적 에이전트가 보유하는 자격 증명 값
key 연결이 제시하는 키(모델 또는 MCP 서버에서 key 또는 apiKey 아래에 작성됨)는 Agent Framework가 자격 증명으로 표시하는 유일한 멤버입니다. 이 키는 로더가 로그에서 가리는 유일한 값입니다. 선언적 에이전트가 리터럴로 작성한 각 키는 Release에서 에이전트 항목 위의 주석에 선언적 에이전트가 작성한 그대로 기록되며, 기본적으로 작성된 그대로 전달되고 credential-carried 경고에서 값이 아니라 에이전트와 model.connection.key 같은 필드로 명시됩니다. MCP 서버의 url은 같은 주석에 전체가 기록되고 필드로 명시되며(tools.microsoft_learn.url of node LearnAgent is carried as written), MCP 서버 구성의 멤버입니다. 연결된 모델의 엔드포인트는 Agent Framework가 자격 증명이 아닌 것으로 표시하는 입력입니다. empty_credentials 설정이 marked이면 키와 MCP 서버의 url은 값 없이 작성되고(주석은 각각을 필드로만 명시합니다) credential-emptied로 보고되며, 모델의 엔드포인트는 전달됩니다. all이면 모델의 infra.endpoint도 제외되어 그 항목 위의 주석에 Release에 맡겨진 것으로 명시되며, 설정될 때까지 Component의 기본 주소가 사용됩니다. =Env.NAME으로 작성된 값은 값을 보유하지 않으므로 설정과 관계없이 Agent Framework가 환경에서 이를 읽는 조건과 함께 변수로 명시되며(model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads …), 어느 코드로도 보고되지 않습니다. 그 밖의 표현식으로 작성된 값은 표현식으로 명시되며 결코 작성되지 않습니다.
읽는 설정
Agent Framework 임포터는 Settings에서 설명하는 target_namespace, empty_credentials, render_mode를 읽으며, 그 밖의 설정은 읽지 않습니다.
대상이 추가하는 것
대상이 주어진 import, 즉 aggrega import의 --target, 또는 어시스턴트의 import 도구와 세션의 aggrega/import 메서드의 target으로 compose나 helm 같은 provider 기능을 지정한 import는 그 대상을 importer에 넘기므로, importer는 그 대상을 위해 초안을 작성합니다. 각 시크릿은 그 대상이 읽는 형식으로 작성되고, 그 대상만 필요로 하는 줄은 활성 상태로 작성되며, 다른 대상만 필요로 하는 줄은 생략됩니다. compose에서는 각 importer의 섹션에서 설명하듯 importer가 호스트의 루프백 주소에 서비스를 게시하는 모든 곳에 그러한 줄로 infra.published_port가 포함됩니다. importer가 고르는 포트는 Release의 다른 포트가 사용하는 번호를 결코 받지 않습니다. 이어서 import는, 어느 importer가 실행되었든 importer가 초안으로 작성한 것 옆에 Manifest를 초안으로 작성합니다. 이 manifest.yaml은 초안으로 작성된 Release 옆에 놓이고 그 Release와 같은 이름과 버전을 가지며, importer가 Release를 초안으로 작성하지 않았다면 초안으로 작성된 Aggregate 옆에 놓이고 그 Aggregate와 같은 이름과 버전을 가집니다.
초안이 필요로 하는 각 component 유형과 각 feature 유형, 즉 초안으로 작성된 Aggregate의 component, 그 연결과 하위 시스템, core/dify처럼 그것이 구성하는 카탈로그 Aggregates, 그리고 초안으로 작성된 Release의 첨부에 있는 유형에 대해, Manifest는 그 유형을 작업 공간의 카탈로그가 그 유형에 제공하는 해당 기능의 Recipe(feature 유형이라면 feature recipe)에 매핑합니다. 대상은 존재하는 단 하나의 것(한 Recipe의 여러 버전은 하나로 셉니다)이거나, 이름이 서로 다른 것이 여러 개라면 core/datastore/postgres에 대한 helm/postgres처럼 유형 자체의 이름을 딴 것입니다. 해당하는 것이 없거나, 여러 개 있지만 그렇게 이름 붙은 것이 없는 유형은 매핑되지 않은 채로 남고, 경고가 그 유형과 이유를 명시하며, 초안의 빌드는 그 유형을 매핑할 때까지 해당 유형의 각 인스턴스나 첨부를 지정하며 중단됩니다.
여러 Recipes 중 어느 것이 적용되는지 importer만 아는 경우에는 importer가 직접 Manifest를 초안으로 작성합니다. MCP importer는 각 서버를 그 키에 따라 서버 실행 방식의 실현에 매핑하고, 이름으로 시크릿을 첨부하는 importer는 core/referenced-secret를 helm/k8s-existing-secret에 매핑합니다. 그런 다음 import가 이를 완성합니다. importer가 작성한 매핑 중 카탈로그가 그 유형과 기능에 대해 제공하는 것은 유지되고, 그 밖의 것은 경고와 함께 삭제되며, importer가 남긴 유형은 위와 같이 매핑됩니다.
대상이 없을 때 비워 둔 채 작성되는, 초안으로 작성된 Release의 spec.manifest는 Manifest의 이름으로 설정되고, 그 위의 주석은 삭제되며, Release의 다른 부분은 바뀌지 않습니다. aggrega import에서 전체 내용을 설명합니다.
설정
임포터는 자신을 연결하는 plugins.importer 항목의 설정을 with.settings 아래에서 전달받으며, 이는 Which importer turns a source into drafts에서 설명합니다. 항목이 없거나 설정이 없으면 모든 설정이 기본값을 사용합니다.
plugins: importer: - uri: importer/langflow:<version> with: settings: target_namespace: payments reuse_mode: hints-only| 설정 | 기본값 | 동작 |
|---|---|---|
target_namespace | imported | 초안으로 작성된 엔터티의 이름이 놓이는 네임스페이스입니다. Component에는 <target_namespace>/<category>/<name>, Aggregate와 Release에는 <target_namespace>/<name>이 쓰이며, <name>은 소스 자체의 이름이고, 없으면 그 디렉터리의 이름 또는 확장자를 뺀 파일 이름, 그것도 없으면 flow입니다. 이 이름은 소문자로 쓰이며, ASCII 문자와 숫자가 아닌 문자가 연속된 부분은 각각 하이픈 하나로 바뀝니다. 자세한 내용은 초안의 이름을 정하는 방식에서 설명합니다. |
reuse_mode | auto-apply-above-threshold | auto-apply-above-threshold는 초안이 고유한 Component를 부여하는 노드 중 일치가 상위 등급이고 점수가 reuse_threshold 이상인 노드에 대해 가장 잘 일치하는 카탈로그 Component를 참조하고, 나머지는 모두 초안으로 작성합니다. hints-only는 그러한 모든 노드를 초안으로 작성하고 카탈로그 Component를 참조하지 않으며, 강한 일치는 힌트로 기록합니다. 그 밖의 값은 hints-only로 읽힙니다. |
reuse_threshold | 0.85 | auto-apply-above-threshold가 Component를 참조하는 기준 점수입니다(이상). 해당 모드에서만 읽으며, 0은 기본값으로 읽힙니다. |
emit_hints | true | 상위 또는 중위 등급 일치에 대해, 초안 Component 파일이 유사한 카탈로그 Component를 명시하는 주석으로 시작하는지 여부입니다. 초안 Aggregate는 해당 노드 항목 위에 같은 주석을 두고, 참조된 항목 위에는 교체할 수 있는 차선의 후보를 명시하거나 0점을 넘은 후보가 없다고 알리는 주석을 둡니다. false는 주석을 생략합니다. |
render_mode | human | human은 위에서 설명한 초안을 작성합니다. llm은 초안을 작성하지 않고, 대신 모든 노드, 검토한 후보, 내린 선택을 포함한 전체 결정 기록을 다른 도구가 읽을 수 있도록 하나의 문서 import-decisions.json으로 작성합니다. 그 밖의 값은 human으로 읽힙니다. |
mapping_overrides | 없음 | 임포터 자체 테이블 위에 덧씌우는 매핑으로, 형식별, 그다음 노드 유형별로 키가 지정됩니다. Compose 임포터의 경우 이미지 저장소별입니다. 각 항목은 해당 유형의 노드가 매핑되는 component를 명시하고, 선택적으로 그 category, 일치하는 Component가 지닌 traits(레이블과 그 값), 이름에 포함된 vendor 단어를 명시합니다. 테이블이 이미 매핑하는 노드 유형에 대한 항목은 테이블 행을 대체합니다. 가져오는 형식 아래의 항목만 읽힙니다. |
layout | platform | platform은 흐름을 실행하는 플랫폼을 흐름을 담은 채로 초안으로 작성하며, 흐름의 각 부분은 플랫폼에 연결된 고유한 Component가 됩니다. 이는 The platform carrying the flow에서 설명합니다. nodes는 모든 노드를 고유한 Component로 초안 작성하며, 이는 Node by node에서 설명합니다. Dify 임포터의 경우 platform은 애플리케이션을 담은 Dify 설치를 초안으로 작성하며, 이는 What an application becomes에서 설명합니다. 그 밖의 값은 platform으로 초안 작성되며, 가져오기는 unknown-layout으로 경고합니다. |
empty_credentials | none | 어떤 자격 증명 값을 빈 값으로 작성할지 지정합니다. 대상은 플랫폼이 담는 흐름(Credential values the flow holds에 나열), MCP 임포터가 작성하는 Release(Credential values a server holds에 나열), Compose 임포터가 작성하는 Release(Credential values a service holds에 나열), Dify 임포터가 담는 애플리케이션(Credential values an application holds에 나열), CrewAI 임포터가 작성하는 Release(Credential values a declaration holds에 나열), LangGraph 임포터가 작성하는 Release(The environment a configuration states에 나열), Google ADK 임포터가 작성하는 Release(Credential values a configuration holds에 나열), Agent Framework 임포터가 작성하는 Release(Credential values a declarative agent holds에 나열)입니다. none은 아무것도 비우지 않으며, 각 값은 작성된 그대로 담기고 credential-carried 경고에 명시됩니다. marked는 형식이 자격 증명으로 표시한 값과 MCP 서버 구성의 모든 멤버를 비웁니다. all은 형식이 자격 증명으로 표시하지 않았지만 자격 증명을 담을 수 있는 입력, 즉 요청 헤더, 쿼리 매개변수, 명령줄로 작성된 요청, 키를 이름으로 한 입력도 비웁니다. 노드가 연결에 도달하도록 초안이 작성하는 내용은 이 설정과 관계없이 작성됩니다. 그 밖의 값은 가져오기를 unknown-empty-credentials로 중단시키며, 아무것도 초안 작성되지 않습니다. 노드별로 작성된 초안은 값을 읽지 않으므로 이 설정도 읽지 않습니다. |
attach_egress_allowlist | false | true는 초안이 작성하는 각 플랫폼 인스턴스에 표준 라이브러리의 core/egress-allowlist Feature를 egress-allowlist로 연결하며, 그 infra는 하나도 설정하지 않습니다. 이는 What the draft leaves for the Release에서 설명합니다. false는 아무것도 연결하지 않습니다. layout: nodes에서 플랫폼을 작성하지 않는 초안과, Dify 설치 항목이 Feature를 받지 않는 Dify 임포터의 초안은 이 설정과 관계없이 아무것도 연결하지 않으며, 이 설정이 true이면 가져오기는 feature-not-attached로 경고합니다. 불리언이 아닌 값은 false로 읽힙니다. |
임포터가 알지 못하는 설정은 무시됩니다.
with: settings: mapping_overrides: langflow: AzureOpenAIModel: component: acme/ai-model/azure-openai category: ai-model vendor: azure가져오기가 보고하는 내용
각 코어 임포터는 수행하지 못한 것과 작성자를 대신해 수행한 것을
진단으로 보고합니다. 명령은 각 진단을 표준 오류에 <severity>: <message> 형식으로, 각 노드에 대한 줄보다
먼저 출력합니다. 편집기 세션의 aggrega/import 메서드와 어시스턴트의 import 도구는 각 진단을
해당 code와 함께 반환합니다.
| 코드 | 심각도 | 보고되는 경우 |
|---|---|---|
parse-failed | halt | 소스를 파싱할 수 없습니다. 파서가 소스를 거부하며, 메시지에 파서가 제시한 이유가 담깁니다. |
no-nodes | warn | 소스에 임포터가 인식하는 노드가 없습니다. MCP 임포터의 경우 서버가 없을 때, Compose 임포터의 경우 서비스도 모델도 없을 때, CrewAI 임포터의 경우 크루가 에이전트를 선언하지 않을 때, LangGraph 임포터의 경우 구성이 그래프를 선언하지 않을 때, Google ADK 임포터의 경우 루트 구성이 에이전트를 선언하지 않거나 with.sources가 가져오기에 전달하는 각 파일에 루트 구성이 없을 때, Agent Framework 임포터의 경우 소스가 프롬프트 에이전트를 선언하지 않을 때입니다. |
unknown-layout | warn | layout이 platform도 nodes도 아닙니다. 흐름은 platform으로 초안 작성됩니다. |
unknown-empty-credentials | halt | empty_credentials에 none, marked, all 이외의 값이 있으며, 설정 이름과 함께 보고됩니다. 가져오기는 아무것도 초안 작성하지 않습니다. |
platform-not-in-catalog | warn | 워크스페이스의 카탈로그에 플랫폼 이름의 Component가 없으므로 어떤 부분도 플랫폼에 연결되지 않습니다. Dify 임포터의 경우 core/ai-agent/dify가 없는 경우이며, 이때도 core/dify는 그대로 구성됩니다. |
part-not-placed | warn | 흐름의 한 부분이 플랫폼의 어떤 소켓에도 연결되지 않으며, 그 이유가 함께 보고됩니다. 해당 부분은 흐름에 남습니다. |
socket-selector-unreadable | warn | 플랫폼의 소켓이 선언하는 선택자를 읽을 수 없으므로 어떤 부분도 해당 소켓에 연결되지 않습니다. 소켓마다 한 번씩 보고됩니다. |
credential-carried | warn | 자격 증명 값이 초안이 담는 흐름에, 또는 MCP, Compose, CrewAI, LangGraph, Google ADK, Agent Framework 임포터가 초안 작성하는 Release에 작성된 그대로 담깁니다. 값이 아니라 노드(또는 서버, 서비스, 에이전트, 구성)와 필드로 명명되며, 해당 값을 비워 쓰게 하는 empty_credentials 값이 함께 보고됩니다. |
credential-emptied | warn | empty_credentials가 요구하는 곳에서 자격 증명 값이 초안이 담는 흐름에, 또는 MCP, Compose, CrewAI, LangGraph, Google ADK, Agent Framework 임포터가 초안 작성하는 Release에 비워서 작성되며, 노드(또는 서버, 서비스, 에이전트, 구성)와 필드로 명명됩니다. |
carriage-returns-rewritten | warn | 흐름의 캐리지 리턴이 라인 피드로 작성되며, 그 개수가 함께 보고됩니다. |
definition-respelled | warn | 흐름의 값은 플랫폼 자체 도구가 읽는 표기로, 같은 값 그대로 작성되며, 어떤 값을 왜 그렇게 했는지가 함께 표시됩니다. Langflow 흐름의 엣지 핸들은 Langflow의 편집기가 작성하는 대로 작성됩니다. 흐름이 어떤 부분에 도달하도록 초안이 작성하는 값이나 자격 증명을 담을 수 있는 값은 결코 표기가 바뀌지 않으며 — 배선의 값 또는 empty_credentials의 값으로 남습니다 — 경고는 표기가 바뀌지 않은 각 값을 셉니다. |
definition-not-carried | warn | 흐름이 values.flow_definition에 담기지 않거나, Dify 임포터의 애플리케이션이 parameters.app_definition에 담기지 않으며, 그 이유가 함께 보고됩니다. |
part-reads-connection | warn | 흐름이 연결을 통해 연결된 부분에 도달하는 방식, 또는 초안이 어떤 소켓에도 연결하지 않는 노드에 연결이 작성된 그대로 도달하는 방식입니다. |
part-address-in-flow | warn | 흐름이 연결 이외의 방식으로 연결된 부분에 도달하며, 그 방식이 함께 보고됩니다. |
model-not-named | warn | 참조된 부분의 values.model이 작성자에게 남겨지며, 그 이유가 함께 보고됩니다. |
feature-attached | info | attach_egress_allowlist가 초안 작성된 플랫폼에 core/egress-allowlist를 부착했으며, 그중 Release가 설정하는 항목이 함께 보고됩니다. 플랫폼 인스턴스마다 한 번씩 보고됩니다. |
feature-not-attached | warn | attach_egress_allowlist가 true이지만 초안이 플랫폼을 작성하지 않거나, 항목이 Feature를 받지 않는 Dify 설치를 구성하므로 아무것도 부착되지 않습니다. |
part-configured-in-platform | warn | Dify 애플리케이션의 노드가 Dify가 자체적으로 구성하는 것(모델과 그 공급자, 도구, 지식 베이스, 에이전트 전략, 플러그인)을 명명하므로 초안은 이에 대한 부분을 연결하지 않습니다. |
dsl-version-newer | warn | Dify 애플리케이션이 core/ai-agent/dify가 기본으로 실행하는 Dify 버전이 작성하는 DSL 버전보다 새로운 버전으로 작성되어 있습니다. |
대상이 주어진 가져오기는 임포터의 진단 다음에 Manifest 초안 작성에서 발견한 내용을 보고합니다. Manifest가 매핑하지 않은 채로 두는 각 컴포넌트 유형 또는 feature 유형과 그 이유를 명명하는 warn, 그리고 초안 작성된 Release가 이미 Manifest를 명명하거나 초안 작성된 어떤 Release도 이를 참조하지 않는 경우의 info입니다. 이들은 임포터가 아닌 가져오기 자체의 진단이며 코드가 없습니다. 대상이 추가하는 것에서 설명합니다. 이어서 모든 가져오기는 역시 자체 진단으로서, 초안에 아직 필요한 각 값에 대해 초안 파일, 키 경로와 그 설명을 명명하는 warn을 보고하며, --offline에서는 Release를 초안으로 작성했고 필요한 값이 없는 경우 다음에 실행할 aggrega pull을 명명하는 info를 보고합니다. 가져오기 답변 파일에서 설명합니다.
각 컴파일러 릴리스와 함께 게시됨
각 컴파일러 릴리스는 태그가 지정된 소스에서 열 개의 임포터를 빌드하고, 임포터 자체로부터 해당 Plugin
엔터티를 생성하므로, 엔터티의 기능, 인식 시그니처, 호스트
함수 및 설명은 해당 임포터가 보고하는 그대로입니다. 릴리스는 열 개 모두,
importer/langflow, importer/flowise, importer/n8n, importer/mcp, importer/compose, importer/dify, importer/crewai, importer/langgraph, importer/google-adk, importer/agent-framework를 릴리스의 버전으로 다른
코어 플러그인과 함께 서명하여 게시하고, 그 엔터티를 표준
카탈로그용으로 다른 코어 플러그인의 엔터티와 함께 기록합니다.