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

## Watch the events arrive

After the setup panel's doctor command passes, open your project's Live Events stream. `[Agent] AI Response` events appear with model, provider, latency, token, and cost fields populated. For the full verification checklist, go to [Verify your data](https://amplitude.com/docs/amplitude-ai/agent-analytics/setup#verify-your-data).

## Add IDs when you're ready

It's a ladder you climb over time, not a form you fill out on day one.

| Add | What it unlocks |
| --- | --- |
| Nothing (provider wrappers only) | Basic LLM traces and aggregate call counts |
| User ID | Per-user analytics, cohorts, retention |
| Session ID | Multi-turn analysis, session enrichment, quality scores |
| Agent ID | Per-agent cost, latency, and quality dashboards |

Placeholder IDs work: events still flow, sessions still enrich, and you can swap in real identity later without re-instrumenting. For the complete breakdown, go to [What you set and what you get](https://amplitude.com/docs/sdks/agent-analytics/sdk#what-you-set-and-what-you-get) in the SDK reference.