ADK 集中講座 - 初心者から上級者まで

1. 学習内容

ADK マスタークラス - マルチエージェント システムへのジャーニーへようこそ

AI エージェントの魅力的な世界に足を踏み入れようとしています。質問に答えるだけの単純な chatbot は忘れてください。Agent Development Kit (ADK) を深く掘り下げ、推論、計画、ツールを使用して複雑なタスクを達成できる洗練された自律システムを構築しています。

コースのロードマップ

このチュートリアルを修了すると、次のことができるようになります。

  • 初めての AI エージェントを構築する: ユーザーのニーズを理解し、Google 検索などのツールを使用して、詳細で役立つ回答を生成できる、完全に機能するエージェントをゼロから構築します。
  • カスタムツールを使いこなす: エージェントを独自のカスタム関数や API に接続して、エージェントの真の力を引き出します。エージェントに、リアルタイムの天気予報などのリアルタイム データを取得するように教えます。
  • マルチエージェント システムを構築する: エージェントがタスクを他の専門エージェントに委任し、連携して動作する AI エキスパートのチームを作成する革新的なコンセプトである 「エージェントをツールとして使用する」パターンについて学習します。
  • 複雑なワークフローをオーケストレートする: 単純な委任を超えて、ルーター、シーケンシャル チェーン、ループ、並列実行などの高度なパターンを習得し、ほぼすべてのリクエストを処理できる堅牢で効率的かつインテリジェントなアプリケーションを構築します。
  • エージェントにメモリを付与する: 会話メモリの重要な役割を理解し、エージェントが追加の質問に対応したり、フィードバックから学習したり、複数のステップからなるタスクをシームレスに管理したりできるようにします。

では始めましょう。🚀

2. GCP と Gemini API キーを設定する

GCP プロジェクトと Gemini API キーを設定する

AI エージェントを強化するには、基盤となる Google Cloud プロジェクトと、Google の強力なモデルにアクセスするための Gemini API キーの 2 つが必要です。

ステップ 1: 請求先アカウントを有効にする

  • デプロイに必要な 5 ドルのクレジットで請求先アカウントを請求します。Gmail アカウントであることを確認します。

ステップ 2: 新しい GCP プロジェクトを作成する

  • Google Cloud コンソールに移動し、新しいプロジェクトを作成します。

新しい GCP アカウントを作成する

  • Google Cloud コンソールに移動し、新しいプロジェクトを作成します。
  • 左側のパネルを開き、Billing をクリックして、請求先アカウントがこの gcp アカウントにリンクされているかどうかを確認します。

請求先アカウントを GCP アカウントにリンクする

このページが表示されたら、manage billing account をオンにして、Google Cloud トライアルを選択してリンクします。

ステップ 3: Gemini API キーを生成する

鍵を保護するには、鍵が必要です。

  • Google AI Studio（https://aistudio.google.com/）に移動します。
  • Gmail アカウントでログインします。
  • [API キーを取得] ボタンをクリックします。通常、このボタンは左側のナビゲーション ペインまたは右上にあります。
  • [API キー] ダイアログで、[新しいプロジェクトで API キーを作成] をクリックします。新しいプロジェクトで API キーを作成
  • 請求先アカウントが設定されている、作成した新しいプロジェクトを選択します。新しいプロジェクトを選択する
  • 新しい API キーが生成されます。このキーをすぐにコピーして、安全な場所に一時的に保存します（パスワード マネージャーや安全なメモなど）。これは次のステップで使用する値です。

3. セッション 1: Runner を使用した最初のエージェント

roadmap1

まずは基本から始めましょう。ここでは、最初の単純なエージェント day_trip_agent を作成します。このエージェントの目的は、予算の考慮事項を含め、ユーザーのリクエストに基づいて 1 日の旅行プランを作成することです。この例では、ADK のエージェント インタラクションの 3 つのコア コンポーネントを紹介します。

  • エージェント: オペレーションの中核となる頭脳。これは、指示（個性と使命）、使用する AI モデル（Gemini など）、アクセスできるツールによって定義されます。
  • セッション: 会話のメモリ。インタラクションの履歴（ユーザー メッセージとエージェントのレスポンス）を保存し、継続的な会話を可能にします。
  • Runner: タスクを実行するエンジン。エージェントとセッションを取得し、新しいユーザー クエリを処理して、レスポンスを生成する手順を調整します。

➡️ ノートブックでの確認方法

👉 これは、パート 1: 初めてのエージェント - 日帰り旅行のジーニー 🧞 のセルに対応しています。🌟

エージェント ロボットが読み取り中

  • Agent Definition: create_day_trip_agent() 関数を探します。ここでエージェントが定義されます。詳細な指示文字列に注目してください。これは、エージェントの動作を指示するプロンプトです。また、最初のツールとして Google 検索も提供します。
  • ヘルパー関数: run_agent_query() ヘルパー関数がここで定義されます。このユーティリティは、ノートブック全体でクエリの実行を簡素化するために使用します。
  • テスト実行: run_day_trip_genie() 関数は、ユーザーが「手頃な価格」で「リラックスできる」日帰り旅行をリクエストする様子をシミュレートします。エージェントは、指示と Google 検索ツールを使用して適切な場所を見つけ、マークダウン形式の旅程を作成します。

➡️ アクション: day_trip_agent の指示プロンプトを確認します。テストクエリの「手頃な価格」の旅行のリクエストが、エージェントの「予算を意識する」というガイドラインに直接関連していることを確認します。

4. セッション 2: カスタムツール 🛠️

roadmap2

Google 検索は強力ですが、AI エージェントの真の可能性が発揮されるのは、独自のデータソース、API、カスタム ロジックに接続したときです。このセクションでは、シンプルな Python 関数からカスタムツールを作成します。

関数ツールの最も重要な部分は docstring です。ADK は docstring を自動的に解析して、ツールの機能、受け入れるパラメータ（Args）、返す値（Returns）を理解します。大規模言語モデル（LLM）はこの説明を読み取り、ツールを使用するタイミングと方法を決定します。

➡️ ノートブックでの確認方法

👉 これは、2.1 シンプルな FunctionTool: リアルタイムの天気予報 API の呼び出しのセルに対応しています。🌟

adk tools

  • ツールの定義: get_live_weather_forecast(location: str) 関数はカスタムツールのコアです。都市名を受け取り、公共の National Weather Service API を呼び出し、気温と天気予報を含む辞書を返します。
  • エージェントの定義: weather_agent が作成され、初期化時に tools=[get_live_weather_forecast] を渡すことで新しいツールが装備されます。エージェントの指示には、アウトドア アクティビティを提案する前にこのツールを使用するよう明示的に記載されています。
  • テスト実行: 「タホ湖の近くでハイキングに行きたいのですが、天気はどうですか？」というクエリは、エージェントが get_live_weather_forecast ツールを使用するように直接トリガーします。これは、その指示で get_live_weather_forecast ツールを使用する必要があるためです。

➡️ アクション: get_live_weather_forecast 関数の docstring と weather_agent の手順を読みます。両者の間に直接的な関係があることに注意してください。

5. セッション 3: Agent-as-a-Tool 🧑‍🍳

roadmap3

専門家チームを作成できるのに、単一のモノリシック エージェントを構築する理由は何ですか？Agent-as-a-Tool パターンは、プライマリ エージェント（通常はオーケストレーターまたはルーターと呼ばれる）がタスクを他のより専門的なエージェントに委任する複雑なシステムを構築する強力な方法です。

このパターンを使用すると、モジュール式の再利用可能なエージェントを作成できます。たとえば、データベース クエリの専門家であるエージェント、クリエイティブ ライティングの専門家であるエージェント、親切なコンシェルジュとして機能するエージェントを配置できます。オーケストレーターの役割は、ユーザーのリクエストを理解し、適切なスペシャリストにルーティングすることです。

➡️ ノートブックでの確認方法

👉 これは、2.2 エージェントをツールとして使用する: 専門家にコンサルトする 🧑‍🍳 のセルに対応しています。🌟

ルートデータ

この例では、高度な多層エージェント システムを構築します。

  • スペシャリスト:
    • food_critic_agent: レストランの提案のみを行う高度に専門化されたエージェント。
    • db_agent: ホテル情報をデータベースにクエリするふりをするモック エージェント。
    • concierge_agent: 丁寧なコンシェルジュとして機能する中級レベルのエージェント。重要なのは、food_critic_agent が独自のツールとして存在することです。
  • オーケストレーター（trip_data_concierge_agent）: ユーザーがやり取りする最上位のエージェントです。このエージェントは「マスター旅行プランナー」として、他のエージェントを呼び出す 2 つのツールが与えられます。
    • call_db_agent: db_agent を呼び出す関数。
    • call_concierge_agent: concierge_agent を呼び出す関数。
  • フロー: run_trip_data_concierge() で実行されるテストは、完全な委任チェーンを示しています。
    • ユーザーがオーケストレーターにホテルと近くのレストランを尋ねます。
    • オーケストレーターの指示により、まず call_db_agent ツールを使用してホテルデータを取得します。
    • 次に、オーケストレーターは call_concierge_agent ツールを使用して推奨事項を取得します。
    • concierge_agent は、リクエストを受け取ると、独自のツールである food_critic_agent を使用してレストランのアイデアを取得します。

グルメ評論家の回答はコンシェルジュに渡され、コンシェルジュが丁寧に形式設定してオーケストレーターに返します。オーケストレーターは最終的にユーザーに回答を提示します。

➡️ アクション: run_trip_data_concierge() のテスト実行で実行フローをトレースします。TOOL CALLED の出力に、オーケストレーターからスペシャリストまでの委任チェーンが表示されていることを確認します。これは順次コマンド チェーンです。

6. セッション 4: エージェントのメモリ 🧠

roadmap4

真にインテリジェントなエージェントは、単発のクエリに応答するだけでなく、会話を記憶し、コンテキストを理解し、フィードバックに適応する必要があります。これは、適切なセッション管理によって実現されます。「ループ エージェント」は、メモリによって継続的な会話ループに関与するエージェントと考えることができます。

複数の連続したクエリに同じセッション オブジェクトを使用すると、エージェントは会話の履歴全体を「確認」できます。これにより、フォローアップの質問に対応したり、フィードバックに基づいて自己修正したり、複数ステップのタスクを計画したりできます。

➡️ ノートブックでの確認方法

👉 これは、パート 3: メモリ付きエージェント - アダプティブ プランナー 🗺️ のセルに対応しています。🌟

エージェントのメモリ

  • エージェントの定義: create_multi_day_trip_agent() 関数は、旅行を段階的に計画するように設計されたエージェントを定義します。この手順では、コンテキストを記憶すること、フィードバックを処理すること、1 日単位で計画することを重視しています。

シナリオ 3a: エージェントにメモリがある（✅）

このテストは run_adaptive_memory_demonstration() 関数で実行されます。

  • 1 つの trip_session が作成され、3 ターン連続して再利用されます。
  • ターン 1: ユーザーが 2 日間の旅行プランを開始します。
  • ターン 2: ユーザーがフィードバックを提供します（「お城はあまり好きじゃない」）。エージェントはターン 1 のメモリを持っているため、プランのどの部分を変更すべきかを理解し、代替案を提示します。
  • ターン 3: ユーザーが変更を確認し、次のステップについて尋ねます。エージェントはすべてを記憶し、2 日目の計画に進みます。

シナリオ 3b: メモリなしのエージェント（❌）

このテストは run_memory_failure_demonstration() 関数で実行されます。

これは、セッション管理の重要性を意図的に誤って示すものです。ターンごとに新しいセッションが作成されます。

  • ターン 1: ユーザーが session_one で乗車を開始します。エージェントが正しく応答します。
  • ターン 2: ユーザーが 2 日目の計画を立てるようリクエストしていますが、クエリは新しい session_two で送信されています。この新しいセッションには履歴がないため、エージェントは混乱します。記憶喪失です。どのような旅行が計画されているかはわかりません。

対応: run_adaptive_memory_demonstration() と run_memory_failure_demonstration() のエージェントの返信を比較します。これはノートブックで最も重要なコンセプトです。継続的な会話には継続的なセッションが必要です。

7. セッション 5: ルーター エージェント 🚏

roadmap5

1 人のエージェントが対応できる範囲には限界があります。本当に複雑なユーザー リクエストに対応するには、専門のエージェントのチームが必要です。しかし、特定のクエリにどのエージェントを使用すべきかをどのように判断すればよいのでしょうか？そこで Router Agent の出番です。

ルーター エージェントは、「マスター」エージェントまたはディスパッチャーとして機能します。その唯一の目的は、受信したユーザー クエリを分析し、どの専門エージェント（またはエージェントのワークフロー）がジョブに最適かを判断することです。クエリ自体には回答せず、適切なダウンストリーム エージェントにルーティングするだけです。

たとえば、「最高の寿司」に関するクエリは foodie_agent に送信し、「今週末のコンサート」に関する質問は weekend_guide_agent で処理する必要があります。

➡️ ノートブックでの場所:

👉 このコンセプトはノートブック全体の中核となるものですが、最初に紹介するのはパート 1: マルチエージェントの混乱 - 順次ワークフロー 🧠→🤖→🤖 🌟 です。

ルーター エージェント

  • エージェントの定義: コードセルは、複数のスペシャリスト エージェント（day_trip_agent、foodie_agent、transportation_agent）と、最も重要な router_agent を定義します。router_agent の指示プロンプトに注意してください。ジョブに最適なエージェントの名前のみを返すように明示的に指示されています。
  • 実行ロジック: run_sequential_app 関数は、最初に router_agent を呼び出して決定（chosen_route）を取得し、その決定を if/elif ブロックで使用して適切なスペシャリスト エージェントを実行する方法を示しています。

8. セッション 6: SequentialAgent ⛓️

roadmap6

一部のタスクでは、特定の順序で複数のステップを実行する必要があります。たとえば、「パロアルトで一番おいしい寿司屋を探して、そこまでの行き方を教えて」と話しかけます。これは 2 段階のプロセスです。まずレストランを見つけ、次に経路を取得します。

ADK には、SequentialAgent を使用してこれを管理するクリーンで強力な方法が用意されています。これは、事前定義された順序でサブエージェントのリストを実行する特別なワークフロー エージェントです。

共有状態に魔法が宿っています。シーケンス内の 1 つのエージェントの出力を共有状態辞書に自動的に保存し、次のエージェントの入力として使用できます。これにより、ステップ間で情報を渡すための複雑な手動コードが不要になります。

➡️ ノートブックでの場所:

👉 これは、パート 2（ADK の方法）: SequentialAgent を使用したマルチエージェントの混乱 🧠→⛓️→🤖で説明されています。🌟

Sequential Agent

  • エージェントのリファクタリング: このセクションの最初のコードセルで、foodie_agent と transportation_agent のキーが変更されていることに注目してください。
    • foodie_agent に output_key="destination" が追加されました。これにより、ADK は最終的な回答を共有状態の destination という名前の変数に保存します。
    • transportation_agent の指示プロンプトにプレースホルダ {destination} が追加されました。ADK は、共有状態の値をこのプレースホルダに自動的に挿入します。
  • ワークフローの定義: find_and_navigate_agent は SequentialAgent として定義され、その sub_agents は [foodie_agent, transportation_agent] に設定されているため、この順序で実行されます。
  • 実行の簡略化: このセクションの run_sequential_app 関数をご覧ください。複雑な if/elif ロジックがなくなりました。find_and_navigate_agent は単一の呼び出し可能な単位として扱われるようになり、ADK が内部の順次ステップを自動的に処理します。

9. セッション 7: LoopAgent 🔁

roadmap7

すべての問題に、単純な一発解決策があるわけではありません。特定の制約を満たすまで、ソリューションを提案し、批判し、改良する必要がある場合があります。

このために、ADK には LoopAgent が用意されています。このワークフロー エージェントは、特定の条件が満たされるまで、サブエージェントのシーケンスを繰り返し実行します。これは、自身の作業を計画、批評、改善できる「完璧主義者」のエージェントを構築するのに最適です。

この図は、Planner Agent が最初にプランを作成することを示しています。次に、LoopAgent を入力します。Critic Agent はプランを確認します。欠陥がある場合は、Refiner Agent によって新しいバージョンが作成され、ループが繰り返されます。プランが適切であれば、Refiner Agent は exit_loop ツールを呼び出し、検証済みの最終プランが返されます。

Loop Agent

➡️ ノートブックでの場所:

👉 詳しくは、LoopAgent を使用したアイデアの反復 🧠→🔁→🤖をご覧ください。🌟

  • コア エージェント: ワークフローは planner_agent、critic_agent、refiner_agent を使用します。
  • ループの定義: refinement_loop は、critic_agent、refiner_agent、sets max_iterations=3 をオーケストレートする LoopAgent として定義されます。
  • 終了条件: critic_agent がプランを承認するとループが終了し、refiner_agent がカスタム exit_loop ツールを呼び出します。

10. セッション 8: ParallelAgent ⚡️

roadmap8

効率性が重要です。ユーザーが複数の無関係な情報を一度に要求した場合、これらの検索を 1 つずつ実行すると時間がかかります。

ParallelAgent が解決策です。このワークフロー エージェントは、サブエージェントのリストを同時に実行します。すべての並列タスクが完了すると、その結果が収集され、1 つの包括的なレスポンスに統合されます。

この図は、ParallelAgent が単一のクエリを取得し、作業を 3 つの同時実行トラックにフォークしていることを示しています。museum_finder、concert_finder、restaurant_finder はすべて同時に実行されます。3 つのタスクがすべて完了すると、個々の結果（共有状態に保存）が結合され、最終的な合成エージェントに渡されます。合成エージェントは、それらを 1 つの回答にまとめます。

➡️ ノートブックでの場所:

👉 このワークフローの詳細については、ParallelAgent による並列処理 🧠→⚡️→🤖🤖🤖のセクションをご覧ください。🌟

Parallel Agent

  • スペシャリスト エージェント: 3 人のスペシャリスト エージェントが定義され、それぞれに一意の output_key（museum_result など）が割り当てられています。
  • 並列ワークフロー: parallel_research_agent は ParallelAgent として定義され、3 つのファインダー エージェントが sub_agents としてリストされています。
  • 統合ステップ: 並列ステップの後、最終的な synthesis_agent がプレースホルダ（{museum_result}、{concert_result} など）を使用して共有状態からすべての結果を収集し、わかりやすい概要を作成します。

11. 付録: ADK ウェブ - 🍎 Mac/Linux 向け

roadmap9

このガイドでは、ローカルマシンで ADK 日帰り旅行プランニング エージェントを設定して実行する手順について説明します。

前提条件

  • Python 3.8 以降
    • Python 3.9 以降: google-adk==1.5.0（すべての機能を備えた最新バージョン）をインストールします。
    • Python 3.8: google-adk==0.3.0（互換性のあるバージョン）をインストールします。
  • Google AI Studio API キー
  • インターネット接続

ステップ 1: リポジトリのクローンを作成する

ターミナルを開いて実行します。

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

ステップ 2: 仮想環境を設定して依存関係をインストールする

オプション A: 自動設定（推奨）

# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

オプション B: 手動設定

# Create virtual environment
python3 -m venv .adk_env

# Activate virtual environment
source .adk_env/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

ステップ 3: 🔥 重要 - 環境変数を作成する

⚠️ この手順はスキップしないでください。agent/ ディレクトリに .env ファイルを作成します。

# Create the .env file
touch agent/.env

# Open it in your default text editor
open agent/.env

次の行をファイルに追加します。

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 重要な注意: your_actual_api_key_here は実際の API キーに置き換えてください。

ステップ 4: 仮想環境を有効にする（まだ有効になっていない場合）

source .adk_env/bin/activate

ターミナル プロンプトの先頭に (.adk_env) が表示されます。

ステップ 5: ADK ウェブ インターフェースを実行する

adk web

ステップ 6: ブラウザを開く

  1. ブラウザを開き、ターミナルに表示された URL（通常は http://localhost:8000）に移動します。
  2. 左上のプルダウンで agent を選択します。
  3. 日帰り旅行の計画担当エージェントとのチャットを開始します。

次のような会話が表示されます。ADK ウェブ UI の例

環境を無効にする

プロジェクトの作業が完了したら:

deactivate

このコマンドは、Mac/Linux と Windows の両方で同じように機能します。ターミナル プロンプトから (.adk_env) 接頭辞が消えます。

Mac のトラブルシューティング

  • Python が見つかりません: python ではなく python3 を使用する
  • Permission denied: スクリプトを実行する前に chmod +x setup_venv.sh を実行する

12. 付録: ADK ウェブ - 🪟 Windows ユーザー向け

roadmap9

このガイドでは、ローカルマシンで ADK 日帰り旅行プランニング エージェントを設定して実行する手順について説明します。

前提条件

  • Python 3.8 以降
    • Python 3.9 以降: google-adk==1.5.0（すべての機能を備えた最新バージョン）をインストールします。
    • Python 3.8: google-adk==0.3.0（互換性のあるバージョン）をインストールします。
  • Google AI Studio API キー
  • インターネット接続

ステップ 1: リポジトリのクローンを作成する

コマンド プロンプトまたは PowerShell を開き、次のコマンドを実行します。

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

ステップ 2: 仮想環境を設定して依存関係をインストールする

オプション A: 自動設定（推奨）

# Run the setup script in Command Prompt
setup_venv.bat

オプション B: 手動設定

コマンド プロンプトの場合:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

PowerShell の場合:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\Activate.ps1

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

ステップ 3: 🔥 重要 - 環境変数を作成する

⚠️ この手順はスキップしないでください。agent/ ディレクトリに .env ファイルを作成します。

# Create the .env file
type nul > agent\.env

# Open it in Notepad
notepad agent\.env

次の行をファイルに追加します。

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 重要な注意: your_actual_api_key_here は実際の API キーに置き換えてください。

ステップ 4: 仮想環境を有効にする（まだ有効になっていない場合）

コマンド プロンプト:

.adk_env\Scripts\activate

PowerShell:

.adk_env\Scripts\Activate.ps1

プロンプトの先頭に (.adk_env) が表示されます。

ステップ 5: ADK ウェブ インターフェースを実行する

adk web

ステップ 6: ブラウザを開く

  1. ブラウザを開き、ターミナルに表示された URL（通常は http://localhost:8000）に移動します。
  2. 左上のプルダウンで agent を選択します。
  3. 日帰り旅行の計画担当エージェントとのチャットを開始します。

Windows のトラブルシューティング

  • PowerShell 実行ポリシー エラー: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser を実行する

次のような会話が表示されます。ADK ウェブ UI の例

環境を無効にする

プロジェクトの作業が完了したら:

deactivate

このコマンドは、Mac/Linux と Windows の両方で同じように機能します。ターミナル プロンプトから (.adk_env) 接頭辞が消えます。