Importar um projeto CrewAI
Este guia passo a passo importa as declarações de agentes e tarefas de um projeto CrewAI — uma equipa de dois agentes que responde à pergunta de um cliente sobre planos de suporte — e compila a equipa para Docker Compose. A importação gera como rascunho cada ficheiro que o build lê: os dois agentes e o respetivo modelo, a chave que cada um apresenta ao modelo como referência de variável, e as realizações de cada um. Pergunta uma única vez pelo único valor que nenhuma declaração contém, a imagem em que o programa da equipa é executado. Cada ficheiro e cada bloco de saída abaixo provêm de uma execução real; as declarações e cada etapa do guia estão no exemplo import-crewai, onde um script de verificação volta a executar a importação, compara o que ela escreve, o que imprime e os blocos que esta página cita com os ficheiros aí guardados, e valida e compila o que a importação escreveu.
Gerar o exemplo
É possível executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example import-crewaiDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta; o seguinte, abaixo, entra na pasta source da nova pasta, que contém o que esta página importa e é onde a importação é executada:
cd import-crewai
O projeto
Um projeto CrewAI guarda o comportamento da sua equipa num programa e declara os seus agentes e as suas tarefas em ficheiros de configuração. Este, escrito para este guia, segue a estrutura clássica do CrewAI, e a importação lê os seus dois ficheiros de declaração, em src/support_brief/config/. O programa — o crew.py de um projeto clássico, as ferramentas que define — nunca é lido, pelo que o exemplo contém apenas as declarações.
agents.yaml declara os dois agentes, ambos no gpt-4o-mini da 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 atribui uma tarefa a cada um:
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: writerNa raiz do projeto, um .aggrega-config.yaml torna a pasta um espaço de trabalho:
# 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.aiA importação referencia os Components de agente e de modelo do catálogo, e --target gera como rascunho um Manifest a partir das Recipes do catálogo. O espaço de trabalho não indica nenhuma pasta de catálogo, pelo que a importação lê o catálogo da biblioteca padrão a partir do registry de onde obtém o seu importador: um snapshot assinado do catálogo publicado, que a primeira importação obtém, verifica e guarda na cache de conteúdo do espaço de trabalho, e que o registo que a importação escreve junto aos seus rascunhos indica pelo seu digest. Um espaço de trabalho que indique as suas próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS, ou em workspace.catalog_dirs — importa antes com base nessas pastas.
O que a importação pergunta
As declarações indicam o modelo de cada agente, nunca a imagem em que o programa da crew é executado: essa imagem é construída a partir do seu projeto. Por isso, a importação pede-a, uma vez para cada agente. Num terminal, faz uma pergunta para cada um e escreve as respostas nos rascunhos e no ficheiro de respostas, import-answers.yaml, dentro do diretório que importa, src/support_brief/, de modo que a importação seguinte as lê daí e não pergunta nada. Sem terminal — em integração contínua, ou através de um pipe — não pergunta nada: escreve o ficheiro com as chaves vazias e para, indicando o ficheiro. O exemplo já contém o ficheiro, com ambos os agentes na mesma imagem, ghcr.io/example/support-brief:1.0.0, que representa a imagem que se constrói:
# 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"As duas respostas origin destinam-se a uma compilação para Kubernetes, com --target helm: aí cada agente lê a chave da OpenAI de um Secret do Kubernetes, e a resposta é o nome do Secret, openai-api-key, nunca a chave. Uma compilação para Docker Compose lê antes a chave da shell, pelo que esta importação não usa essas respostas. O ficheiro de respostas da importação descreve o ficheiro, as perguntas e as regras para a resposta de um segredo.
aggrega import lista todas as flags que o comando aceita, entre elas --answers, que indica um ficheiro de respostas guardado noutro local.
Entre em source:
cd sourceExecutar a importação
Indique o diretório da equipa. A importação lê as declarações que ele contém e nada mais:
aggrega import src/support_brief --target composeNa saída padrão, lista o que escreveu:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa saída de erro padrão, com <workspace> a representar a pasta em que a executou:
[… 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)
- A linha
infoindica as respostas que os rascunhos para Docker Compose não usam, guardadas no ficheiro de respostas para uma compilação para Kubernetes. - As linhas
mappedindicam que cada agente é uma instância do agente CrewAI da biblioteca padrão,core/ai-agent/crewai, e que o modelo que ambos nomeiam,openai/gpt-4o-mini, é uma instância decore/ai-model/openai. O nível deles éNONE: a importação do CrewAI referencia estes Components pelo que as declarações nomeiam, um agente e um fornecedor de modelos, em vez de comparar cada um com o catálogo. - As linhas
made no choiceindicam que não é gerado nenhum rascunho para as tarefas: uma tarefa é lógica que o programa da equipa executa. - A linha
Pull completeé a importação a obter aquilo de que a Release rascunhada depende, como fazaggrega pull, pararelease.lock, para que os rascunhos sejam validados e compilados de imediato. Com--offline, a importação não obtém nada e indica o comandoaggrega pulla executar.
O que a importação escreve
O Aggregate, a Release e o Manifest chamam-se imported/support-brief: os ficheiros config/agents.yaml e config/tasks.yaml de um projeto não nomeiam nenhuma crew — o nome dela está no programa, que a importação não lê — pelo que uma importação do respetivo diretório recebe o nome do diretório, support_brief, escrito como segmento de nome, no namespace que a definição target_namespace do importador estabelece, imported, salvo se definir outro (Definições).
aggregate.yaml — uma instância por agente, cada uma ligada ao modelo que nomeia, com a chave que apresenta declarada na ligação, e o modelo, abrindo com comentários que indicam o que foi lido e o que não foi:
# 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 e backstory são transportados tal como declarados, incluindo a quebra de linha com que termina cada bloco dobrado. log_level é DEBUG para o investigador, declarado verbose, e INFO para o redator, que não o é. Um agente que não declara allow_delegation é gerado como rascunho com false. O modelo é um serviço alojado, pelo que o Component do agente recusa uma ligação a ele que não transporte nenhuma credencial; cada ligação declara uma, sob a chave OPENAI_API_KEY.
release.yaml — o ambiente, a imagem e a porta publicada de cada agente e a origem de cada chave:
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: {}O ambiente, development, é uma predefinição que a importação escreve porque nenhuma declaração indica um; altere-o onde a Release for implementada noutro local. Cada imagem é a resposta que a importação leu de import-answers.yaml. Cada agente é publicado no endereço de loopback da máquina, reencaminhando para a porta em que o seu programa escuta, infra.port, 8000 se não for definida: o investigador na 8000 e o redator na 8001, uma vez que dois serviços de uma mesma Release não podem publicar a mesma porta. As declarações não indicam nenhuma variável para a chave, pelo que cada ligação a lê de ${OPENAI_API_KEY}, a variável que as bibliotecas cliente da OpenAI leem, como referência a uma variável e nunca como valor.
manifest.yaml — a Recipe do Compose de cada tipo e a realização que escreve no ficheiro Compose a referência à variável de uma chave tal como está escrita:
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 regista, por digest, as entidades do catálogo para as quais a Release foi resolvida, e .aggrega-import.json é o registo do que a importação escreveu, que um aggrega import --sync posterior lê.
Validar e compilar
aggrega validate --release release.yamlaggrega build --release release.yaml

A validação 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)e o build, com <workspace> a representar a pasta onde o executou:
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>/distA linha notice é apenas informativa: a Feature de segredo aceita o seu origin dos values do Aggregate ou da infra da Release, e a notificação informa que uma folha está declarada em ambos. Não altera nenhum veredicto.
O serviço do investigador em dist/compose/docker-compose.yaml; o do redator difere apenas no nome, nos valores que as suas próprias variáveis transportam e na porta 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: - composeO agente recebe o endereço e o nome do modelo como OPENAI_BASE_URL e MODEL, as variáveis a partir das quais o CrewAI os lê, e a chave como OPENAI_API_KEY. O seu papel, objetivo, história de fundo, interruptor de delegação e nível de registo chegam com os nomes que o Component do CrewAI lhes atribui por predefinição, para o programa da equipa os ler; um bloco inject: no próprio componente entrega, em vez disso, qualquer um deles com o nome que o programa lê. Cada valor que a importação redigiu mantém a quebra de linha com que a sua declaração terminava, pelo que o ficheiro o escreve como um bloco. O modelo não recebe um serviço próprio: os agentes chegam à API da OpenAI no endereço dela. A chave é uma referência de variável, preenchida a partir da shell quando a stack arranca. Cada serviço publica a sua porta apenas em 127.0.0.1: a 8000 do investigador e a 8001 do redator, cada uma reencaminhada para a porta 8000 do programa dentro do seu contentor.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole nele este prompt.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do Workspace ainda não contiver uma pasta `import-crewai`, chame uma vez a ferramenta `scaffold` com `example` definido como `import-crewai` e sem `dir`: esta escreve o exemplo numa nova pasta `import-crewai`, cuja pasta `source` contém o que esta página importa. Depois, chame a ferramenta `import` com `workspace_root` definido como `import-crewai/source`, `source` definido como `src/support_brief` e `target` definido como `compose`: esta lê as respostas de que precisa em `import-answers.yaml`, dentro da pasta `src/support_brief`, escreve os seus rascunhos em `import-crewai/source` e obtém aquilo de que estes precisam. Depois, chame a ferramenta `validate` com `workspace_root` definido como `import-crewai/source` e `release` definido como `release.yaml`, e a ferramenta `build` com `workspace_root` definido como `import-crewai/source`, `release` definido como `release.yaml` e `write` definido como true. Indique-me que ficheiros a compilação escreveu; estão em `import-crewai/source/dist/`.Abrir no VS Code
Com a extensão do Aggrega para Visual Studio Code instalada, abra no VS Code a pasta import-crewai/source, onde a importação escreveu os seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, pelo que o editor a seleciona automaticamente e verifica os rascunhos face a essa Release à medida que são editados, assinalando o que encontra no ficheiro e no painel Problemas. Aggrega: Show topology graph, na paleta de comandos, desenha os componentes da Release e as ligações entre eles. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull atuam sobre a mesma Release, e cada um é também um botão no painel Commands da vista Aggrega na barra de atividade; o Build escreve os seus ficheiros no dist/ da pasta. Utilizar o Aggrega no Visual Studio Code trata do resto.
Execução
A imagem é construída a partir do projeto, com um Dockerfile próprio. O Docker Compose executa o comando da própria imagem como serviço de cada agente, uma vez que a Recipe não define nenhum, pelo que esse comando tem de continuar em execução, e tem de atender pedidos se quiser chegar à crew. O seu programa decide o endereço, a rota e a resposta.
A execução abaixo usou uma imagem desse tipo: o programa da crew na estrutura clássica do CrewAI — um crew.py que constrói a crew a partir dos dois ficheiros de declaração, tal como a importação os leu — e, como comando da imagem, um pequeno servidor HTTP do próprio programa na porta 8000, que executa a crew uma vez por cada POST /kickoff. Construa a sua imagem na raiz do projeto, escreva o nome dela no lugar de ghcr.io/example/support-brief:1.0.0 para ambos os agentes em src/support_brief/import-answers.yaml e volte a importar com --sync, que escreve as novas respostas nos rascunhos e volta a fazer o pull; depois, faça o build:
docker build -t support-brief:local .aggrega import src/support_brief --syncaggrega build --release release.yamlCom support-brief:local como ambas as respostas, a sincronização nomeia os dois valores que alterou, entre as linhas que imprime:
changed spec.components.researcher.infra.image in release.yamlchanged spec.components.writer.infra.image in release.yamlDepois, defina a chave na shell e inicie a stack:
export OPENAI_API_KEY='your OpenAI key'docker compose -p support-brief -f dist/compose/docker-compose.yaml up -d --wait-p dá nome ao projeto, como explica o passo de execução de Como decorre uma importação.
Testar
O pedido abaixo chega ao programa que a imagem deste guia executa: a crew por trás de um pequeno servidor HTTP na porta 8000, que responde a POST /kickoff. O programa de cada utilizador decide a sua própria rota e resposta. Envie-o ao investigador em http://127.0.0.1:8000, o endereço que published_port publica, assim que o programa estiver à escuta, alguns segundos depois de a stack arrancar:
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]"}A execução definiu OPENAI_API_KEY com um valor provisório, pelo que a resposta é a recusa da OpenAI, transmitida pelo programa. O pedido da crew chegou à API da OpenAI com a chave que a compilação entregou. Ambos os agentes executam a mesma imagem, pelo que o pedido podia ir para qualquer um deles: o redator responde da mesma forma em http://127.0.0.1:8001.
Pare a stack com:
docker compose -p support-brief -f dist/compose/docker-compose.yaml downEm Kubernetes, importe com --target helm e envie a imagem para um registo a partir do qual o seu cluster obtém imagens, indicando-a em src/support_brief/import-answers.yaml. Em seguida, crie o Secret openai-api-key e aplique a compilação, como descreve o passo de execução de Como decorre uma importação. O Deployment de cada agente não tem Service, pelo que deve reencaminhar uma porta local para a do researcher. O comando fica em execução até o parar:
kubectl port-forward deploy/researcher 8000:8000Forwarding from 127.0.0.1:8000 -> 8000Forwarding from [::1]:8000 -> 8000Noutro terminal, envie o mesmo pedido para a porta reencaminhada:
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]"}