Cursor SDK for agents

The situation

Cursor’s April 29 changelog adds an SDK for building agents with the same runtime, harness, and models used by the product itself. It lets teams script agents locally or run them in Cursor’s cloud on a dedicated VM, using a frontier model and a small TypeScript surface.

For Cursor users, the shift is practical: agent work moves from inside the app to inside your codebase and workflow. The next questions are which tasks deserve a reusable agent, which rules belong in the repo, and what gets checked before agent output is trusted.

The changelog also notes a reworked Cloud Agents API: durable agents, per-prompt runs, run-scoped follow-ups, streaming, cancellation, lifecycle controls, and standardized response and error shapes. That points to a more operational workflow. Teams need to be able to observe, resume, cancel, and review runs cleanly.

If you are mapping this to team practice, see Cursor subagents and skills.

Walkthrough

1. Start with the smallest useful agent. The changelog example is simple: create an agent, point it at a repo, send one prompt, and stream events back. Use that for bounded work first, like repo summaries, codebase inspection, or a narrow transformation.

2. Decide where the agent runs. Cursor says the SDK can run locally or in Cursor’s cloud on a dedicated VM. Treat that as a policy choice. Local runs are easier to inspect against a developer workspace. Cloud runs fit isolation, repeatability, or a shared execution environment.

3. Put rules close to the code. Cursor’s rule model lives in scoped .cursor/rules/*.mdc files, not one monolithic rules file. Keep agent behavior near the files it affects.

---
description: Apply when editing API client code
globs:
  - src/api/**
  - tests/api/**
apply: auto
---

- Prefer small diffs.
- Update tests with behavior changes.
- Ask before changing public interfaces.

4. Add a repo boundary in AGENTS.md. The SDK makes agent runtime more programmable, but it does not remove the need for repository rules. Use AGENTS.md for durable team conventions: what the agent may change, what it must not touch, and how to verify output.

# AGENTS.md

- This repo uses Cursor agents for scoped refactors only.
- Do not modify deployment config without explicit review.
- Every agent-authored change must include tests or a clear reason why not.
- Prefer one task per run; cancel and restart instead of widening scope.

5. Use a review checklist. The move to run-scoped follow-ups and explicit lifecycle controls implies a more auditable workflow. A practical checklist is: did the agent stay within scope, did it stream a coherent run, did it touch the right files, and did tests or validation cover the change?

6. Turn repeatable work into skills. Cursor’s SDK fits the broader skills pattern: package instructions, scripts, and resources so the agent can load them when needed. For teams, the useful habit is to turn recurring work into a named capability instead of re-explaining it in chat.

7. Keep follow-ups run-scoped. Cursor’s API changes make follow-ups, status, streaming, and cancellation part of a specific run. Use the same habit in team workflows: one run, one objective, one review trail. If the task changes materially, start a new run.

Tradeoffs and limits

The SDK lowers the cost of building agents, but it does not solve task design. If the prompt is vague, the agent will still wander. If repo rules are broad, the agent will still make risky edits. If review is weak, faster runs just create faster mistakes.

Run-scoped APIs also make it easy to over-orchestrate. Not every coding task needs a durable agent, a skill, and a cloud VM. For many changes, a scoped rule plus a normal Cursor session is simpler and easier to trust. Use the SDK when the task repeats, benefits from streaming, or needs a stable execution boundary.

The changelog mentions public beta and token-based pricing. Teams should watch cost and usage early, especially if they move from manual prompting to automated runs. Budgeting is part of governance here.

The API changes are a signal, not a complete operating model. Durable agents, lifecycle controls, and SSE streaming help with observability, but they do not replace code review, test coverage, or permission review. Keep the agent narrow, the rules local, and the review explicit.

A small methodology note: in the Review step, verify the run before you trust the output. That matters when the agent can stream, resume, or continue after a follow-up.

Further reading

• Cursor Docs
• Cursor Rules
• Cursor changelog
• Cursor subagents and skills
• Our methodology