google-adk

Google Agent Development Kit（ADK）スキル

目的

Google の Agent Development Kit（ADK）を使用して、エージェント型アプリケーションとマルチエージェントシステムを開発するための専門的なガイダンスを提供します。AI アシスタントが、エージェントの設計、ツールの構築、マルチエージェントワークフローのオーケストレーション、メモリ／状態管理の実装、コードファーストの開発パターンに従ったエージェントベースのアプリケーションのデプロイを行えるようにします。

このスキルを使用する場面

次のような場合に、このスキルを呼び出してください。

• ツール統合を備えた会話型 AI エージェントを構築する場合
• マルチエージェントのオーケストレーションシステムを作成する場合
• ワークフローエージェント（逐次、並列、反復）を開発する場合
• エージェント向けのカスタムツールを実装する場合
• 複雑なタスク向けにエージェントアーキテクチャを設計する場合
• エージェントアプリケーションを本番環境にデプロイする場合
• エージェントのパフォーマンスや動作を評価する場合
• ヒューマン・イン・ザ・ループのパターンを実装する場合

次の場合は、このスキルを使用しないでください。

• 一般的な Python 開発（Python 専用スキルを使用してください）
• シンプルな REST API の開発（ADK はエージェント型システム向けです）
• フロントエンド開発（ADK はバックエンドのエージェントフレームワークです）
• エージェントオーケストレーションを伴わない LLM API の直接利用（LLM プロバイダーの SDK を使用してください）
• Python 以外のエージェントフレームワーク（LangChain、CrewAI、AutoGPT は異なるパターンを使用します）

ADK の主要概念

プラットフォームアーキテクチャ

フレームワークの理念：

• コードファーストのアプローチ — エージェントを Python コードで定義します（YAML／JSON 設定ファイルではありません）
• モデル非依存 — Gemini 向けに最適化されていますが、他の LLM もサポートします
• 合成可能 — シンプルなエージェントの基本要素から複雑なシステムを構築します
• 可観測性 — トレースおよびモニタリングツールとの統合機能を内蔵しています

サポート対象の言語：

• Python（主要言語、最も成熟）— google-adk パッケージ
• Go（利用可能）— adk-go リポジトリ
• Java（利用可能）— adk-java リポジトリ

実行環境：

• Python 3.9 以降が必要です
• デプロイには Agent Engine を使用します（コンテナ化された実行環境）
• 開発／テスト用の Web UI（Angular + FastAPI）
• 評価およびデプロイ操作用の CLI

エージェントの種類と階層構造

1. LlmAgent（動的、モデル駆動型）

用途：

• 会話型インターフェース
• 不確実性を伴う意思決定
• 自然言語理解
• 創造的なタスク（コンテンツ生成）
• 文脈に基づく推論

特徴：

• 意思決定に LLM を使用します
• 実行は非決定的です
• ツールの選択はモデルによって行われます
• 曖昧な入力にも対応します

2. ワークフローエージェント（決定論的、プログラム駆動型）

逐次エージェント：

• ツールを固定された順序で実行します
• 用途：依存関係のある複数ステップのプロセス
• 例：データパイプライン（取得 → 変換 → 読み込み）

並列エージェント：

• 複数のツールを同時に実行します
• 用途：結果の集約が必要な独立した操作
• 例：複数のソースからのデータ収集

ループエージェント：

• 条件が満たされるまで実行を繰り返します
• 用途：反復的な改善、収束タスク
• 例：ジェネレーター・クリティックパターン

3. カスタムエージェント（ユーザー定義のロジック）

用途：

• ドメイン固有のオーケストレーション
• 複雑なステートマシン
• 既存システムとの統合
• 特殊な実行パターン

エージェントの合成：

• エージェントはサブエージェントを含めることができます（階層型）
• 親エージェントが子エージェントを調整します
• 複数階層のネストに対応しています

ツールエコシステム

ツールのカテゴリ：

1. 組み込みツール：

   • 検索 - Google Search API を使用したウェブ検索
   • コード実行 - Python コードインタープリター（サンドボックス化）
   • Google Cloud ツール - Vertex AI、BigQuery、Cloud Storage

2. カスタム関数ツール：

   • ツールとしてラップした Python 関数
   • 型ヒントからスキーマを自動生成
   • 非同期関数をサポート

3. OpenAPI ツール：

   • OpenAPI/Swagger 仕様から自動生成
   • HTTP ベースのサービス統合

4. MCP（Model Context Protocol）ツール：

   • MCP サーバーとの統合
   • フレームワーク間でのツール共有

ツールの属性：

• 名前 - 一意の識別子
• 説明 - LLM 向けの自然言語による説明
• パラメーター - 入力を定義する JSON スキーマ
• 関数 - 実行ロジック
• 確認 - オプションの human-in-the-loop 承認

メモリと状態管理

セッション管理：

• エージェントが会話履歴を保持
• コンテキストウィンドウを自動管理
• 履歴の保持期間を設定可能

状態の永続化：

• エージェントごとのカスタム状態オブジェクト
• シリアル化をサポート（JSON、pickle）
• 長期保存のためのデータベース統合

コンテキストのキャッシュ：

• コンテキストの繰り返し使用によるトークン消費を削減
• キャッシュを自動で無効化
• キャッシュ TTL を設定可能

エージェント開発の方法論

計画フェーズ

ステップ 1：エージェントの目的を定義する

• 主な目的（単一の責務）
• 入出力形式
• 成功の基準
• 失敗パターン

ステップ 2：必要なツールを特定する

選定基準：

• 利用可能な場合は、組み込みツール（検索、コード実行）を使用する
• 単純な処理（100 行未満）には、カスタム関数を作成する
• 既存の REST API には、OpenAPI ツールを使用する
• フレームワーク間の互換性には、MCP ツールを使用する

ステップ 3：エージェントの種類を選択する

START: What's the agent's decision pattern?
  │
  ├─> Requires natural language reasoning? ─Yes─> LlmAgent ★
  │
  ├─> Fixed sequence of steps?
  │   └─> Sequential Workflow Agent ★
  │
  ├─> Independent parallel operations?
  │   └─> Parallel Workflow Agent ★
  │
  ├─> Iterative refinement needed?
  │   └─> Loop Workflow Agent ★
  │
  └─> Custom orchestration logic?
      └─> Custom Agent ★

ステップ 4：マルチエージェントアーキテクチャを設計する（必要な場合）

パターン：

• コーディネーター／ディスパッチャー - 中央のエージェントが専門エージェントに処理を割り当てる
• 逐次パイプライン - エージェント A の出力 → エージェント B の入力
• 並列ファンアウト／集約 - 作業を分配し、結果を集約する
• 階層的な分解 - 複雑なタスクをサブタスクに分割する

実装フェーズ

エージェント実装例：

[コード例を参照：examples/google_adk_agent_implementation.py]

以下の主要なエージェントパターンを示しています：

• LlmAgent - create_weather_assistant() - カスタムツールを備えた会話型エージェント
• SequentialAgent - create_data_pipeline() - 順序に沿った実行（取得 → 変換 → 保存）
• ParallelAgent - create_market_researcher() - ツールの並列実行
• LoopAgent - create_content_generator() - 中断条件を伴う反復的な改善
• セッション管理 - create_stateful_session() - 履歴を伴う複数ターンの会話

テストフェーズ

ウェブ UI テスト：

# Start API server
adk api_server --port 8000

# Start web UI (separate terminal)
cd adk-web
npm install
npm start
# Access: http://localhost:4200

プログラムによるテスト：

# Unit test for agent
def test_weather_agent():
    agent = create_weather_agent()
    response = agent.run("Weather in NYC?")
    assert "weather" in response.content.lower()
    assert response.success is True

# Integration test with mock tools
def test_pipeline_agent():
    agent = create_pipeline_agent(mock_tools=True)
    result = agent.run({"input": "test_data"})
    assert result["status"] == "completed"

評価フレームワーク：

from google.adk.evaluation import evaluate_agent

# Criteria-based evaluation
results = evaluate_agent(
    agent=my_agent,
    test_cases=[
        {"input": "What's 2+2?", "expected_output": "4"},
        {"input": "Explain quantum computing", "criteria": "mentions_qubits"}
    ],
    evaluator_model="gemini-2.0-flash"
)

print(f"Pass rate: {results.pass_rate}")
print(f"Average score: {results.avg_score}")

ツール開発

[コード例を参照：examples/google_adk_tools_example.py]

カスタム関数ツール

実例：

• 基本的な関数ツール - calculate_tax() - 型ヒントを使用したシンプルなツール
• 非同期ツール - fetch_user_data() - 非同期 API 呼び出し
• HITL 確認 - send_email()、delete_user_account() - 人による承認が必要
• 入力検証 - send_email_tool() - メール形式の検証とサニタイズ
• 再試行ロジック - fetch_external_data() - 指数バックオフによる自動再試行
• レート制限 - call_external_api() - デコレーターによるレート制限
• エラー処理 - fetch_stock_price() - 障害発生時の適切な縮退動作

OpenAPI ツール

統合パターン：

• OpenAPI 仕様の URL からツールを読み込む
• 特定の操作に対するツールの絞り込みは任意
• 仕様からスキーマを自動生成 [参照：examples/google_adk_tools_example.py の create_api_agent()]

MCP ツールの統合

統合パターン：

• MCP サーバーのエンドポイントに接続します
• フレームワーク間の互換性を確保するため、ツールをインポートします [参照：examples/google_adk_tools_example.py の create_mcp_agent()]

マルチエージェントのオーケストレーション

[コード例を参照：examples/google_adk_multi_agent.py]

マルチエージェントのパターン

パターン 1：コーディネーター／ディスパッチャー（複雑さ：4）

• 用途： ユーザーのリクエストを専門エージェントに振り分けます
• 関数： create_coordinator_system() - 天気と金融の専門エージェント

パターン 2：逐次パイプライン（複雑さ：3）

• 用途： 依存関係のある複数段階の処理を行います
• 関数： create_content_pipeline() - 調査 → 執筆 → 編集

パターン 3：並列ファンアウト／集約（複雑さ：4）

• 用途： 複数の情報源から結果を集約します
• 関数： create_market_analysis_system() - テクニカル分析 + ファンダメンタル分析 + センチメント分析

パターン 4：階層的な分解（複雑さ：5）

• 用途： 複雑なタスクを管理しやすいサブタスクに分割します
• 関数： create_project_management_system() - マルチレベルのエージェント階層

パターン 5：生成／批評ループ（複雑さ：4）

• 用途： フィードバックを取り入れて反復的に改善します
• 関数： create_quality_content_system() - 生成 → 批評 → 改善

パターン 6：ヒューマン・イン・ザ・ループ（HITL）（複雑さ：3）

• 用途： 重要な判断に人間の承認を必要とします
• 関数： create_account_management_agent() - 削除前に確認します

パターン 7：状態管理

• 用途： セッションをまたいでユーザーコンテキストを保持します
• クラス： StatefulAgent - 履歴を含むインメモリ状態ストレージ

パターン 8：データベース永続化

• 用途： 状態を長期保存します
• 関数： save_state()、load_state() - PostgreSQL を利用した永続化

メモリと状態の管理

[コード例を参照：examples/google_adk_multi_agent.py - 状態管理のセクション]

セッション管理

基本的なセッションパターン：

• 履歴を保持するマルチターン会話
• コンテキストウィンドウの自動管理
• 設定可能な履歴の上限

[参照：examples/google_adk_agent_implementation.py の create_stateful_session()]

状態の永続化

カスタム状態オブジェクト：

• ユーザーごとのインメモリ状態ストレージ
• データクラスに基づく状態モデリング
• 会話履歴の追跡

[参照：examples/google_adk_multi_agent.py の StatefulAgent クラス]

データベース永続化：

• SQLAlchemy による状態の長期保存
• JSON 形式でシリアライズされた状態データ
• PostgreSQL／MySQL に対応

[参照：examples/google_adk_multi_agent.py の save_state()、load_state() 関数]

デプロイの選択肢

[コード例を参照：examples/google_adk_deployment.py]

Agent Engine（マネージドサービス）

デプロイコマンド：

pip install google-adk[cli]
adk auth login
adk deploy --agent-file agent.py --agent-name my_agent --project-id my-gcp-project --region us-central1

[設定例は create_production_agent() を参照]

Cloud Run へのデプロイ

コンポーネント：

• エージェントのエンドポイントを備えた FastAPI サーバー
• コンテナ化用の Dockerfile
• ヘルスチェックとエラー処理
• 環境設定

[examples/google_adk_deployment.py の FastAPI アプリの実装、Dockerfile の参考情報、デプロイコマンドを参照]

Docker によるコンテナ化

セルフホストの選択肢：

• Redis を使用する Docker Compose
• 単一コンテナでのデプロイ
• 環境変数の設定

[examples/google_adk_deployment.py の docker-compose.yml の参考情報とデプロイコマンドを参照]

リソース要件

エージェントの複雑さ	CPU	RAM	同時リクエスト数
シンプルな LlmAgent	1 コア	512MB	10
ワークフローエージェント	2 コア	1GB	20
マルチエージェント（3～5 エージェント）	4 コア	2GB	10
複雑なマルチエージェント（>5）	8 コア	4GB	5

評価とテスト

[コード例を参照：examples/google_adk_deployment.py - 評価エンドポイント]

基準ベースの評価

パターン：

• カスタムの評価基準（正確性、有用性など）を定義します
• エージェントに対してテストケースを実行します
• 合格率とスコアを分析します

[参照：examples/google_adk_deployment.py の evaluate_agent_endpoint()]

ユーザーシミュレーション評価

パターン：

• 定義した目標に沿ってユーザーとのやり取りをシミュレートします
• 目標達成率を追跡します
• 完了までの平均ターン数を測定します

[ユーザーシミュレーターの例については、ドキュメントを参照してください]

ベストプラクティス

[コード例：examples/google_adk_tools_example.py の「ツール設計のベストプラクティス」セクションを参照]

エージェント指示の作成

効果的なパターン：

• 役割と責任を明確にします
• 制約を含む構造化された形式にします
• ツールの使用方法を具体的に示します
• やり取りの例を示します

[examples/google_adk_tools_example.py の末尾にある GOOD と BAD の例を参照]

ツール設計の原則

主な原則：

1. 単一責任 - 各ツールの目的を明確にします
2. 説明的な命名 - アクションと対象を明確に命名します
3. 型ヒント - すべてのパラメーターに完全な型注釈を付けます

[examples/google_adk_tools_example.py の末尾にあるツール設計の例を参照]

エラー処理

戦略：

• グレースフルデグラデーション - 例外を発生させる代わりにエラーメッセージを返します
• 再試行ロジック - 指数バックオフで自動的に再試行します
• 入力検証 - すべての入力を検証し、サニタイズします

[examples/google_adk_tools_example.py の fetch_stock_price()、fetch_external_data()、send_email_tool() を参照]

セキュリティと安全性

実装：

• 入力検証 - メール形式の検証、長さの制限
• レート制限 - デコレーターによるリクエストのスロットリング
• サニタイズ - 危険な HTML／スクリプトコンテンツを削除します

[examples/google_adk_tools_example.py の send_email_tool() と rate_limit() デコレーターを参照]

パフォーマンス最適化

非同期ツール：

• 非同期関数を自動的に並列実行します
• I/O バウンドの処理のスループットを向上させます

[examples/google_adk_tools_example.py の fetch_price() と create_portfolio_analyzer() を参照]

品質ゲート

完了の定義：エージェント

エージェントは、次の条件を満たすと本番環境に対応できます。

1. 機能：

   • ✓ エージェントがテストケースで主要な目標を達成する
   • ✓ 有効な入力でツールの実行に成功する
   • ✓ 想定される障害モードに対するエラー処理がある
   • ✓ 複数ターンの会話でコンテキストを維持する

2. パフォーマンス：

   • ✓ 単純なクエリの応答時間が 5 秒未満
   • ✓ 複雑なワークフローの応答時間が 30 秒未満
   • ✓ 評価基準に対する合格率が 80％以上
   • ✓ リソース使用量がデプロイの制限内に収まる

3. 安全性：

   • ✓ すべてのツールで入力検証を行う
   • ✓ リスクの高いアクションでは確認を必須とする（HITL）
   • ✓ 認証情報や API キーをハードコードしない
   • ✓ 外部 API 呼び出しにレート制限を設ける

4. 可観測性：

   • ✓ デバッグ用のロギングを設定する
   • ✓ マルチエージェントのワークフローでトレーシングを有効にする
   • ✓ 評価指標を追跡する
   • ✓ エラーアラートを設定する

5. ドキュメント：

   • ✓ エージェントの目的と機能を文書化する
   • ✓ ツールの説明が明確で正確である
   • ✓ 使用例を提示する
   • ✓ 既知の制限事項を文書化する

完了の定義：ツール

ツールは、次の条件を満たすと本番環境に対応できます。

1. インターフェース：

   • ✓ すべてのパラメーターに型ヒントがある
   • ✓ docstring で目的、引数、戻り値を説明する
   • ✓ パラメーターの説明が LLM による選択の指針となる
   • ✓ 戻り値が JSON シリアライズ可能である

2. 信頼性：

   • ✓ 有益なメッセージを含むエラー処理がある
   • ✓ 入力検証によって無効な操作を防止する
   • ✓ 長時間実行される処理にタイムアウトを設定する
   • ✓ 一時的な障害に対する再試行ロジックがある

3. テスト：

   • ✓ ユニットテストで成功ケースを網羅する
   • ✓ ユニットテストでエラーケースを網羅する
   • ✓ エージェント実行との統合テストがある
   • ✓ 負荷の高い処理のパフォーマンスベンチマークがある

エラー処理ガイド

よくある問題と解決策

問題：エージェントが適切なツールを呼び出さない

• 原因： ツールの説明が不明瞭、または曖昧です
• 解決策：

  # BAD: Vague description
  def process(data):
      """Process data."""  # Too generic
  
  # GOOD: Specific description
  def validate_email_format(email: str) -> bool:
      """Check if email address matches valid format ([email protected]).
  
      Use this tool ONLY to validate email syntax, not to verify
      if email exists or is deliverable."""
  

問題：エージェントが無限ループする

• 原因： Loop Agent に終了条件がありません
• 解決策：

  # Add max_iterations and explicit break condition
  agent = LoopAgent(
      tools=[...],
      max_iterations=10,  # Hard limit
      break_condition=lambda result: result.get("completed", False)
  )
  

問題：「ツールの実行に失敗しました」というエラーが発生する

• 原因： ツールが未処理の例外を発生させます
• 解決策：

  def robust_tool(param: str) -> str:
      try:
          result = risky_operation(param)
          return f"Success: {result}"
      except SpecificError as e:
          return f"Operation failed: {e.message}"
      except Exception as e:
          logger.error(f"Unexpected error in robust_tool: {e}")
          return "Temporary service error, please try again"
  

問題：エージェントの応答が遅すぎる

• 原因： 並列化できる処理でツールを逐次的に呼び出しています
• 解決策：

  # Use Parallel Agent or async tools
  agent = ParallelAgent(
      tools=[tool1, tool2, tool3]  # Execute concurrently
  )
  

問題：コンテキストの上限を超過する

• 原因： 会話履歴が長すぎます
• 解決策：

  session = Session(
      agent=my_agent,
      max_history_turns=10,  # Limit history
      context_window_tokens=30000  # Set explicit limit
  )
  

問題：Cloud Run でのデプロイに失敗する

• 原因： 依存関係または環境変数が不足しています
• 解決策：

  # Ensure requirements.txt is complete
  pip freeze > requirements.txt
  
  # Set required environment variables
  gcloud run deploy my-agent \
    --set-env-vars GOOGLE_API_KEY=your_key,AGENT_CONFIG=prod
  

デバッグ戦略

1. 詳細ログを有効にします：

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("google.adk")
logger.setLevel(logging.DEBUG)

2. ツールを個別にテストします：

# Test tool without agent
tool = Tool.from_function(my_function)
result = my_function("test_input")
print(f"Tool output: {result}")

3. インタラクティブなデバッグにはウェブ UI を使用します：

adk api_server --debug
# Access UI at http://localhost:4200
# View tool calls, agent reasoning, response generation

4. エージェントの実行トレースを調べます：

response = agent.run("test query", return_trace=True)
print(response.trace)  # Shows all tool calls and decisions

複雑さの評価

タスク	評価	説明
ツールを備えたシンプルな LlmAgent	2	基本的な会話エージェント
Sequential Workflow Agent	2	順序が固定されたツール実行
Parallel Workflow Agent	3	並行処理
Loop Workflow Agent	3	反復的な改善
Custom Agent	3	ユーザー定義のオーケストレーション
Coordinator/Dispatcher（2-3 エージェント）	4	マルチエージェントのルーティング
Sequential Pipeline（3+ エージェント）	4	エージェントの連鎖実行
Hierarchical Multi-Agent（>5 エージェント）	5	複雑な入れ子構造のアーキテクチャ
カスタムツールの開発	2	Python 関数のラッパー
OpenAPI ツールの統合	2	仕様からの自動生成
MCP ツールの統合	3	フレームワークをまたいだツール
Agent Engine へのデプロイ	2	マネージドデプロイ
セルフホストの Docker デプロイ	3	コンテナオーケストレーション
高度な評価フレームワーク	4	カスタム基準とシミュレーション

参考資料

公式ドキュメント

• メインドキュメント： https://google.github.io/adk-docs/
• Python SDK： https://github.com/google/adk-python
• サンプル： https://github.com/google/adk-samples
• ウェブ UI： https://github.com/google/adk-web

Python SDK のリソース

• インストール： pip install google-adk
• API リファレンス： https://google.github.io/adk-docs/api/python/
• クイックスタートガイド： https://google.github.io/adk-docs/quickstart/

その他の言語

• Go SDK： https://github.com/google/adk-go
• Java SDK： https://github.com/google/adk-java

コミュニティのリソース

• GitHub ディスカッション： https://github.com/google/adk-python/discussions
• 課題トラッカー： https://github.com/google/adk-python/issues

関連スキル

• ワークフローの自動化には、n8n スキルを使用します
• API 設計には、api-design-architect スキルを使用します
• クラウドへのデプロイには、cloud-devops-expert スキルを使用します
• Python 開発には、Python 固有のスキルを使用します
• LLM の統合には、モデルプロバイダーの SDK（OpenAI、Anthropic など）を使用します

---

バージョン： 1.0.0 最終更新日： 2025-11-13 複雑さの評価： 3（中程度 - エージェントアーキテクチャの知識が必要です） 習得までの推定時間： 熟達まで 10-15 時間