TracingAgent Frameworks

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.

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

Run npx @respan/cli setup to set up with your coding agent.

Setup

1

Install packages

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

Set environment variables

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

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.

4

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" }]
  }
}
5

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

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({...})
AttributeTypeDescription
customer_identifierstr | stringIdentifies the end user in Respan analytics.
thread_identifierstr | stringGroups related Cursor activity into a session.
trace_group_identifierstringGroups related TypeScript SDK spans into a named trace group.
metadatadict | objectCustom key-value pairs attached to spans.