---
title: Import Cursor Agent SDK sessions into Agent Analytics
description: "Forward live Cursor Agent SDK sessions to Agent Analytics from a hook, on the same user as your product analytics. Cursor's built-in evals stay in Cursor."
product: general
lang: en
last_updated: 2026-10-26
token_estimate: 1199
---
# Import Cursor Agent SDK sessions into 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`.

The Cursor Agent SDK integration sends every live session of your agent to Agent Analytics: what the user asked, which tools ran, what the agent replied, and how many tokens it used. Each session lands on the same user ID as the rest of your product analytics, so you can see whether people got what they came for and whether it showed up in conversion and retention. A hook in your agent project posts each turn to the Amplitude HTTP API when it finishes. Amplitude then builds sessions, turns, and tool calls, and runs built-in signals after the session closes.

Cursor's evals and Agent Analytics answer different questions. Cursor's evals run your agent on fixed test cases before you ship. Agent Analytics shows what happened with real users after you ship. The hook skips eval and dry-run sessions, so neither appears in Agent Analytics.

## Set up 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 fetches the guide, adds the hook, and starts with a dry run.

```text
Forward live Cursor Agent SDK sessions to Amplitude Agent Analytics.

Fetch https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/cursor-agent-sdk.md
If @amplitude/ai is installed, the same file is under node_modules/@amplitude/ai/docs/integrations/.
Follow links in the guide. If your source isn't listed, start at https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/README.md
Follow "Part 2: Coding agent procedure". Start with a dry run.
```

The agent stops and asks for values it can't infer, such as which field holds your user ID and which model the agent runs. Review its changes, then verify with the steps in [Get started](#get-started).

## What this means for you

- **You add**: Two files to the Agent SDK project, a hook in `bot/hooks/` and a mapping file in `bot/lib/`. No change to your tools, prompts, or model calls.
- **You need**: Your Amplitude project API key, egress to `api2.amplitude.com` (or `api.eu.amplitude.com` for EU data residency), and the field on the session that holds your product-analytics user ID.
- **You don't need**: The Amplitude AI SDK. Cursor runs the model loop, so there's no client to wrap.

## What carries over

| Data | Carries over |
| --- | --- |
| Session grouping | Yes, one Agent SDK session becomes one session |
| User and agent messages | Yes, the full text of each, unless you send metadata only |
| Tool calls | Yes, with name, success, input, and output |
| Subagents | As tool calls inside the parent agent's turn, not as separate agents |
| Model | Yes, the `model` set in `bot/agent.ts` |
| Tokens | Yes, input and output |
| Cost | No. Cursor prices the whole session, not each turn |
| Failed turns | Yes, as an AI Response marked as an error. The hook skips turns the user cancels |
| Cursor eval runs and dry-run sessions | No |

## Freshness and limits

- **Latency**: Each turn posts when it finishes. Built-in signals run once, after the session has been idle for 30 minutes.
- **Restarts**: Hooks don't replay events. The hook doesn't send turns that finish while the agent process is down.
- **User ID**: There is no default. The hook skips sessions without your product-analytics user ID rather than storing them as `unknown`.
- **Privacy**: Amplitude doesn't scrub content after receipt. Send metadata only, or scrub in the hook before the post. Refer to [Agent Analytics privacy modes](https://amplitude.com/docs/amplitude-ai/agent-analytics/privacy-modes).
- **Resends**: Insert IDs are stable. Amplitude deduplicates resent events within 7 days.

## Get started

Follow the [Cursor Agent SDK integration guide](https://github.com/amplitude/Amplitude-AI-Node/blob/main/docs/integrations/cursor-agent-sdk.md). Start with a dry run, which prints the events without sending them. Then send one real session with a tool call and confirm in Live Events:

1. Session ID is the Agent SDK session ID.
2. User ID is the product-analytics user, not `unknown`.
3. Agent ID is your agent's name.
4. The turn shows the user message, the tool call, and the reply text, with the model name and both token counts.
5. An eval run from the same agent doesn't appear.

After the session has been idle for 30 minutes, open it in the session viewer to see the built-in signals.

Guide last verified on October 26, 2026, against `@grok/agent-sdk` 0.3.0. Cursor and the Agent SDK are trademarks of their owner. Amplitude isn't affiliated with or endorsed by Cursor.