Key Takeaways
- Cursor Agent SDK is a developer kit for defining AI agents as code: each agent's prompt is a Markdown file and its tools are TypeScript modules, so agents live in version control like any other project file.
- You can deploy agents on Cursor's hosted infrastructure or run them on your own machines, which matters if your team has strict data-handling rules.
- Built-in evals let you measure every prompt or tool change, so you can keep improvements and drop regressions instead of guessing.
- Get started from the official site, cursor.com, where you download Cursor Desktop or the CLI, sign in, and follow the docs.
Quick Facts
| Type | Developer SDK for building AI agents as code |
|---|---|
| Devices | Desktop and CLI, primarily on macOS; docs in browser |
| Price | See the Pricing page on cursor.com |
| Languages | Prompts in Markdown, tools in TypeScript; UI language switchable |
| Highlight | Built-in evals plus hosted or self-hosted deployment |
| Learning curve | Moderate; easier if you know TypeScript and Git |
| Category | Dev & Web Tools |
| Creator | Cursor |
| Official site | cursor.com ↗ |
| Heat | 🔥 277.3K Heat |
| Last updated |
What Cursor Agent SDK Is and Why Developers Are Paying Attention
Cursor Agent SDK is a development kit from Cursor, announced on October 26, 2026, that lets you define AI agents as code rather than as settings buried in a chat window. Each agent's instructions live in a Markdown file, and the tools it can call are written in TypeScript. That structure means an agent becomes a reviewable, versionable artifact you can diff, test and ship alongside the rest of your codebase.
The kit supports two deployment paths: Cursor's hosted infrastructure, or your own machines. That choice is the reason many teams are looking at it now. If your organization has rules about where code and data may live, self-hosting lets you keep execution inside your own environment while still using the same agent definitions and evaluation workflow.
What separates it from simply prompting a coding assistant is the built-in evals. Instead of changing a prompt and hoping for the best, you run evaluations and compare results before and after each edit. Cursor frames the product as a way to make agents better over time, and the eval loop is the mechanism that turns that claim into something measurable.
- Agents as code
Prompts are Markdown files and tools are TypeScript, so agents can be committed, reviewed and rolled back like any other source file.
- Hosted or self-hosted
Deploy on Cursor's infrastructure for convenience or on your own machines when data residency and internal policy demand it.
- Evals built in
Every prompt or tool change can be scored, letting you keep improvements and catch regressions before they reach production.
- Surrounding platform
Cloud, Automations, Marketplace and Review extend agents from a single script into a managed workflow; check the official site for current details.
How the Markdown Prompts, TypeScript Tools and Evals Fit Together
An agent in this SDK has two halves. The prompt half is a Markdown document: plain text with headings and instructions that describe what the agent should do and how it should behave. Because it is Markdown, it stays readable for non-engineers and produces clean diffs when someone edits a sentence. The tool half is TypeScript code that defines the concrete actions the agent may take, such as fetching data or calling an internal service.
Writing tools in TypeScript gives you type checking, which is a practical defense against the most common agent failure: calling a function with the wrong shape of arguments. When a tool's signature changes, the compiler tells you what broke. The notes do not specify which TypeScript runtime versions are supported or how tools are registered, so confirm those mechanics in the documentation on cursor.com before you commit to a structure.
Evals are the third piece and the one that changes daily habits. Rather than treating a prompt edit as an act of faith, you run your evaluation set and compare the score. If the number improves, keep the change; if it drops, revert. Over time this produces a record of what actually made the agent better, which is far more useful than a folder of prompt variants with names like final-v3.
- Keep prompts small and specific
One agent, one job. A Markdown prompt that tries to cover five responsibilities is hard to evaluate and harder to debug.
- Type your tool boundaries
Give each TypeScript tool a narrow, explicit input and output type so mistakes surface at compile time rather than mid-run.
- Change one thing per eval run
Edit either a prompt or a tool, not both, then re-run evals. Isolating variables is what makes the score meaningful.
- Baseline before you optimize
Record an initial eval score on day one. Without a baseline you cannot tell whether later changes helped or merely felt better.
Setting Up a Real Agent Workflow from Install to Review
The practical path starts on the official site, cursor.com, where you download Cursor Desktop or the CLI and sign in. The CLI is often the faster route for a first experiment because it fits into an existing terminal workflow. Once you are signed in, you convert one prompt you already use into a Markdown agent file and describe its tools in TypeScript, keeping the first version deliberately small.
From there, run the built-in evals to establish a baseline. Then improve in small increments: tighten a sentence in the prompt, add a guard to a tool, re-run the evaluation, and keep only changes that move the score. When the agent behaves reliably, deploy it on Cursor's hosted infrastructure or on your own machines, depending on your team's constraints.
The desktop experience shows task states such as Plan, Mission Control and Ready for Review, which gives you a way to follow an agent's progress and inspect its output before accepting it. As you grow, Cloud, Automations, Marketplace and Review let you run agents on a schedule, extend them with integrations and fold them into a team review cycle. Pricing and plan limits are listed on the Pricing page, so check there rather than assuming a free tier.
- Start with one boring task
Pick a repetitive internal chore for your first agent. Low stakes make it easy to judge whether the output is genuinely useful.
- Use Review before trusting output
Treat the review state as a gate. Reading an agent's proposed changes is cheaper than cleaning up an unreviewed commit.
- Automate only after stability
Move a task into Automations once its eval score is steady, not while you are still rewriting the prompt weekly.
- Track the changelog
The SDK is new, so follow the Changelog and Docs on the official site to catch behavior changes and new capabilities early.
Who Should Use It, How It Compares, and Where It Stops
This kit suits engineering teams that already treat prompts as production assets and want them under version control with tests attached. If you write TypeScript and use Git daily, the mental model will feel familiar almost immediately. Solo developers building internal automations are also a good fit, especially if they want the option to self-host later without rewriting agent definitions.
Compared with general agent frameworks, the distinguishing combination here is the pairing of a hosted-or-self-hosted runtime with first-class evals and a surrounding platform of Cloud, Automations, Marketplace and Review. Compared with simply using a coding assistant interactively, the gain is repeatability: the same agent definition can be evaluated, deployed and reviewed by a team rather than living in one person's chat history.
The limitations are worth stating plainly. The notes describe desktop and CLI tooling centered on macOS, and do not confirm mobile or browser-based agent authoring, so do not plan around those. Exact pricing, supported TypeScript versions, evaluation dataset formats and self-hosting requirements are not specified in the announcement; verify each of those on cursor.com before adopting the SDK for critical work.
- Best fit
TypeScript-proficient teams that want agents versioned, evaluated and deployable under their own data policies.
- Weaker fit
Non-developers seeking a no-code agent builder, or anyone who needs confirmed mobile support today.
- Versus interactive assistants
An interactive assistant helps you once; a defined agent with evals can be re-run, compared and improved indefinitely.
- Check before committing
Confirm pricing, supported runtimes and self-hosting details on the official site, since the announcement leaves them open.
Step-by-Step Guide
Get Cursor Desktop or the CLI
Visit the official site, cursor.com, and download Cursor Desktop or the command-line tool. The CLI is usually the quickest way to a first working agent. Sign in with your account to unlock the Agents and Cloud features.
Write your first agent prompt in Markdown
Create a Markdown file describing one narrow task: what the agent should do, what it must not do, and what a good result looks like. Keep it short enough that you can read it in under a minute, since you will be editing it repeatedly.
Define the agent's tools in TypeScript
Write the TypeScript functions the agent may call, giving each one a clear input and output type. Start with a single tool so failures are easy to trace. Check the documentation for the exact registration and runtime requirements.
Run built-in evals to set a baseline
Execute the evaluation suite against your agent and record the score before changing anything. This baseline is what later edits are measured against. If the eval setup is unclear, the Docs on the official site explain the current workflow.
Deploy, review and iterate
Deploy on Cursor's hosted infrastructure or your own machines, then use the review flow to inspect output before accepting it. Change one thing at a time, re-run evals, and keep only changes that raise the score. Add Automations once behavior is stable.
Frequently Asked Questions
Is Cursor Agent SDK free to use?
The announcement does not state pricing, so the honest answer is that you should check the Pricing page on the official site, cursor.com. Cursor lists plan tiers there, and any free allowance would appear in that section. Costs may also depend on whether you run agents on Cursor's hosted infrastructure or on your own machines, since self-hosting shifts compute to you.
Do I need to know TypeScript to use it?
You need TypeScript for the tools half of an agent, since tools are written as TypeScript code. The prompt half is plain Markdown, which anyone can read and edit. If your team has at least one TypeScript developer, they can define the tools while others refine prompts and review eval results. Basic Git familiarity also helps because agents are managed like code.
What exactly are the built-in evals and why do they matter?
Evals are the SDK's scoring mechanism: you run an evaluation against your agent and get a result you can compare before and after a change. They matter because prompt editing is otherwise guesswork, and small wording changes can silently break behavior. By re-running evals after each edit, you keep measurable improvements and revert regressions instead of accumulating untested prompt variants.
Can I run agents on my own servers instead of Cursor's cloud?
Yes. The announcement states that agents can be deployed on Cursor's hosted infrastructure or run on your own machines. Self-hosting is the option to consider when data residency, internal policy or client contracts restrict where code and data may be processed. The notes do not detail self-hosting requirements, so confirm supported environments and setup steps in the documentation on cursor.com.
Which devices and platforms are supported?
The available tooling centers on Cursor Desktop and the CLI, with macOS explicitly mentioned in the reference material. Documentation and the changelog are readable in a browser. Mobile apps and browser-based agent authoring are not confirmed, so if you need those, verify current platform support on the official site before planning around them.
