AI SDKを使用してエージェントをインストルメントする
Amplitude AI SDK(Nodeは@amplitude/ai、Pythonはamplitude-ai)はLLMクライアントをラップして、各会話をエージェントセッションにグループ化するため、エージェント分析が必要とするすべての[Agent]イベントが送信されます。また、セッションを閉じ、プライバシーモードを適用し、モデル呼び出しのコストを計算します。
Node または Python コードベースを変更できる場合、AI SDKを使用してください。 ブラウザ、エッジランタイム、Java、Go、Rubyなどのランタイムで実行できない場合は、代わりにAI SDKなしでエージェントイベントを送信してください。 OpenTelemetry GenAIのスパンをすでにエクスポートしている場合は、OpenTelemetryトレースを送信します。
開始する前に、セッションIDとユーザーID、およびプライバシーモードを決定します。 SDK APIの詳細については、AI SDKリファレンスを参照してください。
AIコーディングエージェントを使用してインストルメントする(推奨)
このプロンプトを、Cursor、Claude Code、Windsurf、GitHub Copilot、CodexなどのAIコーディングエージェントに貼り付けます。エージェントはSDKをインストールし、バンドルされた命令ファイルを読み取り、コードベースをスキャンして、すべてのLLMコールサイトとセッションのライフサイクルを検出し、それらをインストルメントします。また、検証テストも記述します。
Instrument this app with Amplitude Agent Analytics using the Node SDK.
Fetch and follow https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/amplitude-ai.md
Then install the SDK as that guide says:
npm install @amplitude/ai @amplitude/analytics-node
提案された変更をレビューし、インストルメンテーションを確認します。
手動でインストルメントする
LLMクライアントをラップし、エージェントに名前を付け、セッション内の各会話を実行します。 このパターンにより、Agent Analyticsが予期するすべてのイベントタイプが生成されます。
import { AmplitudeAI, OpenAI } from "@amplitude/ai";
const ai = new AmplitudeAI({ apiKey: process.env.AMPLITUDE_AI_API_KEY });
const openai = new OpenAI({
amplitude: ai,
apiKey: process.env.OPENAI_API_KEY,
});
const agent = ai.agent("my-agent");
const session = agent.session({ userId, sessionId });
await session.run(async (s) => {
s.trackUserMessage(message);
return openai.chat.completions.create({ model, messages });
});
await ai.flush();
ラッピングされたプロバイダー(Nodeではnew OpenAI({ amplitude: ai })、Pythonではpatch(amplitude_ai=ai))は、完了レスポンスから、チャットテキストを含む[Agent] AI Responseをキャプチャします。ラップされたプロバイダーがない場合、Amplitudeはそのイベントやそのメッセージコンテンツを追跡しません。SDKがラップしていないプロバイダーを使用するか、ラップされていないクライアントを直接呼び出す場合は、完了が返された後にtrackAiMessage()(Nodeの場合)またはtrack_ai_message()(Pythonの場合)を呼び出します。すべてのトラッキング方法については、SDKリファレンスの手動インストルメンテーションを参照してください。
プライバシーモードを適用するには、AIConfigでcontentMode(Nodeの場合)またはcontent_mode(Pythonの場合)を設定します。SDKの設定を参照してください。
エージェントがA/Bテストまたは機能フラグの下で実行される場合は、フラグクライアントから返されるバリアントを、ai.agent()またはagent.session()のexperimentsとして渡します(例:experiments: [{ key: 'planner', variant }])。これにより、セッション内のすべてのイベントが[Agent] Experiment Variantを持つようになります。エージェント分析に実験バリアントを記録するを参照してください。
エージェントとセッションを長寿命サーバーに配置する
多数のターンとユーザーを処理するHTTPサーバーでは、3つの配置ルールに従うことでセッションが正しくグループ化されます。
モジュールスコープでエージェントを定義します。
リクエストハンドラ内でai.agent(...)を構築すると、ターンごとに新しい[Agent] Agent IDが生成され、セッションのグループ化が崩れます。モジュールの読み込み時にエージェントを一度作成し、その参照を再利用します。
// agent.ts (module scope)
export const agent = ai.agent("support-bot");
// handler.ts
export async function POST(req: Request) {
const { sessionId, userId, message } = await req.json();
return agent.session({ userId, sessionId }).run(async (s) => {
s.trackUserMessage(message);
// ...
});
}
安定したセッションIDを使用して、リクエストごとに1つのセッションを開きます。
各リクエストハンドラ内でagent.session({ sessionId })を呼び出し、同じジョブの全ターンを通じて同じsessionIdを使用します。ターンが結びつけられるのはIDを共有しているからであり、プロセスを共有しているからではありません。
各セッションIDを1つのユーザーに保ちます。
共有またはグローバルなセッションIDは、異なるユーザーの会話を統合し、ユーザーごとの分析を損ないます。セッションIDの選択を参照してください。
セッションを閉じてフラッシュする
run()(Node)または session()(Python)コンテキストマネージャーで開かれたセッションは、スコープが終了すると閉じられます。複数のリクエストにまたがるセッションの場合、ジョブが完了したら trackSessionEnd()(Node) または track_session_end()(Python) を呼び出します。 閉じる方法については、セッションの終了方法を参照してください。
SDKはイベントをメモリにバッチ処理し、一定の間隔で送信します。 短いセッション(1分未満)の場合、バッチ処理は透過的です。 数時間にわたるチケット対応、1日にわたるコーディングタスク、バックグラウンドジョブなど、長時間実行されるセッションの場合、終了イベントがバッファに留まることがあります。プロセスがイベントを送信する前に再起動した場合、そのセッションはアイドルタイムアウトによって終了するまで開いたままになります。
クローズ直後にai.flush()を呼び出して、プロセスが終了または再起動する前に確実に送信されるようにします。
agent.trackSessionEnd({ sessionId: ticketId });
await ai.flush();
Serverless ハンドラはsession.run()完了時に自動的にフラッシュされるため、明示的な呼び出しは不要です。長時間にわたり稼働するサーバーの場合は、SIGTERMハンドラ内でもai.flush()を呼び出します。これにより、プロセスが停止する前に、すべてのオープンセッションにまたがってバッファリングされたイベントが送信されます。
セッションをデフォルトの30分以上に長く開いたままにするには、セッションのタイムアウトの設定を参照してください。
これは役に立ちましたか?
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.