# ADKの便利で実践的な使い方 ## 🎨 実戦で使えるコールバックパターン集！ADKのCallback Design Patterns コールバックの基本は分かった、でも実際どう使うの？ADKの **Callback Design Patterns** で、ログ・キャッシュ・セキュリティなど実戦パターンをマスターしましょう！💪 ## 📌 タイトル Callback Patterns（コールバックデザインパターン） ## 🔗 URL ## 🧩 概要 ADKのコールバックには、実戦で繰り返し使われる定番パターンがあります。ロギング、キャッシュ、ステート管理、セキュリティガードレール、リクエスト/レスポンス変換、条件付きスキップ、アーティファクト処理などです。 さらに、これらのパターンを効果的に使うためのベストプラクティス（単一責任、パフォーマンス、冪等性、エラーハンドリング）も定義されています。 重要な判断基準として、**エージェント横断のセキュリティガードレールにはCallbacksよりもPluginsが推奨**されています。 ## 🛠 使い方 **パターン1: ロギング＆モニタリング** `logging_before_tool(ctx, tool, args)` では `ctx.invocation_id`、` を ` で記録し、`None` を返してフローを変更しません。`logging_after_model(ctx, response)` では ` の長さを ` で記録し、同様に `None` を返して観察のみ行います。 **パターン2: キャッシュ戦略** `cache_before_tool(ctx, tool, args)` では、` と `hash(str(args))` からキャッシュキーを生成し、`ctx.state.get(cache_key)` でキャッシュを検索します。キャッシュヒットすればその値を返してツール実行をスキップし、ミスなら `None` を返して通常実行します。`cache_after_tool(ctx, tool, args, tool_ctx, result)` では、同じキャッシュキーで `ctx.state[cache_key] = result` として結果を保存し、`None` を返してフローを変更しません。 **パターン3: ステート管理** `state_aware_callback(ctx, req)` では、`ctx.state.get("user:tier", "free")` でユーザーティアを取得し、`"premium"` であれば `req.config.system_instruction` にプレミアム向けの追加指示を動的に付加します。`None` を返してフローはそのまま続行します。 ## 🏗 実践的な使い方 **本番環境での多層防御パターン：** セキュリティガードレール（本番ではPluginsを推奨）として `security_before_model(ctx, req)` を定義します。`req.contents[-1].parts[0].text` からユーザー入力を取得し、`detect_pii()` でPIIを検出した場合は `audit_log()` で監査記録を残し、拒否メッセージ入りの `LlmResponse` を返してLLM呼び出しをスキップします。続いて `detect_injection()` でプロンプトインジェクションを検出した場合も同様にブロックします。いずれにも該当しなければ `None` を返して続行します。ツール引数のサニタイズとして `sanitize_before_tool(ctx, tool, args)` を定義し、` が `"database_query"` の場合に `args.get("query", "")` に `"DROP"` が含まれていればエラー辞書を返してツール実行をブロックします。アーティファクト保存として `save_artifact_after_agent(ctx)` を定義し、`generate_report(ctx)` でレポートを生成して `"execution_report.json", report)` で保存し、`None` を返します。 ## 💡 ユースケース - 📊 **構造化ロギング**：全実行ポイントで invocation_id 付きの構造化ログを出力 - 💾 **APIコスト削減**：before/after パターンでツール結果をキャッシュし、同じ引数の再呼び出しを防止 - 🔐 **多層セキュリティ**：PII検出、インジェクション防止、SQLサニタイズを各レイヤーに配置 - 📦 **アーティファクト管理**：実行結果やレポートをアーティファクトとして自動保存 - 🎚️ **動的振る舞い制御**：ユーザーティアやステートに応じてインストラクションを動的変更 ## ⚠️ 注意点 - **単一責任の原則**：1つのコールバックに1つの目的を持たせてください（ロギングとバリデーションを混ぜない） - **パフォーマンス**：コールバックは同期実行されるため、ブロッキングI/Oや重い処理は避けましょう - **冪等性**：外部副作用を持つコールバックは、リトライ時に安全であるように設計してください - **エラーハンドリング**：必ず try-except で囲み、コールバックエラーがプロセス全体をクラッシュさせないようにしましょう - **Plugins推奨**：エージェント横断のセキュリティポリシーには、Callbacksよりも **Plugins** を検討してください ## ✨ まとめ コールバックパターンを知ることで、ADKエージェントの実践力が格段に上がります。ログ・キャッシュ・セキュリティ・ステート管理…定番パターンを組み合わせて、堅牢でコスト効率の良いエージェントを構築しましょう。ただし、横断的なセキュリティにはPluginsの利用もお忘れなく！ #ADK# #AIAgent#