Google ADK評価・デプロイ実践ガイド2026

この記事では、GoogleのAgent Development Kit（ADK）を「作る」「評価する」「出す」の順に扱います。料金や性能ベンチマークのような数値は、公式ページで確認できないものを本文に入れません。代わりに、公式ドキュメントで確認できるコマンド、サポート範囲、評価観点、運用上の判断基準を中心に整理します。

Google ADKとは何か：プロトタイプではなく本番エージェントの土台

Google ADK公式トップは、ADKをオープンソースのエージェント開発フレームワークとして説明しています。単なるプロンプト実行ではなく、エージェントの構築、デバッグ、評価、デプロイを一続きで扱うための道具です。公式ページではPython、TypeScript、Go、Java、Kotlinの入り口が並び、Python 2.0 GA、graph workflows、collaborative agentsへの言及も確認できます。ここで重要なのは、言語の多さそのものではありません。エージェントがPoCから抜けるには、コード、セッション、メモリ、ツール出力、成果物を構造として扱う必要がある、という思想です。

ADKを選ぶ前に決める3つの境界

導入判断では、モデル性能の印象よりも境界設計を先に決めます。第一に、エージェントが呼んでよいツールの境界。第二に、評価で合格とみなす振る舞いの境界。第三に、どこまでをGoogle Cloud側のマネージド機能に任せ、どこからを自社のコンテナ運用に残すかという境界です。ADKはこの3つをコードと設定に落とし込みやすい反面、境界を曖昧にしたまま導入すると、評価できない自動化が広がります。

Python 2.0 READMEで確認できる注意点

google/adk-pythonのREADMEでは、ADK 2.0にagent API、event model、session schemaの破壊的変更があること、Python 3.11+が要件であることが示されています。既存の1.x系サンプルをそのまま社内標準にすると、セッション互換やイベント処理でつまずく可能性があります。新規プロジェクトなら2.0系前提でテンプレートを作る。既存プロジェクトなら、最初にセッション保存形式とイベント購読箇所を棚卸しする。ここを飛ばすと、評価やデプロイ以前にローカル実行の再現性が崩れます。

# 最小構成の例。実運用ではバージョン固定とロックファイルを必ず使う
python -m venv .venv
source .venv/bin/activate
pip install google-adk
python --version  # README上の要件は Python 3.11+

最小エージェントを作る：評価しやすい形から始める

公式トップのサンプルは、Agentにname、model、instruction、toolsを渡すシンプルな形です。実務でそのまま巨大化させるのではなく、最初は「入力を分類する」「検索する」「確認して回答する」のように、後から軌跡を検証できる単位に分けます。評価不能なエージェントの多くは、最初のファイルが便利すぎます。ひとつのinstructionに業務ルール、例外処理、口調、検索条件、承認条件を詰め込むと、失敗時にどの条件が壊れたかを追えません。

# capital_agent/agent.py のように、root_agent を明示しておく
from google.adk import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="policy_researcher",
    model="gemini-flash-latest",
    instruction=(
        "You research internal policy questions. "
        "First identify the policy domain, then search, then cite the source. "
        "If the source is not found, say that verification failed."
    ),
    tools=[google_search],
)

root_agentを固定する理由

Cloud RunのADKデプロイ手順では、Pythonの場合、エージェントコードがagent.pyにあり、変数名がroot_agentで、__init__.pyがfrom . import agentを含む構成が前提として説明されています。これは単なる命名規約ではありません。デプロイ時、テスト時、評価時に同じ入り口を参照するための契約です。チーム内でmain_agent、app_agent、agentなどが混在すると、ローカルでは動いたのにCIやCloud Runで読み込めない、という地味な事故が起きます。

ツールは少なく、名前は監査しやすく

ADKの評価では、エージェントがどのツールをどの順序で使ったかを確認する考え方があります。そのため、ツール名は監査ログで読める粒度にします。search、fetch、sendのように短すぎる名前より、lookup_policy_document、summarize_policy_section、draft_approval_requestのように役割が分かる名前のほうが評価しやすくなります。特に本番では、ツール名が権限境界にもなります。

評価設計：ADKで見るべきは最終回答だけではない

ADK公式の評価ページは、従来のソフトウェアテストとエージェント評価の違いを説明しています。生成モデルは確率的に振る舞うため、単純なpass/failだけでは不十分です。ADKでは、最終応答の品質だけでなく、エージェントが回答前にたどったtrajectory、つまりツール選択や中間ステップを見る発想が重視されています。これは現場感覚とも一致します。AIエージェントの事故は、最後の文章が少し変だったから起きるよりも、参照すべき情報を見ずに回答した、承認を飛ばした、間違ったAPIを呼んだ、という過程で起きるからです。

最初の評価ケースは1ターンでいい

評価を始めるときに、いきなり全業務フローを再現する必要はありません。公式ドキュメントは、単一のシンプルなagent-model interactionを表すテストファイルと、複数のセッションを含められるevalsetという2つの方向を示しています。開発中のユニットテストに近い用途なら小さなテストファイル、長い会話や複数ケースをまとめたいならevalset、という使い分けです。

{
  "eval_set_id": "policy_researcher_smoke_eval",
  "name": "policy researcher smoke eval",
  "description": "最初の1ケースだけを固定し、検索ツールの呼び出しと最終回答を確認する",
  "evals": [
    {
      "eval_id": "travel_policy_lookup",
      "conversation": [
        {
          "user_content": "海外出張の事前承認ルールを確認して",
          "expected_tool_use": ["google_search"],
          "reference_response": "事前承認が必要。根拠URLを添えて回答する。"
        }
      ]
    }
  ]
}

評価指標は目的別に選ぶ

ADKのEvaluation Criteriaページには、tool_trajectory_avg_score、response_match_score、final_response_match_v2、rubric_based_final_response_quality_v1、rubric_based_tool_use_quality_v1、hallucinations_v1、safety_v1などの指標が並びます。ここで全指標を一気に使う必要はありません。社内ナレッジ検索なら、まずツール軌跡と根拠性を重視する。問い合わせ返信なら、最終応答の品質と安全性を見る。業務代行なら、承認ステップを飛ばしていないかをツール利用のrubricで見る。指標は網羅よりも、失敗したときに直す場所が分かることを優先します。

目的	最初に見る指標	見る理由
検索・RAG系	tool_trajectory_avg_score / hallucinations_v1	参照すべき情報を見たか、根拠から外れていないかを確認するため
問い合わせ返信	final_response_match_v2 / safety_v1	意味が合っているか、危険な回答をしていないかを見るため
業務代行	rubric_based_tool_use_quality_v1	承認、確認、記録などの手順を飛ばしていないかを見るため
長い会話	multi_turn_task_success_v1	単発回答ではなく、会話全体で目的を達成したかを見るため

pytestとadk eval：CIに入れる評価の最小単位

公式評価ページでは、adk web、pytest、adk evalの3つの実行方法が示されています。UIで確認する段階ではadk webが便利です。しかし、チーム開発では、最低限のスモーク評価をpytestまたはCLIでCIに入れるほうが効果的です。毎回100ケースを回す必要はありません。プロンプト、ツール、依存パッケージ、モデル設定を変えたときに、最も壊れると困る3ケースだけを先に固定します。

# ローカルで評価を回すイメージ
# 実際のファイル名や引数はプロジェクトのADKバージョンに合わせて確認する
adk eval ./capital_agent ./evals/policy_researcher_smoke_eval.json

# CIでは、まずスモーク評価だけを必須にする
pytest tests/test_policy_researcher_eval.py

CIで落とす条件を狭くする

エージェント評価をCIに入れるときの失敗パターンは、最初から判定を厳しくしすぎることです。生成文の細かい語尾まで一致させると、モデル更新や軽微なプロンプト修正で毎回赤くなります。逆に、ツール利用や安全確認のような「外してはいけない手順」は厳しくします。たとえば、社内規程を回答するエージェントなら、根拠検索ツールを呼ばないケースは不合格。文章の言い回しはrubricで許容。こう分けると、CIが開発の邪魔ではなく安全網になります。

カスタムメトリクスを使う場面

ADKのCustom Metricsページでは、InvocationやEvalMetricを受け取り、EvaluationResultを返すPython関数として独自メトリクスを定義できると説明されています。標準指標で足りない場合、たとえば「社外送信前にapproval_requiredイベントが必ずある」「金額を含む回答では必ず根拠URLを含む」「PIIを検出したら送信ツールを呼ばない」のような社内ルールをメトリクス化できます。これはAI品質というより、業務統制のコード化です。

# my_agent/metrics.py の概念例。実プロジェクトではADKの現在の型定義に合わせて調整する
from google.adk.evaluation.eval_metrics import EvaluationResult, EvalStatus

def approval_step_exists(eval_metric, actual_invocations, expected_invocations=None, conversation_scenario=None):
    tool_names = []
    for invocation in actual_invocations:
        for call in getattr(invocation, "tool_uses", []) or []:
            tool_names.append(getattr(call, "name", ""))
    ok = "request_human_approval" in tool_names
    return EvaluationResult(
        overall_score=1.0 if ok else 0.0,
        overall_eval_status=EvalStatus.PASSED if ok else EvalStatus.FAILED,
        per_invocation_results=[]
    )

デプロイ先の選び方：Cloud Run、Agent Runtime、GKE

ADKのDeployページは、Agent Runtime、Cloud Run、GKE、その他コンテナフレンドリーなインフラを選択肢として示しています。ここでの判断軸は「どこが一番か」ではなく、「いまのチームがどこまで運用責任を持てるか」です。Cloud Runはコンテナベースで始めやすく、ADKドキュメントでもadk deploy cloud_runまたはgcloud run deployの流れが説明されています。Agent RuntimeはGoogle Cloud Agent Platform上のマネージドなランタイムとして、スケールやガバナンスを意識した本番向けの選択肢です。GKEはKubernetesの制御が必要な組織、あるいはより細かいネットワークや実行環境の要件がある場合に向きます。

選択肢	向いている状況	注意点
Cloud Run	小さく本番化したい、HTTPサービスとして扱いたい、コンテナ運用を最小化したい	Secret Managerやサービスアカウント権限を最初に整理する
Agent Runtime	Google Cloud Agent Platformの管理機能を使い、スケールとガバナンスを重視したい	有料サービスであり、プロジェクトとAPI有効化の前提を確認する
GKE	Kubernetes標準の運用、細かいネットワーク制御、既存クラスタ統合が必要	クラスタ、Artifact Registry、Cloud Build、権限の管理負荷が増える
その他コンテナ	自社基盤や閉域環境で動かしたい	ADK Web UIやAPIサーバーの含め方、ログ、ヘルスチェックを自前で決める

Cloud Runに出す前のファイル構成

Cloud RunのADKドキュメントでは、Pythonの場合、agent.py、root_agent、__init__.py、requirements.txtの存在が前提として説明されています。これはCIでもチェックできます。人間がレビューするより、リポジトリにテンプレートと検査スクリプトを置いたほうが早いです。特にrequirements.txtがない、__init__.pyが空、root_agentの名前が違う、というミスはデプロイ直前に見つかると時間を溶かします。

capital_agent/
  __init__.py        # from . import agent
  agent.py           # root_agent を定義
  requirements.txt   # google-adk などを明示

evals/
  policy_researcher_smoke_eval.json

tests/
  test_policy_researcher_eval.py

Cloud Runデプロイの基本コマンド

Cloud Runページでは、Python向けにadk deploy cloud_runが推奨コマンドとして示されています。環境変数としてGOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION、GOOGLE_GENAI_USE_VERTEXAIなどを設定する流れも確認できます。APIキーを使う場合でも、ソースコードやログに直書きせず、Secret ManagerやCI/CDのシークレット管理に寄せるのが前提です。

export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_GENAI_USE_VERTEXAI="True"
export AGENT_PATH="./capital_agent"

# Pythonでは公式ドキュメント上、adk deploy cloud_run が推奨経路として説明されている
adk deploy cloud_run   --project="$GOOGLE_CLOUD_PROJECT"   --region="$GOOGLE_CLOUD_LOCATION"   "$AGENT_PATH"

運用設計：評価、ログ、権限、ロールバックを先に置く

AIエージェントの本番運用で怖いのは、失敗したこと自体より、失敗がどこで起きたか分からない状態です。ADKを使う場合も、評価とデプロイだけでは足りません。セッションの保存、ツール呼び出しログ、モデル設定、プロンプトのバージョン、デプロイしたコンテナのリビジョンを結びつける必要があります。Cloud Runならリビジョン単位の切り戻し、GKEならDeploymentのロールアウト、Agent Runtimeならプラットフォーム側の管理機能を前提に、どの単位で戻すかを決めます。

ログに残すべき最小フィールド

ログは多ければよいわけではありません。個人情報やシークレットを残すと、あとで別のリスクになります。最低限、request_id、session_id、agent_version、model、tool_name、tool_result_status、evaluation_case_id、deployment_revisionを残します。本文全量やツール結果全量は、機密性に応じてマスクまたはサンプリングします。評価ケースIDとデプロイリビジョンを紐づけると、どの変更でどのケースが壊れたかを追いやすくなります。

権限はツールごとに切る

エージェントに広いサービスアカウントを渡すと、プロンプトの改善では解決できない事故が起きます。検索ツール、読み取りツール、書き込みツール、送信ツールを分け、それぞれ最小権限にします。人間承認が必要な操作は、ツール関数の中で承認トークンや状態を確認する設計にします。プロンプトに「承認を得てから実行して」と書くだけでは、評価と監査の境界になりません。

失敗パターン：Google ADK導入でよく起きるつまずき

失敗1：評価ケースが成功例だけ

❌ 成功する質問だけをevalsetに入れる。⭕ 境界例、禁止操作、情報不足、ツール障害を含める。エージェントは成功例ではなく、迷う場面で品質が出ます。社内規程が見つからない、APIが500を返す、ユーザーが曖昧な依頼をする、といったケースを最初から1つずつ入れておくと、PoC後の手戻りが減ります。

失敗2：最終回答だけを採点する

❌ 回答文が自然なら合格にする。⭕ 期待したツール軌跡を通ったかを見る。AIエージェントは、たまたま正しそうな文章を出すことがあります。社内DBを検索すべき場面で検索していないなら、不合格にするべきです。ADKの評価観点にtrajectoryがあるのは、この問題を避けるためです。

失敗3：Cloud Runに出してから秘密情報を考える

❌ GOOGLE_API_KEYや外部APIキーをローカルの.envからそのまま持ち込む。⭕ デプロイ前にSecret Manager、サービスアカウント、IAMロールを整理する。Cloud Runの公式手順でも、Google Cloudプロジェクト、ロケーション、サービスアカウント、シークレットへのアクセス権限が前提として出てきます。秘密情報の置き場所は、デプロイコマンドを書く前に決めます。

失敗4：ADK 1.xのサンプルを混ぜる

❌ 古いブログ記事のコードを混ぜて、セッションやイベントの違いを無視する。⭕ READMEで2.0の破壊的変更を確認し、プロジェクトのADKバージョンを固定する。特にsession schemaとevent modelに触れているコードは、あとで見つけると修正範囲が広がります。

失敗5：デプロイ先を技術趣味で選ぶ

❌ なんとなくKubernetesだからGKE、なんとなくマネージドだからAgent Runtimeにする。⭕ 運用責任、ネットワーク制約、権限管理、ロールバック要件で選ぶ。小規模なHTTPエージェントならCloud Runで十分なケースが多く、既存のKubernetes運用が強い会社ならGKEが自然です。プラットフォーム選定は、将来の監査と障害対応の作業量で見ます。

導入ロードマップ：2週間でPoCを本番候補に近づける

ADK導入は、最初から大きな自律エージェントを作るより、2週間で評価可能な薄い縦切りを作るほうが成功しやすいです。1日目から3日目はユースケースを1つに絞り、root_agentとツールを作る。4日目から6日目は、成功例、失敗例、禁止例の評価ケースを作る。7日目から9日目はCloud Runにデプロイし、ログと権限を確認する。10日目以降は、評価を増やすか、Agent RuntimeやGKEの要件を検討します。

期間	作業	完了条件
1〜3日目	最小エージェントとツール境界を作る	root_agent、requirements、README、ローカル実行手順が揃う
4〜6日目	evalsetとスモーク評価を作る	成功例、情報不足、禁止操作の最低3ケースが通る
7〜9日目	Cloud Runまたは検証環境に出す	Secret、IAM、ログ、ヘルスチェックが確認できる
10〜14日目	運用判断をする	継続評価、ロールバック、監査ログの責任者が決まる

社内テンプレートに入れるチェックリスト

• ADKバージョンとPythonバージョンをREADMEに明記する。
• root_agentの場所、ツール名、権限境界を固定する。
• 最低3件の評価ケースをCIまたは手動リリースゲートに入れる。
• Cloud Run、Agent Runtime、GKEのどれに出すか、選定理由をADRとして残す。
• シークレット、ログ、PIIマスク、ロールバック手順をデプロイ前に確認する。

関連記事・次に読む

ADKは単体で完結するというより、評価、デプロイ、ガードレール、運用監視の一部として使うと効果が出ます。次に読む記事として、AIエージェントの継続評価とCI/CD回帰検知を扱った運用ガイド、本番デプロイ全体を整理したデプロイ・サービング実践ガイド、入出力の安全フィルタリングを扱うLLMガードレール実装ガイドを合わせて確認してください。評価、デプロイ、安全性を別々に見るのではなく、同じリリースゲートで扱うのが実務では重要です。

よくある質問

Google ADKはLangChainやLangGraphの代替ですか？

完全な置き換えと考えるより、Google CloudやGemini系の開発・評価・デプロイと相性がよいエージェント開発基盤として見るのが安全です。既存資産がある場合は、評価とデプロイの境界から試すと判断しやすくなります。

ADKの評価は最初からLLM-as-a-Judgeを使うべきですか？

最初はツール軌跡や明確な禁止条件のような判定しやすい項目から始めます。意味的な品質やrubric評価が必要になった段階でLLM-as-a-Judgeを足すほうが、CIが安定します。

Cloud RunとAgent Runtimeはどちらから始めるべきですか？

小さなHTTPサービスとして検証するならCloud Runが始めやすいです。スケール、ガバナンス、Google Cloud Agent Platformの管理機能が重要ならAgent Runtimeを検討します。

サンプルコードをそのまま本番投入できますか？

できません。サンプルは構造理解のための入口です。本番ではシークレット管理、ツール権限、ログ、評価ケース、ロールバック手順を追加する必要があります。

評価ケースは何件から始めるべきですか？

件数より種類が重要です。成功例、情報不足、禁止操作の3種類をまず固定し、その後に実ユーザーの問い合わせログから増やします。

参考・出典

1. Google ADK公式トップ（参照日: 2026-06-09）
2. Google ADK Get started（参照日: 2026-06-09）
3. Google ADK Evaluation（参照日: 2026-06-09）
4. Google ADK Evaluation Criteria（参照日: 2026-06-09）
5. Google ADK Custom Metrics（参照日: 2026-06-09）
6. Google ADK Deploy（参照日: 2026-06-09）
7. Google ADK Cloud Run Deploy（参照日: 2026-06-09）
8. Google ADK Agent Runtime Deploy（参照日: 2026-06-09）
9. google/adk-python README（参照日: 2026-06-09）

まとめ：ADK導入は「評価できる最小単位」から

Google ADKは、AIエージェントを作るための便利なSDKというだけでなく、評価とデプロイを開発プロセスに組み込むための土台です。最初の一歩は、派手な自律化ではありません。root_agentを固定し、ツール境界を小さくし、evalsetを1つ作り、Cloud RunまたはAgent Runtimeへ出す最小経路を再現可能にすることです。そこまでできると、次に足すべきものが見えます。評価ケースを増やすのか、カスタムメトリクスを足すのか、Agent Runtimeへ移すのか、GKEで既存基盤に寄せるのか。判断を感覚ではなく、テストと運用要件で進められるようになります。