1. 始める前に
「ADK を使用した AI エージェントの構築」シリーズの第 1 部へようこそ。このハンズオン Codelab シリーズでは、Google のエージェント開発キット（ADK）を使用して、独自のインテリジェント AI エージェントを作成するエキサイティングな旅に出かけます。
まず、開発環境の設定と基本的な会話型エージェントの作成について説明します。この Codelab を終えると、最初のインタラクティブ AI が完成します。この AI は、このシリーズの以降のパートで、高度なマルチエージェント システム（MAS）に変換する際に拡張できます。
この Codelab は、ローカル環境または Google Cloud で完了できます。一貫したエクスペリエンスを実現するには、Google Cloud 環境の Cloud Shell を使用することをおすすめします。Cloud Shell には、$HOME ディレクトリに 5 GB の永続ストレージも用意されています。これは、スクリプト、構成ファイル、クローン作成されたリポジトリを保存する場合に便利です。
前提条件
- 生成 AI のコンセプトを理解していること
- Python プログラミングの基本的なスキル
- コマンドライン / ターミナルに精通していること
学習内容
- Python 環境の設定方法
- ADK を使用してシンプルなパーソナル アシスタント エージェントを作成する方法
- エージェントの実行、テスト、デバッグ方法
必要なもの
- 動作するパソコンと安定した Wi-Fi 接続
- Google Cloud コンソールにアクセスするためのブラウザ（Chrome など）
- 課金が有効になっている Google Cloud プロジェクト
- 好奇心と学習意欲
2. はじめに
生成 AI（GenAI）の世界は急速に進化しており、AI エージェントは現在注目を集めているトピックです。AI エージェントは、パーソナル アシスタントのようにユーザーに代わって行動するように設計されたスマートなコンピュータ プログラムです。デジタル環境を認識し、意思決定を行い、人間の直接的な制御なしに特定の目標を達成するための行動をとることができます。学習して適応し、タスクを完了できる、プロアクティブな自律型エンティティとお考えください。
AI エージェントは、大規模言語モデル（LLM）を「脳」として使用して、理解と推論を行います。これにより、テキスト、画像、音声など、さまざまなソースからの情報を処理できます。エージェントは、この理解に基づいて計画を作成し、一連のタスクを実行して、事前に定義された目標を達成します。
エージェント開発キット（ADK）などのすぐに使用できるフレームワークにより、深い専門知識がなくても独自の AI エージェントを簡単に構築できるようになりました。このジャーニーでは、タスクを支援するパーソナル アシスタント エージェントを構築することから始めます。では始めましょう
3. Google Cloud サービスを構成する
トライアルの請求先アカウントを利用する
Google Cloud サービスを利用するには、有効な請求先アカウントが必要です。まだお持ちでない場合は、この Codelab を完了できるように、トライアルの課金アカウントをご用意しています。
請求先アカウントを利用する手順は次のとおりです。
- こちらの特典交換ポータルにアクセスします。
- 個人の Gmail アカウントを使用してログインする
- 手順に沿って操作します
請求先アカウントを利用してプロジェクトを正常に設定できた場合は、Cloud Shell の構成セクションに進んでください。
提供されたトライアル請求先アカウントをすでに使い切っている場合は、新しい請求先アカウントを設定する必要があります。手順は次のとおりです。
Google Cloud プロジェクトを選択または作成する
- Google Cloud コンソールに移動します。
- 上部にあるプロジェクト セレクタのプルダウン（Google Cloud ロゴの横）をクリックします。
- 既存のプロジェクトを選択するか、新しいプロジェクトを作成します。
プロジェクトに対する課金を有効にする
- Google Cloud の課金ドキュメントの手順に沿って、プロジェクトの課金を有効にします。
Cloud Shell を構成する
次に、Google Cloud Console 内の便利なコマンドライン インターフェースである Cloud Shell で正しく設定されていることを確認します。
Cloud Shell を起動する
Google Cloud コンソールの右上隅に、ターミナル（>_）のようなアイコンが表示されます。このアイコンをクリックして Cloud Shell をアクティブにします。
アクセスを承認
プロンプトが表示されたら、[承認] をクリックして、Google Cloud プロジェクトを操作するために必要な権限を Cloud Shell に付与します。
アカウントを確認する:
Cloud Shell が読み込まれたら、正しい Google Cloud アカウントを使用していることを確認します。次のコマンドを実行します。
gcloud auth list
ターミナルに次のようなコマンド出力が表示されます。
Credentialed Accounts
ACTIVE: *
ACCOUNT: current_account@example.com
To set the active account, run:
$ gcloud config set account `ACCOUNT`
アカウントを切り替える（必要な場合）:
アクティブなアカウントが正しくない場合は、次のコマンドを使用して正しいアカウントに切り替えます。your_username@example.com は実際のメールアドレスに置き換えてください。
gcloud config set account your_username@example.com
プロジェクトを確認する
次に、正しい Google Cloud プロジェクトを使用するように Cloud Shell が構成されていることを確認します。次のコマンドを実行します。
gcloud config list project
構成リストが表示されます。[core] セクションを探し、プロジェクトの値がこの Codelab で使用する Google Cloud プロジェクトの ID と一致していることを確認します。
[core] project = <current-project-id>
プロジェクトを設定する（必要な場合）
project ID の値が正しくない場合は、次のコマンドを使用して目的のプロジェクトに設定します。
gcloud config set project <your-desired-project-id>
必要な API を有効にする
Google Cloud サービスを使用するには、まずプロジェクトでそれぞれの API を有効にする必要があります。Cloud Shell ターミナルで次のコマンドを実行すると、この Codelab で必要なすべてのサービスが有効になります。
gcloud services enable aiplatform.googleapis.com
オペレーションが正常に完了すると、ターミナルに Operation/... finished successfully が出力されます。
4. Python 仮想環境を作成する
Python プロジェクトを開始する前に、仮想環境を作成することをおすすめします。これにより、プロジェクトの依存関係が分離され、他のプロジェクトやシステムのグローバル Python パッケージとの競合が回避されます。エージェント開発キット（ADK）には Python 3.9 以降が必要なため、uv などのツールを使用して仮想環境を管理し、正しい Python バージョンが使用されるようにします。
uv は、Python プロジェクトと環境を管理するための最新の高速で効率的なツールです。pip、venv、pip-tools、pipx などのツールに従来からある機能を組み合わせています。速度を重視して Rust で記述されています。
Cloud Shell には uv がすでに用意されているため、すぐに始めることができます。ターミナルで次のコマンドを 1 行ずつ実行します。
uv が正しくインストールされているかどうかを確認する
uv --version
エージェントの新しいプロジェクト フォルダを作成する
uv init ai-agents-adk
プロジェクト フォルダに移動する
cd ai-agents-adk
Python 3.12 で仮想環境を作成する
uv venv --python 3.12
仮想環境に Google ADK ライブラリをインストールする
uv add google-adk
google-adk パッケージが正常にインストールされているかどうかを確認する
uv pip list | grep google-adk
google-adk とそのバージョンを含む出力行が表示されたら、次のステップに進みます。
5. エージェントを作成する
開発環境のセットアップが完了し、準備が整ったので、AI エージェントの基盤を構築しましょう。エージェント開発キット（ADK）を使用すると、このプロセスが簡素化され、エージェントのコアロジックと構成を定義するために必要なファイルは数個のみになります。
これら 3 つのファイルが連携して、エージェントを検出可能、実行可能、構成可能にします。
agent.py: エージェントの中核となる部分です。これには、エージェントの動作を定義する主要な Python コードが含まれています。これには、エージェントの名前、「脳」として使用する大規模言語モデル（LLM）、レスポンスをガイドするコア インストラクションが含まれます。__init__.py: Python では、__init__.pyファイルはディレクトリを Python パッケージとしてマークします。ADK では、フレームワークがagent.pyからエージェント定義を検出して読み込むのに役立つため、非常に重要です。シンプルな ADK プロジェクトでは、多くの場合、agentモジュールをインポートする 1 行が含まれており、エージェントを ADK ランナーからアクセスできるようにしています。.env: このファイル（「環境」の略）は、API キー、プロジェクト ID、地理的位置など、エージェントに必要な機密情報と構成変数を保存するために使用されます。これらの詳細情報を別の.envファイルに保存することは、セキュリティと移植性の観点からベスト プラクティスです。機密データをコードに直接ハードコードすることを防ぐことができます。また、メイン エージェントのロジックを変更せずに構成を簡単に変更することもできます。
次のコマンドを使用して、パーソナル アシスタント エージェント専用のフォルダ内にこれらのファイルを作成します。
uv run adk create personal_assistant
コマンドが実行されると、エージェントを構成するためのオプションをいくつか選択するように求められます。最初のステップでは、オプション 1 を選択して、会話タスクに最適な高速で効率的なモデルである gemini-2.5-flash モデルを使用します。
Choose a model for the root agent: 1. gemini-2.5-flash 2. Other models (fill later) Choose model (1, 2): 1
2 番目のステップでは、バックエンド サービス プロバイダとして、Google Cloud の強力なマネージド AI プラットフォームである Vertex AI（オプション 2）を選択します。
1. Google AI 2. Vertex AI Choose a backend (1, 2): 2
その後、角かっこ [...] で囲まれたプロジェクト ID が正しいことを確認する必要があります。その場合は、Enter キーを押します。表示されていない場合は、ここで正しいプロジェクト ID を入力します。
Enter Google Cloud project ID [project-id]:
最後に、角かっこ [...] で囲まれたプロジェクト リージョンが正しいことを確認する必要があります。その場合は、Enter キーを押します。そうでない場合は、こちらのドキュメントで利用可能な Google Cloud リージョンを確認し、正しいリージョンを入力します。
Enter Google Cloud region [project-region]:
ターミナルに次のような出力が表示されます。
Agent created in /home/<your-username>/ai-agent-adk/personal_assistant: - .env - __init__.py - agent.py
次に、Cloud Shell ウィンドウの上部にある [エディタを開く] ボタンをクリックします。このボタンをクリックすると、エディタ ウィンドウに移動し、ファイルの内容を簡単に確認できます。
切り替えには時間がかかることがあります。読み込み画面が数分以上表示されたままの場合は、ブラウザを更新してみてください。
エディタ ウィンドウが完全に読み込まれたら、personal-assistant フォルダに移動します。上記で説明した必要なファイル（agent.py、__init__.py、.env）が表示されます。内容を見てみましょう。
フォルダに .env ファイルが表示されない場合は、上部のメニューバーに移動して [表示] をクリックし、[隠しファイルの切り替え] を選択します。.env ファイルは誤って公開されないようにデフォルトで非表示になっていることが多いため、これは一般的な設定です。
各ファイルの内容を見ていきましょう。
agent.py
このファイルは、google.adk.agents ライブラリの Agent クラスを使用してエージェントをインスタンス化します。
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-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 import Agent: この行は、ADK ライブラリから必要なAgentクラスをインポートします。root_agent = Agent(...): ここでは、AI エージェントのインスタンスを作成しています。name="root_agent": エージェントの一意の識別子。ADK はこの名前でエージェントを認識し、参照します。model="gemini-2.5-flash": この重要なパラメータは、エージェントが理解、推論、レスポンスの生成の基盤となる「脳」として使用する大規模言語モデル（LLM）を指定します。gemini-2.5-flashは、会話タスクに適した高速で効率的なモデルです。description="...": エージェントの目的や機能の簡潔な概要を提供します。この説明は、人間が理解するため、またはマルチエージェント システム内の他のエージェントがこの特定のエージェントの動作を理解するためのものです。これは、ロギング、デバッグ、またはエージェントに関する情報を表示する場合によく使用されます。instruction="...": エージェントの動作をガイドし、ペルソナを定義するシステム プロンプトです。LLM に、どのように行動すべきか、主な目的は何かを伝えます。この例では、エージェントを「役に立つアシスタント」として確立しています。この指示は、エージェントの会話スタイルと機能を形成するうえで重要です。
init.py
このファイルは、Python が personal-assistant をパッケージとして認識するために必要です。これにより、ADK は agent.py ファイルを正しくインポートできます。
from . import agent
from . import agent: この行は相対インポートを実行し、Python に現在のパッケージ（personal-assistant）内のagent（agent.pyに対応）という名前のモジュールを探すよう指示します。このシンプルな行により、ADK がpersonal-assistantエージェントを読み込もうとするときに、agent.pyで定義されたroot_agentを見つけて初期化できます。空であっても、__init__.pyが存在することで、ディレクトリが Python パッケージになります。
.env
このファイルには、環境固有の構成と機密性の高い認証情報が含まれています。
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION
GOOGLE_GENAI_USE_VERTEXAI: これは、生成 AI オペレーションに Google の Vertex AI サービスを使用することを ADK に伝えます。これは、Google Cloud のマネージド サービスと高度なモデルを活用するうえで重要です。GOOGLE_CLOUD_PROJECT: この変数には、Google Cloud プロジェクトの一意の識別子が格納されます。ADK は、エージェントをクラウド リソースに正しく関連付け、課金を有効にするためにこれが必要です。GOOGLE_CLOUD_LOCATION: Vertex AI リソースが配置されている Google Cloud リージョンを指定します（例:us-central1）。正しいロケーションを使用すると、エージェントがそのリージョンの Vertex AI サービスと効果的に通信できます。
6. ターミナルでエージェントを実行する
3 つのファイルがすべて配置されたら、ターミナルからエージェントを直接実行できます。これを行うには、ターミナル ウィンドウを開く必要があります。メニューバーの [ターミナル] をクリックし、[新しいターミナル] を選択します。
ターミナルが使用可能になったら、adk run コマンドを使用してエージェントを起動できます。これは新しいターミナル ウィンドウであり、uv を使用しているため、まず ai-agent-adk フォルダに移動してから、adk run コマンドの前に uv run を付ける必要があります。
ターミナルに次のコマンドを入力します。
cd ai-agents-adk
uv run adk run personal_assistant
すべてが正しく設定されていれば、ターミナルに同様の出力が表示されます。
... Running agent personal_assistant, type exit to exit. [user]: hello. What can you do for me? [personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as: ...
エージェントとのチャットを開始してください。出力は Markdown でフォーマットされることがあり、ターミナルで読みにくいことがあります。次のステップでは、開発 UI を使用して、チャット アプリケーションのようなリッチなエクスペリエンスを実現します。
7. 開発用ウェブ UI でエージェントを実行する
エージェント開発キットには、開発 UI を使用してエージェントをチャット アプリケーションとして起動する便利な方法も用意されています。adk run. の代わりに adk web コマンドを使用します。
前のセッションがまだ開いている場合は、ターミナルで exit と入力して閉じます。前のセッションが閉じたら、ターミナルで次のコマンドを入力します。
uv run adk web
ターミナルに次のような出力が表示されます。
... 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)
開発 UI にアクセスするには、次の 2 つの方法があります。
- ターミナルから開く
- リンク（
http://localhost:8000）と表示されます。
- [ウェブでプレビュー] から開く
- [ウェブでプレビュー] ボタンをクリックします。
- [ポートを変更] を選択します。
- ポート番号を入力します（例: 8000）
- [変更してプレビュー] をクリックします。
ブラウザにチャット アプリケーションのような UI が表示されます。このインターフェースからパーソナル アシスタントとチャットしてみましょう。Markdown 形式が正しく表示されるようになり、この UI を使用して、各メッセージ イベント、エージェントの状態、ユーザー リクエストなどをデバッグして調査することもできます。Gemini との会話をぜひお楽しみください！
8. クリーンアップ（省略可）
この Codelab には長時間実行されるプロダクトは含まれていないため、ターミナルで Ctrl+C または Cmd+C を押して、アクティブなエージェント セッション（ターミナルの adk web インスタンスなど）を停止するだけで十分です。
エージェントのプロジェクト フォルダとファイルを削除する
Cloud Shell 環境からコードのみを削除する場合は、次のコマンドを使用します。
cd ~
rm -rf ai-agents-adk
Vertex AI API を無効にする
以前に有効にした Vertex AI API を無効にするには、次のコマンドを実行します。
gcloud services disable aiplatform.googleapis.com
Google Cloud プロジェクト全体をシャットダウンする
Google Cloud プロジェクトを完全にシャットダウンする場合は、公式ガイドで詳細な手順をご確認ください。
9. おわりに
おめでとうございます！Agent Development Kit（ADK）を使用して、シンプルなパーソナル アシスタント エージェントを正常に構築しました。これで、ADK エージェントのコア コンポーネントの基礎と概要を理解できました。
次のステップとして、リアルタイム情報にアクセスして外部サービスを操作するためのツールをエージェントに提供することで、エージェントの機能を大幅に拡張できます。このシリーズの次の Codelab である ADK を使用した AI エージェントの構築: ツールによる強化では、このプロセスについて説明します。