Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Importar um projeto CrewAI

Este passo a passo importa as declarações de agentes e tarefas de um projeto CrewAI — uma equipe de dois agentes que responde à pergunta de um cliente sobre planos de suporte — e compila a equipe para Docker Compose. A importação gera como rascunho cada arquivo que o build lê: os dois agentes e o modelo deles, a chave que cada um apresenta ao modelo como referência de variável, e as realizações de cada um. Ela pergunta uma única vez pelo único valor que nenhuma declaração contém, a imagem em que o programa da equipe é executado. Cada arquivo e cada bloco de saída abaixo vêm de uma execução real; as declarações e cada etapa do passo a passo estão no exemplo import-crewai, onde um script de verificação executa a importação novamente, compara o que ela grava, o que ela imprime e os blocos que esta página cita com os arquivos mantidos ali, e valida e compila o que a importação escreveu.

Gerar o exemplo

Você pode executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute para você.

Escreva o exemplo em uma nova pasta com o nome dele:

Terminal window
aggrega scaffold --example import-crewai

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova; o seguinte, abaixo, entra na pasta source da pasta nova, que contém o que esta página importa e é onde a importação é executada:

Terminal window
cd import-crewai

A pasta source do exemplo gerado aberta no Visual Studio Code, mostrando a configuração dos agentes da crew, com um pesquisador e um redator.

O projeto

Um projeto CrewAI mantém o comportamento da sua equipe em um programa e declara seus agentes e suas tarefas em arquivos de configuração. Este, escrito para este passo a passo, está no layout clássico do CrewAI, e a importação lê seus dois arquivos de declaração, em src/support_brief/config/. O programa — o crew.py de um projeto clássico, as ferramentas que ele define — nunca é lido, então 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-mini

tasks.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: writer

Na 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.ai

A 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, então a importação lê o catálogo da biblioteca padrão a partir do registro do qual obtém o seu importador: um snapshot assinado do catálogo publicado, que a primeira importação busca, verifica e guarda no cache de conteúdo do espaço de trabalho, e que o histórico que a importação escreve ao lado dos seus rascunhos indica pelo seu digest. Um espaço de trabalho que indica suas próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS, ou em workspace.catalog_dirs — importa a partir delas em vez disso.

O que a importação pergunta

As declarações indicam o modelo de cada agente, nunca a imagem em que o programa da crew roda: essa imagem você constrói a partir do seu projeto. Por isso a importação a solicita, uma vez para cada agente. Em um terminal, ela faz uma pergunta para cada um e escreve as respostas nos rascunhos e no arquivo de respostas, import-answers.yaml, dentro do diretório que importa, src/support_brief/, de modo que a próxima importação as lê de lá e não pergunta nada. Sem terminal — em integração contínua, ou por meio de um pipe — ela não pergunta nada: escreve o arquivo com as chaves vazias e para, indicando o arquivo. O exemplo já contém o arquivo, com os dois agentes na mesma imagem, ghcr.io/example/support-brief:1.0.0, que representa a imagem que você 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 são para um build para Kubernetes, com --target helm: ali 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. Um build para Docker Compose lê a chave do seu shell em vez disso, então esta importação não usa essas respostas. O arquivo de respostas da importação descreve o arquivo, 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 nomeia um arquivo de respostas mantido em outro lugar.

Entre em source:

Terminal window
cd source

Executar a importação

Indique o diretório da equipe. A importação lê as declarações que ele contém e nada mais:

Terminal window
aggrega import src/support_brief --target compose

Na saída padrão, ela lista o que gravou:

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

Na saída de erro padrão, com <workspace> representando a pasta em que você 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 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)

A importação executada pelo editor: o Aggregate, a Release e o Manifest em rascunho aparecem ao lado do projeto da crew, a saída do Aggrega lista como cada agente, modelo e tarefa foi mapeado e os arquivos gravados, e uma notificação informa que a importação gerou 3 arquivos em rascunho, reconhecidos como crewai.

  • A linha info indica as respostas que os rascunhos do Docker Compose não usam, mantidas no arquivo de respostas para um build para Kubernetes.
  • As linhas mapped dizem que cada agente é uma instância do agente CrewAI da biblioteca padrão, core/ai-agent/crewai, e que o modelo que ambos citam, openai/gpt-4o-mini, é uma instância de core/ai-model/openai. O nível deles é NONE: a importação do CrewAI referencia esses Components pelo que as declarações citam, um agente e um provedor de modelo, em vez de comparar cada um com o catálogo.
  • As linhas made no choice dizem que nenhum rascunho é gerado para as tarefas: uma tarefa é lógica que o programa da equipe executa.
  • A linha Pull complete é a importação buscando aquilo de que a Release rascunhada depende, como faz aggrega pull, em release.lock, para que os rascunhos sejam validados e compilados imediatamente. Com --offline, a importação não busca nada e indica o comando aggrega pull a executar.

O que a importação grava

O Aggregate, a Release e o Manifest se chamam imported/support-brief: os arquivos config/agents.yaml e config/tasks.yaml de um projeto não nomeiam nenhuma crew — o nome dela fica no programa, que a importação não lê — então uma importação do diretório deles recebe o nome do diretório, support_brief, escrito como segmento de nome, sob o namespace definido pela configuração target_namespace do importador, imported, a menos que você defina outro (Configurações).

aggregate.yaml — uma instância por agente, cada uma ligada ao modelo que cita, com a chave que apresenta declarada na conexão, e o modelo, abrindo com comentários que dizem 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 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 são levados como declarados, incluindo a quebra de linha com que termina cada bloco dobrado. log_level é DEBUG para o pesquisador, declarado verbose, e INFO para o redator, que não é. Um agente que não declara allow_delegation é gerado como rascunho com false. O modelo é um serviço hospedado, então o Component do agente recusa uma conexão com ele que não carregue nenhuma credencial; cada conexão declara uma, sob a chave OPENAI_API_KEY.

release.yaml — o ambiente, a imagem e a porta publicada de cada agente e de onde vem cada chave:

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

O ambiente, development, é um padrão que a importação escreve porque nenhuma declaração indica um; altere-o onde a Release for implantada em outro lugar. Cada imagem é a resposta que a importação leu de import-answers.yaml. Cada agente é publicado no endereço de loopback da sua máquina, encaminhando para a porta em que seu programa escuta, infra.port, 8000, a menos que você a defina: o pesquisador na 8000 e o redator na 8001, já 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, então cada conexã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 arquivo Compose a referência à variável de uma chave tal como está escrita:

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, por digest, as entidades do catálogo para as quais a Release foi resolvida, e .aggrega-import.json é o registro do que a importação gravou, que um aggrega import --sync posterior lê.

Validar e compilar

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

A Release em rascunho aberta no editor após validá-la, com a saída do Aggrega e uma notificação informando, ambas, que nenhum problema foi encontrado.

O build da Release em rascunho: uma pasta dist aparece no Explorer, a saída do Aggrega lista o arquivo do Docker Compose gravado e uma notificação informa que 1 arquivo foi gravado.

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> representando a pasta em que você 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>/dist

A linha notice é apenas informativa: a Feature de segredo aceita seu origin dos values do Aggregate ou da infra da Release, e a notificação informa que uma folha está declarada em ambos. Ela não altera nenhum veredito.

O serviço do pesquisador em dist/compose/docker-compose.yaml; o do redator difere apenas no nome, nos valores que suas próprias variáveis carregam 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:
- compose

O agente recebe o endereço e o nome do modelo como OPENAI_BASE_URL e MODEL, as variáveis das quais o CrewAI os lê, e a chave como OPENAI_API_KEY. O papel, o objetivo, a história de fundo, a chave de delegação e o nível de log dele chegam com os nomes que o Component do CrewAI lhes dá por padrão, para o programa da equipe 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 rascunhou mantém a quebra de linha com que sua declaração terminava, então o arquivo o escreve como um bloco. O modelo não recebe um serviço próprio: os agentes alcançam a API da OpenAI no endereço dela. A chave é uma referência de variável, preenchida a partir do seu shell quando a stack é iniciada. Cada serviço publica sua porta apenas em 127.0.0.1: a 8000 do pesquisador e a 8001 do redator, cada uma encaminhando para a porta 8000 do programa dentro do seu contêiner.

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

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`: ela grava o exemplo em uma nova pasta `import-crewai`, cuja pasta `source` contém o que esta página importa. Em seguida, chame a ferramenta `import` com `workspace_root` definido como `import-crewai/source`, `source` definido como `src/support_brief` e `target` definido como `compose`: ela lê as respostas de que precisa em `import-answers.yaml`, dentro da pasta `src/support_brief`, grava seus rascunhos em `import-crewai/source` e baixa o que eles precisam. Em seguida, 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. Diga-me quais arquivos o build gravou; eles estão em `import-crewai/source/dist/`.

Abra 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 gravou seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, então o editor a seleciona para você e verifica os rascunhos em relação a essa Release enquanto você os edita, marcando o que encontra no arquivo e no painel Problemas. Aggrega: Show topology graph, na paleta de comandos, desenha os componentes da Release e as conexõ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 visualização Aggrega na barra de atividades; o Build grava seus arquivos no dist/ da pasta. Usar o Aggrega no Visual Studio Code cobre o restante.

Execução

Você constrói a imagem a partir do projeto, com um Dockerfile próprio. O Docker Compose executa o comando da própria imagem como o serviço de cada agente, já que a Recipe não define nenhum, então esse comando precisa continuar em execução e precisa atender requisições se você quiser alcançar a crew. Seu programa decide o endereço, a rota e a resposta.

A execução abaixo usou uma imagem assim: o programa da crew no layout clássico do CrewAI — um crew.py que monta a crew a partir dos dois arquivos 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 para cada POST /kickoff. Construa sua imagem na raiz do projeto, escreva o nome dela no lugar de ghcr.io/example/support-brief:1.0.0 para os dois agentes em src/support_brief/import-answers.yaml e importe novamente com --sync, que grava as novas respostas nos rascunhos e faz o pull de novo; depois, faça o build:

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

Com support-brief:local como as duas respostas, a sincronização cita os dois valores que alterou, entre as linhas que imprime:

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

Em seguida, defina a chave no seu shell e inicie a 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 dá nome ao projeto, como explica a etapa de execução de Como uma importação é executada.

Teste

A requisição abaixo chega ao programa que a imagem deste passo a passo executa: a crew por trás de um pequeno servidor HTTP na porta 8000, que responde a POST /kickoff. O seu próprio programa decide a própria rota e a resposta. Envie-a ao pesquisador em http://127.0.0.1:8000, o endereço que published_port publica, assim que o programa estiver escutando, alguns segundos depois de a stack iniciar:

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

A execução definiu OPENAI_API_KEY como um valor provisório, então a resposta é a recusa da OpenAI, repassada pelo programa. A requisição da crew chegou à API da OpenAI com a chave que o build entregou. Os dois agentes executam a mesma imagem, então a requisição poderia ir para qualquer um deles: o redator responde da mesma forma em http://127.0.0.1:8001.

Pare a stack com:

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

No Kubernetes, importe com --target helm e envie a imagem para um registry do qual o seu cluster faça pull, indicando-a em src/support_brief/import-answers.yaml. Em seguida, crie o Secret openai-api-key e aplique o build, como descreve a etapa de execução de Como uma importação é executada. O Deployment de cada agente não tem Service, então encaminhe uma porta local para a do researcher. O comando fica em execução até você interrompê-lo:

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

Em outro terminal, envie a mesma requisição para a porta encaminhada:

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