ADK を理解する

AI要約#

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

ADK とは#

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

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

ADK の基本要素#

Agent	`LlmAgent` ,`SequentialAgent`, `ParallelAgent`, `LoopAgent`
Tool	外部APIとの連携・情報の検索・コードの実装など
Callbacks	エージェントの処理の特定の時点で実行されるように提供するカスタムコードスニペット
Session 管理	`Session`& `State` 会話コンテキストを処理。State は短期的なセッション
Memory	長期的なコンテキストを提供
Artifact 管理	エージェントがセッションまたはユーザーに関連付けられたファイルまたはバイナリデータ（画像、PDFなど）を保存、読み込み、管理できるようにする
Models	基盤となるLLM
Event	セッション中に発生する事象（ユーザーメッセージ、ツールの使用など）を表す基本的なコミュニケーション単位
Runner	実行フローを管理し、イベントに基づいてエージェント間のやり取りを調整。バックエンドサービスと連携するエンジン。

主要機能#

マルチエージェント設計

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

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

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

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

状態・メモリ管理

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

Session, State, Memory について#

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

基本概念#

Session	会話スレッド。エージェントが行ったメッセージやアクションの時系列が含まれる (Events) 。一時データ (State) も保持できる
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 を提供しており、最適なストレージバックエンドを選択できる

	`InMemorySessionService`	`VertexAiSessionService`	`VertexAiSessionService`
仕組み		セッション管理には、API呼び出しを介してGoogle Cloud Vertex AIインフラストラクチャを使用	RDBに接続し、セッションデータをテーブルに永続的に保存
永属性	なし	あり。データはVertex AI Agent Engine ↗によって管理	あり
用途	ローカルテスト・サンプル作成など	Google Cloud上にデプロイされたスケーラブルな本番環境アプリケーション	信頼性が高く、永続的なストレージを自分で管理する必要があるアプリケーション

Session ライフサイクル#

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

長期ナレッジ MemoryService#

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

MemoryService の役割#

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

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

特徴	インメモリメモリサービス	VertexAiMemoryBankService
永属性	なし（再起動時にデータが失われる）	あり（Vertex AIが管理）
主な使用例	プロトタイピング、ローカル開発、および簡単なテスト	ユーザーとの会話から、有意義で進化し続ける記憶を構築する
メモリ抽出		会話から有意義な情報 ↗を抽出し、既存の記憶と統合
検索機能	基本的なキーワードマッチング	高度なセマンティック検索
セットアップの複雑さ	なし。デフォルト設定	低負荷。Vertex AI のエージェントエンジンインスタンスが必要です。 ↗
依存関係	なし	Google Cloudプロジェクト、Vertex AI API
いつ使うべきか	プロトタイプ作成のために、複数のセッションのチャット履歴を横断的に検索したい場合	エージェントに過去のやり取りを記憶させ、そこから学ばせたい場合

コールバックについて#

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

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

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

監視・デバッグ

重要なステップで詳細な情報をログに記録
カスタマイズ・制御

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

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

実行中にエージェントのセッション状態を読み取り、動的に更新
統合と機能強化

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

ベストプラクティス#

設計原則

スコープを絞る

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

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

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

エラーを適切に処理する

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

State 管理

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

信頼性

冪等性を考慮する

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

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

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

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

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

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

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

Web UI によるデバッグ#

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

Events ビュー#

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

Trace ビュー#

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

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

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

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

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

TABLE OF CONTENTS