Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Основні імпортери

Репозиторій компілятора збирає десять власних плагінів-імпортерів, по одному для кожного формату джерела, і публікує їх з кожним випуском компілятора:

PluginОбслуговуєЧитає
importer/langflowimport:langflowпотік, експортований з Langflow, у форматі JSON
importer/flowiseimport:flowisechatflow або agentflow, експортований з Flowise, у форматі JSON
importer/n8nimport:n8nробочий процес, експортований з n8n, у форматі JSON
importer/mcpimport:mcpконфігурацію клієнта MCP — .mcp.json, claude_desktop_config.json, .vscode/mcp.json або .cursor/mcp.json — або опис сервера з реєстру MCP, server.json, у форматі JSON
importer/composeimport:composeзастосунок Compose — compose.yaml, docker-compose.yml та їхні файли перевизначення — у форматі YAML
importer/difyimport:difyзастосунок, експортований з Dify у його DSL, у форматі YAML
importer/crewaiimport:crewaiагентів і завдання, які оголошує проєкт CrewAI, — config/agents.yaml і config/tasks.yaml у форматі YAML або crew.jsonc і agents/<name>.jsonc, чи їхні варіанти в строгому JSON crew.json і agents/<name>.json, у форматі JSON з коментарями
importer/langgraphimport:langgraphконфігурацію застосунку LangGraph, langgraph.json, у форматі JSON, а з файлу середовища, який вона називає, — лише імена змінних, якщо цей файл передано імпорту в with.sources
importer/google-adkimport:google-adkагентів, оголошених у файлах Agent Config застосунку, побудованого на Google ADK, — root_agent.yaml і конфігурації, які називають його субагенти, — у форматі YAML
importer/agent-frameworkimport:agent-frameworkдекларативного агента Microsoft Agent Framework, документ типу Prompt з будь-якою назвою, у форматі YAML

Кожен збирається з власних джерел компілятора й позначається версією компілятора, тож імпортери, випущені з компілятором версії X.Y.Z, повідомляють версію X.Y.Z, і їхні сутності Plugin її записують. На відміну від плагінів, перелічених у розділі Вбудовані плагіни, жоден не вкомпільовано в бінарний файл. Бінарний файл містить сутність Plugin кожного з них і дайджест єдиного модуля, який він для неї приймає, тож кожен обслуговує свій формат у кожному робочому просторі без запису в його каталозі.

Усі десять побудовано на пакеті імпортерів набору Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Для імпортерів Langflow, Flowise і n8n усе, що імпортер робить незалежно від формату, — оцінювання Components каталогу робочого простору щодо кожного вузла, рішення, чи посилатися на наявний, чи створити чернетку нового, розміщення чернетки, перенесення облікових значень, які вона містить, або запис їх порожніми, як вимагає налаштування, запис чернеток і читання налаштувань нижче, — належить цьому пакету, а особливим для кожного імпортера є лише читання формату й знання платформи, на якій працюють його потоки. Імпортер MCP створює чернетку екземпляра одного Component на кожен сервер, тож нічого не оцінює; він спільно з пакетом читає свої налаштування, ухвалює рішення щодо облікових значень і дотримується домовленостей, за якими називаються й описуються його чернетки, як описано в розділі Імпортер MCP. Імпортер Compose вирішує щодо кожного зіставленого сервісу так само, як імпортери потоків щодо вузла, через той самий пакет, відтворює свої чернетки так само, як вони, а решту поділяє так само, як імпортер MCP, як описано в розділі Імпортер Compose. Імпортер Dify створює чернетку інсталяції Dify, яку збирає стандартна бібліотека, з застосунком усередині, через чернетку платформи того самого пакета у формі, якої вона набуває для платформи, що є цілою інсталяцією, як описано в розділі Імпортер Dify. Імпортер CrewAI створює чернетку екземпляра агента CrewAI стандартної бібліотеки на кожного агента, якого оголошує проєкт, з’єднаного з моделлю, яку той називає, а решту поділяє так само, як імпортер MCP, як описано в розділі Імпортер CrewAI. Імпортер LangGraph створює чернетку екземпляра агента LangGraph стандартної бібліотеки на кожен граф, який оголошує конфігурація застосунку, з’єднаного зі сховищем даних, у якому його checkpointer зберігає стан, а решту поділяє так само, як імпортер MCP, як описано в розділі Імпортер LangGraph. Імпортер Google ADK створює чернетку екземпляра агента ADK стандартної бібліотеки на кожне дерево агентів, яке оголошують конфігурації застосунку, з’єднаного з моделлю, яку називає дерево, коли ADK надсилає свої запити до Gemini API, а решту поділяє так само, як імпортер MCP, як описано в розділі Імпортер Google ADK. Імпортер Agent Framework створює чернетку екземпляра агента Agent Framework стандартної бібліотеки на кожного декларативного агента, з’єднаного з моделлю OpenAI, яку той називає, — кожен сервер MCP, який він називає, записано в коментарях, оскільки постачальник моделі звертається до нього як до розміщеного інструмента, — а решту поділяє так само, як імпортер MCP, як описано в розділі Імпортер Agent Framework. Як працює сокет імпортера і що йому передається, описано в розділі Сокет імпортера.

Ця сторінка — довідник про те, що кожен імпортер читає та які чернетки створює. Щоб імпортувати власний проєкт і зібрати результат, почніть з розділу Імпорт, який проводить проєкт від джерела до збірки, по одному формату за раз.

Як імпорт отримує його

aggrega import, метод aggrega/import сеансу редактора та інструмент асистента import отримують основний імпортер однаково. Якщо машина вже має його модуль — у кеші вмісту робочого простору, — імпорт читає його звідти, не потребуючи для цього мережі. Якщо ні, перший імпорт, якому він потрібен, завантажує його з типового реєстру робочого простору у версії компілятора і:

  • звіряє його з дайджестом, який містить бінарний файл, тож запускається лише модуль, опублікований у випуску компілятора;
  • перевіряє його так само, як pull перевіряє завантажений плагін, — його підпис за політикою довіри цього реєстру, а функції хоста, які він використовує, — за тими, що записані в його сутності Plugin;
  • зберігає його в кеші вмісту робочого простору, і це єдине, що для нього записується: ні lockfile, ні запису про довірені плагіни, бо імпорт не закріплює жодного імпортера.

Кожен наступний імпорт читає його з кешу вмісту. Модуль, який не пройшов перевірку, відхиляється, і нічого не зберігається. У теці, яку не позначає жоден робочий простір, немає кешу вмісту, де його можна зберегти, тому завантаження там відхиляється з назвою теки та поясненням, як указати робочий простір або зробити теку робочим простором. Модуль ніколи не читається поруч із сутністю Plugin з тією самою назвою, але іншою версією в теці каталогу: цей модуль належить іншій сутності.

Якщо модуль не вдається завантажити, імпорт зупиняється з помилкою A plugin’s .wasm is not on this machine (Файлу плагіна немає на цій машині), називаючи імпортер і його версію, і повідомляє, що розмістить його модуль на машині:

  • Запустіть імпорт один раз із доступною мережею, якщо робочий простір працює офлайн або його реєстр був недоступний. Цей запуск завантажить модуль, і всі наступні запуски працюватимуть офлайн.
  • Розмістіть його модуль поруч із сутністю Plugin цього імпортера цієї версії в теці каталогу під назвою, яку вказує повідомлення, — importer--langflow.wasm для імпортера Langflow. Сутність каталогу з тією самою назвою та версією, що й основний імпортер, запускається замість нього, а її модуль читається поруч із нею; така сутність без модуля поруч не запускається замість нього, і основний імпортер отримується, як описано вище. Якщо реєстр не містить модуля або робочий простір не вказує типового реєстру, це єдиний спосіб виправлення, який наводить повідомлення.

Який із них виконується поруч із вашими власними імпортерами

Основні імпортери є кандидатами поруч з імпортерами, які містить каталог вашого робочого простору, за правилами, за якими вибирається кожен імпортер і які викладено в розділі Which importer turns a source into drafts (Який імпортер перетворює джерело на чернетки):

  • У межах одного імені виконується найвища версія або версія, яку називає запис plugins.importer.
  • Якщо ваш каталог містить імпортер з іншим іменем для langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk або agent-framework, формат оголошують два імпортери, і імпорт, який не приєднує жодного з них, відхиляється із зазначенням обох під повідомленням A parse or import format is advertised by more than one plugin (Формат розбору або імпорту оголошує більше ніж один плагін). Запис 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; джерело, яке розбирається як JSON з коментарями, як його читає Visual Studio Code, має назву .vscode/mcp.json і містить об’єкт у servers; або джерело з будь-якою назвою, яке розбирається як JSON і чий $schema є текстом, що починається з https://static.modelcontextprotocol.io/schemas/, — опис сервера з реєстру. Назва зіставляється з кінцем шляху, переданого імпорту, тож project/.vscode/mcp.json розпізнається, тоді як mcp.json, переданий зсередини .vscode, або файл клієнта з будь-якою іншою назвою імпортується із зазначенням --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, містить текст app у kind і щось містить у app.mode та у version, як кожен застосунок, що його експортує Dify.
  • CrewAI — джерело з назвою config/agents.yaml або config/tasks.yaml, яке розбирається як YAML, джерело з назвою crew.jsonc або crew.json, яке розбирається як JSON з коментарями і містить список у agents, або джерело з назвою agents/<name>.jsonc чи agents/<name>.json, яке розбирається як JSON з коментарями і щось містить у role. Класичний проєкт індексує своїх агентів і свої завдання назвами, які обирає його автор, тож два його файли розрізняються лише за назвами.
  • LangGraph — джерело з назвою langgraph.json, яке розбирається як JSON і містить об’єкт у graphs; або джерело з будь-якою назвою, яке розбирається як JSON, містить об’єкт у graphs і чий $schema є текстом https://langgra.ph/schema.json — схемою, яку LangGraph публікує для своєї конфігурації. Конфігурація з іншою назвою, що не називає схеми, імпортується із зазначенням --format langgraph. Жодна сигнатура імпортера не називає файлу середовища, тож під час розпізнавання каталогу жоден такий файл не відкривається.
  • Google ADK — джерело з назвою root_agent.yaml, яке розбирається як YAML і щось містить у name та в instruction, як конфігурація LlmAgent, або текст у agent_class і щось у name, як конфігурація будь-якого іншого агента. Конфігурація з іншою назвою імпортується із зазначенням --format google-adk. Жодна сигнатура не називає конфігурації субагента, яка може мати будь-яку назву, тож під час розпізнавання каталогу не відкривається жоден файл YAML, крім root_agent.yaml.
  • Agent Framework — джерело з будь-якою назвою, яке розбирається як YAML, містить текст Prompt у kind і об’єкт у model, як декларативний агент, що називає свою модель; Agent Framework завантажує декларативного агента з будь-якого файлу, який називає його застосунок, тож сигнатура не називає файлу. Декларативний агент, що не називає моделі або записує свій вид в іншому регістрі чи як 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: той, що його обслуговує каталог вашого робочого простору, якщо обслуговує, а інакше — парсер, який сам компілятор має для цього синтаксису (див. Вбудовані плагіни). Тож імпорт через будь-який із них не потребує парсера у вашому каталозі, і для нього нічого не завантажується. Парсер, який ваш каталог таки обслуговує, і є тим, що використовується, а парсер компілятора не бере участі. Імпортери 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 поруч із нею, якщо створює її, назву <target_namespace>/<name>. Перша частина — це параметр target_namespace, imported, якщо ви не задасте інший. <name> — перше з наведеного нижче, що не порожнє:

  • назва, яку джерело дає собі само, у полі, в якому її оголошує його формат:

    ІмпортерНазва, яку він читає
    importer/langflowname потоку
    importer/flowiseнемає: експорт не має власної назви
    importer/n8nname робочого процесу
    importer/mcpname опису сервера в реєстрі; конфігурація клієнта не має назви
    importer/composename верхнього рівня проєкту, причому назва файла перевизначення замінює назву файла, який він перевизначає, як їх об’єднує Compose
    importer/difyname застосунку в app
    importer/crewainame команди в crew.jsonc або crew.json; config/agents.yaml і config/tasks.yaml не мають назви, оскільки класичний проєкт називає свою команду у своїй програмі
    importer/langgraphідентифікатор графа, який оголошує конфігурація, оскільки конфігурація не має власної назви
    importer/google-adkname кореневого агента
    importer/agent-frameworkname агента; його 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 вузла, а його поля — із записів data.node.template, значенням яких є об’єкт, що містить type. Інші записи шаблону не є полями.
  • Поле, об’єкт якого містить password: true, оформлюється як слот облікових даних, а кожне інше поле — як поле значення. Назва поля ролі не відіграє, і оформлення вузла як сутності Component не читає значення жодного поля.
  • Нотатка, закріплена на полотні, — вузол типу noteNode, — не імпортується, а ребро до вузла, що не імпортується, відкидається.
  • Створення чернетки платформи, що несе потік, також зчитує з потоку: його id верхнього рівня; значення кожного поля, позначеного password: true; поле mcp_server вузла MCP Tools — сервер MCP, який воно називає, і конфігурацію цього сервера — або поля, у яких вузол натомість зберігає свій сервер; кожне введення, яке Langflow позначає як не облікові дані, але яке може їх містити, як їх перелічує розділ Облікові дані, які містить потік; поле, у якому вузол називає свою модель, і постачальника моделі, на якому вона працює; а також поля, через які вузол звертається до адреси та ключа частини, які він переписує. Розділ Що вони створюють пояснює, що стається з кожним із них.

Що читає імпортер Flowise

  • Вузли та ребра на верхньому рівні потоку, nodes і edges.
  • Для кожного вузла — його тип із data.name вузла; його слоти облікових даних із записів data.inputParams, чий type дорівнює credential, за їхнім name; і його поля значень із ключів data.inputs, за винятком тих, які називає data.inputAnchors, — куди під’єднується інший вузол, що фіксує ребро між ними, — і за винятком облікових даних.
  • Створення чернетки вузла як сутності Component не читає значення жодного поля, а назва облікових даних не впливає на те, чи є вони обліковими даними.
  • Нотатка, закріплена на полотні, — вузол типу stickyNote, — не імпортується, а ребро до вузла, який не імпортується, відкидається.
  • Створення чернетки платформи, що несе chatflow, також зчитує з нього: його id верхнього рівня, якщо це UUID; облікові дані, які вузол зберігає в data.credential; значення кожного входу, який його inputParams оголошують із типом password; FLOWISE_CREDENTIAL_ID серед входів вузла, а також credential або FLOWISE_CREDENTIAL_ID всередині об’єкта конфігурації на будь-якій їхній глибині; конфігурацію сервера у вході mcpServerConfig вузла; кожен вхід, який Flowise позначає як не облікові дані, але який може їх містити, як їх перелічує розділ Значення облікових даних, які містить потік, і член, у якому конфігурація agentflow називає модель або інструмент, який вона вибирає; вхід modelName вузла; і Base Path вузла OpenAI, його вхід 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-клієнта; заголовки й параметри запиту, які вузол надсилає із запитом, що його складає робочий процес, як їх перелічує Значення облікових даних, які містить потік; і параметр, у якому вузол моделі називає свою модель. Що створюють чернетки пояснює, що стається з кожним із них.

Що вони створюють у чернетці

Кожен вузол зіставляється з Components власного каталогу робочого простору і ні з чим іншим, як описує сокет імпортера, і кожен імпортер містить коротку таблицю, що зіставляє поширені типи вузлів свого формату — моделі чату та ембедингів, пошук, HTTP-запити і, у Langflow, вузол MCP Tools MCPTools, який зіставляється з core/ai-tool/mcp, — із Components стандартної бібліотеки. Таблиця Langflow також зіставляє компонент Language Model, LanguageModelComponent, модель чату, яку викликають стартові потоки Langflow, з core/ai-model/openai, моделлю, яку обслуговує з’єднання моделі платформи Langflow: вузол працює на постачальнику моделей, якого називає його поле provider, типово OpenAI, а вузол, що називає іншого постачальника, ніколи не під’єднується до цього з’єднання, як описано в розділі Які вузли стають частинами. Таблиця імпортера n8n зіставляє моделі чату та ембедингів n8n, його клієнтський інструмент MCP з core/ai-tool/mcp, його інструменти HTTP-запитів, інструмент SerpApi, векторні сховища Qdrant, PGVector, Chroma, Milvus і Weaviate, а також пам’ять чату Postgres і Redis. Вузол, який n8n виконує всередині самого робочого процесу, — агент, ланцюжок, тригер, пам’ять, яку робочий процес зберігає у власному процесі, інструмент коду — належить самому робочому процесу, і жоден рядок його не зіставляє. Рядок цієї таблиці враховується для збігу лише тоді, коли каталог робочого простору містить сутність Component, яку він називає. Команда виводить один рядок для кожного зіставленого вузла, називаючи, що вона обрала, рівень збігу та оцінку найкращого кандидата, і рядок made no choice for <node id> (<node type>) для вузла, якому вона не дає власної сутності Component. Вузол, що посилається на сутність Component каталогу, а не створюється в чернетці, не має власного файлу: чернетка Aggregate називає цю сутність Component.

Структуру чернетки визначає параметр layout. platform, значення за замовчуванням, створює в чернетці платформу, що виконує потік, і переносить потік у тому вигляді, у якому його експортовано, а власну сутність Component дає лише кожній частині потоку, яку приймає сокет платформи, — на платформах стандартної бібліотеки це модель, сервер MCP або інший інструмент, доступний через HTTP, і векторне сховище. nodes створює кожен вузол як окрему сутність Component.

Платформа, що переносить потік

За замовчуванням імпорт записує:

  • aggregate.yaml — чернетку Aggregate, названу за потоком, як описано в розділі Як іменується чернетка. Вона містить один екземпляр платформи, що виконує потік, — core/ai-agent/langflow під ключем langflow для потоку Langflow, core/ai-agent/flowise під ключем flowise для потоку Flowise і core/ai-agent/n8n під ключем n8n для робочого процесу n8n, — що посилається на сутність Component каталогу з цією назвою. Екземпляр переносить потік у values.flow_definition і називає його у своєму значенні-ідентифікаторі: flow_id у Langflow, chatflow_id у Flowise і workflow_id у n8n. Кожна частина потоку є окремим записом поруч із ним, під’єднаним до платформи в 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 з Flowise, експортований як Multiple Documents QnA.json та імпортований без жодного налаштування й без цілі за каталогом, що містить платформу Flowise стандартної бібліотеки та її Components моделей і інструментів пошуку, створюється в чернетці як така сутність Aggregate (більшу частину потоку тут пропущено й позначено ...):

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
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

Його модель чату — єдина під’єднана частина; дві його моделі ембедингів залишаються в потоці, оскільки сокет моделі приймає одне з’єднання, а його інструменти-ретривери залишаються в потоці, оскільки жоден сокет платформи їх не приймає. Імпорт повідомляє про кожну з них.

Ідентифікатор потоку — той, який дає йому експорт: id верхнього рівня потоку Langflow, id верхнього рівня чатфлоу Flowise, якщо це UUID, і id верхнього рівня робочого процесу n8n, — якщо він складається з 1–128 літер, цифр, ., -, _ або : і починається з літери чи цифри. Якщо експорт не дає ідентифікатора або дає такий, що містить будь-який інший символ, чернетка записує UUID на основі імені, похідний від назви формату та потоку в тому вигляді, у якому він переноситься, тож один потік завжди дає один ідентифікатор, а коментар над значенням повідомляє, що його виведено. Чатфлоу, експортований з редактора Flowise, не містить id, тому отримує похідний.

Якщо каталог робочого простору не містить сутності Component з назвою платформи, чернетка все одно називає платформу, але не під’єднує до неї жодної частини: кожен вузол, що став би частиною, залишається в потоці з повідомленням про це, а імпорт попереджає, що каталог не містить такої сутності Component.

Які вузли стають частинами і куди кожен під’єднано

Вузол є частиною потоку, якщо рядок таблиці зіставлення імпортера або запис mapping_overrides зіставляє його тип, або якщо його найкращий кандидат має щонайменше середній рівень збігу. Вузол MCP Tools з Langflow є частиною незалежно від оцінок: він називає сервер MCP, до якого звертається, і цей сервер є частиною. Частина стає окремою сутністю Component, на яку посилаються або яку створюють у чернетці саме так, як вирішує reuse_mode, і під’єднується до першого сокета платформи — у порядку, в якому запис платформи в каталозі оголошує свої сокети, — селектору міток якого задовольняє сутність 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 Tools, чиє поле mcp_server називає це з’єднання, тож вузол, шаблон якого не містить поля mcp_server, — незалежно від його типу і від того, з чим його зіставляє рядок зіставлення чи перевизначення, — ніколи не під’єднується до сокета tools: його під’єднують до наступного сокета, який задовольняє його сутність Component, або він залишається в потоці з повідомленням. Вузол MCP Tools, що не називає жодного сервера, не під’єднується до жодного сокета, і про нього повідомляється. Так само й вузол, конфігурація сервера якого запускає власний сервер — містить command або задає режим Stdio, — і повідомлення про нього вказує, що слід вилучити, оскільки збірка платформи зупиняється на вузлі, який називає сервер, що йому не відповідає жодне з’єднання tools.
  • Сервер MCP під’єднується за назвою, яку дає йому потік. Вузли одного потоку, що називають один сервер, досягають однієї частини, створеної в чернетці один раз, через одне з’єднання. Псевдонімом з’єднання є назва сервера, якщо псевдонім з’єднання може її прийняти — літери, цифри, дефіси та підкреслення, — і жодне інше з’єднання цього сокета не передається під тією самою назвою змінної (його псевдонім у верхньому регістрі, де кожен інший символ записано як підкреслення). Інакше з’єднання отримує псевдонім, похідний від ключа частини, сервер вузла перейменовується на цей псевдонім у потоці, який переносить чернетка, і рішення частини повідомляє про це.

Рішення під’єднаної частини вказує, до якого сокета платформи її під’єднано і через яке з’єднання, а також називає кожен сокет, який для неї оминуто, і причину.

Як перенесений потік досягає кожної частини

Там, де формат це дозволяє, потік, який несе платформа, досягає кожної підключеної частини через її з’єднання, і чернетка записує в потік те, що це забезпечує, — ім’я змінної, спорожнену адресу або спорожнене те, що вузол надсилав би замість того, що постачає з’єднання, і ніколи не значення. Це підключення, а не видалення облікового значення: чернетка записує його незалежно від того, що каже параметр empty_credentials, оскільки збережене там значення перекрило б те, що постачає з’єднання.

  • Вузол MCP Tools у Langflow. Платформа записує адресу, яку постачає його з’єднання, у конфігурацію сервера вузла, а там, де з’єднання несе облікові дані, — ім’я змінної, що їх містить, під заголовком, який публікує інструмент. Чернетка записує адресу, яку там містив експорт, порожньою, щоб потік не містив її копії, і залишає адресу сервера — infra.endpoint частини — для сутності Release. Langflow надсилає власне поле вузла headers поверх заголовків конфігурації його сервера, тому чернетка записує все значення цього поля порожнім, зберігаючи його вид — об’єкт як {}, список як [], текст як порожній рядок, — оскільки заголовок, збережений зі спорожненим значенням, однаково надсилався б, тоді як порожній об’єкт чи список нічого не перекриває.

  • Вузол моделі або векторного сховища в Langflow. Платформа постачає з’єднання моделі як OPENAI_BASE_URL і OPENAI_API_KEY, а з’єднання векторного сховища — як змінні, названі за його псевдонімом, які Langflow читає через поле, що називає глобальну змінну: поле, об’єкт якого містить load_from_db: true, має значенням ім’я змінної, і Langflow читає глобальну змінну з цим ім’ям або, якщо такої не збережено, змінну середовища з цим ім’ям. Чернетка записує кожне з цих полів з ім’ям змінної та load_from_db: true:

    • openai_api_base вузла OpenAIModel — як OPENAI_BASE_URL, а його api_key — як OPENAI_API_KEY;
    • openai_api_base вузла OpenAIEmbeddings — як OPENAI_BASE_URL, а його openai_api_key — як OPENAI_API_KEY;
    • api_key вузла LanguageModelComponent — як OPENAI_API_KEY;
    • api_base вузла EmbeddingModel — як OPENAI_BASE_URL, а його api_key — як OPENAI_API_KEY;
    • pg_server_url вузла pgvector — як AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING, де <ALIAS> — псевдонім з’єднання у верхньому регістрі, у якому кожен символ, крім літери чи цифри, записано як підкреслення.

    Вузол LanguageModelComponent або EmbeddingModel працює на одному з кількох постачальників моделей — на тому, який називає його поле provider, або, якщо воно порожнє, на постачальнику моделі, яку вибирає його поле model, — і передає свій ключ цьому постачальнику. Платформа постачає з’єднання моделі для OpenAI-сумісного клієнта, тому такий вузол записується зі змінними лише там, де він працює на OpenAI. Вузол, що працює на іншому постачальнику, ніколи не під’єднується, як описано вище; вузол, що не вибирає жодного, називає свого постачальника через глобальну змінну або бере модель з іншого вузла, записується без жодної з них, тож чернетка ніколи не спрямовує іншого постачальника на ключ з’єднання. Там, де жодне поле такого вузла не задає адресу його API — вузол LanguageModelComponent не містить такого поля для OpenAI, а api_base вузла EmbeddingModel може бути відсутнім або порожнім там, де воно не може назвати змінну, — клієнт OpenAI, який він запускає, бере OPENAI_BASE_URL із середовища, тож вузол однаково досягає адреси, яку постачає платформа.

    Клієнт вузла OpenAIEmbeddings надсилає свої default_headers поверх тих, що будує з ключа, і зливає свій default_query поверх запиту адреси, яку викликає, тому на такому вузлі, який підключає чернетка, все значення кожного з них записується порожнім зі збереженням його виду, як і headers вузла MCP Tools.

    Поле, яке експорт записує без обох цих членів, не перезаписується — поле облікових даних серед них переноситься як записане або записується порожнім там, де цього вимагає параметр, як описано нижче. Там, де це поле несе адресу частини — і, для вузла LanguageModelComponent або EmbeddingModel, задає її, — там, де такий вузол не працює на OpenAI, або там, де вузол має будь-який інший тип, імпорт повідомляє, що частина досягається за адресою, яку задає потік або типові значення його компонента.

  • Вузол OpenAI у Flowise. Клієнт OpenAI, на якому Flowise запускає вузол chatOpenAI або openAIEmbeddings, читає OPENAI_BASE_URL і OPENAI_API_KEY із середовища там, де Base Path вузла порожній і він не вибирає облікових даних, тому чернетка записує Base Path, який містить експорт, порожнім, а облікові дані, які вибирає вузол, у data.credential, — теж порожніми. Цей клієнт надсилає типові заголовки вузла, його baseOptions, поверх заголовка, який будує з ключа, тому чернетка записує все їхнє значення порожнім зі збереженням його виду. Про вузол моделі будь-якого іншого типу повідомляється, що він досягається за адресою, яку задає chatflow або його власні типові значення.

  • Інструмент або векторне сховище у Flowise. Chatflow читає адресу, яку платформа постачає для них, — AGGREGA_TOOL_<ALIAS>_URL або AGGREGA_VECTOR_STORE_<ALIAS>_URL — лише через змінну Runtime з цим ім’ям, яку ніщо не створює під час запуску. Чернетка нічого для неї не записує, а імпорт повідомляє крок, що змушує chatflow її читати: створіть змінну Runtime на сторінці Variables у Flowise і читайте її у вузлі як $vars.<name>.

  • Будь-який вузол n8n. Платформа постачає з’єднання моделі як OPENAI_BASE_URL і OPENAI_API_KEY, а з’єднання інструментів чи векторного сховища — як AGGREGA_TOOL_<ALIAS>_URL або AGGREGA_VECTOR_STORE_<ALIAS>_URL, тоді як вузол n8n досягає моделі, сховища чи сервісу за адресою, яку задають збережені облікові дані, що він вибирає, або адресою, що містять його власні параметри, а workflow читає змінну середовища лише через вираз, що читає $env, який платформа відхиляє, якщо сутність Aggregate не встановлює values.allow_env_access_in_nodes у true. Чернетка залишає це значення типовим, false, оскільки його встановлення дозволяє кожному workflow і кожному користувачеві, який може його редагувати, читати кожну змінну середовища платформи, зокрема доставлені облікові дані. Тож чернетка нічого не записує у workflow для з’єднання, і про кожну підключену частину повідомляється, що вона досягається не через нього. Клієнтський вузол MCP досягає свого сервера за адресою, яку містить workflow, — як її записав експорт, або жодною, де параметр empty_credentials записує її порожньою, як описано нижче, — а власна адреса сервера — infra.endpoint частини — залишається для сутності Release.

Там, де потік переноситься, про кожну підключену частину повідомляється, що з цього виконується: part-reads-connection, де потік досягає частини через її з’єднання, і part-address-in-flow, де він досягає частини не через її з’єднання — за адресою, яку містить потік, або яку задають типові значення його компонента. Рішення частини каже те саме.

Вузол, який чернетка не підключає до жодного сокета, однаково може досягати з’єднання, яке вона підключає, так, як записано вузол: клієнт OpenAI без власної адреси та ключа читає зі свого середовища OPENAI_BASE_URL і OPENAI_API_KEY, які платформа постачає для з’єднання моделі. Там, де так і є, чернетка записує вузол так, як записала б підключений, щоб ніщо з того, що він містить, не надсилалося замість того, що постачає з’єднання, і повідомляє про нього з part-reads-connection:

  • вузол Langflow OpenAIEmbeddings, поле адреси якого називає змінну OPENAI_BASE_URL, яку постачає платформа, що читається як глобальна змінна, тоді як до сокета моделі підключено частину: його default_headers і default_query;
  • вузол Flowise chatOpenAI або openAIEmbeddings, Base Path якого порожній і який не вибирає облікових даних, а також конфігурація такої моделі, яку вузол agentflow тримає серед своїх входів, тоді як до сокета моделі підключено частину: його baseOptions.

На будь-якому іншому вузлі ці значення не є підключенням: вони переносяться як записані або записуються порожніми там, де цього вимагає параметр, як описано в наступному розділі.

Облікові значення, що містяться в потоці

Перед перенесенням потоку імпорт знаходить у ньому кожне значення, яке може містити облікові дані, у місцях, перелічених нижче, і кожне належить до одного з трьох видів: те, що формат позначає як облікові дані; член конфігурації MCP-сервера, хоч би де формат її зберігав; і вхідне значення, яке формат позначає як не облікові дані, але яке все ж може їх містити, — заголовки запиту, параметри запиту, цілий запит, записаний як командний рядок, вхідне значення, що містить облікові дані під назвою облікових даних.

За замовчуванням імпорт не записує порожнім жодне з них: потік переноситься таким, яким його експортовано, і кожне знайдене значення, що щось містить, — не порожній рядок і не null, — називається в попередженні credential-carried за його вузлом і полем (заголовок чи параметр запиту — за назвою), ніколи не за значенням чи будь-якою його частиною, разом зі значенням параметра empty_credentials, яке записує його порожнім. Параметр вмикає вилучення: marked записує порожнім те, що формат позначає як облікові дані, і кожен член конфігурації MCP-сервера; all записує порожніми також вхідні значення, позначені як не облікові дані. Кожне значення, яке він записує порожнім, повідомляється з credential-emptied за його вузлом і полем, ніколи не за значенням; значення, яке вже порожнє або null, залишається як є і не повідомляється. Значення, якого параметр не приймає, зупиняє імпорт, який тоді нічого не створює, замість того щоб читатися як none.

Знайдене значення, яке є одним посиланням на змінну й нічим більше, не містить власного значення: проста назва змінної, ${NAME} — разом із попередньо визначеними змінними, як-от ${workspaceFolder} чи ${userHome}, — або одна з форм, які визначають MCP-клієнти, ${env:NAME} і ${input:id}. Хоч би що вказував параметр, воно переноситься як записане й не називається в жодному попередженні, хоч би в якому форматі був потік, так само як його записує імпортер MCP. Те саме стосується члена, що є одним посиланням усередині значення, яке формат зберігає як текст, як-от mcpServerConfig у Flowise, записаний як текст JSON, або заголовки й параметри запиту, що зберігаються як об’єкт JSON у тексті у Flowise та n8n: при записі порожнім текст зберігає цей член як записаний.

Посилання, що містить текст після оператора, містить цей текст, який може бути ключем, незалежно від того, чи стоїть перед оператором двокрапка: значення за замовчуванням, ${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 і які вибирає його параметр облікових даних; значення кожного вхідного параметра типу password, оголошеного в його inputParams; а також FLOWISE_CREDENTIAL_ID серед вхідних значень вузла і credential чи FLOWISE_CREDENTIAL_ID усередині об’єкта конфігурації на будь-якій глибині в них, як agentflow зберігає конфігурацію моделі чи інструмента.
  • n8n — id кожних збережених облікових даних, які вибирає вузол, у credentials.<type>.id. Експорт n8n зберігає облікові дані як посилання, ніколи не їхнє значення, а name посилання не знаходиться: n8n, імпортуючи робочий процес на іншому екземплярі, визначає облікові дані, чий id у ньому відсутній, за їхнім типом і назвою. Облікові дані, які старіший експорт вибирає лише за назвою, називають облікові дані, але не містять їх, і не знаходяться. А також значення кожного параметра, який n8n позначає як пароль у визначеннях своїх базових вузлів, — скажімо, secret вузла Crypto або password вузлів, що створюють користувача, — хоч би де серед параметрів вузла він був, причому вузол, використаний як інструмент агента, читається як той вузол, яким він є.

Конфігурація MCP-сервера — записується порожньою за marked і all:

  • Конфігурація mcp_server вузла MCP Tools у Langflow і mcpServerConfig вузла Flowise, записана як текст JSON або як об’єкт: кожне значення заголовка, чи то заголовки є об’єктом, рядками з ключа й значення, чи об’єктами, що зливаються цілком, причому елемент будь-якого іншого виду знаходиться цілком; кожне значення середовища; адреса сервера; команда; і кожен аргумент. Жоден із форматів не позначає адресу, команду чи аргумент як облікові дані, а кожне з них може містити ключ — адреса в частині користувача, шляху чи запиту, — тож усі три теж знаходяться в обох форматах. При записі порожніми команда й кожен аргумент зберігають свої члени, тож конфігурація, що запускає власний сервер, і далі читається як така. Там, де вузол MCP Tools у Langflow під’єднано до з’єднання інструментів, його адреса є підключенням, як описано вище, і ніколи не повідомляється як облікове значення. Конфігурація Flowise, записана як текст, що не читається як об’єкт JSON, знаходиться цілком, оскільки нічого всередині неї знайти неможливо.
  • Вузол MCP Tools у Langflow без поля mcp_server натомість зберігає свій сервер у власних полях — адресу в sse_url, заголовки в headers_input, середовище в env, а весь командний рядок разом з аргументами в command, — і Langflow теж не позначає жодне з них як облікові дані, тож кожне значення заголовка, кожен запис env, адреса й командний рядок знаходяться, а їхні поля й записи зберігаються при записі порожніми. Там, де env є списком, кожен запис повідомляється за його позицією, оскільки назва змінної та її значення ділять один текст. Такий вузол не називає MCP-сервера, тож його ніколи не під’єднують до з’єднання інструментів.
  • Власне поле headers вузла MCP Tools у Langflow, яке Langflow надсилає серверу поверх заголовків його конфігурації, на вузлі, який чернетка не під’єднує: усе його значення, записане порожнім зі збереженням виду, як і на під’єднаному вузлі, і повідомлене один раз, як headers.
  • Компоненти Langflow MCP Tools (SSE) і MCP Tools (stdio), які Langflow позначає як застарілі, зберігають свій сервер в одному полі кожен — вузол MCPSse свою адресу в url, вузол MCPStdio весь командний рядок разом з аргументами в command, — яке знаходиться цілком. Жоден із них не називає MCP-сервера, тож жоден не під’єднується до з’єднання інструментів.
  • Вузол MCP-клієнта n8n — MCP Client Tool, який викликає агент, вузол MCP Client або клієнт сервера з реєстру n8n — зберігає адресу сервера у своєму параметрі endpointUrl або sseEndpoint у першій версії, а свої заголовки — лише як облікові дані, які він вибирає; адреса знаходиться цілком, під’єднано вузол чи ні.

Вхідне значення, яке формат позначає як не облікові дані — записується порожнім лише за all:

  • Заголовки запиту — у Langflow це headers вузла APIRequest, URLComponent, CloudflareWorkersAIEmbeddings або ConfluentKafkaProducer і api_headers вузла DoclingRemote; у Flowise — headers вузла httpAgentflow, getApiChain, postApiChain, openApiChain, apiLoader, openAPIToolkit або searXNG, requestsGetHeaders, requestsPostHeaders, requestsPutHeaders і requestsDeleteHeaders інструментів Requests, а також baseOptions — типові заголовки, які надсилає клієнт моделі, — вузла azureChatOpenAI, azureOpenAIEmbeddings, chatCerebras, chatOpenAICustom, openAIEmbeddingsCustom, chatOpenRouter, chatSambanova або openAI; у n8n — headerParameters, jsonHeaders, headerParametersUi і headerParametersJson вузла n8n-nodes-base.httpRequest (його поточна версія зберігає перші два, попередні версії — інші два), зокрема того самого вузла, використаного як інструмент агента, parametersHeaders і jsonHeaders вузла @n8n/n8n-nodes-langchain.toolHttpRequest та headerParametersUi вузла n8n-nodes-base.graphql. Назва заголовка не містить секрету, тому значення кожного заголовка знаходиться, а назва зберігається, хоч би якої форми набували заголовки: об’єкт назв і значень, рядки з ключем і значенням (у n8n — рядки з name і value) або об’єкти, які Langflow цілком об’єднує в заголовки. Про кожен заголовок повідомляється за його назвою. Елемент списку, що не є рядком заголовка, знаходиться цілком, і про нього повідомляється за його позицією. Заголовки, записані як текст, знаходяться цілком, крім Flowise і n8n, де текст містить заголовки як об’єкт JSON: там у разі спорожнення текст переписується на місці, кожне значення стає порожнім, і про нього повідомляється один раз із назвами заголовків, які він містить. Текст n8n, що починається з =, є виразом, який n8n обчислює під час виконання workflow, і знаходиться цілком. У разі спорожнення порожніми стають усі значення, зокрема значення заголовків без секретів, як-от User-Agent, тож імпортований запит надсилається з ними порожніми, доки автор їх не відновить.
  • Параметри запиту — у Langflow це query_params вузла APIRequest або GoogleSerperAPI і search_params вузла SerpAPI, Serp, SearchAPI або SearchComponent; у Flowise — queryParams вузла httpAgentflow і customParameters завантажувача searchApi; у n8n — queryParameters, jsonQuery, queryParametersUi і queryParametersJson вузла n8n-nodes-base.httpRequest, використаного як інструмент чи ні, parametersQuery і jsonQuery вузла @n8n/n8n-nodes-langchain.toolHttpRequest, а також queryParameters і queryParametersJson, які вузол n8n-nodes-base.facebookGraphApi зберігає серед своїх options. Кожен надсилається як рядок запиту, а параметр запиту може містити ключ (деякі пошукові API приймають його як api_key у рядку запиту), тож кожен знаходиться так само, як заголовки: кожне значення, зі збереженням назви, хоч би якої форми набували параметри, і про кожен повідомляється за його назвою; параметри, записані як текст, знаходяться цілком, крім Flowise і n8n, де текст містить їх як об’єкт JSON, який у разі спорожнення переписується на місці, і про нього повідомляється один раз із назвами, які він містить. У разі спорожнення порожніми стають усі значення, зокрема значення параметрів без секретів, тож імпортований запит надсилається з ними порожніми (або, з вузла HTTP у Flowise, який не надсилає параметрів із порожнім значенням, без них), доки автор їх не відновить.
  • Типові заголовки й типовий рядок запиту на вузлі OpenAI, до якого не веде жодне з’єднання — default_headers і default_query вузла Langflow OpenAIEmbeddings, а також baseOptions вузла Flowise chatOpenAI або openAIEmbeddings, де б не був вузол, зокрема в конфігурації agentflow для моделі, яку він обирає, якщо чернетка не підключає вузол і не знаходить з’єднання, що веде до нього в записаному вигляді; якщо таке є, вони є підключенням, як описано вище. Кожен знаходиться цілком і в разі спорожнення зберігає свій вид (об’єкт як {}, список як [], текст як порожній рядок), і про нього повідомляється один раз.
  • Цілий запит, записаний як командний рядок — curl_input вузла Langflow APIRequest і curl вузла Webhook, які знаходяться цілком, зокрема типове значення Webhook. Жоден не читається під час виконання потоку: перший лише заповнює поля вузла в редакторі, другий показує приклад.
  • Вхідне значення, що містить облікові дані під назвою облікових даних — api_key вузла Langflow OlivyaComponent, verification_token кожного компонента Composio і mem0_config вузла mem0_chat_memory, усе значення якого в разі спорожнення зберігає свій вид; а також webhookSecret і callbackSecret вузла Flowise startAgentflow і bearerToken вузла teradataMCP. Кожне знаходиться цілком. Вхідне значення, назва якого лише нагадує облікові дані (назва ключа, що зберігається деінде, ім’я користувача або параметр, який компонент оголошує як несекретний), не знаходиться.

Окрім значень, які налаштування робить порожніми, того, що чернетка записує, щоб потік досяг своїх частин, маркерів ребра Langflow, записаних так, як їх записує редактор Langflow, і символів повернення каретки, записаних як переведення рядка (див. нижче), потік переноситься таким, яким його експортовано: без жодного з цього — байт у байт.

З’єднання в чернетці не містить значення облікових даних: чорнова сутність Release за посиланням долучає ті, які пред’являє кожне з’єднання, як описано в розділі Що чернетка залишає для Release.

Кожне значення, яке налаштування залишає як є, потрапляє в чернетку, і автор перевіряє його, керуючись попередженнями credential-carried. Жодне правило щодо поля не охоплює решту потоку, тож автор перевіряє і її, перш ніж поширювати чернетку: власний код компонента, який переносить потік і в якому користувацький компонент може містити ключ; вхідні значення, які редактор додає до вузла понад ті, що оголошує його компонент; тіло, з яким надсилається запит, як-от вузла APIRequest або httpAgentflow, що може містити токен; аргументи, які вузол передає клієнту своєї моделі або завантажувачу як окремий об’єкт, як-от model_kwargs вузла Langflow EmbeddingModel або additionalInputs вузла Flowise replicate, що можуть містити ключ під будь-якою назвою; адресу, відмінну від адреси сервера MCP, яка може містити ключ у частині користувача або в рядку запиту; код вузла Code у n8n, а також заголовки чи рядок запиту вузла, що надсилає запит, якого імпортер не перелічує вище; і довільний текст, як-от промпт чи повідомлення.

Що чернетка залишає для Release

Чорнова сутність Release містить у записі платформи та в записі кожної частини те, чого потік не може надати:

  • Образ платформи, як infra.image: власний вибір образу імпортера, у версії, з якою, як відомо, працюють сутності Recipes каталогу для платформи, — langflowai/langflow:1.6.0, flowiseai/flowise:3.1.3 і n8nio/n8n:1.110.1, — під коментарем, що про це повідомляє. Імпорт ніколи не підвищує й не знижує її, щоб слідувати за джерелом; там, де експорт зазначає іншу версію платформи, як це робить last_tested_version потоку Langflow, коментар її називає.
  • Порт, на якому опубліковано платформу, як infra.published_port, лише з --target compose: 7860 для Langflow, 3000 для Flowise і 5678 для n8n — порти, на яких кожна з них обслуговує запити і які її сутність Recipe для Compose публікує на адресі зворотної петлі хоста, 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, що вже є в просторі імен і зберігає значення під ключем даних value. Це ім’я не може надати жодне джерело, тож його записують порожнім під коментарем, що каже, що воно містить, і воно належить до значень, які імпорт лишається винен; створена чернетка сутності Manifest зіставляє core/referenced-secret з helm/k8s-existing-secret.

На кожній іншій цілі, а також без цілі, кожен секрет — це core/secret-value, чий origin є посиланням на змінну — ${LANGFLOW_ADMIN_PASSWORD}, ${FLOWISE_OWNER_PASSWORD} і ${OPENAI_API_KEY} для облікових даних з’єднання з моделлю, — яке ціль, що підставляє посилання на змінні, як це робить Docker Compose під час запуску стеку, читає із середовища, тож жоден файл не містить значення і за нього нічого не лишається винним. Наведений вище chatflow Flowise, імпортований без цілі, отримує чернетку з такою сутністю Release:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
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 оголошує кожен із них із власним ключем там, де платформа проводить з’єднання: owner_password з ключем OWNER_PASSWORD у Flowise, admin_password з ключем LANGFLOW_SUPERUSER_PASSWORD у Langflow і credential з’єднання з моделлю з ключем OPENAI_API_KEY на всіх трьох платформах, кожен під коментарем, що пояснює причину. З --target compose ці рядки записуються активними; без цілі вони записуються закоментованими, як у прикладі вище, щоб ви розкоментували їх, якщо збираєте для compose; з будь-якою іншою ціллю вони не записуються. Release приєднує походження кожного слота, називаючи той самий тип або жодного.

Якщо параметр attach_egress_allowlist має значення true, екземпляр платформи також оголошує під features сутність Feature core/egress-allowlist стандартної бібліотеки як egress-allowlist, тож платформа з’єднується лише з компонентами, до яких ведуть її з’єднання, з власними подами та з DNS кластера — вихідний відповідник ребра uses як оголошеного виклику. Сутність Aggregate оголошує тип приєднання і нічого більше, оскільки приєднання сутності Aggregate не несе infra, а створена чернетка сутності 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 — model_name вузла OpenAIModel або AnthropicModel; model вузла OpenAIEmbeddings; і перевизначення model_name вузла LanguageModelComponent або EmbeddingModel, якщо його задано, а інакше модель, яку вибирає його поле model.
  • Flowise — modelName вузла chatOpenAI, chatAnthropic або openAIEmbeddings.
  • n8n — параметр model вузла чату, доповнення чи ембедингів, який зіставляє таблиця імпортера, або його modelName на вузлах Google Gemini і Vertex, записаний як назва або як значення селектора, у якому його зберігають новіші вузли n8n. n8n не включає до експорту параметр, заданий за замовчуванням, тож вузол, що зберігає модель за замовчуванням, не називає в експорті жодної.

Release не може записати значення. Тож там, де вузол не називає моделі, яку чернетка може записати — не вибирає жодної, називає її через глобальну змінну чи вираз, що читається лише під час виконання потоку, бере її з іншого під’єднаного до нього вузла або має тип, поле моделі якого імпортер не читає, — коментар усередині частини залишає values.model авторові, а імпорт повідомляє про це з model-not-named. Частина, яку чернетка створює як чернетку, пишеться без значення.

Як потік записується в чернетку

Потік записується як літеральний блок YAML, режим обрізання якого зберігає кінцеві розриви рядків, тож values.flow_definition зчитується назад як власний текст потоку. Текст сутності Aggregate читається як шаблон, тож кожне {{, яке містить потік, — chatflow Flowise пише {{<node id>.data.instance}} для кожного з’єднання між двома вузлами, — записується як {{"{{"}}, що інтерполяція перетворює назад на дві дужки, як описує розділ Text that carries its own double braces. Назва моделі записується так само.

Літеральний блок не може передати кожен символ так, як його записано:

  • Повернення каретки — з пари CR LF або окреме — записується як один переведення рядка. JSON-документ містить його лише між своїми токенами, де будь-який пробільний символ читається однаково, тож платформа читає той самий потік. Імпорт повідомляє їхню кількість з carriage-returns-rewritten.
  • Будь-який інший символ, який літеральний блок не може передати, не дає перенести потік: символ розриву рядка — U+0085, U+2028 або U+2029; керівний символ, окрім табуляції та переведення рядка, — від U+0000 до U+001F, U+007F і від U+0080 до U+009F; несимволи U+FFFE і U+FFFF; і байт, що не є частиною послідовності UTF-8. Тоді values.flow_definition залишається незаданим із коментарем про це, решта створюється як чернетка, а імпорт повідомляє definition-not-carried для кожного виду символу, з їхньою кількістю в потоці та рядком і стовпцем першого.

Потік також не переноситься, якщо значення, яке чернетка записує порожнім чи наново, відсутнє в байтах експорту там, де його містить розібране дерево, і імпорт повідомляє definition-not-carried, називаючи місце цього значення. Ідентифікатором потоку тоді є його власний, якщо чернетка може його перенести, а інакше — похідний від ідентифікаторів вузлів потоку.

Вузол за вузлом

З layout: nodes імпорт створює чернетку кожного вузла потоку як окремої сутності Component і записує:

  • aggregate.yaml — чернетку сутності Aggregate, названу за потоком, як описано в розділі Як іменується чернетка, що компонує вузли потоку: запис для кожного, а кожне ребро потоку — з’єднання uses вузла, який воно живить, причому його сокет і псевдонім названо за ключем вузла, що його живить, тож вузол, який живлять кілька вузлів, дає кожному з’єднанню власний псевдонім.
  • один файл у components/ для кожного вузла, який він створює, — чернетку сутності Component з назвою <target_namespace>/<category>/<name>, де назву взято з типу вузла, з версією 0.1.0, її полями значень як рядковими полями закритого об’єкта values і полями облікових даних як обов’язковими слотами облікових даних, доставку яких вирішує сутність Recipe.
  • release.yaml — чернетка сутності Release з тим самим іменем, що називає цю сутність Aggregate, із записом для кожного вузла.

Сам потік не переноситься, і значення жодного поля не читається.

Перенесення самого експортованого потоку

Типова чернетка переносить потік: екземпляр платформи приймає експорт як values.flow_definition, записаний так, як описано в розділі Як потік записується в чернетку. Автор, який записує потік в Aggregate вручну — у чернетку, розкладену вузол за вузлом, або у власну сутність Aggregate, — записує його так само. Component, що виконує потік у тому вигляді, в якому його створено, приймає експорт як значення — flow_definition у core/ai-agent/langflow та core/ai-agent/flowise зі стандартної бібліотеки, — а текст сутності Aggregate читається як шаблон, тож подвійні фігурні дужки, які містить експорт, читалися б як дії шаблону: чат-потік Flowise записує {{<node id>.data.instance}} для кожного з’єднання між двома вузлами, промпт Flowise називає змінну як {{question}}, а експорт Langflow містить вихідний код своїх компонентів, де дужки також можуть траплятися. Записуйте кожне {{ в експорті як {{"{{"}} усередині блокового скаляра, і інтерполяція відновить текст експорту до того, як його прочитають Recipes сутності Component; розділ Текст, що містить власні подвійні фігурні дужки пояснює чому. Значення облікових даних, яке містить експорт, належить до секрету, який приєднує Release, а не до сутності Aggregate: залишайте його порожнім, як це робить чернетка, коли цього вимагає налаштування empty_credentials.

# Aggregate fragment — a Flowise chatflow carried as exported
spec:
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. Кожен сервер є таким інструментом, тож імпортер не зважує кандидатів і не повідомляє про рішення щодо зіставлення.

Що він читає

  • Конфігурація клієнта. .mcp.json у Claude Code, claude_desktop_config.json у Claude Desktop і .cursor/mcp.json у Cursor перелічують свої сервери за іменем у mcpServers; .vscode/mcp.json у Visual Studio Code перелічує їх у servers, а файл, що перелічує сервери в обох, спершу читається в mcpServers. Сервер, чий type — stdio, або який не вказує type і містить command, запускається з командного рядка — свого command і своїх args — зі своїм env як середовищем. До сервера, чий type — http, streamable-http або sse, або який не вказує ні type, ні command і містить url, звертаються за його url і надсилають йому його headers.
  • Опис сервера в реєстрі. server.json, який публікує реєстр MCP: його name і його перший пакет, або, якщо пакетів немає, його перший віддалений сервер. Пакет npm або PyPI запускається з командного рядка, який утворюють його засіб запуску — його runtimeHint, або npx для npm і uvx для PyPI, — його runtimeArguments, пакет із версією, записаний як <identifier>@<version> для npm і <identifier>==<version> для PyPI, і його packageArguments, зі змінними environmentVariables як середовищем. Позиційний аргумент — це його value або його default; іменований аргумент записується як <name>=<value>, якщо він має одне з них, і як його name, якщо не має жодного. Пакет OCI запускається з образу, який називає його identifier. До віддаленого сервера звертаються за його url і надсилають йому його headers. Кожен інший пакет і віддалений сервер, перелічений в описі, названо в коментарі, оскільки один екземпляр запускає лише один із них.

Кожен інший член сервера — cwd, envFile, auth у Cursor або член, якого його вид не читає, як-от url сервера, що запускається з командного рядка, — ніде не записується і називається в коментарі над записом сервера в сутності Release, оскільки жоден інфраструктурний ключ core/ai-tool/mcp його не приймає. inputs конфігурації, що описують, які значення запитує Visual Studio Code, і не містять значень, не читаються. Сервери, їхнє середовище та їхні заголовки зберігають порядок, у якому їх записує джерело, окрім конфігурації, що читається як JSON із коментарями: вона зберігає порядок, у якому їх записує її розібране дерево, — порядок імен (див. Конфігурація з коментарями).

Каталог читається через конфігурації клієнтів, які він містить, — кожен файл з одним із чотирьох імен на будь-якій глибині — у порядку їхніх шляхів, і кожен сервер кожного файлу потрапляє в чернетку однієї сутності Aggregate.

Чим стає сервер

aggregate.yaml — це чернетка сутності Aggregate, названа за джерелом, як описує Як називається чернетка, що містить по одному екземпляру core/ai-tool/mcp на кожен сервер. Ключем екземпляра є ім’я його сервера в нижньому регістрі, де кожну послідовність символів, відмінних від літер і цифр, записано одним дефісом, із числовим суфіксом, якщо цей ключ уже зайняв попередній сервер. Якщо ключ не збігається з ім’ям сервера в записаному вигляді або імпорт прочитав кілька файлів, коментар над екземпляром називає сервер і файл, з якого він походить. Жодного агента, що їх використовує, у чернетці не створюється.

Поруч із ним release.yaml — це чернетка сутності Release з тим самим іменем, чий spec.aggregate називає сутність Aggregate і яка містить для кожного екземпляра операційні вхідні дані, зазначені в джерелі:

  • для сервера, що запускається з командного рядка, — infra.stdio_command, його команда, а потім кожен аргумент, по одному елементу на кожен; і infra.stdio_runtime, екосистема засобу запуску: npm, якщо команда — npx, npm або node, pypi, якщо це uvx, uv, python або python3, а для пакета з реєстру — його реєстр, npm або pypi;
  • для сервера, до якого звертаються за адресою, — infra.endpoint: адреса без частини користувача, запиту та фрагмента, оскільки сутність Component приймає адресу без жодної частини, що містить ключ; кожну пропущену частину записано в коментарі над записом, поруч з адресою, як описує розділ Облікові значення, які містить сервер;
  • для пакета OCI — infra.image;
  • для жодного сервера, на жодній цілі, infra.published_port: чернетка ніколи не публікує сервер на хості;
  • для середовища сервера — слот server_env, приєднаний за посиланням відповідно до цілі імпорту. На --target helm це core/referenced-secret, що називає Kubernetes Secret, який уже є в просторі імен і містить по одному ключу даних на змінну, кожен з іменем змінної, яку він містить; ім’я Secret записується порожнім під коментарем, що називає ключі даних, і воно належить до значень, які імпорт лишається винен. На кожній іншій цілі, а також без цілі, це core/referenced-secret-set з одним записом під infra.entries на змінну, з іменем змінної як ключем і значенням у тому вигляді, як його записує джерело, тож посилання на змінну, як-от ${GITHUB_TOKEN}, лишається посиланням, яке ціль, що підставляє посилання на змінні, читає із середовища.

Те, чого джерело не зазначає, записується порожнім під коментарем, що каже, що це таке: команда, чийого засобу запуску не містить жоден із мостових образів, залишає infra.stdio_runtime порожнім, і імпорт лишається його винен; аргумент, який опис у реєстрі залишає користувачеві, записується порожнім елементом, а змінна, значення якої джерело не записує, — записом із порожнім значенням, і кожне з них названо в коментарі над записом.

Як і кожна чернетка сутності Release, вона записує metadata.environment як development під коментарем, що каже, що це типове значення чернетки, яке слід змінити, а без цілі — spec.manifest як порожній рядок, який імпорт лишається винен. Якщо задано ціль, імпортер сам створює чернетку сутності Manifest, оскільки каталог реалізує core/ai-tool/mcp через кілька сутностей Recipes і лише імпортер знає, як працює кожен сервер: він зіставляє кожен сервер за його ключем, під mappings.components.name, з реалізацією цілі для того, як працює сервер, — mcp-stdio-bridge для командного рядка, mcp-remote для адреси, mcp для образу, як-от helm/mcp-stdio-bridge або compose/mcp-remote, — а тип секрету, як який приєднано середовище, — з його реалізацією: helm/k8s-existing-secret на helm і compose/dotenv-secret-set на compose. Імпорт доповнює цю сутність Manifest і називає її в сутності Release, як описує розділ Що додає ціль.

.mcp.json у Claude Code, що перелічує сервер, до якого звертаються через HTTP, і сервер, що запускається через npx:

{
"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}" }
}
}
}

потрапляє в чернетку так:

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
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/mcp
release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
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: ""
manifest.yaml
apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/mcp
version: 0.1.0
spec:
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 (url вузла remote-search перенесено з його запитом як записано)», — і ніколи за його значенням. Якщо параметр empty_credentials має значення marked або all, кожне з них записується порожнім і повідомляється з credential-emptied: елемент командного рядка — як порожній елемент, а значення середовища — як порожнє значення, і кожне з них названо в коментарі над записом; адреса — як порожній infra.endpoint, який імпорт лишається винен; а значення заголовка або частина адреси пропускаються в коментарі, який називає лише заголовок або частину. infra.stdio_runtime клієнта визначається з команди так, як її записує Release, тож команда, записана порожньою, теж залишає його порожнім, і імпорт лишається його винен. На --target helm сутність Release взагалі не записує значень середовища: їх містить Secret, який називає слот server_env.

Значення, яке є лише одним посиланням на змінну і нічим іншим, — просте ім’я ${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 записується в короткій формі — postgres для docker.io/library/postgres:16. Репозиторій зіставляється через таблицю образів — таблицю від репозиторію образу до Component каталогу, для якого Recipe для Compose стандартного каталогу запускає образ цього репозиторію. Таблиця генерується з Recipes для Compose і Components стандартного каталогу під час збирання імпортера і компілюється в нього, тож під час імпорту не читається жоден Recipe, а таблиця містить мітки стандартного каталогу, хоч би що містив ваш каталог; сутність Plugin імпортера називає у своєму описі ревізію хабу, з якої згенеровано таблицю. З кожного Recipe таблиця читає Component, який реалізує Recipe, і образ його контейнера з іменем main, якщо цей образ записує свій репозиторій у власному тексті або є записом locals, що це робить. Recipe, що запускає образ, який повністю називає Release, або образ, який його шаблон складає інакше, не додає рядка, як і образ, що Recipe запускає поруч зі своїм основним контейнером. Два Recipes, що називають один репозиторій для різних Components, зупиняють генерування таблиці, тож рядок ніколи не називає один із двох. Для Component, який називає рядок, таблиця читає його мітки так, як їх отримує імпорт, — у версії, до якої розв’язується посилання на Component без версії, разом із тими, що успадковуються через extends, — і записує в рядок як його ознаки всі мітки, крім component.aggrega.ai/category. Recipe, що реалізує Component, якого не містить стандартний каталог, теж зупиняє генерування таблиці.

Рядок читається так само, як рядок таблиці імпортера потоків: 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 із мітками, які дає йому стандартний каталог, сервіс, зіставлений рядком, є для нього збігом високого рівня з оцінкою 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 записує назад як context_size Compose. Якщо каталог не містить core/ai-model/docker-model-runner, для моделі створюється чернетка <target_namespace>/ai-model/<key> — сутність Component категорії ai-model, значення якої оголошують model, context_size і runtime_flags, а її екземпляр записує кожне, яке зазначає джерело. Кожна модель має рішення, що вказує, який саме варіант — 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, образ у тому вигляді, як його записано, і infra.port, порт, який контейнер прослуховує, з першого запису ports або expose, якщо ports не містить жодного. З --target compose вона також записує infra.published_port, порт хоста, який публікує той самий запис ports, так, як його зазначає джерело, під коментарем про те, що він доступний лише з цієї машини, будь-якому процесу, що на ній працює, і що видалення рядка залишає сервіс внутрішнім; порт хоста нижче 1024, якого published_port не приймає, не записується, а коментар над записом його називає. Коментар над записом кожного сервісу записує те, що зазначає джерело, але що не переносить жоден ключ чернетки — образ сервісу, зіставленого з іншою сутністю Component, тег якого чернетка не перекладає, його ports, expose, volumes і кожну змінну його environment, яку чернетка не перекладає, — щоб ви перенесли це туди, де сутність Component це приймає. Те, що чернетка залишає для сутності Release, — образ сервісу, що не називає жодного, як-от сервісу, що збирає власний, і порт, який не є одним числом, — записується порожнім під коментарем, що пояснює чому. Збірка розміщує лише ті екземпляри, які називає сутність Release, тому екземпляр кожної моделі має порожній запис, <key>: {}, після записів сервісів: як екземпляр core/ai-model/docker-model-runner, який не приймає на Compose жодних вхідних даних без значення за замовчуванням, так і модель, для якої створено чернетку як окремої сутності Component, тож модель із чернетки вже розміщено, і вона збирається, щойно ви напишете Recipe, що її реалізує. Порт, якого сутність Component не приймає, як-от нижчий за мінімум 1024 для core/compute/server, записується так, як його зазначає джерело, і збірка зупиняється, назвавши його. Сутність Release записує metadata.environment і, без цілі, порожній spec.manifest, як і в імпортера MCP; якщо задано ціль, імпорт створює чернетку сутності Manifest, як описує розділ Що додає ціль, зіставляючи кожну сутність Component із Recipe, що реалізує її на цій цілі, — core/compute/server із compose/server або helm/server, а core/ai-model/docker-model-runner із compose/docker-model-runner або helm/docker-model-runner.

compose.yaml, що запускає PostgreSQL і власний API, який від нього залежить:

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 зі стандартної бібліотеки, перетворюється на таку чернетку:

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
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: db
release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
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, імпортер читає його образ і середовище так, як їх читають Compose Recipes стандартного каталогу для цієї сутності Component, на основі того, що таблиця образів записує про кожен Recipe, і перекладає їх у чернетки:

  • Тег образу — це ключ інфраструктури, з якого Recipe будує посилання на образ, як-от engine_version — 16 для postgres:16, — записаний у сутності Release під коментарем, що називає образ джерела.
  • Змінна, яку Recipe задає з одного зі значень сутності Component, — POSTGRES_DB, POSTGRES_USER, — значення якої містить текст, є цим значенням екземпляра, database або user, якщо сутність Component каталогу його оголошує, і записується в сутності Aggregate під коментарем, що називає змінні.
  • Змінна, з якої Recipe читає пароль, як-от POSTGRES_PASSWORD, значення якої є одним посиланням на змінну, є секретом, приєднаним у цьому слоті, що читається зі змінної, яку називає посилання, і оголошується з ключем, під яким його читає Recipe.

А для кожного сервісу — кожна змінна його середовища, не прочитана таким чином:

  • Значення, яке є назвою іншого сервісу проєкту, якщо рядок того сервісу називає ключ provides, що публікує його ім’я хоста, створює з’єднання з тим сервісом, блок inject якого доставляє змінну з цього ключа, — CACHE_HOST: cache стає CACHE_HOST із host кешу.
  • Значення, рівне значенню, яке інший сервіс задає для своєї сутності Component і яке ця сутність Component публікує, — DATABASE_USER: notes поруч із сервісом PostgreSQL, що задає POSTGRES_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 читає target_namespace, reuse_mode, reuse_threshold, emit_hints, render_mode, mapping_overrides і empty_credentials, як їх описує розділ Параметри, і жодних інших параметрів. Підказка, якою керує emit_hints, записується лише у файлі чернетки сутності Component; чернетка сутності Aggregate не містить жодної.

Імпортер Dify

importer/dify читає застосунок, експортований із Dify у його DSL — YAML-документі, який Dify записує для застосунку, — і створює чернетку сутності Aggregate, що компонує інсталяцію Dify зі стандартної бібліотеки, core/dify, а застосунок передається в параметрі інсталяції app_definition. Інсталяція імпортує його під час розгортання через крок, який для нього рендерить Recipe її API-сервера.

Що він читає

  • Застосунок. kind, що дорівнює app; version — версія DSL, якою написано застосунок; і app з його mode.
  • Workflow або chatflow — mode workflow або advanced-chat — зберігає свій граф у workflow: кожен вузол workflow.graph.nodes, що називає свій тип у data.type, є вузлом застосунку в порядку, у якому їх перелічує граф, а workflow.environment_variables містить змінні, які він читає.
  • Застосунок типу chat, agent chat або completion зберігає свою конфігурацію в model_config: його model, кожна база знань у dataset_configs.datasets.datasets і кожен інструмент у agent_mode.tools є вузлом застосунку, названим за своїм місцем там, наприклад model_config.model. Застосунок режиму agent є одним вузлом, agent.
  • Плагіни, яких він потребує. Кожен запис dependencies також є вузлом, названим dependencies.<n>, того типу, який називає запис, наприклад marketplace.

Ніщо інше не визначає, що потрапляє в чернетку: передається весь застосунок.

Чим стає застосунок

aggregate.yaml — це чернетка сутності Aggregate, названа за застосунком, як описує Як називається чернетка, що компонує один запис core/dify з ключем dify, параметр app_definition якого передає застосунок у тому вигляді, як його записано, — як Як потік записується в чернетку описує для потоку, тож власні посилання Dify {{#…#}} досягають інсталяції такими, як їх експортовано. Інсталяція сама з’єднує кожне з’єднання свого API-сервера — його базу даних, кеш, векторне сховище, пісочницю, середовище виконання плагінів і проксі для вихідного трафіку, — тож чернетка не створює жодної сутності Component і нічого не з’єднує: кожен вузол лишається в застосунку, і його рішення про це повідомляє. Поруч із нею release.yaml — це чернетка сутності Release з тим самим іменем, яка розміщує інсталяцію в межі platform і передає те, чого застосунок не може надати.

Імпорт бачить Components каталогу робочого простору і жодної з його Aggregates, тому не перевіряє, чи каталог містить core/dify, і про це повідомляє коментар над записом. Якщо каталог не містить core/ai-agent/dify — API-сервера, який запускає core/dify, — імпорт видає попередження platform-not-in-catalog і все одно створює запис.

Секрет застосунку інсталяції — ключ, яким Dify підписує свої сесійні cookie та яким шифрує збережені облікові дані постачальників моделей, — це параметр secret_key з core/dify, що не має значення за замовчуванням. Тому чернетка оголошує власний параметр secret_key — рядок, обов’язковий, завдовжки щонайменше один символ і без значення за замовчуванням — і передає його кожному запису core/dify, який вона записує, щоб сутність Release заповнила його у своїх parameters; збірка, чия сутність Release лишає його незаданим, зупиняється й називає його.

Застосунок імпортується під обліковим записом власника інсталяції, який сутність Release називає у своєму записі маршрутизації для інсталяції: infra.owner_email у компоненті інсталяції api і слот owner_password у тому самому компоненті, приєднаний як core/referenced-secret; без них збірка зупиняється. Електронну адресу власника не може надати жодне джерело, тож її записано порожньою під коментарем, що пояснює, що це таке, і імпорт позначає це значення як потрібне.

Для кожної цілі той самий запис маршрутизації встановлює infra.marketplace_enabled у true у компонентах api, worker і scheduler інсталяції, кожне під коментарем, що пояснює чому: інсталяція не досягає нічого від постачальника Dify, якщо сутність Release цього не дозволяє, кожен із трьох читає власне налаштування, а Dify встановлює плагін, що обслуговує модель застосунку, наприклад модель OpenAI, зі свого маркетплейсу плагінів.

Секрет застосунку та пароль власника є секретами, які створюються в чернетці за посиланням відповідно до цілі імпорту:

  • З --target helm кожен із них називає Kubernetes Secret, що вже є в просторі імен: secret_key — ім’я Secret, який core/dify читає за ключем даних secret-key, а owner_password — Secret, що містить пароль за ключем даних value. Жодне з цих імен не може надати жодне джерело, тож кожне записано порожнім під коментарем, що пояснює, що це таке, і імпорт позначає обидва значення як потрібні; чернетка сутності Manifest зіставляє core/referenced-secret з helm/k8s-existing-secret.
  • За будь-якої іншої цілі, а також без цілі, кожен із них — це посилання на змінну: secret_key як "${DIFY_SECRET_KEY}", а пароль власника як "${DIFY_OWNER_PASSWORD}" — імена, які читають сутності Recipes Dify для Compose зі стандартного каталогу, — і Docker Compose читає їх із середовища під час запуску стека, тож для жодного з них нічого не потрібно; з --target compose чернетка сутності Manifest зіставляє core/referenced-secret з compose/dotenv-referenced-secret.

Якщо задано ціль, сутність Manifest зіставляє тип кожного компонента, який компонує інсталяція, а також тип самої чернетки, як описує Що додає ціль.

Створений вручну workflow-застосунок під назвою Support Answers, який імпортують тести цього імпортера, без жодних налаштувань перетворюється на таку чернетку:

aggregate.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
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, а в записі маршрутизації, який розміщує інсталяцію, називає власника й вмикає маркетплейс плагінів, причому кожне потрібне значення записано порожнім:

release.yaml
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
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}" і позначає як потрібну лише електронну адресу власника; вона також записує infra.published_port у компоненті api, 5001, і у фронтенді, компоненті console, 3001, кожне під коментарем, який повідомляє, що сервіс доступний лише з цієї машини, для будь-якого процесу, що на ній працює, і що видалення рядка залишає сервіс внутрішнім, а під портом компонента api — infra.console_url з адресою, за якою опубліковано консоль, "http://127.0.0.1:3001", яку сервер Dify використовує як адресу консолі. Покроковий посібник з імпорту Dify збирає застосунок для обох цілей і запускає його в Kubernetes.

Що Dify налаштовує сам

Dify сам усередині себе налаштовує провайдерів моделей та інструментів, які викликає застосунок, а core/ai-agent/dify не оголошує сокета для моделі, тож чернетка нічого не з’єднує. Про кожен вузол, що їх називає, повідомляється через part-configured-in-platform і в його рішенні — за тим, що він називає:

  • вузол llm, question-classifier або parameter-extractor, а також model_config.model chat-застосунку: модель — за її назвою та її провайдером;
  • вузол tool, а також інструмент chat-застосунку: інструмент — за його назвою та його провайдером;
  • вузол agent: стратегія агента і плагін, що її надає;
  • вузол knowledge-retrieval, а також база знань chat-застосунку: бази знань, з яких він отримує дані, і модель, якою він маршрутизує запит або переранжовує результати, якщо він її називає. Застосунок називає базу знань ідентифікатором інсталяції, з якої його експортовано, і не містить жодного з її документів і жодного сховища, тож кожна створюється всередині Dify, у векторному сховищі, яке інсталяція з’єднує зі своїм API-сервером;
  • залежність: плагін — за ідентифікатором, під яким Dify його встановлює, і за тим, звідки Dify його встановлює.

Кожен інший вузол лишається в застосунку без жодних повідомлень.

Облікові дані, які містить застосунок

Імпортер знаходить у тому порядку, у якому їх записує застосунок:

  • значення кожної змінної середовища, value_type якої — secret, яке Dify позначає як облікові дані. Експорт Dify записує його порожнім, якщо експорт не включає секрети;
  • authorization.config.api_key вузла HTTP-запиту, який Dify позначає як облікові дані й експортує в записаному вигляді;
  • збережені облікові дані, які вузол tool або інструмент вузла agent вибирає в credential_id, які Dify позначає як облікові дані й записує лише тоді, коли експорт включає секрети;
  • headers і params вузла HTTP-запиту, які Dify не позначає як облікові дані і які можуть їх містити, кожне цілком.

За замовчуванням кожне з них, що містить значення, передається в застосунку в записаному вигляді й називається в попередженні credential-carried за своїм вузлом — workflow для змінної середовища — і своїм полем, але ніколи за значенням. Якщо параметр empty_credentials має значення marked, кожне значення, яке Dify позначає як облікові дані, записується порожнім, а за all — також заголовки й параметри запиту; про кожне повідомляється через credential-emptied. Значення, яке є одним посиланням на змінну і нічим іншим, не містить значення і передається в записаному вигляді незалежно від налаштування та не називається в жодному попередженні, як у потоці. Значення записується порожнім у власному тексті застосунку: скаляр після його ключа замінюється на '', і більше нічого не змінюється. Застосунок передається лише тоді, коли парсер, що обслуговує parse:yaml, зчитує результат назад як експортований застосунок, у якому порожніми стали саме ці значення; інакше він не передається, app_definition лишається незаданим із коментарем, а definition-not-carried пояснює причину — як для застосунку, у якому YAML-аліас читає значення секрету, яке запис цього значення порожнім теж змінив би. Значення, яке налаштування лишає в записаному вигляді, ніколи не переписується, тож воно ніколи не заважає передати застосунок.

Версія DSL

Якщо застосунок написано версією DSL, новішою за 0.7.0 — версію, яку записує Dify 1.17.0, версія, що її core/ai-agent/dify запускає за замовчуванням, — імпорт видає попередження dsl-version-newer. Dify затримує імпорт такого застосунку до підтвердження, яке дає крок, що імпортує його під час розгортання, тож перевірте застосунок на сумісність із версією Dify, яку запускає Release.

Параметри, які він читає

Імпортер Dify читає target_namespace, empty_credentials, layout, attach_egress_allowlist і render_mode, як їх описує розділ Налаштування, а також reuse_mode, reuse_threshold, emit_hints і mapping_overrides, які нічого не змінюють у чернетці макета за замовчуванням: кожен вузол лишається в застосунку. attach_egress_allowlist нічого не приєднує, оскільки запис скомпонованої сутності Aggregate приймає параметри й жодної сутності Feature, і за значення true імпорт видає попередження feature-not-attached. layout: nodes створює чернетку кожного вузла як окремої сутності Component, як описує Вузол за вузлом, і не передає застосунку.

Імпортер CrewAI

importer/crewai читає агентів і завдання, які проєкт CrewAI оголошує у своїх конфігураційних файлах, і створює чернетку сутності Aggregate, що містить по одному екземпляру агента CrewAI зі стандартної бібліотеки, core/ai-agent/crewai, на кожного агента, кожен під’єднаний до моделі, яку називає його конфігурація, а поруч — чернетку сутності Release.

Що він читає

CrewAI зберігає поведінку екіпажу (crew) у програмі, а його агентів і завдання оголошує в конфігураційних файлах, в одному з двох розташувань, і імпортер читає будь-яке з них:

  • Класичний проєкт — config/agents.yaml, де кожен агент має ключем своє ім’я, і config/tasks.yaml, де кожне завдання має ключем своє ім’я; обидва читаються як YAML. Агенти читаються в тому порядку, у якому їх записує agents.yaml.
  • Проєкт у розташуванні JSON-first — crew.jsonc, що перелічує агентів екіпажу за іменами в agents і його завдання в tasks, та agents/<name>.jsonc, по одному файлу на агента; усі читаються як JSON з коментарями, тож їхні коментарі та кінцеві коми читаються так, як їх читає CrewAI. Агенти читаються в тому порядку, у якому їх перелічує crew.jsonc, а за ними — файли решти агентів за порядком імен; агента, якого перелічує екіпаж, але чий файл імпорту не передано, названо в коментарі, і для нього нічого не створюється. Те саме розташування, записане строгим JSON — crew.json і agents/<name>.json, — читається так само. Де екіпаж або агента записано в обох варіантах, читається файл .jsonc, як його читає CrewAI, а файл .json названо в коментарі як непрочитаний.

З агента імпортер читає його role, goal і backstory; allow_delegation і verbose — на верхньому рівні його оголошення або в settings, причому перевагу має settings, як їх читає CrewAI; його llm; та імена його tools. Із завдання він читає його ім’я та агента, якому його призначено. Кожен інший член названо в коментарі, і він нікуди не переноситься.

Каталог передається імпортеру лише як файли, які називають його сигнатури, тож програма екіпажу — crew.py класичного проєкту, main.py потоку, інструмент, який проєкт визначає на Python, — ніколи не читається. Файл, імпортований окремо, читається як оголошення, якому відповідає його форма. Каталог проєкту може містити кілька екіпажів, кожен з яких читається з власного каталогу.

Чим стає проєкт

aggregate.yaml — це чернетка сутності Aggregate, названа за екіпажем, як описує Як називається чернетка, що починається з коментарів, які називають прочитані оголошення, зазначають, що програму екіпажу не прочитано, і перелічують завдання кожного екіпажу з агентом, якому призначено кожне. Вона містить для кожного агента, з його ім’ям як ключем, екземпляр core/ai-agent/crewai з:

  • role, goal і backstory в оголошеному вигляді;
  • allow_delegation в оголошеному вигляді та false, де агент його не оголошує;
  • log_level DEBUG для агента, оголошеного як verbose, який описує кожен крок своїх міркувань, і INFO для агента, що таким не є, який повідомляє лише про поступ і проблеми. verbose або allow_delegation, що не є ні true, ні false, залишається за типовим значенням сутності Component і названий у коментарі;
  • його з’єднанням model, під’єднаним до екземпляра моделі, яку називає його llm.

llm, записаний як <provider>/<model> або як об’єкт, що називає модель у model, model_name чи deployment_name, називає провайдера й модель. Модель — це екземпляр сутності Component каталогу для цього провайдера — core/ai-model/<provider>, де підкреслення в імені провайдера читається як дефіс, а azure — як azure-openai, — з іменем моделі як ключем і моделлю як його values.model; агенти, що називають одного провайдера й одну модель, спільно використовують один екземпляр. Де каталог робочого простору не містить сутності Component з таким іменем, створюється її чернетка, <target_namespace>/ai-model/<provider>, що оголошує значення model, і її рішення про це повідомляє; мітка model.aggrega.ai/api, за якою сокет model агента вибирає сутність Component, і сутність Recipe, що публікує її кінцеву точку та модель, залишаються вам, як зазначає коментар на її початку. llm, що не називає провайдера, — просте ім’я моделі, для якого CrewAI визначає провайдера під час виконання програми, або ім’я llm, який визначає програма, — посилання на програму, а також агент, що не оголошує llm, який CrewAI тоді читає із середовища, у якому виконується його програма, ні до чого не під’єднуються, і коментар над агентом пояснює чому; збірка зупиняється, називаючи сокет model, доки до нього щось не під’єднано.

Завдання — це логіка, яку виконує програма екіпажу, а інструмент — код, який програма визначає або завантажує: жодне з них не стає сутністю Component. Про кожне повідомляється в рішенні, яке нічого не вибирає, а інструмент, чиє ім’я — без кінцевого Tool, дефісів і підкреслень — збігається з іменем сутності Component інструмента, яку містить каталог, несе цю сутність Component як підказку: search_tool і SearchTool обидва вказують на core/ai-tool/search. core/ai-agent/crewai не оголошує сокета для інструмента, тож для нього нічого не під’єднується.

release.yaml поруч — це чернетка сутності Release з тим самим іменем, що називає цю сутність Aggregate. Вона записує infra.image кожного агента — образ, що виконує програму екіпажу, якого не називає жодне оголошення, — порожнім під коментарем, що пояснює, що це таке, і імпорт позначає це значення як потрібне. З --target compose запис кожного агента також записує infra.published_port, 8000, — порт, який infra.port сутності Component типово називає для програми і який її сутність Recipe для Compose публікує на loopback-адресі хоста, 127.0.0.1, — під коментарем, який повідомляє, що сервіс доступний лише з цієї машини, для будь-якого процесу, що на ній працює, і що видалення рядка залишає сервіс внутрішнім; другий агент отримує наступний вільний порт, тож два агенти класичного проєкту опубліковано на 8000 і 8001. Облікові дані, які кожен агент подає своїй моделі, вона прикріплює в credential до його з’єднання model за посиланням і ніколи як значення: жодне оголошення не називає для них змінної, тож їх читають зі змінної, з якої клієнтські бібліотеки постачальника читають свій ключ API, — OPENAI_API_KEY для OpenAI, — як посилання ${…} для кожної цілі, крім 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 розміщує такий проєкт, — оскільки його оголошення не називають жодного екіпажу, він отримує назву за цим каталогом:

aggregate.yaml
# 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_writer
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
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 і образ кожного агента:

release.yaml
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: {}

Тоді кожен агент рендериться з образом, який ви вкажете у відповіді, і отримує кінцеву точку моделі та ім’я моделі як OPENAI_BASE_URL і MODEL — змінні, з яких їх читає CrewAI.

Облікові дані, які містить оголошення

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, і створює чернетку Aggregate, що містить по одному екземпляру агента LangGraph зі стандартної бібліотеки, core/ai-agent/langgraph, на кожен граф, кожен під’єднаний до сховища даних, у якому його checkpointer зберігає стан, і до моделі, і поруч із ним Release, що містить середовище, яке задає конфігурація. Імпортер читає цю конфігурацію і ніколи не читає код графів.

Що він читає

Застосунок LangGraph зберігає свої графи в коді й оголошує їх у langgraph.json: у graphs ідентифікатор кожного графа відповідає шляху імпорту графа в коді застосунку — ./src/agent/graph.py:graph або module:attr — або об’єкту, який називає цей шлях у path і описує граф у description. Імпортер читає в тому порядку, у якому їх записує конфігурація:

  • graphs — ідентифікатор кожного графа, його шлях імпорту та його опис;
  • checkpointer — його backend: default, що означає PostgreSQL і що LangGraph використовує, коли жоден не вказано; mongo, база даних, що підтримує протокол MongoDB; або custom, checkpointer, який код застосунку визначає за path;
  • 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 checkpointer.

Каталог передається імпортеру як langgraph.json і жодного іншого файлу, тож із нього ніколи не читаються ні код застосунку, ні файл середовища. Файл середовища потрапляє до імпортера лише тоді, коли його передає with.sources імпортера, і ніколи не розбирається: з того, який називає env конфігурації, — зіставленого за останнім сегментом шляху, який він називає, — читаються лише імена змінних, а файл середовища, який не називає жодна конфігурація, називається в коментарі як непрочитаний. Якщо імпорт не отримав файлу, який називає конфігурація, Aggregate називає його як непереданий і вказує назвати його в with.sources імпортера, а його змінні залишаються для Release:

plugins:
importer:
- uri: importer/langgraph:<version>
with:
sources:
- ./local.env

Конфігурація, імпортована окремо, читається незалежно від її імені. Каталог може містити кілька застосунків, кожен із яких читається з власного каталогу.

Чим стає застосунок

aggregate.yaml — це чернетка Aggregate, названа за графом, як описує Як називається чернетка, що починається з коментарів, які називають прочитані конфігурації, файли середовища, прочитані лише заради їхніх імен, те, що код застосунку не читається, і те, чого чернетка не переносить. Вона містить для кожного графа, з ключем за його ідентифікатором, екземпляр core/ai-agent/langgraph з:

  • graph_entrypoint — шляхом імпорту графа так, як його записує конфігурація;
  • description — описом графа, якщо конфігурація його надає;
  • його з’єднанням checkpointer_db, під’єднаним до сховища даних застосунку;
  • його з’єднанням model, під’єднаним до моделі застосунку.

recursion_limit не записується, тож діє типове значення сутності Component, 25. Конфігурація не називає моделі, тож чернетка містить один екземпляр core/ai-model/openai з ключем model, який викликає кожен граф: модель, яку передають клієнту OpenAI агента. Його values.model записано порожнім під коментарем, що повідомляє, що конфігурація не називає жодної моделі, і імпорт позначає це значення як потрібне.

Бекенд checkpointer — це сховище даних, до якого під’єднано кожен граф застосунку: default або checkpointer без названого бекенду — це екземпляр core/datastore/postgres з ключем postgres. mongo — це FerretDB, що підтримує протокол MongoDB, поверх PostgreSQL з розширенням DocumentDB: екземпляр core/datastore/ferretdb з ключем ferretdb, до якого під’єднано кожен граф, і екземпляр core/datastore/documentdb з ключем documentdb, до якого веде з’єднання backend FerretDB, чий блок inject доставляє те, що публікує DocumentDB, під іменами, які читає FerretDB; один пароль, прочитаний зі змінної FERRETDB_PASSWORD, прикріплюється до DocumentDB, до з’єднання FerretDB з ним і до з’єднання кожного графа з FerretDB. Якщо каталог робочого простору не містить сутності Component з іменем сховища даних PostgreSQL, створюється її чернетка, <target_namespace>/datastore/postgres, що оголошує host і port, які читає з’єднання checkpointer_db агента, і її рішення про це повідомляє; Recipe, що запускає сховище даних і публікує їх, залишається для вас, як каже коментар на її початку. Якщо він не містить сутності Component FerretDB або DocumentDB, checkpointer mongo не під’єднується до жодного сховища даних. Checkpointer custom або бекенд, який імпортер не зіставляє з жодним сховищем даних, нічого не під’єднує, а коментар над кожним графом і рішення checkpointer пояснюють чому; збирання зупиняється з указанням сокета checkpointer_db, доки його не під’єднано. Про сховище пам’яті повідомляє рішення, яке нічого не вибирає.

Пароль сховища даних — це секрет, який чернетка прикріплює за посиланням до власного слота password сховища даних і до з’єднання checkpointer_db кожного графа, так само як і облікові дані, які кожен граф подає моделі у своєму з’єднанні model: їх читають з POSTGRES_PASSWORD (або FERRETDB_PASSWORD) і OPENAI_API_KEY, оскільки конфігурація не називає змінної для жодного з них, як посилання ${…} для кожної цілі, крім helm, а для helm — як ім’я Kubernetes Secret, записане порожнім, щоб імпорт позначив його як потрібне. Для compose сутність Aggregate оголошує кожне з ключем, який читає її сутність Recipe, як описує Секрети для кожної цілі для платформи.

release.yaml поруч із ним — це чернетка Release з тим самим іменем, що називає цей Aggregate. Коментарі над записом першого графа пояснюють, що таке образ кожного графа — власний образ застосунку, його код зі встановленим LangGraph, а не серверний образ, який збирає langgraph build, — які змінні він отримує і який блок inject: замінює яке з їхніх імен. Запис кожного графа записує його infra.image, образ, що запускає застосунок, порожнім під коментарем, що пояснює, що це таке, і імпорт позначає це значення як потрібне; доки його не задано, сутність Recipe Docker Compose запускає власний агент quickstart каталогу, який читає змінні за замовчуванням. З --target compose запис кожного графа також записує infra.published_port, 8000, — порт, який infra.port сутності Component типово називає для застосунку і який її сутність Recipe для Compose публікує на loopback-адресі хоста, 127.0.0.1, — під коментарем, який повідомляє, що сервіс доступний лише з цієї машини, для будь-якого процесу, що на ній працює, і що видалення рядка залишає сервіс внутрішнім; другий граф отримує наступний вільний порт. Сховище даних і модель також мають записи, тож Release розміщує їх разом із графами. Коментар над першим графом застосунку викладає середовище, яке оголошує його конфігурація, як описує Середовище, яке задає конфігурація. Як і кожна чернетка сутності Release, вона записує metadata.environment як development і, без цілі, порожній spec.manifest, який імпорт позначає як потрібний; якщо задано ціль, імпорт створює чернетку сутності Manifest, як описує Що додає ціль.

Застосунок Python, який імпортують тести цього імпортера, що оголошує два графи, checkpointer без названого бекенду, сховище пам’яті та env, записаний як об’єкт, без жодного налаштування перетворюється на чернетку, наведену нижче; імпортований як його каталог, support_desk — названий, як тут, за пакетом, у якому визначено його графи, — з двома графами з різними ідентифікаторами, він отримує назву за цим каталогом:

aggregate.yaml
# 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/v1beta1
kind: Aggregate
metadata:
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: ""
release.yaml
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 читає агентів, яких застосунок, побудований на Agent Development Kit (ADK) від Google, оголошує у своїх файлах Agent Config — root_agent.yaml і конфігураціях, які називають його субагенти, — і створює чернетку сутності Aggregate з одним екземпляром агента ADK зі стандартної бібліотеки, core/ai-agent/google-adk, на кожне дерево агентів, під’єднаним до моделі, яку називає дерево, якщо ADK надсилає її запити до Gemini API, а поруч — сутність 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.yaml, чернетка сутності Aggregate, названа за кореневим агентом, як описує Як називається чернетка, містить на кожне дерево агентів, з ключем за назвою його кореневого агента, екземпляр core/ai-agent/google-adk з:

  • description — описом кореневого агента, якщо його конфігурація його надає;
  • його з’єднанням model, під’єднаним до моделі, яку називає дерево, якщо ADK надсилає її запити до Gemini API.

Коментарі над ним називають інших агентів дерева, які не стають окремими екземплярами; кожного субагента, якого не прочитано, і причину — його будує код застосунку, це конфігурація, яку імпорту не передали, або та, яку відхиляє ADK; інструменти, які називають агенти дерева, — ті, що постачає ADK, і ті, що визначає код застосунку; агентів, чий клас — LoopAgent, ParallelAgent або SequentialAgent — ADK оголошує застарілим на користь Workflow; і, якщо модель дерева під’єднано, моделі, які запитують інші агенти дерева, кожну з родиною, через яку її обслуговує ADK. Про кожне повідомляється в рішенні, що нічого не обирає.

Модель екземпляра визначає перший агент дерева, починаючи з кореня, який називає модель або код, що її будує. Названа ним модель, запити якої ADK надсилає до Gemini API, — назва моделі, яку ADK обслуговує через свій клас Gemini, як-от gemini-2.5-flash, крім назви ресурсу Vertex AI, або назва, яку він обслуговує через свій клас Gemma, — є екземпляром core/ai-model/gemini, що обслуговує цю модель і має її за ключ, а дерева, що називають одну модель, спільно використовують один екземпляр. Якщо каталог робочого простору не містить core/ai-model/gemini, створюється чернетка <target_namespace>/ai-model/gemini з міткою model.aggrega.ai/api: gemini, яку вибирає сокет model агента, і її рішення про це каже; сутність Recipe, що публікує її кінцеву точку та модель, залишено вам, як каже коментар на її початку. Модель, яку ADK обслуговує в будь-який інший спосіб, — рядок моделі LiteLLM, як-от openai/gpt-4o, назва ресурсу Vertex AI або назва на кшталт claude-sonnet-4-5 чи gpt-4o, яку ADK обслуговує через Anthropic або OpenAI, — ні до чого не під’єднується: сокет model агента приймає модель Gemini, а агент не читає назви моделі зі свого середовища, тож ви під’єднуєте туди модель Gemini і називаєте цю модель у конфігурації агента. Коментар над екземпляром і рішення кореневого агента називають модель і родину, через яку її обслуговує ADK. Модель, яку будує код застосунку, або дерево, що не називає жодної моделі, — тоді ADK використовує свою модель за замовчуванням, — теж ні до чого не під’єднується, і коментар над екземпляром пояснює чому. Щоразу, коли модель ні до чого не під’єднано, збірка зупиняється, називаючи сокет model, доки його не під’єднано. Серед моделей, які запитують інші агенти дерева, модель, запити якої ADK надсилає до Gemini API, не потребує окремого з’єднання: клієнт Gemini від ADK надсилає її запити з ключем, який доставляє з’єднання екземпляра. Чи звертається застосунок до Gemini через Gemini API, чи через 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 поруч — це чернетка сутності Release з тією самою назвою, що називає цю сутність Aggregate. Запис кожного екземпляра записує його infra.image — образ, що запускає застосунок, побудований на ADK, який містить його конфігурації, — порожнім, під коментарем, що пояснює, що це, а імпорт позначає його як ще не надане значення. З --target compose запис також записує infra.published_port, 8000, порт, який прослуховує застосунок і який його сутність Recipe для Compose публікує на адресі зворотної петлі хоста, 127.0.0.1, під коментарем, що повідомляє, що він доступний лише з цієї машини, будь-якому процесу, запущеному на ній, і що видалення рядка залишає сервіс внутрішнім; друге дерево отримує наступний вільний порт. Якщо його модель під’єднано, запис приєднує облікові дані, які екземпляр пред’являє цій моделі, під credential у його з’єднанні model, за посиланням і ніколи як значення: жодна конфігурація не називає для них змінної, тож вони зчитуються з GOOGLE_API_KEY, змінної, з якої клієнтські бібліотеки Gemini API від Google зчитують свій ключ, як посилання ${…} на кожній цілі, крім helm, а на helm — як ім’я Kubernetes Secret, записане порожнім, щоб імпорт позначив його як ще не надане; на compose з’єднання model оголошує їх із цим ключем. Під’єднана модель також має запис, який не містить жодної інфраструктури, тож сутність Release розміщує її разом з екземпляром. Значення, які конфігурації дерева передають своїм інструментам і запитам до моделі, записуються в коментарі над записом, як описано в розділі Значення облікових даних у конфігурації. Як і кожна чернетка сутності Release, вона записує metadata.environment як development і, без цілі, порожнє spec.manifest, яке імпорт позначає як ще не надане; якщо задано ціль, імпорт створює чернетку сутності Manifest, як описано в розділі Що додає ціль.

Застосунок, який імпортують тести цього імпортера, — кореневий агент, що називає конфігурації двох субагентів і одного, побудованого кодом, імпортований як його каталог із двома конфігураціями, названими під with.sources, — без жодного параметра стає такою чернеткою під назвою свого кореневого агента, tutor_root:

aggregate.yaml
# 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/v1beta1
kind: Aggregate
metadata:
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 читаються так, як записано.

release.yaml
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, які клієнт Gemini від ADK надсилає до Gemini API, а модель — як Service, що звертається до адреси Gemini API.

Облікові дані, які містить конфігурація

Конфігурація може передати ключ інструменту в його args або своїм запитам до моделі в http_options свого generate_content_config — їхнім заголовкам, їхній адресі, аргументам їхнього клієнта. Кожен член args інструмента і цих параметрів HTTP записується в коментарі над записом екземпляра в сутності Release так, як його записує конфігурація, і кожен, що є текстом, об’єктом або списком, може містити облікові дані, жоден з яких ADK не позначає: типово кожен переноситься як записано і називається в попередженні credential-carried за своїм агентом і своїм полем, як-от tools.tutor_tools.make_snippet_runner.args.api_key, і ніколи за своїм значенням. Якщо параметр empty_credentials має значення all, кожен записується без значення і повідомляється з credential-emptied; зі значенням marked кожен переноситься, оскільки ADK не позначає жодного. Число або булеве значення не містить ключа і записується так, як його записує конфігурація. ADK не розгортає жодних посилань на змінні в конфігурації, тож кожне значення читається як записано; файл середовища, який зазвичай містить ключ, що його читає клієнт Gemini в ADK, ніколи не читається, хай що каже параметр.

Параметри, які він читає

Імпортер Google ADK читає target_namespace, empty_credentials і render_mode, як їх описує розділ Параметри, і жодних інших параметрів.

Імпортер Agent Framework

importer/agent-framework читає декларативного агента Microsoft Agent Framework — YAML-документ виду Prompt, з якого застосунок, побудований на Agent Framework, завантажує агента, — і створює чернетку Aggregate, що містить один екземпляр агента Agent Framework зі стандартної бібліотеки, core/ai-agent/agent-framework, під’єднаний до моделі OpenAI, яку він називає, а поруч — Release. Він читає декларативних агентів і ніколи не читає код застосунку. Agent Framework публікує свої пакети декларативних агентів як попередні випуски.

Що він читає

Декларативний агент оголошує:

  • name, displayName і description, свої instructions і схеми своїх вхідних і вихідних даних;
  • model — id моделі, provider, що її обслуговує, API, до якого її клієнт надсилає запити (apiType), options її запитів і її connection: з’єднання key, що надає ключ, записаний під key або apiKey, до endpoint; з’єднання remote, що звертається до endpoint; з’єднання reference, що називає з’єднання, яке розв’язує застосунок; або з’єднання anonymous, що нічого не надає;
  • tools — кожен певного kind: function, код якої прив’язує застосунок, інструмент web_search, file_search або code_interpreter, який запускає постачальник моделі, або сервер mcp, доступний за його url, з approvalMode, який отримують його виклики, allowedTools сервера, які агент може викликати, і власним connection.

Член, записаний як =Env.NAME, Agent Framework читає зі змінної середовища NAME лише там, де застосунок завантажує декларативного агента з AgentFactory(safe_mode=False), власним параметром безпеки Agent Framework, і наявне середовище виконання .NET, а інакше його сприймають як текст виразу в записаному вигляді; будь-який інший член, що починається з =, — це вираз, який обчислює застосунок. Імпортер не читає жодного з них: посилання він називає за його змінною, а вираз — як вираз.

Файл, імпортований окремо, читається як один декларативний агент, хоч би як він називався, а кожен файл, який передає 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.yaml, чернетка Aggregate, названа за агентом, як описує Як називається чернетка, містить для кожного декларативного агента, з ключем за його назвою, екземпляр core/ai-agent/agent-framework з:

  • display_name і description — displayName і description агента, якщо він їх зазначає;
  • його з’єднанням model, під’єднаним до моделі, яку він називає, якщо цю модель під’єднано.

Його інструкції, схеми його вхідних і вихідних даних, його шаблон, його метадані та параметри його запитів до моделі застосунок читає з декларативного агента, і їх названо в коментарі над екземпляром. Функціональний інструмент, інструмент, який запускає постачальник моделі, та інструмент будь-якого іншого виду теж названо в коментарі, і про них повідомляється в рішенні, яке нічого не обирає.

Модель, чий provider — OpenAI і яка називає id, є екземпляром core/ai-model/openai, що обслуговує цей id і має його як ключ: сокет model агента приймає модель, що обслуговує OpenAI API, а середовище виконання передає адресу, назву й ключ цієї моделі у змінних, які читають клієнти OpenAI в Agent Framework. Агенти, що називають одну модель за однією адресою, мають спільний екземпляр. Якщо каталог робочого простору не містить core/ai-model/openai, створюється чернетка <target_namespace>/ai-model/openai з міткою model.aggrega.ai/api: openai, яку вибирає сокет model агента, і її рішення про це повідомляє; сутність Recipe, що публікує її кінцеву точку та модель, залишено вам, як каже коментар на її початку. id, записаний як посилання, залишає вам values.model моделі, а коментар над моделлю називає змінну; збірка зупиняється, називаючи її, доки її не задано. З’єднання anonymous записується як unauthenticated: true з’єднання. Модель будь-якого іншого постачальника — AzureOpenAI, Anthropic, — модель, що називає свого постачальника посиланням або не називає жодного (тоді Agent Framework використовує постачальника за замовчуванням, якого задає застосунок), і модель без id ні до чого не під’єднуються, а коментар над екземпляром пояснює чому; збірка зупиняється, називаючи сокет model, доки до нього щось не під’єднано.

Інструмент виду mcp не оформлюється в чернетці ні як сутність Component, ні як з’єднання: Agent Framework надсилає сервер постачальнику моделі як розміщений інструмент, і до нього за його url звертається постачальник, а не застосунок, тому ця адреса має бути досяжною з боку постачальника, і ніщо з того, що розгортає чернетка, до нього не звертається. Коментар над екземпляром агента називає сервер, повідомляє про це і називає опис, approvalMode та allowedTools, які декларативний агент зазначає для нього; його url записано повністю в коментарі над записом агента в сутності Release, а його рішення нічого не обирає.

release.yaml, поруч із ним, — чернетка сутності Release з тією самою назвою, що називає цю сутність Aggregate. Запис агента записує його infra.image — образ, що запускає застосунок, побудований на Agent Framework, який містить його декларативного агента, — порожнім, під коментарем, що пояснює, що це, а імпорт позначає його як ще не надане значення. З --target compose запис також записує infra.published_port, 8000, — порт, який infra.port сутності Component типово називає для застосунку і який її сутність Recipe для Compose публікує на loopback-адресі хоста, 127.0.0.1, — під коментарем, який повідомляє, що сервіс доступний лише з цієї машини, для будь-якого процесу, що на ній працює, і що видалення рядка залишає сервіс внутрішнім. Якщо його модель під’єднано, запис приєднує облікові дані, які агент надає цій моделі, під credential у його з’єднанні model, за посиланням і ніколи як значення: вони зчитуються зі змінної, яку декларативний агент називає для свого ключа, записаної як =Env.NAME, а інакше з OPENAI_API_KEY, змінної, з якої клієнтські бібліотеки OpenAI зчитують свій ключ; як посилання ${…} на кожній цілі, крім helm, а на helm — як ім’я Kubernetes Secret, записане порожнім, щоб імпорт позначив його як ще не надане; на compose з’єднання model оголошує їх із цим ключем. Значення, які декларативний агент зазначає для своєї моделі та своїх MCP-серверів, — ключі та url кожного сервера — записано в коментарі над записом агента, як описано в розділі Значення облікових даних у декларативному агенті. Кожна під’єднана модель має запис, тож сутність Release розміщує її разом з агентом. Кінцеву точку, яку зазначає її з’єднання, записано як infra.endpoint моделі, а записану як посилання названо поруч із її записом, і доки її не задано, використовується власна адреса сутності Component; з’єднання, яке не зазначає кінцевої точки, залишає запис без жодної інфраструктури, і чинною лишається власна адреса сутності Component. Як і кожна чернетка сутності Release, вона записує metadata.environment як development і, без цілі, порожнє spec.manifest, яке імпорт позначає як ще не надане; якщо задано ціль, імпорт створює чернетку сутності Manifest, як описано в розділі Що додає ціль.

Декларативний агент, якого імпортують тести цього імпортера, — постачальника OpenAI з з’єднанням за ключем, MCP-сервером, що надає власний ключ, функціональним інструментом і вебпошуком, імпортований як окремий файл, — без жодних налаштувань створюється під своїм name, LearnAgent, як:

aggregate.yaml
# 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/v1beta1
kind: Aggregate
metadata:
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 він читався як написано.

release.yaml
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, — записаний під key або apiKey, на моделі чи на MCP-сервері, — це єдиний член, який Agent Framework позначає як облікові дані: це єдине значення, яке його завантажувач приховує з того, що записує в журнал. Кожен ключ, який декларативний агент записує як літерал, записується в коментарі над записом агента в сутності Release так, як його записує декларативний агент, і за замовчуванням переноситься як записано та називається в попередженні credential-carried за його агентом і його полем, наприклад model.connection.key, ніколи за його значенням. url MCP-сервера, записаний повністю в тому самому коментарі й названий за своїм полем — tools.microsoft_learn.url of node LearnAgent is carried as written, — є членом конфігурації MCP-сервера, а кінцева точка під’єднаної моделі — це вхідні дані, які Agent Framework позначає як не облікові. Коли параметр empty_credentials має значення marked, ключі та url MCP-серверів записуються без значення — коментар називає кожен лише за його полем, — і повідомляються з 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 читає target_namespace, empty_credentials і render_mode, як їх описує розділ Параметри, і жодного іншого параметра.

Що додає ціль

Імпорт, якому задано ціль — --target у aggrega import або target в інструменті імпорту асистента та в методі aggrega/import сеансу, що називає можливість провайдера, як-от compose чи helm, — передає цю ціль імпортеру, тож імпортер створює чернетки для неї: кожен секрет у формі, яку зчитує ця ціль, і рядки, потрібні лише цій цілі, записано активними, тоді як рядки, потрібні лише іншій цілі, пропущено. На compose ці рядки містять infra.published_port усюди, де імпортер публікує сервіс на адресі зворотної петлі хоста, як зазначено в розділі кожного імпортера; порт, який вибирає імпортер, ніколи не отримує номера, який займає інший порт сутності Release. Потім імпорт створює чернетку Manifest поряд із тим, що створив імпортер, хоч би який імпортер працював: manifest.yaml, поряд із чернеткою Release, з тими самими назвою та версією, що й у неї, — або, якщо імпортер не створив чернетки Release, поряд із чернеткою Aggregate, з тими самими назвою та версією, що й у неї.

Для кожного типу компонента й кожного типу feature, потрібних чернеткам, — у компонентах чернетки Aggregate, їхніх з’єднаннях і її підсистемах, у каталожних сутностях Aggregates, які вона компонує, як-от core/dify, та в приєднаннях чернетки Release — Manifest зіставляє тип із сутністю Recipe або, для типу feature, з feature recipe цієї можливості, яку каталог робочого простору пропонує для нього: з тією єдиною, що є, причому кілька версій однієї рахуються як одна; або, якщо є кілька з різними назвами, з тією, що названа на честь самого типу, як-от helm/postgres для core/datastore/postgres. Тип, для якого немає жодної, або є кілька, але жодна не названа так, лишається незіставленим, попередження називає його та причину, а збірка чернеток зупиняється, називаючи кожен його екземпляр або приєднання, доки ви його не зіставите.

Якщо лише імпортер знає, яка з кількох сутностей Recipes застосовується, він сам створює чернетку Manifest — імпортер MCP зіставляє кожен сервер за його ключем із реалізацією того, як працює сервер, а імпортер, що приєднує секрет за іменем, зіставляє core/referenced-secret з helm/k8s-existing-secret, — а імпорт її доповнює: кожне зіставлення, записане імпортером, яке каталог пропонує для цього типу й цієї можливості, зберігається, будь-яке інше відкидається з попередженням, а типи, які він залишає, зіставляються, як описано вище.

spec.manifest чернетки Release, записане порожнім без цілі, встановлюється на ім’я сутності Manifest, коментар над ним видаляється, і більше нічого в Release не змінюється. aggrega import описує це повністю.

Налаштування

Імпортер отримує налаштування запису plugins.importer, який його підключає, у with.settings, як описано в розділі Який імпортер перетворює джерело на чернетки. Якщо запису або налаштувань немає, кожне налаштування набуває значення за замовчуванням.

plugins:
importer:
- uri: importer/langflow:<version>
with:
settings:
target_namespace: payments
reuse_mode: hints-only
НалаштуванняЗа замовчуваннямЩо вона робить
target_namespaceimportedПростір імен, у якому отримують назви створені чернетки сутностей: <target_namespace>/<category>/<name> для сутності Component і <target_namespace>/<name> для сутностей Aggregate і Release, де <name> — власна назва джерела, а за її відсутності — назва його каталогу або назва його файлу без розширення, а за їх відсутності — flow, записана в нижньому регістрі, причому кожна послідовність символів, відмінних від літер і цифр ASCII, замінюється одним дефісом, як описано в розділі Як називається чернетка.
reuse_modeauto-apply-above-thresholdauto-apply-above-threshold посилається на найкраще відповідну сутність Component з каталогу для вузла, якому чернетка надає власну сутність Component і збіг якого належить до високого рівня й має оцінку, не нижчу за reuse_threshold, а всі інші створює в чернетці. hints-only створює в чернетці кожен такий вузол і не посилається на жодну сутність Component з каталогу, записуючи сильний збіг як підказку. Будь-яке інше значення читається як hints-only.
reuse_threshold0.85Оцінка, починаючи з якої auto-apply-above-threshold посилається на сутність Component. Читається лише в цьому режимі; 0 читається як значення за замовчуванням.
emit_hintstrueЧи починається файл створеної в чернетці сутності Component з коментаря, що називає схожу на неї сутність Component з каталогу, для збігу високого або середнього рівня. Чернетка сутності Aggregate містить той самий коментар над записом цього вузла, а над записом із посиланням — коментар, що називає наступного найкращого кандидата, на якого його можна замінити, або повідомляє, що жоден не отримав оцінки вище нуля. false пропускає коментарі.
render_modehumanhuman записує описані вище чернетки. llm не записує чернеток, а натомість записує весь запис рішень — кожен вузол, зважених кандидатів і зроблений вибір — як один документ, import-decisions.json, для читання іншим інструментом. Будь-яке інше значення читається як human.
mapping_overridesнемаєВідповідності, накладені поверх власної таблиці імпортера, з ключами за форматом, а потім за типом вузла — для імпортера Compose за репозиторієм образу. Кожен запис називає component, якому відповідає вузол цього типу, і, за бажанням, його category, traits — мітки та їхні значення, — які має відповідна сутність Component, і слово vendor, яке містить її назва. Запис для типу вузла, який таблиця вже зіставляє, заступає рядок таблиці. Читаються лише записи для формату, що імпортується.
layoutplatformplatform створює в чернетці платформу, яка виконує потік і несе його, причому кожна його частина є власною сутністю Component, з’єднаною з платформою, як описано в розділі Платформа, що несе потік. nodes створює в чернетці кожен вузол як власну сутність Component, як описано в розділі Вузол за вузлом. Для імпортера Dify platform створює в чернетці інсталяцію Dify, що несе застосунок, як описано в розділі Чим стає застосунок. Будь-яке інше значення створює чернетку як platform, і імпорт попереджає з unknown-layout.
empty_credentialsnoneЯкі облікові значення записано порожніми в потоці, який несе платформа, як їх перелічено в розділі Облікові значення, які містить потік, у сутності Release, яку створює імпортер MCP, як їх перелічено в розділі Облікові значення, які містить сервер, у сутності Release, яку створює імпортер Compose, як їх перелічено в розділі Облікові значення, які містить сервіс, у застосунку, який несе імпортер Dify, як їх перелічено в розділі Облікові значення, які містить застосунок, у сутності Release, яку створює імпортер CrewAI, як їх перелічено в розділі Облікові значення, які містить оголошення, у сутності Release, яку створює імпортер LangGraph, як їх перелічено в розділі Середовище, яке задає конфігурація, у сутності Release, яку створює імпортер Google ADK, як їх перелічено в розділі Облікові значення, які містить конфігурація, і в сутності Release, яку створює імпортер Agent Framework, як їх перелічено в розділі Облікові значення, які містить декларативний агент. none не записує порожнім жодного: кожне переноситься як записане й називається в попередженні credential-carried. marked записує порожнім те, що формат позначає як облікові дані, і кожен елемент конфігурації сервера MCP. all записує порожніми також вхідні дані, які формат не позначає як облікові, але які можуть їх містити, — заголовки запитів, параметри запиту, запит, записаний як командний рядок, вхідні дані, названі за ключем. Те, що чернетка записує, щоб вузол досяг свого з’єднання, записується незалежно від цього налаштування. Будь-яке інше значення зупиняє імпорт, який нічого не створює, з unknown-empty-credentials. Чернетка, створена вузол за вузлом, не читає жодного значення, а тому не читає й цього налаштування.
attach_egress_allowlistfalsetrue підключає сутність Feature core/egress-allowlist зі стандартної бібліотеки до кожного екземпляра платформи, який записує чернетка, як egress-allowlist, не задаючи жодного з її infra, як описано в розділі Що чернетка залишає для Release. false нічого не підключає. Чернетка, яка не записує платформи, за layout: nodes, і чернетка імпортера Dify, чий запис для інсталяції Dify не приймає сутності Feature, нічого не підключають незалежно від цього налаштування, і якщо воно 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-failedhaltДжерело не розбирається: його парсер відхиляє його, і повідомлення містить причину від парсера.
no-nodeswarnДжерело не містить жодного вузла, який розпізнає імпортер: для імпортера MCP — жодного сервера, для імпортера Compose — жодного сервісу й жодної моделі, для імпортера CrewAI — команда, що не оголошує жодного агента, для імпортера LangGraph — конфігурація, що не оголошує жодного графа, для імпортера Google ADK — коренева конфігурація, що не оголошує жодного агента, або кожен файл, який with.sources передає імпорту, не містить кореневої конфігурації, а для імпортера Agent Framework — джерело, що не оголошує жодного prompt-агента.
unknown-layoutwarnlayout не є ні platform, ні nodes; потік створюється як platform.
unknown-empty-credentialshaltempty_credentials містить значення, відмінне від none, marked чи all, назване разом із параметром; імпорт нічого не створює.
platform-not-in-catalogwarnКаталог робочого простору не містить жодної сутності Component з іменем платформи, тож до неї не під’єднано жодної частини; для імпортера Dify — немає core/ai-agent/dify, і core/dify все одно компонується.
part-not-placedwarnЧастину потоку не під’єднано до жодного сокета платформи, із поясненням причини; вона залишається в потоці.
socket-selector-unreadablewarnСелектор, який оголошує сокет платформи, не читається, тож до нього не під’єднано жодної частини; по одному разу для кожного сокета.
credential-carriedwarnОблікове значення перенесено як записане в потоці, який містить чернетка, або в сутності Release, яку створює імпортер MCP, Compose, CrewAI, LangGraph, Google ADK чи Agent Framework, назване за його вузлом — або сервером, сервісом, агентом чи конфігурацією — і полем, ніколи не за значенням, разом зі значенням empty_credentials, яке записує його порожнім.
credential-emptiedwarnОблікове значення записано порожнім у потоці, який містить чернетка, або в сутності Release, яку створює імпортер MCP, Compose, CrewAI, LangGraph, Google ADK чи Agent Framework, де цього вимагає empty_credentials, назване за його вузлом — або сервером, сервісом, агентом чи конфігурацією — і полем.
carriage-returns-rewrittenwarnСимволи повернення каретки в потоці записано як символи переведення рядка, із зазначенням кількості.
definition-respelledwarnЗначення потоку записуються в написанні, у якому їх зчитують власні інструменти платформи, з тими самими значеннями, із зазначенням яких саме й чому: дескриптори ребер потоку Langflow, записані так, як їх записує редактор Langflow. Значення, яке чернетка записує, щоб потік досяг частини, або таке, що може містити облікові дані, ніколи не переписується — воно лишається значенням з’єднання або значенням empty_credentials, — а попередження підраховує кожне непереписане значення.
definition-not-carriedwarnПотік не перенесено в values.flow_definition, або застосунок імпортера Dify — у parameters.app_definition, із поясненням причини.
part-reads-connectionwarnЯк потік досягає під’єднаної частини через її з’єднання або як з’єднання досягає вузла, який чернетка не під’єднує до жодного сокета, у тому вигляді, як воно записане.
part-address-in-flowwarnПотік досягає під’єднаної частини не через її з’єднання, із поясненням як.
model-not-namedwarnvalues.model частини, на яку посилаються, залишено для автора, із поясненням причини.
feature-attachedinfoattach_egress_allowlist під’єднав core/egress-allowlist до створеної платформи, із зазначенням, що з нього задає Release; по одному разу для кожного екземпляра платформи.
feature-not-attachedwarnattach_egress_allowlist має значення true, а чернетка не записує жодної платформи або компонує інсталяцію Dify, запис якої не приймає сутності Feature, тож нічого не під’єднано.
part-configured-in-platformwarnВузол застосунку Dify називає те, що Dify налаштовує сам — модель і її постачальника, інструмент, базу знань, стратегію агента, плагін, — тож чернетка не під’єднує для нього жодної частини.
dsl-version-newerwarnЗастосунок Dify записано у версії DSL, новішій за ту, яку записує версія Dify, що її core/ai-agent/dify запускає за замовчуванням.

Імпорт, якому задано ціль, після діагностики імпортера повідомляє, що виявило створення сутності Manifest: warn із назвою кожного типу компонента або feature, який Manifest залишає незіставленим, і причиною, та info, коли створена сутність Release уже називає Manifest або жодна створена сутність Release на нього не посилається. Ці повідомлення належать самому імпорту, а не імпортеру, і не мають коду; їх описано в розділі Що додає ціль. Потім кожен імпорт повідомляє, також як власні, warn для кожного значення, якого чернетки ще не мають, із назвою чорнового файлу, шляхом ключа та його описом, а в режимі --offline, коли він створив чернетку сутності Release і нічого не бракує, — info з назвою aggrega pull, який слід виконати далі, як описано в розділі Файл відповідей імпорту.

Публікуються з кожним випуском компілятора

Кожен випуск компілятора збирає десять імпортерів із позначених тегом джерел і генерує їхні сутності Plugin із самих імпортерів, тож можливість, сигнатури розпізнавання, функції хоста й опис сутності — це те, що повідомляє її імпортер. Випуск підписує й публікує всі десять, importer/langflow, importer/flowise, importer/n8n, importer/mcp, importer/compose, importer/dify, importer/crewai, importer/langgraph, importer/google-adk і importer/agent-framework, у версії випуску, поряд з іншими основними плагінами, і записує їхні сутності разом із сутностями інших основних плагінів для стандартного каталогу.