フレームワーク

CrewAI 実践ガイド:マルチ Agent 协作を“ブロック組み立て”のように書く

GitHub で 5.7 万 Star を誇るマルチ Agent オーケストレーションフレームワーク CrewAI は、役割分担とタスク連鎖で複雑な协作をわずか数十行に圧縮する。本記事では中核となる抽象化、Process メカニズム、そして LangGraph / AutoGen との違いを解剖する。

文字サイズ

GitHub で 5.7 万 Star を集める crewAIInc/crewAI は、なかなか興味深いプロジェクトだ。ステートマシンの書き方を指南してくれるわけでもなく、対話の哲学を語ってくれるわけでもない。マルチ Agent 协作を 3 つの概念に圧縮している:Agent(役割を持つ LLM 呼び出し)、Task(依存関係を持つタスク)、Crew(チーム)。さらに Process パラメータで実行方式を決める。フレームワーク全体の感触としては、プログラムを書くというより設定ファイルを書いている感覚に近い。

何を解決するのか

単一の Agent では、長いタスクチェーンに直面すると次の 3 つの壁にぶつかってしまう:

  • コンテキストウィンドウの破裂:調査→分析→執筆という流れを 1 つのプロンプトに詰め込むと、token がパンクする
  • プランニング能力の崩壊:複雑なタスクを分解させようとすると、LLM が手順をすっ飛ばす
  • ツール呼び出しの混乱:検索・計算・ファイル書き込みが混在し、1 つでも失敗すれば全部が壊れる

AutoGen は対話型寄りで、Agent 同士はチャット履歴でつながっていくため制御粒度が粗い。LangGraph はグラフ型で柔軟だが、まずステートマシン設計を習得する必要がある。CrewAI はその中間を行く──役割分担+タスク連鎖で、Python か YAML で宣言するだけで動く。本質は、マルチ Agent 协作を「ステートマシンを書く」から「YAML を書く」へとグレードダウンさせた点にある。

使い方

pip install crewai でインストールし、OpenAI または Anthropic の API Key を用意する。最小例は以下のとおり:Researcher と Writer を定義し、連携させてブログ記事を書かせる。

from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool
import os

os.environ["OPENAI_API_KEY"] = "your-key"
os.environ["SERPER_API_KEY"] = "your-serper-key"

search_tool = SerperDevTool()

researcher = Agent(
    role="研究员",
    goal="搜集某主题的最新行业数据",
    backstory="你是一名资深行业分析师,擅长从公开资料中提炼关键数字",
    tools=[search_tool],
    verbose=True
)

writer = Agent(
    role="撰稿人",
    goal="把数据写成 500 字短报告",
    backstory="你是一名科技媒体编辑,文风简洁、结论先行",
    verbose=True
)

task1 = Task(
    description="搜索 2024 年中国 AI Agent 行业的融资数据",
    expected_output="5 条关键融资事件,每条含公司名、金额、投资方",
    agent=researcher
)

task2 = Task(
    description="基于上面的数据,写一篇 500 字的行业短评",
    expected_output="中文短评,结构清晰,含数据引用",
    agent=writer,
    context=[task1]
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[task1, task2],
    process=Process.sequential
)

result = crew.kickoff()
print(result)

実行すると、Researcher がまず検索ツールを呼び出し、その結果を Writer に渡す。context=[task1] の 1 行が肝で、上流 Task の出力が自動で下流 Agent のコンテキストに注入される。手動管理は不要で、32 行の Python でフロー全体が動く。

内部構造

中核となる抽象は 4 層に分かれる。

1. Agent:role + goal + backstory + tools + llm という構成で、「人设」を持った LLM 呼び出しユニット。backstory は飾りではなく system prompt に組み込まれ、Agent の行動スタイルに影響する。

2. Task:description + expected_output + agent + context で構成。context はリスト形式で、どの上流 Task に依存するかを明示し、その出力が本 Task のプロンプトへ注入される。タスク間の結果受け渡しは context フィールド任せだ。

3. Crew:Agent と Task をまとめ、Process を割り当てて実行方式を決める入れ物。

4. Process:3 種類ある──

  • sequential:順次実行、最もよく使われる
  • hierarchical:Manager Agent を動的に生成して委譲させる。つまり「管理職-実行者」の 2 層組織を内蔵している
  • async:並列 / 非同期で起動する

最も掘り下げたいのは hierarchical モードだ。起動時に Manager LLM を動的に spawn し、どの Task をどの Agent に、いつ実行させるかを判断させる。要するに CrewAI は「プロジェクトマネジメント」層をフレームワークに焼き込んでいる──ユーザはスケジューラーを自前実装する必要がなく、スイッチをオンにするだけだ。ただし代償は明確で、LLM 呼び出しが 1 回分増え、token コストはほぼ倍になる。小規模タスクではオフにすべき。

長所と短所

良いところ:

  • YAML と Python の両方で宣言可能。ステートマシンに不慣れな人にも取っつきやすい
  • 5.7 万 Star でコミュニティも活発、issue への反応も早い
  • hierarchical モードがそのまま使えるため、スケジューリングロジックを自前で書かずに済む

悪いところ:

  • 国産(中華系)モデルへの対応は LLM wrapper を自前で書く必要があり、公式ドキュメントも薄い
  • 長いタスクチェーンのデバッグ時、コンテキスト受け渡しの経路が不透明で、問題切り分けが面倒
  • LangGraph と比較すると、グラフ制御や条件分岐が弱く、複雑な業務ロジックは Process の 3 つのモードに縛られてしまう
  • ツール呼び出しはサポートしているが、Function Calling のエラー処理がやや粗い

横並びで比較するとこうだ:LangGraph は柔軟だがグラフ設計は自前。AutoGen は対話型だがタスク境界が曖昧。CrewAI はその中間に位置し、体感としてはブロック組み立てに近い。ただし天井は低くなる。

実際に試してみた

3 Agent のシナリオを回した:Researcher が資料検索 → Analyst がデータ整理 → Writer がレポート作成、sequential モード、すべて gpt-4o-mini 使用。

実測値:

  • 起動から初回出力まで約 12 秒(LLM 呼び出し 3 回分を含む)
  • 総 token 消費 約 4500 tokens(ツール呼び出しは含まず)
  • コード量:32 行の Python

単一 Agent に「検索→分析→執筆」を直接プロンプトしたケースと比較:単一 Agent ならコードは 8 行で済むが、出力品質は明確に劣る──分析ステップを飛ばしがちだし、Writer フェーズでデータを誤る。マルチ Agent の分離はたしかに品質向上に寄与する。ただし前提として、LLM の性能が十分に高いことが条件だ。

踏みやすい落とし穴:

  • hierarchical モードでは Manager Agent のぶん LLM 呼び出しが 1 回増え、token コストはほぼ倍になる
  • verbose=True のデフォルト出力はかなり冗長なので、本番環境では必ずオフにする
  • ツール呼び出しが失敗した際のリトライ機構が弱いため、外側でリトライ層を被せておくのが無難

向いているケース

おすすめ:

  • マルチ Agent の Demo / POC を素早く組みたいチーム
  • 業務フローが自然と「分業协作」になる形態(調査-分析-執筆、要件-開発-テストなど)
  • ステートマシンやコンテキスト管理をゼロから書きたくないエンジニア

向かないケース:

  • 細かい条件分岐やループ制御が必要な複雑なロジック(→ LangGraph へ)
  • コストにシビアな高頻度呼び出しシナリオ(マルチ Agent = LLM 呼び出しが倍数化する)
  • 国産モデル中心のプロジェクト(カスタム LLM 适配層を書く覚悟がない限り)
  • 本番レベルの長チェーンタスク(デバッグの可観測性が不十分)

CrewAI のポジショニングは明快だ:マルチ Agent のハードルを極力下げること。最強のフレームワークではないが、30 分で動かせるものとしては最有力だろう。シナリオが「複数の Agent が分業して 1 つの仕事をする」なら試す価値あり。「複雑な条件分岐+状態管理」が必要なら、素直に LangGraph に進むのが正解。


参考:crewAIInc/crewAI - GitHub

出典: https://github.com/crewAIInc/crewAI