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

Імпорт проєкту CrewAI

Цей покроковий посібник імпортує оголошення агентів і завдань проєкту CrewAI — команди з двох агентів, що відповідають на запитання клієнта про плани підтримки, — і збирає команду для Docker Compose. Імпорт створює чернетку кожного файлу, який читає збірка: обох агентів і їхню модель, ключ, який кожен із них подає моделі як посилання на змінну, і реалізації кожного з них. Він один раз запитує єдине значення, якого не містить жодне оголошення, — образ, у якому працює програма команди. Кожен файл і кожен блок виводу нижче взято з реального запуску; оголошення і кожен етап посібника містяться в прикладі import-crewai, де скрипт перевірки знову запускає імпорт, порівнює те, що він записує, те, що він виводить, і блоки, які цитує ця сторінка, з файлами, що там зберігаються, а також перевіряє та збирає те, що записав імпорт.

Створення прикладу

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

Запишіть приклад у нову теку, названу за ним:

Terminal window
aggrega scaffold --example import-crewai

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку; наступна, нижче, переходить у її теку source, яка містить те, що імпортує ця сторінка, і де виконується імпорт:

Terminal window
cd import-crewai

Тека source згенерованого прикладу, відкрита у Visual Studio Code, з конфігурацією агентів crew: дослідником і автором.

Проєкт

Проєкт 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-mini

tasks.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:

Terminal window
cd source

Запуск імпорту

Вкажіть теку команди. Імпорт читає оголошення в ній і більше нічого:

Terminal window
aggrega import src/support_brief --target compose

У стандартний вивід він виводить перелік записаного:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .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 applied
mapped researcher (agent) to core/ai-agent/crewai as a reference, NONE
mapped openai/gpt-4o-mini (llm) to core/ai-model/openai as a reference, NONE
mapped writer (agent) to core/ai-agent/crewai as a reference, NONE
made 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)

Імпорт, запущений з редактора: чернетки сутностей Aggregate, Release і Manifest з’являються поруч із проєктом crew, вивід Aggrega перелічує, як зіставлено кожного агента, модель і завдання, і записані файли, а сповіщення повідомляє, що імпорт створив 3 чернетки файлів, розпізнані як crewai.

  • Рядок 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 writer
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
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/v1beta1
kind: Release
metadata:
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/v1beta1
kind: Manifest
metadata:
name: imported/support-brief
version: 0.1.0
spec:
mappings:
components:
type:
core/ai-agent/crewai: compose/crewai
core/ai-model/openai: compose/openai
features:
type:
core/secret-value: compose/dotenv-secret

release.lock фіксує за дайджестом сутності каталогу, до яких розв’язалася сутність Release, а .aggrega-import.json — це відомості про те, що записав імпорт; їх читає пізніший aggrega import --sync.

Перевірка та збирання

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

Чернетка сутності Release, відкрита в редакторі після валідації; вивід Aggrega і сповіщення обидва повідомляють, що проблем не знайдено.

Збірка чернетки сутності Release: у Провіднику з’являється тека dist, вивід Aggrega перелічує записаний файл Docker Compose, а сповіщення повідомляє, що записано 1 файл.

Перевірка виводить:

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; потім виконайте збірку:

Terminal window
docker build -t support-brief:local .
aggrega import src/support_brief --sync
aggrega build --release release.yaml

Коли обидві відповіді — support-brief:local, синхронізація серед рядків, які виводить, називає два значення, які вона змінила:

changed spec.components.researcher.infra.image in release.yaml
changed spec.components.writer.infra.image in release.yaml

Потім встановіть ключ у своїй оболонці й запустіть стек:

Terminal window
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, щойно програма почне слухати, за кілька секунд після запуску стека:

Terminal window
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.

Зупиніть стек командою:

Terminal window
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. Команда працює, доки ви її не зупините:

Terminal window
kubectl port-forward deploy/researcher 8000:8000
Forwarding from 127.0.0.1:8000 -> 8000
Forwarding from [::1]:8000 -> 8000

З іншого термінала надішліть той самий запит на перенаправлений порт:

Terminal window
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]"
}