ADK を理解する

AI要約#

この記事は、大体の文章を主に公式ドキュメントから拝借しつつ、実際に動かしてみた情報をまとめています。 https://adk.dev/ ↗

ADK とは#

Google Agent Development Kit (ADK) は、AIエージェントを効率的に構築・管理・評価・デプロイするためのオープンソースフレームワーク。

エージェント開発用の柔軟な環境を提供している。

ADK の基本要素#

主要機能#

マルチエージェント設計

• 複数の専門エージェントで構成されるアプリケーションを簡単に構築できる

Google エコシステムとの相性の良さ

• GeminiやVertex AI, BigQueryなど AIとのシームレスな連携とのシームレスな連携が可能
• Cloud Run へのデプロイも簡単

柔軟なオーケストレーション

状態・メモリ管理

• 短期的会話の内容(Session , State ) や長期的記憶( Memory ) を管理するためのサービスを提供

Session, State, Memory について#

ADK は、session、State、Memoryを通して、コンテキストを管理するための構造化された方法を提供している。

基本概念#

サービス#

ADKは、上記の概念を管理するためのサービスを提供。

SessionService

さまざまな会話スレッド（Session オブジェクト）を管理

• 個々のオブジェクトの作成、取得、更新（Events追加、State変更）、Session削除を行う

MemoryService

長期ナレッジ(Memory)を管理

• クエリに基づいて、この保存されたナレッジを検索する方法を提供

両方のサービスに インメモリ実装 が提供されている。ローカルのテスト・開発のために設計されている。 このインメモリで保存されたデータ(セッション、State、長期ナレッジ**)**はアプリケーションが再起動すると失われる

クラウドベースおよびデータベースサービス のオプションも提供している

Session 詳細#

https://adk.dev/sessions/session/ ↗

識別情報（id, appName, userId）

会話のための一意なラベル

• id: 会話スレッドに割り当てられたユニークな識別子で
• appName: 会話がどのエージェントアプリケーションに属するものかを識別
• userId: 会話を特定ユーザーに紐づける

SessionService#

様々な SessionService を提供しており、最適なストレージバックエンドを選択できる

Session ライフサイクル#

https://adk.dev/sessions/session/#the-session-lifecycle ↗

長期ナレッジ MemoryService#

エージェントが参照できる検索可能なアーカイブまたは知識ライブラリのようなもの。過去の多くのチャットやその他のソースからの情報が含まれる

MemoryService の役割#

• 情報の取り込み
• 情報の検索

適切なメモリーサービスを選ぶ#

コールバック について#

特定の定義済みポイントでエージェントの動作を監視、カスタマイズ、制御することができる

関数を定義し、ADKフレームワークは、これらの関数を自動的に呼び出す。

コールバックの利用用途#

• 監視・デバッグ

  重要なステップで詳細な情報をログに記録

• カスタマイズ・制御

  エージェントを介して流れるデータ（LLMリクエストやツール結果など）を変更したり、独自のロジックに基づいて特定の手順を完全にスキップしたり

• ガードレールを実装する

  安全規則を強制し、入出力を検証し、許可されていない操作を防止

• 状態の管理

  実行中にエージェントのセッション状態を読み取り、動的に更新

• 統合と機能強化

  外部アクション（API呼び出し、通知）をトリガーしたり、キャッシュなどの機能を追加したり

ベストプラクティス#

設計原則

スコープを絞る

• 各コールバックは、単一の目的（例：ログ記録のみ、検証のみ）で設計する。単一のコールバックが多用されるような構成は避ける。

パフォーマンスに関する注意

• コールバックはエージェントの処理ループ内で同期的に実行される。長時間実行される処理やブロッキング処理（ネットワーク呼び出し、負荷の高い計算など）は避ける。

エラーを適切に処理する

• エラーを適切にログに記録する
• エージェント呼び出しを停止するか、回復を試みるかを決定する
• コールバックエラーによってプロセス全体がクラッシュしないようにする

State 管理

• 読み取り・書き込みは慎重に行う
• 永続的な SessionService の実装では、明確化のために状態プレフィックス の使用を検討する
  • State.APP_PREFIX, State.USER_PREFIX, State.TEMP_PREFIX

信頼性

• 冪等性を考慮する

テスト・ドキュメント作成

• コールバック関数の単体テスト・結合テストを行う
• エージェントフロー全体で正しく機能するように

適切なコンテキストタイプを利用する

• Agent/Model のための CallbackContext
• Tools のための ToolContext

エージェントを実行する方法#

以下の3つの方法でエージェントを実行できる

1. Web UI を利用してブラウザベースで実行
2. adk run でコマンドラインで実行
3. adk api_serverRESTful API経由でエージェントを実行

Web UI によるデバッグ#

ADK には Web UI 機能がある。これを使うことで、エージェントの内部的な動作を詳細に追跡できる

Events ビュー#

発生したすべての Event を時系列に沿ってリストアップするビュー

Trace ビュー#

処理の全体像を階層的に把握しやすくしたビュー。 処理フローの把握やボトルネックの特定に有効

エージェント評価を行う#

エージェントの評価、評価データセットの生成、エージェントの動作の詳細な検査を行うことができる

https://adk.dev/evaluate/#how-to-run-evaluation-with-the-adk ↗

期待に近い結果をテストケースとして保存しておき、プロンプトチューニングの際の評価に利用することが可能

エージェントをデプロイする#

ADK で構築したエージェントは、Agent Runtime や Cloud Run などのクラウドサービスにデプロイできる

Agent Runtime と Cloud Run#

2026年4月、Vertex AI Agent Engine は Gemini Enterprise Agent Platform の一部として Agent Runtime にリネームされた。

ADK のデプロイ先としての Agent Runtime と Cloud Run の違い

コスト・料金の観点#

Agent Runtime の料金

コロコロ変わるので料金の詳細は Gemini Enterprise Agent Platform 料金ページ ↗ を参照。

Cloud Run の料金

リクエストがない間はインスタンスがゼロにスケールし、課金も止まる。

判断基準 デフォルトは Agent Runtime を使う。以下のケースでは Cloud Run を使う。

• Web UI をエージェントと一緒にデプロイしたい場合（--with_ui）
• Dockerfile などカスタムコンテナ設定が必要な場合
• 既存の Cloud Run インフラに乗せたい場合

Session 管理の違い#

ローカル開発時は InMemorySessionService がデフォルトで使われる。セットアップ不要でそのまま動かせるが、アプリを再起動するとすべてのセッションデータが失われる。

Agent Runtime にデプロイすると、SessionService として VertexAiSessionService が自動で使われるようになる。開発時のコードをそのまま持ち込める設計になっており、Vertex AI のインフラがセッションを永続管理してくれる。

Cloud Run にデプロイする場合は、SessionService を自分で選んで設定する必要がある。DatabaseSessionService か、明示的に VertexAiSessionService を指定する。

# ローカル開発: InMemorySessionService（デフォルト）
from google.adk.sessions import InMemorySessionService
session_service = InMemorySessionService()

# Cloud Run: 永続化が必要な場合は自分で設定
from google.adk.sessions import DatabaseSessionService
session_service = DatabaseSessionService(
    db_url="sqlite+aiosqlite:///./sessions.db"
)

# Cloud Run: Vertex AI に任せる場合
from google.adk.sessions import VertexAiSessionService
session_service = VertexAiSessionService(
    project="your-project", location="us-central1"
)

Cloud Run へのデプロイ#

adk deploy cloud_run \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --service_name=my-agent \
  --with_ui \
  /path/to/agent

デプロイの流れ

1. ADK がエージェントコードをパッケージング
2. コンテナイメージをビルドして Artifact Registry にプッシュ
3. Cloud Run にデプロイ
4. 公開 URL を返す