CrewAIにおける「No tool found with name」ValueErrorの修正方法

エラーメッセージ

マルチエージェントシステムが思考を開始した直後にクラッシュすることほど、ストレスがたまることはありません。エージェントがアクションを実行しようとした直後に、以下のようなトレースバックが表示されることがあります。

ValueError: No tool found with name 'search_tool'. Make sure you have registered the tool correctly.

なぜこのエラーが発生するのか？

CrewAIは実行コンテキストに対して厳格です。単純なラッパーとは異なり、エージェントと、そのエージェントが使用を許可されているツールの間には、直接的なリンクが必要です。このエラーは、LLMが特定のツールの使用を決定したものの、そのツールがローカルレジストリに登録されていない場合に発生します。

通常、以下の3つのいずれかが原因です。

ツールはスクリプト内に存在するが、Agentコンストラクタに渡されていない。
実際のツールオブジェクトではなく、文字列（名前）のリストを渡してしまった。
カスタムの@toolデコレータで設定した名前と、エージェントが想定している名前に不一致がある。

修正方法 1: エージェントにツールを明示的に登録する

最も頻繁な原因は、エージェント定義への登録漏れです。ツールをグローバルに定義しただけでは、エージェントが自動的にアクセスできるようにはなりません。toolsパラメータを使用して、明示的に渡す必要があります。

誤った方法:

from crewai import Agent
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

# ここではエージェントは search_tool を認識できません
researcher = Agent(
  role='リサーチャー',
  goal='2024年のAIトレンドを調査する',
  backstory='熟練のリサーチャー',
  verbose=True
)

正しい方法:

from crewai import Agent
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

# ツールオブジェクトをリストに含めて渡します
researcher = Agent(
  role='リサーチャー',
  goal='2024年のAIトレンドを調査する',
  backstory='熟練のリサーチャー',
  verbose=True,
  tools=[search_tool] # これによりオブジェクトがエージェントに紐付けられます
)

修正方法 2: 文字列ではなくオブジェクトを渡す

CrewAIは List[BaseTool] を期待しており、List[str] ではありません。tools=['search_tool'] のように渡そうとすると、エージェントは失敗します。エージェントは文字列の名前を、自分自身で実行可能な関数に解決することはできません。

# 誤り: これにより ValueError が発生します
agent = Agent(..., tools=['search_tool'])

# 正解: インスタンスを渡します
search_tool = SerperDevTool()
agent = Agent(..., tools=[search_tool])

修正方法 3: カスタムツール名の不一致を解消する

@toolデコレータを使用する場合、関数名がツールのユニークIDになります。デコレータ内で名前を手動で上書きした場合は、LLMがその正確な名前を認識していることを確認する必要があります。ここでタイポ（打ち間違い）が1つあるだけで、実行ループは中断されます。

from langchain.tools import tool

@tool("web_search_api")
def my_custom_search(query: str):
    """Web検索に便利です。"""
    return "検索結果..."

# ツールは "my_custom_search" ではなく "web_search_api" として登録されます
researcher = Agent(
    role='アナリスト',
    tools=[my_custom_search],
    verbose=True
)

修正方法 4: タスクレベルのツール割り当てを確認する

CrewAI v0.28.0以降では、特定のタスクにツールを制限することができます。タスクの説明で明示的に、割り当てられたエージェントが持っていないツールを要求した場合、システムがクラッシュすることがあります。確実を期すために、Taskレベルでもツールが利用可能であることを確認してください。

task1 = Task(
  description='特定のAIスタートアップ5社を検索する',
  expected_output='名前のリスト',
  agent=researcher,
  tools=[search_tool] # このタスクにツールを明示的に許可します
)

検証: ヘルスチェックの実行

修正を確認するには、クルーを開始する前に print 文を追加します。これにより、エージェントが想定通りにツールを「認識」しているかどうかを確認できます。

スクリプトに print(f"Agent Tools: {researcher.tools}") を追加します。
コードを実行します。[<SerperDevTool name='search_tool'>] のようなオブジェクトのリストが表示されるはずです。
ログを確認します。verbose=True の場合、Action: search_tool に続いて Observation が表示されるはずです。ループが継続すれば、マッピングは成功です。

予防のためのプロのヒント

環境をクリーンに保ちましょう。pip install --upgrade crewai crewai-tools を実行して、古いバージョンのバグに悩まされないようにしてください。カスタムツールでは常に説明的な docstring を使用してください。CrewAI はこれらの docstring を使用して、いつ、どのようにツールを使用すべきかを LLM に伝えます。これにより、レジストリに存在しないツール名を LLM が「捏造（ハルシネーション）」するのを防ぐことができます。