【ITニュース解説】【Google】adk webでNo agents found in current folder.が発生した場合の原因と解決策

GoogleのAgent Development Kit（ADK）は、AIエージェントと呼ばれる特別なプログラムを開発するためのツール一式だ。AIエージェントとは、特定の目標を達成するために自律的に動作するソフトウェアのことで、例えばユーザーの質問に答えたり、情報を自動で収集したりするような機能を担う。このADKを使ってエージェントの開発を進めていると、初心者がよく出会うエラーメッセージの一つに「No agents found in current folder.」というものがある。このエラーがどのような状況で発生し、その根本的な原因は何か、そして具体的にどうすれば解決できるのかを、順を追って解説する。

このエラーは、通常 adk web というコマンドをターミナルやコマンドプロンプトで実行した後、ウェブブラウザで http://127.0.0.1:8000 というアドレスにアクセスした際に表示される。「Failed to load agents.」という大きな警告の下に、「To get started, run adk create-agent <agent_name> from your desired folder.」といった指示が続くのが一般的だ。http://127.0.0.1:8000 というアドレスは、あなたのコンピューター上で一時的に動作しているウェブサーバーを指し、adk web コマンドはこのローカルサーバーを起動し、開発中のエージェントを管理したり、動作をテストしたりするためのウェブベースの画面を提供している。この画面は、エージェント開発において非常に便利なインターフェースとなる。

では、なぜこのエラーメッセージが表示されてしまうのか。その最も主要な原因は、adk web コマンドが現在作業しているフォルダ、つまりコマンドを実行した場所の直下にある agents という名前の特定のフォルダを探し、その中にエージェントのプログラムファイルが存在することを期待しているからだ。もし、adk web コマンドを実行したフォルダに agents フォルダが存在しなかったり、あるいは agents フォルダはあっても、エージェントとして認識されるべきファイル（例えば、エージェントの処理内容を記述した main.py ファイルや、設定情報が書かれた agent_config.yaml ファイルなど）が含まれていなかったりすると、adk web は自分が管理すべきエージェントを見つけられず、「どこにもエージェントがないじゃないか」というメッセージを表示してしまうのだ。

また、もう一つの見落としがちな原因として、Pythonの仮想環境（Virtual Environment）が適切にアクティベートされていないことが挙げられる場合もある。Pythonの仮想環境は、それぞれのプロジェクトが必要とするPythonのバージョンやライブラリを、他のプロジェクトから独立させて管理するための仕組みだ。これにより、複数のプロジェクトで同じ名前のライブラリでも異なるバージョンを使うといった状況でも、互いに影響を与えずに開発を進めることができる。もし仮想環境をアクティベートせずに adk コマンドを実行すると、システム全体にインストールされているPythonやツールが参照されてしまい、ADKが正しく動作しなかったり、必要なツールが見つからずにエラーになったりすることがある。これは、特定の作業専用の道具箱があるのに、それを開かずに一般的な道具を使ってしまっているような状態と言える。

このエラーを解決する方法は主に二つある。一つ目の方法は、adk create-agent コマンドを使って新しいエージェントを作成することだ。例えば、あなたが開発したいエージェントの名前が「hello_world」だとすると、コマンドラインで adk create-agent hello_world と入力して実行する。このコマンドを実行すると、現在作業しているフォルダの直下に、自動的に agents という名前のフォルダが生成される。さらに、その agents フォルダの中には hello_world という名前のフォルダが作られ、その中にエージェントとして最低限必要なファイル（main.py や agent_config.yaml など）のひな形が自動的に生成される。こうしてディレクトリ構造が整えば、再度 adk web コマンドを実行したときに、ADKが agents フォルダとその中のエージェントを正しく認識し、ローカルサーバーが問題なく起動するようになる。特にエージェント開発を始める最初の一歩としては、この方法が最も簡単で確実だ。

二つ目の解決策は、もしすでに他の場所で開発済みのエージェントのフォルダがある場合、それを適切な位置に配置し直すことだ。具体的には、adk web コマンドを実行するフォルダの直下に、手動で agents という名前の新しいフォルダを作成する。そして、その agents フォルダの中に、既存のエージェントのフォルダ（例えば hello_world というエージェントのフォルダ）を丸ごと移動させるか、コピーして配置する。このようにすることで、adk web コマンドが期待する「現在作業しているフォルダの直下の agents フォルダ」というディレクトリ構造が完成し、ADKがエージェントを認識して正常に機能するようになる。重要なのは、adk web コマンドは、常に自分が実行された場所を基準として、その直下にある agents フォルダの中身を探すという動作ルールを理解しておくことだ。

どちらの解決策を選ぶにしても、Pythonの仮想環境を使用している場合は、必ず仮想環境をアクティベート（有効化）してから adk コマンドを実行することを決して忘れてはならない。macOSやLinux環境では、一般的に source venv/bin/activate のようなコマンドをターミナルで実行する。Windows環境では、venv\Scripts\activate といったコマンドを使うことが多い。これにより、adk コマンドやその他のPython関連ツールが、そのプロジェクト専用の環境設定のもとで正しく動作するようになる。仮想環境をアクティベートしないままでは、せっかく準備したADKが期待通りに動かないだけでなく、意図しない場所にインストールされているPythonライブラリが使われてしまい、予期せぬエラーや問題が発生する原因にもなりかねない。

この「No agents found in current folder.」というエラーは、一見すると少し複雑そうに思えるかもしれないが、その本質は「開発ツールが期待するファイルやフォルダが正しい場所に見つからない」というシンプルな問題に行き着く。システムエンジニアとしてソフトウェア開発を進める上で、使用するツールがどのような前提で動作するのか、そしてファイルやフォルダの配置がその挙動にどのように影響するのかを理解することは非常に重要だ。エラーメッセージは単なる問題の通知ではなく、その問題を解決するための貴重なヒントが隠されたメッセージと捉えることができる。冷静にエラーの内容を読み解き、その原因を特定する習慣を身につけることは、スムーズな開発を実現するために不可欠なスキルとなる。今回のエラーを経験することは、ディレクトリ構造の重要性や、開発ツールの基本的な動作に対する理解を深める良い機会と捉えられるだろう。