◉GEMINI LABEN
●OMNI 1.2 — Gemini Omni 1.2 Flash が GA になりました(11/5)。最長15秒の動画生成と会話での編集に対応し、1.1 Flash は 12/3 に自動で 1.2 へ振り替わります●COMPUTER — Computer Use が Interactions / GenerateContent API で GA になりました(10/30)●LIVE — Live と TTS のプレビュー版は最短 11/17 に停止します(残り7日)。移行先は gemini-3.8-live と 3.8 系 TTS です●CLI — Gemini API CLI(gemini-api)がベータで登場(10/27)。エージェントやCI向けのゼロ依存クライアントです●2.5 PRO — gemini-2.5-pro と 2.5-flash は 12/1 から自動で振り替えられます(残り21日)。移行先は 3.8 Flash と 3.5 Flash-Lite です●NEW — クラッシュ報告を毎回ゼロから読ませない — 既知バグ早見表を先に grep し…●OMNI 1.2 — Gemini Omni 1.2 Flash が GA になりました(11/5)。最長15秒の動画生成と会話での編集に対応し、1.1 Flash は 12/3 に自動で 1.2 へ振り替わります●COMPUTER — Computer Use が Interactions / GenerateContent API で GA になりました(10/30)●LIVE — Live と TTS のプレビュー版は最短 11/17 に停止します(残り7日)。移行先は gemini-3.8-live と 3.8 系 TTS です●CLI — Gemini API CLI(gemini-api)がベータで登場(10/27)。エージェントやCI向けのゼロ依存クライアントです●2.5 PRO — gemini-2.5-pro と 2.5-flash は 12/1 から自動で振り替えられます(残り21日)。移行先は 3.8 Flash と 3.5 Flash-Lite です●NEW — クラッシュ報告を毎回ゼロから読ませない — 既知バグ早見表を先に grep し…
記事一覧/開発ツール
⟐ 開発ツール/2026-05-02初級

Google ADK の使い方 — 最初のAIエージェントを30分で動かすハンズオンチュートリアル

Google Agent Development Kit(ADK)を初めて触る方向けのハンズオンです。環境構築、フォルダ構成、エージェント本体の実装、adk web での起動と会話までを30分で完走できるよう、公式クイックスタートとの違いや、フォルダ・.env・root_agent まわりのつまずきも順に案内します。

gemini121adkagent-development-kitpython112tutorial5beginner7

先日、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 --version

adk: 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__.pyagent.py を読み込むための 1 行
weather_agent/agent.pyエージェント本体
weather_agent/.envAPI キー(次の手順で作ります)

__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"
INNER

YOUR_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 を再起動するところから始めていただければと思います。小さな変更が画面に反映されるのを一度見ておくと、そのあとの拡張がずっと楽になります。

シェア

お読みいただきありがとうございます

Gemini Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

もしこの記事がお役に立ちましたら、チップ(¥150)で応援いただけると大変励みになります。広告なしでの運営を続けるため、皆さまのご支援が大きな力になっています。

関連記事

⟐ 開発ツール2026-10-20
@config と打ったのに別のファイルが渡っていた? Gemini CLI の @ 参照が曖昧一致を黙って拾う件の確かめ方
Gemini CLI の @ 参照で、名前が曖昧なときに最初の一致だけが使われるという報告を読み、同名ファイルが複数ある場所で事故を防ぐために行った点検の手順を、小さな Python スクリプトと一緒に整理しました。
⟐ 開発ツール2026-10-06
Veo 3.1 の preview 3種が 10/22 に止まります。差し替えの前に、呼び出し箇所の棚卸しから始めました
Veo 3.1 の preview 3種は 10/22 に提供終了、移行先は gemini-omni-1.1-flash です。モデル名を置換する前に、リポジトリ内の呼び出し箇所を洗い出す検索スクリプトと、期日を過ぎたら黙って別モデルへ流れずに止まる設定の書き方をまとめます。
⟐ 開発ツール2026-09-15
承認ルールを書いたのに一度も一致していませんでした — policy を点検して回った記録
Gemini CLI の policy に書いた承認ルールが一度も一致していませんでした。照合対象が JSON 文字列だったこと、置き場所の階層が無効だったこと、無人実行で ask_user が deny になること。点検を機械化したスクリプトまで書き残します。