このページでは

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.

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

早期アクセス

この機能は早期アクセスです。 この期間中、機能のさまざまな側面はまだ開発されている可能性があり、このドキュメントは常に最新であるとは限りません。 ご質問がある場合は、までお問い合わせください。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_intentやproduct_areaなど)や評価者名(task_completionなど)は設定から取得され、プロジェクトごとに異なります。独自の評価者を作成および調整するには、カスタム評価者の作成と調整に移動します。

非推奨イベント

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

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