Cursor Introduces a TypeScript SDK for Building Programmatic Coding Agents With Sandboxed Cloud VMs, Subagents, Hooks, and Token-Based Pricing

Source: Dev.to

Overview

Cursor, the AI‑powered code editor, is opening up the core technology behind its coding agents to developers everywhere. The Cursor team announced the public beta of the Cursor SDK — a TypeScript library that gives engineers programmatic access to the same runtime, harness, and models that power Cursor’s desktop app, CLI, and web interface.

This marks a shift in how AI coding tools are positioned: not just as interactive assistants sitting alongside a developer, but as deployable infrastructure that organizations can wire into their existing systems.

If you’ve used Cursor before, you know it as an IDE where you interact with an agent in real time — asking it to write functions, fix bugs, or explain code. The Cursor SDK changes the access model. Instead of a developer sitting at a keyboard, the agent can now be invoked programmatically: from a CI/CD pipeline trigger, a backend service, or embedded directly inside another product.

Key idea: Previously you had to be “in” Cursor to use its agents. Now you can call those same agents from anywhere in your stack with a few lines of TypeScript.

Getting Started

Installation is a single command:

npm install @cursor/sdk

Create an Agent instance, send it a task, and stream the response back — all in TypeScript:

import { Agent } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});

const run = await agent.send("Summarize what this repository does");

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

The Agent.create() call accepts:

• apiKey – your Cursor API key.
• model – the model identifier to run (e.g., "composer-2").
• local or cloud configuration – determines where execution happens.

Problem It Solves

Building fast, reliable, and capable coding agents that run safely against your data requires substantial engineering effort:

• Secure sandboxing
• Durable state and session management
• Environment setup
• Context management

When a new model ships, teams often have to rework their agent loops just to take advantage of it. The Cursor SDK eliminates this complexity, letting teams focus on building useful agents instead of maintaining underlying infrastructure.

Harness Features

SDK agents use the same harness that powers Cursor’s own products. “Harness” refers to the full set of supporting infrastructure that makes an agent effective beyond the raw LLM call. Key components include:

Codebase Indexing & Retrieval

• Semantic search, instant grep, and indexing so agents retrieve the right code context before generating responses.
• Reduces hallucinations and irrelevant outputs by providing accurate retrieval.

External Tool Integration

• Agents can connect to external tools and data sources over stdio or HTTP.
• Configuration can be supplied via a .cursor/mcp.json file or inline in the API call.
• MCP (Model Context Protocol) is an open standard for wiring tools into agent runtimes.

Reusable Behaviors

• Agents automatically pick up behavior definitions from a .cursor/skills/ directory in the repository.

Hooks & Extensibility

• A .cursor/hooks.json file lets you observe, control, and extend the agent loop across cloud, self‑hosted, and local runtimes.
• Useful for logging, guardrails, or custom orchestration.

Subagents, Tools, and Multi‑Agent Workflows

• The main agent can delegate subtasks to named subagents with their own prompts and models via the Agent tool.
• Enables multi‑agent workflows without writing custom orchestration code.
• Subagents inherit the same harness capabilities, allowing seamless coordination.

Pricing Model (Token‑Based)

The SDK follows a token‑based pricing structure, aligning costs with actual usage of the underlying LLMs. Developers are billed for the number of tokens processed during agent interactions, whether running locally or in the cloud.

Conclusion

The Cursor SDK turns the powerful coding‑assistant capabilities of Cursor into a programmable service that can be embedded anywhere—from CI pipelines to custom developer tools. By abstracting away sandboxing, state management, and context handling, it lets teams concentrate on the logic that adds real value to their products.