> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor SDK

> Trace Cursor agent SDK runs in Braintrust to debug tool calls, subagents, and multi-step reasoning

The [Cursor agent SDK](https://www.npmjs.com/package/@cursor/sdk) (`@cursor/sdk`) is a TypeScript SDK for building agents with Cursor. Braintrust traces agent runs, tool calls, and the subagent tasks an agent spawns.

**TypeScript**

## Setup

Install Braintrust alongside the Cursor SDK, then set your API keys. Requires `@cursor/sdk` v1.0.7 or later.

**1. Install packages**

```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
```

**2. Set environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=<your-braintrust-api-key>
CURSOR_API_KEY=<your-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.

**1. Initialize Braintrust and run an agent**

```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);
```

**2. Run with the import hook**

```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 and run the compiled file with the import hook, or [run TypeScript directly](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) with a TypeScript loader.

> [!NOTE]
>
> If you're using a bundler, see [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md#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: <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](https://www.npmjs.com/package/@cursor/sdk)
* [Cursor documentation](https://docs.cursor.com/)

**Python**

## Setup

Install Braintrust alongside the Cursor SDK, then set your API keys. Requires `cursor-sdk>=1.0.25`.

**1. Install packages**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install braintrust cursor-sdk
```

**2. Set environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=<your-braintrust-api-key>
CURSOR_API_KEY=<your-cursor-api-key>
```

## Auto-instrumentation

To trace Cursor agent runs without modifying your application code, call `braintrust.auto_instrument()` before importing the Cursor SDK.

```python title="trace_cursor_auto.py" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import os
import braintrust

braintrust.auto_instrument()
braintrust.init_logger(
    project="cursor-agent-example",  # Replace with your project name
    api_key=os.environ["BRAINTRUST_API_KEY"],
)

from cursor_sdk import Agent, LocalAgentOptions

with Agent.create(
    model="composer-2.5",
    local=LocalAgentOptions(cwd=os.getcwd()),
) as agent:
    result = agent.send("Summarize what this repository does").wait()
    print(result.result)
```

To disable Cursor SDK instrumentation when calling `auto_instrument()`, pass `cursor_sdk=False`:

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
braintrust.auto_instrument(cursor_sdk=False)
```

## Manual instrumentation

To register the Cursor SDK integration without `auto_instrument()`, call `setup_cursor_sdk()` before importing the Cursor SDK.

```python title="trace_cursor_manual.py" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import os
from braintrust.integrations.cursor_sdk import setup_cursor_sdk

setup_cursor_sdk(
    project="cursor-agent-example",  # Replace with your project name
    api_key=os.environ["BRAINTRUST_API_KEY"],
)

from cursor_sdk import Agent, LocalAgentOptions

with Agent.create(
    model="composer-2.5",
    local=LocalAgentOptions(cwd=os.getcwd()),
) as agent:
    result = agent.send("Summarize what this repository does").wait()
    print(result.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.
* LLM turn spans (`Cursor Model Turn`) for each model call within the run, with the conversation history as input, the model response as output, token metrics, and time to first token.
* Tool spans (named by tool name), with tool arguments as input and the tool result as output.
* Aggregate token usage metrics (prompt, completion, total, plus cached and cache-creation tokens) on the root agent span.
* Errors captured on the agent span.

> [!NOTE]
>
> Cursor executes model calls inside its own bridge subprocess, so `Cursor Model Turn` spans are reconstructed from the run's streamed events rather than from a provider client. Provider-level spans do not appear for Cursor's internal model requests even when OpenAI or Anthropic auto-instrumentation is also active. Use the `Cursor Model Turn` spans for per-turn LLM visibility.

## Resources

* [Cursor SDK on PyPI](https://pypi.org/project/cursor-sdk/)
* [Cursor documentation](https://docs.cursor.com/)
* [Braintrust Python SDK reference](https://docs.braintrust.dev/sdks/python/versions/latest.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.