1. 始める前に
「ADK を使用して AI エージェントを構築する」シリーズの第 1 部へようこそ。この実践的な Codelab シリーズでは、Google の Agent Development Kit（ADK）を使用して、独自のインテリジェント AI エージェントを作成するというエキサイティングな取り組みを開始します。
まず、必須事項として、開発環境のセットアップと基本的な会話エージェントの作成について説明します。この Codelab を終える頃には、最初のインタラクティブな AI が完成し、このシリーズの以降のパートで高度なマルチエージェント システム（MAS）に変換する準備が整います。
この Codelab は、ローカル環境または Google Cloud で完了できます。一貫したエクスペリエンスを実現するには、Google Cloud 環境の Cloud Shell を使用することをおすすめします。Cloud Shell には、$HOME ディレクトリに 5 GB の永続ストレージも用意されています。これは、スクリプト、構成ファイル、クローン作成されたリポジトリを保存する場合に便利です。
この Codelab には、短縮 URL（goo.gle/adk-foundation）からアクセスすることもできます。
前提条件
- 生成 AI のコンセプトを理解していること
- Python プログラミングの基本的なスキル
- コマンドライン / ターミナルに精通していること
学習内容
- Python 環境の設定方法
- ADK を使用してシンプルなパーソナル アシスタント エージェントを作成する方法
- エージェントの実行、テスト、デバッグ方法
必要なもの
- 動作するパソコンと安定した Wi-Fi 接続
- Google Cloud コンソールにアクセスするためのブラウザ（Chrome など）
- 好奇心と学習意欲
2. はじめに
生成 AI（GenAI）の世界は急速に進化しており、AI エージェントは現在ホットなトピックとなっています。AI エージェントは、パーソナル アシスタントのようにユーザーに代わって行動するように設計されたスマートなコンピュータ プログラムです。デジタル環境を認識し、意思決定を行い、人間の直接的な制御なしに特定の目標を達成するための行動をとることができます。学習して適応し、物事を成し遂げる自律的なエンティティとして考えてください。
AI エージェントは、大規模言語モデル（LLM）を「脳」として使用し、理解や推論を行います。これにより、テキスト、画像、音声など、さまざまなソースからの情報を処理できます。エージェントは、この理解に基づいて計画を作成し、一連のタスクを実行して、事前に定義された目標を達成します。
Agent Development Kit（ADK）などのすぐに使用できるフレームワークのおかげで、深い専門知識がなくても、独自の AI エージェントを簡単に構築できるようになりました。このジャーニーは、タスクを支援するパーソナル アシスタント エージェントを構築することから始まります。では、始めましょう。
3. Google Cloud サービスを構成する
Google Cloud プロジェクトを作成する
まず、この Codelab のアクティビティがこの新しいクラウド プロジェクト内でのみ分離されるように、新しい Google Cloud クラウド プロジェクトを作成します。
- console.cloud.google.com/projectcreate に移動します。
- 必要な情報を入力します。
- プロジェクト名 - 任意の名前を入力できます（例: genai-workshop）。
- Location - [No Organization] のままにします。
- 請求先アカウント - このオプションが表示されたら、[Google Cloud Platform 無料トライアルの請求先アカウント] を選択します。このオプションが表示されない場合でも、心配はいりません。次のステップに進んでください。
- 生成されたプロジェクト ID をメモしておきます。この ID は後で必要になります。
- 問題がなければ、[作成] ボタンをクリックします。
Cloud Shell を構成する
プロジェクトが正常に作成されたら、次の手順で Cloud Shell を設定します。
1. Cloud Shell を起動する
shell.cloud.google.com に移動し、承認を求めるポップアップが表示されたら、[承認] をクリックします。
2. プロジェクト ID を設定する
Cloud Shell ターミナルで次のコマンドを実行して、正しいプロジェクト ID を設定します。<your-project-id> は、上記のプロジェクト作成手順でコピーした実際のプロジェクト ID に置き換えます。
gcloud config set project <your-project-id>
これで、Cloud Shell ターミナルで正しいプロジェクトが選択されていることがわかります。選択したプロジェクト ID が黄色でハイライト表示されます。
3. 必要な API の有効化
Google Cloud サービスを使用するには、まずプロジェクトでそれぞれの API を有効にする必要があります。Cloud Shell ターミナルで次のコマンドを実行して、この Codelab のサービスを有効にします。
gcloud services enable aiplatform.googleapis.com
オペレーションが正常に完了すると、ターミナルに Operation/... finished successfully が出力されます。
4. Python 仮想環境を作成する
Python プロジェクトを開始する前に、仮想環境を作成することをおすすめします。これにより、プロジェクトの依存関係が分離され、他のプロジェクトやシステムのグローバル Python パッケージとの競合が回避されます。
1. プロジェクト ディレクトリを作成し、そのディレクトリに移動します。
mkdir -p ai-agents-adk
cd ai-agents-adk
2. 仮想環境を作成して有効にします。
uv venv --python 3.12
source .venv/bin/activate
ターミナル プロンプトの先頭に（ai-agents-adk）が表示され、仮想環境がアクティブであることを示します。
3. ADK のインストール ページ
uv pip install google-adk
5. エージェントを作成する
環境の準備が整ったら、AI エージェントの基盤を作成します。ADK では、エージェントのロジックと構成を定義するために、次のファイルが必要です。
agent.py: エージェントのメインの Python コードが含まれています。エージェントの名前、使用する LLM、コアの指示を定義します。__init__.py: ディレクトリを Python パッケージとしてマークし、ADK がエージェント定義を検出して読み込むのに役立ちます。.env: API キー、プロジェクト ID、ロケーションなどの機密情報と構成変数を保存します。
このコマンドを実行すると、3 つの重要なファイルを含む personal_assistant という名前の新しいディレクトリが作成されます。
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 [your-project-id]:
最後に、次の質問で Enter キーを押して、この Codelab のリージョンとして us-central1 を使用します。
Enter Google Cloud region [us-central1]:
ターミナルに同様の出力が表示されます。
Agent created in /home/<your-username>/ai-agent-adk/personal_assistant: - .env - __init__.py - agent.py
6. エージェント コードを確認する
作成したファイルを表示するには、Cloud Shell エディタで ai-agents-adk フォルダを開きます。
- 上部のメニューで [ファイル] > [フォルダを開く...] をクリックします。
ai-agents-adkフォルダを検索して選択します。- [OK] をクリックします。
上部のメニューバーが表示されない場合は、フォルダ アイコンをクリックして [フォルダを開く] を選択することもできます。
エディタ ウィンドウが完全に読み込まれたら、personal-assistant フォルダに移動します。上記で説明した必要なファイル（agent.py、__init__.py、.env）が表示されます。
.env ファイルは、デフォルトで非表示になっていることがよくあります。Cloud Shell エディタで表示するには:
- 上部のメニューバーに移動し、
- [表示] をクリックします。
- [Toggle Hidden Files] を選択します。
各ファイルの内容を確認します。
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 サービスと効果的に通信できます。
7. ターミナルでエージェントを実行する
3 つのファイルがすべて配置されたら、ターミナルからエージェントを直接実行できます。これを行うには、ターミナルで次の adk run コマンドを実行します。
adk run personal_assistant
すべてが正しく設定されていれば、ターミナルに同様の出力が表示されます。[user]: が表示されていれば、警告は無視して続行できます。
... Running agent personal_assistant, type exit to exit. [user]: ...
エージェントとのチャットを開始してください。「こんにちは。」と入力すると、返信が届きます。
... 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: ...
出力はマークダウンでフォーマットされることがあり、ターミナルで読みにくいことがあります。次のステップでは、開発 UI を使用して、チャット アプリケーションのような、よりリッチなエクスペリエンスを実現します。
トラブルシューティング
この API メソッドは、課金を有効にする必要があります
{‘message': ‘This API method requires billing to be enabled'} というメッセージが表示された場合は、次の操作を行います。
.envファイルで正しいプロジェクト ID を使用しているかどうかを確認する- [リンクされた請求先アカウント] ページに移動して、請求先アカウントがすでにリンクされているかどうかを確認します。
- 表示されない場合は、オプションから [Google Cloud Platform Trial Biling Account] を選択します。
Vertex AI API がプロジェクトで使用されていない
{'message': 'Vertex AI API has not been used in project...'} を含むエラー メッセージが表示された場合は、ターミナルに次のコマンドを入力して Vertex AI API を有効にします。
gcloud services enable aiplatform.googleapis.com
オペレーションが正常に完了すると、ターミナルに Operation/... finished successfully が出力されます。
その他のエラー
上記以外のエラーが表示された場合は、ブラウザで Cloud Shell タブを再読み込みしてみてください（プロンプトが表示されたら再認証します）。
8. 開発用ウェブ UI でエージェントを実行する
Agent Development Kit には、開発 UI を使用してエージェントをチャット アプリケーションとして起動する便利な方法も用意されています。adk run. の代わりに adk web コマンドを使用します。
ターミナルで adk run がまだ実行されている場合は、コマンドを入力する前に「exit」と入力して閉じます。
adk web --allow_origins "regex:https://.*\.cloudshell\.dev"
ターミナルに、次のような出力が表示されます。
... 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などの提供されたリンクを Ctrl+クリック（または Cmd+クリック）します。 - ウェブ プレビューの使用:
- [ウェブでプレビュー] ボタンをクリックします。
- [ポートを変更] を選択します。
- ポート番号を入力します（例: 8000）。
- [変更してプレビュー] をクリックします。
ブラウザにチャット アプリケーションのような UI が表示されます。このインターフェースからパーソナル アシスタントとチャットしてみましょう。
Markdown 形式が正しく表示されるようになり、この UI を使用して、各メッセージング イベント、エージェントの状態、ユーザー リクエストなどをデバッグして調査することもできます。Gemini との会話をぜひお楽しみください！
9. クリーンアップ（省略可）
この 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 プロジェクトを完全にシャットダウンする場合は、公式ガイドで詳細な手順をご確認ください。
10. まとめ
おめでとうございます！Agent Development Kit（ADK）を使用して、シンプルなパーソナル アシスタント エージェントを構築できました。これで、ADK エージェントのコア コンポーネントについて、しっかりとした基礎知識と理解が得られました。
次のステップとして、リアルタイムの情報にアクセスして外部サービスとやり取りできるツールをエージェントに提供することで、エージェントの機能を大幅に拡張できます。このシリーズの次の Codelab である ADK を使用して AI エージェントを構築する: ツールによる強化では、このプロセスについて説明します。