跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

导入 CrewAI 项目

本演练导入一个 CrewAI 项目的智能体和任务声明——一个由两个智能体组成、负责回答客户关于支持计划问题的团队——并为 Docker Compose 构建该团队。导入会为构建读取的每个文件生成草稿:两个智能体及其模型、每个智能体以变量引用形式提交给模型的密钥,以及各自的实现。它只询问一次那个没有任何声明包含的值,即团队程序运行所用的镜像。下面的每个文件和每段输出都来自一次真实运行;这些声明和演练的每个阶段都位于 import-crewai 示例中,其中的检查脚本会再次运行导入,将它写入的内容、打印的内容以及本页引用的各段内容与保存在那里的文件进行比较,并验证和构建导入写入的内容。

生成示例

你可以使用本页的命令运行此导入,也可以让你的 AI 助手替你运行。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example import-crewai

然后它会打印接下来要运行的命令。第一条命令进入新文件夹;其后的那条命令见下文,它进入新文件夹的 source 文件夹,该文件夹包含本页导入的内容,也是运行导入的位置:

Terminal window
cd import-crewai

在 Visual Studio Code 中打开的已生成示例的 source 文件夹,显示该 crew 的智能体配置,其中有一个研究员和一个撰稿人。

项目

CrewAI 项目将团队的行为保存在程序中,并在配置文件中声明其智能体和任务。本项目专为本演练编写,采用 CrewAI 的经典布局,导入会读取 src/support_brief/config/ 下的两个声明文件。程序——经典项目的 crew.py 及其定义的工具——从不会被读取,因此该示例只包含声明。

agents.yaml 声明了这两个智能体,二者都使用 OpenAI 的 gpt-4o-mini:

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 为每个智能体分配一个任务:

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

在项目根目录下,一个 .aggrega-config.yaml 使该文件夹成为工作区:

# 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

导入会引用目录中的智能体和模型 Components,而 --target 会根据目录中的 Recipes 起草一个 Manifest。工作区没有指定目录文件夹,因此导入会从获取其导入器的注册表中读取标准库目录:这是已发布目录的一个签名快照,由第一次导入获取、验证并保存在工作区的内容缓存中,并在导入写在其草稿旁的记录中以其摘要标明。指定了自己的目录文件夹的工作区——在 AGGREGA_CATALOG_DIRS 中,或在 workspace.catalog_dirs 下——则改为针对这些文件夹进行导入。

导入会询问什么

这些声明指定每个智能体的模型,但从不指定 crew 程序运行所在的镜像:该镜像由你从自己的项目构建。因此,导入会为每个智能体询问一次镜像。在终端中,它为每个智能体提出一个问题,并将答案写入草稿以及所导入目录 src/support_brief/ 内的答案文件 import-answers.yaml,这样下一次导入会从那里读取答案而不再询问。没有终端时——在持续集成中或通过管道——它不询问任何内容:它写入键值为空的文件,然后停止,并指出该文件。示例中已经包含该文件,两个智能体使用同一个镜像 ghcr.io/example/support-brief:1.0.0,它代表你构建的镜像:

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

两个 origin 答案用于面向 Kubernetes 的构建,即使用 --target helm 时:在那里,每个智能体从 Kubernetes Secret 中读取 OpenAI 密钥,答案是该 Secret 的名称 openai-api-key,而绝不是密钥本身。面向 Docker Compose 的构建则从你的 shell 中读取密钥,因此本次导入不使用这些答案。导入答案文件描述了该文件、各个问题以及机密答案的规则。

aggrega import 列出了该命令接受的每个标志,其中包括 --answers,它指定保存在其他位置的应答文件。

进入 source:

Terminal window
cd source

运行导入

指定团队所在的文件夹。导入只读取其中的声明,不读取其他任何内容:

Terminal window
aggrega import src/support_brief --target compose

它在标准输出上列出所写的内容:

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

在标准错误上,其中 <workspace> 代表你运行它的文件夹:

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

从编辑器运行的导入:草拟的 Aggregate、Release 和 Manifest 出现在该 crew 的项目旁边,Aggrega 输出列出每个智能体、模型和任务的映射方式以及写入的文件,一条通知说明导入草拟了 3 个文件,识别为 crewai。

  • info 行指出 Docker Compose 草稿未使用的答案,这些答案保留在答案文件中,供面向 Kubernetes 的构建使用。
  • mapped 行说明每个智能体都是标准库 CrewAI 智能体 core/ai-agent/crewai 的一个实例,而二者都指定的模型 openai/gpt-4o-mini 是 core/ai-model/openai 的一个实例。它们的档位显示为 NONE:CrewAI 导入根据声明中指明的内容(一个智能体和一个模型提供方)来引用这些 Components,而不是将每一项与目录进行比对。
  • made no choice 行说明任务不会被起草为任何内容:任务是团队程序所运行的逻辑。
  • Pull complete 这一行表示导入正在像 aggrega pull 那样,将草拟的 Release 所依赖的内容获取到 release.lock 中,使草稿可以立即通过验证并构建。在 --offline 下,导入不拉取任何内容,并给出需要运行的 aggrega pull。

它写出的内容

该 Aggregate、Release 和 Manifest 命名为 imported/support-brief:项目的 config/agents.yaml 和 config/tasks.yaml 没有为 crew 命名——它的名称位于程序中,而导入不读取程序——因此以目录方式导入它们时,按该目录命名,即 support_brief,写成名称段的形式,位于导入器的 target_namespace 设置所设定的命名空间下,除非你另行设置,否则该命名空间为 imported(设置)。

aggregate.yaml——每个智能体一个实例,各自连接到其指定的模型,并在连接上声明其出示的密钥,另有该模型本身,开头的注释说明了读取了什么、未读取什么:

# 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 和 backstory 按声明原样承载,包括每个折叠块末尾的换行符。log_level 对于声明了 verbose 的研究员为 DEBUG,对于未声明的撰写者为 INFO。未声明 allow_delegation 的智能体在草稿中取值 false。模型是托管服务,因此智能体的 Component 会拒绝指向该模型且不携带凭据的连接;每个连接都在键 OPENAI_API_KEY 下声明一个凭据。

release.yaml——环境、每个智能体的镜像和发布的端口,以及每个密钥的来源:

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

环境 development 是导入写入的默认值,因为没有任何声明指定环境;当 Release 部署到其他地方时,请修改它。每个镜像都是导入从 import-answers.yaml 中读取的答案。每个智能体都发布在你机器的回环地址上,并转发到其程序监听的端口 infra.port,未设置时为 8000:研究员在 8000 上,撰稿人在 8001 上,因为同一个 Release 的两个服务不能发布同一个端口。声明没有为密钥指定变量,因此每个连接都从 ${OPENAI_API_KEY}(OpenAI 客户端库读取的变量)读取密钥,作为变量引用,而绝不是值。

manifest.yaml——每种类型的 Compose Recipe,以及将密钥的变量引用按原样写入 Compose 文件的实现:

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 按摘要记录该 Release 解析到的目录实体,.aggrega-import.json 则是导入所写内容的记录,之后的 aggrega import --sync 会读取它。

验证并构建

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

验证后在编辑器中打开的草拟 Release,Aggrega 输出和一条通知都报告未发现问题。

草拟 Release 的构建:资源管理器中出现一个 dist 文件夹,Aggrega 输出列出写入的 Docker Compose 文件,一条通知说明已写入 1 个文件。

验证打印:

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)

以及构建,其中 <workspace> 代表你运行它的文件夹:

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

notice 行仅供参考:机密 Feature 从 Aggregate 的 values 或 Release 的 infra 接受其 origin,该通知报告有一个叶节点在两者中都有声明。它不会改变任何判定结果。

研究员的服务位于 dist/compose/docker-compose.yaml 中;撰稿人的服务仅在名称、其自身变量所携带的值以及它发布的端口上不同:

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

智能体以 OPENAI_BASE_URL 和 MODEL(CrewAI 读取这些信息所用的变量)接收模型的地址和名称,并以 OPENAI_API_KEY 接收密钥。它的角色、目标、背景故事、委派开关和日志级别以 CrewAI Component 默认赋予的名称送达,供团队的程序读取;组件本身上的 inject: 块则改以程序读取的名称交付其中任意一项。导入所起草的每个值都保留其声明结尾的换行符,因此文件将其写为块。模型没有自己的服务:智能体通过 OpenAI API 自身的地址访问它。密钥是一个变量引用,在栈启动时从你的 shell 中填充。每个服务只在 127.0.0.1 上发布其端口:研究员的 8000 和撰稿人的 8001,各自转发到其容器内程序的端口 8000。

借助 AI 助手

配置了 Aggrega 工具的 AI 助手也可以完成同样的操作:将下面的提示词粘贴给它。

只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `import-crewai` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `import-crewai`,且不设 `dir`:它会把示例写入一个新的 `import-crewai` 文件夹,其中的 `source` 文件夹包含本页导入的内容。然后调用 `import` 工具,将 `workspace_root` 设为 `import-crewai/source`,`source` 设为 `src/support_brief`,`target` 设为 `compose`:它会从 `src/support_brief` 文件夹内的 `import-answers.yaml` 读取所需的回答,把草稿写入 `import-crewai/source`,并拉取草稿所需的内容。然后调用 `validate` 工具,将 `workspace_root` 设为 `import-crewai/source`,`release` 设为 `release.yaml`;再调用 `build` 工具,将 `workspace_root` 设为 `import-crewai/source`,`release` 设为 `release.yaml`,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `import-crewai/source/dist/` 下。

在 VS Code 中打开

安装 Aggrega 的 Visual Studio Code 扩展后,在 VS Code 中打开文件夹 import-crewai/source,导入就把草稿写在这里。该文件夹只包含一个 Release,即草拟的 release.yaml,因此编辑器会替你选中它,并在你编辑草稿时对照该 Release 检查它们,把发现的问题标记在文件中和“问题”面板中。命令面板中的 Aggrega: Show topology graph 会绘制该 Release 的组件及它们之间的连接。Aggrega: Build、Aggrega: Preview build 和 Aggrega: Pull 作用于同一个 Release,并且每一个也是活动栏中 Aggrega 视图的 Commands 面板上的一个按钮;Build 把文件写入该文件夹的 dist/。其余内容见 在 Visual Studio Code 中使用 Aggrega。

运行

镜像由你使用自己的 Dockerfile 从项目构建。由于 Recipe 没有设置命令,Docker Compose 会把镜像自身的命令作为每个智能体的服务来运行,因此该命令必须持续运行;如果你想访问该 crew,它还必须处理请求。地址、路由和回复都由你的程序决定。

下面的运行使用了这样一个镜像:采用 CrewAI 经典布局的 crew 程序——一个按导入所读取的方式、从两个声明文件构建 crew 的 crew.py——以及作为镜像命令的、该程序自带的一个小型 HTTP 服务器,监听 8000 端口,对每个 POST /kickoff 运行一次 crew。在项目根目录构建你的镜像,在 src/support_brief/import-answers.yaml 中为两个智能体将 ghcr.io/example/support-brief:1.0.0 替换为该镜像的名称,然后使用 --sync 再次导入,它会把新的答案写入草稿并再次拉取;然后构建:

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

以 support-brief:local 作为两个答案时,同步会在它打印的各行中列出它更改的两个值:

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

然后在你的 shell 中设置密钥并启动栈:

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

-p 为项目命名,正如 导入如何运行 中的运行步骤所解释的那样。

测试

下面的请求会到达本演练镜像运行的程序:位于端口 8000 上一个小型 HTTP 服务器之后的 crew,它响应 POST /kickoff。你自己的程序会自行决定其路由和回复。在程序开始监听后,即栈启动几秒之后,将请求发送给位于 http://127.0.0.1:8000 的研究员,即 published_port 发布的地址:

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

本次运行将 OPENAI_API_KEY 设为一个占位值,因此回复是 OpenAI 对它的拒绝,由程序转发。crew 的请求带着构建所提供的密钥到达了 OpenAI API。两个智能体运行同一个镜像,因此请求可以发往其中任意一个:撰稿人在 http://127.0.0.1:8001 上以同样的方式应答。

使用以下命令停止该栈:

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

在 Kubernetes 上,使用 --target helm 导入,并将镜像推送到你的集群可以拉取的镜像仓库,在 src/support_brief/import-answers.yaml 中填写其名称。然后创建 Secret openai-api-key 并应用构建结果,如 导入如何运行 中的运行步骤所述。每个智能体的 Deployment 都没有 Service,因此请将一个本地端口转发到 researcher 的端口。该命令会一直运行,直到你停止它:

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

在另一个终端中,向转发的端口发送同样的请求:

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