はじめに

私たちのプロダクトチームでは、AI Agentの開発にGoogle ADK (Agent Development Kit)を利用しています。過去に開発したエージェントを段階的に成長させる形でバージョンアップを行っていますが、その過程で少しニッチなエラーに遭遇し、デプロイがブロックされる事象が発生しました。

今回は、その原因と解決策について備忘録を兼ねてまとめます。

起きた問題：アップデート後にSmoke Testが404エラーで落ちる

私たちは Argo Rollouts を利用してデプロイを行っており、AnalysisTemplate を用いたスモークテストを自動実行しています。このスモークテストは、実際に本番相当のアプリケーションを Kubernetes Job として起動し、そこに対して curl でリクエストを投げて正常に応答するかを検証するものです。

具体的には、対象のエージェントに対して以下のような curl コマンドを実行していました。

curl -f -X POST \
  http://hoge-agent-preview-svc.../a2a/hoge_agent

しかし、ADKのバージョンを最新の 2.2.0 に更新したところ、この curl が 404 Not Found で失敗し、Rollout の pre-promotion analysis が通らなくなってしまいました。

ログを確認すると、A2A（Agent-to-Agent）エンドポイントに対する POST が失敗している状態でした。

curl: (22) The requested URL returned error: 404

通常の /run やセッション系の API、およびヘルスチェック（/healthz など）は正常に応答しているため、「なぜか A2A のスモークテストだけが落ちる」という非常に原因が特定しづらい状況に陥りました。

原因：ライブラリ内部での `UnboundLocalError` とルーティング登録の失敗

原因を突き止めるため、google-adk 2.2.0 のソースコード（google/adk/cli/fast_api.py）を確認したところ、A2A ルートの登録処理部分に問題があることが分かりました。

該当の関数内では、前半部分で agent.json を読み込む処理が行われています。

# 関数の前半
data = json.load(f)
agent_card = AgentCard(**data)

しかし、同じ関数の後半部分に import json が記述されていました。

Python の仕様では、「関数内で代入やインポートが行われている変数は、その関数全体でローカル変数として扱われる」というルールがあります。そのため、前半の json.load(f) を実行しようとした時点で、Python はグローバルにインポート済みの json ではなく、まだ初期化されていないローカル変数の json を参照しようとしてしまいます。

結果として、内部で UnboundLocalError（に類するエラー）が発生していました。

これにより ADK 内部で A2A エージェントのルーティング登録処理自体がクラッシュし、/a2a/hoge_agent というパスが作成されなかったのが 404 エラーの真相でした。

解決方法：バージョンの一時的な固定と依存関係の明示

根本的な原因が google-adk 2.2.0 内部のバグ（実装漏れ・考慮漏れ）であると判明したため、今回は ADK のバージョンを 2.1.0 にロールバックして固定する 運用回避を選択しました。

これにより、/a2a/hoge_agent が再び FastAPI のルートとして正常に登録され、AnalysisTemplate のスモークテストも無事に通過するようになりました。

また、google-adk 2.1.0 を安定して動作させるための依存ライブラリとして、sse-starlette を明示的に追加しています。

# pyproject.toml (抜粋)
dependencies = [
    "google-adk[a2a,gcp]>=2,<3",
    "aiohttp>=3.12.15",
    "python-json-logger>=3.3.0",
    "opentelemetry-instrumentation-logging>=0.59b0",
    "sse-starlette>=3.4.4",
]

pyproject.toml 上の表記は google-adk[a2a,gcp]>=2,<3 のままですが、パッケージマネージャー（uv）のロックファイル（uv.lock）側で、明確に google-adk == 2.1.0 に固定する運用としています。