Імпорт
aggrega import читає проєкт, написаний в іншому форматі, — потік, експортований з Langflow, конфігурацію клієнта MCP, файл Compose та інші формати, перелічені нижче, — і записує з нього файли Aggrega: сутність Aggregate, сутність Release і, для цілі, яку вказує --target, сутність Manifest. Разом вони утворюють робочий простір, який проходить валідацію і збирається в тому вигляді, в якому записаний, щойно надано відповіді на кілька значень, яких не може містити жодне джерело: імпорт запитує кожне з них один раз і зберігає відповіді у файлі відповідей. Він нічого не розгортає й не звертається до жодного кластера чи хмарного облікового запису. Чернетки — це звичайні файли у вашому робочому просторі, і що з ними робити далі, вирішуєте ви.
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importчернетки файлів Aggrega
щоб ви їх переглянули й відредагували
На вході — ваш наявний проєкт, на виході — чернетки файлів Aggrega. Нічого не розгортається; спершу ви переглядаєте чернетки.
Що він вам дає
- Ваш проєкт потрапляє в Aggrega без ручного переписування. Чернетки сутностей Aggregate, Release і Manifest — це файли того самого типу, які ви написали б самі. Вони збираються в тому вигляді, в якому записані, для цілі, яку вказує імпорт, а кожна політика управління, яку приєднує ваш робочий простір, оцінює цю збірку так само, як будь-яку іншу.
- Те, що зазначено в джерелі, переноситься. Вузол або сервіс, для якого каталог містить сильний збіг, посилається на цю сутність Component каталогу зі значеннями, які надає йому джерело, як-от модель, яку вказує потік. Платформа, на якій працює джерело, потрапляє в чернетку з образом, який запускають для неї сутності Recipes каталогу. Секрет записується в чернетку як посилання на те, звідки він походить, і ніколи як його значення.
- Вас запитують лише про те, чого не може містити жодне джерело, і лише один раз. Відповіді зберігаються у файлі відповідей поруч із джерелом, тож наступний імпорт того самого джерела нічого не запитує.
- Чернетки належать вам. Це звичайний YAML у вашому робочому просторі, і після них не лишається нічого, від чого залежала б збірка. Редагуйте їх, перейменовуйте, комітьте.
- Чернетка може стежити за своїм джерелом.
aggrega import --syncоновлює чернетки попереднього імпорту відповідно до зміненого джерела, змінюючи лише те, що записав імпорт. Якщо джерело змінило частину, яку ви редагували, він зупиняється й називає цю частину, замість того щоб перезаписати ваші зміни.
Чого він не робить
Імпорт створює чернетку того, що зазначено в джерелі, і того, що визначає ваш каталог, а про решту запитує. Кожна чернетка в коментарі поруч зі значенням повідомляє, звідки походить записане нею значення.
- Він не вгадує того, чого ваше джерело не може зазначити. Жодне джерело не вказує середовище, у яке розгортається сутність Release, тому чернетка сутності Release вказує
developmentз коментарем про те, що це значення за замовчуванням, яке слід змінити. Значення, якого вимагає каталог і якого не містить жодне джерело, — електронна пошта облікового запису власника, образ застосунку, зібраного з вашого власного коду, ім’я Secret у Kubernetes, — записується в чернетку порожнім і запитується, як описує розділ Як виконується імпорт нижче. - Він не читає код. Власна програма потоку чи проєкту не читається: програма crew CrewAI, код графа застосунку LangGraph, вихідний код компонента Langflow, який лише переноситься всередині потоку.
- Він не судить, що означає значення. Кожен вузол чи сервіс порівнюється із сутностями Components каталогу вашого робочого простору — їхніми іменами, категоріями, мітками та іменами значень, які вони оголошують. На збіг із високого рівня чернетка посилається; слабший записується як коментар, що вказує сутність Component та її оцінку, і вибір за вами.
- Він не змінює версію, яку запускає платформа, щоб слідувати за джерелом. Образ платформи записується в чернетку з версією, яку, як відомо, запускають для неї сутності Recipes каталогу, а там, де джерело вказує іншу версію, її вказує коментар поруч з образом.
- Він не виносить облікові дані з вашого джерела замість вас. Значення, яке може містити ключ, — значення середовища, заголовок, командний рядок сервера MCP — за замовчуванням переноситься в чернетку як є, і імпорт називає кожне з них у попередженні
credential-carried, ніколи не за його значенням. Параметр імпортераempty_credentialsнатомість записує їх порожніми (Налаштування). Прочитайте попередження, перш ніж ділитися чернеткою. - Він нічого не розгортає й не запускає. Він читає джерело та ваш каталог і записує файли. Збирання чернеток і запуск того, що записала збірка, — це окремі кроки, які виконуєте ви.
Як виконується імпорт
Імпорт можна виконати командами нижче або доручити його вашому ШІ-асистенту.
-
Почніть із робочого простору. Імпорт записує свої чернетки всередині кореня робочого простору, у якому він запущений, — теки, що містить
.aggrega-config.yamlіз ключемworkspace, — або всередині директорії, яку задає--output-dir. Він ніколи не перезаписує наявну там сутність Aggregate. -
Каталог, з яким порівнює імпорт. Імпорт оцінює ваше джерело щодо сутностей Components каталогу робочого простору — і нічого іншого. Якщо робочий простір не вказує власної теки каталогу, це каталог стандартної бібліотеки, який читається з типового реєстру робочого простору: кожна публікація каталогу публікує підписаний знімок усього каталогу, а перший імпорт отримує цей знімок, перевіряє його підпис, зберігає в кеші вмісту робочого простору й називає за його дайджестом у записі, який він записує поруч із чернетками, тож пізніший імпорт тих самих чернеток читає той самий каталог, не звертаючись знову до реєстру. Щодо нього сервіс PostgreSQL зіставляється з
core/datastore/postgres, а--targetстворює чернетку сутності Manifest на основі сутностей Recipes каталогу. Без каталогу імпорту нема з чим зіставляти, а--targetвідхиляється, оскільки жоден Recipe не прив’язаний до цілі.Робочий простір, який вказує власні теки каталогу, натомість імпортує щодо них і не отримує жодного знімка: директорій, які перелічує
workspace.catalog_dirs, текиcatalogу корені робочого простору або директорій, які називаєAGGREGA_CATALOG_DIRS. Власні файли каталогу стандартної бібліотеки — це текаaggrega-catalogрепозиторіюaggrega-hub, https://github.com/aggrega-ai/aggrega-hub, для робочого простору, якому вони потрібні як тека.--upgradeотримує найновіший знімок, який публікує реєстр, і відтоді імпортує щодо нього; з--offlineімпорт, якому довелося б отримати знімок, зупиняється й називає, що слід запустити. -
Запустіть імпорт. Назвіть файл або директорію:
Terminal window aggrega import compose.yaml --target composeФормат розпізнається за іменем і вмістом файлу; там, де це не так, його задає
--format.--targetзадає можливість провайдера, як-отcomposeчиhelm, і створює чернетку сутності Manifest, що зіставляє кожен тип компонента й кожен тип функції, потрібний чернеткам, з тією сутністю Recipe цієї можливості, яку ваш каталог пропонує для нього: з єдиною наявною або, серед кількох, з тією, що названа за типом. Чернетка сутності Release називає цю сутність Manifest, а вміст чернеток залежить від цілі: дляcomposeсекрет — це посилання на змінну, яку Docker Compose заповнює з вашої оболонки, дляhelm— ім’я Kubernetes Secret. У стандартний потік помилок імпорт виводить назву прочитаного формату, кожне попередження та по одному рядку на кожен зіставлений вузол; у стандартний вивід — перелік записаних файлів. -
Дайте відповідь на те, чого не містить жодне джерело. Значення, якого вимагає каталог і якого не може містити жодне джерело, — електронна адреса облікового запису власника, образ застосунку, зібраного з вашого власного коду, ім’я Kubernetes Secret — потребує відповіді лише раз. Імпорт читає відповіді з
import-answers.yamlпоруч із джерелом або з файлу, який задає--answers; у терміналі він запитує кожне ще відсутнє значення, по одному запитанню за раз, і записує ваші відповіді в цей файл. На секрет відповідають тим, звідки він береться, — змінною або ім’ям Secret, — і ніколи його значенням. Там, де нічого не можна запитати, — у безперервній інтеграції, через конвеєр, з асистента чи редактора — імпорт записує файл відповідей із ключем кожного відсутнього значення й порожньою відповіддю, перелічує їх і завершується зі статусом 1; заповніть їх і запустіть імпорт знову. Один файл відповідей слугує кожній цілі: відповідь, яка не потрібна чернеткам для певної цілі, зберігається у файлі й лишається невикористаною. Файл відповідей імпорту повністю описує цей файл. -
Імпорт завантажує те, що потрібно збірці. Щойно нічого не бракує, імпорт завантажує залежності чернетки сутності Release, як це робить
aggrega pull, і записує поручrelease.lock. З--offlineвін нічого не завантажує й називає командуaggrega pull, яку слід запустити. -
Перевірте та зберіть. У теці з чернетками:
Terminal window aggrega validate --release release.yamlaggrega build --release release.yamlКоли обидві команди проходять, збірка вже записала файли цілі в
dist/. Відмова називає, що змінити й де, у документі, який ви змінюєте. -
Запустіть те, що записала збірка. Збірка для Docker Compose записує
dist/compose/docker-compose.yaml, і цей файл не задає назви проєкту Compose, тож задайте її за допомогою-p:Terminal window docker compose -p <name> -f dist/compose/docker-compose.yaml up -dБез
-pDocker Compose називає проєкт за текою, що містить файл,compose, тож два робочі простори, запущені таким способом, спільно використовують один проєкт. Сервіси розміщуються в одній мережі, яку Docker Compose називає за проєктом,<name>_compose. До сервісу, для якого збірка не публікує жодного порту, звертаються зсередини цієї мережі за допомогоюdocker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …або з контейнера, який ви запускаєте в цій мережі, за допомогоюdocker run --network <name>_compose …. Розділи «Запуск» і «Перевірка» покрокового посібника показують команди для його власної збірки.Запуск відповідає без ключа OpenAI, щойно його модель
core/ai-model/openaiспрямовано на невелику модель, яку обслуговує Ollama в тому самому проєкті, за трьох змін у створених чернетках файлів, збірки з--auto-pull, яка завантажує те, що потрібно доданому компоненту, і однієї команди після запуску стеку:- у сутності Aggregate — ще один компонент, ні з чим не з’єднаний:
local-modelтипуcore/ai-model/ollamaзmodel: qwen2.5:0.5bу йогоvalues; - у сутності Manifest — його Recipe для Compose:
core/ai-model/ollama: compose/ollama; - у сутності Release —
local-model: {}, а також ключendpointмоделі OpenAI в їїinfra, встановлений на OpenAI-сумісну адресу цього сервера,http://local-model:11434/v1; - після запуску стека завантажену модель копіюють під назвою моделі, яку вказує модель OpenAI збірки,
<model>, наприкладgpt-4o-miniабоgpt-4.1:docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.
Після цього
OPENAI_API_KEYможе містити будь-яке ваше непорожнє значення: локальний сервер жодного не перевіряє. Робочий процес n8n читає адресу й ключ моделі з облікових даних, які вибирає його вузол моделі, а не з адреси, яку надаєendpoint, тому передайте цим обліковим даним також адресу сервера — якurlпоруч зapiKeyу їхніхdata. Сервер Ollama, який типово запускаєcore/ai-model/ollama, обслуговує не лише Chat Completions, а й Responses API від OpenAI, тому декларативний агент Agent Framework, який вказуєapiType: Responses, звертається до нього в тому вигляді, у якому його написано.Збірка для Kubernetes, ціль
helm, записує звичайні маніфести, а не чарт, як описує провайдер helm: уdist/helm/або, для компонентів, які сутність Release розміщує в межі, уdist/boundaries/<boundary>/helm/, деякі з них — у власній теці нижче. Файли, які не вказують простору імен, як-от файли збірок MCP і Dify, потрапляють до того, який вказує ваш контекстkubectl, або доdefault, якщо він не вказує жодного; спершу створіть там Secrets, які вони читають, а потім застосуйте теку:Terminal window kubectl apply -R -f dist/helm/-Rохоплює файли в цих теках. Service типуClusterIP— тип, який збірки MCP і Dify надають серверам, що їх запускають, — доступний лише зсередини кластера: щоб звернутися до нього зі своєї машини, перенаправте на нього локальний порт за допомогоюkubectl port-forward svc/<service> <local port>:<port>; ця команда працює, доки ви її не зупините. - у сутності Aggregate — ще один компонент, ні з чим не з’єднаний:
Поруч зі своїми чернетками імпорт записує .aggrega-import.json — відомості про те, що він записав. Зберігайте його, доки маєте намір запускати aggrega import --sync: ця команда читає його, щоб відрізнити ваші зміни від записаного самим імпортом. Зберігайте й файл відповідей: він не містить жодного секрету, тож може зберігатися в системі контролю версій поруч із джерелом, і кожен пізніший імпорт цього джерела його читає.
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте в нього цей промпт.
Використовуй лише інструменти Aggrega і сам не створюй жодної теки. Виклич інструмент `import`, задавши `source` як `compose.yaml` і `target` як `compose`: він записує свої чернетки в теку Workspace. Якщо він повідомить, що деяких значень ще бракує, назви мені кожне й поясни, що це, і зачекай, поки я впишу відповіді поруч із їхніми ключами у файлі відповідей, який він назве; потім знову виклич інструмент `import` так само. Далі виклич інструмент `validate`, задавши `release` як `release.yaml`, та інструмент `build`, задавши `release` як `release.yaml` і `write` як true. Скажи мені, які файли записала збірка; вони лежать у `dist/` у теці Workspace.Відкриття у VS Code
Коли встановлено розширення Aggrega для Visual Studio Code, відкрийте у VS Code робочу область, у якій виконувався імпорт, — теку з її .aggrega-config.yaml: чернетки лежать у ній, у корені або в теці, яку вказав --output-dir. Якщо робоча область містить одну сутність Release, редактор вибирає її за вас; якщо кілька, Aggrega: Select Release… вибирає ту, з якою працює редактор. Редактор перевіряє чернетки щодо вибраної сутності Release під час редагування, позначаючи знайдене у файлі та на панелі «Проблеми». Aggrega: Show topology graph у палітрі команд малює компоненти вибраної сутності Release і з’єднання між ними. Aggrega: Build, Aggrega: Preview build і Aggrega: Pull діють на ту саму сутність Release, і кожна з них також є кнопкою на панелі Commands подання Aggrega на панелі дій; Build записує свої файли в dist/ робочої області. Решту описано в розділі Використання Aggrega у Visual Studio Code.
Звідки беруться імпортери
Кожен формат читає плагін-імпортер. Базові імпортери компілятора, по одному для кожного формату з таблиці нижче, публікуються з кожним випуском компілятора й обслуговують свої формати в кожному робочому просторі без жодного запису у вашому каталозі. Перший імпорт, якому потрібен імпортер, завантажує його з типового реєстру робочого простору у версії самого компілятора, перевіряє його та зберігає в кеші вмісту робочого простору, тож кожен наступний імпорт читає його звідти, не звертаючись заради нього до мережі. Якщо модуль узагалі неможливо завантажити — скажімо, робочий простір офлайн, — імпорт зупиняється й називає два способи розмістити його на машині. Базові імпортери повністю описують кожен імпортер, а також параметри, які імпортер отримує через запис plugins.importer.
Формати
| Формат | Що він читає | Покроковий приклад |
|---|---|---|
| Compose | файл Compose і його файл перевизначень або директорія, що їх містить | Імпорт проєкту Compose |
| Конфігурації клієнтів MCP | .mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json або server.json реєстру MCP | Імпорт конфігурації клієнта MCP |
| Langflow | потік, експортований з Langflow, у форматі JSON | Імпорт потоку Langflow |
| Flowise | chatflow або agentflow, експортований з Flowise, у форматі JSON | Імпорт chatflow Flowise |
| n8n | робочий процес, експортований з n8n, у форматі JSON | Імпорт робочого процесу n8n |
| Dify | застосунок, експортований з Dify у його DSL, у форматі YAML | Імпорт застосунку Dify |
| CrewAI | оголошення агентів і завдань проєкту CrewAI | Імпорт проєкту CrewAI |
| LangGraph | langgraph.json застосунку LangGraph | Імпорт застосунку LangGraph |
| Google ADK | файли Agent Config застосунку, побудованого на Google ADK, починаючи з root_agent.yaml | Імпорт агента Google ADK |
| Microsoft Agent Framework | декларативний агент — документ YAML виду Prompt | Імпорт декларативного агента Microsoft Agent Framework |
aggrega import — повний довідник команди: кожен прапорець, як розпізнається джерело, що змінює --sync і що він відхиляє. Файл відповідей імпорту описує файл відповідей: де він розташований, що містить і як відповідати на секрет.