Setup Install Braintrust alongside the Cursor SDK, then set your API keys. Requires `@cursor/sdk` v1.0.7 or later. ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} pnpm add braintrust @cursor/sdk ``` ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} npm install braintrust @cursor/sdk ``` ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} BRAINTRUST_API_KEY= CURSOR_API_KEY= ``` Auto-instrumentation To trace Cursor agent runs without modifying your application code, initialize Braintrust normally, then run your app with Braintrust’s import hook to patch the Cursor SDK at runtime. ```javascript title="trace-cursor-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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); ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} node --import braintrust/hook.mjs trace-cursor-auto.js ``` The auto-instrumentation example uses plain JavaScript so `node --import` can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook. If you’re using a bundler, see [Trace LLM calls](/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup. Manual instrumentation To trace the Cursor SDK manually, wrap the imported module yourself with `wrapCursorSDK()`. ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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 Braintrust patches the Cursor SDK and captures: * Agent run spans (`Cursor Agent`), with the user message as input and the agent’s final output as output. * Tool call spans (`tool: `), with the tool arguments as input and the tool result as output. * Subagent spans (`Agent: `) 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](https://www.npmjs.com/package/@cursor/sdk) * [Cursor documentation](https://docs.cursor.com/)