On this page

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.

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

Early Access

This feature is in Early Access. During this time, aspects of the functionality may still be developed, and this documentation may not always be up to date. If you have any questions, contact Amplitude Support.

このページは、Agent アナリティクスが生成するデータ(すべての[Agent]イベント、エンリッチメントイベントのプロパティ、デフォルトのシグナルなど)のリファレンスです。これらの結果を UI で読むには、[エージェント結果の分析] に移動してください。 コードからイベントを送信するには、Agent アナリティクス SDK にアクセスしてください。

このタクソノミーは設定可能であり、オープンベータ版の期間中も進化を続けています。以下のリストをデフォルトの形式として扱い、ライブセットを自分のイベントストリームと照合して確認してください。

データ階層

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

  • セッション: ユーザーが最初から最後までエージェントに渡す 1 つのジョブです。 Amplitude は、[Agent] Session IDプロパティを持つセッションを識別します。 エージェントセッションは、ユーザーのアプリまたはウェブへの訪問を指す Amplitude の標準分析セッション($session_id)とは異なります。
  • ターン:セッション内での1回の往復のやり取り(ユーザーメッセージ、エージェントのツール呼び出し、AIの応答)です。
  • スパン: ツール呼び出し、ベクトル検索、リランク、ガードレールなどのサブターンステップです。

すべてのユーザーメッセージ、AIレスポンス、ツールコールは独立したAmplitudeイベントとして送信されるため、まずトレースを分解することなく、ファネル、コホート、リテンションチャートでエージェントデータを活用できます。

イベントインベントリ

Agent アナリティクスはこれらのイベントを生成します。SDK のインストルメンテーションは、SDK の直接呼び出しを通じて、または enable_otel() / enableOtel() がアクティブな場合には OTEL スパンを通じて、最初の 7 つを生成します(SDK はスパンを自動的にイベントにマップします)。サーバーエンリッチメントパイプラインは、セッションの終了後に残りのデータを生成します。

SDKイベント

エージェントの実行時にインストルメンテーションがこれらのイベントを生成します。この[Agent] AI Responseイベントはレスポンスごとのモデル、プロバイダー、トークン、レイテンシ、コストのプロパティを伝送します。

  • [Agent] User Message:ユーザーがエージェントに送信するメッセージです。
  • [Agent] AI Response:エージェントの応答。モデル、プロバイダー、トークン、レイテンシー、コストなどが含まれています。
  • [Agent] Tool Call:エージェントが呼び出す関数またはツールです。
  • [Agent] Embedding:埋め込みまたはベクター検索のステップです。
  • [Agent] Span:リランクやガードレールなど、その他のパイプラインステップです。
  • [Agent] Session End:セッションの終了を示します。
  • [Agent] Session Enrichment:プライバシーモードで送信される、customer_enriched独自のセッションラベルです。

すべての SDK イベントプロパティには、[Amplitude] Session Replay IDを除き、[Agent]のプレフィックスが付きます。以下の表は、SDK が発行するプロパティをイベント別にグループ化したものです。 オプションのプロパティは、関連するデータが利用可能で、プライバシーモードで許可されている場合に設定されます。

共通のプロパティ

これらのプロパティは、任意の SDK イベントに表示できます。

導入と OTEL のメタデータ

これらのオプションのプロパティは、設定時に任意の SDK イベントに表示できます。

[Agent] User Message プロパティ

共通のプロパティに加えて。

[Agent] AI Response プロパティ

共通のプロパティに加えて。

[Agent] Tool Call プロパティ

共通のプロパティに加えて。

[Agent] Embedding プロパティ

共通のプロパティに加えて。

[Agent] Span プロパティ

共通のプロパティに加えて。

[Agent] Session End プロパティ

共通のプロパティに加えて。

[Agent] Session Enrichment プロパティ

customer_enrichedプライバシーモードで送信されました。 共通のプロパティに加えて。

[Agent] Score プロパティ

[Agent] Score ユーザーからの明確なフィードバックを伝えます。 共通のプロパティに加えて。

イベントJSONの例

これらの例は、SDKがAmplitudeに送信する内容を示しています。 プロパティ名と$llm_messageコンテンツシェイプは、SDKを使用する場合もイベントを直接送信する場合も同じです。

json
{
  "event_type": "[Agent] AI Response",
  "user_id": "user-42",
  "event_properties": {
    "[Agent] Session ID": "sess-abc123",
    "[Agent] Trace ID": "trace-def456",
    "[Agent] Turn ID": 2,
    "[Agent] Message ID": "msg-789xyz",
    "[Agent] Model Name": "gpt-4o",
    "[Agent] Provider": "openai",
    "[Agent] Model Tier": "standard",
    "[Agent] Latency Ms": 1203,
    "[Agent] Input Tokens": 150,
    "[Agent] Output Tokens": 847,
    "[Agent] Total Tokens": 997,
    "[Agent] Cost USD": 0.0042,
    "[Agent] Is Error": false,
    "[Agent] Finish Reason": "stop",
    "[Agent] Component Type": "llm",
    "[Agent] Agent ID": "support-bot",
    "[Agent] Env": "production",
    "[Agent] SDK Version": "1.0.0",
    "[Agent] Runtime": "node"
  }
}
json
{
  "event_type": "[Agent] User Message",
  "user_id": "user-42",
  "event_properties": {
    "[Agent] Session ID": "sess-abc123",
    "[Agent] Turn ID": 1,
    "[Agent] Message ID": "msg-123abc",
    "[Agent] Component Type": "user_input",
    "[Agent] Agent ID": "support-bot",
    "[Agent] SDK Version": "1.0.0",
    "[Agent] Runtime": "node",
    "$llm_message": { "text": "How do I reset my password?" }
  }
}
json
{
  "event_type": "[Agent] Tool Call",
  "user_id": "user-42",
  "event_properties": {
    "[Agent] Session ID": "sess-abc123",
    "[Agent] Turn ID": 3,
    "[Agent] Invocation ID": "inv-456def",
    "[Agent] Tool Name": "search_knowledge_base",
    "[Agent] Tool Success": true,
    "[Agent] Is Error": false,
    "[Agent] Latency Ms": 340,
    "[Agent] Component Type": "tool",
    "[Agent] Agent ID": "support-bot",
    "[Agent] SDK Version": "1.0.0",
    "[Agent] Runtime": "node"
  }
}
json
{
  "event_type": "[Agent] Score",
  "user_id": "user-42",
  "event_properties": {
    "[Agent] Score Name": "thumbs-up",
    "[Agent] Score Value": 1,
    "[Agent] Target ID": "msg-789xyz",
    "[Agent] Target Type": "message",
    "[Agent] Evaluation Source": "user",
    "[Agent] Session ID": "sess-abc123",
    "[Agent] Agent ID": "support-bot",
    "[Agent] SDK Version": "1.0.0",
    "[Agent] Runtime": "node"
  }
}

サーバ拡張イベント

セッションが終了すると、エンリッチメントパイプラインがセッションを評価し、2つのイベントをイベントストリームに書き戻します。

セッション記録

[Agent] Session Record セッションごとに1回発生します。 このメッセージには、セッションのロールアップ、常時接続信号の結果、および品質フラグが含まれます。

評価結果

[Agent] Evaluator Result 評価者ごとにセッションごとに1回記録されます。 それは、信号検出器、トピック分類器、ルーブリックスコアラーなどのすべてのサーバー側評価のための統一イベントです。

ユーザーフィードバックスコア

[Agent] Scoreは、応答に対する「高く評価」や「低く評価」など、ユーザーの明示的なフィードバックを記録します。スコアは、エンリッチメント パイプラインからではなく、SDK のscore()メソッドを通じてアプリケーションから得られます。 スコアを送信するには、[ユーザーフィードバック(スコア)を送信] に移動します。

シグナル

シグナルはデフォルトの常時稼働の評価機能で、Amplitudeは終了したすべてのセッションに対して実行します。これらは[Agent] Evaluator Resultイベントとして記録されます。ユーザーはそれらを設定しません。Amplitudeは時間をかけてそれらを洗練するため、それらは傾向を示す目安として扱ってください。

トピックとカスタム エバリュエーター

デフォルトの信号以外にも、独自のトピックモデルと評価者を定義できます。 エンリッチメントタクソノミーは完全に設定可能です。トピックモデル名(query_intentproduct_areaなど)や評価者名(task_completionなど)は設定から取得され、プロジェクトごとに異なります。独自の評価者を作成および調整するには、カスタム評価者の作成と調整に移動します。

非推奨イベント

[Agent] Topic Classificationは非推奨です。 トピック分類は、出力タイプが classification[Agent] Evaluator Result イベントとして表示されるようになりました。Rubricスコアも[Agent] Scoreから、出力タイプがscoreである[Agent] Evaluator Resultへと移動しました。[Agent] Scoreは現在、ユーザーフィードバックのみを保持しています。

Was this helpful?