エージェント分析のセッションおよびユーザーID

エージェントセッションは、エージェントがユーザーに対して実行する作業の1つの単位です。開始、一連のターン、および結果(チケットの解決、タスクの完了、会話の終了など)があります。 エージェント分析は、その結果を生成したすべてのイベントを1つの[Agent] Session IDの下にグループ化し、セッションが終了した後にセッションに対してエンリッチメントを実行します。[Agent] Session Endはオプションですが、推奨されます。それを送信することが明示的な終了となります。このメッセージが決して到着しない場合、Amplitudeは以下のライフサイクルルールに従ってセッションを終了します。 インストルメントを行う前にセッションIDとユーザーIDを決定してください。どちらも値も、ロールアウト後に変更することは困難です。

セッションとは

セッションは、1つの結果(User Message、AI Response、Tool Call、Score、Span)を生成するイベントを1つの[Agent] Session IDにグループ化します。セッションは、コードが最初にイベントをそのIDに添付したときに開始され、アクティビティが到着し続ける間は開いたままとなり、明示的またはアイドルタイムアウトのいずれかによって終了します。エンリッチメント(セッションレコード、シグナル、評価ツールの結果)は、セッションが終了した後に、セッションごとに一度実行されます。

すべてのセッションはユーザーに属しています。プロダクト分析に使用しているのと同じユーザーIDを渡します。 ユーザーIDの設定を参照してください。

エージェントセッションと標準分析セッション

エージェントセッションはAmplitudeの標準分析セッションではありません。エージェントセッション([Agent] Session ID)は、ユーザーがエージェントに渡す1つのジョブであり、アプリケーションがそのIDを所有しています。Amplitudeの標準的な分析セッション$session_idは、セッションリプレイとプロダクトレポートの基盤となる、ユーザーのアプリまたはウェブへの訪問です。1回の訪問には、複数のエージェントセッションが含まれている可能性があります。 これら2つを接続するには、エージェントセッションをセッションリプレイにリンクするを参照してください。

セッションIDを選択する

アプリケーションが「this unit of work(この作業単位)」に対してすでに持っているIDを渡します。

一致するものがない場合は、セッション開始時に安定したUUIDを生成し、チケット行、スレッドレコード、リクエストコンテキストなど、アプリケーションがすでに作業単位の状態を保持している場所にそのUUIDを永続化してください。すべてのリクエストハンドラを通じて同じIDを維持することで、1つのセッション内でターンを継続できるため、リクエストごとに新しいIDを生成しないでください。

同じユーザーが新しい目標で戻ってきた場合、新しいIDを使用して新しいセッションを開始します。 ユーザー間でセッションIDを再利用しないでください。共有またはグローバルなセッションIDは、異なるユーザーの会話を統合し、ユーザーごとの分析を中断します。

セッションの終了方法

エンリッチメントは終了したセッションでのみ実行されます。 [Agent] Session Recordイベントが表示されない場合は、ここから開始してください。

セッションは次の2つのいずれかの方法で終了します。

  1. 明示的に閉じる(推奨):作業単位が完了した時点で(チケット解決、呼び出し終了、実行完了など)、コードが[Agent] Session Endを送信します。AI SDKでは、trackSessionEnd()(Node)またはtrack_session_end()(Python)で呼び出すか、スコープ終了時にセッションを閉じるスコープヘルパーを使用してセッションを開きます(Nodeの場合はrun()、およびPythonではsession()コンテキストマネージャーを使用します)。SDKを使用しない場合は、イベントを自分で送信してください。 セッションを閉じるを参照してください。 Amplitudeは、次の取り込みバッチがSession Endイベントを処理する際にクローズを書き込むため、この[Agent] Session Recordイベントは通常15~20分で到着します。組織にエンリッチメントのバックログがある間は、これに時間がかかることがあります。
  2. アイドルタイムアウト(自動フォールバック):明示的に閉じない場合、サーバーはデフォルトでセッションに受信された最後のエージェントイベントから測定された30分間の非アクティブ状態の後にセッションを終了します。 次の6つの[Agent]イベントのいずれかが時計をリセットします:ユーザーメッセージ、AI応答、ツール呼び出し、セッション終了、スコア、スパン。Session RecordやEvaluator Resultなど、サーバー生成のエンリッチメントイベントは、リセットしません。取り込みは周期的に実行されるため、アイドル期間が経過した後、およそ15分でcloseが実行されます。

すべてのセッションレコードには、explicit_closeまたはtimeoutのいずれかの[Agent] Close Reasonがあるため、アイドルタイムアウトによりセッションが何度閉じられたかをモニタリングできます。

クローズは完了を示しており、セッションはロックされません。Amplitudeは引き続き後のイベントを受け入れ保存しますが、エンリッチメントは一度しか実行されないため、遅れて到着したイベントはセッションのシグナル、ロールアップ、またはセッションレコードに到達しません。最初のクローズのみがカウントされます。Amplitudeは重複を無視し、アイドルタイムアウトによってすでにセッションが終了した後に到着した[Agent] Session Endイベントも無視します。ジョブが完了したら閉じます。 実際の作業が続く場合は、新しいセッションを開始してください。

アイドルタイムアウト値

セッションごとのオーバーライドのないセッションも、アクティビティに関係なく、24時間後に終了します。 任意のオーバーライド(正の値または-1)を設定すると、そのセッションはその上限の対象外になります。

タイムアウトを小さく設定しすぎると、長い一時停止によりセッションが早期に終了してしまいます。フォローアップイベントは引き続き添付され、Amplitudeはそれらを保存しますが、エンリッチメントが実行された後に表示されるため、セッションレコードに到達することはありません。 -1は、アクティビティのない期間が通常のことで上限も読めな場合(週末に放置されたチケットや長時間実行されるバックグラウンドジョブなど)に使用します。固定のタイムアウトを設定すると最終的に実際のジョブが分割されてしまうからです。トレードオフとして、アプリ側でセッションを閉じ忘れた場合、90日間のバックストップによって終了されるまでセッションは開いたままとなり、エンリッチされません。

-1に関する2つの注意事項

  • エンリッチメントが無効になっているエージェントは、組織のデフォルトのスケジュールで終了します。
  • 90 日の制限は、セッションの開始日付からカウントされます。そのため、90 日以上継続したセッションは自動的に終了しません。

オーバーライドを設定するには、セッションタイムアウトの設定を参照してください。

ユーザーIDを設定する

Amplitudeは、匿名セッション、サインイン、複数のデバイスにわたって3つの識別子(デバイスID、ユーザーID、Amplitude ID)を1つのプロファイルに組み合わせることで、ユニークユーザーをカウントします。 ユーザーが認証されるとすぐに安定したユーザーIDを送信します。これにより、同じデバイス上の匿名イベントが1つのプロファイルに統合され、アクティブユーザー数が正確なままになります。

すべての[Agent]イベントに安定したユーザーIDが指定されている場合、エージェントとプロダクトの動作を網羅したファネル、コホート、リテンションチャートを作成できます。

Amplitudeが別のプロジェクトでユーザーIDに関連付けられている既知のデバイスIDに遭遇した場合、AmplitudeはPortfolioアドオンを持っていなくても、すべてのプロジェクトでデバイスIDがそのユーザーIDに関連付けられていると仮定します。 詳細については、「ポートフォリオ」を参照してください。

2つのルールが、1人のユーザーが2つに分割されるのを防ぎます:

  • 決してプレースホルダのユーザーIDを渡さないでください。 プレースホルダには、"anonymous"、空の文字列、または一時IDを含めます。一度設定されたユーザーIDを変更することはできないため、プレースホルダは、後でマージされない永続的な別のユーザーを作成します。 代わりにユーザーIDを省略します。 匿名アクティビティは、ユーザーが識別されると、標準的なID 解決によって既知のIDに統合されます。
  • プレアカウントセッション全体で同じデバイスIDを再利用してください。 バックエンドがリクエストごとに新しいデバイスIDを生成すると、IDのマージは中断されます。可能であれば、Browser SDKからデバイスIDを読み取り、転送します。

インストルメンテーションの初日にID戦略を決定します。

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

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.

このページでは