先日、ADK のドキュメントを開いたまま、エージェント、ツール、セッション、ランナーという言葉が一度に並んでいるのを前に、しばらく手が止まっていました。コード例を写して adk web を叩いても、画面にはエージェントが一つも出てきません。原因はコードではなく、コマンドを実行したフォルダでした。
最初にお伝えしたいのは、ADK は概念から入るより、先に一度動かしてしまうほうがはるかに早い、ということです。このチュートリアルでは理屈を最小限にして、写せば動くコードと、つまずく順に並べた確認ポイントをお渡しします。終わるころには、お手元のターミナルで「天気を答えるエージェント」が動いているはずです。
作るもの
動かすのは、「東京の天気は?」と聞くと get_weather という Python 関数を自分で呼び出し、その結果を自然な一文にして返す小さなエージェントです。天気 API にはつなぎません。固定のダミーデータを返します。
狙いは、「モデルが考える → ツールを呼ぶ → 結果を言葉にする」という ADK の基本の流れを、最短で体に入れることです。
この流れが見えたら、get_weather を「在庫を調べる関数」や「Slack に投稿する関数」に差し替えるだけで、形はほとんど変わりません。
Step 1: 環境を整える(5分)
ADK は Python 3.10 以上で動きます。公式のクイックスタートも、まず仮想環境を作ってからインストールする流れです。
# 作業フォルダを作って仮想環境を有効化
mkdir adk-tutorial && cd adk-tutorial
python3 -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
# ADK 本体をインストール
pip install google-adk
# 動作確認(バージョンが表示されれば OK)
adk --versionadk: command not found と出たときは、仮想環境の有効化に失敗しているか、pip が別の Python を見ているかのどちらかであることがほとんどです。which python と which pip の出力が、どちらも .venv の中を指しているかを先に確かめてみてください。
Step 2: フォルダ構成を作る(3分)
ADK は「フォルダ名がそのままエージェント名になる」という約束で動きます。少し独特ですが、ここを押さえておくと後の adk web で迷いません。
公式には adk create というコマンドが雛形(agent.py・.env・__init__.py)を一式作ってくれます。ここでは仕組みを目で追えるよう、手で作ります。
# weather_agent という名前のエージェント用フォルダを作成
mkdir weather_agent
cd weather_agent
# 必要なファイルを作成
touch __init__.py agent.pyここまでの構成は次のとおりです。
| パス | 役割 |
|---|---|
adk-tutorial/ | 作業フォルダ。adk web はここから起動します |
weather_agent/__init__.py | agent.py を読み込むための 1 行 |
weather_agent/agent.py | エージェント本体 |
weather_agent/.env | API キー(次の手順で作ります) |
__init__.py に書くのは 1 行だけです。
# weather_agent/__init__.py
from . import agentこの import が欠けていると、エージェントが一覧に出てきません。私も最初の起動で「見つかりません」の表示を前に、五分ほど画面を見つめておりました。
API キーは、Google AI Studio で発行したものを、エージェントのフォルダの中の .env に置きます。公式のクイックスタートも my_agent/.env という場所を指しています。
# weather_agent フォルダの中で実行
cat > .env << 'INNER'
GOOGLE_API_KEY="YOUR_GEMINI_API_KEY"
INNERYOUR_GEMINI_API_KEY は、ご自身のキーに置き換えてください。.env は Git にコミットしないよう、.gitignore に一行足しておくと安心です。
Step 3: エージェント本体を書く(10分)
weather_agent/agent.py に、次をそのまま貼り付けます。
# weather_agent/agent.py
from google.adk.agents import Agent
def get_weather(city: str) -> dict:
"""指定された都市の現在の天気をダミーで返します。
Args:
city: 天気を知りたい都市名(例: "Tokyo", "Osaka")
Returns:
天気情報を含む辞書。status, temperature_c, condition を含みます。
"""
# 本番では外部 API を叩く部分。ここでは固定値で挙動を確認します。
weather_data = {
"Tokyo": {"temperature_c": 22, "condition": "晴れ"},
"Osaka": {"temperature_c": 24, "condition": "曇り"},
"Sapporo": {"temperature_c": 14, "condition": "雨"},
}
if city in weather_data:
return {"status": "success", "city": city, **weather_data[city]}
return {"status": "error", "message": f"{city} の天気データは未登録です。"}
# ADK が起動時に探す変数名は "root_agent"
root_agent = Agent(
name="weather_agent",
model="gemini-3.8-flash",
description="日本国内の天気を答える小さなアシスタント。",
instruction=(
"あなたは天気案内のアシスタントです。"
"ユーザーから都市名を聞かれたら、必ず get_weather ツールを呼んで結果を取得し、"
"その結果を日本語で自然な一文にまとめて答えてください。"
"都市名は英語表記(Tokyo など)に直してから渡してください。"
),
tools=[get_weather],
)ここで最も大事なのは、変数名を root_agent にすることです。別の名前にすると、画面にエージェントが出ず、エラーも出ないため、原因にたどり着きにくくなります。
もう一つは、get_weather の docstring です。ADK は docstring を読んで、その関数で何ができるのかをモデルに伝えます。ここが空だと、モデルは呼ぶ場面を判断できず、せっかくの関数が素通りされてしまいます。
instruction の最後に「英語表記に直して渡す」と一文を足したのは、辞書のキーが Tokyo だからです。日本語の「東京」のまま渡されると、未登録のエラーが返ってきます。
モデル名について補足します。この記事を更新した 2026年10月時点で、Gemini API の公式ドキュメントが新規プロジェクトに勧めている安定版の Flash は gemini-3.8-flash です。公式のクイックスタートは gemini-flash-latest という別名を使っていますが、挙動を固定したいので、ここでは名前を明示しました。モデルは入れ替わりが早いため、写す前に モデル一覧 と 非推奨一覧 をご確認いただければと思います。
Step 4: 起動して会話してみる(5分)
起動の前に、いまいる場所を確認します。weather_agent/ の一つ上、adk-tutorial/ に戻ってから実行します。
cd ..
adk webブラウザで http://localhost:8000 を開き、左上のドロップダウンから weather_agent を選んで、チャット欄に打ち込みます。
東京の天気を教えて
うまくいくと、「東京は現在22℃で晴れています」のような返答が表示されます。画面右側の Trace を開くと、get_weather がどんな引数で呼ばれたかが時系列で見えます。
なお、公式ドキュメントは ADK Web を「開発とデバッグ専用で、本番では使わない」と明記しています。ここで作った環境は、あくまで手元の練習用です。
ターミナルだけで済ませたいときは、adk-tutorial/ から次のコマンドでも会話できます。
adk run weather_agentつまずきやすいポイントと対処
最初の30分で私が踏んだ落とし穴を、順に挙げます。
| 症状 | 原因と対処 |
|---|---|
| エージェントが一覧に出ない | adk web を weather_agent/ の中で実行しています。一つ上の adk-tutorial/ から起動してください。__init__.py の import 行も確認します |
| ツールが呼ばれず、モデルが勝手に答える | docstring が空か、薄い説明になっています。引数・戻り値・使いどころを具体的に書き直します |
| API キーのエラーが出る | .env を置いた場所を確認します。weather_agent/.env に置き、キーを引用符つきで書いているかも見直します |
| 429(レート制限)が出る | 無料枠には 1 分あたりのリクエスト数の上限があります。続けて試すときは、少し間隔を空けます |
| モデル名のエラーが出る | モデルが入れ替わっている可能性があります。非推奨一覧で、使いたい名前が現役かどうかを確かめます |
私の場合、最初の晩に時間を食ったのは、実は上の最初の行でした。コードを疑い続けて、疑うべきは実行場所だったのです。
エージェントが動かないときは、コードより先に、どのフォルダで動かしたかを疑います。 いま思えば、これがいちばん時間の節約になる線引きでした。ADK で最初に確かめる習慣として、いまも続けています。
次のステップ
動いたら、次は実用に寄せていきます。
第一歩は、get_weather を本物の関数に置き換えることです。手元の CSV を読む、社内 API に問い合わせる、通知を投げる——日々の小さな作業を関数にして渡すだけで、エージェントは仕事を始めます。
ADK を使わずに自前でループを組む選択肢もあります。両者の違いは ADK を使わない Gemini API カスタムエージェントループの本番実装に書きました。
本番運用を見据える段階では、コールバックによる安全装置が欠かせません。Google ADK のコールバックとガードレールで扱っています。会話が長くなったときの記憶の落ち方は、ADK セッション圧縮と記憶の欠落を測るが参考になります。
まずは get_weather の返す都市を一つ増やして、adk web を再起動するところから始めていただければと思います。小さな変更が画面に反映されるのを一度見ておくと、そのあとの拡張がずっと楽になります。