Importar un proyecto de CrewAI
Esta guía paso a paso importa las declaraciones de agentes y tareas de un proyecto de CrewAI — una crew de dos agentes que responde a la pregunta de un cliente sobre los planes de soporte — y construye la crew para Docker Compose. La importación esboza cada archivo que lee la compilación: los dos agentes y su modelo, la clave que cada uno presenta al modelo como referencia a una variable, y las realizaciones de cada uno. Pregunta una sola vez por el único valor que ninguna declaración contiene, la imagen en la que se ejecuta el programa de la crew. Cada archivo y cada bloque de salida que aparecen a continuación provienen de una ejecución real; las declaraciones y cada etapa de la guía están en el ejemplo import-crewai, donde un script de comprobación vuelve a ejecutar la importación, compara lo que escribe, lo que imprime y los bloques que cita esta página con los archivos guardados allí, y valida y construye lo que escribió la importación.
Generar el ejemplo
Puedes ejecutar esta importación con los comandos de esta página o pedir a tu asistente de IA que la ejecute por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example import-crewaiDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva; el siguiente, más abajo, entra en la carpeta source de la carpeta nueva, que contiene lo que esta página importa y es donde se ejecuta la importación:
cd import-crewai
El proyecto
Un proyecto de CrewAI guarda el comportamiento de su crew en un programa y declara sus agentes y sus tareas en archivos de configuración. Este, escrito para esta guía, sigue la estructura clásica de CrewAI, y la importación lee sus dos archivos de declaración, en src/support_brief/config/. El programa — el crew.py de un proyecto clásico, las herramientas que define — nunca se lee, así que el ejemplo contiene solo las declaraciones.
agents.yaml declara los dos agentes, ambos sobre gpt-4o-mini de 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 asigna una tarea a cada uno:
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: writerEn la raíz del proyecto, un archivo .aggrega-config.yaml convierte la carpeta en un espacio de trabajo:
# 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.aiLa importación hace referencia a los Components de agente y de modelo del catálogo, y --target esboza un Manifest a partir de las Recipes del catálogo. El espacio de trabajo no indica ninguna carpeta de catálogo, así que la importación lee el catálogo de la biblioteca estándar desde el registro del que obtiene su importador: una instantánea firmada del catálogo publicado, que la primera importación obtiene, verifica y guarda en la caché de contenido del espacio de trabajo, y que el historial que la importación escribe junto a sus borradores nombra por su resumen criptográfico. Un espacio de trabajo que indica sus propias carpetas de catálogo — en AGGREGA_CATALOG_DIRS, o bajo workspace.catalog_dirs — importa en cambio a partir de ellas.
Qué pide la importación
Las declaraciones nombran el modelo de cada agente, nunca la imagen en la que se ejecuta el programa de la crew: esa imagen la construyes tú a partir de tu proyecto. Por eso la importación la pide, una vez por cada agente. En una terminal hace una pregunta por cada uno y escribe las respuestas en los borradores y en el archivo de respuestas, import-answers.yaml, dentro del directorio que importa, src/support_brief/, de modo que la siguiente importación las lee desde ahí y no pregunta nada. Sin terminal — en integración continua, o a través de una tubería — no pregunta nada: escribe el archivo con las claves vacías y se detiene, nombrando el archivo. El ejemplo ya contiene el archivo, con ambos agentes en la misma imagen, ghcr.io/example/support-brief:1.0.0, que representa la imagen que construyes:
# 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"Las dos respuestas origin son para una compilación para Kubernetes, con --target helm: allí cada agente lee la clave de OpenAI de un Secret de Kubernetes, y la respuesta es el nombre del Secret, openai-api-key, nunca la clave. Una compilación para Docker Compose lee en cambio la clave de tu shell, así que esta importación no usa esas respuestas. El archivo de respuestas de importación describe el archivo, las preguntas y las reglas para la respuesta de un secreto.
aggrega import enumera cada opción que admite el comando, entre ellas --answers, que nombra un archivo de respuestas guardado en otro lugar.
Entra en source:
cd sourceEjecutar la importación
Indica el directorio de la crew. La importación lee las declaraciones que contiene y nada más:
aggrega import src/support_brief --target composeEn la salida estándar enumera lo que escribió:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonEn la salida de error estándar, donde <workspace> representa la carpeta en la que la ejecutaste:
[… 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)
- La línea
infonombra las respuestas que los borradores de Docker Compose no usan, guardadas en el archivo de respuestas para una compilación para Kubernetes. - Las líneas
mappedindican que cada agente es una instancia del agente de CrewAI de la biblioteca estándar,core/ai-agent/crewai, y que el modelo que ambos nombran,openai/gpt-4o-mini, es una instancia decore/ai-model/openai. Su nivel esNONE: la importación de CrewAI hace referencia a estos Components por lo que nombran las declaraciones, un agente y un proveedor de modelos, en lugar de comparar cada uno con el catálogo. - Las líneas
made no choiceindican que para las tareas no se esboza nada: una tarea es lógica que ejecuta el programa de la crew. - La línea
Pull completees la importación obteniendo aquello de lo que depende la Release redactada, como haceaggrega pull, enrelease.lock, para que los borradores se validen y se compilen de inmediato. Con--offline, la importación no obtiene nada e indica el comandoaggrega pullque hay que ejecutar.
Lo que escribe
El Aggregate, la Release y el Manifest se llaman imported/support-brief: los archivos config/agents.yaml y config/tasks.yaml de un proyecto no nombran ningún crew — su nombre está en el programa, que la importación no lee — así que una importación de su directorio recibe el nombre del directorio, support_brief, escrito como segmento de nombre, bajo el namespace que fija el ajuste target_namespace del importador, imported salvo que fijes otro (Ajustes).
aggregate.yaml — una instancia por agente, cada una conectada al modelo que nombra, con la clave que presenta declarada en la conexión, y el modelo, con comentarios al principio que indican qué se leyó y qué 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 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 y backstory se trasladan tal como se declararon, incluido el salto de línea con el que termina cada bloque plegado. log_level es DEBUG para el agente researcher, declarado verbose, e INFO para el agente writer, que no lo está. Un agente que no declara allow_delegation se esboza con false. El modelo es un servicio alojado, así que el Component del agente rechaza una conexión hacia él que no lleve ninguna credencial; cada conexión declara una, bajo la clave OPENAI_API_KEY.
release.yaml — el entorno, la imagen y el puerto publicado de cada agente, y de dónde procede cada clave:
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: {}El entorno, development, es un valor predeterminado que la importación escribe porque ninguna declaración nombra uno; cámbialo donde la Release se despliegue en otro lugar. Cada imagen es la respuesta que la importación leyó de import-answers.yaml. Cada agente se publica en la dirección de loopback de tu máquina y reenvía al puerto en el que escucha su programa, infra.port, 8000 salvo que lo definas: el investigador en el 8000 y el redactor en el 8001, ya que dos servicios de una misma Release no pueden publicar el mismo puerto. Las declaraciones no nombran ninguna variable para la clave, así que cada conexión la lee de ${OPENAI_API_KEY}, la variable que leen las bibliotecas cliente de OpenAI, como referencia a una variable y nunca como valor.
manifest.yaml — la Recipe de Compose de cada tipo y la realización que escribe tal cual en el archivo Compose la referencia a la variable de una clave:
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 registra, por digest, las entidades del catálogo a las que se resolvió la Release, y .aggrega-import.json es el registro de lo que escribió la importación, que lee un aggrega import --sync posterior.
Validar y compilar
aggrega validate --release release.yamlaggrega build --release release.yaml

La validación imprime:
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)y la compilación, donde <workspace> representa la carpeta en la que la ejecutaste:
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>/distLa línea notice es informativa: la Feature de secreto acepta su origin desde los values del Aggregate o desde la infra de la Release, y el aviso informa de que una hoja está declarada en ambos. No cambia ningún veredicto.
El servicio del investigador en dist/compose/docker-compose.yaml; el del redactor solo difiere en su nombre, en los valores que llevan sus propias variables y en el puerto que publica:
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: - composeEl agente recibe la dirección del modelo y su nombre como OPENAI_BASE_URL y MODEL, las variables de las que CrewAI los lee, y la clave como OPENAI_API_KEY. Su rol, su objetivo, su trasfondo, su interruptor de delegación y su nivel de registro llegan con los nombres que el Component de CrewAI les da por defecto, para que los lea el programa del equipo; un bloque inject: en el propio componente entrega en su lugar cualquiera de ellos con el nombre que lee el programa. Cada valor que redactó la importación conserva el salto de línea con el que terminaba su declaración, así que el archivo lo escribe como un bloque. El modelo no obtiene ningún servicio propio: los agentes llegan a la API de OpenAI en su propia dirección. La clave es una referencia de variable, que se rellena desde tu shell cuando se inicia el stack. Cada servicio publica su puerto solo en 127.0.0.1: el 8000 del investigador y el 8001 del redactor, cada uno reenviado al puerto 8000 del programa dentro de su contenedor.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pega en él este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta del Workspace aún no contiene una carpeta `import-crewai`, llama una vez a la herramienta `scaffold` con `example` establecido en `import-crewai` y sin `dir`: escribe el ejemplo en una nueva carpeta `import-crewai`, cuya carpeta `source` contiene lo que importa esta página. Después llama a la herramienta `import` con `workspace_root` establecido en `import-crewai/source`, `source` establecido en `src/support_brief` y `target` establecido en `compose`: lee las respuestas que necesita de `import-answers.yaml`, dentro de la carpeta `src/support_brief`, escribe sus borradores en `import-crewai/source` y descarga lo que estos necesitan. Después llama a la herramienta `validate` con `workspace_root` establecido en `import-crewai/source` y `release` establecido en `release.yaml`, y a la herramienta `build` con `workspace_root` establecido en `import-crewai/source`, `release` establecido en `release.yaml` y `write` establecido en true. Dime qué archivos escribió la compilación; están en `import-crewai/source/dist/`.Ábrelo en VS Code
Con la extensión de Aggrega para Visual Studio Code instalada, abre en VS Code la carpeta import-crewai/source, donde la importación escribió sus borradores. La carpeta contiene una sola Release, el release.yaml en borrador, así que el editor la selecciona por ti y comprueba los borradores con respecto a esa Release mientras los editas, marcando lo que encuentra en el archivo y en el panel Problemas. Aggrega: Show topology graph, en la paleta de comandos, dibuja los componentes de la Release y las conexiones entre ellos. Aggrega: Build, Aggrega: Preview build y Aggrega: Pull actúan sobre la misma Release, y cada uno es también un botón del panel Commands de la vista Aggrega en la barra de actividades; Build escribe sus archivos en el dist/ de la carpeta. Usar Aggrega en Visual Studio Code cubre el resto.
Ejecución
La imagen la construyes tú a partir del proyecto, con un Dockerfile propio. Docker Compose ejecuta el comando propio de la imagen como servicio de cada agente, ya que la Recipe no establece ninguno, así que ese comando debe seguir en ejecución, y debe atender solicitudes si quieres llegar a la crew. Tu programa decide la dirección, la ruta y la respuesta.
La ejecución siguiente usó una imagen así: el programa de la crew en la estructura clásica de CrewAI — un crew.py que construye la crew a partir de los dos archivos de declaración, tal como los leyó la importación — y, como comando de la imagen, un pequeño servidor HTTP propio del programa en el puerto 8000, que ejecuta la crew una vez por cada POST /kickoff. Construye tu imagen en la raíz del proyecto, escribe su nombre en lugar de ghcr.io/example/support-brief:1.0.0 para ambos agentes en src/support_brief/import-answers.yaml e importa de nuevo con --sync, que escribe las nuevas respuestas en los borradores y vuelve a hacer el pull; luego compila:
docker build -t support-brief:local .aggrega import src/support_brief --syncaggrega build --release release.yamlCon support-brief:local como ambas respuestas, la sincronización nombra los dos valores que cambió, entre las líneas que imprime:
changed spec.components.researcher.infra.image in release.yamlchanged spec.components.writer.infra.image in release.yamlDespués establece la clave en tu shell e inicia el stack:
export OPENAI_API_KEY='your OpenAI key'docker compose -p support-brief -f dist/compose/docker-compose.yaml up -d --wait-p da nombre al proyecto, como explica el paso de ejecución de Cómo se ejecuta una importación.
Probarlo
La solicitud siguiente llega al programa que ejecuta la imagen de esta guía: la crew detrás de un pequeño servidor HTTP en el puerto 8000, que responde a POST /kickoff. Tu propio programa decide su propia ruta y respuesta. Envíala al investigador en http://127.0.0.1:8000, la dirección que publica published_port, cuando el programa esté escuchando, unos segundos después de que se inicie el stack:
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]"}La ejecución definió OPENAI_API_KEY con un valor de marcador, así que la respuesta es el rechazo de OpenAI, transmitido por el programa. La solicitud de la crew llegó a la API de OpenAI con la clave que entregó la compilación. Ambos agentes ejecutan la misma imagen, así que la solicitud podía ir a cualquiera de los dos: el redactor responde igual en http://127.0.0.1:8001.
Detén el stack con:
docker compose -p support-brief -f dist/compose/docker-compose.yaml downEn Kubernetes, importa con --target helm y sube la imagen a un registro del que tu clúster descargue imágenes, indicándola en src/support_brief/import-answers.yaml. Después crea el Secret openai-api-key y aplica la compilación, como describe el paso de ejecución de Cómo se ejecuta una importación. El Deployment de cada agente no tiene Service, así que reenvía un puerto local al del researcher. El comando se ejecuta hasta que lo detengas:
kubectl port-forward deploy/researcher 8000:8000Forwarding from 127.0.0.1:8000 -> 8000Forwarding from [::1]:8000 -> 8000Desde otra terminal, envía la misma solicitud al puerto reenviado:
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]"}