Перейти к содержимому
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]"
}