メモリと MCP を使用した ADK エージェント パターン

1. 学習内容

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

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

この Codelab 全体はハンズオン形式で進められます。セッションのすべてのコードとサンプルを含む 1 つの GitHub リポジトリ（github リポジトリ）を使用します。

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

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

では始めましょう。🚀

2. 設定: API キーを取得する

Google AI Studio API キーの設定

この Codelab は、無料の Google AI Studio API キーのみで実行できます。Google Cloud プロジェクト、請求先アカウント、クレジットは不要です。Memory（セッション 6）や MCP（セッション 7）を含むすべてのセッションが、キーに対してローカルで実行されます。各学習者は独自のキーを使用するため、API 割り当ては共有されず、ユーザーごとに割り当てられます。

必要なもの:

• Python 3.9 以降（python3 --version で確認）
• Google アカウント（AI Studio キーを作成するため）
• ターミナル - ローカルマシンまたは Cloud Shell のいずれか
• 約 10 分

AI エージェントを強化するには、Google AI Studio の Gemini API キーが必要です。この方法が最も早く始めることができます。

ステップ 1 - AI Studio から Gemini API キーを取得する（1 分）

1. 新しいブラウザタブで https://aistudio.google.com/app/apikey を開きます。
2. Google アカウントを使用してログインします。
3. [API キーを作成]（右上）をクリックします。
4. ダイアログが開き、プロジェクトのプルダウンが表示されます。

• Google プロジェクトをすでに作成している場合: プロジェクトを選択し、[既存のプロジェクトで API キーを作成する] をクリックします。
• リストにない場合: [プロジェクトを作成] をクリックします。

5. 表示された API キーをコピーします。AIza... で始まり、約 40 文字です。

✏️ 安全な場所に貼り付けます。これは以下の手順 4 で必要になります。

API キーはパスワードと同様に扱います。公開チャットやスクリーンショットに貼り付けたり、公開 GitHub リポジトリに commit したりしないでください。

ステップ 2 - リポジトリのクローンを作成する（1 分）

👉💻 ターミナル（または Cloud Shell）を開き、チュートリアル リポジトリのクローンを作成します。

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

ステップ 3 - 仮想環境を作成して依存関係をインストールする

👉💻 .adk_env という名前の仮想環境を作成して有効にし、依存関係をインストールします。

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

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

ステップ 4 - 🔥 重要: API キーを追加する

⚠️ この手順はスキップしないでください。adk_tutorial フォルダのルートに .env ファイルを作成します。この 1 つのファイルが、この Codelab のすべてのセッションを支えています。ADK Web セッション（1 ～ 5）とコマンドラインのメモリと MCP セッション（6 ～ 7）は、すべてこのファイルを自動的に読み取ります。

👉💻 鍵を使用して .env ファイルを作成します（your_actual_api_key_here は手順 1 の鍵に置き換えます）。

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

~/adk_tutorial/.env には次のものが含まれます。

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 重要な注意: your_actual_api_key_here をステップ 1 の実際の API キーに置き換えます（AIza... で始まります）。

⚠️ GOOGLE_GENAI_USE_VERTEXAI が FALSE に設定されていることを確認します。これにより、ADK は Vertex AI ではなく Google AI Studio API キーで認証を行うようになります。

✅ チェックポイント: ~/adk_tutorial/.env に AIza... 鍵を含む .env ファイルがあり、ターミナル プロンプトに (.adk_env) が表示されています。エージェントを構築する準備が整いました。

3. セッション 1: ADK Web で初めてのエージェントを作成する

次のコマンドを実行して ADK Web を開きます。

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

コマンドを実行すると、ターミナルに ADK Web サーバーが起動したことを示す次のような出力が表示されます。

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 次に、ブラウザで http://localhost:8000 を開いて、ADK 開発 UI にアクセスします。

ローカルではなく Cloud Shell で実行しますか？Cloud Shell ツールバー（通常は右上）の [ウェブでプレビュー] アイコンをクリックし、[ポートを変更] を選択して、ポートを「8000」に設定し、[変更してプレビュー] をクリックします。Cloud Shell が新しいブラウザタブで ADK 開発 UI を開きます。

👉 召喚の儀式が完了し、エージェントが実行されています。ブラウザの ADK Dev UI は、Familiar への直接接続です。

最初のエージェントを選択する: UI の上部にあるプルダウン メニューで、a_single_agent を選択します。

a_single_agent は、こちらで選択できます。

トレースはこちら（）で確認できます。

👉 テスト プロンプト:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. セッション 2: ワークフロー エージェント: シーケンシャル エージェント、パラレル エージェント、ループ エージェント

セッション 1 の手順に沿って ADK Web UI を開きます。

並列エージェント

並列ワークフロー エージェントを選択する: UI の上部にあるプルダウン メニューで、b2_parallel_agent を選択します。

👉 テスト プロンプト:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

b2_parallel_agent は、こちらで選択できます。

トレースはこちら（）で確認できます。

シーケンシャル エージェント

順次ワークフロー エージェントを選択する: UI の上部にあるプルダウン メニューで、b1_sequential_agent を選択します。

👉 テスト プロンプト:

Find a good sushi near Standford and tell me how to get there.

b1_sequential_agent は、こちらで選択できます。

トレースはこちら（）で確認できます。

ループ エージェント

ループ ワークフロー エージェントを選択する: UI の上部にあるプルダウン メニューで、b3_loop_agent を選択します。

👉 テスト プロンプト:

Plan a trip from Sunnyvale to San Francisco today.

b3_loop_agent は、こちらで選択できます。

トレースはこちら（）で確認できます。

5. セッション 3: カスタム エージェント

セッション 1 の手順に沿って ADK Web UI を開きます。

ADK ウェブ UI が開いたら、プルダウンから c_custom_agent を選択します。

👉 テスト プロンプト:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

c_custom_agent は、こちらで選択できます。

トレースはこちら（）で確認できます。

6. セッション 4: オーケストレーター パターン - ルーティング エージェント

セッション 1 の手順に沿って ADK Web UI を開きます。

ADK ウェブ UI が開いたら、プルダウンから d_routing_agent を選択します。

👉 テスト プロンプト:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

d_routing_agent はこちらで選択できます:

トレースはこちら（）で確認できます。

7. セッション 5: ツールとしてのエージェント

セッション 1 の手順に沿って ADK Web UI を開きます。

ADK ウェブ UI が開いたら、プルダウンから e_agent_as_tool を選択します。

👉 テスト プロンプト:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

e_agent_as_tool は、こちらで選択できます。

トレースはこちら（）で確認できます。

8. セッション 6: 長期記憶を備えたエージェント

完全にローカルで実行されます。このセッションでは、会話メモリがローカル SQLite データベース（~/.adk/ の下）に保存されるため、再起動しても設定が保持されます。Google Cloud、請求、クレジットは必要ありません。エージェントは、セットアップで作成した ~/adk_tutorial/.env から AI Studio キーを読み取ります。

👉💻 フォルダに移動してランナーを使用してエージェントを強化し、長期記憶をテストします。

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 テスト プロンプト:

I like Art and Italian food.

次に、Ctrl+C キーを押してセッションを終了します。セッションを再起動します。

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 テスト プロンプト:

Plan a trip to San Francisco based on my preference.

✅ エージェントは、前の実行から「アートとイタリア料理」を思い出す必要があります。これは、セッション間で機能する長期記憶です。

9. セッション 7: MCP でエージェントを強化する

完全にローカルで実行されます。このセッションでは、ローカル SQLite データベース（destinations.db）を読み取る ローカル MCP ツールボックス サーバーが起動します。Google Cloud、課金、クレジットは必要ありません。外部からダウンロードするのは、オープンソースの MCP ツールボックス バイナリのみです。

ステップ 1: ローカル データベースを準備する

👉💻 リポジトリのルートから、サンプル データベースを作成します。

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

これにより、~/adk_tutorial/ に destinations.db が作成されます。

⚠️ サンプル データベースには、パリ、ローマ、ニューヨーク、東京の 4 つの都市のみが含まれています（観光スポットのタイプ: ランドマーク、美術館、公園）。他の都市（サンフランシスコやサニーベールなど）を参照するプロンプトは、それらの行が存在しないため、正しく「結果なし」を返します。このセッションをテストする際は、上記の 4 つの都市を使用してください。

ステップ 2: MCP ツールボックス サーバーをインストールして実行する

👉💻 オペレーティング システム用の MCP ツールボックス バイナリをダウンロードします。

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

ダウンロードが完了したら、実行します。

chmod +x toolbox

お使いの Mac がわからない場合は、uname -m を実行します。arm64 = Apple Silicon、x86_64 = Intel。Windows の場合は、.../windows/amd64/toolbox.exe をダウンロードして PowerShell から実行します。

ステップ 3

1 つのターミナルで 次のコマンドを実行します（実行したままにします。エージェントは http://127.0.0.1:7001 でこのコマンドに接続します）。

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

別のターミナルで次のコマンドを実行します。

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 テスト プロンプト（サンプル データベースに存在する都市（パリ、ローマ、ニューヨーク、東京）を使用します）。

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

セッション 7 のトラブルシューティング

• 「接続が拒否されました」/ エージェントがツールを見つけられない: 最初のターミナルの Toolbox サーバーが実行されていません。再起動して、ポート 7001 でリッスンしていることを確認します。
• すべてのクエリで空の結果が返される: ステップ 1 を実行して ~/adk_tutorial/destinations.db が存在することと、プロンプトで 4 つの都市（パリ、ローマ、ニューヨーク、東京）のいずれかを使用していることを確認します。
• macOS で toolbox: cannot execute binary file: Linux ビルドをダウンロードした場合は、OS=darwin/arm64（Apple Silicon）または OS=darwin/amd64（Intel）を使用してステップ 2 を再実行します。