---
title: Agent Analytics quickstart
description: "Get agent events flowing into Amplitude in minutes: install the SDK, run the setup agent or a one-line patch, and watch your first sessions arrive, even with anonymous IDs."
product: general
token_estimate: 1742
---
# Agent Analytics quickstart

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Choose your SDK and setup path, then get your agent's traffic flowing into Amplitude in about five minutes. You need a project with Agent Analytics enabled and its API key. Anonymous user and session IDs are fine.

This page contains the fast installation path with limited customizations. To instrument production with full identity and privacy controls, go to [Set up Agent Analytics](https://amplitude.com/docs/amplitude-ai/agent-analytics/setup) and the [SDK reference](https://amplitude.com/docs/sdks/agent-analytics/sdk) instead.

## Set up Agent Analytics

The interactive page shows the Node agent prompt first. Choose Node or Python in the prompt header, or expand the manual setup below. The page detects Windows and updates commands automatically.

### Node agent prompt

```text
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`.
```

### Python agent prompt

```text
Instrument this app with Amplitude Agent Analytics using the Python SDK.

Install the SDK:

python3 -m pip install amplitude-ai

Then run `amplitude-ai --print-guide` and follow the printed instrumentation guide.
```

### Manual setup for Node

1. **Install the SDK**: Add the Agent Analytics and Amplitude Node packages to your project.

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

2. **Set the project API key**: Set the key for the current terminal session. Use your Agent Analytics project API key.

   ```
   export AMPLITUDE_AI_API_KEY="YOUR_API_KEY"
   ```

3. **Instrument an agent session**: Initialize the SDK once, name your agent, and wrap each user task in a session. Replace the sample IDs and messages with values from your app.

   ```
   import { AmplitudeAI } from "@amplitude/ai";
   
   const ai = new AmplitudeAI({
     apiKey: process.env.AMPLITUDE_AI_API_KEY!,
   });
   
   const agent = ai.agent("my-agent");
   const session = agent.session({ userId: "user-1", sessionId: "session-1" });
   
   await session.run(async (s) => {
     s.trackUserMessage("What is my balance?");
     s.trackAiMessage("Your balance is $1,234.", "gpt-4o", "openai", 120);
   });
   
   await ai.flush();
   ```

4. **Verify the integration**: Run the doctor after your tests pass, then send one conversation through your agent.

   ```
   npx amplitude-ai doctor
   ```

### Manual setup for Python

1. **Install the SDK**: Add the Agent Analytics Python package to your environment.

   ```
   python3 -m pip install amplitude-ai
   ```

2. **Set the project API key**: Set the key for the current terminal session. Use your Agent Analytics project API key.

   ```
   export AMPLITUDE_AI_API_KEY="YOUR_API_KEY"
   ```

3. **Instrument an agent session**: Initialize the SDK once, name your agent, and wrap each user task in a session. Replace the sample IDs and messages with values from your app.

   ```
   import os
   from amplitude_ai import AmplitudeAI
   
   ai = AmplitudeAI(api_key=os.environ["AMPLITUDE_AI_API_KEY"])
   agent = ai.agent("my-agent")
   
   with agent.session(user_id="user-1", session_id="session-1") as session:
       session.track_user_message("What is my balance?")
       session.track_ai_message(
           "Your balance is $1,234.", "gpt-4o", "openai", 120
       )
   
   ai.flush()
   ```

4. **Verify the integration**: Run the doctor after your tests pass, then send one conversation through your agent.

   ```
   amplitude-ai doctor
   ```

### Windows command differences

- Set the API key in PowerShell with `$env:AMPLITUDE_AI_API_KEY="YOUR_API_KEY"`.
- Install the Python SDK with `py -m pip install amplitude-ai`.

If your runtime doesn't fit the Node or Python SDK (edge workers, browser SPAs, or languages like Java, Go, or Ruby), skip the block above. Go to [Send agent events without the AI SDK](https://amplitude.com/docs/amplitude-ai/agent-analytics/setup#send-agent-events-without-the-ai-sdk) for the HTTP path, or [Send OpenTelemetry traces directly](https://amplitude.com/docs/amplitude-ai/agent-analytics/setup#send-opentelemetry-traces-directly) if you already emit OpenTelemetry GenAI spans.

Watch the following implementation video for a demonstration of how you can set up Amplitude Agent Analytics.

**Video (2:35):** How Agent Analytics setup works — wistia id `j4frodo3ld` — [poster](https://amplitude.com/docs/images/amplitude-ai/agent-analytics/setup-video-poster.jpg)

## The ID ladder

Each ID you add unlocks more of the product. Nothing below requires re-instrumenting what you already did.

| Add | What it unlocks |
| --- | --- |
| Nothing (patch only) | Basic LLM traces and aggregate call counts |
| User ID | Per-user analytics, cohorts, retention |
| Agent session ID | Multi-turn analysis, session enrichment, quality scores |
| Agent ID | Per-agent cost, latency, and quality dashboards |
| Browser session ID | Link agent activity to your product's web and app analytics sessions |
| Session Replay ID | Watch the matching session in Session Replay |

Avoid using placeholder IDs unless you're using test data. [Read here for more details on how identity resolution is handled in Amplitude](https://amplitude.com/docs/data/sources/instrument-track-unique-users#how-amplitude-identifies-unique-users)

## Validate the full setup

1. Run your app and send a message through the agent.
2. In Amplitude, open your project's Live Events view. Within about a minute you should see `[Agent] User Message`, `[Agent] AI Response`, and, when the session completes, `[Agent] Session End`.
3. Open an `[Agent] AI Response` event and confirm the key fields are populated: Model Name, Provider, Input and Output Tokens, Cost USD, Latency Ms, Session ID, and Agent ID.

To verify locally before checking Amplitude, construct the client with `debug: true`. In this mode, every tracked event prints to stderr with its model, tokens, cost, and latency.

**Expected gaps by rung:** Verification checks all eight core fields, but what you should expect depends on where you are on the ladder. If you haven't passed real IDs yet, Agent session ID will show an auto-generated value and enrichment results will be less meaningful; that is expected, not a failure. Full instrumentation makes all eight gates meaningful.

## What happens next

About 30 minutes after your session goes quiet (or immediately, if you close it explicitly), Amplitude's enrichment pipeline evaluates it and emits an `[Agent] Session Record` with quality signals. Head to Agent Analytics in the left nav to see your sessions, then continue to [setup](https://amplitude.com/docs/amplitude-ai/agent-analytics/setup) to choose a privacy mode and plan production instrumentation.