> ## 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](/docs/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, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

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](/docs/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>

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

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

  <Steps>
    <Step title="Install packages">
      ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      pip install braintrust cursor-sdk
      ```
    </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-python">
    Auto-instrumentation
  </h2>

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

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

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

  <h2 id="what-traced-python">
    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.
  * 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.
  </Note>

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

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