How to Build Programmatic Agents With the Cursor SDK

The official release of the Cursor SDK allows you to transition AI coding assistants from interactive desktop utilities into programmatic infrastructure. Released in April 2026 alongside the Cloud Agents API (v1), the TypeScript-based SDK provides direct API access to the exact harness and runtime that powers the Cursor editor, CLI, and web application.

You can now deploy agents that automatically summarize pull requests, identify root causes of pipeline failures, or execute complex performance refactors across large repositories. The standard @cursor/sdk package gives your automation pipelines native access to intelligent context management, codebase indexing, and frontier models.

The Cursor Harness

Unlike generic agent frameworks, the Cursor SDK is built specifically for software engineering tasks. Agents instantiated via the SDK automatically inherit the Cursor Harness.

This harness provides built-in semantic search and intelligent codebase indexing. Instead of manually chunking repository files and managing context windows, the SDK handles token limits and code retrieval dynamically based on the current agent prompt.

The framework also includes native support for subagents. You can parallelize complex architectural tasks by spawning multiple asynchronous subagents that report back to a primary coordinator agent.

All frontier models available in the desktop editor are fully supported in the SDK. This includes Composer-2, Cursor’s specialized coding model, as well as third-party models like GPT-5.5 and Claude Opus.

Installation and API Integration

The SDK is distributed as a standard npm package. You install it by running npm install @cursor/sdk in your Node.js environment.

Because the SDK is currently in public beta, the configuration schemas are subject to minor updates. The Cursor SDK documentation maintains the complete list of initialization parameters, type definitions, and constructor patterns required to authenticate your application.

Simultaneous to the SDK, Cursor launched the Cloud Agents API (v1) to manage remote agent execution. This API relies on Server-Sent Events (SSE) streaming to provide real-time updates during run execution. If a connection drops, your application can cleanly resume the stream using standard Last-Event-ID reconnect support.

The API enforces per-prompt run scoping. This ensures that memory management remains predictable across long-running autonomous tasks. You also have full programmatic lifecycle controls to archive, unarchive, or permanently delete completed agent sessions.

Runtime Environments

The SDK allows you to execute agent loops in three distinct environments using the exact same interface. You configure the target runtime during agent initialization based on your security requirements and workflow needs.

Runtime	Execution Environment	Best For
Local	Developer workstation	Fast iteration and workflow testing
Cloud	Sandboxed Cursor VMs	Durable, long-running asynchronous tasks
Self-Hosted	Private network workers	Strict data compliance and internal tooling

The Cloud Runtime is built for durability. Sessions execute on Cursor’s cloud infrastructure and will continue running even if the initiating client disconnects or goes to sleep. This makes it ideal for autonomous maintenance tasks, such as self-driving codebases that systematically manage dependency updates across an organization.

Self-Hosted Workers target enterprise compliance requirements. By running the agent execution layer within your own infrastructure, all source code and tool execution remains strictly within your private network boundaries.

Extending Agent Capabilities

The Cursor SDK provides multiple extension points to connect your programmatic agents to internal business logic and external data sources.

Agents natively support the Model Context Protocol. By attaching MCP servers to your agent instance, you can grant the model secure read and write access to issue trackers, internal wikis, or external cloud services.

The SDK also respects repository-level agent skills. If your target codebase contains a .cursor/skills directory, the agent automatically integrates those specific instructions and tool definitions into its context.

For custom workflow orchestration, the SDK exposes programmatic hooks. You can use these hooks to intercept the agent loop, inject custom validation logic, or pause execution pending human approval before the agent commits a change.

Pricing and Tradeoffs

The Cursor SDK uses standard token-based consumption pricing. You are billed based on the total number of input and output tokens processed by the underlying models during the agent run.

Building with the SDK introduces specific architectural tradeoffs. While the harness handles heavy lifting for code indexing, you are delegating total control of the chunking and retrieval strategies to the Cursor engine. Organizations requiring highly customized embedding pipelines for non-standard codebases may find the default harness too opaque.

Additionally, utilizing the Cloud Runtime requires transmitting repository data to external virtual machines. Teams with strict air-gapped security policies must use the Self-Hosted Workers option, which introduces the operational overhead of provisioning and maintaining your own execution environments.

Before deploying programmatic agents to production CI/CD pipelines, configure aggressive token limits and monitor early runs closely. You should systematically evaluate and test AI agents against a sandbox repository before granting them write access to critical infrastructure.