How to Build a Code-Based Agent with the Cursor Agent SDK

How do I start a project?

The current Agent SDK documentation calls for Node.js 22.13 or newer and the @grok/agent-sdk package. Follow its install and login steps, then create a project with agent-sdk init ./my-bot. Run agent-sdk dev inside the project and a local playground starts.

The October 20 changelog has an init example that uses @cursor/agent-sdk, and that isn't the package the current documentation names. The changelog says the --template option picks a template for a security reviewer, owner policy approval, automatic PR fixes, or Linear or Jira issue triage. So check the current package and access requirements before you install.

Where do the agent's instructions and tools go?

Cursor describes instructions.md as the agent's instructions. Typed actions the model can call go in tools/. Procedures to load when needed go in skills/. mcp-connections/ connects MCP server tools, and channels/ defines the paths for receiving or responding to messages.

Use agent-sdk validate to check the project structure and agent-sdk info to see what it discovers. But a passing validation doesn't cover everything. Check the connected services' permissions and the actual task results separately.

Which events can trigger it?

The official announcement lists pull requests and comments on GitHub, GitLab, and Bitbucket, as well as CI events, as triggers. Slack mentions and DMs, webhooks, and cron schedules work too. The announcement also says GitHub events don't need a public webhook URL, since Cursor receives them through the Cursor account.

Each conversation keeps its own session and records messages and tool calls. A follow-up question in a PR or Slack thread continues in the same session. Also check that access to each connected channel is limited to what the work requires.

How do I deploy and validate it?

For local testing, agent-sdk eval sends fixed messages, so you can check tool calls and response formats. The changelog also lists agent-sdk github replay <pr-url> for testing with a GitHub PR, and the --dry-run --fixtures-dir fixtures/ options save payloads as fixtures for evaluation.

When the project is ready to deploy to Cursor, run agent-sdk deploy from the project directory. Cursor says the command builds the project, gives it a URL, and runs it on Cursor infrastructure. You manage secrets and integrations in the dashboard.

Before you deploy, go through the tools the agent can call and the permissions they've been given. Then run local evaluations and check that the permitted actions and response formats are right. The changelog was checked on 2026-11-2.