Cursor SDK (tracing)

Respan supports Cursor tracing in Python through Cursor hook payloads and in TypeScript through the Cursor SDK (@cursor/sdk). Use the Python setup for Cursor hook events, or the TypeScript setup for programmatic Cursor SDK agent runs.

Set up Respan

Create an account at platform.respan.ai and grab an API key .

Paste this into your coding agent:


Help me set up Respan tracing with the Cursor SDK integration.
Follow https://www.respan.ai/docs/integrations/cursor-sdk.md

Setup

Install packages


pip install respan-ai respan-instrumentation-cursor-sdk

Set environment variables


export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export RESPAN_BASE_URL="https://api.respan.ai/api"

Initialize and run


from respan import Respan
from respan_instrumentation_cursor_sdk import CursorSDKInstrumentor

respan = Respan(instrumentations=[CursorSDKInstrumentor()])
processor = CursorSDKInstrumentor.create_processor()

processor.process_event(
    {
        "hook_event_name": "afterAgentThought",
        "conversation_id": "conv_123",
        "generation_id": "gen_456",
        "text": "Inspecting repository files to find the right implementation.",
        "duration_ms": 320,
    }
)

respan.shutdown()

For TypeScript, pass sdkModule when your app imports @cursor/sdk directly. This ensures the instrumentor patches the same Cursor SDK module instance your application uses.

Configure Cursor hooks for Python

Use respan-cursor-hook as your Cursor hook command when using the Python hook integration.


{
  "version": 1,
  "hooks": {
    "beforeSubmitPrompt": [{ "command": "respan-cursor-hook" }],
    "afterAgentThought": [{ "command": "respan-cursor-hook" }],
    "afterShellExecution": [{ "command": "respan-cursor-hook" }],
    "afterFileEdit": [{ "command": "respan-cursor-hook" }],
    "afterMCPExecution": [{ "command": "respan-cursor-hook" }],
    "afterAgentResponse": [{ "command": "respan-cursor-hook" }],
    "stop": [{ "command": "respan-cursor-hook" }]
  }
}

Trace streamed runs in TypeScript


const agent = await cursorSdkModule.Agent.create({
  name: "cursor_stream_agent",
  model: { id: "cursor-small" },
});

const run = await agent.send("Use the docs MCP server and explain Cursor SDK streaming.", {
  mcpServers: {
    docs: {
      type: "stdio",
      command: "node",
      args: ["docs-server.js"],
    },
  },
});

for await (const event of run.stream()) {
  console.log(event.type);
}

const finalResult = await run.wait();
console.log(finalResult.result);

View your trace

Open the Traces page to inspect Cursor hook spans or Cursor TypeScript SDK agent spans, generation spans, tool spans, streamed events, and local custom tool activity.

Captured data


- Cursor hook payloads
- Conversation and generation identifiers
- Agent thoughts
- Shell execution events
- File edit events
- MCP execution events
- Agent responses
- Stop events

Local custom tools

Cursor TypeScript SDK runs can define local custom tools. The instrumentor captures the tool definition and the tool call result.


const agent = await cursorSdkModule.Agent.create({
  name: "cursor_custom_tools_agent",
  model: { id: "cursor-small" },
});

const run = await agent.send("Look up Tokyo weather with a local custom tool.", {
  local: {
    customTools: {
      lookup_weather: {
        description: "Return deterministic weather for a city.",
        inputSchema: {
          type: "object",
          properties: { city: { type: "string" } },
          required: ["city"],
        },
        execute: async ({ city }: { city: string }) => ({
          city,
          condition: "clear",
          temperatureC: 21,
        }),
      },
    },
  },
});

await run.wait();

Attributes

Use Respan attributes to group Cursor runs by user, thread, or workflow.


from respan import Respan, propagate_attributes
from respan_instrumentation_cursor_sdk import CursorSDKInstrumentor

respan = Respan(instrumentations=[CursorSDKInstrumentor()])

with propagate_attributes(
    customer_identifier="user_123",
    thread_identifier="cursor-session-abc",
    metadata={"environment": "production"},
):
    processor = CursorSDKInstrumentor.create_processor()
    processor.process_event({...})

Attribute	Type	Description
`customer_identifier`	`str \| string`	Identifies the end user in Respan analytics.
`thread_identifier`	`str \| string`	Groups related Cursor activity into a session.
`trace_group_identifier`	`string`	Groups related TypeScript SDK spans into a named trace group.
`metadata`	`dict \| object`	Custom key-value pairs attached to spans.