Playbooks · Coding tasks
Cursor Agent SDK: define an agent as a folder
Written November 8, 2026
Cursor's Agent SDK treats an agent as a project folder — instructions, tools, skills, MCP connections — testable with evals, deployable to Cursor's infra.
What it is
Cursor's Agent SDK, generally available from October 20, 2026, treats an agent as a project you can check into a repo: a folder of code, tested with evals, deployed to Cursor or your own infrastructure. It is the same harness Cursor uses for its own managed agents — Bugbot, Security Review, Approval Bot, and Rollouts all run on it. The point is the shape: an agent defined in files has a history, a diff, and a test run, where an agent defined in a settings box has none of those.
The folder contract is fixed. instructions.md is the prompt. Each file in tools/ is one typed action the model can call. skills/ holds procedures the model loads on demand, mcp-connections/ adds tools from MCP servers, and channels/ defines where the bot receives and answers messages. agent-sdk dev runs the bot locally with a playground; agent-sdk validate checks the project and agent-sdk info prints what was discovered. agent-sdk deploy builds the agent, gives it a URL, and starts it on Cursor's infrastructure, with secrets and integrations managed from the dashboard and the same logs, evals, and playground available locally.
Agents wake on pull request, comment, and CI events from GitHub, GitLab, and Bitbucket; on mentions and DMs in Slack; on webhooks from any provider; and on a cron schedule. GitHub events pull through your Cursor account, so no public webhook URL is required. Each conversation keeps its own session and a complete record of every message and tool call, and follow-ups on a pull request or Slack thread resume the same session.
The install command in the changelog does not work as printed
Cursor's changelog tells readers to run npx @cursor/agent-sdk init ./my-bot. Independent checks on October 27–29 found that npm answers 404 for @cursor/agent-sdk — the package is not on the registry under that name. Cursor's docs install @grok/agent-sdk instead: npm install -g @grok/agent-sdk, then agent-sdk login and agent-sdk init ./my-bot. The same code has gone out under three npm names (@cursor/july, @cursor/bdk, and @grok/agent-sdk), and the docs name @grok/agent-sdk as the current one. Start from the docs, not from the changelog's command, and check the package name again before you script it into anything — the SDK was at version 0.5.0 by October 28, two minor versions past the 0.3.0 release the docs label as generally available, so the ground is still moving.
Evals are the reason to use it
An eval sends a fixed message to the bot and asserts on what it did: which tools ran, with what input, and the shape of the reply. Run agent-sdk eval locally or in CI. agent-sdk github replay <pr-url> turns a real pull request into signed webhook payloads and sends them to the bot, so a GitHub-driven bot can be tested without waiting for a push. This is the part that makes the folder shape pay off: a prompt change that breaks a tool call shows up as a failing eval before the bot ever answers a real pull request. The evals are yours to write — the SDK gives you the runner, not the test cases.
Templates give a starting point: pass --template to start from a security reviewer, an owners-policy approver, a PR autofixer, or a Linear or Jira triager.
What it is not
- It is not a hosted-agent product by itself. The SDK is a framework for defining and running an agent. Deploying to Cursor's infrastructure is one option; running it on your own infrastructure is the other. Either way, you own the agent's behaviour.
- Not a way out of Cursor's model loop. Even a self-hosted agent still routes its model calls through Cursor, per Cursor's docs. Self-hosting moves the process, not the inference.
- Not priced. Neither Cursor's pricing page nor its docs give a price for a deployed agent's hosting, or say which plan is required to deploy one. Do not budget for hosting until Cursor publishes a figure.
- Not portable as a whole. Instructions in Markdown, skills, and MCP server configs port to other harnesses — they are plain files. Triggers, hosting, state, and evals are written against
@grok/agent-sdkand stay with it.
What to do first
- Install from the docs, not the changelog. Use
@grok/agent-sdkand confirm the package name in Cursor's docs before you run it. - Scaffold one narrow bot. A PR autofixer or a triager, not a general-purpose agent. One channel, one or two tools, and one eval.
- Write the eval before the prompt. A fixed message, an assertion on which tools ran and with what input. The eval is what turns the folder from a layout into a testable agent.
- Replay a real pull request.
agent-sdk github replayagainst a closed PR shows whether the bot handles real webhook payloads, not just the happy path.
Limits
- This page reads Cursor's changelog and docs, plus independent checks of the package name. No agent was built, deployed, or run here, so it says nothing firsthand about the SDK in use.
- The changelog's install command names a package npm does not carry. The working package name comes from Cursor's docs and independent checks, and it may change again — confirm it before installing.
- No price for hosting a deployed agent is published. This page states that the price is unstated rather than guessing one.
- The SDK moved from 0.3.0 to 0.5.0 in five days. Anything version-specific here dates to the October 20–28 releases and may already be superseded.
Related playbooks
- Cursor Agent SDK is GA, with 300-repo environments
- Don't resume an Agent SDK session from an untrusted ID
- Cursor builds live apps from cloud agents
- Cursor's freeze cost, measured
Sources
- What's New in Cursor — Agent SDK — Cursor Changelog
- Agent SDK — Cursor Docs
- Cursor Agent SDK Tutorial: Install, Build and Deploy a PR Agent — Apex Logic
Back to: Coding playbooks hub · Also: Cursor builds live apps from cloud agents · GitHub Agentic Workflows are now GA · Cursor agents take voice calls now