Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

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

What to do first

  1. Install from the docs, not the changelog. Use @grok/agent-sdk and confirm the package name in Cursor's docs before you run it.
  2. Scaffold one narrow bot. A PR autofixer or a triager, not a general-purpose agent. One channel, one or two tools, and one eval.
  3. 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.
  4. Replay a real pull request. agent-sdk github replay against a closed PR shows whether the bot handles real webhook payloads, not just the happy path.

Limits

Related playbooks

Sources

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