# ADK 2.0の便利だけど知られていない機能 🌍 AIエージェントが画像やPDFなどのバイナリデータを扱う際、ファイル管理が煩雑になっていませんか？ ADK 2.0のアーティファクト管理は、エージェントが生成・利用するバイナリデータ（画像、PDF、音声など）をファイル名で識別し、自動バージョニングで管理する仕組みです。 📌 タイトル：アーティファクト管理 🔗 URL： 🧩 概要 アーティファクトは、エージェントのセッション内で生成・保存されるバイナリデータを統一的に管理する機能です。`google.genai.types.Part`のinline_data（データバイト列 + MIMEタイプ）として表現され、ファイル名で識別されます。保存のたびに自動的にバージョン（0, 1, 2...）が付与され、変更履歴を追跡できます。スコープはセッション単位（デフォルト）またはユーザー単位（`user:`プレフィックス）を選択可能です。 🛠 使い方 `context`オブジェクトを通じて、アーティファクトの保存・読込・一覧を操作します。 ```python from google.genai import types # アーティファクトの保存 image_part = types.Part(inline_data=types.Blob( data=image_bytes, mime_type="image/png" )) version = "report_chart.png", image_part) # アーティファクトの読込 artifact = context.load_artifact("report_chart.png") # アーティファクト一覧の取得 artifact_names = context.list_artifacts() ``` 開発時は`InMemoryArtifactService`、本番環境では`GcsArtifactService`を使い分けることで、環境に応じた柔軟な運用が可能です。 🏗 本番システムへの組み込み方 ・本番環境では`GcsArtifactService`を使用し、永続的なストレージを確保する ・ユーザー横断で共有すべきデータには`user:`プレフィックスでユーザースコープを活用する ・バージョニングを活かして、生成物の変更履歴やロールバックの仕組みを構築する ・MIMEタイプを正しく設定し、ダウンストリームでの処理互換性を保つ 💡 ユースケース 🖼️ エージェントが生成したグラフや図表の保存と再利用 📄 PDF レポートの生成・バージョン管理 🎵 音声合成結果の保存と後続処理への受け渡し 👤 ユーザーごとのプロファイル画像やドキュメントの管理 ⚠️ 注意点 `InMemoryArtifactService`はプロセス終了時にデータが消失するため、開発・テスト用途に限定してください。大容量のバイナリデータを大量に保存する場合は、GCSのストレージコストとクォータに注意が必要です。また、セッションスコープのアーティファクトはセッション終了後にアクセスできなくなるため、永続化が必要なデータにはユーザースコープを使用してください。 ✨ アーティファクト管理を活用すれば、バイナリデータの取り扱いがシンプルになり、エージェントのマルチモーダル対応が格段に容易になります。 #ADK# #AIAgent#

# 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#

AIエージェントをエンタープライズシステムに組み込むプラクティス 【オブザーバビリティ / トレース＋プロベナンス】 💡 「なぜその回答になったか」を説明できないエージェントは、本番に出してはいけません。構造化トレースとプロベナンスで、確率的な挙動を追跡可能にしましょう。 🔥 解決する課題 - 「なぜこの回答になったか」を再現・分析できない - 部署・プロジェクト・エージェント単位のコストを把握できない - モデル変更やプロンプト変更による品質劣化をサイレントに見逃す - 規制下の意思決定で「なぜこの判断になったか」を後から説明できない 🏗️ 提案パターン 推論ステップ・ツール呼び出し・トークン数・コスト・レイテンシ・評価スコアをOpenTelemetry準拠の構造化トレースで記録します。ログ基盤にはメタデータを、オブジェクトストレージにはプロンプト本文や生出力を格納し、トレースIDで紐付けます。正常系はサンプリング（1〜10%が起点）、エラーや低評価は全量記録します。規制下の重要な意思決定には、参照データ・推論経路・使用モデル・承認者まで遡れるプロベナンス（来歴）を追加します。 ✅ 選定条件 - 向き：本番運用するすべてのエージェント（例外なし） - 不向き：特になし（本番では必須パターン） ⚠️ 落とし穴 - 全プロンプト本文をログ基盤に入れると容量・コストが非現実的になる - PIIのマスキングを怠るとトレースログ自体がセキュリティリスクになる - プロベナンスの粒度を決める設計判断は、必ず人間のレビューを通すべき 🛠️ 実装方針 1. OpenTelemetry GenAI semantic conventions 準拠のスパンを全エージェントに組み込み、推論・ツール呼び出し・検索の各ステップをトレースIDで一貫して記録します 2. Langfuse / LangSmith / Arize 等のLLMオブザーバビリティ基盤にメタデータ（モデル名・トークン数・レイテンシ・コスト・評価スコア）を送信し、ダッシュボードで部署別コスト・品質推移を監視します 3. プロンプト本文・コンテキスト・生出力はオブジェクトストレージ（S3等）に格納し、ログ基盤のメタデータとIDで紐付けます 4. tail-based sampling を導入し、正常系は1〜10%サンプリング、エラー・低評価・高コストのリクエストは全量記録します 5. 規制対応が必要な場合は、決定ログをappend-onlyの不変監査ログとして保持し、参照データ・使用モデル・プロンプトバージョン・承認者まで逆引き可能なプロベナンスを構築します #AIエージェント# #エンタープライズアーキテクチャ#