> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/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

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

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.

<View title="TypeScript" icon="https://img.logo.dev/typescriptlang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="setup-typescript">
    Setup
  </h2>

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

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```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
        ```
      </CodeGroup>
    </Step>

    <Step title="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>
      ```
    </Step>
  </Steps>

  <h2 id="auto-instrumentation-typescript">
    Auto-instrumentation
  </h2>

  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.

  <Steps>
    <Step title="Initialize Braintrust and run an agent">
      <CodeGroup>
        ```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);
        ```
      </CodeGroup>
    </Step>

    <Step title="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, then run the compiled file with the import hook.

      <Note>
        If you're using a bundler, see [Trace LLM calls](/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup.
      </Note>
    </Step>
  </Steps>

  <h2 id="manual-instrumentation-typescript">
    Manual instrumentation
  </h2>

  To trace the Cursor SDK manually, wrap the imported module yourself with `wrapCursorSDK()`.

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

  <h2 id="what-traced-typescript">
    What Braintrust traces
  </h2>

  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.

  <h2 id="resources-typescript">
    Resources
  </h2>

  * [Cursor agent SDK on npm](https://www.npmjs.com/package/@cursor/sdk)
  * [Cursor documentation](https://docs.cursor.com/)
</View>