エージェント分析の設定に関するトラブルシューティング
Agent分析の設定問題のほとんどは、3つの原因から発生します:セッションが決して終了しない、イベントに必要なIDが欠落している、またはコンテンツが間違った形で送信されていることです。以下の症状を見つけてください。 新しいインストルメンテーションをエンドツーエンドで確認するには、「Agent分析インストルメンテーションの確認」を参照してください。
セッション記録イベントが表示されない
Amplitudeは、セッションが終了した後にのみエンリッチメントを実行し、[Agent] Session Recordを書き込みます。
- セッションはまだ閉じていません:明示的な終了の後、セッションレコードは通常 15 分から 20 分以内に到着し、その後のエンリッチメントバックログ期間中に到着します。明示的な終了がない場合、セッションはアイドルタイムアウト(デフォルトでは30分)を待機し、取り込みから最大約15分間待機します。
- コードでSession Endが送信されていません:ジョブが終了したらそれを送信するか、アイドルタイムアウトを待機してください。セッションの終了方法を参照してください。
- closeイベントはプロセスを離れません:AI SDKの場合、プロセスが再起動すると、メモリ内にバッファリングされたcloseは失われます。 閉じた後に
ai.flush()を呼び出します。セッションを閉じてフラッシュするを参照してください。 - セッションレコードが空:最新のAI SDKに更新してください。現在のリリースでは、実際のアクティビティがあった場合のみセッションが作成されます。
- タイムアウト後にSession Endが到着する:Amplitudeは、アイドルタイムアウトによってすでにセッションが終了した後に到着したSession Endを無視します。
[Agent] Close Reasonの中でtimeoutが占める割合が高い場合、閉じるタイミングが遅すぎることを意味する場合があります(ページを閉じたときのみなど)。 - レコードに最後のターンが欠落している:各セッションが1つのセッションレコードを取得します。Amplitudeは、close後に到着するイベントを保存しますが、エンリッチしません。 セッションにレコードが全くなく、最後のアクティビティがタイムアウトをかなり過ぎている場合は、セッションIDを記載してサポートにお問い合わせください。
イベントが到着しない
- LLMの呼び出しはセッション外で実行されます(AI SDK):SDKは、アクティブなセッションコンテキスト外でパッチ適用済みの呼び出しをエラーなしで破棄しますが、LLMの呼び出し自体は依然として成功します。 これには、スタートアップ時にパッチを適用するもののセッションは開かない
AMPLITUDE_AI_AUTO_PATCH=trueのほか、バックグラウンドジョブ、ウォームアップ呼び出し、リクエストの範囲外にあるpromiseが含まれます。呼び出しをsession.run()でラップするか、ミドルウェアを使用するか、またはpatch()を参照してください。 - イベントはプロセスを離れることはありません:SDKはイベントをバッファリングします。サーバーレス関数や短命なプロセスの場合は、シャットダウン時と呼び出しごとに
flush()を呼び出してください。 - プロジェクトの間違い: APIキーが、Agent分析を有効にしたプロジェクトに属していることを確認し、そのプロジェクトのライブイベントを確認してください。
- インストルメンテーションと配信のどちらに問題があるか不明な場合:
debug: trueでクライアントを構築し、追跡されたすべてのイベントをstderrに出力してください。何も出力されない場合は、セッションのコンテキストを確認してください。イベントが出力されてもflush()1分間の期間内に到着しない場合は、APIキーとプロジェクトを確認してください。 node:async_hooksCloudflare Workersのエラー:完全なAI SDKをWorkerにバンドルすることはできません。 EdgeランタイムとCloudflare Workersでfetchベースの転送を使用するか、AI SDKなしでイベントを送信します。
イベントは200を返しますが、セッションにはなりません
イベントに[Agent] Agent IDが欠落しています。HTTP APIはAgent分析がイベントを処理する前に受信を確認します。そのため、イベントが正しくグループ化されたことにはなりません200。ai.agent()にエージェントIDを設定するか、HTTP APIに送信する際にすべてのイベントに[Agent] Agent IDを含めてください。
1つの会話が複数のセッションとして表示されます
- リクエストごとに新しいエージェント:リクエストハンドラ内で
ai.agent(...)を構築すると、ターンごとに新しいエージェントIDが生成されます。エージェントはモジュールの範囲で定義してください。エージェントとセッションを長寿命サーバーに配置するを参照してください。 - リクエストごと、またはクライアントのアイドルタイマー後に新しいセッションID: ジョブの各ターンを通じて、1つの安定したセッションIDを維持します。セッションIDの選択を参照してください。
- すべてのOpenTelemetryトレースが独自のセッションになる:
gen_ai.conversation.idなどの会話属性を設定します。このIDがない場合、AmplitudeはトレースIDにフォールバックし、セッションを劣化したとマークします。 「セッション属性とユーザー属性を設定する」を参照してください。
セッションは作業が完了する前に閉じます。
長い一時停止によりアイドルタイムアウトが発生したため、その後のターンはエンリッチメント実行後に到着し、セッションレコードに到達しませんでした。自然な空白期間が長いジョブのタイムアウト値を上げます。 セッションのタイムアウトの設定を参照してください。 ストリームされたレスポンスの寿命がセッションよりも長い場合、ストリームが消費されるまでセッションを開いたままにしてください。 ストリームレスポンスを参照してください。
ユーザーが表示されるか、unknownまたは2つに分割されます。
- OpenTelemetryユーザーは
unknown:Amplitudeが読み取るユーザー属性がどれも設定されていません。enduser.idまたは、サポートされている別の属性。 - 1 人のユーザーは2人のユーザーとして表示されます。"anonymous"などのプレースホルダユーザーIDが永続的な別のユーザーを作成するか、バックエンドがリクエストごとに新しいデバイスIDを生成しました。 ユーザーIDの設定を参照してください。
スレッドビューにはメッセージのコンテンツが表示されません。
$llm_messageが文字列になる:{ text: "..." }オブジェクトを送信してください。Amplitudeは、エラーなしで普通の文字列を無視します。- メッセージ文字列が空です:AI SDKは、空のメッセージを送信するのではなくドロップします。追跡時に、渡した変数に値が入力されていることを確認してください。
- プライバシーモードではコンテンツが削除される:
metadata_onlyおよびcustomer_enrichedはメッセージテキスト、ツールの入力と出力、システムプロンプト、例外メッセージ、またはスタックトレースを一切送信しません。Agent分析のプライバシーモードを参照してください。 - テキストが
[email]などのプレースホルダに置き換えられる:PIIマスキング(秘匿化)がオンになっています。Redactionは、イベントがプロセスから離れる前に、一致したパターンを置き換えます。 - ストリーミングされたレスポンスにテキストはありません:SDKがレスポンスを記録する前に、ストリームを空にしてください。
コストが不足している、ゼロである、または高すぎる
- AI SDKに
[Agent] Cost USDがないか、$0になっている:モデル名が料金カタログにないか、微調整されたft:モデルです。正規のプロバイダーモデルIDを使用するか、明示的にtotalCostUsdを設定してください。以前のSDKリリースでは記録されますが$0、現在のリリースではこのプロパティが省略されています。 - HTTP APIまたはOpenTelemetryの場合、コストがありません:Amplitudeはダイレクトイベントのコストを計算しません。
[Agent] Cost USDまたはgen_ai.usage.costを送信します。 - セッションコストUSDがありません:セッションでトークンを使用している任意のイベントにコストがない場合、Amplitudeは部分的な合計を報告するのではなく、セッションの合計を省略します。通常は、SDKが価格設定できないモデルであることが原因です。たとえば、標準外の名前、
openrouter/autoなどのゲートウェイのエイリアス、微調整されたft:モデルなどです。モデルIDを修正するか、これらの呼び出しでコストを渡します。以降のセッションでは合計を送信します。 - セッションのコストが高すぎます:サーバーはすべてのイベントから合計を計算するため、Tool Call または Session End のコストは合計を膨張させます。
[Agent] Cost USDAI Responseにのみコストを置きます。 - Anthropicキャッシュトークンが一致しない:
cache_read_input_tokensとcache_creation_input_tokensをinputTokensに追加してください。コストとトークンの管理を参照してください。
コストの仕組みについては、「コストの計算方法」を参照してください。
セットアップの初期段階で検証に失敗する
予想通りです。 検証ゲートは、実ユーザーID、実セッションID、コンポーネントごとのエージェントIDなど、完全なインストルメンテーションをチェックします。 プレースホルダIDを使用するか、最小限の設定を使用すると、アイデンティティゲートでは、何が残っているかを表示できません。 「エージェント分析(Agent Analytics)のインストルメンテーションを確認」を参照してください。
シグナルの結果が欠落しているか、情報量が少ないように見えます
- Amplitudeにコンテンツが到達していません:
metadata_onlyまたはcustomer_enrichedモードの場合、あるいはインストルメンテーションが空の文字列を送信した場合、コンテンツベースのシグナルは読み取る対象がありません。Amplitudeは推測を行うのではなく設定されていない状態のままにするため、失敗ではなく不在として扱われます。データ品質の問題は引き続き実行され、コスト、レイテンシ、エラーの各メトリックは引き続き機能します。 コンテンツを送信せずに品質を測定するには、自分で計算し、セッションエンリッチメントを送信します。 - セッションがジョブの途中で終了:タイムアウトに達したセッションは、不完全な会話として読み取られます。アイドルタイムアウトを修正し、信号品質を再度判断してください。
各シグナルが測定する内容については、Agent分析の組み込みシグナルを参照してください。
[Agent] Topic Classificationが届かなくなった
Amplitudeは、もうそれを送信しません。 トピックと分類の結果は、[Agent] Evaluator Result(分類の出力)とセッションレコードの[Agent] Topic Summaryに記録されます。古いイベントに基づいて構築されたチャートをこれらのプロパティに移動します。
プロパティが属していないイベントに表示される
SDKは、AIレスポンスイベントと組み込みイベントに対してのみ[Agent] Providerおよび[Agent] Temperatureを書き込みます。それらがツール呼び出しイベントやユーザーメッセージイベントに表示される場合、eventPropertiesから送信されていることが多く、ToolCallTracker.setAmplitude({ eventProperties })を通じて設定されたプロセス全体でのデフォルト設定になっています。eventPropertiesとして渡すものを監査し、カスタムセグメント化ディメンションにはcontextを使用してください。
実験プロパティがありません。
イベントに[Agent] Experimentsまたは[Agent] Experiment Variantがない場合は、次の原因を確認してください。
- SDKバージョン:この
experimentsオプションには、0.24.1より後の Node@amplitude/aiリリースまたは1.20.1より後の Pythonamplitude-aiリリースが必要です。 - Dropped entry: SDKは、キーまたはバリアントが空であるか、256文字を超えるか、または不正な文字を含むキーを持つエントリをドロップし、
:デバッグレベルで記録します。デバッグログを有効にすると、それを検索できます。 - 配列のみ:実験が2つ以上ある場合、イベントはプロパティを保持しますが、
[Agent] Experiments単一実験のプロパティは保持しません。代わりに[Agent] Experimentsグループ化してください。 - Forwarders と OpenTelemetry: フォワーダーは、その会話記録に実験が含まれている場合にのみ実験を送信し、OpenTelemetryレシーバーはGenAIスパン上の
feature_flag.*属性とイベントのみを読み取ります。
ルールについては、「Agent 分析の実験バリアントの記録」を参照してください。
ツール呼び出しは0ミリ秒のレイテンシーを表示します
patch() はメッセージ配列からツールの呼び出しを抽出したため、タイミングはありません。 実際の遅延にはtool()またはtrackToolCall()を使用します。追跡ツールを参照してください。
ブラウザのイベントはエラーなしでドロップされます。
setTransport('beacon')はSDK全体に永続的に適用されるため、以降のイベントでは、再試行なしで一度だけ送信されます。デフォルトのトランスポートを使用します。 BrowserおよびEdgeのノートを参照してください。
OpenTelemetry Collectorは413を取得するか、スパンを削除します。
413:リクエストが、解凍後に4MBを超えるか、または翻訳済みイベント数が2,000件を超えています。コレクタのバッチサイズを小さくします。200(partial_successあり):取り込みで一部のイベントが拒否されています。200はコレクタにバッチを削除するよう指示しています。partial_successbodyに注意してください。- 再起動時に失われたスパン: メモリ内の送信キューではなく、永続的な送信キューを使用してください。
OpenTelemetryの取り込みリファレンスを参照してください。
これは役に立ちましたか?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.