Cursor Agent SDK: what it is and how to use it

Cursor Agent SDK is a framework for building your own AI agents as code. The prompt is a Markdown file, each tool the model can call is a TypeScript file, and you deploy the result to Cursor's servers or run it yourself. To try it, install the CLI with npm install --global @grok/agent-sdk, run agent-sdk init ./my-bot, then agent-sdk dev.

The post that put it on everyone's feed

On Monday, @cursor_ai announced that "the Agent SDK is now available," and summed it up in one line: "Define agents as code, with prompts in Markdown and tools in TypeScript." The post also says you can host agents on Cursor's infrastructure or your own, and that built-in evals measure each change.

Cursor's blog post and changelog went up on October 20, so the X post was a wider push a week later. What caught my eye is the harness. Cursor says the SDK runs on the same one behind its own managed agents: Bugbot, Security Review, Approval Bot and Rollouts. Last week the company also shipped Cursor Computer Use, which lets its coding agent drive desktop apps on your own machine. The Agent SDK is for the other kind of agent, the one that sits in your repo or Slack and works while nobody is at the keyboard.

What it can do

Everything lives in a project folder, with the agent's files under bot/ and tests under evals/. Here is what each piece does, from Cursor's docs and changelog:

Channels cover pull request, comment and CI events from GitHub, GitLab and Bitbucket, plus Slack mentions and DMs, webhooks from any provider, and cron schedules. Each conversation keeps its own session and full record, and follow-ups pick up where they left off.

Cursor shows where it fits next to its other options. Automations are a prompt, model and trigger set in a dashboard. Grok Bot is for talking to an agent without writing code. The SDK is for teams that want the agent in version control, reviewed and tested like any other code.

How to try it

You need Node 22.13 or newer and a Cursor login. One naming quirk to watch: the changelog shows npx @cursor/agent-sdk init, but that package wasn't on npm when I checked. The current docs install @grok/agent-sdk and note the package used to be called @cursor/bdk. The @grok name fits Cursor's new owner. SpaceX bought Cursor in August, as covered in our post on OpenAI cutting off Cursor. Version 0.3.0 of @grok/agent-sdk went up on npm on October 25.

npm install --global @grok/agent-sdk
agent-sdk login
agent-sdk init ./pr-reviewer
cd pr-reviewer
agent-sdk dev

In a second terminal, agent-sdk run --dir . --message "Introduce yourself in one sentence." confirms it answers. From there, Cursor's quickstart builds a pull request reviewer. A tool called inspect_pr sorts each PR as trivial, moderate or large based on lines and files changed. Then instructions.md tells the agent what to do with each class: approve trivial changes that match their title, approve moderate ones only when every patch is clear, and send large ones straight to a human. The rule I'd copy into any agent is "Never approve a draft."

Before you deploy, agent-sdk eval runs your tests locally or in CI, and agent-sdk github replay <pr-url> turns a real past pull request into test input. When it passes, agent-sdk deploy builds the agent, gives it a URL and runs it on Cursor's servers. If you'd rather host it yourself, each agent is a single Node process you can put in a container. init --template offers four starting points: a security reviewer, an owners-policy approver, a PR autofixer, and a Linear or Jira triager.

On cost, neither the announcement nor the docs I read list a separate price. Model turns run on your Cursor login, so check Cursor's pricing page before you point a busy webhook at an agent.

My read

The best example in Cursor's announcement is a small one. One team built "kb-reviewer" in about a day. It reads every PR in their main codebase and flags changes that go against a lesson the team wrote down earlier. A narrow job and a written rule, with tests to show the agent sticks to it. I'd spend most of my attention on the evals and PR replay. Homemade agents tend to rot because nobody can tell whether last week's prompt edit broke something, and replaying real pull requests is a cheap way to find out.

It also fits a wider drift, the same one behind Agent Skills moving to the Agentic AI Foundation: agents are becoming plain files you can read and carry between vendors.

You can take the lesson without ever opening Cursor. Write the agent's rules down where a person can review them, keep its list of actions short, and test it before it touches customers. If you're trying to work out which of your processes are worth handing to an agent, New Face Design's free process audit is a good place to start.