エージェント分析のFAQとトラブルシューティング

エージェント分析とは何ですか?

エージェント分析とは何ですか?

エージェント分析は、AmplitudeのAIエージェント向け分析プロダクトです。この機能は、すべてのエージェントの会話とワークフロー(セッション、ターン、トレース、ツール呼び出し、トークンコスト)をキャプチャし、タスク完了、応答品質、ユーザー摩擦、安全性などの品質信号に基づいて各セッションを自動的にスコアリングします。すべてが標準のAmplitudeイベントとして表示されるため、エージェントの品質を、すでに追跡しているプロダクトメトリクスに直接関連付けることができます。

エージェントの品質を、リテンションやコンバージョンなどのビジネス成果に関連付けることはできますか?

はい、これがプロダクトのコアです。評価結果は標準のAmplitudeイベントとして送信されるため、その結果に基づいてファネル、リテンションカーブ、コホートを作成できます。たとえば、エージェントセッションが正常に完了したユーザーとエラーが発生したユーザーのリテンションを比較したり、ユーザーが質問したトピックに基づいてユーザーをコホート化したり、各コホートがどのようにコンバージョンされるかを確認したりできます。 ほとんどのチームは、ビジネスユーザーが統合できない複数の相互接続されていないシステムでエージェントをモニタリングしています。エージェント分析は、品質と結果を1か所にまとめます。

エージェント分析はチャットボット専用ですか?

いいえ。これは、会話型エージェント、音声エージェント、バックグラウンドまたは自律型「doer」エージェント、マルチモーダルエージェント(画像入力と出力を含む)、およびマルチエージェントシステムをサポートしています。マルチエージェントのワークフローはエージェントごとの識別子で追跡されます。Amplitudeのジャーニーチャートを使用してクロスエージェントのフローを分析できます。

私のオブザーバビリティやevalツールとどのように違うのですか?

Agent Analyticsは、既存のツール(LangSmith、Langfuse、Braintrust、Datadog)とどのように連携していますか?

選ぶ必要はありません。ほとんどのチームは、3つの異なる問題に対処するため、3つのレイヤーすべてを実行しています。オブザーバビリティプラットフォームは、エージェントが実行されているかどうかを示します:アップタイム、レイテンシ、エラー。オフライン評価ツールは、変更安全にリリースできるかどうかを示します:合成テストスイート、リリース前の回帰テスト。エージェント分析は、エージェントが問題無く動作しているかどうかを示します:本番環境でユーザーのタスクを完了できたか、ユーザーは満足したか、そのやり取りがエージェントを構築した目的である成果につながったかを、すでにあるコンバージョンデータやリテンションデータと結び付けて確認できます。evalスタックを使用して変更をテストし、オブザーバビリティスタックを使用してインフラストラクチャを監視し、Agent分析を使用して、リリース後に実際のセッションがビジネスにどのような影響を及ぼしているかを把握します。

なぜ私は、通常のプロダクト分析を使用してエージェントイベントを追跡するだけではいけないのですか?

従来のエンゲージメント指標はエージェントにとって壊れます。長い会話はユーザーの喜びを意味するものでも、ユーザーの深い不満を意味するものでもあり、同じ使用パターンが正反対の結果を意味する可能性があります。 エージェント分析は、プロダクト分析が確認できないもの(会話コンテンツ、トレース、LLMスコアリングされた品質シグナル)を追加し、行動データでそれらを結合します。

使用の開始とインストルメンテーション

SDKを使用する必要がありますか?

いいえ。いくつかのパスがあり、それらすべてが同じイベントタクソノミーを生成します:

LangChainを使用している場合、コールバックハンドラは任意のモデルプロバイダーで動作します。 イベントを自分で送信する場合の完全なワイヤ契約については、設定ページのAI SDKなしでエージェントイベントを送信を参照してください。

ブラウザで@amplitude/ai SDKを使用できますか?Lovable、Superblocks、その他のAIアプリビルダーについてはどうですか?

いいえ。AI SDKはNode.jsとPythonのみ対応しています。ブラウザのバンドルまたはエッジランタイム(例:Cloudflare Workers)にインポートすると、Nodeのみのモジュールが含まれているため失敗します。ブラウザ、エッジランタイム、AIアプリビルダーでサポートされている方法は、標準の@amplitude/analytics-browser SDKを使用して[Agent]タクソノミーを直接出力することです。この設定ページには、ビルダーエージェント向けの仕様の全容と、貼り付けですつ使えるプロンプトが表示されます。

セッションを終了するために、独自のクライアント側アイドルタイマーを作成すべきですか?

ほとんどの場合、必要ありません。2つのクロックがあり、ユーザーが担当するのは1つだけです。Amplitudeのクロックは常に実行されます。セッションが30分間イベントを受信しない場合(設定可能、または-1で無効)、サーバーがセッションを閉じてエンリッチメントを実行します。明示的な[Agent] Session Endの指定はオプションですが、推奨されます。Amplitudeがそのイベントを処理するとセッションが終了し、セッションレコードは通常15~20分以内に到着します。 クライアントに独自の短いタイマーも構築した場合(たとえば、2分間の静止時間が経過した後にセッションを終了し、セッションIDをローテーションするなど)、実際の会話は断片化されます。長い回答を読むために一時停止したユーザーは、「新しい」セッションに戻ります。 その後、Enrichmentは不完全な会話(half-conversations)を判定するため、タスクの完了状況が人為的に低く表示されます。また、エージェント分析はセッションごとに課金されるため、1つの会話が複数として課金されることになります。ジョブが実際に終了したら明示的に閉じます。30分間のサーバークロックに放棄をキャッチさせます。 プロダクトが実際にそのようにセッションを定義している場合にのみ、クライアント側にアイドルタイマーをミラーリングし、その設定を寛大に保ってください。

エージェントセッションとは何ですか?また、Amplitudeセッションとはどう違うのですか?

これらは2つの異なる概念であり、2つの異なるプロパティによって定義されます。

  • エージェントセッションは、[Agent] Session IDイベントプロパティによって定義されます。これは、ユーザーがエージェントに渡す1つのジョブの最初から最後までを表しています:会話スレッド、サポートチケット、音声コール、バックグラウンド実行など。これは、すでに追跡しているID(スレッドID、チケットID、コールID、ジョブID)から設定します。その同じIDを共有するものはすべて、サブエージェントのアクティビティを含めて、同じエージェントセッションにまとめられます。
  • 通常のAmplitudeセッションは、標準のSession IDプロパティ($session_id)によって定義されます。これは行動に基づきます:ユーザーのアプリまたはウェブ訪問。これは、セッションリプレイとプロダクトレポートを基盤とし、非アクティブ状態の後に閉じます。

この2つは関連性があるものの、独立しています。ユーザーは、1回のプロダクト訪問で3つのエージェント会話が発生することがあります。または、ユーザーがアプリを離れた後もずっと続く1つのエージェントワークフローが発生することがあります。 エージェントセッションは、既存のセッション定義を妨げません。 これらを紐づけるには、標準のセッションIDをバックエンドに転送し、それをエージェントセッション(browserSessionId)に渡します。これにより、エージェントイベントがユーザーのプロダクトセッションに含まれるようになります。

エージェントのセッションはどのように終了しますか? タイムアウトを設定できますか?

セッションは次のいずれかの方法で終了します。

  • **明示的な終了(推奨):**チケットのクローズや実行の完了など、ジョブが終了したときにtrackSessionEnd()(ノード)またはtrack_session_end()(Python)を呼び出します。[Agent] Session Endはオプションです。エンリッチメントは終了後に一度実行され、セッションレコードは通常15~20分の期間で到着します。
  • アイドルタイムアウト: セッションを終了しない場合、セッションは30分間の非アクティブ状態で自動的に終了します。この時間帯は、セッションに対して受信された最後のエージェントイベントから測定されます。 これは、idleTimeoutMinutes(ノード)またはidle_timeout_minutes(Python)を使用してセッションごとに設定できます。現時点では、エージェントのcontext設定にもidle_timeout_minutesキーを含めて、オーバーライドが確実にサーバーに到達するようにしてください(オーバーライドの設定場所を参照)。自然な空白時間が長いジョブの場合はこの値を大きくします(たとえば、何時間にもわたって対応するサポートチケットの場合は240にするなど)。あるいは、-1を指定するとアイドルによる状態による終了が完全に無効になり、明示的に終了するまでセッションが開いたままになります(90日間の上限あり)。

同じユーザーが新しい目標で戻ってきた場合は、古いセッションIDを続行するのではなく、新しいセッションIDを使用して新しいセッションを開始してください。

エージェントセッションを既存のAmplitudeユーザーにリンクするにはどうすればよいですか?

プロダクト分析で使用しているのと同じユーザーID(またはデバイスID)を送信します。このIDが、エージェントのアクティビティをユーザーの残りのジャーニーと連携させます。 セッションIDは ID 解決には参加しません。匿名ユーザーまたは事前登録ユーザーは、IDが識別されると、Amplitudeの標準 ID 解決を使用して、後で統合されます。Amplitudeでは、インストルメンテーションの初日にID戦略を決定することをお勧めします。これは、最も一般的なセットアップの問題であるためです。

Thumbs up / thumbs downコントロールをどのように計測しますか?

Agent分析でユーザーフィードバックの収集を参照してください。簡単にまとめると、名前がuser-feedback、値が1または0で、評価されたAIメッセージを対象とする[Agent] Scoreイベントをソースuserと共に送信します。この方法で送信された低評価(thumbs down)は、ネガティブフィードバックの明示的な不満とみなされます。

会話履歴をインポートできますか?

はい、HTTP import API、ウェアハウスインポート、または連携経由でインポートできます。評価者は今後のセッションをスコアリングすることに注意してください。過去のデータをスコアリングする方法については、以下の評価者セクションを参照してください。

シグナルと評価子

何が自動的にスコアリングされますか?

Amplitudeは、設定なしの7つの組み込みシグナルに基づいて、すべての終了セッションをスコアリングします。これらは、「Task Completed」、「Response Quality」、「Session Safety」、「User Intent」、「User Friction」、「Has Negative Feedback」、「Data Quality Issues」です。 結果はセッションの[Agent] Session Recordイベントのプロパティとして表示されます。各プロパティには根拠があり、すぐにチャート化やセグメント化を行うことができます。 シグナルは方向性を示す指標であり、正解(グラウンドトゥルース)ではありません。各シグナルが回答する質問、そのラベル、およびそのプロパティについては、エージェント分析の組み込みシグナルを参照してください。

シグナルと評価子の違いは何ですか?

シグナルは、すべてのセッションで自動的に実行される固定された組み込みスコアです。 評価子とは、ドメイン固有のあらゆる事柄に対して定義するカスタムチェックです(「エージェントは正しいポリシーを引用しましたか?」、「キャラクターを維持していましたか?」)。独自の基準を用いたLLM-as-a-judgeの使用。

評価器に使用する推奨モデルは何ですか?

小さくて高速なモデルと、バイナリ(Yes/No)の質問を使用します。実際には次のようにします。

  • **数値よりもバイナリが適しています。**LLMの判定は数値範囲で一貫性がありません。人間のラベルに対して調整された、明確なyes/noの質問の方が、はるかに信頼性が高いです。組み込みシグナルでも、同じ理由からバイナリ判定を採用しています。
  • **通常、小さなモデルで十分です。**適切に設定されたバイナリチェックの場合、軽量モデル(GPT-4o mini、Claude Haiku、Gemini Flashクラスなど)は、通常、人間のラベルと高い一致率を示します。これは、すべての本番セッションで評価者を実行する場合に重要になります。より大きなモデルは、真に繊細な判断が必要な判断のために温存し、いずれの方法の場合も有効にする前に、ドライランで検証しておきます。
  • **モデル選びについて議論するのでなく、テストします。**一連の実際のセッションを調べ、人間に各セッションで期待される結果(グラウンドトゥルース)をマークしてもらいます。 次に、同じセッションに対して評価ツールをドライランし、人間のラベルと一致する頻度をカウントします。一致率が約90%であれば、モデルのサイズに関係なく、その評価ツールは有効にするのに十分な信頼性があります。小規模モデルがその基準に達した場合はその小規模モデルを使用し、達しない場合はプロンプトを改善するか、より強力なモデルにステップアップして再度測定します。

カスタム評価者は、独自のモデルAPIキーで実行されます(独自のキーをご用意ください)。そのため、モデル、プロバイダー、および支出を制御できます。 これは、キャリブレーションにも適用されます。これには、ライブスコアリングだけでなく、過去のセッションにおけるドライ実行やワンオフ実行などが含まれます。

評価者は過去のセッションに対して遡及的に実行されますか?

アクティブな評価者は、到着時に新しいセッションを評価します。 履歴セッションをスコアリングするには、Runsページから評価器を実行します。特定のセッション、日付範囲(サンプリングサポートあり)、またはデータセットに対して実行します。 完全自動の遡及的スコアリングがロードマップ上にあります。

スコアを信頼できると判断するには、どうすればよいですか?

有効にする前にキャリブレーションを行ってください。実際のセッションのデータセットを組み立て、評価器をドライランし、サンプルに人間によるグラウンドトゥルースをラベル付けして比較します。合意率が高い場合は有効にします。合意率が低い場合はプロンプトを反復します。 評価器のバージョンは追跡されるため、時間の経過とともに改良できます。

どのような種類の評価器を作成できますか?また、どのようなときにそれぞれを使用すべきですか?

  • LLM評価者は、ユーザーが作成したプロンプトに基づいて各セッションを判断します。 ポリシーのコンプライアンス、根拠性、トーン、払い戻しの決定が正しかったかどうかなど、読解を必要とする基準にこれらを使用してください。これらはセッションごとにトークンを消費し、その判断は完全に決定論的ではありません。
  • コード評価者は、モデル呼び出しなしで決定論的なパターンルールを適用します。RegexはTrueまたはFalseのパターンマッチ用であり、Keyword Classifierは一致するキーワードでセッションにラベルを付けます。 正確な機械的チェックに使用してください。

人間のラベルに対してキャリブレーションされたバイナリ出力は、通常、最も信頼性の高い選択肢です。 評価者の作成と調整を参照してください。

ユーザーは、サムズアップ/サムズダウンをほとんどクリックしません。それは問題ですか?

いいえ。明示的なフィードバックは、希薄で信頼性が低いことで知られています。 エージェント分析ではこれに依存していません。組み込みのシグナルがすべてのセッションをスコアリングし、Amplitudeは暗黙の行動シグナル(コピー、再試行、離脱、不満の表明)を自動的にキャプチャします。Amplitudeは、明示的な評価がある場合、それらも取り込みます。user-feedbackスコアとして送信された低評価(サムズダウン)は、ネガティブフィードバックにおいて明示的な不満としてカウントされます。

料金

Agent分析の価格設定はどのように設定されていますか?

エージェント分析は、イベントではなく、エージェントのセッションに基づいて、契約内容に応じて月単位または年単位で課金されます。すべてのプランには無料のセッション割り当てが含まれており、拡張に応じて追加のボリュームが利用できます。 詳細については、アカウントチームにお問い合わせいただくか、料金設定ページを参照してください。

エージェントイベントは私のAmplitudeイベントボリュームにカウントされますか?

ほとんどの場合はカウントされません。コアエージェントイベント(ユーザーメッセージ、AIの応答、ツール呼び出し)は、エージェントセッションとして別枠で計測され、既存のイベントボリューム制限にはカウントされません。例外はカスタムeval関連イベントです。これは、Amplitudeイベントボリュームに対してカウントされます。

評価の実行コストについてはどうですか?

組み込みの品質シグナルは、基本価格に含まれています。カスタムLLM-as-a-judge評価者では、独自のモデルAPIキーで実行されるため、推論コストは指定したレートでプロバイダーに渡され、お客様はモデルを選択します。

LLMのコスト追跡はどのように機能しますか?

コストは、トレース上のトークン数と、継続的にメンテナンスされているオープンソースのモデル価格カタログ(Pydanticのgenai-pricesプロジェクト)を掛け合わせて算出されるため、標準的なモデル名を使用することが重要です。大量にキャッシュされているワークロードやバッチ割引されているワークロードは、プロバイダーの請求書と異なる場合があります。プロバイダーの請求書を財務上の真実のソースとして扱い、Agent Analyticsのコストデータを分析上のビュー(請求書では提供できないアトリビューション、すなわちエージェントごと、ユーザーごと、機能ごとのアトリビューション)として扱ってください。カタログで価格設定できないモデル(非標準名、ゲートウェイエイリアス、ファインチューニング済みft:モデル)には自動コストはありません。これらのモデルには明示的にコストを渡します。

プライバシーとセキュリティ

会話コンテンツはどうなりますか?それはどこへ行きますか?

システムから送信されるものを、3つのレベルで正確に制御できます。 フルコンテンツがデフォルトであり、組み込みのシグナル、トピック、LLM評価者が読み取るものです。

  • フルコンテンツ(full、デフォルト):メッセージのコンテンツ。PIIのマスキングは、Node SDKではデフォルトで有効になっており、Python SDKでもバージョン1.17.0以降は有効になっています。SDKは、データが環境を離れる前に、メールアドレス、電話番号、クレジットカード、SSN、IPアドレス、base64エンコードされた画像データをクライアント側で消去します。 電話とSSNのパターンは米国の形式を対象としています。国際ロケールやドメイン固有の要件には、カスタム正規表現パターンを追加するか、独自のリダクション(例:Presidio)を組み込んでください。
  • メタデータのみ(metadata_only):イベントとメトリクス、メッセージテキストは一切なし。このゲートは、SDK内のすべてのコンテンツ送信チャネルを網羅しており、メッセージテキスト($llm_message.text)、ツールの入力と出力、システムプロンプト、例外メッセージ、スタックトレース、フレームワークによって送信されるコンテンツ属性(gen_ai.system_instructions、gen_ai.input.messages、gen_ai.output.messages)、およびスコアコメントが含まれます。
  • エンリッチドメタデータ(customer_enriched):生のコンテンツを含まない、ユーザーが計算した構造化されたラベルと評価結果。

組織の標準Amplitudeセキュリティコントロールは保存済みコンテンツを管理しており、ロールベースの権限によりアクセスが制限されます。 各モードが送信する内容については、エージェント分析のプライバシーモードを参照してください。

Amplitudeはデータに基づいてAIモデルを学習しますか?

いいえ。お客様の会話データは、Agent 分析をお客様に提供し、セッション、シグナル、評価を支えるためにのみ使用されます。Amplitudeは、AIモデルのトレーニングにデータを使用していません。

GDPR / HIPAA / コンプライアンスはどうですか?

Amplitudeの標準的なコンプライアンス体制とDPAは、Agent Analyticsデータに適用されます。 完全なコンテンツの場合、PIIの編集はデータが環境を離れる前にプロセスで実行されます。メッセージのテキストがシステムを全く離れることができない場合でも、メタデータのみとenriched-metadataのモードでは、コスト、レイテンシ、トークン、セッション、および自分で計算した任意のラベルが引き続き提供されます。組み込みのシグナル、トピック、LLM評価ツールはメッセージテキストを必要とするため、これらのモードでは実行されません。

チーム内で会話コンテンツを閲覧できるユーザーを制限できますか?

はい Agent分析、特に会話コンテンツへのアクセスは、AmplitudeのRole-Based Access Control(RBAC)機能を通じて制御されます。管理者は、これらの権限をロールレベルで付与および管理します。

どのエージェントをサポートしていますか?

この機能は任意のモデルやフレームワークで動作しますか?

はい、イベントスキーマはプロバイダーに依存しません。OpenAI、Anthropic、Google(Vertexを含む)、Bedrock、オープンソースモデル、LangChain、Vercel AI SDK、カスタムスタック:イベントを送信できる場合、サポートされています。OpenTelemetryをすでにエクスポートしているフレームワークは、統合概要にあります。 コスト追跡は、標準的なモデル識別子での使用が最適です。

管理できないサードパーティ製のエージェントまたはホスト型エージェント(サポートボット、Intercom Fin、Sierraなどのプラットフォーム)についてはどうですか?

はい スケジュールされたジョブがプラットフォームで公開されている会話を転送することで、セッション分析、品質シグナル、および結果アトリビューションを取得できます。ホスト型プラットフォームは通常、トークンレベルのコストや内部ツール呼び出しを公開しないため、ファーストパーティ製のインストルメンテーションよりも詳細さが劣ることをご了承ください。Amplitudeは、Sierra、Decagon、Fin by Intercom、Salesforce Agentforceのガイドを公開しています。「他のツールからエージェントの会話をインポート」を参照してください。

音声エージェント?

はい サーバー側でインスツルメンテーションを実施し、音声プラットフォームが提供するトランスクリプト/分析Webhookを転送します。

マルチエージェントシステム?

はい 各エージェントは独自の識別子とバージョンを取得します。セッションIDを共有するサブエージェントは1つのセッションにロールアップされ、エージェント間のジャーニーは標準のAmplitudeチャートで分析できます。

他のAmplitude機能との連携

通常のAmplitudeチャートでエージェントデータをチャート化できますか?

はい 組み込みのシグナルは[Agent] Session Recordイベントに到達し、カスタム評価ツールの結果は[Agent] Evaluator Resultに到達します。そのため、すべてが標準のチャートビルダー(セグメント化、ファネル、リテンション、ダッシュボード)で動作し、プロダクトイベントと並行して機能します。

エージェントデータは、プロダクト分析と同じプロジェクトに存在する必要がありますか?

はい、エージェントデータはプロダクト分析と同じプロジェクトに存在させることができます。これが、それらをまとめて分析する最も簡単な方法です。エージェントデータを別のプロジェクトに保管したい場合、Portfolioもサポートされているため、IDは両方で解決されます。 CSMまたはソリューションエンジニアが、適切な設定を選択するお手伝いをいたします。

トラブルシューティング

イベントが到着しない、セッションレコードの欠落、メッセージコンテンツの空白、コストの欠落、情報のないシグナル結果など、設定に関する問題については、エージェント分析の設定に関するトラブルシューティングを参照してください。

これは役に立ちましたか?

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.

このページでは