Cursor Agent SDK (Beta)

The @raindrop-ai/cursor-agent-sdk package automatically instruments the Cursor Agent SDK to capture events and traces from agent runs. It wraps the SDK’s Agent.prompt, Agent.create, Agent.resume, and SDKAgent.send APIs while preserving Cursor’s return values, streams, and errors. Features:

No OpenTelemetry setup required
Automatic event and trace capture for agent runs
Thinking and tool-call child spans
Token usage, model, output, status, and error capture
Support for Run.stream(), Run.wait(), and Run.conversation()
Per-context identity and routing metadata

Installation

npm install @raindrop-ai/cursor-agent-sdk @cursor/sdk

yarn add @raindrop-ai/cursor-agent-sdk @cursor/sdk

pnpm add @raindrop-ai/cursor-agent-sdk @cursor/sdk

bun add @raindrop-ai/cursor-agent-sdk @cursor/sdk

Quick Start

import * as cursor from "@cursor/sdk";
import { createRaindropCursorAgentSDK, eventMetadata } from "@raindrop-ai/cursor-agent-sdk";

const raindrop = createRaindropCursorAgentSDK({
  writeKey: process.env.RAINDROP_WRITE_KEY,
});

const wrapped = raindrop.wrap(cursor, {
  context: eventMetadata({
    userId: "user-123",
    eventName: "cursor_agent_run",
    convoId: "conversation-1",
  }),
});

const agent = await wrapped.Agent.create({
  model: { id: "composer-1" },
});
const run = await agent.send("Summarize the repository");

for await (const message of run.stream()) {
  console.log(message);
}

await raindrop.flush();

The wrapper also supports direct prompts:

const result = await wrapped.Agent.prompt("Summarize the repository");
console.log(result);

Agent.create() and Agent.resume() return wrapped agents whose send() method returns a wrapped run. Consume that run with stream(), wait(), or conversation(). Each run is finalized once, regardless of which lifecycle method is used.

Configuration

const raindrop = createRaindropCursorAgentSDK({
  writeKey: process.env.RAINDROP_WRITE_KEY, // Optional; disables shipping when absent
  endpoint: "https://api.raindrop.ai/v1", // Optional
  projectId: "support-prod", // Optional project slug
  localWorkshopUrl: false, // Optional local workshop mode
  events: {
    enabled: true,
  },
  traces: {
    enabled: true,
  },
  context: {
    userId: "user-123",
    eventName: "cursor_agent_run",
  },
});

When writeKey is absent, the wrapper remains usable and does not send telemetry.

Per-Run Context

Cursor’s method signatures do not provide a trailing metadata argument. Supply identity and routing metadata through the wrapper context instead:

const wrapped = raindrop.wrap(cursor, {
  context: eventMetadata({
    userId: "user-456",
    convoId: "conversation-2",
    eventName: "support_agent_run",
    eventId: "event-123",
    properties: { plan: "pro" },
  }),
});

Create separate wrapped contexts when concurrent runs need different metadata.

Events and Traces

Events are enabled by default in the wrapper configuration, and traces include the run span plus thinking and tool-call child spans. The client also exposes the event lifecycle methods for partial events:

const eventId = "event-123";

await raindrop.events.patch(eventId, {
  properties: { source: "cursor" },
});
await raindrop.events.setProperties(eventId, {
  environment: "production",
});
await raindrop.events.addAttachments(eventId, [
  { type: "text/plain", role: "context", value: "run context" },
]);
await raindrop.events.finish(eventId);

Use flush() to drain queued event and trace delivery, and shutdown() to close the client when the process exits.

Identifying Users

await raindrop.users.identify({
  userId: "user-123",
  traits: {
    plan: "pro",
    email: "user@example.com",
  },
});

Signals

await raindrop.signals.track({
  name: "agent_feedback",
  type: "feedback",
  sentiment: "POSITIVE",
  rating: 5,
});

Tool catalog capture (`ai.prompt.tools`)

Override only. The Cursor SDK streams messages, never the request it sends to the model, so this integration cannot observe the tool catalog and records nothing by default. tools on createRaindropCursorAgentSDK(...) is the default for every wrap() call and wrap(..., { tools }) replaces it entirely; the override is recorded verbatim on the cursor.agent.run span (the span carrying the prompt and ai.model.id), never on tool_call / thinking spans. tools: [] records an explicitly empty catalog. See Tool catalog capture for the attribute format, the absent / [] semantics and the override shapes accepted.

Flush and Shutdown

Call flush() before a short-lived process exits. Call shutdown() when the client will no longer be used:

await raindrop.flush();
await raindrop.shutdown();

Limitations

Concurrent runs should use separate wrapped contexts when each run needs distinct identity metadata.
The Cursor SDK requires Node.js >=22.13.
Cloud responses may omit usage, model, or message content; those fields are omitted gracefully.

Application Git identity

Set appGit on createRaindropCursorAgentSDK to provide commitSha, commitDirty, and optional branch, or pass false to opt out. Cursor may operate against a remote workspace, so local discovery requires a sourceDirectory that explicitly identifies the AUT and never defaults to the observer or edited checkout. See the TypeScript Git reference.

Getting Started

SDK

Integrations

Platform

Organization

Cookbooks

Workshop

Query API

MCP

Security

Support

Cursor Agent SDK (Beta)

Installation

Quick Start

Configuration

Per-Run Context

Events and Traces

Identifying Users

Signals

Tool catalog capture (`ai.prompt.tools`)

Flush and Shutdown

Limitations

Application Git identity

​Installation

​Quick Start

​Configuration

​Per-Run Context

​Events and Traces

​Identifying Users

​Signals

​Tool catalog capture (ai.prompt.tools)

​Flush and Shutdown

​Limitations

​Application Git identity

Installation

Quick Start

Configuration

Per-Run Context

Events and Traces

Identifying Users

Signals

Tool catalog capture (`ai.prompt.tools`)

Flush and Shutdown

Limitations

Application Git identity