crewai

CrewAI エキスパートスキル

CrewAI は、役割ベースのマルチエージェントオーケストレーションのためのフレームワークです。低レベルのステートマシングラフを扱う LangGraph とは異なり、CrewAI はより高度な抽象化を提供します。エージェントは役割、目標、背景情報を持つものとして定義され、クルーは組み込みの逐次または階層型ワークフローで構成され、エージェント間の委任機能がフレームワークに組み込まれています。

中核となるパラダイム

from crewai import Agent, Task, Crew, Process
from crewai.tools import tool

@tool("search")
def search_web(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

researcher = Agent(
    role="Senior Researcher",
    goal="Find accurate information on any topic",
    backstory="Expert researcher with 10 years of experience",
    tools=[search_web],
    verbose=True,
)

writer = Agent(
    role="Technical Writer",
    goal="Write clear reports from research findings",
    backstory="Experienced technical writer",
    verbose=True,
)

research_task = Task(
    description="Research the topic thoroughly",
    expected_output="A detailed research brief",
    agent=researcher,
)

write_task = Task(
    description="Write a report based on research",
    expected_output="A well-structured report",
    agent=writer,
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff()

中核となる原則

1. エージェントは関数ではなく、役割です。 役割＋目標＋背景情報によって、エージェントのアイデンティティが定義されます。役割を明確に定義すると、ハルシネーションを減らせます。
2. タスクでは方法ではなく、内容を宣言します。 説明＋期待される出力でタスクが定義されます。実行方法はエージェントが判断します。
3. 逐次型はパイプラインに、階層型は複雑なタスクに適しています。 逐次型ではタスクを順番に実行します。階層型ではマネージャーエージェントが委任と検証を行います。
4. 階層型にはマネージャー LLM が必要です。 manager_llm がないと、階層型プロセスはエラーを通知せずに失敗します。
5. 委任ループは実際に発生します。 max_iter の上限を設定せずに allow_delegation=True にすると、引き継ぎが無限に続く可能性があります。
6. ツールのエラーは例外を発生させません。 ツール呼び出しに失敗するとタスクは失敗としてマークされますが、例外は発生しません。タスクの出力を確認してください。

どこから始めるか

すでにあるもの	ここから始める
何もない — CrewAI を試している	2 つのエージェントによる逐次型クルー（調査 → 執筆）
連携させたいエージェント	manager_llm を使って階層型クルーを構築する
統合したいツール	@tool デコレーターを使い、関連するエージェントにツールを追加する
本番環境へのデプロイ	コールバック、メモリ、エラー処理を追加する

クイックリファレンス

タスク	方法	リファレンス
エージェントを定義する	Agent(role, goal, backstory)	references/agent-design.md
タスクを定義する	Task(description, expected_output, agent)	references/task-design.md
逐次型クルー	Crew(process=Process.sequential)	references/crew-patterns.md
階層型クルー	Crew(process=Process.hierarchical, manager_llm=...)	references/crew-patterns.md
ツールを作成する	@tool("name") デコレーター	references/tool-integration.md
コールバックを追加する	Agent の step_callback=fn	references/callbacks.md
メモリを有効にする	Crew または Agent の memory=True	references/crew-patterns.md

フレームワーク選択ガイド

シナリオ	選択するもの	理由
役割ベースのマルチエージェントチーム	CrewAI	役割／目標／背景情報がネイティブの抽象化です
ステートマシン型のマルチエージェント	LangGraph	グラフトポロジー、サブグラフ、ヒューマン・イン・ザ・ループに対応します
会話型マルチエージェント	AutoGen	エージェント間のチャットをオーケストレーションの基本要素として扱います
チェーン／エージェントの構成	LangChain	汎用チェーン向けの LCEL パイプ演算子を利用できます
ドキュメントの検索／RAG	LlamaIndex	データの取り込みが主要な基本要素です

リファレンスファイル

リファレンス	読み込むタイミング	ファイル
エージェント設計	役割、目標、背景情報を持つエージェントを定義するとき	references/agent-design.md
タスク設計	説明と出力を持つタスクを作成するとき	references/task-design.md
クルーのパターン	逐次型、階層型、合意形成型のクルーを扱うとき	references/crew-patterns.md
ツール統合	@tool デコレーターを使ってツールを作成するとき	references/tool-integration.md
コールバック	エージェントとタスクの実行を監視するとき	references/callbacks.md
メモリシステム	統合メモリークラス、エージェント間のコンテキストを扱うとき	references/memory-system.md
フロー	クルーをつなぐイベント駆動型オーケストレーションを扱うとき	references/flows.md
FAQ とトラブルシューティング	よくあるエラーと解決方法を確認するとき	references/faq-and-troubleshooting.md

テンプレート

テンプレート	使用する場面	ファイル
調査クルー	逐次型：調査担当者 → 執筆者 → レビュアー	templates/research-crew.py
階層型クルー	専門エージェントを率いるマネージャー	templates/hierarchical-crew.py
カスタマーサポート	トリアージ → 専門担当者 → 回答	templates/support-crew.py

トラブルシューティング

症状	考えられる原因	解決策	参照
Crew は実行されるが出力がない	エージェントが委任ループから抜け出せない	エージェントに max_iter=15 を設定します	references/agent-design.md
階層型の Crew が失敗する	manager_llm が設定されていない	manager_llm=ChatOpenAI(model="gpt-4") を追加します	references/crew-patterns.md
タスクが完了しない	エージェントが max_iter を超過する	max_iter を増やすか、タスクを簡素化します	references/agent-design.md
ツールが呼び出されない	ツールがエージェントに追加されていない	Agent の定義に tools=[my_tool] を追加します	references/tool-integration.md
トークンの使用量が多い	階層モード	マネージャーがすべての出力を処理します — より安価な LLM を使用します	references/crew-patterns.md
タスク間のメモリが機能しない	Crew レベルのメモリが設定されていない	Crew に memory=True を追加します	references/crew-patterns.md

CrewAI を使用しないケース

• 単一エージェントのタスク — 1 つのエージェントには抽象化が過剰です
• グラフを細かく制御する必要がある場合（サイクル、条件分岐） — LangGraph を使用します
• 会話型エージェントのやり取りが必要な場合 — AutoGen を使用します
• シンプルなチェーン構成が必要な場合 — LangChain LCEL を使用します