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

lization & Execution:**

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

Architecture Decisions & Implementation Details:

• Model & Runtime Selection: Agent.create() accepts an apiKey, a model configuration, and either local or cloud execution parameters. Cloud execution routes tasks to sandboxed VMs with isolated filesystems and deterministic network policies.
• Streaming Event Loop: The run.stream() iterator provides real-time token deltas, tool calls, and state transitions, enabling fine-grained progress tracking and custom orchestration logic.
• Intelligent Context Management: The harness automatically indexes the codebase, performs semantic search, and injects relevant file contexts before LLM inference. This eliminates manual RAG pipelines and ensures agents operate on precise, up-to-date repository state.
• MCP Server Integration: Agents connect to external tools and data sources via stdio or HTTP using the Model Context Protocol. Configuration is handled through .cursor/mcp.json or inline API parameters, enabling standardized tool routing without custom adapter code.
• Skills & Hooks: Reusable behavior definitions are loaded from .cursor/skills/. The .cursor/hooks.json file enables cross-runtime observation and control, supporting logging, guardrails, and custom orchestration hooks across cloud, self-hosted, and local environments.
• Subagent Delegation: The primary agent can spawn named subagents with distinct prompts and model routing via the Agent tool. This enables multi-agent workflows without external orchestration frameworks, maintaining state isolation and clear delegation boundaries.

Pitfall Guide

1. Context Window Overflow: Feeding entire repositories or unfiltered file trees into agent prompts exhausts context limits and degrades output quality. Best Practice: Rely on the harness's intelligent context management and semantic search. Explicitly scope tasks to relevant directories or use MCP tools to fetch targeted snippets.
2. Hook Blocking & Infinite Loops: Misconfigured .cursor/hooks.json files can block agent execution or trigger recursive event loops. Best Practice: Implement async, non-blocking hooks with explicit timeouts. Validate hook payloads before mutation and avoid synchronous I/O in critical path hooks.
3. Subagent Nesting Debt: Creating deeply nested subagent chains without clear delegation boundaries causes state drift and token waste. Best Practice: Limit subagent depth to 2–3 levels. Define explicit prompt contracts, route models based on task complexity, and enforce termination conditions.
4. MCP Server Security Exposure: Exposing untrusted tools via stdio/HTTP without input validation creates injection and data exfiltration risks. Best Practice: Scope MCP tools to least-privilege operations. Validate all tool inputs/outputs, enforce network isolation in cloud VMs, and audit tool call logs.
5. Local vs Cloud Environment Drift: Assuming local cwd execution behaves identically to sandboxed cloud VMs leads to path resolution failures and dependency mismatches. Best Practice: Containerize runtime dependencies, use explicit environment variables, and validate parity between local and cloud execution contexts before production deployment.
6. Token Cost Blindness: Running verbose streaming or unoptimized prompts without monitoring causes unpredictable billing spikes. Best Practice: Implement token budgeting, configure token-based pricing alerts, and optimize prompt templates to minimize redundant context injection.

Deliverables

• Blueprint: Cursor SDK Agent Architecture Blueprint – Covers harness initialization, MCP tool routing, subagent delegation patterns, and cloud VM sandboxing strategies for production deployment.
• Checklist: Production-Ready Agent Deployment Checklist – Validates security boundaries, hook configuration, context indexing integrity, token monitoring setup, and environment parity before pipeline integration.
• Configuration Templates: Ready-to-use .cursor/mcp.json, .cursor/hooks.json, and .cursor/skills/ directory structures with annotated examples for tool integration, execution guardrails, and reusable behavior definitions.