CrewAIの使い方｜Pythonでマルチエージェントを組む手順

※この記事にはプロモーションが含まれます

「マルチエージェント」という言葉をよく見かけるようになったので、PythonでいちばんよくおすすめされているCrewAIをちゃんと調べてみました。

普段はClaude APIやOpenAI APIを直接呼んで、プロンプトを順番につなげることが多いです。ただ、それだと「役割ごとにAIを分けて協力させる」ような構成を組むとき、毎回自前で配線することになります。CrewAIはそこを肩代わりしてくれるフレームワークらしいので、基本の書き方を自分用にまとめておきます。

この記事でわかること

CrewAIの基本概念（Agent / Task / Crew / Flow）の関係
uvとCLIを使ったプロジェクトの作り方
1ファイルで動くCrewの最小構成と、Claudeをつなぐ方法
Flowsで処理の順番や分岐を決める書き方
2026年時点で知っておきたい注意点（hierarchicalモードの既知の問題、セキュリティ修正など）

CrewAIとは？Agent・Task・Crew・Flowの関係
インストールとプロジェクト作成（uv + CLI）
1. YAML派とJSONIC派がある問題
1ファイルで書くCrewの基本
1. 押さえておきたいポイント
Flowsで処理の順番や分岐を決める
使う前に知っておきたい注意点
まとめ

CrewAIとは？Agent・Task・Crew・Flowの関係

CrewAIは、役割を持ったAIエージェントを「チーム（Crew）」として動かすためのオープンソースのPythonフレームワークです。もともとはJoão Moura氏が作ったもので、今はCrewAI Inc.が開発しています。

登場する概念は大きく4つです。

Agent：役割（role）、目標（goal）、背景設定（backstory）を持つエージェント。「リサーチ担当」「ライター」のように人の役職っぽく定義します
Task：エージェントにやらせる仕事。説明（description）と期待する出力（expected_output）を書きます
Crew：AgentとTaskの組み合わせ。どの順番で、どう協力させるかを決めます
Flow：Crewや普通のPython処理をつなぐ、イベント駆動のワークフロー。状態（state）も持てます

自分なりにざっくり分けると、Crewは「エージェントにある程度おまかせする部分」、Flowは「人間がきっちり手順を決める部分」という役割分担です。最初はCrewだけで十分ですが、本番っぽく作るならFlowで外枠を固めるのが今の推奨パターンらしいです。

開発ペースはかなり速く、執筆時点（2026年11月）では1.15系です。PyPIの履歴を見ると、ほぼ毎週のように正式版やdev版が出ています。ネットの解説記事は、書かれた時期によって書き方がけっこう違うので注意が必要です。これは後でもう少し触れます。

インストールとプロジェクト作成（uv + CLI）

CrewAIはパッケージ管理にuvを前提にしているようです。uvは自分も使ったことがあって、pipより速くて気に入っているので、ここは素直にうれしいところです。

uv tool install crewai
crewai create crew my_crew
cd my_crew
crewai install
crewai run

crewai create crew でプロジェクトのひな形ができます。途中で使うLLMプロバイダーやAPIキーを聞かれ、.env に書き込まれる流れです。Pythonは3.10以上が必要で、上限バージョンも決まっているので、新しすぎるPythonを使っている人は公式のインストールページを確認したほうがよさそうです。

YAML派とJSONIC派がある問題

調べていて少し混乱したのがここです。少し前までの定番は、config/agents.yaml と config/tasks.yaml にエージェントとタスクを書き、@CrewBase デコレーターを付けたクラスから読み込む構成でした。ネットの解説記事もほとんどがこの形です。

ところが、2026年9月の1.15.21あたりで「JSONファーストのcrewプロジェクト」に関するドキュメントが追加されたようです。最新のQuickstartでは、crew.jsonc を load_crew() で読み込む書き方に変わっています。

from pathlib import Path
from crewai.project import load_crew


def kickoff_content_crew(inputs: dict):
    crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
    return crew.kickoff(inputs={**default_inputs, **inputs})

Flowの公式ガイドには今も @CrewBase を使ったYAML方式が載っているようなので、どちらかが即廃止というわけではないっぽいです。正直、crew.jsonc のスキーマはまだちゃんと追えていません。なので、この記事では仕組みが一番わかりやすい「Pythonコードで直接定義する」書き方で進めます。

あと細かい話ですが、CLIは crewai-cli という別パッケージにも切り出されているようです。PyPIの説明によると、共通部品の crewai-core は入るけれど、フレームワーク本体は入らない構成だそうです。CI上でCLIだけ使いたいときに便利なのかもしれません。

1ファイルで書くCrewの基本

CLIのひな形を使わなくても、uv add crewai したプロジェクトなら1ファイルで動かせます。題材は「AWSのサービス名を渡すと、コスト削減のポイントを調べて初心者向けにまとめる」2人チームにしてみました。

余談ですが、自分はLambdaでAWSの日次コストを集計してWebページに出すところまで作って、表示部分を3か月ほど放置しています。こういう解説生成をくっつけたら少しは見栄えがよくなるかな、と思いながら書いています。

from crewai import Agent, Task, Crew, Process, LLM

llm = LLM(model="anthropic/claude-sonnet-4-5", temperature=0.3)  # モデル名は使えるものに合わせて

researcher = Agent(
    role="AWSコスト調査担当",
    goal="{service} のコストが膨らみやすいポイントを具体的に洗い出す",
    backstory="AWSの料金体系に詳しく、請求書を読むのが好きなエンジニア",
    llm=llm,
    verbose=True,
)

writer = Agent(
    role="テクニカルライター",
    goal="調査結果を初心者にもわかる日本語にまとめる",
    backstory="専門用語をかみ砕いて説明するのが得意なブロガー",
    llm=llm,
)

research_task = Task(
    description="{service} でコストが増えやすい原因と対策を3つ挙げてください",
    expected_output="原因と対策のペアを3つ、箇条書きで",
    agent=researcher,
)

write_task = Task(
    description="調査結果をもとに、初心者向けの短い解説文を書いてください",
    expected_output="400字程度の日本語の文章",
    agent=writer,
    context=[research_task],  # ここ注意：前のタスク結果を渡すならcontextで明示
)

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

result = crew.kickoff(inputs={"service": "AWS Lambda"})
print(result.raw)

APIキーは環境変数 ANTHROPIC_API_KEY に入れておけば読まれるようです。OpenAIを使う場合は OPENAI_API_KEY を設定して、モデル指定を openai/... にします。"プロバイダー/モデル名" 形式で切り替えられるのは楽ですね。

押さえておきたいポイント

{service} のような波括弧は、kickoff(inputs=...) の値で置き換えられます。role・goal・descriptionのどこにでも使えます
expected_output は意外と大事です。ここがふんわりしていると、出力もふんわりしがちと言われています
Process.sequential はタスクを上から順に実行します。もう一つの Process.hierarchical は、マネージャー役のエージェントが仕事を振り分けるモードです（ただし後述の注意点あり）

backstoryに設定を盛るほどキャラが立つのは、ちょっと楽しいです。ただ、盛った分だけプロンプトが長くなってトークンを消費するので、ほどほどがよさそうです。

Flowsで処理の順番や分岐を決める

Crewだけだと、「どのタイミングで何を実行するか」をLLMにまかせる部分が大きくなります。そこで、処理の骨組みをPythonで書けるのがFlowです。@start() が入口、@listen() が「あるメソッドが終わったら動く」、@router() が分岐です。

from pydantic import BaseModel
from crewai.flow.flow import Flow, listen, start, router


class CostState(BaseModel):
    service: str = ""
    monthly_cost: float = 0.0
    report: str = ""


class CostReportFlow(Flow[CostState]):

    @start()
    def load_cost(self):
        self.state.service = "AWS Lambda"
        self.state.monthly_cost = 42.5  # 本当はCost Explorerなどから取る想定

    @router(load_cost)
    def check_threshold(self):
        if self.state.monthly_cost > 30:
            return "high"
        return "normal"

    @listen("high")
    def explain_with_crew(self):
        result = crew.kickoff(inputs={"service": self.state.service})
        self.state.report = result.raw

    @listen("normal")
    def skip(self):
        self.state.report = "今月は問題なし"


flow = CostReportFlow()
flow.kickoff()
print(flow.state.report)

（crew は前のセクションで作ったものを使う想定です）

この書き方のいいところは、「コストが閾値を超えたときだけLLMを呼ぶ」という判断をPython側で確定できることです。LLMの呼び出しはお金がかかるので、呼ばなくていい場面を普通のif文で切れるのは地味にありがたいです。

stateはPydanticモデルで型を付けられます。型なしの辞書（self.state["city"] のような形）でも書けますが、個人的には型付きのほうが後で読み返したときに迷わないかなと思います。

なお、最新のQuickstartでは from crewai.flow import Flow, listen, start という短いimportになっています。古い記事の crewai.flow.flow と混在していますが、調べた範囲ではどちらも見かけました。新しく書くなら公式の最新の書き方に合わせるのが無難そうです。

ちなみにFlowには、状態の永続化（SQLiteベースの保存）や、チェックポイント機能もあるようです。途中から再開したり、ある時点から分岐させたりできるらしいです。ここは便利そうですが、自分はまだ概要しか追えていないので、深掘りは別の機会に回します。

使う前に知っておきたい注意点

いいところばかり書くのもあれなので、調べていて気になった点もメモしておきます。

hierarchicalモードには既知の問題がある

hierarchicalモードのマネージャーエージェントが、タスクを適切なエージェントに振り分けずに順番どおり実行してしまうことがあるという報告があります。「マネージャーが賢く仕事を振ってくれる」構成に期待して組む場合は、実際の挙動を確認したほうがよさそうです。個人的には、最初はsequentialとFlowの分岐で組むほうが予測しやすいかなと思っています。

トークン消費が多くなりがち

エージェント同士がやり取りする分、単発でAPIを呼ぶよりトークンを使いやすいです。複雑なCrewほどコストが膨らむという声は多いです。AWSのコストを監視する仕組みを作っている人間が、LLMのコストで泣くのは避けたいところです。最初は安いモデルで動作確認するのがよさそうです。

セキュリティ修正とバージョンの追従

CrewAIに関するセキュリティ上の問題が複数報告されています。対応として、Code Interpreterツールは削除され、allow_code_execution は非推奨になりました。古い記事のサンプルにコード実行系の設定が出てきても、今はそのまま使えない、あるいは使うべきではない可能性があります。

リリースが速いのはいいことですが、裏を返すと「半年前の記事のコードが動かない」がふつうに起こりえます。pyproject.toml でバージョンを固定しておくのは必須っぽいです。

まとめ

CrewAIは「役割を持ったエージェントのチーム（Crew）」と「手順を固めるワークフロー（Flow）」の2本柱
uvとCLIでプロジェクトを作るのが基本。設定ファイルはYAML方式に加えて、最近はJSONIC方式も出てきている
Crewは Agent → Task → Crew → kickoff() の流れで書ける。LLMは "プロバイダー/モデル名" で切り替えられる
hierarchicalモードの挙動、トークンコスト、バージョンの追従には注意