ADK を使用した AI エージェントの構築: 基礎

1. 概要

AI エージェントは、大規模言語モデル（LLM）に指示、状態、ツールを組み合わせることで、ユーザーのリクエストを推論し、マルチステップのタスクを自律的に実行できます。構造化されたエージェント フレームワークがないと、デベロッパーは 1 つのプロンプトをテストする前に、モデル クライアント、環境構成、会話セッション、ローカル デバッグ インターフェースを手動で接続する必要があります。

「ADK を使用した AI エージェントの構築」シリーズの最初のパートでは、Google Cloud で Python 開発環境を設定し、Agent Development Kit（ADK 2）と gemini-3.8-flash を使用して Agent Platform で personal_assistant エージェントをスキャフォールディングします。生成されたエージェント パッケージを探索し、インタラクティブなターミナル CLI（adk run）とブラウザベースの ADK ウェブ UI（adk web）の両方でエージェントをテストします。この Codelab は、goo.gle/adk-foundation から直接開くこともできます。

前提条件

学習内容

  • Google Cloud Shell と、uv を使用した分離された Python 3.12 環境を構成する方法
  • Agent Platform で gemini-3.8-flash を利用したスターター ADK 2 エージェント パッケージをスキャフォールディングする方法
  • ADK 2 が agent.py、__init__.py、.env でエージェント コードを整理する方法
  • adk run と adk web でイベント、トレース、SQLite を基盤とするセッションを実行、テスト、検査する方法

必要なもの

  • Google アカウント（ワークショップのクレジットを申請する場合は、個人の @gmail.com アカウントを使用してください）
  • インストラクターから提供されたワークショップ クレジット リンク（および QR コードをスキャンするためのスマートフォンのカメラ）または有効な Cloud 請求先アカウント
  • Google Chrome（個人アカウントと仕事用アカウントが混在しないように、シークレット ウィンドウを使用することをおすすめします）

2. Google Cloud クレジットを申請する（省略可）

イベント クレジット リンクのあるワークショップに参加している場合は、Google Developer Program クレジットを申請して、クレジット カードなしで請求先アカウントをプロビジョニングします。

イベントのクレジットを取得する

  1. シークレット ウィンドウでワークショップのクレジット リンクを開き、@gmail.com アカウントでログインします。
  2. [特典を申請] で、[クレジットを申請] をクリックします。

[クレジットを申請] ボタンが表示された Google Builders Hub の [特典を申請] カード

  1. Google Developer Program プロフィールの作成を求められた場合は、フォームに記入します。
  2. [Scan to Verify You're Human] が表示されたら、スマートフォンで QR コードをスキャンして確認を完了します（QR コードが表示されない場合は、更新して [Claim Credit] をもう一度クリックします）。

Google Developer Program の「スキャンして人間であることを証明してください」QR コード ダイアログ

  1. 「イベントのクレジットを取得しました」と表示されたことを確認し、[請求先アカウントを開く] をクリックします。

「イベントのクレジットを取得しました」というメッセージと [請求先アカウントを開く] ボタンが表示された Google Builders Hub

🔍 実施したタスクを確認する

請求先アカウントの設定には最大 3 分かかります。

  1. Google Cloud Billing を開くか、URL をコピーしてシークレット ウィンドウに貼り付け、[請求先アカウント] を選択します。
https://console.cloud.google.com/billing
  1. GDP Credit アカウントのステータスが [有効] になるまで更新します。

有効な GDP クレジット請求先アカウントが表示されている Google Cloud 請求先アカウント管理

3. Google Cloud プロジェクトを作成する（省略可）

この Codelab のすべてのリソースが分離され、クリーンアップが容易になるように、専用の Google Cloud プロジェクトを作成します。

  1. [プロジェクトを作成] を開きます（または、URL をコピーしてシークレット ウィンドウに貼り付けます）。
https://console.cloud.google.com/projectcreate
  1. プロジェクトの詳細を入力します。
    • プロジェクト名: google-cloud-workshop など
    • 請求先アカウント（表示されている場合）: GDP Credit（または有効な請求先アカウント）を選択します。
    • 親リソース: 組織なし（または必要に応じて組織）
  2. プロジェクト名の下に生成されたプロジェクト ID をメモし、[作成] をクリックします。

プロジェクト名、プロジェクト ID、親リソース、[作成] ボタンが表示されている Google Cloud プロジェクトの作成画面

🔍 実施したタスクを確認する

右上のツールバーにある [通知] をクリックし、プロジェクトの作成が完了したら [プロジェクトを選択] をクリックします。

[プロジェクトを作成] と [プロジェクトを選択] リンクが表示された Google Cloud コンソールの [通知] メニュー

4. 環境を設定する

Google Cloud Shell を構成し、Agent Platform API を有効にして、uv を使用して隔離された Python 3.12 仮想環境を作成します。

Cloud Shell を構成する

  1. Google Cloud コンソールのツールバーで [Cloud Shell をアクティブにする]（>_）をクリックするか、Google Cloud Shell を直接開きます（または、URL をシークレット ウィンドウにコピーします）。
https://shell.cloud.google.com/?show=ide,terminal

Google Cloud コンソールのツールバーにある [Cloud Shell をアクティブにする] ボタン

  1. [承認] をクリックします（求められた場合）。

[Cloud Shell の承認] ダイアログ

  1. ターミナルの番号付きメニューから、アクティブな Google Cloud プロジェクト ID を選択します。
unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
  [ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done

次のような出力が表示されます（タグ付けされていないプロジェクトでは、情報を示す [environment: untagged] 行も出力されます）。

1) google-cloud-workshop-4210
2) my-cloud-project-8812
Select your project (e.g. 1): 1
Updated property [core/project].

選択したプロジェクト ID が Cloud Shell プロンプトで黄色でハイライト表示されていることを確認します。

選択したプロジェクト ID が黄色でハイライト表示されている Cloud Shell ターミナル

必要な API の有効化

ADK エージェントが Gemini モデルを呼び出せるように、Agent Platform API を有効にします。

gcloud services enable aiplatform.googleapis.com

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

Operation "operations/acat.p2-..." finished successfully.

Python 仮想環境を作成して ADK をインストールする

~/ai-agents-adk ワークスペース ディレクトリを作成し、Python 3.12 仮想環境を有効にします。

cd ~
mkdir -p ai-agents-adk && cd ~/ai-agents-adk

which uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

uv venv .venv --python 3.12
source .venv/bin/activate

ターミナル プロンプトの先頭に (.venv) 接頭辞が表示されていることを確認します。

アクティブな Python 仮想環境で .venv 接頭辞が表示されている Cloud Shell ターミナル

アクティブな仮想環境内に ADK をインストールします。

uv pip install --no-cache "google-adk==2.14.0"

🔍 実施したタスクを確認する

インストールされている adk CLI のバージョンを確認します。

adk --version

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

adk, version 2.14.0

5. エージェントをスキャフォールディングする

adk create を使用して、スターター personal_assistant エージェント パッケージを生成します。ADK は personal_assistant/ 内に 4 つのファイルを作成します。

  • agent.py: モデル、名前、説明、システム指示を使用して root_agent を定義します。
  • __init__.py: personal_assistant を Python パッケージとしてマークし、ADK が agent.py を検出してインポートできるようにします。
  • .env: バックエンド フラグ（GOOGLE_GENAI_USE_ENTERPRISE=1）、プロジェクト ID、ロケーション（global）を保存します。
  • .gitignore: .env とローカルの .adk/ SQLite セッション ファイルをバージョン管理から除外します。

adk create を実行します

~/ai-agents-adk から personal_assistant パッケージをスキャフォールディングします。

cd ~/ai-agents-adk
adk create personal_assistant

プロンプトが表示されたら、次のオプションを選択します（初回実行時に Enable telemetry? [Y/n]: のプロンプトが表示された場合は、Enter キーを押すか、n と入力して Enter キーを押します）。

  1. ルート エージェントのモデルを選択する: 「2」と入力して gemini-3.8-flash を選択し（オプション 1 は gemini-3.5-flash を選択）、Enter キーを押します。
  2. バックエンドを選択する: 「2」と入力して Google Cloud Agent Platform バックエンド（以下の CLI メニューのオプション 2）を選択し、Enter キーを押します。
  3. Enter Google Cloud project ID: Enter キーを押して、括弧内に表示されている検出されたプロジェクト ID を受け入れます（異なる場合はプロジェクト ID を入力します）。
  4. Enter Google Cloud region: 「global」（Agent Platform で gemini-3.8-flash を提供するために必要）と入力し、Enter キーを押します。

🔍 実施したタスクを確認する

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

Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2
1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [google-cloud-workshop-4210]:
Enter Google Cloud region [us-central1]: global

Agent created in /home/your_username/ai-agents-adk/personal_assistant:
- .env
- .gitignore
- __init__.py
- agent.py

⚠️  WARNING: Secrets (like GOOGLE_API_KEY) are stored in .env.

Next steps:
- Chat with your agent in the terminal: adk run personal_assistant
- Or in the browser: adk web .
- Have your coding agent evaluate and deploy it: uvx google-agents-cli setup
  (other install options: https://adk.dev/get-started/agents-cli/)

6. 生成されたコードを確認する

Cloud Shell エディタで ~/ai-agents-adk を開き、生成されたファイルをターミナルで確認できるようにします。

which cloudshell >/dev/null 2>&1 && cloudshell workspace ~/ai-agents-adk || true

再読み込みされたターミナルで仮想環境を再度有効にします。

cd ~/ai-agents-adk
source .venv/bin/activate

Cloud Shell エディタでワークスペースを手動で開くこともできます。エクスプローラ アイコン（または [File] > [Open Folder...]）をクリックして、ai-agents-adk を選択します。

[フォルダを開く] ボタンが表示されている Cloud Shell エディタのエクスプローラ ペイン

.env などのドットファイルは、デフォルトでエクスプローラ ツリーに表示されません。上部のメニューバーで [View] > [Toggle Hidden Files] をクリックして、personal_assistant/.env を表示します。

[Toggle Hidden Files] がハイライト表示された Cloud Shell エディタの [View] メニュー

agent.py を確認

Cloud Shell エディタで ~/ai-agents-adk/personal_assistant/agent.py を開きます。

cloudshell edit ~/ai-agents-adk/personal_assistant/agent.py

スキャフォールディングされたファイルを確認します（編集は不要です）。

from google.adk.agents.llm_agent import Agent

root_agent = Agent(
    model='gemini-3.8-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)
  • from google.adk.agents.llm_agent import Agent: ADK の Agent クラス（LlmAgent のエイリアス。ADK 2 では、カスタムコードを記述する際に from google.adk import Agent をトップレベルの短縮形として公開することもできます）をインポートします。
  • model='gemini-3.8-flash': 推論と回答を強化するモデルとして gemini-3.8-flash を選択します。
  • name='root_agent': ADK がログ、トレース、マルチエージェント グラフで使用する識別子を割り当てます。
  • description='...': 親コーディネーターがエージェントに委任するかどうかを決定する際に、エージェントが行う処理を要約します。
  • instruction='...': エージェントのトーンと動作を制御するシステム プロンプトを設定します。

__init__.pyと.envをご確認ください

personal_assistant/__init__.py を開いて、agent が再エクスポートされ、adk run と adk web が root_agent を検出できることを確認します。

from . import agent as agent

personal_assistant/.env を開いて、ランタイム構成を調べます。

GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=google-cloud-workshop-4210
GOOGLE_CLOUD_LOCATION=global
  • GOOGLE_GENAI_USE_ENTERPRISE=1: API キーではなく Google Cloud 認証情報を使用して、Agent Platform 経由で ADK モデル呼び出しをルーティングします。
  • GOOGLE_CLOUD_PROJECT: モデル リクエストと課金を Google Cloud プロジェクトに関連付けます。
  • GOOGLE_CLOUD_LOCATION=global: gemini-3.8-flash が提供されるグローバル エンドポイントをターゲットにします。

🔍 実施したタスクを確認する

personal_assistant/agent.py が正常にインポートされ、.env が global を指していることをターミナルから確認します。

cd ~/ai-agents-adk && source .venv/bin/activate
python3 -c "from personal_assistant.agent import root_agent; print(root_agent.name, root_agent.model)"
cat ~/ai-agents-adk/personal_assistant/.env

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

root_agent gemini-3.8-flash
GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=google-cloud-workshop-4210
GOOGLE_CLOUD_LOCATION=global

7. ターミナルでエージェントを実行する

adk run を使用して、コマンドラインから personal_assistant エージェントを直接テストします。

cd ~/ai-agents-adk && source .venv/bin/activate
adk run personal_assistant

[user]: プロンプトで、hello. What can you do for me? などのメッセージを送信し、エージェントが応答することを確認します。

🔍 実施したタスクを確認する

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

Running agent root_agent, type exit to exit.
[user]: hello. What can you do for me?
[root_agent]: Hello! I can help answer questions, explain concepts, summarize text, brainstorm ideas, and assist with writing or coding tasks. How can I help you today?
[user]: exit

「exit」と入力して Enter キーを押し、インタラクティブ CLI セッションを閉じてシェル プロンプトに戻ってから、続行します。

トラブルシューティング

  • This API method requires billing to be enabled: personal_assistant/.env の GOOGLE_CLOUD_PROJECT がアクティブなプロジェクトと一致していることを確認し、[リンクされた請求先アカウント] を開いて（または以下の URL をコピーしてシークレット ウィンドウに貼り付けて）、アクティブな GDP Credit または Cloud 請求先アカウントをリンクします。
https://console.cloud.google.com/billing/linkedaccount
  • API has not been used in project: ターミナルで Agent Platform API を有効にして、数秒後に再試行します。
gcloud services enable aiplatform.googleapis.com

8. ADK ウェブ UI でエージェントを実行する

ADK 2 の組み込みブラウザ プレイグラウンドでは、マークダウン レスポンス、イベント ペイロード、マルチターン状態を簡単に検査できます。親の ~/ai-agents-adk ディレクトリ（personal_assistant/ の上）から ADK Web UI を起動します。

cd ~/ai-agents-adk && source .venv/bin/activate
adk web --allow_origins "*"

ブラウザで ADK ウェブ UI を開きます。

  1. Cloud Shell の右上にあるツールバーの [ウェブでプレビュー] アイコンをクリックし、[ポートを変更] を選択します。
  2. ポート 8000 を入力し、[変更してプレビュー] をクリックします。

[ポートでプレビュー] オプションと [ポートを変更] オプションが表示された Cloud Shell の [ウェブでプレビュー] メニュー

  1. 左上のエージェント プルダウンで personal_assistant が選択されていることを確認し、"Hello. What can you do?" を送信して、エージェントのレスポンス イベントをクリックしてメタデータを検査します。

ADK 2 ウェブ UI。フォーマットされた Markdown 出力が、[Events] ビュー、[Traces] ビュー、[Info] タブ、[State] タブ、[Artifacts] タブ、[Evals] タブとともに表示されている

ADK 2 のウェブ UI では、[イベント] と [トレース] のストリーム切り替えが、[情報]、[状態]、[アーティファクト]、[評価] のインスペクタ タブ（および上部ツールバーの [エージェント構造] グラフアイコン）と組み合わされ、ローカル セッションが personal_assistant/.adk/session.db に自動的に保存されます。

🔍 実施したタスクを確認する

Cloud Shell ターミナルに、次のような出力が表示されます。

INFO:     Started server process [4978]
INFO:     Waiting for application startup.
+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

テストが完了したら、ターミナルで Ctrl + C を押して adk web サーバーを停止し、コマンド プロンプトに戻ります。

9. クリーンアップ（省略可）

この Codelab では、リクエストごとの Gemini 呼び出し以外に、永続的な課金対象のインフラストラクチャは作成されません。adk web が停止していることを確認します（Ctrl + C）。

ローカル ワークスペース ファイルを削除する

Cloud Shell から ~/ai-agents-adk ディレクトリを削除するには:

cd ~
rm -rf ~/ai-agents-adk

専用プロジェクトを削除する（省略可）

gcloud projects delete "$(gcloud config get-value project)" --quiet

10. 完了

Google Cloud で ADK 2 Python 環境を設定し、Agent Platform で gemini-3.8-flash を利用する personal_assistant エージェントをスキャフォールディングし、生成されたパッケージ構造を調べて、ターミナル CLI と ADK Web UI の両方でテストしました。

達成した内容

  • Google Cloud Shell を構成し、Agent Platform API を有効にして、uv を使用して Python 3.12 環境を作成しました。
  • adk create を使用して personal_assistant をスキャフォールディングし、agent.py、__init__.py、.env がどのように連携するかを確認しました。
  • adk run を介してマルチターンの会話をテストし、adk web でイベント、トレース、SQLite を利用したセッションを検査しました。

次のステップ