Cursor SDK

​

Setup

pnpm add braintrust @cursor/sdk

npm install braintrust @cursor/sdk

BRAINTRUST_API_KEY=<your-braintrust-api-key>
CURSOR_API_KEY=<your-cursor-api-key>

​

Auto-instrumentation

import { initLogger } from "braintrust";
import { Agent } from "@cursor/sdk";

initLogger({
  projectName: "cursor-agent-example", // Replace with your project name
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const result = await Agent.prompt("Summarize the README in this repo.", {
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});

console.log(result);

node --import braintrust/hook.mjs trace-cursor-auto.js

​

Manual instrumentation

import { initLogger, wrapCursorSDK } from "braintrust";
import * as cursorSDK from "@cursor/sdk";

initLogger({
  projectName: "cursor-agent-example", // Replace with your project name
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const { Agent } = wrapCursorSDK(cursorSDK);

const result = await Agent.prompt("Summarize the README in this repo.", {
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});

console.log(result);

​

What Braintrust traces

• Agent run spans (Cursor Agent), with the user message as input and the agent’s final output as output.
• Tool call spans (tool: <name>), with the tool arguments as input and the tool result as output.
• Subagent spans (Agent: <description>) nested under a tool span when the agent delegates to a subagent or task.
• Token usage metrics (prompt, completion, total, plus cached and cache-creation tokens) from agent turns.
• Run metadata, including the model, agent ID, run ID, status, duration, runtime (local or cloud), and git branch information under cursor_sdk.* keys.
• Errors captured on the agent span.

​

Resources

• Cursor agent SDK on npm
• Cursor documentation