AI SDKなしでエージェントイベントを送信する
AI SDKなしでも、任意の標準Amplitude SDKのtrack()を使用するか、HTTP APIにPOSTすることで、自分で[Agent]イベントを送信することでエージェント分析データを送信することができます。Amplitudeは、SDK生成型のイベントと同じ方法で、セッションを構築し、これらのイベントに対してエンリッチメントを実行します。
このパスは、AI SDKが使用するランタイムに適合しない場合に使用します。AI SDKはNode.jsとPythonのみをサポートしているため、一般的なケースは、ブラウザやクライアントサイドの処理が重いSPA、Cloudflare WorkersやDenoなどのエッジランタイム、Java、Go、Rubyなどの言語です。また、Lovable、Superblocks、v0、BoltなどのAIアプリビルダーも対象となります。これらの環境では、生成されたアプリがブラウザ優先であり、Node専用のモジュールに@amplitude/aiをインポートすると失敗します。AI SDKを実行できる場合は、代わりにAI SDKを使用してください。このSDKはセッションのライフサイクル、墨消し、IDを自動的に処理します。
SDKがない場合、次の3つのジョブがコードに移動します。
- セッションのライフサイクル:作業単位が完了したときに
[Agent] Session Endを送信します。これはオプションであり、推奨されます。 これを省略した場合、Amplitudeはデフォルトで30分間のアイドル状態でセッションを終了します。 - プライバシー:
track()を呼び出す前に、コンテンツを編集します。 - IDの規律:セッション、ターン、トレース、およびエージェントの各IDを生成してスレッドします。
最小限のイベントを送信する
すべてのセッションに対して以下のイベントを発行します。
[Agent] User Message[Agent] Tool Call、呼び出しごとに1回(エージェントがツールを使用する場合のみ)[Agent] AI Response[Agent] Session End、オプションだが推奨、作業単位が終了するごとに1回
ワイヤ形式は、[Agent]イベントコントラクトをJSONにしたAmplitudeのHTTPエンドポイントへのPOSTです。
curl -X POST https://api2.amplitude.com/2/httpapi \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY",
"events": [{
"event_type": "[Agent] User Message",
"user_id": "user-123",
"event_properties": {
"[Agent] Session ID": "ticket-42",
"[Agent] Turn ID": 1,
"[Agent] Trace ID": "trace-abc",
"[Agent] Agent ID": "support-bot",
"[Agent] Message ID": "msg-1",
"$llm_message": { "text": "I need a refund" }
}
}]
}'
EU域内のデータレジデンシーの場合は、https://api.eu.amplitude.com/2/httpapiを使用してください。このページの残りの部分は、標準の SDK track()ルートと未加工の HTTP ルートの両方に適用されます。
すべてのイベントには、共有プロパティ([Agent] Session ID、[Agent] Turn ID、[Agent] Trace ID、[Agent] Agent ID、[Agent] Env、および[Agent] Runtime)に加え、そのイベントタイプに必要なプロパティも含まれます。プロダクト分析に使用するものと同じユーザーIDを送信し、再試行しても重複が発生しないように、各イベントに対して一意のinsert_idを設定します。各イベントの必須プロパティについては、タクソノミーのイベントコントラクトを参照してください。
常に[Agent] Agent IDを設定してください。設定されていない場合、Amplitudeはイベントを受け入れるものの、セッションにグループ化できないため、エージェント分析のビューには表示されません。HTTP APIは、エージェント分析がイベントを処理する前に受信を確認するため、依然として200を返します。そのため、200は正しくグループ化されていることの確認には使用できません。
セッションが実行されたA/Bテストまたは機能フラグのバリアントを記録するには、key:variant文字列の配列としてすべてのイベントに[Agent] Experimentsを追加します(例:["planner:v2"])。実験がちょうど1つだけ該当する場合は、[Agent] Experiment Key、[Agent] Experiment Variant、および[Agent] Experiment Unit(agent_session、turn、またはspan)も設定します。Agent Analyticsの実験バリアントの記録を参照してください。
ユーザーの評価を[Agent] Scoreイベントとして送信する場合は、AI SDKを使用せずにフィードバックを送信するを参照してください。
手動によるインストルメンテーションが誤ってしまうルール
$llm_messageはオブジェクトです:{ text: "..." }の形式で送信してください。Amplitudeはエラーのない普通の文字列を無視し、スレッドビューにはメッセージのコンテンツが表示されません。- Turn IDはイベントではなく交換を識別します。ユーザーメッセージのラウンドトリップごとにこの値を1回増分し、その交換のユーザーメッセージ、すべてのツール呼び出し、およびAIレスポンスに同じ値をスタンプします。ターン内の順序付けはイベント時間から行われるため、実際の実行順序では、AIレスポンスの前にツール呼び出しを発行してください。ラウンドトリップごとに
[Agent] Trace IDを1つ生成し、同じイベント間で共有します。 - タクソノミーの範囲内にとどめる:未登録のイベントタイプやプロパティはチャートでクエリできない可能性があるため、
[Agent]プレフィックスの下にイベントタイプやプロパティを作成しないでください。購入、予約、レコメンデーションのクリックなど、エージェントが実行するビジネスアクションについては、既存の名前と同じuser_idを使用して標準のプロダクトイベントを送信します。これにより、エージェント駆動型とクリック駆動型のジャーニーが1つのファネルで比較可能になります。 - コストは自分で指定する:Amplitudeはモデルやトークンのプロパティから
[Agent] Cost USDを計算しないため、コストレポートが必要な場合はこの値を含めてください。コストの計算方法を参照してください。 - トークンとコストのプロパティは「AI Response」イベントでのみ発生します。ツール呼び出しはトークンを消費しません。サーバーは取り込むすべてのイベントからの
[Agent] Cost USDを合計するため、Tool CallやSession Endにコストを含めるとセッション合計値が実際よりも大きくなります。 - ユーザー間でセッションIDを再利用しないでください:共有セッションIDを使用すると、異なるユーザーの会話が統合され、ユーザーごとの分析が損なわれます。
セッションを閉じる
ジョブが終了したとき(チャットが終了したとき、チケットが解決されたとき、実行が完了したときなど)に[Agent] Session Endを送信します。サーバーは、SDKが発行するクローズの場合とまったく同じ方法で、そのイベントのセッションを閉じます。終了するセッションと一致する[Agent] Session IDイベントを含め、エージェント分析を有効にしたプロジェクトにイベントを送信します。
{
"event_type": "[Agent] Session End",
"user_id": "user-123",
"event_properties": {
"[Agent] Session ID": "session-abc",
"[Agent] Agent ID": "support-bot"
}
}
Amplitudeはイベントの任意の追加プロパティを保存しますが、これらのプロパティは終了には影響しません。
Session Endを送信しない場合、サーバーは30分間の非アクティブ状態が続くと、セッションを閉じます。そのタイムアウト値が、放棄されたセッションをキャッチします。 終了の仕組みと、遅延イベントがエンリッチメントを逃す理由については、「セッションの終了方法」を参照してください。
セッションを30分以上開いたままにするには、[Agent] Contextにアイドルタイムアウトの上書きを設定します。セッションIDをローテーションすると1つの会話が複数のセッションに分割されてしまうため、代わりに独自の短いアイドルタイマーを作成しないでください。セッションのタイムアウトの設定を参照してください。
追跡する前にコンテンツをリダクトする
編集は、track()の前に実行する必要があります。最も一般的な間違いは、メッセージのコンテンツにゲートを設定し、コンテンツを含む他のプロパティを忘れてしまうことです。プライバシーモードを次の4つすべてに適用します。
- [ ユーザーメッセージとAIレスポンスの
$llm_message.text - [ AIレスポンスの
[Agent] System Prompt - [ Tool Callの
[Agent] Tool Inputおよび[Agent] Tool Output(ペイロードはオブジェクトであるため、再帰的に編集します) - [ スコアの
[Agent] Comment
metadata_only動作の場合は、4つすべてを省略します。まだ、コスト、レイテンシ、トークン、セッショングループ化は引き続き表示されます。full動作の場合は、追跡の前にPII(メールアドレス、電話番号、SSN、クレジットカード番号、IPアドレス)を除去してください。
ブラウザとエッジのノート
- アイデンティティ:
localStorageに永続的な匿名UUIDを保存し、user_idとして送信すると、匿名の訪問者に安定したアイデンティティを提供できます。標準のID 解決では、ユーザーがサインインするときにそれらを統合します。 - セッションリプレイ:セッションリプレイプラグインを有効にした状態で、すべてのエージェントイベントにリプレイプロパティを追加して、セッションが録画にリンクするようにします。 セッションリプレイへのリンクを参照してください。
- トランスポート:ビーコントランスポートをグローバルに設定しないでください。たとえば、セッション終了ハンドラ内などで
setTransport('beacon')を呼び出すと、SDK全体に永久に適用され、以降のイベントが再試行なしで一度だけ送信されて、エラーなしで破棄される可能性があります。デフォルトのトランスポートを使用してください。 - Latencyとトークン: これらをサーバー側で測定し、レスポンスとともにクライアントに返し、イベントに添付します。
AIアプリビルダー内のインストルメント
Lovable、Superblocks、または任意のプロンプト駆動型ビルダーの場合は、このプロンプトをビルダーのエージェントに貼り付け、生成される内容を確認します。
Instrument this app's chat agent with Amplitude Agent Analytics using the standard
@amplitude/analytics-browser SDK (do NOT use @amplitude/ai, it is Node-only and will
crash this runtime). Emit these events via amplitude.track(): [Agent] User Message at
request start, one [Agent] Tool Call per tool invocation in execution order,
[Agent] AI Response after the reply, and [Agent] Session End when the chat genuinely ends
(no short idle timers; the server auto-closes idle sessions). On every event include
[Agent] Session ID (one stable UUID per conversation), [Agent] Turn ID (increment once
per user-message exchange and stamp the same value on all events of that exchange),
[Agent] Trace ID (new UUID per exchange), [Agent] Agent ID (a stable name for this agent),
and [Agent] Runtime: "browser". Message text goes in $llm_message as { text: "..." }
(an object, not a string) on User Message and AI Response only. Put [Agent] Model Name,
[Agent] Provider, token counts, [Agent] Latency Ms, and [Agent] System Prompt on AI
Response only. Put [Agent] Tool Name, [Agent] Tool Success, [Agent] Latency Ms,
[Agent] Invocation ID, and [Agent] Parent Message ID on Tool Call. Redact PII (emails,
phones, SSNs, cards, IPs) from all message text, system prompts, and tool payloads
before tracking. Use one persistent anonymous UUID from localStorage as the Amplitude
user_id. Never call setTransport("beacon"). Use functional state updates when computing
turn counters from UI state so follow-up messages aren't lost to stale closures.
次に、2つのメッセージを送信し(1つはツールをトリガーするもの)、ライブイベントで次の事項を確認します。
- すべてのイベントは1つのセッションIDを共有します。
- 各エクスチェンジは、1つのTurn IDと1つのTrace IDを共有します。
- ツールの呼び出しは、AI Responseの前に行われます。
$llm_message.textは、セッションスレッドビューに表示されます。
これは役に立ちましたか?
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.