エージェントアナリティクスのタクソノミー

エージェント分析は、マネージドイベントのタクソノミーを使用します。すべてのイベント名とプロパティには[Agent]プレフィックスが付いているため、同じプロジェクト内に存在していても、エージェントデータはプロダクトイベントと明確に区別されています。それらはプロジェクトとユーザーIDを共有しているため、エージェントとプロダクトの動作全体にわたって、コホートをチャート化、セグメント化、構築できます。

このページは、エージェント分析が生成するすべてのイベントとプロパティのリファレンスです。イベントは、2つのプロデューサーから生成されます。

  • SDKのインストルメンテーションは、エージェントの実行中にリアルタイムでイベントを出力します:ユーザーメッセージ、AIレスポンス、ツール呼び出し、スパン、埋め込み、セッション終了、セッションエンリッチメント、スコア。
  • Amplitudeのエンリッチメントパイプラインは、セッションが終了した後にイベントを生成します:Session RecordとEvaluator Result。 AmplitudeはScoreイベントを決して発行しません。スコアは常にアプリケーションから取得されます。

データ階層

Agent アナリティクスは、各エージェントのやり取りを階層構造としてモデル化します。

エージェントはすべてのイベントに付くディメンションです。すべてのイベントがこの[Agent] Agent IDプロパティを持ち、マルチエージェントシステムでは子エージェントが[Agent] Parent Agent IDを持ちます。単一のセッションに複数のエージェントが含まれる場合があります。セッションレベルのロールアップでは[Agent] Root Agent Name(セッションを開始したエージェント)と、[Agent] Agent Chain Depth(最長の委任パス上にあるエージェント数)が記録されます。エージェントを比較するには、任意のチャートを[Agent] Agent IDでグループ化します。マルチエージェントのセッションを分析するには、チェーン深さが1より大きいセッションレコードをフィルタリングします。

エージェントセッションは分析セッションではありません。[Agent] Session IDはエージェント作業の単位を識別する役割を担い、インストルメンテーションで設定します(アプリがすでに持っているスレッド、チケット、コール、または実行IDを使用してください)。Amplitudeの標準session IDは、アプリまたはウェブ訪問を識別し、セッションリプレイを強化します。1つの分析セッションに複数のエージェントセッションを含めることができます。セッションリプレイでこの2つをリンクするには、「エージェントセッションをセッションリプレイにリンクする」を参照してください。

イベントインベントリ

非推奨のイベント

非推奨:[Agent] Topic Classificationは起動しなくなりました。トピックおよび分類の出力は、[Agent] Evaluator Resultとセッションレコードの[Agent] Topic Summaryに表示されるようになりました。トピックの分類に基づいてチャートを作成した場合は、それらを評価ツール結果に移行してください。

シグナル:品質が記録される場所

Amplitudeは、すべてのクローズされたセッションで、固定された一連の品質シグナルを実行します。シグナル結果は[Agent] Session Recordイベントのプロパティとして記録されます(セッションごとにレコード1件)。各シグナルに固有の結果、根拠、および(該当する場合は)エビデンスのプロパティが付きます。シグナルは個別のイベントを生成しません。 各シグナルが何を回答し、そのラベルが何を意味するかについては、Agent分析の組み込みシグナルを参照してください。

シグナルセマンティクスに関する注意事項:

  • すべてのシグナルには根拠が書かれます。 Task Completed、Response Quality、データ品質も証拠を作成できます。シグナルは方向性を示す指標であり、確定的な事実ではありません。
  • Task CompletedとResponse Qualityは、数値スコアではなく、ブール値です。 これらのトレンドを表示するには、値がtrueであるセッションのシェアをチャートに表示します。Task Completedは、初期エラーの後に成功した状態で回復をクレジットし、toneを無視します。Response Qualityは、タスクの結果とは独立してテキスト(正確、明快、構造化されている)を判断します。
  • ネガティブなフィードバックとユーザーの摩擦は関連していますが、別物です。ネガティブなフィードバックは、ユーザーが書いた内容に明らかな不満を検出します。ユーザーの摩擦は、ユーザーが苦情を言わなかった場合でも、再試行ストームやclarificationループなどの行動パターンを検出します。
  • アプリが[Agent] Scoreとして送信する低評価(サムズダウン)は、ネガティブフィードバックの明示的な不満とみなされます。ユーザーフィードバックの収集を参照してください。
  • ほとんどのシグナルにはメッセージテキストが必要です。 metadata_onlyやcustomer_enrichedのように、セッションに何も含まれていない場合、これらのシグナルプロパティは、障害として報告されるのではなく、セッションレコードから除外されます。データ品質は引き続きレポートされます。各モードの送信内容を参照してください。

分類値:

  • [Agent] User Intent:情報リクエスト、分析と統合、タスク実行、コンテンツ作成、アドバイスとレコメンデーション、トピック外/ソーシャル。グリーティングではなく、セッション全体にわたるドミナントインテント(主要なインテント)によって分類されます。
  • [Agent] Session Safety:標準(デフォルト)、トピック外、プロンプトインジェクション、悪用、探索行為、安全でない出力(エージェントが有害なコンテンツを生成)、データ漏えい(エージェントがPII、認証情報、内部情報を露出)。

共通のプロパティ

これらは、すべてまたはほとんどのSDKイベントに表示されます。

イベントコントラクト

AI SDKは、必要なプロパティを記入します。 標準の Amplitude SDK または HTTP API を通じてイベントを自分で送信する場合、各イベントには以下の共有プロパティ プラス、そのイベントタイプに必要なプロパティが必要です。手順については、「AI SDKを使用しないでエージェントイベントを送信」を参照してください。

すべてのイベントの共有プロパティ:[Agent] Session ID、[Agent] Turn ID、[Agent] Trace ID、[Agent] Agent ID、[Agent] Env、[Agent] Runtime、およびオプションで[Agent] Contextと実験プロパティ。プロダクト分析に使用するものと同じものuser_idを送信し、イベントごとにユニークなinsert_idを送信します。これにより、再試行しても重複が発生しません。

ワイヤ形式のルール:

  • $llm_messageはオブジェクトです:{ "text": "..." }Amplitudeはプレーンな文字列を無視するため、スレッドビューにはコンテンツが表示されません。
  • Turn IDは、イベントではなく、交換を識別します。ユーザーメッセージのラウンドトリップごとにこの値を1回増分し、その交換のユーザーメッセージ、すべてのツール呼び出し、およびAIレスポンスに同じ値をスタンプします。ラウンドトリップごとに[Agent] Trace IDを1つ生成し、同じイベント間で共有します。 ターン内の順序は、イベントの時刻によって決まります。
  • トークンとコストは、AI Responseにのみ属します:ツール呼び出しはトークンを消費しません。 サーバーはすべてのイベントから[Agent] Cost USDを合計するため、別のイベントタイプにコストを設定すると、セッションの合計が水増しされます。
  • [Agent] Agent IDは必須です:この情報がない場合、HTTP APIは200を返しますが、エージェント分析はイベントをセッションにグループ化できません。
  • プレフィックスプロパティ:すべてのエージェントプロパティ名は[Agent] で始まります。ただし、セッションリプレイIDは例外で、[Amplitude] Session Replay IDです。

イベントプロパティ参照

[エージェント]ユーザーメッセージ

[エージェント]AIのレスポンス

[エージェント]ツールの呼び出し

[エージェント]スパンと[エージェント]の組み込み

スパンは[Agent] Span Name、[Agent] Latency Ms、[Agent] Input State、[Agent] Output State、[Agent] Is Error、オプションの親スパンのネスト、およびユーザーが添付した任意のプロパティを保持します。エンベッディングには、AI Responseと同様に、モデル、プロバイダー、トークン、コストのプロパティが含まれます。Embedding イベントはセッションパイプラインに参加しないことに注意してください。これらのイベントはアイドルクロックをリセットしません。また、そのコストはセッションコスト USD に含まれません。

[エージェント]セッションの終了

ライフサイクルとタイムアウトのルールについては、セッションの終了方法を参照してください。

[Agent] Score

アプリケーションのフィードバックイベント。 Amplitudeは決してスコアを発行しません。プロジェクト内のすべてのスコアは、score()またはtrackScore()を介してコードから取得されます。

[エージェント]セッションのエンリッチメント

独自のセッションレベルのラベル:お客様のインフラストラクチャ上で計算された品質スコア、結果、トピック。trackSessionEnrichment()またはsetEnrichments()経由で送信されます。任意のプライバシーモードで動作します。これは、customer_enrichedモードにおけるプライマリデータパスです。

[エージェント]セッションレコード

セッションが終了した後に、セッションごとに一度発行されます。 これは品質分析の主力イベントです。セッションごとに1つの行で、すべてのシグナル結果とロールアップを伝送します。 1 セッションあたり正確に1つのセッションレコードがあります。

セッションの識別情報とロールアップ:

シグナルの結果(セマンティクスについては、上記のシグナル表を参照してください)

[Agent] Evaluator Result

終了したセッションごとに、アクティブなカスタム評価者ごとに一度発行されます。 カスタム評価者は、Amplitude UIで定義および調整を行うものです。組み込みのシグナルは、Evaluator Resultイベントを生成しません。

評価者のIDと出力:

すべての評価ツール結果に反映されるセッションディメンション。これにより、セッションレコードに接続することなく、評価ツールの結果をセグメント化できます:[Agent] Root Agent Name、[Agent] Agent Chain Depth、[Agent] Close Reason、[Agent] Turn Count、[Agent] Session Total Tokens、[Agent] Session Cost USD、[Agent] Session Avg Latency Ms、[Agent] Models Used、[Agent] Technical Error Count、[Agent] Topic Summary、Hasフラグ、および存在する場合は[Agent] User Score。

コストの計算方法

[Agent] Cost USDは、SDK内で、イベントが追跡される時点で正確に一度だけ計算されます。下流のプロセスでそれが再計算されることはありません。サーバーは値を逐次読み取り、それを合計します。自動料金設定では、イベントのトークン数と、継続的にメンテナンスされているオープンソースのモデルの料金カタログ(SDKにバンドルされているPydanticのgenai-pricesプロジェクト)を掛け合わせるため、標準的なモデル識別子の使用が重要になります。明示的に渡されるコストは、常に自動料金設定に優先され、ゼロを含め、指定された通りに発行されます。

何が課金され、何が課金されないか:

  • キャッシュ認識のブレンド。 キャッシュトークンの内訳を使用すると、キャッシュされていない入力、キャッシュ読み取り、キャッシュ書き込みはそれぞれ独自のレートで価格設定されます。これらを使用しない場合、キャッシュ負荷の高いワークロードでは2~5倍の過大評価になる可能性があります。
  • **価格設定できないモデル。**SDKでは、標準外の名前、ゲートウェイエイリアス(例:openrouter/auto)、またはファインチューニングされたft:モデル名に自動的に料金を設定することはできません。この方法はプロパティを省略し、モデルごとに警告を一度記録します。 ファインチューニングされたモデルやカスタムモデルの場合は、コストをご自身で渡してください。
  • **料金の鮮度。**料金は、SDKのバンドルカタログに含まれており、SDKはデフォルトで更新を取得しません。新しくリリースされたモデルの場合は、スタートアップ時にenableLivePriceUpdates()(Node)またはenable_live_price_updates()(Python)を呼び出して、1時間ごとに価格を更新します。更新に失敗した場合、SDKは引き続きそのバンドルされたカタログを使用します。ライブの更新は、既存のイベントの価格を変更しません。設定の詳細については、料金データを最新の状態に保つを参照してください。

SDK経由でなく直接イベントを送信する場合は、HTTPイベントの場合またはgen_ai.usage.cost、OTLPスパンの場合は[Agent] Cost USDコストを自身で入力してください。Amplitudeは送信した値を保存します。ダイレクトイベントには正確な推定に必要なすべての入力が含まれていない可能性があるため、ダイレクトイベントの価格を変更しません。

セッションレコード上の[Agent] Session Cost USDは、セッションの[Agent] AI Responseイベント全体の[Agent] Cost USDを合算したものであり、オール・オア・ナッシングで算出されます。トークンを使用するイベントでコストがかからないもの(無価格モデルなど)がある場合、部分的な合計をレポートするのではなく、そのプロパティがセッションレコードから完全に除外されます。埋め込みイベントはセッションパイプラインの対象外であるため、埋め込みコストが加算されることはありません。この値は、取り込み時に累積され、セッションがエンリッチされると固定されます。その後に到着したイベントでは、この値は変更されません。

判断コストは構造上別扱いです。[Agent] Evaluator Enrichment Cost USDは定義した評価ツールの[Agent] Evaluator Resultイベントに表示され、Session Cost USDに混入することはありません。Amplitudeの組み込みシグナルのコストはどこにも報告されません。これはプロダクトに含まれています。

すべてが全工程を通じてUSDであり、どこにも通貨コンバージョンは発生しません。プロバイダーの請求書を財務上の真実のソースとして扱います。高頻度でキャッシュされたワークロードやバッチ割引されたワークロードは異なる場合があります。エージェントアナリティクスのコストデータは、請求書では提供できないエージェントごと、ユーザーごと、トピックごとのアトリビューションという分析ビューです。

管理されたスキーマ

[Agent]タクソノミーはAmplitudeによって管理されています。プロパティ名、タイプ、データカタログへの登録は自動で処理されます。独自のディメンションを追加するには、[Agent] Context(SDKイベントに含まれ、セッションレコードに反映されるJSONプロパティ)を使用するか、ツールから標準のプロダクトイベントを発行してください。チャートでクエリできなくなる可能性があるため、登録されていないフラットなプロパティを[Agent]イベントに追加しないでください。

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

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.

このページでは