Импорт проекта 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]"}