Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Importare un progetto CrewAI

Questa guida passo passo importa le dichiarazioni di agenti e task di un progetto CrewAI — una crew di due agenti che risponde alla domanda di un cliente sui piani di assistenza — ed esegue la build della crew per Docker Compose. L’importazione abbozza ogni file che la build legge: entrambi gli agenti e il loro modello, la chiave che ciascuno presenta al modello come riferimento a una variabile, e le realizzazioni di ciascuno. Chiede una sola volta l’unico valore che nessuna dichiarazione contiene, l’immagine in cui gira il programma della crew. Ogni file e ogni blocco di output riportati di seguito provengono da un’esecuzione reale; le dichiarazioni e ogni fase della guida si trovano nell’esempio import-crewai, dove uno script di controllo esegue di nuovo l’importazione, confronta ciò che scrive, ciò che stampa e i blocchi citati in questa pagina con i file conservati lì, e valida ed esegue la build di ciò che l’importazione ha scritto.

Generare l’esempio

Puoi eseguire questa importazione con i comandi di questa pagina, oppure farla eseguire al tuo assistente AI.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example import-crewai

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella; quello successivo, qui sotto, ti porta nella cartella source della nuova cartella, che contiene ciò che questa pagina importa ed è dove viene eseguita l’importazione:

Terminal window
cd import-crewai

La cartella source dell’esempio generato aperta in Visual Studio Code, che mostra la configurazione degli agenti della crew con un ricercatore e uno scrittore.

Il progetto

Un progetto CrewAI conserva il comportamento della sua crew in un programma e dichiara i suoi agenti e i suoi task in file di configurazione. Questo, scritto per questa guida, segue la struttura classica di CrewAI, e l’importazione legge i suoi due file di dichiarazione, in src/support_brief/config/. Il programma — il crew.py di un progetto classico, gli strumenti che definisce — non viene mai letto, quindi l’esempio contiene solo le dichiarazioni.

agents.yaml dichiara i due agenti, entrambi su gpt-4o-mini di 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 assegna un task a ciascuno:

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

Nella radice del progetto, un file .aggrega-config.yaml rende la cartella un’area di lavoro:

# 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

L’importazione fa riferimento ai Components di agente e di modello del catalogo, e --target abbozza un Manifest a partire dalle Recipes del catalogo. Lo spazio di lavoro non indica alcuna cartella di catalogo, quindi l’importazione legge il catalogo della libreria standard dal registry da cui recupera il proprio importer: uno snapshot firmato del catalogo pubblicato, che la prima importazione recupera, verifica e conserva nella cache dei contenuti dello spazio di lavoro, e che il record scritto dall’importazione accanto alle sue bozze indica tramite il suo digest. Uno spazio di lavoro che indica le proprie cartelle di catalogo — in AGGREGA_CATALOG_DIRS, oppure sotto workspace.catalog_dirs — importa invece rispetto a quelle.

Cosa chiede l’importazione

Le dichiarazioni indicano il modello di ciascun agente, mai l’immagine in cui gira il programma della crew: quell’immagine la costruisci tu a partire dal tuo progetto. Per questo l’importazione la chiede, una volta per ogni agente. A un terminale pone una domanda per ciascuno e scrive le risposte nelle bozze e nel file delle risposte, import-answers.yaml, all’interno della directory che importa, src/support_brief/, così la successiva importazione le legge da lì e non chiede nulla. Senza un terminale — nell’integrazione continua, o attraverso una pipe — non chiede nulla: scrive il file con le chiavi vuote e si ferma, indicando il file. L’esempio contiene già il file, con entrambi gli agenti sulla stessa immagine, ghcr.io/example/support-brief:1.0.0, che sta per l’immagine che costruisci tu:

# 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"

Le due risposte origin servono per una build per Kubernetes, con --target helm: lì ogni agente legge la chiave OpenAI da un Secret di Kubernetes, e la risposta è il nome del Secret, openai-api-key, mai la chiave. Una build per Docker Compose legge invece la chiave dalla tua shell, quindi questa importazione non usa quelle risposte. Il file delle risposte dell’importazione descrive il file, le domande e le regole per la risposta relativa a un segreto.

aggrega import elenca ogni flag accettato dal comando, tra cui --answers, che indica un file delle risposte conservato altrove.

Entra in source:

Terminal window
cd source

Eseguire l’importazione

Indica la directory della crew. L’importazione legge le dichiarazioni che contiene e nient’altro:

Terminal window
aggrega import src/support_brief --target compose

Sullo standard output elenca ciò che ha scritto:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Sullo standard error, dove <workspace> sta per la cartella in cui l’hai eseguita:

[… 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)

L’importazione eseguita dall’editor: l’Aggregate, la Release e il Manifest in bozza compaiono accanto al progetto della crew, l’output di Aggrega elenca come sono stati mappati ciascun agente, modello e task e i file scritti, e una notifica indica che l’importazione ha prodotto 3 file in bozza, riconosciuti come crewai.

  • La riga info indica le risposte che le bozze per Docker Compose non usano, conservate nel file delle risposte per una build per Kubernetes.
  • Le righe mapped dicono che ogni agente è un’istanza dell’agente CrewAI della libreria standard, core/ai-agent/crewai, e che il modello indicato da entrambi, openai/gpt-4o-mini, è un’istanza di core/ai-model/openai. La loro fascia è NONE: l’importazione CrewAI fa riferimento a questi Components in base a ciò che le dichiarazioni nominano, un agente e un fornitore di modelli, anziché confrontare ciascuno con il catalogo.
  • Le righe made no choice dicono che per i task non viene abbozzato nulla: un task è logica che il programma della crew esegue.
  • La riga Pull complete è l’import che recupera ciò da cui dipende la Release generata in bozza, come fa aggrega pull, in release.lock, così che le bozze si validino e si compilino subito. Con --offline l’import non recupera nulla e indica il comando aggrega pull da eseguire.

Cosa scrive

L’Aggregate, la Release e il Manifest si chiamano imported/support-brief: config/agents.yaml e config/tasks.yaml di un progetto non danno nome a nessuna crew — il suo nome si trova nel programma, che l’importazione non legge — quindi un’importazione di questi file come directory prende il nome dalla directory, support_brief, scritto come segmento di nome, nel namespace definito dall’impostazione target_namespace dell’importatore, imported a meno che tu non ne imposti un altro (Impostazioni).

aggregate.yaml — un’istanza per agente, ciascuna collegata al modello che nomina, con la chiave che presenta dichiarata sulla connessione, e il modello, con in apertura commenti che dicono che cosa è stato letto e che cosa no:

# 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 e backstory sono riportati come dichiarati, compreso l’a capo con cui termina ogni blocco ripiegato. log_level è DEBUG per l’agente researcher, dichiarato verbose, e INFO per l’agente writer, che non lo è. Un agente che non dichiara allow_delegation viene abbozzato con false. Il modello è un servizio ospitato, quindi il Component dell’agente rifiuta una connessione verso di esso che non porti alcuna credenziale; ogni connessione ne dichiara una, sotto la chiave OPENAI_API_KEY.

release.yaml — l’ambiente, l’immagine e la porta pubblicata di ciascun agente, e da dove proviene ciascuna chiave:

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: {}

L’ambiente, development, è un valore predefinito che l’importazione scrive perché nessuna dichiarazione ne indica uno; cambialo dove la Release viene distribuita altrove. Ogni immagine è la risposta che l’importazione ha letto da import-answers.yaml. Ogni agente è pubblicato sull’indirizzo di loopback della tua macchina e inoltra alla porta su cui ascolta il suo programma, infra.port, 8000 se non la imposti: il ricercatore sulla 8000 e il redattore sulla 8001, poiché due servizi di una stessa Release non possono pubblicare la stessa porta. Le dichiarazioni non indicano alcuna variabile per la chiave, quindi ogni connessione la legge da ${OPENAI_API_KEY}, la variabile che leggono le librerie client di OpenAI, come riferimento a una variabile e mai come valore.

manifest.yaml — la Recipe Compose di ciascun tipo e la realizzazione che scrive tale e quale nel file Compose il riferimento alla variabile di una chiave:

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 registra, per digest, le entità del catalogo in cui la Release si è risolta, e .aggrega-import.json è il registro di ciò che l’importazione ha scritto, che un successivo aggrega import --sync legge.

Convalidare e compilare

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

La Release in bozza aperta nell’editor dopo averla validata, con l’output di Aggrega e una notifica che segnalano entrambi che non sono stati trovati problemi.

La build della Release in bozza: nell’Explorer compare una cartella dist, l’output di Aggrega elenca il file Docker Compose scritto e una notifica indica che è stato scritto 1 file.

La convalida stampa:

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)

e la build, dove <workspace> indica la cartella in cui l’hai eseguita:

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

La riga notice è informativa: la Feature del segreto accetta il suo origin dai values dell’Aggregate o dall’infra della Release, e l’avviso segnala che una foglia è dichiarata in entrambi. Non cambia alcun verdetto.

Il servizio del ricercatore in dist/compose/docker-compose.yaml; quello del redattore differisce solo nel nome, nei valori che portano le sue variabili e nella porta che pubblica:

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

L’agente riceve l’indirizzo del modello e il suo nome come OPENAI_BASE_URL e MODEL, le variabili da cui CrewAI li legge, e la chiave come OPENAI_API_KEY. Il suo ruolo, l’obiettivo, la storia pregressa, l’interruttore di delega e il livello di log arrivano con i nomi che il Component di CrewAI assegna loro per impostazione predefinita, perché il programma della crew li legga; un blocco inject: sul componente stesso consegna invece uno qualsiasi di essi con il nome che legge il programma. Ogni valore redatto dall’importazione conserva l’a capo con cui terminava la sua dichiarazione, quindi il file lo scrive come blocco. Il modello non riceve un servizio proprio: gli agenti raggiungono l’API di OpenAI al suo indirizzo. La chiave è un riferimento a variabile, riempito dalla tua shell all’avvio dello stack. Ogni servizio pubblica la sua porta soltanto su 127.0.0.1: la 8000 del ricercatore e la 8001 del redattore, ciascuna inoltrata alla porta 8000 del programma all’interno del suo container.

Con un assistente AI

Un assistente AI configurato con gli strumenti di Aggrega può fare lo stesso: incollaci questo prompt.

Usa solo gli strumenti di Aggrega e non creare alcuna cartella da solo. Se la cartella del Workspace non contiene ancora una cartella `import-crewai`, chiama una volta lo strumento `scaffold` con `example` impostato su `import-crewai` e senza `dir`: scrive l’esempio in una nuova cartella `import-crewai`, la cui cartella `source` contiene ciò che questa pagina importa. Poi chiama lo strumento `import` con `workspace_root` impostato su `import-crewai/source`, `source` impostato su `src/support_brief` e `target` impostato su `compose`: legge le risposte di cui ha bisogno da `import-answers.yaml` all’interno della cartella `src/support_brief`, scrive le sue bozze in `import-crewai/source` e scarica ciò di cui hanno bisogno. Poi chiama lo strumento `validate` con `workspace_root` impostato su `import-crewai/source` e `release` impostato su `release.yaml`, e lo strumento `build` con `workspace_root` impostato su `import-crewai/source`, `release` impostato su `release.yaml` e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `import-crewai/source/dist/`.

Aprilo in VS Code

Con l’estensione Aggrega per Visual Studio Code installata, apri in VS Code la cartella import-crewai/source, dove l’importazione ha scritto le sue bozze. La cartella contiene una sola Release, il release.yaml in bozza, quindi l’editor la seleziona per te e controlla le bozze rispetto a quella Release mentre le modifichi, segnalando ciò che trova nel file e nel pannello Problemi. Aggrega: Show topology graph, nel riquadro comandi, disegna i componenti della Release e le connessioni tra di essi. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull agiscono sulla stessa Release, e ciascuno è anche un pulsante nel pannello Commands della vista Aggrega nella barra delle attività; Build scrive i suoi file in dist/ all’interno della cartella. Usare Aggrega in Visual Studio Code tratta il resto.

Esecuzione

L’immagine la costruisci tu a partire dal progetto, con un tuo Dockerfile. Docker Compose esegue il comando proprio dell’immagine come servizio di ciascun agente, poiché la Recipe non ne imposta alcuno, quindi quel comando deve restare in esecuzione, e deve servire richieste se vuoi raggiungere la crew. Il tuo programma decide l’indirizzo, la route e la risposta.

L’esecuzione seguente ha usato un’immagine di questo tipo: il programma della crew nel layout classico di CrewAI — un crew.py che costruisce la crew dai due file di dichiarazione, così come l’importazione li ha letti — e, come comando dell’immagine, un piccolo server HTTP proprio del programma sulla porta 8000, che esegue la crew una volta per ogni POST /kickoff. Costruisci la tua immagine nella radice del progetto, scrivi il suo nome al posto di ghcr.io/example/support-brief:1.0.0 per entrambi gli agenti in src/support_brief/import-answers.yaml e importa di nuovo con --sync, che scrive le nuove risposte nelle bozze ed esegue di nuovo il pull; poi esegui la build:

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

Con support-brief:local come entrambe le risposte, la sincronizzazione indica i due valori che ha modificato, tra le righe che stampa:

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

Poi imposta la chiave nella tua shell e avvia lo stack:

Terminal window
export OPENAI_API_KEY='your OpenAI key'
docker compose -p support-brief -f dist/compose/docker-compose.yaml up -d --wait

-p assegna il nome al progetto, come spiega il passo di esecuzione di Come si svolge un’importazione.

Eseguire il test

La richiesta qui sotto raggiunge il programma eseguito dall’immagine di questa guida: la crew dietro un piccolo server HTTP sulla porta 8000, che risponde a POST /kickoff. Il tuo programma decide da sé route e risposta. Inviala al ricercatore su http://127.0.0.1:8000, l’indirizzo che published_port pubblica, quando il programma è in ascolto, pochi secondi dopo l’avvio dello stack:

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

L’esecuzione ha impostato OPENAI_API_KEY su un segnaposto, quindi la risposta è il rifiuto di OpenAI, inoltrato dal programma. La richiesta della crew ha raggiunto l’API di OpenAI con la chiave fornita dalla build. Entrambi gli agenti eseguono la stessa immagine, quindi la richiesta poteva andare all’uno o all’altro: il redattore risponde allo stesso modo su http://127.0.0.1:8001.

Arresta lo stack con:

Terminal window
docker compose -p support-brief -f dist/compose/docker-compose.yaml down

Su Kubernetes, importa con --target helm e invia l’immagine a un registry da cui il tuo cluster esegue il pull, indicandola in src/support_brief/import-answers.yaml. Poi crea il Secret openai-api-key e applica la build, come descrive il passo di esecuzione di Come si svolge un’importazione. Il Deployment di ciascun agente non ha alcun Service, quindi inoltra una porta locale a quella del researcher. Il comando resta in esecuzione finché non lo interrompi:

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

Da un altro terminale, invia la stessa richiesta alla porta inoltrata:

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