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.

This page covers agents you build on the Cursor Agent SDK. To send the sessions of the agent in the Cursor editor or CLI that your engineers use, refer to Cursor.

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.

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
Session trigger	When the mapping sets `trigger`. Refer to the note after this table
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

To record how each session started, set trigger in the mapping to interactive, headless, ci, scheduled, or event, for example scheduled for a schedule or event for a Slack or GitHub event. Every event of the session then carries it as [Agent] Session Trigger. Other values are ignored. The mapping file doesn't read environment variables, so your hook passes the value. Without trigger, the property is left out.

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.

これは役に立ちましたか？