For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.
Import Cursor Agent SDK sessions into Agent Analytics
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.
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.
What this means for you
- You add: Two files to the Agent SDK project, a hook in
bot/hooks/and a mapping file inbot/lib/. No change to your tools, prompts, or model calls. - You need: Your Amplitude project API key, egress to
api2.amplitude.com(orapi.eu.amplitude.comfor 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.
- Resends: Insert IDs are stable. Amplitude deduplicates resent events within 7 days.
Get started
Follow the Cursor Agent SDK integration guide. 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:
- Session ID is the Agent SDK session ID.
- User ID is the product-analytics user, not
unknown. - Agent ID is your agent's name.
- The turn shows the user message, the tool call, and the reply text, with the model name and both token counts.
- 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.
Was this helpful?