Set up Agent Analytics

Early Access

This feature is in Early Access. During this time, aspects of the functionality may still be developed, and this documentation may not always be up to date. If you have any questions, contact Amplitude Support.

This page describes how to customize your Agent Analytics set up. To complete the in-depth set up, you'll need to modify your environment with the Agent Analytics SDK. The Agent Analytics SDK is the full developer reference, covering install, initialization, instrumenting sessions and tools, provider notes, edge runtimes, OTel ingestion, cost handling, and the full API.If you want to quickly get started with basic Agent Analytics, go to the Agent Analytics Quickstart Guide. The quickstart guide does not allow for any customizations. You can always complete the quickstart guide to get insights as fast as possible and then come back to this set up guide to customize your Agent Analytics insights.

The timeline below shows what your instrumentation produces. Click any event to inspect its shape.

Event type

[Agent] AI Responsefrom the SDK

Fired at

22:33:48

Identity

[Agent] Session ID	4ddcc6b2-1041-432a-aa8c-ebe3eccac40b
[Agent] Agent ID	support-chatbot
[Agent] Trace ID	b4f63d43-d752-4b1f-8489-d234ddf586b2

Event-specific

$llm_message.text	I can help. Your subscription renews on Aug 15…
[Agent] Model	gpt-4o-mini
[Agent] Provider	openai
[Agent] Input Tokens	1245
[Agent] Output Tokens	87
[Agent] Latency Ms	3420
[Agent] Cost USD	0.0012

Closes the turn. Carries the eight fields the SDK doctor checks at setup: Session ID, Agent ID, Model, Provider, Latency Ms, Input/Output Tokens, Cost USD. Emitted by s.trackAiMessage(...) or a provider wrapper.

How setup works

You must have previously completed the following prerequisites before data shows up in Amplitude:

Your project has Agent Analytics enabled. If it isn't, contact your CSM.
You've instrumented your code. The Amplitude AI SDK (Node and Python) covers most stacks. Runtimes the SDK doesn't bundle into can send events directly to the HTTP API. These runtimes include Cloudflare Workers, other edges, and unsupported languages such as Java, Go, and Ruby.
You've decided what leaves your app. Privacy mode controls whether prompt and response text reaches Amplitude.

Connect with the SDK

Use this sequence when you connect Agent Analytics from the product UI or from your IDE. Both SDKs emit the same [Agent] event schema.

Install the SDK

Pick your stack:

bash

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

bash

pip install amplitude-ai

Let a coding agent instrument your app (recommended)

Run the CLI in your project root. It prints a prompt for your coding agent, scans your repo for agents and LLM call sites, and proposes instrumentation you can review before merging.

bash

npx amplitude-ai

Or wire it up by hand

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

typescript

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

Send a message and verify

Run one conversation through your agent, then open the Sessions tab in Agent Analytics. Your first session appears within a few minutes. For field-level checks, use Verify your data in the SDK reference.

Choose an instrumentation path

Path	Use when	Where to go
Amplitude AI SDK (Node or Python)	Most stacks	SDK reference
HTTP API	Runtimes the SDK doesn't support (Java, Go, Ruby, Cloudflare Workers)	Instrument without the SDK
OpenTelemetry	Stacks already emitting OTel spans, or you want span-first observability	Ingest OpenTelemetry spans — call `enable_otel()` / `enableOtel()` for the recommended span-first approach

Choose a privacy mode

Mode	What leaves your app	Use when
`full` (default)	Prompt and response text, with PII redaction on by default	Most products
`metadata_only`	Tokens, latency, model, and cost (no text)	Sensitive or regulated data
`customer_enriched`	Pre-scored summaries you send through `trackSessionEnrichment()`	You already have an evaluation stack

Refer to Choose a privacy mode for the configuration details and PII-redaction tunables.

Verify your data

After events start arriving, your project's Live Events stream shows [Agent] AI Response events with Session ID, Agent ID, Model, Provider, Latency Ms, Input/Output Tokens, and Cost USD populated. If any of those fields are missing, walk through Verify your data in the SDK reference.

Local verification: Before deploying, run MockAmplitudeAI.summary() to get a fill-rate report of all captured events. It checks the eight verification gates (identity, session, model, provider, latency, input tokens, output tokens, cost) and flags gaps before data reaches Amplitude.

After you confirm the data is flowing, go to Analyze agent results for what Amplitude infers on top: turn-level signals, session rollups, and the evaluator results that drive the dashboards.

Was this helpful?