# ADKの便利で実践的な使い方 ## 🔌 全エージェントに一括適用！ADKのPlugins機能 個別のエージェントにコールバックを設定するのは面倒…ADKの **Plugins** なら、Runnerレベルで全エージェント・全ツール・全LLM呼び出しに横断的な制御を一括適用できます！🎯 ## 📌 タイトル Plugins（プラグイン） ## 🔗 URL ## 🧩 概要 Pluginsは、Runnerレベルで動作するクロスエージェントモジュールです。エージェント個別のCallbacksとは異なり、**一度登録するだけで全エージェント・全ツール・全LLM呼び出しに適用**されます。セキュリティガードレール、ロギング、レート制限などの横断的関心事に最適です。 プラグインはエージェントレベルのコールバックよりも**先に実行される**ため、グローバルポリシーの適用に適しています。 ADKには組み込みプラグインも用意されています：Reflect and Retry Tools、BigQuery Analytics、Context Filter、Global Instruction、Logging Pluginなど。 ## 🛠 使い方 `BasePlugin` を `google.adk.plugins.base_plugin` からインポートし、`InMemoryRunner` を `google.adk.runners` からインポートします。`SecurityGuardPlugin` クラスを `BasePlugin` のサブクラスとして定義し、`__init__` で `super().__init__(name="security_guard")` を呼びます。`before_model_callback` メソッドでは `llm_request.contents[-1].parts[0].text` からユーザー入力を取得し、`detect_injection()` でインジェクションを検出した場合に拒否メッセージ入りの `LlmResponse` を返します。`before_tool_callback` メソッドでは `is_authorized( で権限チェックを行い、未認可ならエラー辞書を返します。いずれも問題なければ `None` を返して通常続行します。最後に `InMemoryRunner` を作成し、`plugins=[SecurityGuardPlugin()]` を渡すだけで全エージェントにこのセキュリティガードが適用されます。 ## 🏗 実践的な使い方 **「Gemini as a Judge」パターンでのインジェクション検出：** `InjectionDetectorPlugin` は `BasePlugin` を継承し、`name="injection_detector"` で初期化します。`self.judge_model = "gemini-flash-lite"` をジャッジモデルとして保持し、`before_model_callback` で `llm_request.contents[-1].parts[0].text` からユーザー入力を取得して `judge_with_flash_lite()` に渡します。判定結果が `"INJECTION"` であれば `audit_log()` で記録し、拒否メッセージ入りの `LlmResponse` を返してブロックします。問題なければ `None` を返します。 `RateLimitPlugin` は `BasePlugin` を継承し、`max_calls_per_minute` パラメータ（デフォルト60）で初期化します。` リストで呼び出し履歴を管理し、`before_model_callback` で直近60秒間の呼び出し回数をカウントします。上限に達していればレート制限メッセージ入りの `LlmResponse` を返し、そうでなければ現在時刻を `call_log` に追加して `None` を返します。 最後に `InMemoryRunner` の `plugins` パラメータに `InjectionDetectorPlugin()` と `RateLimitPlugin(max_calls_per_minute=30)` を渡して、複数プラグインを組み合わせて登録します。 ## 💡 ユースケース - 🛡️ **セキュリティガードレール**：全エージェントに対するインジェクション検出・PII保護を一元管理 - 📊 **統合ロギング**：BigQuery Analyticsプラグインで全エージェントの実行ログを集約 - ⏱️ **レート制限**：API呼び出し回数を制御してコスト爆発を防止 - 🔄 **自動リトライ**：Reflect and Retry Toolsプラグインでツール失敗時のインテリジェントなリトライ - 📝 **グローバルインストラクション**：全エージェントに共通のポリシーや指示を注入 ## ⚠️ 注意点 - プラグインはエージェントレベルのコールバックより**先に**実行されます（優先順位に注意） - プラグインで値を返すと、対応するエージェントレベルのコールバックも含めてスキップされます - 全エージェントに適用されるため、特定エージェントだけに適用したいロジックはCallbacksを使ってください - `on_model_error_callback` / `on_tool_error_callback` フックでエラーハンドリングも可能です - Python v1.7.0+、TypeScript v0.2.5+、Go v0.4.0+、Java v0.3.0+ で利用可能です ## ✨ まとめ Pluginsは「一度書けば全エージェントに適用」を実現する強力な仕組みです。セキュリティ、ロギング、レート制限などの横断的関心事はPluginsに任せ、エージェント固有のロジックはCallbacksに集中させましょう。この分離により、保守性とセキュリティの両方が向上します！ #ADK# #AIAgent#