# ADKの便利で実践的な使い方 🔍 エージェントが「なぜその判断をしたのか」を追跡できていますか？ADKのObservability機能を使えば、ツール選択の理由からLLMへの完全なプロンプトまで、エージェントの内部動作を透明化できます。本番障害の原因特定にも不可欠な機能です。 📌 タイトル：Observability / Logging 🔗 URL： 🧩 概要 ADKはPythonの標準`logging`モジュールとOpenTelemetryを統合した構造化ログ機能を提供します。DEBUG/INFO/WARNING/ERROR/CRITICALの5段階のログレベル（デフォルトはINFO）で、LLMへの完全なプロンプト、ツール実行の引数と結果、エージェントのライフサイクルイベントなどを記録できます。GCPのCloud Loggingとのネイティブ連携により、GKE上のエージェントのログを一元管理することも可能です。 🛠 使い方 基本的なログ設定は以下の通りです。 Pythonの `logging` モジュールをインポートし、`logging.basicConfig()` で `level=logging.DEBUG` とフォーマット文字列（`'%(asctime)s - %(levelname)s - %(name)s - %(message)s'`）を設定します。 CLIからの起動時にログレベルを指定できます。 ```bash adk web --log_level DEBUG path/to/agents_dir ``` DEBUGレベルでは、LLMに送信される完全なプロンプト内容が確認できます。デフォルトではプロンプト内容は省略されるため、OpenTelemetryの環境変数で明示的に有効化する必要があります。 ```bash export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true ``` GCPのCloud Loggingにログを送信する場合は、専用のエクスポーターを使用します。 ` から `get_gcp_exporters` をインポートし、`get_gcp_exporters(enable_cloud_logging=True)` を呼び出してGCPエクスポーターを取得します。 CLIからGCPエクスポートを有効化する場合はさらに簡単です。 ```bash adk web --otel_to_cloud path/to/agents_dir ``` 🏗 実践的な使い方 **本番インシデントの根本原因分析**: DEBUGログを有効にすると、エージェントがLLMに送った完全なプロンプト（システム指示、会話履歴、ツール定義）とレスポンスが確認できます。「なぜ間違ったツールを選択したのか」「なぜ期待と異なる回答をしたのか」を、LLMとのやり取りレベルで追跡できます。 **予期しないツール呼び出しループの検出**: INFOレベルのログではツール実行の名前と引数が記録されます。同じツールが短時間に繰り返し呼ばれているパターンを検出すれば、エージェントが無限ループに陥っていることを早期発見できます。Cloud Loggingと組み合わせれば、アラート設定も可能です。 **GKE環境での一元管理**: `get_gcp_exporters`を使えば、複数のエージェントインスタンスのログがCloud Loggingに集約されます。OpenTelemetryのSemantic Conventionsに準拠した構造化ログにより、エージェント名やツール名でフィルタリングしながら横断的に動作を分析できます。 **本番と開発のログレベル使い分け**: 本番環境ではINFOまたはWARNINGを推奨し、アクティブなトラブルシューティング時のみDEBUGを有効にします。DEBUGレベルではプロンプト全文が記録されるため、機密データやPIIが含まれる可能性がある点に注意が必要です。 💡 ユースケース 🔎 エージェントのツール選択戦略の効率性分析 🚨 本番障害時の根本原因の迅速な特定 📊 Cloud Loggingでの複数エージェントの横断的モニタリング 🔄 ツール呼び出しの無限ループ検出とアラート ⚠️ 注意点 - `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`を有効にすると、ユーザープロンプトとエージェントレスポンスの全文がログに記録されます。機密データやPIIの漏洩リスクがあるため、本番環境での使用には注意してください。 - DEBUGレベルのログは非常に詳細でストレージコストが増大するため、常時有効にするのは避けてください。 - Cloud Loggingへのエクスポートには適切なGCPプロジェクトの設定とIAM権限が必要です。 ✨ Observability機能は、エージェントの「ブラックボックス」を開く鍵です。開発時はDEBUGでプロンプトレベルの詳細を確認し、本番ではINFOレベル＋Cloud Loggingで運用監視を実現しましょう！ #ADK# #AIAgent#