このページは Cloud Translation API によって翻訳されました。

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

1. 始める前に

「ADK を使用して AI エージェントを構築する」シリーズの第 1 部へようこそ。このハンズオン Codelab シリーズでは、Google の Agent Development Kit（ADK）を使用して独自のインテリジェント AI エージェントを作成するエキサイティングな旅に出かけます。

まず、開発環境の設定と基本的な会話型エージェントの作成について説明します。この Codelab を終了すると、最初のインタラクティブ AI が完成します。この 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）を「脳」として使用し、理解と推論を行います。これにより、テキスト、画像、音声など、さまざまなソースからの情報を処理できます。エージェントは、この理解に基づいて計画を作成し、一連のタスクを実行して、事前定義された目標を達成します。

エージェント開発キット（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 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]: 
...

エージェントとのチャットを開始してください。「こんにちは。「What can you do for me?」と入力すると、返信が届きます。

...
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 を使用して、チャットアプリケーションのようなリッチなエクスペリエンスを実現します。

トラブルシューティング

この 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

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

...
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 との会話をぜひお楽しみください！

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 エージェントの構築: ツールによる強化では、このプロセスについて説明します。