コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

CrewAI プロジェクトをインポートする

このウォークスルーでは、CrewAI プロジェクトのエージェントとタスクの宣言(サポートプランに関する顧客の質問に答える 2 つのエージェントからなるクルー)をインポートし、クルーを 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/ の下にある 2 つの宣言ファイルを読み取ります。プログラム(クラシックプロジェクトの crew.py と、それが定義するツール)は一切読み取られないため、例には宣言だけが含まれています。

agents.yaml は 2 つのエージェントを宣言し、どちらも 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 はそれぞれに 1 つのタスクを割り当てます:

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 のプログラムが実行されるイメージは指定しません。そのイメージはプロジェクトからビルドします。そのため、インポートはエージェントごとに 1 回、イメージを尋ねます。ターミナルではエージェントごとに質問を行い、回答を下書きと、インポート対象のディレクトリ 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"

2 つの origin の回答は、--target helm による Kubernetes 向けのビルド用です。そこでは各エージェントが Kubernetes Secret から OpenAI キーを読み取り、回答はキーそのものではなく Secret の名前 openai-api-key です。Docker Compose 向けのビルドは代わりにシェルからキーを読み取るため、このインポートではこれらの回答を使いません。インポート回答ファイルでは、ファイル、質問、シークレットの回答に関するルールを説明しています。

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 の行は、インポートが、ドラフトされた Release の依存先を aggrega pull と同じように release.lock へ取得していることを示します。これにより、ドラフトはすぐに検証とビルドができます。--offline の場合、インポートは何も取得せず、実行すべき aggrega pull を示します。

書き出される内容

Aggregate、Release、Manifest の名前は imported/support-brief です。プロジェクトの config/agents.yaml と config/tasks.yaml はクルーの名前を示しません。クルーの名前はプログラムの中にあり、インポートはプログラムを読み取らないためです。そのため、これらをディレクトリとしてインポートすると、ディレクトリ名 support_brief を名前セグメントとして書き表したものが名前になります。名前空間は、インポーターの target_namespace 設定が定めるもので、別のものを設定しない限り imported です(設定)。

aggregate.yaml — エージェントごとに 1 つのインスタンス(それぞれが指定するモデルに接続され、提示するキーが接続上で宣言されます)と、そのモデル。冒頭のコメントには、何が読み取られ、何が読み取られなかったかが記されています:

# 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 の下で資格情報を 1 つ宣言します。

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 です。1 つの Release の 2 つのサービスが同じポートを公開することはできないためです。宣言はキー用の変数を指定していないため、各接続は OpenAI のクライアントライブラリが読み取る変数 ${OPENAI_API_KEY} からキーを、値ではなく変数参照として読み取ります。

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 は origin を Aggregate の values または Release の infra から受け付け、この通知は 1 つのリーフが両方で宣言されていることを報告しています。判定は何も変わりません。

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

エージェントは、モデルのアドレスと名前を、CrewAI がそれらを読み取る変数である OPENAI_BASE_URL と MODEL として受け取り、キーを OPENAI_API_KEY として受け取ります。ロール、ゴール、バックストーリー、委任スイッチ、ログレベルは、クルーのプログラムが読み取れるよう、CrewAI Component がデフォルトで付ける名前で届きます。コンポーネント自体の inject: ブロックは、それらのいずれも、代わりにプログラムが読み取る名前で渡します。インポートが下書きした各値は、宣言の末尾にあった改行を保持するため、ファイルはそれをブロックとして書き出します。モデルには独自のサービスがありません。エージェントは OpenAI API 自身のアドレスでそれにアクセスします。キーは変数参照であり、スタックの起動時にシェルから値が埋められます。各サービスはポートを 127.0.0.1 でのみ公開します。リサーチャーは 8000、ライターは 8001 で、それぞれコンテナー内のプログラムのポート 8000 に転送されます。

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。Workspace フォルダーにまだ `import-crewai` フォルダーがない場合は、`example` を `import-crewai` に設定し、`dir` を指定せずに、`scaffold` ツールを 1 回呼び出してください。これは例を新しい `import-crewai` フォルダーに書き込み、その `source` フォルダーにこのページでインポートするものが入ります。次に、`workspace_root` を `import-crewai/source`、`source` を `src/support_brief`、`target` を `compose` に設定して `import` ツールを呼び出してください。これは必要な回答を `src/support_brief` フォルダー内の `import-answers.yaml` から読み取り、下書きを `import-crewai/source` に書き込み、下書きが必要とするものをプルします。次に、`workspace_root` を `import-crewai/source`、`release` を `release.yaml` に設定して `validate` ツールを呼び出し、`workspace_root` を `import-crewai/source`、`release` を `release.yaml`、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。それらは `import-crewai/source/dist/` の下にあります。

VS Code で開く

Visual Studio Code 用の Aggrega 拡張機能をインストールした状態で、インポートが下書きを書き込んだフォルダー import-crewai/source を VS Code で開きます。このフォルダーには Release が 1 つ、下書きの 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 のプログラム(インポートが読み取ったとおりの 2 つの宣言ファイルから crew を構築する crew.py)と、イメージのコマンドとして、プログラム独自の小さな HTTP サーバー(ポート 8000 で待ち受け、POST /kickoff ごとに crew を 1 回実行する)です。プロジェクトのルートでイメージをビルドし、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 にすると、同期は出力する行の中で、変更した 2 つの値を示します:

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

次に、シェルでキーを設定してスタックを起動します:

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 に応答します。独自のプログラムでは、ルートと応答はそのプログラム自身が決めます。プログラムがリッスンを始めてから、つまりスタックの起動から数秒後に、published_port が公開するアドレス http://127.0.0.1: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]"
}

この実行では 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]"
}