The Cursor Agent SDK went generally available on October 20, 2026. It lets you define an AI agent as a small code project, with prompts in Markdown and tools in TypeScript. Then you ship it to Cursor’s servers or run it on your own.
If you’ve ever hand-wired a bot that reviews pull requests, this is Cursor’s answer to the glue code. Here’s what’s in it and how to start.
Quick facts:
- Released: October 20, 2026, and generally available, not a preview.
- Prompts live in Markdown files; tools are typed TypeScript functions.
- Agents can run on Cursor’s hosting or as a single Node process on your own infrastructure.
- Evals, event replay and a local playground are built in.
- Pricing: Cursor’s launch post doesn’t mention it, so check the docs before you commit.
That list is the short version. The rest of this post explains what each piece means in practice.
What a Cursor Agent SDK project looks like
Cursor says it built its own managed agents, including Bugbot, Security Reviewer and Rollouts, on this SDK. So you’re getting the same plumbing the company uses internally.
A project is just a folder. Per Cursor’s docs, a bot/ directory holds the agent and an evals/ directory holds the tests.
| Path | What it does |
|---|---|
bot/agent.ts |
Model and local harness settings |
bot/instructions.md |
The system prompt, written in plain Markdown |
bot/tools/ |
One typed TypeScript tool per file |
bot/skills/ |
Procedures the model loads only when needed |
bot/subagents/ |
Specialist agents, each with its own instructions |
bot/channels/ |
Triggers such as pull requests, CI and comments |
evals/ |
Regression checks for the whole bot |
There’s more in the tree than the table shows. An mcp-connections/ folder holds tools from MCP servers such as Linear, and a hooks/ folder lets you observe session events, which is handy for audit logs. Once a bot is deployed, access is split into three roles: Viewer, Editor and Owner.
Because everything is a file, you can review a prompt change in a pull request like any other diff. That’s the real selling point: agent behavior stops living in a dashboard text box and starts living in version control.
How to build and deploy your first agent
Cursor’s launch post lists four steps. None of them needs a special editor, though Cursor suggests opening the project there.
- Create a project directory.
- Define the agent with
defineAgentfrom@cursor/agent-sdk. - Start the local playground and run your evals.
- Run
agent-sdk deployfrom the project folder.
The deploy command builds the agent, gives it a URL and starts it on Cursor’s infrastructure. Secrets and integrations are managed from the dashboard. Cursor’s docs page also mentions an agent-sdk init command for scaffolding, but the package name in the docs differs from the blog post, so follow the blog’s name and double-check against the live docs.
A good first target is pull request triage. Channels can listen to GitHub, GitLab or Bitbucket events, judge the risk of a change, route it, and approve changes that meet your team’s policy.
Hosted or self-hosted: which should you pick?
Both options run the same project. The difference is who operates it.
| Aspect | Cursor hosting | Self-hosting |
|---|---|---|
| How it runs | agent-sdk deploy builds it and starts it on Cursor’s servers |
A single Node process, which you can package in a container |
| Best for | Small teams that want a URL and no ops work | Teams with strict data or network rules |
| You manage | Secrets and integrations in the dashboard | The container, secrets and uptime |
If your agent touches private repositories, think about this early. It’s also worth reading our piece on how a hidden AGENTS.md file can hijack a coding agent before you give any bot write access.
Why evals matter more than the model
Agents drift. You tweak a prompt to fix one case and quietly break three others.
The Cursor Agent SDK ships evals and event replay so you can test critical workflows before relying on them. Evals are written in normal TypeScript, so there’s no separate config language to learn. Run them in the local playground, change a prompt, run them again.
Multi-agent setups get the same treatment. An agent can hand work to a specialist or split a job across parallel subagents, and your evals cover the whole chain.
This fits the wider push toward agents that act on your machine, like Cursor’s computer use feature. More autonomy means more reason to test.
Frequently Asked Questions
What is the Cursor Agent SDK?
It’s a framework for building and deploying agents defined in code. Prompts go in Markdown, tools in TypeScript, and the result can be version-controlled and code-reviewed like any software project.
Is the Cursor Agent SDK free?
Cursor’s announcement doesn’t state pricing. Check the official docs and pricing page before you deploy anything that runs on a schedule.
Can I run agents on my own servers?
Yes. Cursor says each agent runs as a single Node process that you can package in a container.
Do I need Cursor’s editor to use it?
The docs suggest opening the project in Cursor, but the project itself is ordinary files and a command-line tool. Any editor can work with them.
My take: try the Cursor Agent SDK on one low-risk job first, like labeling pull requests, and write the evals before the prompt. If those evals pass for a week, widen the bot’s permissions a little. Skip the self-hosting setup until you actually have a compliance reason, because Cursor’s hosting gets you running in minutes.
Leave a Reply