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

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:

Terminal window
aggrega scaffold --example import-crewai

Depois, 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:

Terminal window
cd import-crewai

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

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-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, 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:

Terminal window
cd source

Executar a importação

Indique o diretório da equipa. 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, lista o que escreveu:

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

Na 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 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 a partir do 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 ficheiros escritos, e uma notificação indica que a importação gerou 3 ficheiros em rascunho, reconhecidos como crewai.

  • A linha info indica as respostas que os rascunhos para Docker Compose não usam, guardadas no ficheiro de respostas para uma compilação para Kubernetes.
  • As linhas mapped indicam 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 de core/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 choice indicam 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 faz aggrega pull, para release.lock, para que os rascunhos sejam validados e compilados de imediato. Com --offline, a importação não obtém nada e indica o comando aggrega pull a 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 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 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/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, é 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/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 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

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

A Release em rascunho aberta no editor depois de validada, com a saída do Aggrega e uma notificação a indicarem, ambas, que não foram encontrados problemas.

A compilação da Release em rascunho: aparece uma pasta dist no Explorador, a saída do Aggrega lista o ficheiro do Docker Compose escrito e uma notificação indica que foi escrito 1 ficheiro.

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>/dist

A 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:
- compose

O 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:

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

Com 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.yaml
changed spec.components.writer.infra.image in release.yaml

Depois, defina a chave na 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 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:

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

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

Em 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:

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

Noutro terminal, envie o mesmo pedido para a porta reencaminhada:

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