エージェントアナリティクスのタクソノミー
エージェント分析は、マネージドイベントのタクソノミーを使用します。すべてのイベント名とプロパティには[Agent]プレフィックスが付いているため、同じプロジェクト内に存在していても、エージェントデータはプロダクトイベントと明確に区別されています。それらはプロジェクトとユーザーIDを共有しているため、エージェントとプロダクトの動作全体にわたって、コホートをチャート化、セグメント化、構築できます。
このページは、エージェント分析が生成するすべてのイベントとプロパティのリファレンスです。イベントは、2つのプロデューサーから生成されます。
- SDKのインストルメンテーションは、エージェントの実行中にリアルタイムでイベントを出力します:ユーザーメッセージ、AIレスポンス、ツール呼び出し、スパン、埋め込み、セッション終了、セッションエンリッチメント、スコア。
- Amplitudeのエンリッチメントパイプラインは、セッションが終了した後にイベントを生成します:Session RecordとEvaluator Result。 AmplitudeはScoreイベントを決して発行しません。スコアは常にアプリケーションから取得されます。
データ階層
Agent アナリティクスは、各エージェントのやり取りを階層構造としてモデル化します。
| レベル | 概要 | 識別基準 |
|---|---|---|
| セッション | ユーザーがエージェントに渡す作業の1つの単位:会話スレッド、サポートチケット、音声コール、バックグラウンド実行。 | [Agent] Session ID |
| ターン | セッション期間の 1 回のやり取り:ユーザーメッセージ、エージェントのツール呼び出し、AI レスポンス。 | [Agent] Turn ID |
| スパン | ターン期間の 1 つの操作:LLM 呼び出し、ツールの呼び出し、取得ステップ、または追跡する任意のカスタム操作。 | 各イベントのスパンレベルID |
エージェントはすべてのイベントに付くディメンションです。すべてのイベントがこの[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] User Message | SDK | ユーザーはエージェントにメッセージを送信します。ターンを開きます。 |
[Agent] AI Response | SDK | モデルはレスポンスを返します。 モデル、トークン、コスト、レイテンシを含みます。 |
[Agent] Tool Call | SDK | エージェントはツールまたは関数を呼び出します。 |
[Agent] Span | SDK | observe()またはtrackSpan()を使用して追跡する任意のカスタム操作。 |
[Agent] Embedding | SDK | RAGと取得ワークロード用のembedding呼び出し。 |
[Agent] Session End | SDK | アプリは作業単位を完了とマークします。 オプション。以下のセッション終了を参照してください。 |
[Agent] Session Enrichment | SDK | 独自のラベルとスコアをセッションに添付します。 任意のプライバシーモードで利用できます。 |
[Agent] Score | SDK | アプリは、ユーザーの評価(サムズアップ/ダウン)、LLM判定者、または人間のレビューアなど、フィードバックを記録します。Amplitudeはこのイベントを生成しません。 |
[Agent] Session Record | サーバー | 閉じたセッションごとに1回。 すべてのシグナル結果とセッションロールアップを伝送します。 |
[Agent] Evaluator Result | サーバー | 終了したセッションごとに、アクティブなカスタム評価ツールごとに1回。 |
非推奨のイベント
非推奨:[Agent] Topic Classificationは起動しなくなりました。トピックおよび分類の出力は、[Agent] Evaluator Resultとセッションレコードの[Agent] Topic Summaryに表示されるようになりました。トピックの分類に基づいてチャートを作成した場合は、それらを評価ツール結果に移行してください。
シグナル:品質が記録される場所
Amplitudeは、すべてのクローズされたセッションで、固定された一連の品質シグナルを実行します。シグナル結果は[Agent] Session Recordイベントのプロパティとして記録されます(セッションごとにレコード1件)。各シグナルに固有の結果、根拠、および(該当する場合は)エビデンスのプロパティが付きます。シグナルは個別のイベントを生成しません。 各シグナルが何を回答し、そのラベルが何を意味するかについては、Agent分析の組み込みシグナルを参照してください。
| シグナル | Resultプロパティ | タイプ | コンパニオンプロパティ |
|---|---|---|---|
| タスクの完了 | [Agent] Task Completed | ブール値 | 根拠(Rationale)、証拠(Evidence) |
| 応答品質 | [Agent] Response Quality | ブール値 | 根拠(Rationale)、証拠(Evidence) |
| ユーザーのインテント | [Agent] User Intent | 分類 | 根拠 |
| セッションの安全性 | [Agent] Session Safety | 分類 | 根拠 |
| ユーザーフリクション | [Agent] Has User Friction | ブール値 | 根拠、[Agent] Detected User Friction(パターン) |
| ネガティブなフィードバック。 | [Agent] Has Negative Feedback | ブール値 | 根拠、[Agent] Detected Negative Feedback(フレーズ) |
| データ品質 | [Agent] Has Data Quality Issues | ブール値 | 根拠、エビデンス、[Agent] Detected Data Quality Issues(課題リスト) |
シグナルセマンティクスに関する注意事項:
- すべてのシグナルには根拠が書かれます。 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イベントに表示されます。
| プロパティ | タイプ | 概要 |
|---|---|---|
[Agent] Session ID | 文字列 | このイベントが属するエージェントセッション。 IDを渡さない場合は自動生成されます。本番環境では常に実際のスレッド、チケット、コール、または実行IDを渡してください。 |
[Agent] Turn ID | 数値 | セッション期間の順序数。交換ごとに1つの値。ユーザーメッセージ、そのツール呼び出し、そのAIレスポンスの値はすべて同じTurn IDを持ちます。 ターン期間の順序は、イベント時間に従います。 |
[Agent] Trace ID | 文字列 | セッション期間の関連する操作をグループ化します。 |
[Agent] Agent ID | 文字列 | このイベントを生成したエージェント。 必須:この情報がない場合、エージェント分析コンシューマーは引き続きイベントを受け入れますが(HTTP APIは200を返します)、そのイベントをセッションに関連付けることができないため、誤ってグループ化され、エージェント分析のビューから除外されます。 |
[Agent] Parent Agent ID | 文字列 | このエージェントに委任したエージェント。 ルートエージェントでは存在しません。 親スパンIDは親エージェントではありません。 |
[Agent] Message Source | 文字列 | ユーザーメッセージ上:エンドユーザーのターンの場合はuser。親エージェントがプロンプトを渡した場合はagent。明示的な値が優先されます。 |
[Agent] Customer Org ID | 文字列 | B2Bエージェントのテナント識別子。 |
[Agent] Env | 文字列 | デプロイメント環境(例:本番環境)。 |
[Agent] Runtime | 文字列 | イベント(例:browser)を発行したランタイム。 |
[Agent] SDK Version | 文字列 | Amplitude AI SDKのバージョン。診断フィールド。お使いのアプリバージョンで上書きしないでください。その場合はエージェントのバージョン管理を使用してください。 |
[Agent] Context | 文字列(JSON) | エージェント作成時に添付する任意のキーと値のコンテキスト(surface、prompt revision、deployment region)。A/Bテストおよび機能フラグのバリアントの場合は、実験プロパティを使用します。 |
[Agent] Experiments | 文字列の配列 | そのイベントが実行されたときに適用されていた実験を、key:variant文字列として示します。SDK experimentsオプションまたはOpenTelemetry feature_flag.*属性から設定します。実験バリアントの記録を参照してください。 |
[Agent] Experiment Key | 文字列 | 実験キーまたはフラグキー。正確に1つの実験が適用される場合。 |
[Agent] Experiment Variant | 文字列 | 該当する実験がちょうど1つの場合の、そのバリアント。この基準でチャートをグループ化して、群を比較します。 |
[Agent] Experiment Unit | 文字列 | フラグクライアントがランダム化の対象としたもの(1つの実験だけが該当する場合):agent_session、turnまたはspan。 |
[Agent] Experiment Provider | 文字列 | フラグまたは実験システム(例: statsig)、該当する実験がちょうど1つで、かつ自身で設定している場合。 |
[Agent] Git SHA | 文字列 | プロセスの構築元となったコミット SHA。SDKのスタートアップ時にAMPLITUDE_GIT_SHA(またはGIT_SHA)から読み取ります。デプロイメタデータをキャプチャするを参照してください。 |
[Agent] Git Ref | 文字列 | プロセスの構築元となった Git ref(通常はブランチまたはタグ)。SDKのスタートアップ時に、AMPLITUDE_GIT_REF(またはGIT_REF)から読み取ります。 |
[Agent] Git Repo | 文字列 | リポジトリのURL。 AMPLITUDE_GIT_REPO(またはGIT_REPO)で選択します。SDKは任意のuser:pass@ユーザー情報を削除することで値をサニタイズします。 |
イベントコントラクト
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を送信します。これにより、再試行しても重複が発生しません。
| イベント | 共有プロパティ以外では必須 | メモ |
|---|---|---|
[Agent] User Message | [Agent] Message ID、プライバシーモードでコンテンツを送信する場合は$llm_message: { text } | リクエスト開始時に発行します。 |
[Agent] Tool Call | [Agent] Invocation ID, [Agent] Tool Name, [Agent] Tool Success, [Agent] Latency Ms, [Agent] Parent Message ID | 各呼び出しにつき1つのイベントが、AI Responseの前に実行順序で発行されます。ツールペイロードは[Agent] Tool Inputおよび[Agent] Tool Outputに含まれ、編集済みとなります。 |
[Agent] AI Response | [Agent] Message ID、[Agent] Model Name、[Agent] Provider、[Agent] Latency Ms、トークン数、計算する場合は[Agent] Cost USD、コンテンツを送信する場合は$llm_message: { text } | システムプロンプトは、このイベントのプロパティ([Agent] System Prompt)であり、別のイベントではありません。 |
[Agent] Session End | オプション:[Agent] Output State、[Agent] Abandonment Turn、[Agent] Session Idle Timeout Minutes | close-reasonやdurationプロパティを作成しないでください。サーバーはセッションレコードに基づいて、[Agent] Close Reasonおよびロールアップを算出します。 |
[Agent] Score | [Agent] Score Name, [Agent] Score Value, [Agent] Target ID, [Agent] Target Type, [Agent] Evaluation Source | SDKの有無にかかわらず、同じ契約。 |
ワイヤ形式のルール:
$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です。
イベントプロパティ参照
[エージェント]ユーザーメッセージ
| プロパティ | タイプ | メモ |
|---|---|---|
[Agent] Message ID | 文字列 | このメッセージの一意の ID。スコアターゲットとして参照します。 |
$llm_message.text | 文字列 | メッセージのコンテンツ。 プライバシーモードでコンテンツを送信する場合にのみ表示されます。 |
[Agent] System Prompt | 文字列 | システムプロンプトが有効です。 オプションのフィールド。プライバシーモードにより制限されています。 |
[Agent] Input State | 文字列 | メッセージが送信された時点でのアプリケーション状態。 |
[Agent] Is Regeneration | ブール値 | ユーザーは、前のレスポンスのやり直しを要求しました。 暗黙の否定的なシグナル。 |
[Agent] Is Edit / [Agent] Edited Message ID | boolean / string | ユーザーが以前のメッセージを洗練しました。オリジナルへのリンク。 |
| 添付ファイルのプロパティ | mixed | Has Attachments, Attachment Count, Attachment Types, Total Attachment Size Bytes, Attachments. |
[エージェント]AIのレスポンス
| プロパティ | タイプ | メモ |
|---|---|---|
[Agent] Message ID | 文字列 | 一意のID。スコアターゲットとして参照します。 |
[Agent] Model Name | 文字列 | レスポンスを生成したモデル。例:gpt-4o。 |
[Agent] Provider | 文字列 | モデルプロバイダー。例:openai、anthropic。 |
[Agent] Model Tier | 文字列 | fast、standard、または reasoning。モデル名から推論されます。 |
[Agent] Input Tokens / [Agent] Output Tokens / [Agent] Total Tokens | 数値 | トークンの使用状況。 |
[Agent] Cache Read Tokens / [Agent] Cache Creation Tokens | 数値 | プロバイダーのキャッシュの内訳を渡すときに表示されます。正確なブレンドコストを可能にします。 |
[Agent] Cost USD | 数値 | トークンとモデルの料金から自動的に計算された値、または直接渡した値。モデルの料金を決定できない場合は省略されます。 |
[Agent] Latency Ms | 数値 | コールの実行時間。 |
[Agent] TTFB Ms | 数値 | ストリーミングレスポンスの最初のバイトまでの時間。 |
[Agent] Temperature | 数値 | サンプリング温度。 |
[Agent] Finish Reason | 文字列 | 生成が停止した理由。 |
[Agent] Is Error / [Agent] Error Message | boolean / string | 呼び出しが失敗したかどうかとその理由。 |
[Agent] Is Streaming | ブール値 | レスポンスがストリーミングされました。 |
[Agent] Was Copied | ブール値 | ユーザーが出力をコピーしました。暗黙の肯定的なシグナル。 |
$llm_message.text | 文字列 | プライバシーモードによって制限されたレスポンスコンテンツ。 |
[エージェント]ツールの呼び出し
| プロパティ | タイプ | メモ |
|---|---|---|
[Agent] Tool Name | 文字列 | 呼び出されたツールの名前。 |
[Agent] Invocation ID | 文字列 | このツール呼び出しに対する一意の ID。 |
[Agent] Parent Message ID | 文字列 | 呼び出しをトリガーしたユーザーメッセージの[Agent] Message ID。 |
[Agent] Tool Input / [Agent] Tool Output | 文字列 | ツールペイロード。プライバシーモードによってゲート設定されています。 |
[Agent] Tool Success | ブール値 | ツールの呼び出しが成功したかどうか。 |
[Agent] Is Error / [Agent] Error Message | boolean / string | 障害の詳細。 |
[Agent] Latency Ms | 数値 | ツールの実行時間。 |
[エージェント]スパンと[エージェント]の組み込み
スパンは[Agent] Span Name、[Agent] Latency Ms、[Agent] Input State、[Agent] Output State、[Agent] Is Error、オプションの親スパンのネスト、およびユーザーが添付した任意のプロパティを保持します。エンベッディングには、AI Responseと同様に、モデル、プロバイダー、トークン、コストのプロパティが含まれます。Embedding イベントはセッションパイプラインに参加しないことに注意してください。これらのイベントはアイドルクロックをリセットしません。また、そのコストはセッションコスト USD に含まれません。
[エージェント]セッションの終了
ライフサイクルとタイムアウトのルールについては、セッションの終了方法を参照してください。
| プロパティ | タイプ | メモ |
|---|---|---|
[Agent] Output State | 文字列 | セッションの最終的なアプリケーション状態。 |
[Agent] Abandonment Turn | 数値 | ユーザーが退去した後のターン。値が低い場合、それは最初のレスポンスに対する不満を強く示唆しています。 |
[Agent] Session Idle Timeout Minutes | 数値 | このセッションを自動的に閉じる前に待機する時間をサーバに指示します。 デフォルトは30。 |
[Agent] Score
アプリケーションのフィードバックイベント。 Amplitudeは決してスコアを発行しません。プロジェクト内のすべてのスコアは、score()またはtrackScore()を介してコードから取得されます。
| プロパティ | タイプ | メモ |
|---|---|---|
[Agent] Score Name | 文字列 | 割り当てる名前(例:user-feedback、quality)。user-feedbackという名前には特別な意味があり、セッションで検出されたネガティブフィードバックシグナルを上書きします。 |
[Agent] Score Value | 数値 | 数値。thumbsには0と1を使用します。また、定義した任意のスケールを使用します。 |
[Agent] Target ID | 文字列 | スコアリングの対象となる[Agent] Message IDまたは[Agent] Session ID。 |
[Agent] Target Type | 文字列 | メッセージまたはセッション。 |
[Agent] Evaluation Source | 文字列 | ユーザー、AI、またはレビュー担当者。判断を行った人。 |
[Agent] Comment | 文字列 | オプションのフリーテキスト。 プライバシーモードによってゲート設定されています。 |
[エージェント]セッションのエンリッチメント
独自のセッションレベルのラベル:お客様のインフラストラクチャ上で計算された品質スコア、結果、トピック。trackSessionEnrichment()またはsetEnrichments()経由で送信されます。任意のプライバシーモードで動作します。これは、customer_enrichedモードにおけるプライマリデータパスです。
[エージェント]セッションレコード
セッションが終了した後に、セッションごとに一度発行されます。 これは品質分析の主力イベントです。セッションごとに1つの行で、すべてのシグナル結果とロールアップを伝送します。 1 セッションあたり正確に1つのセッションレコードがあります。
セッションの識別情報とロールアップ:
| プロパティ | タイプ | メモ |
|---|---|---|
[Agent] Session ID | 文字列 | セッション。 |
[Agent] Root Agent Name | 文字列 | セッションを開始したエージェント。 |
[Agent] Agent Chain Depth | 数値 | 最も長い委任パス上のエージェント。1は単一のエージェント、2は1ホップ、3以上はより深いレベルです。深さが1より大きい場合は、マルチエージェントを意味します。 |
[Agent] Close Reason | 文字列 | explicit_close または timeout。 |
[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 | 文字列 | セッションの内容についてモデルが短くまとめた要約。 |
[Agent] Taxonomy Version | 文字列 | Amplitudeがこのレコードを生成したときに、組織に対して公開された評価設定のID。 このエージェントの評価ツールが変更されていない場合でも、誰かが組織内の任意の評価ツールを公開するたびに、この値は変更されます。そのため、[Agent] Signal Versionsを使用してシグナルが変更されたかどうかを確認します。 |
[Agent] Signal Versions | 配列 | このセッションの結果を生成した組み込みのシグナル。それぞれ<signal>@<version>形式の(例:task_completion@2)で表されます。Amplitudeがこれらのシグナルのいずれかを更新した場合にのみ、この値が変更されます。 |
[Agent] Evaluated At / [Agent] Evaluation Source | timestamp / string | エンリッチメントが実行された時点。ソースはAIです。 |
シグナルの結果(セマンティクスについては、上記のシグナル表を参照してください)
| プロパティ | タイプ |
|---|---|
[Agent] Task Completed、プラス根拠および証拠 | boolean、文字列 |
[Agent] Response Quality、プラス根拠および証拠 | boolean、文字列 |
[Agent] User Intent、プラス根拠 | 分類、文字列 |
[Agent] Session Safety、プラス根拠 | 分類、文字列 |
[Agent] Has User Friction、プラス根拠および[Agent] Detected User Friction | boolean、string、array |
[Agent] Has Negative Feedback、プラス根拠および[Agent] Detected Negative Feedback | boolean、string、array |
[Agent] Has Data Quality Issues、プラス[Agent] Detected Data Quality Issues | boolean、配列 |
[Agent] Has Technical Failure | ブール値 |
[Agent] Has User Feedback / [Agent] User Score | Boolean / 数値。アプリがユーザーフィードバックのスコアを送信したときに存在します |
[Agent] Evaluator Result
終了したセッションごとに、アクティブなカスタム評価者ごとに一度発行されます。 カスタム評価者は、Amplitude UIで定義および調整を行うものです。組み込みのシグナルは、Evaluator Resultイベントを生成しません。
評価者のIDと出力:
| プロパティ | タイプ | メモ |
|---|---|---|
[Agent] Evaluator Name | 文字列 | 評価者、たとえばCompleted Interaction。 |
[Agent] Evaluator Output Type | 文字列 | binary、classification、またはscore。 |
[Agent] Evaluator ID | 文字列 | 評価者の安定したID。これはバージョンが変わっても名前が変更されても変わらないため、時間の経過とともに1つの評価者を追跡するために使用してください。 |
[Agent] Evaluator Version | 文字列 | 評価者のバージョン、1、2、3、など。 評価者を編集して昇格するたびに、この値が上がります。 Amplitudeが評価者のバージョンを追跡する以前のイベントでは、代わりにこの値は組織全体の設定IDを保持します。 |
[Agent] Evaluator Model | 文字列 | judgeモデル。プロバイダー:モデルの形式です。例:openai:gpt-5-mini。 |
[Agent] Evaluator Enrichment Cost USD | 数値 | この評価の実行にかかるコスト。 |
[Agent] Binary Label / [Agent] Binary Value | boolean / number | 結果、バイナリ評価子の場合。 |
[Agent] Primary Label / [Agent] Subcategories | 文字列 / 配列 | 分類評価者にとっての結果。 |
[Agent] Score Value / [Agent] Score Label | number / string | この結果、スコア評価者向けです。 |
[Agent] Evaluated At / [Agent] Evaluation Source | timestamp / string | 実行時。ソースはAIです。 |
すべての評価ツール結果に反映されるセッションディメンション。これにより、セッションレコードに接続することなく、評価ツールの結果をセグメント化できます:[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.