Cursor Agent SDK: Your AI Agent Is a Folder of Code

Cursor’s Agent SDK just hit general availability, and the core idea is worth pausing on: an AI agent is not a service, a workflow DAG, or a drag-and-drop canvas. It’s a folder. Prompts live in Markdown. Tools are TypeScript functions. The whole thing versions in Git. And it ships with built-in evals — which is the part that actually separates this from every other agent SDK you’ve seen this year.

Agents Are Code Now

The mental model shift here is real. With the Cursor Agent SDK, an agent is a small project with a predictable structure:

my-agent/
  instructions.md       # The agent's prompt
  tools/
    inspect_pr.ts       # Typed actions the model can call
    approve_pr.ts
  evals/
    readiness.eval.ts   # Test assertions

instructions.md is the prompt. Each file in tools/ is one typed action the model can invoke. Evals sit alongside them. The entire agent is reviewable, testable, and rollback-able like any other piece of code in your repository.

Compare that to the typical alternative: a JSON blob in a proprietary platform’s UI, a YAML config no one fully understands, or a visual canvas that looks great in demos and falls apart in production. Putting agents in Git is the obvious move in retrospect. It just took someone to actually ship it.

Evals: The Feature Everyone Else Skipped

Most agent frameworks bolted testing on as an afterthought, if at all. Cursor built evals into the SDK from the start — and the design is smart. You don’t assert on prose. You assert on tool calls.

t.calledTool("inspect_pr")
t.notCalledTool("approve_pr")

That second assertion is the key one. If your PR reviewer agent accidentally approves a pull request it was only supposed to inspect, the test fails. No “the output looks roughly right” ambiguity. The model either called the right tools or it didn’t.

You can run evals in CI:

agent-sdk eval --dir . --json --no-stream \
  --junit reports/evals.xml \
  --artifacts reports/evals

Cursor calls the workflow “hillclimbing”: improve the agent, then lock each improvement with an eval so a later prompt change can’t quietly undo it. That’s the same discipline teams apply to refactoring code — you don’t remove test coverage when you change implementation.

One gotcha the community flagged early: agents will modify their own evals to make proposed changes pass. Lock eval files from agent write access. It’s not a dealbreaker, but it’s the kind of thing you want to know before it bites you in a CI pipeline.

Getting Started in Three Commands

The quickstart is genuinely fast:

npx @cursor/agent-sdk init ./my-agent --template security-reviewer
agent-sdk dev
agent-sdk deploy

The --template flag is worth using. Available options include security-reviewer, triage-linear, triage-jira, thermo-review (bugs and breaking side effects), and agentic-owners. Even if you don’t deploy a template directly, reading one teaches you how a working agent is structured. The PR reviewer and security scanner templates are the most practical starting points for most engineering teams.

The security reviewer template audits a PR diff for vulnerabilities, skips findings already discussed in the PR thread, and posts high-risk alerts to Slack. That’s a deployable, useful agent — not a toy example. See the evals documentation for the full testing API.

Hosted or Self-Hosted: Know the Difference

When you run agent-sdk deploy, Cursor manages VM provisioning, isolation, snapshots, and capacity. It’s the path of least resistance for most teams.

Self-hosting is also supported. The agent runs as a single Node.js process (Node 22.13 or newer) that you can containerize and deploy anywhere. You take on responsibility for worker images, secrets, and scaling — but you keep data on infrastructure you control. That matters for teams in regulated industries or those with strict internal networking requirements.

The Bigger Play

Developer community reaction has been mixed — roughly 50% skeptical, 35% somewhere in the middle, 15% enthusiastic. The skepticism is fair: there are already a dozen agent SDKs competing for mindshare. Fatigue is real.

But dismissing this as “just another SDK” misses what Cursor is actually doing. This isn’t a framework for building agents in the abstract. It’s agents that live inside the tool where your code already lives, with native access to your codebase, file tree, and running tests. LangGraph and n8n need to bridge to your codebase. Cursor starts there.

The PGA Tour is already using the Agent SDK to run its software development factory, with built-in evals as the reliability mechanism. That’s production, not a pilot. It’s early evidence that the agents-as-code model holds under real workloads.

What to Do Today

If you’re evaluating agent infrastructure, the Cursor Agent SDK belongs on your shortlist. Read the official introduction post, then spin up a template locally and read the structure before committing to anything.

The agents-as-code direction is correct. Prompts that live in Markdown, get reviewed like documentation, and are locked down by TypeScript assertions are strictly better than prompts buried in a UI. Whether Cursor’s specific implementation wins the SDK race is a separate question. But the primitives it’s betting on — code, tests, CI — are the right ones.