Importowanie projektu CrewAI
Ten przewodnik krok po kroku importuje deklaracje agentów i zadań projektu CrewAI — zespołu (crew) dwóch agentów, który odpowiada na pytanie klienta o plany wsparcia — i buduje zespół dla Docker Compose. Import tworzy szkic każdego pliku, który odczytuje build: obu agentów i ich model, klucz, który każdy z nich przedstawia modelowi jako odwołanie do zmiennej, oraz realizacje każdego z nich. Pyta jeden raz o jedyną wartość, której nie zawiera żadna deklaracja: obraz, w którym działa program zespołu. Każdy plik i każdy blok wyjścia poniżej pochodzi z rzeczywistego uruchomienia; deklaracje i każdy etap przewodnika znajdują się w przykładzie import-crewai, gdzie skrypt kontrolny ponownie uruchamia import, porównuje to, co zapisuje, to, co wypisuje, oraz bloki cytowane na tej stronie z przechowywanymi tam plikami, a także waliduje i buduje to, co zapisał import.
Generowanie przykładu
Ten import można uruchomić poleceniami z tej strony albo zlecić to asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example import-crewaiNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu; kolejne, poniżej, przechodzi do folderu source w nowym folderze, który zawiera to, co importuje ta strona, i w którym uruchamia się import:
cd import-crewai
Projekt
Projekt CrewAI przechowuje zachowanie swojego zespołu w programie, a swoich agentów i zadania deklaruje w plikach konfiguracyjnych. Ten projekt, napisany na potrzeby tego przewodnika, ma klasyczny układ CrewAI, a import odczytuje jego dwa pliki deklaracji w src/support_brief/config/. Program — crew.py klasycznego projektu i zdefiniowane w nim narzędzia — nigdy nie jest odczytywany, więc przykład zawiera tylko deklaracje.
agents.yaml deklaruje dwóch agentów, obu na modelu gpt-4o-mini od 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 przypisuje każdemu z nich jedno zadanie:
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: writerW katalogu głównym projektu plik .aggrega-config.yaml czyni folder obszarem roboczym:
# 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.aiImport odwołuje się do encji Components agenta i modelu z katalogu, a --target tworzy szkic encji Manifest na podstawie encji Recipes z tego katalogu. Obszar roboczy nie wskazuje żadnego folderu katalogu, więc import odczytuje katalog biblioteki standardowej z rejestru, z którego pobiera swój importer: podpisaną migawkę opublikowanego katalogu, którą pierwszy import pobiera, weryfikuje i przechowuje w pamięci podręcznej treści obszaru roboczego i którą rekord zapisywany przez import obok jego szkiców wskazuje za pomocą jej skrótu. Obszar roboczy, który wskazuje własne foldery katalogu — w AGGREGA_CATALOG_DIRS lub pod workspace.catalog_dirs — importuje zamiast tego względem nich.
O co pyta import
Deklaracje wskazują model każdego agenta, nigdy obraz, w którym działa program crew: ten obraz buduje się z własnego projektu. Dlatego import o niego pyta, raz dla każdego agenta. W terminalu zadaje pytanie dla każdego z nich i zapisuje odpowiedzi w szkicach oraz w pliku odpowiedzi import-answers.yaml wewnątrz importowanego katalogu src/support_brief/, dzięki czemu następny import odczytuje je stamtąd i o nic nie pyta. Bez terminala — w ciągłej integracji lub przez potok — o nic nie pyta: zapisuje plik z pustymi kluczami i zatrzymuje się, wskazując ten plik. Przykład zawiera już ten plik, z oboma agentami na tym samym obrazie, ghcr.io/example/support-brief:1.0.0, który zastępuje obraz budowany samodzielnie:
# 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"Dwie odpowiedzi origin są przeznaczone dla kompilacji dla Kubernetes z --target helm: tam każdy agent odczytuje klucz OpenAI z obiektu Secret Kubernetes, a odpowiedzią jest nazwa tego obiektu Secret, openai-api-key, nigdy klucz. Kompilacja dla Docker Compose odczytuje natomiast klucz z powłoki, więc ten import nie używa tych odpowiedzi. Plik odpowiedzi importu opisuje plik, pytania i zasady dotyczące odpowiedzi dla sekretu.
aggrega import wymienia każdą flagę przyjmowaną przez polecenie, w tym --answers, która wskazuje plik odpowiedzi przechowywany gdzie indziej.
Należy przejść do source:
cd sourceUruchomienie importu
Należy wskazać katalog zespołu. Import odczytuje znajdujące się w nim deklaracje i nic więcej:
aggrega import src/support_brief --target composeNa standardowym wyjściu wymienia to, co zapisał:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa standardowym wyjściu błędów, gdzie <workspace> oznacza folder, w którym go uruchomiono:
[… 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)
- Wiersz
infowskazuje odpowiedzi, których szkice dla Docker Compose nie używają, zachowane w pliku odpowiedzi na potrzeby kompilacji dla Kubernetes. - Wiersze
mappedmówią, że każdy agent jest instancją agenta CrewAI z biblioteki standardowej,core/ai-agent/crewai, a model wskazany przez obu,openai/gpt-4o-mini, jest instancjącore/ai-model/openai. Ich poziom toNONE: import CrewAI odwołuje się do tych encji Components na podstawie tego, co wskazują deklaracje, czyli agenta i dostawcy modeli, zamiast porównywać każdą z nich z katalogiem. - Wiersze
made no choicemówią, że dla zadań nie powstaje żaden szkic: zadanie to logika, którą wykonuje program zespołu. - Wiersz
Pull completeoznacza, że import pobiera to, od czego zależy szkic encji Release, tak jak robi toaggrega pull, dorelease.lock, dzięki czemu szkice od razu przechodzą walidację i budowanie. Z--offlineimport niczego nie pobiera i podaje polecenieaggrega pull, które należy uruchomić.
Co zapisuje import
Encje Aggregate, Release i Manifest otrzymują nazwę imported/support-brief: pliki config/agents.yaml i config/tasks.yaml projektu nie nadają nazwy żadnej załodze — jej nazwa znajduje się w programie, którego import nie odczytuje — więc import ich katalogu otrzymuje nazwę od katalogu, support_brief, zapisaną jako segment nazwy, w przestrzeni nazw określonej przez ustawienie target_namespace importera, imported, o ile nie ustawi się innej (Ustawienia).
aggregate.yaml — jedna instancja na agenta, każda połączona ze wskazanym przez siebie modelem, z kluczem, który przedstawia, zadeklarowanym na połączeniu, oraz model, a na początku komentarze, które mówią, co zostało odczytane, a co nie:
# 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 i backstory są przenoszone tak, jak je zadeklarowano, łącznie ze znakiem nowego wiersza, którym kończy się każdy blok zawijany. log_level ma wartość DEBUG dla agenta researcher, zadeklarowanego jako verbose, i INFO dla agenta writer, który taki nie jest. Agent, który nie deklaruje allow_delegation, otrzymuje w szkicu false. Model jest usługą hostowaną, więc encja Component agenta odrzuca połączenie z nim, które nie niesie żadnego poświadczenia; każde połączenie deklaruje jedno, pod kluczem OPENAI_API_KEY.
release.yaml — środowisko, obraz i opublikowany port każdego agenta oraz źródło każdego klucza:
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: {}Środowisko development to wartość domyślna, którą import zapisuje, ponieważ żadna deklaracja go nie wskazuje; należy je zmienić tam, gdzie encja Release jest wdrażana gdzie indziej. Każdy obraz to odpowiedź, którą import odczytał z import-answers.yaml. Każdy agent jest publikowany na adresie pętli zwrotnej maszyny, z przekierowaniem do portu, na którym nasłuchuje jego program, infra.port, domyślnie 8000: badacz na 8000, a autor na 8001, ponieważ dwie usługi jednej encji Release nie mogą publikować tego samego portu. Deklaracje nie wskazują żadnej zmiennej dla klucza, więc każde połączenie odczytuje go z ${OPENAI_API_KEY}, zmiennej odczytywanej przez biblioteki klienckie OpenAI, jako odwołanie do zmiennej, nigdy jako wartość.
manifest.yaml — encja Recipe dla Compose każdego typu oraz realizacja, która zapisuje odwołanie do zmiennej klucza w pliku Compose dokładnie tak, jak zostało zapisane:
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 rejestruje, według digestu, encje katalogu, na które została rozwiązana encja Release, a .aggrega-import.json to zapis tego, co utworzył import, odczytywany przez późniejsze aggrega import --sync.
Walidacja i kompilacja
aggrega validate --release release.yamlaggrega build --release release.yaml

Walidacja wypisuje:
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)oraz build, gdzie <workspace> oznacza folder, w którym go uruchomiono:
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>/distWiersz notice ma charakter informacyjny: encja Feature sekretu przyjmuje swoje origin z values encji Aggregate lub z infra encji Release, a komunikat informuje, że jeden liść jest zadeklarowany w obu miejscach. Nie zmienia żadnego werdyktu.
Usługa badacza w dist/compose/docker-compose.yaml; usługa autora różni się tylko nazwą, wartościami, które niosą jej własne zmienne, i portem, który publikuje:
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: - composeAgent otrzymuje adres modelu i jego nazwę jako OPENAI_BASE_URL i MODEL, zmienne, z których odczytuje je CrewAI, a klucz jako OPENAI_API_KEY. Jego rola, cel, historia tła, przełącznik delegowania i poziom logowania docierają pod nazwami, które domyślnie nadaje im encja Component CrewAI, aby program zespołu mógł je odczytać; blok inject: na samym komponencie dostarcza zamiast tego dowolną z tych wartości pod nazwą, którą odczytuje program. Każda wartość przygotowana przez import zachowuje znak końca wiersza, którym kończyła się jej deklaracja, więc plik zapisuje ją jako blok. Model nie otrzymuje własnej usługi: agenci docierają do API OpenAI pod jego własnym adresem. Klucz jest odwołaniem do zmiennej, wypełnianym z powłoki podczas uruchamiania stosu. Każda usługa publikuje swój port wyłącznie na 127.0.0.1: badacz 8000, a autor 8001, każdy z przekierowaniem do portu 8000 programu w swoim kontenerze.
Z asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić do niego ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder Workspace nie zawiera jeszcze folderu `import-crewai`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `import-crewai` i bez `dir`: zapisuje ono przykład w nowym folderze `import-crewai`, którego folder `source` zawiera to, co importuje ta strona. Następnie wywołaj narzędzie `import` z `workspace_root` ustawionym na `import-crewai/source`, `source` ustawionym na `src/support_brief` i `target` ustawionym na `compose`: odczytuje ono potrzebne odpowiedzi z `import-answers.yaml` w folderze `src/support_brief`, zapisuje wersje robocze w `import-crewai/source` i pobiera to, czego one potrzebują. Następnie wywołaj narzędzie `validate` z `workspace_root` ustawionym na `import-crewai/source` i `release` ustawionym na `release.yaml` oraz narzędzie `build` z `workspace_root` ustawionym na `import-crewai/source`, `release` ustawionym na `release.yaml` i `write` ustawionym na true. Podaj, które pliki zapisała kompilacja; znajdują się w `import-crewai/source/dist/`.Otwieranie w VS Code
Po zainstalowaniu rozszerzenia Aggrega dla Visual Studio Code należy otworzyć w VS Code folder import-crewai/source, w którym import zapisał wersje robocze. Folder zawiera jedną encję Release, wersję roboczą release.yaml, więc edytor sam ją wybiera i podczas edycji sprawdza wersje robocze względem tej encji Release, oznaczając znalezione problemy w pliku i w panelu Problemy. Aggrega: Show topology graph w palecie poleceń rysuje komponenty encji Release i połączenia między nimi. Aggrega: Build, Aggrega: Preview build i Aggrega: Pull działają na tej samej encji Release, a każde z nich jest też przyciskiem w panelu Commands widoku Aggrega na pasku działań; Build zapisuje swoje pliki w dist/ folderu. Resztę omawia Używanie Aggrega w Visual Studio Code.
Uruchomienie
Obraz buduje się z projektu, za pomocą własnego pliku Dockerfile. Docker Compose uruchamia własne polecenie obrazu jako usługę każdego agenta, ponieważ Recipe go nie ustawia, więc to polecenie musi działać nieprzerwanie i musi obsługiwać żądania, jeśli ma być możliwe dotarcie do crew. Adres, trasę i odpowiedź określa program.
Poniższe uruchomienie użyło takiego obrazu: programu crew w klasycznym układzie CrewAI — crew.py budującego crew z dwóch plików deklaracji, tak jak odczytał je import — oraz, jako polecenia obrazu, małego, własnego serwera HTTP programu na porcie 8000, który uruchamia crew raz dla każdego POST /kickoff. Należy zbudować obraz w katalogu głównym projektu, wpisać jego nazwę w miejsce ghcr.io/example/support-brief:1.0.0 dla obu agentów w src/support_brief/import-answers.yaml i ponownie zaimportować z --sync, co zapisuje nowe odpowiedzi w szkicach i ponownie wykonuje pull; następnie uruchomić kompilację:
docker build -t support-brief:local .aggrega import src/support_brief --syncaggrega build --release release.yamlGdy obie odpowiedzi to support-brief:local, synchronizacja wymienia, wśród wypisywanych wierszy, dwie wartości, które zmieniła:
changed spec.components.researcher.infra.image in release.yamlchanged spec.components.writer.infra.image in release.yamlNastępnie należy ustawić klucz w powłoce i uruchomić stack:
export OPENAI_API_KEY='your OpenAI key'docker compose -p support-brief -f dist/compose/docker-compose.yaml up -d --wait-p nadaje nazwę projektowi, jak wyjaśnia krok uruchamiania w Jak przebiega import.
Testowanie
Poniższe żądanie dociera do programu, który uruchamia obraz z tego przewodnika: crew za małym serwerem HTTP na porcie 8000, odpowiadającym na POST /kickoff. Własny program sam decyduje o swojej trasie i odpowiedzi. Należy je wysłać do badacza pod http://127.0.0.1:8000, adres publikowany przez published_port, gdy program już nasłuchuje, kilka sekund po uruchomieniu stosu:
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]"}Uruchomienie ustawiło OPENAI_API_KEY na wartość zastępczą, więc odpowiedzią jest odmowa OpenAI, przekazana dalej przez program. Żądanie crew dotarło do API OpenAI z kluczem dostarczonym przez kompilację. Oba agenty uruchamiają ten sam obraz, więc żądanie mogło trafić do dowolnego z nich: autor odpowiada tak samo pod http://127.0.0.1:8001.
Stack zatrzymuje się poleceniem:
docker compose -p support-brief -f dist/compose/docker-compose.yaml downNa Kubernetes należy importować z --target helm i wypchnąć obraz do rejestru, z którego pobiera klaster, podając go w src/support_brief/import-answers.yaml. Następnie należy utworzyć obiekt Secret openai-api-key i zastosować kompilację, jak opisuje krok uruchamiania w Jak przebiega import. Deployment każdego agenta nie ma obiektu Service, więc należy przekierować port lokalny na port researchera. Polecenie działa, dopóki się go nie zatrzyma:
kubectl port-forward deploy/researcher 8000:8000Forwarding from 127.0.0.1:8000 -> 8000Forwarding from [::1]:8000 -> 8000Z innego terminala należy wysłać to samo żądanie na przekierowany 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]"}