Vercel AI SDKトレースをAgent Analyticsに送信する

Vercel AI SDK 7は、OpenTelemetry GenAIスパンを@ai-sdk/otelを通じて送信します。そのエクスポータをAmplitudeに向けます。エージェントプロセスではAmplitude AI SDKは必要ありません。

このページでは、ai7.0.155と@ai-sdk/otel1.0.155の組み合わせ、およびai6.0.317と@ai-sdk/openai2.0.138の組み合わせについて説明します。Amplitudeは、エクスポートしたスパンを保存します。 個人データがインフラストラクチャを離れる前に、そのデータをスクラブしてください。エージェント分析のプライバシーモードを参照してください。

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

このプロンプトを、Cursor、Claude Code、Windsurf、GitHub Copilot、Codexなどの AI コーディング エージェントに貼り付けます。

text
Connect this Vercel AI SDK 7 app to Amplitude Agent Analytics with native OpenTelemetry.
Fetch https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/vercel-ai-sdk.md
and follow "Part 2: Coding agent procedure".
If @amplitude/ai is installed, the same file is under node_modules/@amplitude/ai/docs/integrations/.
Also follow https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/privacy.md
and scrub content before export.
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

変更を確認し、今すぐ始めるの手順に従って確認します。

必要な対応

  • 実行するもの:Nodeプロセス(@ai-sdk/otelをAmplitudeに向けてポイントします)。関数 ID はセッション ID ではありません。
  • 必要なもの:ai@7.0.155、@ai-sdk/otel@1.0.155、AmplitudeプロジェクトのAPIキー、およびすべてのターンで変わらない会話IDとプロダクト分析ユーザーID。
  • プロトコル:OTLP over HTTP。AmplitudeはprotobufとJSONを受け入れます。AmplitudeはgRPCを受け入れません。
  • プライバシー:Amplitudeは、受信後にコンテンツをスクラブ(匿名化)しません。recordInputs: falseおよびrecordOutputs: falseはメッセージテキストとツール引数をドロップします。セッション、ユーザー、エージェント、モデル、トークン数、およびツール名は引き続き到着します。エクスポートする前に、コンテンツ属性をマスクまたはドロップします。

エクスポート

エージェントプロセスでこれらの変数を設定します。環境変数に値がある場合、ヘッダー値内のスペースは%20としてエンコードします。Authorization=の記述は変更しないでください。

bash
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.amplitude.com/otlp/v1/traces
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<project API key>"
OTEL_SERVICE_NAME=order-support

EU地域のデータレジデンシーの場合はhttps://api.eu.amplitude.com/otlp/v1/tracesを使用します。

SDK 7の最初のモデル呼び出しの前にregisterTelemetry(new OpenTelemetry({ enrichSpan }))を呼び出します。enrichSpanは、gen_ai.conversation.id、user.id、およびgen_ai.agent.idを設定します。SDK 6では、experimental_telemetryを有効にしてから、これら3つの属性をスパンプロセッサから設定します。ツールのループでは、stopWhen: stepCountIs(...)を設定して、最後のモデル呼び出しに返信テキストが含まれるようにします。Amplitudeは、SDK 6 ai.generateText.doGenerateをモデル呼び出し、およびai.toolCallをツール呼び出しにマップします。親ai.generateTextスパンはスパンのままです。

アイデンティティ

引き継がれるもの

ツールループが継続する場合、以前のユーザーテキストがgen_ai.input.messages内で繰り返されます。Amplitudeは、以前のユーザーメッセージを再度送信しません。 ツールの出力は[Agent] Tool Outputです。

セッションを閉じる

[Agent] Session Endはオプションであり、推奨されます。ネイティブのAI SDKエクスポートでは、この値は送信されません。 Amplitudeは、デフォルトで条件を満たすエージェントイベントなしで30分後にセッションを終了します。また、セッションごとのオーバーライドが設定されていない場合は、セッション開始から24時間後にセッションが終了します。最初に閉じたものがカウントされます。セッションレコードとコンテンツベースのシグナルを含むエンリッチメントは、その終了後に一度実行されます。OpenTelemetryトランスレータは、スパンからidle-timeout属性を読み取ることはありません。 セッションの終了方法を参照してください。

今すぐ始める

Vercel AI SDK連携ガイドに従ってください。同じ会話IDを使用して2つのターンを送信し、Live Eventsで確認します。

  1. セッションIDはgen_ai.conversation.idであり、トレースIDではありません。
  2. ユーザーIDはプロダクト分析ユーザーであり、unknownではありません。
  3. エージェントIDはgen_ai.agent.idです。
  4. ターンには、ユーザーメッセージのテキスト、ツール呼び出し、AIレスポンスのテキストが表示されます。また、モデル名と両方のトークン数も含まれます。
  5. 2番目のターンでは、最初のユーザーメッセージは複製されません。

このガイドは2026年10月28日に、ai 7.0.155、@ai-sdk/otel 1.0.155、@ai-sdk/openai 6.0.317、およびai 2.0.138に対して最後に検証されました。VercelとAI SDKは、その所有者の商標です。 Amplitudeは、その所有者と提携していません。また、その所有者によって承認されていません。

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

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.

このページでは