本ドキュメントは、GoogleのAgent Development Kit (ADK) を用いたLLMエージェント開発の学習リポジトリ「agent-development-kit」の仕様書、設計書、および開発工程をまとめた技術文書である。エージェントの基礎から、高度なマルチエージェント・オーケストレーション、永続化、ワークフロー設計までを体系的にカバーする。
本プロジェクトは、GoogleのGeminiモデルを最大限に活用したLLMエージェント構築フレームワーク「ADK」の習得を目的とする。単一の応答を行うエージェントから、ツール利用、セッション管理、そして複数の専門エージェントが協調して動作する複雑なシステムまで、段階的なサンプルを通じて実践的なエージェント開発手法を提供する。
- 多様なエージェント・パターン: 逐次実行（Sequential）、並列実行（Parallel）、ループ（Loop）などの多様なワークフローの実装。
- ツール・エージェント: 関数呼び出し（Function Calling）を介した外部システム（時刻取得、システム監視、リマインダー作成等）との連携。
- 構造化出力: Pydanticモデルを用いた
output_schema定義により、LLMからの応答を厳密なJSON形式で取得。 - セッションと状態管理:
InMemorySessionServiceおよびDatabaseSessionServiceによる、会話履歴とユーザー固有の状態（State）の維持。 - マルチエージェント・システム: 親エージェントから専門のサブエージェント（販売、サポート、ポリシー、注文等）へのタスク委譲（Delegation）。
- CLI・Webインターフェース:
adk webによる対話型UI、adk runによる端末実行、adk api_serverによるAPI提供。
- 永続化対応: PostgreSQLおよびSQLiteをサポートし、アプリケーション再起動後も状態を保持。
- 抽象化: LiteLLMとの統合により、LLMプロバイダーの柔軟な切り替えが可能。
- 発見容易性: 特定のディレクトリ構造（
__init__.py,agent.py,root_agent変数）に従うことで、ADKツールが自動的にエージェントをロード。 - 実用的なドキュメント: 各ステップに詳細なREADMEを配置し、学習のステップアップを支援。
- GeminiおよびGoogle AI Studioを活用したいAIエンジニア
- 自律型エージェントやマルチエージェント・オーケストレーションを構築したい開発者
- 実践的なLLMワークフロー設計（並列・逐次処理）を学びたい層
本プロジェクトは、機能ごとに独立した12以上のエグザンプル・モジュールで構成される：
- Core Agent:
LlmAgentを核とした推論、意思決定、応答生成。 - Workflow Management: Sequential（直列）, Parallel（並列）, Loop（反復）エージェントによる制御フロー。
- State & Session:
ToolContextを通じた状態の読み書きと、データベースによる永続化層。 - Delegation Layer: メインエージェントからサブエージェントへのコンテキスト共有を伴う委譲。
agent-development-kit/
├── 1_basic_agent/ # 最小構成のエージェント
├── 4_structured_outputs/ # Pydanticによる型定義
├── 8_stateful_multi_agent/# 状態を共有するマルチエージェント
├── 11_parallel_agent/ # 並列処理ワークフロー
├── persistent_storage_*/ # 各種DBによる永続化の実装例
└── (他、計12以上のカテゴリ)
- Session State: 各ユーザーセッションごとに保持される辞書型データ。
user_name,interaction_history,purchased_coursesなどの動的なデータを管理。
- Storage Backends:
InMemorySessionService: 開発・テスト用のメモリ内ストレージ。DatabaseSessionService: SQLAlchemyを介したPostgreSQL/SQLite等のRDBへの永続化。
- エージェント構成:
instruction（指示）、model、tools、sub_agents（委譲先）を定義。 - プロンプト・インジェクション:
{user_name}や{generated_code}のように、セッション状態をプロンプトに動的に埋め込む仕組み。 - ツール: Python関数として定義し、
ToolContextを通じてエージェントの状態にアクセス・更新が可能。
- 各エージェント（挨拶、監視、コード生成等）が果たすべきペルソナとゴールの策定。
- 必要なツール（システム情報の取得、リマインダー登録等）のインターフェース定義。
- ワークフロー（単一推論、並列情報収集、またはレビュー・修正のループ）の選択。
- エージェント間で引き継ぐべき「状態（State）」のデータ構造設計。
- プロンプト・インストラクションの言語化（役割、制約、出力形式の定義）。
uvを用いた仮想環境の構築と依存パッケージの管理。agent.pyにおけるroot_agentの定義と、sub_agentsフォルダでの部品化。tools.pyによる実処理の実装とToolContextの統合。.envファイルによる APIキーおよび接続情報の管理。
adk webを起動し、Web UI上でのプロンプト応答精度およびツール実行の検証。adk run <agent_name>によるCLIベースの動作確認。- 永続化ストレージ（SQLite/Postgres）へのデータ保存と、再起動後の復元テスト。
DatabaseSessionServiceによる本番用データベース接続設定の適用。- エージェントの応答（Callbacks）をフックしたモニタリングの実装。
- Dockerコンテナ化によるデプロイ環境の一貫性確保。