# Set up Agent Analytics

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

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](https://amplitude.com/docs/sdks/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](https://amplitude.com/docs/amplitude-ai/agent-analytics/quickstart). 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.

## How setup works

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

1. **Your project has Agent Analytics enabled.** If it isn't, contact your CSM.
2. **You've instrumented your code.** The [Amplitude AI SDK (Node and Python)](https://amplitude.com/docs/sdks/agent-analytics/sdk) 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.
3. **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](https://amplitude.com/docs/sdks/agent-analytics/sdk#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](https://amplitude.com/docs/sdks/agent-analytics/sdk) |
| **HTTP API** | Runtimes the SDK doesn't support (Java, Go, Ruby, Cloudflare Workers) | [Instrument without the SDK](https://amplitude.com/docs/sdks/agent-analytics/sdk#instrument-without-the-sdk) |
| **OpenTelemetry** | Stacks already emitting OTel spans, or you want span-first observability | [Ingest OpenTelemetry spans](https://amplitude.com/docs/sdks/agent-analytics/sdk#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](https://amplitude.com/docs/sdks/agent-analytics/sdk#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](https://amplitude.com/docs/sdks/agent-analytics/sdk#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](https://amplitude.com/docs/amplitude-ai/agent-analytics/results) for what Amplitude infers on top: turn-level signals, session rollups, and the evaluator results that drive the dashboards.