この記事で伝えたいこと（ポイント）

はじめに

この記事はGoogle がOSSとして提供しているOSS、Agent Development Kitでエージェント開発を行う際に必要な概念を整理したものです。
公式ドキュメントは、Agent Development Kitにまとまっていますが

実際に読んでエージェントを開発しようとすると概念が多いためになかなか開発に着手できないことが多いため
この記事では、ADKの概念を整理し、エージェント開発に必要な知識をまとめていきます。

所感：Google ADKを使ってみての感想

まずは最初に所感ですが、エージェント開発においてGoogle ADKは非常に強力なツールだと思いました。
その一方で使い方が難しいという印象も受けました。

なお、筆者はこういった新しい技術を学ぶときはgetting_startedあたりのドキュメントを読んで
実際に触るようにしています。

それからadk_samples - pythonのコードを読んでいくわけですが、気軽に試せるサンプルコードではないことが多く、最初は戸惑いました。※そもそもどうやって作るとイイの？という疑問が浮かぶ一方です。

ということで作り方から順番に内容を整理していきたいと思います。

ADKを使ったアプリのリポジトリ構造

最初にadk_samples - pythonのコードを読んでみましょう。

結論から先に説明すると、ADKを使ったエージェントはagentsディレクトリを起点にして作成されます。
そして、エージェント毎にディレクトリがあり、それらはagentsディレクトリの中に格納されています。

エージェントのディレクトリにはエージェントをデプロイ・評価・テストするためのディレクトリも含まれています。
ディレクトリ構造としては以下のとおりです。※説明に不要なファイル・フォルダは省略しています。

adk-samples
└── agents
    ├── academic-research
    │   ├── README.md
    │   ├── academic_research #実際に動作するエージェントのディレクトリ
    │   │   ├── __init__.py
    │   │   ├── agent.py
    │   │   ├── tools # エージェントが使うツールを定義するディレクトリ
    │   │   └── sub_agents # エージェントが呼ぶ他のエージェントを保存するディレクトリ
    │   │       ├── academic_newresearch
    │   │       │   ├── __init__.py
    │   │       │   ├── agent.py
    │   │       └── academic_websearch
    │   │           ├── __init__.py
    │   │           ├── agent.py
    │   ├── deployment # 今回は細かく扱わない
    │   │   ├── deploy.py
    │   │   └── test_deployment.py
    │   ├── eval # 今回は細かく扱わない
    │   │   ├── data
    │   │   │   └── seminal.test.json
    │   │   └── test_eval.py
    │   └── tests # 今回は細かく扱わない
    │       └── test_agents.py

以上のように、ADKを使ったエージェント開発ではエージェントのコードとその周辺のコードがディレクトリ構造で整理されています。

ちなみにPythonに知見のある人であれば、ADKにおいてエージェントはモジュールとして実装されていることがわかると思います。たとえば、academic_researchはルートモジュールであり、その下にさらにサブモジュールとして
academic_newresearchやacademic_websearchが存在します。

ここでacademic_researchはルートエージェントと呼ばれ、academic_newresearchやacademic_websearchはサブエージェントと呼ばれます。ADKではこのルートエージェントを作成することが最初のステップとなります。

つまりはPythonに知見がある人からすると、ADKを使ったエージェント開発はPythonのモジュール開発に近い感覚で行うことができると考えられます。

deployment・eval・testsディレクトリについて

deployment、eval、testsディレクトリはそれぞれエージェントのデプロイ・評価・テストを行うためのディレクトリです。

一見して難しく感じますが、evalとtestsはPythonでよく使われるpytestを使ってテストを行うためのディレクトリになっています。evalはさておき、testsはPythonに知見のある人であれば、馴染みのあるディレクトリだと思います。

deploymentはGoogle Cloud上にエージェントをデプロイするためのディレクトリです。
このディレクトリには、エージェントをデプロイするためのコードが含まれています。

具体的には、deploy.pyというファイルがあり、これを実行することクラウド上にエージェントをデプロイできます。
academic_researchエージェントのコードを見てみると実態がよくわかります。

上記のコードにはGoogle CloudでAIエージェントをデプロイしたことのある人であれば馴染みのあるコードが書かれています。たとえば、import vertexaiはGoogle CloudのVertex AIを使うためのライブラリです。

参考：deploy.py - L22:L25

とりわけ、今回注目すべきところとしては以下の2つとなるでしょう。

from vertexai import agent_engines
from vertexai.preview.reasoning_engines import AdkApp

この2つがADKとGoogle Cloudを使ったエージェント開発のキモとなる部分ですが、今回は詳細には触れません。
次回以降にADKを使ったエージェント開発の流れを説明する際に触れていきます。

エージェントを起動する際の注意点

ADKはパッケージインストールをしたタイミングでadkというコマンドが使えるようになります。
このコマンドを使うことでエージェントの起動やデプロイ、評価、テストができます。

※詳しいコマンドの使い方についてはAgent Development Kit（ADK）のノート（コマンド編）にまとめています。

ここではエージェントの起動方法にフォーカスして説明します。

結論から説明すると注意点は以下の2つです。

環境変数の設定
gcloudのセットアップ
エージェントの起動方法、どのディレクトリでコマンドを実行するか

環境変数においては、Google CloudのVertex AIを利用する前提で説明しますが
主に3つの環境変数を設定する必要があります。

エージェントの起動方法については前述のroot_agentが読み込めるような形でコマンドを実行する必要があります。
では、順番に説明していきます。

環境変数の設定

環境変数にはプロジェクト、リージョン、Vertex AIの利用を示すフラグなどがあります。
以下のように環境変数を設定します。※your-project-idは実際のプロジェクトID、リージョンは実際に利用するリージョンに置き換えてください。

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_LOCATION=us-central1

gcloudのセットアップ

gcloudのセットアップは、Google Cloudのプロジェクトを作成し、必要なAPIを有効化することから始まります。

エージェントの起動方法

エージェントを起動するためにはadk runあるいはadk webコマンドを使います。
adk runコマンドはターミナル上でエージェントを起動するコマンドであり、コマンドラインベースのエージェントを起動できます。

adk webコマンドはWebブラウザ上でエージェントと対話できるようにするコマンドです。
このコマンドを使うことで、簡易的なチャット画面が起動してWebブラウザ上でエージェントと対話できるようになります。

それぞれの起動方法を見ていきましょう。

adk runコマンドでエージェントを起動する

adk_samplesのacademic_researchエージェントを起動するためには、以下のコマンドを実行します。

## cd agents/academic-research
adk run academic_research

このコマンドを実行すると、ターミナル上でエージェントが起動します。
エージェントが起動すると、以下のようなメッセージが表示されます。

Log setup complete: /tmp/agents_log/agent.20250607_232143.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent academic_coordinator, type exit to exit.
[user]:

adk runは指定のディレクトリをエージェントのルートディレクトリとして起動します。
この場合、academic_researchディレクトリがルートディレクトリとなり、その中のagent.pyがエージェントのエントリポイントとなります。

└── agents
    ├── academic-research
    │   ├── README.md
    │   ├── academic_research # adk runで指定するエージェントのディレクトリ
    │   │   ├── __init__.py
    │   │   ├── agent.py
    │   │   └── sub_agents # エージェントが呼ぶ他のエージェントを保存するディレクトリ

adk webコマンドでエージェントを起動する

adk webコマンドを使うと、Webブラウザ上でエージェントと対話できるようになります。
以下のコマンドを実行します。

## cd agents/academic-research
adk web

このコマンドを実行すると、Webブラウザが起動し、エージェントと対話できる画面が表示されます。
Webブラウザ上でエージェントと対話できるようになります。

adk webコマンドは起動時にカレントディレクトリをエージェントのルートディレクトリとして認識します。
ディレクトリを指定することもできますが、同じディレクトリで以下のようにディレクトリを指定して実行すると正常に動作しません。

## cd agents/academic-research
adk web academic_research

上記の場合、さらに配下にあるsub_agentsディレクトリをルートエージェントとして認識しますが、agent.pyが存在しないため、チャットをしてみると{"error": "module 'sub_agents' has no attribute 'agent'"}というエラーが発生します。

エージェントを開発するためのディレクトリ構造をおさらい

エージェントを開発するためのディレクトリ構造をおさらいします。
挨拶をするエージェントと要約をするエージェントをサブエージェントとして持つルートエージェントを作成する場合は以下のようなディレクトリ構造になります。

adk-samples
└── agents
    ├── human
    │   ├── README.md
    │   ├── main_agent # ルートエージェントのディレクトリ
    │   │   ├── __init__.py
    │   │   ├── agent.py
    │   │   ├── tools # エージェントが使うツールを定義するディレクトリ
    │   │   └── sub_agents # エージェントが呼ぶ他のエージェントを保存するディレクトリ
    │   │       ├── hello_agent # 挨拶をするエージェント
    │   │       │   ├── __init__.py
    │   │       │   └── agent.py 
    │   │       └── summarize_agent # 要約をするエージェント
    │   │           ├── __init__.py
    │   │           └── agent.py

※deployment、eval、testsディレクトリは省略しています。

なお、サブエージェントがtoolsを利用する場合はそれぞれのサブエージェント用にtoolsディレクトリを作成する必要があります。どのように設計するか何を作るかに依存するところがありますが、可能であれば、別のモジュールとして作成して
パッケージレジストリからインストールできるようにするのが望ましいでしょう。

まとめ

本記事では、Google CloudのAgent Development Kit（ADK）を用いたエージェント開発の基本的な概念やディレクトリ構造、実際の起動方法について整理しました。
ADKは強力なツールですが、最初はディレクトリ構成やコマンドの使い方に戸惑うことも多いです。

エージェントの構成や起動のポイントを押さえることで、よりスムーズに開発へ着手できるようになります。

今後は、実際のエージェント実装や応用的な使い方についても触れていく予定です。ADKを活用したエージェント開発の第一歩として、本記事が参考になれば幸いです。

Discussion