データウェアハウスからエージェントの会話をインポートする

ウェアハウスインポートは、Snowflake、BigQuery、Databricksにすでに保存されているエージェントの会話を[Agent]イベントに変換します。AI SDKやフォワーダージョブは必要ありません。テーブルを標準の形状にマップするSQLクエリを1つ書くと、Amplitudeのウェアハウスインポートは設定したスケジュールでそのクエリを実行します。 OpenTelemetry、OpenInference、またはMLflowスパンとして保存された会話は、AmplitudeのOTLPエンドポイントにリプレイされる別のパスを使用します。

履歴を含めた、ウェアハウスにすでに届いている会話については、ウェアハウスインポートを使用します。まだエージェントを構築中の場合は、代わりにAI SDKまたはOpenTelemetryを使用してインストルメントしてください。これにより、実行状況をより詳細に記録できます。

AIコーディングエージェントを使用した設定(推奨)

このプロンプトを、Cursor、Claude Code、Windsurf、GitHub Copilot、CodexなどのAIコーディングエージェントに貼り付けます。エージェントはガイドを取得し、ジョブを構築してから、ドライランを開始します。

text
Connect the agent conversations in our warehouse to Amplitude Agent Analytics.
Fetch https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/warehouses/README.md
If @amplitude/ai is installed, the same file is under node_modules/@amplitude/ai/docs/integrations/.
Follow links in the guide. If your source isn't listed, start at https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/README.md
Follow "Part 2: Coding agent procedure". Start with a dry run.

エージェントは停止し、推測できない値(ユーザーIDがどのフィールドに保持されているかなど)を尋ねます。 その変更を確認し、「Get started(開始する)」の手順に従って検証します。

この機能がもたらすメリット

  • 記述するもの:Stage 1と呼ばれる、テーブルから標準列へのマッピングクエリ。2番目の共有クエリであるStage 2は、これらの列を[Agent]イベントに変換します。Stage 2は編集しないでください。
  • Amplitudeはインポートを実行します。これはスケジュールに従って、通常1時間ごとに実行されます。手動でクエリを再実行することはありません。
  • ウェアハウスでは、以下が実行されます:ウェアハウスのコンピューティング上でクエリ自体が実行されます。Databricksでは、イベントテーブルを最新の状態に保つためのMERGEジョブもスケジュールします。

サポートされているソース形式

テーブルが会話を保存する方法に一致するガイドを選択してください。

まず、ウェアハウスインポートの概要から始めます。この概要では、共有列、設定、およびウェアハウスごとの設定について説明します。

ウェアハウス要件

  • Snowflake:データタイプがイベントで、import_cursor列に基づくタイムスタンプ同期が設定されたAmplitude内のSnowflakeソース。タイムスタンプをUTCとして保存します。
  • BigQuery:データタイプがイベントで、import_cursor列に基づくタイムスタンプ同期が設定されたAmplitude内のBigQueryソース。
  • Databricks:AmplitudeのDatabricksインポートは、Deltaテーブルの変更データフィードを読み取りますが、ビューを読み取ることはできません。 変更データフィードをオンにした状態でイベントテーブルを作成し、クエリの出力をそのテーブルに書き込むMERGEジョブをスケジュールします。

また、プロダクト分析のユーザーIDと一致するユーザーID列も必要です。 Amplitudeは、会話ID、ユーザーIDまたはデバイスID、またはエージェントIDなしで行をドロップします。

引き継がれるもの

ウェアハウスインポートでは、テーブルに記録されたもののみが送信されます。 モデル、トークン、コスト、ツールの呼び出しは、テーブルにそれらの値が含まれている場合に到着し、そうでない場合には空のままになります。Amplitudeは欠落値を推定しません。各会話に1つの[Agent] Session Endが割当られるため、確定した時点で組み込みのシグナルが一度だけ実行されます。オプションのexperiment_keyおよびexperiment_variant列は、単位がagent_sessionである[Agent] Experiment*プロパティになり、1行あたり1つの実験となります。無効なキーやバリアントを持つ行は、これらの情報がない状態でインポートされます。エージェント分析に実験バリアントを記録するを参照してください。フィールドを除外または秘匿する場合は、データがウェアハウスから出る前のステージ1の段階で行います。パターンリストとメタデータのみの選択肢は、Agent分析のプライバシーモードにあります。

鮮度と制限

  • 確定にかかる時間:会話は、アイドル状態がsettle_hoursにわたり続いた後にインポートされます。デフォルト値は2です。この値は、会話の中で実際に生じる最長の中断時間よりも長く設定してください。
  • 更新:インポートでは、新しい行と、updated_atがより新しい行が取り込まれます。インポート後に再開される会話は、最初のSession Endを保持します。
  • 重複:Amplitudeは、7日間の期間内に繰り返しイベントの重複排除を行います。より古い行を再インポートすると、重複が作成されます。
  • バックフィル:最初の同期では、クエリによって返された、完了したすべての会話がインポートされます。まず1週間分をインポートして確認し、クエリが遡る期間を広げます。

保存済みスパンをリプレイする

OpenTelemetry、OpenInference、またはMLflowの各スパンについては、ウェアハウスからスパンをエクスポートし、otlp-replay.mjsでリプレイします。このインストールでは、SDKがアプリに追加されません。

bash
npm install --no-save --ignore-scripts @amplitude/ai
node node_modules/@amplitude/ai/docs/integrations/warehouses/otlp-replay.mjs

このスクリプトには Node.js 18 以降と Amplitude プロジェクトの API キーが必要です。このスクリプトは、Amplitude の米国または EU の OTLP エンドポイントにスパンを送信します。エクスポートと再プレイをスケジュールします(例:1時間ごと)。送信せずにプレビューするには、--dry-runを使用します。

スパンに会話IDがない場合、各トレースは独自のセッションになります。Amplitudeは、その期間内でのみ重複排除を行うため、7日より古いウィンドウを再生しないでください。

今すぐ始める

  1. サポートされているソース形式から、使用している形式のガイドを開きます。
  2. Stage 1を記述します。このインストールでは、SDKはアプリに追加されません。npm install --no-save --ignore-scripts @amplitude/aiを実行し、その後node node_modules/@amplitude/ai/docs/integrations/check-agent-events.mjsでサンプルを確認します。
  3. Amplitudeでウェアハウスソースを作成し、1週間のデータに対して最初の同期を実行します。
  4. ライブイベントとセッションビューアを確認し、2回目の同期を実行して、重複がないことを確認します。

ガイドの最終確認日は2026年10月6日です。

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

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.

このページでは