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

Імпорт

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 натомість записує їх порожніми (Налаштування). Прочитайте попередження, перш ніж ділитися чернеткою.
  • Він нічого не розгортає й не запускає. Він читає джерело та ваш каталог і записує файли. Збирання чернеток і запуск того, що записала збірка, — це окремі кроки, які виконуєте ви.

Як виконується імпорт

Імпорт можна виконати командами нижче або доручити його вашому ШІ-асистенту.

  1. Почніть із робочого простору. Імпорт записує свої чернетки всередині кореня робочого простору, у якому він запущений, — теки, що містить .aggrega-config.yaml із ключем workspace, — або всередині директорії, яку задає --output-dir. Він ніколи не перезаписує наявну там сутність Aggregate.

  2. Каталог, з яким порівнює імпорт. Імпорт оцінює ваше джерело щодо сутностей 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 імпорт, якому довелося б отримати знімок, зупиняється й називає, що слід запустити.

  3. Запустіть імпорт. Назвіть файл або директорію:

    Terminal window
    aggrega import compose.yaml --target compose

    Формат розпізнається за іменем і вмістом файлу; там, де це не так, його задає --format. --target задає можливість провайдера, як-от compose чи helm, і створює чернетку сутності Manifest, що зіставляє кожен тип компонента й кожен тип функції, потрібний чернеткам, з тією сутністю Recipe цієї можливості, яку ваш каталог пропонує для нього: з єдиною наявною або, серед кількох, з тією, що названа за типом. Чернетка сутності Release називає цю сутність Manifest, а вміст чернеток залежить від цілі: для compose секрет — це посилання на змінну, яку Docker Compose заповнює з вашої оболонки, для helm — ім’я Kubernetes Secret. У стандартний потік помилок імпорт виводить назву прочитаного формату, кожне попередження та по одному рядку на кожен зіставлений вузол; у стандартний вивід — перелік записаних файлів.

  4. Дайте відповідь на те, чого не містить жодне джерело. Значення, якого вимагає каталог і якого не може містити жодне джерело, — електронна адреса облікового запису власника, образ застосунку, зібраного з вашого власного коду, ім’я Kubernetes Secret — потребує відповіді лише раз. Імпорт читає відповіді з import-answers.yaml поруч із джерелом або з файлу, який задає --answers; у терміналі він запитує кожне ще відсутнє значення, по одному запитанню за раз, і записує ваші відповіді в цей файл. На секрет відповідають тим, звідки він береться, — змінною або ім’ям Secret, — і ніколи його значенням. Там, де нічого не можна запитати, — у безперервній інтеграції, через конвеєр, з асистента чи редактора — імпорт записує файл відповідей із ключем кожного відсутнього значення й порожньою відповіддю, перелічує їх і завершується зі статусом 1; заповніть їх і запустіть імпорт знову. Один файл відповідей слугує кожній цілі: відповідь, яка не потрібна чернеткам для певної цілі, зберігається у файлі й лишається невикористаною. Файл відповідей імпорту повністю описує цей файл.

  5. Імпорт завантажує те, що потрібно збірці. Щойно нічого не бракує, імпорт завантажує залежності чернетки сутності Release, як це робить aggrega pull, і записує поруч release.lock. З --offline він нічого не завантажує й називає команду aggrega pull, яку слід запустити.

  6. Перевірте та зберіть. У теці з чернетками:

    Terminal window
    aggrega validate --release release.yaml
    aggrega build --release release.yaml

    Коли обидві команди проходять, збірка вже записала файли цілі в dist/. Відмова називає, що змінити й де, у документі, який ви змінюєте.

  7. Запустіть те, що записала збірка. Збірка для Docker Compose записує dist/compose/docker-compose.yaml, і цей файл не задає назви проєкту Compose, тож задайте її за допомогою -p:

    Terminal window
    docker compose -p <name> -f dist/compose/docker-compose.yaml up -d

    Без -p Docker Compose називає проєкт за текою, що містить файл, compose, тож два робочі простори, запущені таким способом, спільно використовують один проєкт. Сервіси розміщуються в одній мережі, яку Docker Compose називає за проєктом, <name>_compose. До сервісу, для якого збірка не публікує жодного порту, звертаються зсередини цієї мережі за допомогою docker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> … або з контейнера, який ви запускаєте в цій мережі, за допомогою docker run --network <name>_compose …. Розділи «Запуск» і «Перевірка» покрокового посібника показують команди для його власної збірки.

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

Поруч зі своїми чернетками імпорт записує .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
Flowisechatflow або agentflow, експортований з Flowise, у форматі JSONІмпорт chatflow Flowise
n8nробочий процес, експортований з n8n, у форматі JSONІмпорт робочого процесу n8n
Difyзастосунок, експортований з Dify у його DSL, у форматі YAMLІмпорт застосунку Dify
CrewAIоголошення агентів і завдань проєкту CrewAIІмпорт проєкту CrewAI
LangGraphlanggraph.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 і що він відхиляє. Файл відповідей імпорту описує файл відповідей: де він розташований, що містить і як відповідати на секрет.