Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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 ツールを段階的に装備します。このラボを完了すると、アップロードされた食品ラベルの写真をクラウドバケットに保存して記録し、各成分の「健康に関するヒント」をすぐに提供できる、完全に機能するオーケストレーターが完成します。

2. 前提条件

課金が有効になっている Google Cloud プロジェクト
ウェブブラウザ

プロジェクトを作成する

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

Cloud Shell をアクティブにする

Cloud Shell（Google Cloud コンソールで実行されるコマンドライン環境）を使用します。この環境には、必要な言語がプリロードされています。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 をクリックすると、すべての Google Cloud プロジェクトが一覧表示されたサイドウィンドウが表示されます。使用するプロジェクトを選択します。

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

インポートしたプロジェクトがプルダウンに表示されます。プルダウンからプロジェクトを選択します。[今すぐ鍵を作成] をクリックします。作成した 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 として指定し、エージェントに名前を付け、わかりやすい説明を入力します。ここで最も重要なのは指示です。自然言語でエージェントが行うべきことを伝えます。
このサンプルエージェントは非常に汎用的で、ユーザーの質問に答えるだけです。
それでは、このエージェントをローカルで実行してみましょう。このエージェントを操作する方法は、CLI とウェブの 2 つがあります。
CLI: healthy_hints ディレクトリの外から次のコマンドを実行します。

adk run healthy_hints

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

adk run .

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

「こんにちは」と入力するか、質問を入力してください。回答は人によって異なる可能性があります。それが生成 AI の性質です。

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

adk web

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

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

ADK のツールの種類

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

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

agent.py に新しいメソッド get_weather を追加しましょう。

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 の統合

複数のツールの使用方法を理解したところで、実際の例を見てみましょう。健康に関するヒントエージェントを作成しましょう。ここでは、材料のリストが記載された画像をエージェントにアップロードし、エージェントが各材料の健康的な側面について教えてくれるようにします。

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

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

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: 基礎からマルチツール エージェントまで