Cursor Agent SDK Guide: Setup, Evals, Channels and Deploy

Last updated: October 29, 2026

The Cursor Agent SDK, generally available since October 20, 2026, lets you build an AI agent as a folder of Markdown and TypeScript. You test it locally in a playground, guard it with evals, connect GitHub, Slack, webhook or cron triggers, and deploy it to Cursor hosting or your own servers.

Cursor says the SDK uses the same harness that powers its Bugbot, Security Review, Approval Bot and Rollouts products (Agent SDK overview). This guide covers what shipped, how to set it up and the settings power users should know.

Contents

What’s new
Agent SDK vs Automations
How to start
Project layout
Channels and triggers
Evals
Deployment, secrets and cost
Limitations
Frequently asked questions

What’s new in the Cursor Agent SDK

The October 20 changelog entry announced the Agent SDK as generally available. Its main ideas are agents as code, local development with a playground, evals, channels that wake the agent, and one-command deployment with agent-sdk deploy.

The SDK’s own changelog lists version 0.3.0 as the GA release on October 23, 2026. That release removed the persistent option from defineAgent. Projects that still set it now fail validate, dev and deploy until the field is deleted.

Note the package name. The launch post used npx @cursor/agent-sdk init, while the current docs install @grok/agent-sdk and say the package was previously called @cursor/bdk. Follow the docs when you install today.

Cursor Agent SDK vs Automations and Grok Bot

Cursor’s documentation compares its three ways to build an agent:

Question	Cursor Automations	Grok Bot	Agent SDK
You define	A prompt, model and trigger in the dashboard	Instructions, skills and connected tools in the app	A versioned Markdown and TypeScript project
Where it runs	Cursor-managed	Cursor-managed	Cursor-managed hosting or your infrastructure
Choose it when	The job fits a schedule or event trigger	You want to configure and talk to an agent without code	You want code around model judgment that your team can version, review and test

If you already run a dashboard Automation, agent-sdk init --from automation:<url> converts it into a project with its prompt, model, schedules and channels. Credentials, webhook registration and Automation memory do not carry over.

How to start with the Cursor Agent SDK

The quickstart builds a pull request reviewer. The core steps are:

Check Node. You need Node 22.13 or newer and a Cursor login for model turns.
Install and sign in with npm install -g @grok/agent-sdk and agent-sdk login.
Scaffold with agent-sdk init ./pr-reviewer. Add --template to start from a template such as security-reviewer, agentic-owners, triage-linear or triage-jira.
Run locally with agent-sdk dev, then test a turn from a second terminal with agent-sdk run --dir . --message "Introduce yourself in one sentence."
Call a tool without a model turn using agent-sdk tool call <tool> --dir . --input '{...}' to check deterministic logic.
Validate with agent-sdk validate --dir . before you deploy.

Project layout and model settings

Agent files live under bot/, and each file’s path decides how the SDK loads it. Evals live in evals/ beside it.

Path	What it holds
`bot/instructions.md`	Always-on system prompt, required on the root agent
`bot/agent.ts`	defineAgent config: model, local options, hosting, concurrency
`bot/tools/<name>.ts`	One typed tool, named after the file
`bot/skills/`	Procedures the model loads on demand
`bot/mcp-connections/`	MCP servers the model can use
`bot/subagents/<id>/`	Child agents, each with a required description
`bot/channels/<name>.ts`	HTTP routes under /v1/channels/<name>
`bot/schedules/`	Cron-driven runs
`bot/lib/`	Shared code that is never discovered as a tool

The default model is grok-4.5 with effort set to high and fast set to true. Effort and speed are parameters, so an ID like grok-4.5-fast is rejected:

import { defineAgent } from "@grok/agent-sdk";

export default defineAgent({
  model: { id: "grok-4.5", params: [{ id: "effort", value: "high" }] },
  concurrency: { maxRunningTurns: 4 },
});

Run agent-sdk info --dir . to list every discovered tool and channel.

Channels and triggers

Channels decide where the agent receives work. According to the changelog, agents wake on pull request, comment and CI events from GitHub, GitLab and Bitbucket, on Slack mentions and DMs, on webhooks from any provider and on a cron schedule.

GitHub events can arrive through your Cursor account, so no public webhook URL is needed. The docs note that Cursor-account delivery carries pull request and comment events, while push, issue and CI triggers need a GitHub App or agent-sdk github forward. To test without waiting for a push, agent-sdk github replay <pr-url> --dir . --action opened sends a real pull request as signed webhook payloads.

For other coding agents released this month, see our Claude Code power-user guide and our GitHub Copilot Fusion guide.

Evals: lock in agent behavior

An eval sends a fixed message to the real agent and checks which tools ran, with what input, and the shape of the reply (CLI reference). A typical case asserts that the agent called an inspection tool and did not call an approval tool.

await t.send("Is https://github.com/acme/checkout/pull/42 ready to approve?");
t.succeeded();
t.calledTool("inspect_pr");
t.notCalledTool("approve_pr");

Run agent-sdk eval --dir . --tag smoke locally or in CI. --strict fails a scored case below its soft threshold, --junit writes a report for CI, and the command exits 1 on failed cases. Evals run real tools, so guard any write actions first.

Deployment, secrets and cost

The deployment guide says agent-sdk deploy builds the pushed Git ref, so uncommitted changes do not ship. You manage deployed agents in the Deployed Agents dashboard.

Egress: list every host your code calls in hosting.egressDomains. Your team’s egress policy limits which hosts you can list.
Secrets: declare names in hosting.secretNames and set values with agent-sdk secret set <slug> <NAME>. Never commit values or use a name starting with CURSOR_.
State: sessions, ctx.host.kv and ctx.host.files survive restarts and redeploys. Other disk writes can disappear.
Alias token: printed once on first deploy. Rotate it with agent-sdk deployment rotate-token <slug>.
Privacy: managed hosting works with Privacy Mode but refuses deploys under Privacy Mode (Legacy).

The Agent SDK pages we reviewed do not publish a separate price. Model turns require a Cursor login, and agent-sdk session list can show session costs, so check usage there and on your Cursor plan before you scale up.

If you want to compare the models an agent can call, our GPT-6.1 Terra guide and Grok Voice 3.0 guide cover recent API releases.

Limitations to know

Self-hosting requires Node 22.13 or newer and does not support Bun.
Older tutorials may show the earlier package names.
Projects written before 0.3.0 that set persistent must remove it.
The Automation converter does not carry credentials or memory and does not support Cursor-managed Automations.

Frequently asked questions

What is the Cursor Agent SDK?

The Cursor Agent SDK is a toolkit for defining, testing, evaluating and deploying AI agents as code. An agent is a project folder of Markdown instructions and TypeScript tools. You can deploy it to Cursor-managed hosting or your own infrastructure.

When did the Cursor Agent SDK become generally available?

Cursor announced general availability in its changelog on October 20, 2026. The SDK’s own changelog lists version 0.3.0 as the GA release on October 23, 2026.

How do I install the Cursor Agent SDK?

You need Node 22.13 or newer. The current docs install the CLI with npm install –global @grok/agent-sdk, then run agent-sdk login, agent-sdk init ./my-bot and agent-sdk dev to start a local playground.

Which model does the Agent SDK use by default?

The agent config reference says the default model is grok-4.5 with effort set to high and fast set to true. You can change it in bot/agent.ts with defineAgent.

How is the Agent SDK different from Cursor Automations?

Cursor’s docs say Automations are a prompt, model and trigger set in the dashboard, while the Agent SDK is a versioned Markdown and TypeScript project. agent-sdk init –from automation converts an existing Automation.

Can I self-host an Agent SDK agent?

Yes. agent-sdk serve runs every agent under a directory on Node 22.13 or newer, not Bun. The deployment docs ask you to set a bearer token and put TLS or an authenticating proxy in front.

Sources

Image: Cursor logo by Anysphere, public domain, via Wikimedia Commons. Placed on a white background and resized.

Cursor Agent SDK: Power-User Guide to Setup, Evals, Channels and Deploy