# AIエージェント開発の意思決定ポイント # トレース・サンプリング率｜Trace Sampling Rate 🎯 ポイント エージェントのトレース、全量記録していますか？それとも全く記録していませんか？ 「全量か無か」ではなく「何を全量にするか」が正しい問いです。AIエージェントの1リクエストは数千〜数万トークンのトレースデータを生成します。全量記録すると観測コストが爆発し、記録しなければ障害時に原因究明が不可能。条件付きサンプリングがこのジレンマを解決します。 📋 概要 トレース・サンプリング率は、エージェントの実行トレース（各LLM呼び出し、ツール実行、意思決定のステップごとの記録）をどの割合で収集・保存するかを制御するパラメータです。100%ならすべてのリクエストのトレースを記録し、1%なら100リクエストに1件だけ記録します。 AIエージェントのトレースは従来のWebサービスのログとは質的に異なります。プロンプト全文、出力全文、ツール引数・戻り値、中間的な推論ステップなどを含めると、1リクエストで数十KB〜数百KBのデータが生成されます。さらにLLMの出力は確率的なため、「同じ入力を再投入すれば再現できる」という前提が成り立ちません。 🔍 意思決定のポイント サンプリング率はaccountability（説明責任）とcost_sensitivity（コスト感度）のバランスで決まりますが、最も重要なのは条件付きサンプリングの設計です 🎯 一律の確率ではなく、リクエストの属性に応じて率を変えます。 判定基準の優先順位: 1. エラー/例外が発生したリクエスト → 100%記録（必須） 2. HITL（人間介在）が発生したリクエスト → 100%記録 3. 高リスク操作（副作用あり、不可逆）を含むリクエスト → 100%記録 4. レイテンシがP95を超えたリクエスト → 100%記録 5. コストが閾値を超えたリクエスト → 100%記録 6. 成功したリクエスト → 標本率で記録（1〜10%） 💡 要点と詳細 目安値 📊 - エラー/例外発生 → 100%。再現性のない障害のデバッグに不可欠 - HITL発生（人間承認/エスカレーション） → 100%。承認判断の妥当性を事後検証 - 高リスク操作（送金、データ削除等） → 100%。不可逆操作の監査に必須 - レイテンシP95超過 → 100%。性能劣化の根本原因分析に必要 - 成功かつ低リスク → 1〜10%。品質の統計的モニタリングに十分 - 開発・ステージング環境 → 100%。コストが問題にならない範囲で全量記録 トレースの粒度をサンプリング率とは別に制御するのも重要です 📦 全量記録するリクエストでも、プロンプト全文はコールド層に、メタデータ（モデル名、トークン数、レイテンシ、ステータス）はホット層に分離します。 ⚖️ トレードオフ サンプリング率が低すぎると、障害の再現が不可能になります 🔍 LLMの出力は確率的なため、同じプロンプトを再投入しても同じエラーが再現するとは限りません。品質劣化の見逃し、監査要件の不達成、コスト異常の遅延検知も深刻なリスクです。 サンプリング率が高すぎると、観測コストが本番のLLM呼び出しコストに匹敵するか上回ることがあります 💸 パフォーマンスへの影響、PII（個人情報）の拡散リスク、大量データ中の信号がノイズに埋もれる問題も発生します。 サンプリング率は運用開始後に段階的に下げてください。最初は高い率（50〜100%）で始め、安定性を確認してから成功リクエストの率を徐々に下げます。 🛠️ ユースケース サンプリング判定はリクエストの終了時に行うことも検討してください 🔄 head-based sampling（開始時に決定）は実装が簡単ですが、エラーが発生するかどうかは事前に分かりません。tail-based sampling（完了後に決定）なら結果に基づいて判定できます。ただし中間データを一時的にバッファする必要があります。 correlation ID（trace ID）の伝播を確実にしてください 🔗 マルチステップのエージェント実行では、最初のリクエストから最後のツール呼び出しまで一貫したtrace IDが紐づいていないと、部分的なトレースしか得られません。非同期処理やキューを介する場合にIDが途切れやすいので要注意です。 ホット/コールド分離と組み合わせるのが効率的です。サンプリングされたトレースはコールド層に全文を、それ以外はホット層にメタデータのみを記録する構成が実用的です。 #AIエージェント# #ソフトウェアアーキテクチャ#