はじめに
Google の Agent Development Kit（ADK）でエージェントを開発していると、動作確認に組み込みの Web UI を使いたくなる場面が多いと思います。
adk web コマンドで手軽に開発サーバーが立ち上がるのは便利なのですが、リモートの開発サーバー上で実行すると、手元のブラウザからアクセスできないという問題に直面することがあります。
この記事では、その原因と解決策をまとめます。
ADK の Web UI とは
ADK（Agent Development Kit）は Google が公開している AI エージェント向けの開発キットです。Python をはじめ複数の言語に対応しており、Gemini 以外のモデルとも組み合わせて使うことができます。
ADK には、エージェントのテスト・デバッグ用にブラウザベースの Web UI が付属しています。adk web を実行するとローカルに開発サーバーが起動し、チャット画面からエージェントと対話できます。あくまで開発専用ですが、動作確認には非常に重宝します。
問題：デフォルトでは外部からアクセスできない
adk web はデフォルトで 127.0.0.1（ループバックアドレス）にしか bind しません。これはそのマシン自身からしかアクセスできないことを意味します。
リモートサーバー上で開発している場合、サーバーのブラウザを直接操作するわけにもいかず、手元の PC から確認できないのは地味に不便です。
解決策：--host 0.0.0.0 を指定する
起動時に --host オプションを指定するだけで解決します。
adk web --host 0.0.0.0 --port 8000 <エージェントのディレクトリ>
0.0.0.0 を指定することで、すべてのネットワークインターフェースで待ち受けるようになり、外部からサーバーの IP アドレスに直接アクセスできるようになります。
実際の手順
-
開発サーバーに SSH でログイン
-
サーバー上で以下を実行
adk web --host 0.0.0.0 --port 8000 -
手元の PC のブラウザで以下を開く
http://<サーバーのIPアドレス>:8000
これだけで、リモート環境で動く ADK エージェントをローカルのブラウザから操作できるようになります。
注意点
セキュリティに気をつける
0.0.0.0 でバインドすると、同一ネットワーク上のホストはもちろん、ファイアウォールが開いていればインターネット越しにもアクセスが可能になります。クラウド環境で使う場合は、セキュリティグループやファイアウォールで接続元 IP を制限することを強くおすすめします。
SSH トンネルという代替手段もある
セキュリティが心配な場合は、0.0.0.0 を使わずに SSH トンネルを利用する方法もあります。
ssh -L 8000:localhost:8000 ユーザー名@<サーバーのIPアドレス>
このコマンドを手元の PC で実行した状態で http://localhost:8000 にアクセスすると、SSH 経由でリモートサーバーのポートにトンネリングされます。通信が SSH で暗号化されるため、0.0.0.0 でポートを開放するより安全です。状況に応じて使い分けてください。
| 方法 | メリット | デメリット |
|---|---|---|
--host 0.0.0.0 |
設定が簡単 | ポートが外部に露出する |
| SSH トンネル | 安全・ポート不要 | SSH セッションの維持が必要 |
おわりに
--host 0.0.0.0 を付けるだけのシンプルな Tips ですが、リモート開発時には地味に効いてくるオプションです。
SSH トンネルと使い分けながら、快適な ADK 開発ライフを送りましょう！