Instrument your agent with the AI SDK

The Amplitude AI SDK (@amplitude/ai for Node, amplitude-ai for Python) wraps your LLM client and groups each conversation into an agent session, so it emits every [Agent] event Agent Analytics expects. It also closes sessions, applies your privacy mode, and prices model calls for you.

Use the AI SDK when you can modify a Node or Python codebase. If your runtime can't run it, such as a browser, an edge runtime, Java, Go, or Ruby, send agent events without the AI SDK instead. If you already export OpenTelemetry GenAI spans, send OpenTelemetry traces.

Before you start, decide your session ID and user ID and your privacy mode. For the full SDK API, refer to the Agent Analytics SDK reference.

Instrument with your AI coding agent (recommended)

Paste this prompt into your AI coding agent, such as Cursor, Claude Code, Windsurf, GitHub Copilot, or Codex. The agent installs the SDK, reads the bundled instructions file, scans your codebase, finds every LLM call site and the session lifecycle, and instruments them. It also writes a verification test.

Instrument this app with Amplitude Agent Analytics using the Node SDK.

Install the SDK:

npm install @amplitude/ai @amplitude/analytics-node

Then follow `node_modules/@amplitude/ai/amplitude-ai.md`.

Review the changes it proposes, then verify your instrumentation.

Instrument by hand

Wrap your LLM client, name an agent, and run each conversation inside a session. That pattern produces every event type Agent Analytics expects.

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();

The wrapped provider (new OpenAI({ amplitude: ai }) in Node, patch(amplitude_ai=ai) in Python) captures [Agent] AI Response, including the chat text, from the completion response. Without a wrapped provider, Amplitude doesn't track that event or its message content. If you use a provider the SDK doesn't wrap, or call an unwrapped client directly, call trackAiMessage() (Node) or track_ai_message() (Python) after the completion returns. For every tracking method, refer to Manual instrumentation in the SDK reference.

To apply your privacy mode, set contentMode (Node) or content_mode (Python) on AIConfig. Refer to Configure the SDK.

Place agents and sessions on a long-lived server

On an HTTP server that handles many turns and users, three placement rules keep sessions grouped correctly.

Define agents at module scope

Constructing ai.agent(...) inside a request handler mints a fresh [Agent] Agent ID on every turn and breaks session grouping. Create the agent once at module load and reuse the reference.

// 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);
    // ...
  });
}

Open one session per request with a stable session ID

Call agent.session({ sessionId }) inside each request handler, with the same sessionId across every turn of the same job. Turns stitch together because they share the ID, not because they share the process.

Keep each session ID to one user

A shared or global session ID merges different users' conversations and breaks per-user analytics. Refer to Choose a session ID.

Close and flush sessions

A session opened with run() (Node) or the session() context manager (Python) closes when the scope exits. For sessions that span several requests, call trackSessionEnd() (Node) or track_session_end() (Python) when the job finishes. For how closing works, refer to How sessions close.

The SDK batches events in memory and ships them on an interval. For short sessions (under a minute), batching is transparent. For long-running sessions, such as tickets worked over hours, coding tasks that span a day, or background jobs, the close event can sit in the buffer. If the process restarts before it ships, the session stays open until the idle timeout closes it.

Call ai.flush() right after the close to make sure it lands before the process exits or restarts:

agent.trackSessionEnd({ sessionId: ticketId });
await ai.flush();

Serverless handlers flush automatically when session.run() completes, so you don't need an explicit call there. For long-running servers, also call ai.flush() in your SIGTERM handler so buffered events across every open session ship before the process stops.

To keep sessions open longer than the 30-minute default, refer to Configure session timeouts.