ADK: 基礎からマルチツールエージェントまで

1. はじめに

この Codelab では、ADK を使用してエージェントを構築する方法を包括的に説明します。基本的なことから始まり、マルチツールエージェントの開発へと進みます。

最もシンプルな AI エージェントは、大規模言語モデル（LLM）を「推論エンジン」として使用し、一連のタスクを自律的に実行して目標を達成するソフトウェアシステムです。

LLM がアドバイスを提供する能力の高いコンサルタントであるとすれば、AI エージェントはツールを使用してそのアドバイスを実行できる積極的なエンジニアです。

LLM とエージェント

脳（LLM）: 推論、計画、自然言語理解を提供します。何を行う必要があるかを決定します。

手（ツール）: エージェントが現実世界とやり取りできるようにする API、SDK、カスタム関数です。計画を実行します。

Agent Development Kit（ADK）

Agent Development Kit（ADK）は、AI エージェントの作成、デプロイ、オーケストレーションを簡素化するために設計された特殊なフレームワークです。静的な大規模言語モデルを、コードの実行、API の呼び出し、複数ステップのワークフローの管理が可能な動的なエージェントに変換するために必要な標準化されたビルディングブロックを提供します。

マルチツールエージェントは、検索エンジン、データベース、電卓など、さまざまな特殊な機能を選択して順序付けし、複雑な問題を解決できるオーケストレーターです。各ステップで使用するツールをインテリジェントに決定し、1 つのアクションの出力を次のアクションの入力として渡して最終的な目標を達成できます。

作成するアプリの概要

この Codelab では、「Healthy Hints」エージェントを作成します。これは、シンプルなテキスト推論からマルチツールパワーハウスに移行するインテリジェントな栄養コンサルタントです。まず、栄養のコンセプトを理解する基本的な会話エージェントを作成し、次に、成分画像をアーカイブする Storage SDK ツールと、それらの画像を「読み取り」分析する Vision ツールを段階的に装備します。このラボの最後には、食品ラベルのアップロードされた写真を記録用に Cloud Storage バケットに保存し、各成分の「Healthy Hints」をすぐに提供できる、完全に機能するオーケストレーターが完成します。

2. 前提条件

課金が有効な Google Cloud プロジェクト
ウェブブラウザ

プロジェクトを作成する

Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
Cloud プロジェクトで課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。

Cloud Shell をアクティブにする

Google Cloud コンソールで実行されるコマンドライン環境である Cloud Shell を使用します。この環境には、必要な言語がプリロードされています。Cloud コンソールで、右上の [Cloud Shell をアクティブにする] をクリックします。

Cloud Shell に接続すると、すでに認証は完了しており、プロジェクトに各自のプロジェクト ID が設定されていることがわかります。Cloud Shell で次のコマンドを実行して、認証されたことを確認します。

gcloud auth list

Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。

gcloud config list project

プロジェクトが設定されていない場合は、次のコマンドを使用して設定します。

gcloud config set project <YOUR_PROJECT_ID>

gcloud コマンドとその使用方法については、ドキュメントをご覧ください。

エディタを開く

この Codelab では、組み込みの Cloud エディタを使用します。Cloud Shell ウィンドウで、右上の [エディタを開く] ボタンをクリックします。これにより、VSCode エディタが開きます。

3. ADK の設定

前のセクションでアクティブにした Cloud Shell ターミナルに移動します。

仮想環境を作成して有効にします（推奨）

Cloud Shell ターミナルで仮想環境を作成します。

python -m venv .venv

仮想環境をアクティブにします。

source .venv/bin/activate

ADK をインストールする

pip install google-adk

4. Google API キー

AI Studio を使用して Google API キーを作成します。

https://aistudio.google.com/ にアクセスし、左下のメニューから Get API Key をクリックします。

[API キー] ウィンドウが表示されます。このウィンドウで [API キーを作成] をクリックします。

新しいキーを作成するためのポップアップが表示されます。キーに「healthy-hints-key」という名前を付けます。

[インポートしたプロジェクトを選択] プルダウンに移動します。

Import Project , there'll be a side window which lists all your Google Cloud projects, select the one that you want to work with.

[インポート] をクリックします。

プルダウンが、インポートしたプロジェクトで更新されます。プルダウンからプロジェクトを選択します。[鍵を作成] をクリックします。作成された API キーのリストが表示されます。作成した API キーのコピーアイコンをクリックします。

5. サンプルエージェント

Cloud Shell ターミナルから、目的のプロジェクトの場所にエージェントのルートディレクトリを作成します。

adk create healthy_hints

任意のモデルを選択できますが、この Codelab では gemini-2.5-flash を使用します。

この Codelab では、Google AI を使用します。前のステップで作成した API キーを貼り付けます。

作成したフォルダを開きましょう。左端のメニューで、アイコンをクリックし、[ファイル] -> [フォルダを開く] をクリックします。作成されたフォルダ healthy_hints を選択します。通常、このフォルダは /home/<username> フォルダにあります。
healthy_hints フォルダの構造は通常次のようになります。

Google API キーを含む .env ファイルが表示されます。このファイルを使用して、環境変数を設定できます。
agent.py という名前のファイルも作成されます。これがメインのエージェントファイルです。ここでは、サンプルルートエージェントが作成されます。このファイルの内容を詳しく見てみましょう。まず、ADK から llm_agent をインポートします。次に、ADK DSL を使用してルートエージェントを作成します。モデル名を Gemini-2.5-flash として指定し、エージェントに名前を付け、わかりやすい説明を入力します。ここで最も重要なのは指示です。エージェントが自然言語で実行する必要があることを伝えます。
このサンプルエージェントは非常に汎用的で、ユーザーからの質問に回答するだけです。
このエージェントをローカルで実行してみましょう。このエージェントとやり取りする方法は 2 つあります。CLI とウェブです。
CLI: healthy_hints ディレクトリの外から次のコマンドを実行します。

adk run healthy_hints

または、healthy_hints ディレクトリ内で次のコマンドを実行します。

adk run .

次のような出力が表示されます。

「hi」または質問を入力します。回答は人によって異なる場合があります。これが GenAI の特性です。

ウェブ: healthy_hints の親ディレクトリから次のコマンドを実行します。

adk web

6. マルチツールエージェント

ツールは、エージェントが内部知識を超えて世界とやり取りできるようにする、モジュール化されたコード（通常は関数または API）です。

ADK のツールの種類

関数ツール: 自分で作成するカスタムロジック。たとえば、特定のデータベースに接続する関数や、会社の固有の形式に対応したカスタムの「ログパーサー」などです。
組み込みツール: Google または ADK が提供するすぐに使用できる機能（Google 検索 、コードインタプリタ 、Google RAG エンジン など）。
Agents-as-Tools: 高度な「マルチツール」または「マルチエージェント」システムでは、1 つの特殊なエージェントが別のエージェントのツールとして機能します。たとえば、「検索エージェント」は「調査マネージャーエージェント」が使用するツールにできます。

この Codelab では、関数ツールについて説明します。エージェントを高度化してマルチツールにしましょう。

agent.py

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

agent.py を変更して、エージェントの名前、説明、指示を変更しましょう。

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

これまでに作成したツールは 1 つだけです。複数のツールを作成しましょう。

get_current_time という別のメソッドを作成しましょう。

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

このツールも呼び出すようにエージェントを変更しましょう。

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

説明、指示、ツールを適宜変更しました。この更新されたエージェントを実行しましょう。今回は、エージェントが現在時刻と天気にも応答します。

7. SDK 統合

複数のツールの使用方法がわかったので、実際の例を見てみましょう。Healthy Hints エージェントを作成しましょう。ここでは、成分リストを含む画像をエージェントにアップロードすると、エージェントが各成分が健康的かどうかを教えてくれます。

まず、Google Cloud Storage に画像をアップロードするためのバケットを作成しましょう。新しいタブを開いて https://console.cloud.google.com/ に移動し、検索バーに「cloud storage」と入力します。[プロダクトとページ] で [Cloud Storage] を選択します。

Google Cloud Storage の概要ページが表示されます。Create bucket ボタンをクリックします。[バケットの作成] ページで、バケットの名前を入力します。名前は任意ですが、この Codelab では healthy-hints-bucket-kolkata とします。他はすべてそのままにして、Create[<code></code>] ボタンをクリックします。

requirements.txt という名前の新しいファイルを作成し、google-cloud-storage を追加します。Python Storage SDK を使用して、画像を Storage にアップロードします。

まず、依存関係をインストールしましょう。

pip install -r requirements.txt

最初に Storage API を有効にする必要がある場合があります。その場合は、ターミナルで次のコマンドを実行します。

gcloud services enable storage.googleapis.com

画像をアップロードする新しいツールを追加しましょう。

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

新しいツールを使用するようにエージェントを更新しましょう。

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

画像から成分を読み取る別のツールを追加しましょう。requirements.txt に google-cloud-vision を追加し、新しい依存関係をインストールします。

pip install -r requirements.txt

ここでも、最初に Vision API を有効にする必要がある場合があります。その場合は、ターミナルで次のコマンドを実行します。

gcloud services enable vision.googleapis.com

新しいツール read_ingredients を追加しましょう。

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

このツールを使用するようにエージェントを更新しましょう。

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. まとめ

Healthy Hints Codelab を完了しました。標準的な AI をテキスト生成ツールから積極的なマルチツールエージェントに変換できました。ADK を使用して Vision API と Cloud Storage SDK を統合することで、エージェントにラベルを読み取る「目」と、ラベルをアーカイブする「メモリ」を与えました。エージェントがファイルを保存するタイミングを自律的に決定する方法と、生データを解釈して現実世界の健康に関するアドバイスを提供する方法を確認しました。

今後、これらの原則はあらゆる自動化システムの設計図として役立ちます。クラウドインフラストラクチャの管理でも、パーソナルアシスタントの構築でも、コアは同じです。特殊なツールを定義し、エージェントにロジックをオーケストレートさせます。次のステップとして、「栄養データベース」や「メールツール」などのツールを追加して、エージェントの影響力を拡大してみましょう。

ADK: 基礎からマルチツール エージェントまで