Імпорт проєкту CrewAI
Цей покроковий посібник імпортує оголошення агентів і завдань проєкту CrewAI — команди з двох агентів, що відповідають на запитання клієнта про плани підтримки, — і збирає команду для Docker Compose. Імпорт створює чернетку кожного файлу, який читає збірка: обох агентів і їхню модель, ключ, який кожен із них подає моделі як посилання на змінну, і реалізації кожного з них. Він один раз запитує єдине значення, якого не містить жодне оголошення, — образ, у якому працює програма команди. Кожен файл і кожен блок виводу нижче взято з реального запуску; оголошення і кожен етап посібника містяться в прикладі import-crewai, де скрипт перевірки знову запускає імпорт, порівнює те, що він записує, те, що він виводить, і блоки, які цитує ця сторінка, з файлами, що там зберігаються, а також перевіряє та збирає те, що записав імпорт.
Створення прикладу
Цей імпорт можна виконати командами з цієї сторінки або доручити його вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example import-crewaiПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку; наступна, нижче, переходить у її теку source, яка містить те, що імпортує ця сторінка, і де виконується імпорт:
cd import-crewai
Проєкт
Проєкт CrewAI зберігає поведінку своєї команди в програмі й оголошує своїх агентів і завдання у файлах конфігурації. Цей проєкт, написаний для цього посібника, має класичну структуру CrewAI, і імпорт читає два його файли оголошень у src/support_brief/config/. Програму — crew.py класичного проєкту та інструменти, які вона визначає, — ніколи не читають, тож приклад містить лише оголошення.
agents.yaml оголошує двох агентів, обидва на gpt-4o-mini від OpenAI:
researcher: role: > Support plan researcher goal: > Find what each support plan of the company covers, and what it costs backstory: > You keep the company's support plans at your fingertips and answer from them alone. llm: openai/gpt-4o-mini verbose: true
writer: role: > Support reply writer goal: > Turn the researcher's findings into a short, friendly reply to the customer backstory: > You write replies customers can act on, in plain words. llm: openai/gpt-4o-minitasks.yaml призначає кожному одне завдання:
research_task: description: > Find the support plans that answer the customer's question: {question} expected_output: > The plans that apply, each with what it covers and what it costs agent: researcher
reply_task: description: > Write a reply to the customer's question from the researcher's findings expected_output: > A reply of at most five sentences agent: writerУ корені проєкту файл .aggrega-config.yaml робить теку робочим простором:
# The workspace key marks this directory as the workspace root, so an import run# here writes its drafts beside src/.workspace: {}# The registry the importer is fetched from the first time an import needs it.default_registry: hub.aggrega.aiІмпорт посилається на сутності Components агентів і моделей із каталогу, а --target створює чернетку сутності Manifest із його сутностей Recipes. Робочий простір не вказує жодної теки каталогу, тому імпорт читає каталог стандартної бібліотеки з реєстру, з якого отримує свій імпортер: підписаний знімок опублікованого каталогу, який перший імпорт отримує, перевіряє та зберігає в кеші вмісту робочого простору і який запис, що його імпорт пише поруч зі своїми чернетками, називає за дайджестом. Робочий простір, що вказує власні теки каталогу — у AGGREGA_CATALOG_DIRS або в workspace.catalog_dirs, — натомість імпортує на їх основі.
Що запитує імпорт
Оголошення називають модель кожного агента, але ніколи — образ, у якому працює програма crew: цей образ ви збираєте зі свого проєкту. Тому імпорт запитує його, по одному разу для кожного агента. У терміналі він ставить питання для кожного і записує відповіді в чернетки та у файл відповідей import-answers.yaml усередині каталогу, який імпортує, src/support_brief/, тож наступний імпорт читає їх звідти й нічого не запитує. Без термінала — у безперервній інтеграції або через конвеєр — він нічого не запитує: записує файл із порожніми ключами й зупиняється, називаючи файл. Приклад уже містить цей файл, де обидва агенти використовують той самий образ, ghcr.io/example/support-brief:1.0.0, що позначає образ, який ви збираєте:
# Values the import could not draft from the source, keyed by the drafted file and the key path inside# it. Write each one beside its key; an import of the same source, and a sync, read them from here and# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable# name, ${NAME}, or the name of a Kubernetes Secret.release.yaml: # Container image running the CrewAI application code. spec.components.researcher.infra.image: "ghcr.io/example/support-brief:1.0.0" # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.researcher.uses.model.gpt-4o-mini.features.credential.infra.origin: "openai-api-key" # Container image running the CrewAI application code. spec.components.writer.infra.image: "ghcr.io/example/support-brief:1.0.0" # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.writer.uses.model.gpt-4o-mini.features.credential.infra.origin: "openai-api-key"Дві відповіді origin призначені для збирання під Kubernetes із --target helm: там кожен агент читає ключ OpenAI з Kubernetes Secret, а відповіддю є ім’я Secret, openai-api-key, ніколи не сам ключ. Збирання під Docker Compose натомість читає ключ із вашої оболонки, тому цей імпорт не використовує ці відповіді. Файл відповідей імпорту описує файл, питання та правила для відповіді щодо секрету.
aggrega import перелічує кожен прапорець, який приймає команда, зокрема --answers, що вказує файл відповідей, збережений деінде.
Перейдіть у source:
cd sourceЗапуск імпорту
Вкажіть теку команди. Імпорт читає оголошення в ній і більше нічого:
aggrega import src/support_brief --target composeУ стандартний вивід він виводить перелік записаного:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonУ стандартний потік помилок, де <workspace> позначає теку, у якій ви його запустили:
[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]read as the crewai format, with drafted paths relative to <workspace>info: the answers file <workspace>/src/support_brief/import-answers.yaml also answers spec.components.researcher.uses.model.gpt-4o-mini.features.credential.infra.origin in release.yaml, spec.components.writer.uses.model.gpt-4o-mini.features.credential.infra.origin in release.yaml, which these drafts do not leave empty; those answers are kept there and not appliedmapped researcher (agent) to core/ai-agent/crewai as a reference, NONEmapped openai/gpt-4o-mini (llm) to core/ai-model/openai as a reference, NONEmapped writer (agent) to core/ai-agent/crewai as a reference, NONEmade no choice for research_task (task)made no choice for reply_task (task)Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)
- Рядок
infoназиває відповіді, які не використовують чернетки для Docker Compose і які зберігаються у файлі відповідей для збирання під Kubernetes. - Рядки
mappedповідомляють, що кожен агент є екземпляром агента CrewAI стандартної бібліотеки,core/ai-agent/crewai, і що модель, яку називають обидва,openai/gpt-4o-mini, є екземпляромcore/ai-model/openai. Їхній рівень —NONE: імпорт CrewAI посилається на ці сутності Components за тим, що називають оголошення, — агентом і постачальником моделі, — а не порівнюючи кожну з каталогом. - Рядки
made no choiceповідомляють, що для завдань у чернетці нічого не створено: завдання — це логіка, яку виконує програма команди. - Рядок
Pull completeозначає, що імпорт отримує те, від чого залежить чернетка сутності Release, як це робитьaggrega pull, уrelease.lock, щоб чернетки одразу проходили валідацію та збірку. З--offlineімпорт нічого не завантажує і називає командуaggrega pull, яку слід виконати.
Що він записує
Сутності Aggregate, Release і Manifest отримують назву imported/support-brief: файли config/agents.yaml і config/tasks.yaml проєкту не називають жодної команди — її назва міститься в програмі, яку імпорт не читає — тому імпорт їхньої теки отримує назву за текою, support_brief, записаною як сегмент назви, у просторі імен, який задає налаштування target_namespace імпортера, тобто imported, якщо ви не задасте інший (Налаштування).
aggregate.yaml — по одному екземпляру на агента, кожен під’єднаний до моделі, яку він називає, із ключем, який він пред’являє, оголошеним на з’єднанні, і сама модель; на початку — коментарі, що кажуть, що було прочитано, а що ні:
# CrewAI declarations read:# - config/agents.yaml# - 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# - reply_task, assigned to writerapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/support-brief version: 0.1.0 description: Draft Aggregate imported from a source in the crewai format.spec: components: researcher: type: core/ai-agent/crewai values: role: "Support plan researcher\u000A" goal: "Find what each support plan of the company covers, and what it costs\u000A" backstory: "You keep the company's support plans at your fingertips and answer from them alone.\u000A" allow_delegation: false log_level: DEBUG uses: model: gpt-4o-mini: target: gpt-4o-mini # For the compose target, the lines below declare credential on gpt-4o-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 writer: type: core/ai-agent/crewai values: role: "Support reply writer\u000A" goal: "Turn the researcher's findings into a short, friendly reply to the customer\u000A" backstory: "You write replies customers can act on, in plain words.\u000A" allow_delegation: false log_level: INFO uses: model: gpt-4o-mini: target: gpt-4o-mini # For the compose target, the lines below declare credential on gpt-4o-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 openai/gpt-4o-mini. gpt-4o-mini: type: core/ai-model/openai values: model: "gpt-4o-mini"role, goal і backstory перенесено так, як їх оголошено, разом із розривом рядка, яким закінчується кожен згорнутий блок. log_level дорівнює DEBUG для дослідника, у якого оголошено verbose, і INFO для автора, у якого ні. Агент, що не оголошує allow_delegation, отримує в чернетці false. Модель є розміщеним сервісом, тому сутність Component агента відхиляє з’єднання з нею, яке не несе жодних облікових даних; кожне з’єднання оголошує їх під ключем OPENAI_API_KEY.
release.yaml — середовище, образ і опублікований порт кожного агента та звідки береться кожен ключ:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/support-brief # 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 crewai format.spec: aggregate: imported/support-brief manifest: imported/support-brief components: researcher: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the crew's program image: "ghcr.io/example/support-brief:1.0.0" # Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal. published_port: 8000 uses: model: gpt-4o-mini: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential researcher presents to gpt-4o-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}" writer: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the crew's program image: "ghcr.io/example/support-brief:1.0.0" # Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal. published_port: 8001 uses: model: gpt-4o-mini: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential writer presents to gpt-4o-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-4o-mini: {}Середовище development — це типове значення, яке записує імпорт, бо жодне оголошення його не називає; змініть його там, де сутність Release розгортається деінде. Кожен образ — це відповідь, яку імпорт прочитав з import-answers.yaml. Кожного агента опубліковано на loopback-адресі вашої машини з переспрямуванням на порт, який слухає його програма, infra.port, типово 8000: дослідника на 8000, а автора на 8001, оскільки два сервіси однієї сутності Release не можуть публікувати той самий порт. Оголошення не називають жодної змінної для ключа, тому кожне з’єднання читає його з ${OPENAI_API_KEY}, змінної, яку читають клієнтські бібліотеки OpenAI, як посилання на змінну, а ніколи не як значення.
manifest.yaml — сутність Recipe для Compose кожного типу та реалізація, яка записує посилання на змінну ключа у файл Compose так, як його написано:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/support-brief version: 0.1.0spec: mappings: components: type: core/ai-agent/crewai: compose/crewai core/ai-model/openai: compose/openai features: type: core/secret-value: compose/dotenv-secretrelease.lock фіксує за дайджестом сутності каталогу, до яких розв’язалася сутність Release, а .aggrega-import.json — це відомості про те, що записав імпорт; їх читає пізніший aggrega import --sync.
Перевірка та збирання
aggrega validate --release release.yamlaggrega build --release release.yaml

Перевірка виводить:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)release dependency validation passed: release.yaml (schema-pillar + dependency pillars)і збірка, де <workspace> позначає теку, у якій ви її запустили:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: a total build time, which differs per run]Build completed: 1 file written to <workspace>/distРядок notice має рекомендаційний характер: секретна сутність Feature приймає свій origin із values сутності Aggregate або з infra сутності Release, і повідомлення сповіщає, що один листок оголошено в обох. Воно не змінює жодного вердикту.
Сервіс дослідника в dist/compose/docker-compose.yaml; сервіс автора відрізняється лише назвою, значеннями, які несуть його власні змінні, і портом, який він публікує:
services: researcher: image: ghcr.io/example/support-brief:1.0.0 environment: OPENAI_BASE_URL: https://api.openai.com/v1 MODEL: gpt-4o-mini CREWAI_ALLOW_DELEGATION: "false" CREWAI_BACKSTORY: | You keep the company's support plans at your fingertips and answer from them alone. CREWAI_GOAL: | Find what each support plan of the company covers, and what it costs CREWAI_LOG_LEVEL: DEBUG CREWAI_ROLE: | Support plan researcher OPENAI_API_KEY: ${OPENAI_API_KEY} ports: - 127.0.0.1:8000:8000 [… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version] networks: - composeАгент отримує адресу моделі та її назву як OPENAI_BASE_URL і MODEL — змінні, з яких їх читає CrewAI, — а ключ — як OPENAI_API_KEY. Його роль, мета, передісторія, перемикач делегування та рівень журналювання надходять під назвами, які сутність Component CrewAI типово їм дає, щоб їх читала програма команди; блок inject: на самому компоненті натомість доставляє будь-яке з них під назвою, яку читає програма. Кожне значення, яке підготував імпорт, зберігає розрив рядка, яким закінчувалося його оголошення, тож файл записує його як блок. Модель не отримує власного сервісу: агенти звертаються до API OpenAI за його власною адресою. Ключ — це посилання на змінну, яке заповнюється з вашої оболонки під час запуску стеку. Кожен сервіс публікує свій порт лише на 127.0.0.1: 8000 дослідника і 8001 автора, кожен з переспрямуванням на порт 8000 програми у своєму контейнері.
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте в нього цей промпт.
Використовуй лише інструменти Aggrega і не створюй жодної теки самостійно. Якщо тека Workspace ще не містить теки `import-crewai`, один раз виклич інструмент `scaffold` зі значенням `example`, встановленим на `import-crewai`, і без `dir`: він записує приклад у нову теку `import-crewai`, тека `source` якої містить те, що імпортує ця сторінка. Потім виклич інструмент `import` з `workspace_root`, встановленим на `import-crewai/source`, `source`, встановленим на `src/support_brief`, і `target`, встановленим на `compose`: він читає потрібні відповіді з `import-answers.yaml` у теці `src/support_brief`, записує свої чернетки в `import-crewai/source` і завантажує те, що їм потрібно. Потім виклич інструмент `validate` з `workspace_root`, встановленим на `import-crewai/source`, і `release`, встановленим на `release.yaml`, та інструмент `build` з `workspace_root`, встановленим на `import-crewai/source`, `release`, встановленим на `release.yaml`, і `write`, встановленим на true. Скажи мені, які файли записала збірка; вони лежать у `import-crewai/source/dist/`.Відкриття у VS Code
Коли розширення Aggrega для Visual Studio Code встановлено, відкрийте у VS Code теку import-crewai/source, куди імпорт записав свої чернетки. Тека містить одну сутність Release, чернетку release.yaml, тож редактор сам вибирає її і під час редагування перевіряє чернетки щодо цієї сутності Release, позначаючи знайдене у файлі та на панелі «Проблеми». Aggrega: Show topology graph у палітрі команд малює компоненти сутності Release і зв’язки між ними. Aggrega: Build, Aggrega: Preview build і Aggrega: Pull діють на ту саму сутність Release, і кожна з них також є кнопкою на панелі Commands подання Aggrega на панелі дій; Build записує свої файли в dist/ теки. Решту описує Використання Aggrega у Visual Studio Code.
Запуск
Образ ви збираєте з проєкту за допомогою власного Dockerfile. Docker Compose запускає власну команду образу як сервіс кожного агента, оскільки Recipe її не задає, тож ця команда має працювати безперервно й має обслуговувати запити, якщо ви хочете звертатися до crew. Адресу, маршрут і відповідь визначає ваша програма.
Наведений нижче запуск використовував такий образ: програму crew у класичній структурі CrewAI — crew.py, що будує crew з двох файлів декларацій так, як їх прочитав імпорт, — і, як команду образу, невеликий власний HTTP-сервер програми на порту 8000, який запускає crew один раз для кожного POST /kickoff. Зберіть свій образ у корені проєкту, запишіть його назву замість ghcr.io/example/support-brief:1.0.0 для обох агентів у src/support_brief/import-answers.yaml і знову виконайте імпорт із --sync, який записує нові відповіді в чернетки й знову виконує pull; потім виконайте збірку:
docker build -t support-brief:local .aggrega import src/support_brief --syncaggrega build --release release.yamlКоли обидві відповіді — support-brief:local, синхронізація серед рядків, які виводить, називає два значення, які вона змінила:
changed spec.components.researcher.infra.image in release.yamlchanged spec.components.writer.infra.image in release.yamlПотім встановіть ключ у своїй оболонці й запустіть стек:
export OPENAI_API_KEY='your OpenAI key'docker compose -p support-brief -f dist/compose/docker-compose.yaml up -d --wait-p задає назву проєкту, як пояснює крок запуску в розділі Як виконується імпорт.
Тестування
Запит нижче досягає програми, яку запускає образ цього покрокового посібника: crew за невеликим HTTP-сервером на порту 8000, що відповідає на POST /kickoff. Ваша власна програма сама визначає свій маршрут і відповідь. Надішліть його досліднику на http://127.0.0.1:8000, адресу, яку публікує published_port, щойно програма почне слухати, за кілька секунд після запуску стека:
curl -sS -X POST http://127.0.0.1:8000/kickoff -H 'Content-Type: application/json' \ -d '{"question": "Which support plan covers a weekend outage, and what does it cost?"}'{ "error": "the crew failed: AuthenticationError: Error code: 401 - {'error': {'message': 'Incorrect API key provided: sk-place************-key. [… omitted: where to find an API key, and the error's type and code]"}Запуск задав OPENAI_API_KEY як заповнювач, тож відповідь — це відмова OpenAI, яку передала програма. Запит crew досяг API OpenAI з ключем, який доставило збирання. Обидва агенти запускають той самий образ, тож запит міг піти до будь-якого з них: автор відповідає так само на http://127.0.0.1:8001.
Зупиніть стек командою:
docker compose -p support-brief -f dist/compose/docker-compose.yaml downУ Kubernetes імпортуйте з --target helm і надішліть образ до реєстру, з якого завантажує ваш кластер, вказавши його в src/support_brief/import-answers.yaml. Потім створіть Secret openai-api-key і застосуйте збирання, як описує крок запуску в розділі Як виконується імпорт. Deployment кожного агента не має Service, тож перенаправте локальний порт на порт researcher. Команда працює, доки ви її не зупините:
kubectl port-forward deploy/researcher 8000:8000Forwarding from 127.0.0.1:8000 -> 8000Forwarding from [::1]:8000 -> 8000З іншого термінала надішліть той самий запит на перенаправлений порт:
curl -sS -X POST http://127.0.0.1:8000/kickoff -H 'Content-Type: application/json' \ -d '{"question": "Which support plan covers a weekend outage, and what does it cost?"}'{ "error": "the crew failed: AuthenticationError: Error code: 401 - {'error': {'message': 'Incorrect API key provided: sk-place************-key. [… omitted: where to find an API key, and the error's type and code]"}