Google ADK の使い方

「Google ADK が良いらしいと聞いたものの、ドキュメントを開いた瞬間にエージェント・ツール・セッション・ランナーといった用語が一気に出てきて手が止まってしまった」— そんな声をよく耳にします。私自身も最初に触れたときは、adk web コマンドが何を起動しているのか、Runner と Session の役割分担は何なのかが、コード例だけでは掴みきれませんでした。

このチュートリアルは、ADK を「とにかく動かすまで」を最短で完走することだけを目的にしています。理屈の説明は最小限にとどめて、コピー&ペーストで動くコードと、つまずきやすい順番に並べた手順をお渡しします。30分後には、ご自身のターミナルで「天気を答えるエージェント」が動いている状態を目指します。

このチュートリアルで作るもの

最終的に動かすのは、ユーザーが「東京の天気は？」と尋ねると、get_weather というツール（Pythonの関数）を自動で呼び出して、その結果をもとに自然な文章で答えてくれる小さなエージェントです。実際の天気APIには接続せず、ダミーのデータを返す関数を用意します。これは「AIモデル → ツール呼び出し → 結果の整形」という ADK の基本パターンを最短で体感するためです。

このパターンさえ理解できれば、get_weather を「在庫を調べる関数」「データベースに書き込む関数」「Slack に投稿する関数」に置き換えるだけで、業務に直結する自動化エージェントへ拡張できます。

Step 1: 環境を整える（5分）

ADK は Python 3.10 以上で動作します。仮想環境を新しく作って、その中にインストールするのが安全です。

# 作業フォルダを作って仮想環境を有効化
mkdir adk-tutorial && cd adk-tutorial
python -m venv .venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate
 
# ADK 本体をインストール
pip install google-adk
 
# 動作確認（バージョンが表示されればOK）
adk --version

adk: command not found と表示される場合は、仮想環境の有効化に失敗しているか、pip が別の Python を見ている可能性が高いです。which python と which pip の出力先が同じ仮想環境内になっているかをまず確認してみてください。

次に、API キーを環境変数として登録します。Google AI Studio の左メニューから無料で発行できます。

# .env ファイルを作成（後で adk web が自動で読み込みます）
cat > .env << 'INNER'
GOOGLE_API_KEY=YOUR_GEMINI_API_KEY
INNER

「YOUR_GEMINI_API_KEY」の部分を、ご自身が発行した実際のキーに置き換えてください。.env ファイルは絶対に Git にコミットしないよう、.gitignore に .env を追加しておくと安心です。

Step 2: フォルダ構成を作る（3分）

ADK は「フォルダ名 = エージェント名」というルールで動きます。少し独特ですが、最初に押さえておくと後の adk web コマンドで戸惑いません。

# weather_agent という名前のエージェント用フォルダを作成
mkdir weather_agent
cd weather_agent
 
# 必要なファイルを2つ作成
touch __init__.py agent.py

ここまでで、フォルダ構成は次のようになっています。

adk-tutorial/
- .env — API キー
- weather_agent/ — エージェント本体（フォルダ名がそのままエージェント名になります）
  - __init__.py — agent.py を import するための空に近いファイル
  - agent.py — メインのコード

__init__.py には、たった1行だけ書きます。

# weather_agent/__init__.py
from . import agent

この import 行がないと、adk web を起動したときにエージェントが認識されません。これは ADK の小さな落とし穴のひとつで、私も最初の起動で「エージェントが見つかりません」のメッセージに5分ほど悩みました。

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-2.5-flash",
    description="日本国内の天気を答える小さなアシスタント。",
    instruction=(
        "あなたは天気案内のアシスタントです。"
        "ユーザーから都市名を聞かれたら、必ず get_weather ツールを呼んで結果を取得し、"
        "その結果を日本語で自然な一文にまとめて答えてください。"
    ),
    tools=[get_weather],
)

ここで一番大事なのは、変数名を必ず root_agent にすることです。ADK は起動時にこの名前の変数を探します。agent や weather_agent という名前にすると、UI 上に何も表示されず、エラーメッセージも出ないため原因にたどり着きにくいです。

もうひとつ大切なのは、get_weather 関数の docstring（三重引用符の中身） です。ADK は docstring を読んで「この関数は何ができるのか」を Gemini に伝えます。docstring が空っぽだと、モデルがツールを呼ぶタイミングを判断できず、せっかく定義した関数が無視されてしまいます。

Step 4: 起動して会話してみる（5分）

ファイル構成と実装が揃ったら、いよいよ起動です。プロジェクトのルート（adk-tutorial/）に戻ってから実行するのがポイントです。

# weather_agent フォルダのひとつ上の階層に戻る
cd ..
 
# Web UI を起動
adk web

http://localhost:8000 がブラウザで開きます。左上のドロップダウンから weather_agent を選んで、チャット欄に次のように打ち込んでみてください。

東京の天気を教えて

うまくいけば、画面上には「東京は現在22℃で晴れています」のような返答が表示され、画面右側の「Trace」タブで get_weather ツールが呼ばれていることが確認できます。Trace タブは、エージェントが「どの順番で考え、どのツールを呼び、どんな引数を渡したか」が時系列で見えるため、デバッグの強力な味方です。

つまずきやすいポイントと対処

私自身が最初の30分で踏んだ落とし穴を、そのまま共有します。

「エージェントが見つかりません」と表示される: adk web を weather_agent/ の中で実行している可能性があります。必ずひとつ上の階層（adk-tutorial/）から起動してください。
ツールが呼ばれずモデルが勝手に答える: 関数の docstring が空、または「天気を返す」程度の薄い説明になっていることが原因です。引数・戻り値・使いどころを具体的に書き直すと、モデルがツールを使うようになります。
gemini-2.5-flash でレート制限に当たる: 無料枠は1分あたりのリクエスト数に上限があります。連続で試したい場合は time.sleep(2) を挟むか、Google AI Studio で上限を確認してから設計しましょう。
環境変数が読み込まれない: .env がプロジェクトルートに置かれていないと adk web は読みません。weather_agent/ の中ではなく、その親フォルダに置いてください。

次のステップ — 実用エージェントへの拡張

「動いた」ことが確認できたら、次は実用に寄せていきましょう。私が初心者の方におすすめしている順番は次のとおりです。

第一歩は、get_weather を本物の関数に置き換えることです。たとえば、お手元のCSVから情報を読む、社内APIに問い合わせる、Slackに投稿する、といった現場の作業を関数化してツールとして渡すだけで、いきなり業務エージェントになります。

複数のツールを使い分けたい段階に来たら、Google ADK × Python マルチエージェント開発ガイド — 複数AIエージェントが連携するシステムの設計と実装で扱っているマルチエージェント構成が役立ちます。役割の異なるエージェントを連携させると、単一エージェントでは対処しきれない複雑な業務フローを綺麗に分解できます。

本番運用に進む段階では、エラー処理や監視の仕組みが避けて通れません。Google ADK のコールバックとガードレール — 本番運用エージェントの監視設計では、コールバックを使った安全装置の入れ方を解説しています。

全体を振り返って

最初の一歩で大事なのは、完璧な構成を作ることではなく、「自分の手元で確かに動いた」という実感を持つことだと考えています。ADKは抽象度が少し高めのフレームワークなので、最初は概念に圧倒されがちですが、__init__.py、root_agent、docstring の3つを押さえておけば、最低限のエージェントはだいたい立ち上がります。

このチュートリアルを動かし終えたら、ご自身の業務で「いつも手作業でやっている小さな繰り返し」をひとつ思い浮かべて、それを get_weather の代わりにツールとして渡してみてください。たぶんそれが、あなたにとって本当に価値のある最初のエージェントになります。

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