Based on Anysphere’s official docs, checked October 27, 2026

Cursor Agent SDK: build, test and deploy agents as code

Cursor’s Agent SDK lets you define an agent as a folder of Markdown and TypeScript, then test, evaluate and deploy it like the rest of your code. Cursor says it uses the same harness that powers Bugbot, Security Review, Approval Bot and Rollouts. Version 0.3.0, dated October 23, 2026 in the SDK changelog, is marked as the GA release. This guide covers installing the CLI, the project layout, writing instructions and tools, triggering the agent from GitHub, Slack or a schedule, guarding it with evals and deploying it. Everything here comes from Cursor’s Agent SDK documentation, checked October 27, 2026.

1. 1. Install the CLI and sign in

   You need Node 22.13 or newer. Cursor’s docs install the package globally, then sign in for model turns. The docs note the package was @cursor/bdk before.

   npm install --global @grok/agent-sdk
   agent-sdk login

2. 2. Scaffold a project

   agent-sdk init creates the project; agent-sdk dev runs it locally.

   agent-sdk init ./my-bot
   cd my-bot
   agent-sdk dev

3. 3. Check that it replies

   In a second terminal, send one message to the running agent.

   agent-sdk run --dir . --message "Introduce yourself in one sentence."

4. 4. Write the instructions

   bot/instructions.md is the always-on system prompt and is required on the root agent. Cursor recommends a few lines: who the agent is, when to use each tool, and the output shape.

   # PR reviewer
   
   You review GitHub pull requests. Be specific and brief.
   
   1. Call `inspect_pr` first. Never judge a change you haven't fetched.
   2. Match your review to the complexity it reports.
   3. Never approve a draft.
   
   End with one sentence: the verdict and why.

5. 5. Validate before you serve or deploy

   validate prints diagnostics and exits non-zero on errors; info lists the tools, channels and other pieces the SDK discovered. serve refuses to start when there are errors.

   agent-sdk validate --dir .
   agent-sdk info --dir .

The project layout

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

bot/agent.ts holds defineAgent config such as the model. bot/tools/ holds one typed tool per file, named after the file. bot/skills/ holds procedures loaded on demand. bot/mcp-connections/ adds MCP servers for the model. bot/subagents/, bot/channels/, bot/hooks/, bot/schedules/ and bot/reminders/ cover child agents, HTTP routes, observe-only event subscribers and timed runs. bot/lib/ is for shared code and is never scanned for tools.

my-agent/
├── package.json
├── bot/
│   ├── agent.ts
│   ├── instructions.md
│   ├── tools/
│   ├── skills/
│   ├── mcp-connections/
│   ├── subagents/
│   ├── channels/
│   └── hooks/
└── evals/
    ├── evals.config.ts
    └── readiness.eval.ts

Tools: typed actions the model can call

A tool needs a description written for the model, an optional input schema and the code that runs. With a Zod schema the SDK validates the input and infers its type. By default a tool runs on the serving host with access to process.env and bot/lib/.

You can call a tool without a model turn, which Cursor’s quickstart uses to check a tool’s output before involving the model: agent-sdk tool call inspect_pr --dir . --input '{"prUrl":"..."}'.

import { defineTool } from "@grok/agent-sdk/tools";
import { z } from "zod";

export default defineTool({
  description: "Inspect a pull request before approval.",
  inputSchema: z.object({ prUrl: z.string().url() }),
  async execute({ prUrl }) {
    return { prUrl };
  },
});

Where the agent listens: channels and schedules

A file in bot/channels/ connects an outside surface and mounts its routes under /v1/channels/. Cursor’s docs have guides for GitHub, GitLab, Bitbucket, Slack, PagerDuty and webhooks; the quickstart uses githubChannel to review pull requests when they are opened, reopened or marked ready for review.

On Cursor hosting, custom routes answer 202 Accepted right away and then run the handler, so results go out through events, a callback or a tool, not the HTTP response.

A Markdown file in bot/schedules/ with cron: frontmatter runs as a task on that schedule. Crons are 5-field and in UTC. A hosted schedule handler must finish within 26 minutes, and a deploy can hold at most 64 schedules.

---
cron: "0 9 * * 1-5"
---

Pull open incidents and post a summary to the metrics endpoint.

Evals: lock in behavior

An eval sends a fixed input to the real agent and checks which tools ran and what the answer says. Cursor’s example passes only if the agent calls inspect_pr and does not call approve_pr.

Evals run real tools, so guard any writes first. Every eval project needs evals/evals.config.ts. In CI, Cursor’s docs run the smoke tag on pull requests and the full suite on a schedule, with JUnit output.

agent-sdk eval --dir . --tag smoke
agent-sdk eval --dir . --json --no-stream --junit reports/evals.xml

Deploying

agent-sdk deploy builds a pushed Git ref on Cursor-managed hosting and prints the agent’s URL; uncommitted changes don’t ship. You manage deployed agents in the Deployed Agents dashboard. You can also self-host with agent-sdk serve.

Declare outbound hosts and secret names in bot/agent.ts under hosting, then set values with agent-sdk secret set. Commit secret names, never values.

Managed hosting works with Privacy Mode; with the legacy Privacy Mode setting, deploy, hosted sessions and eval runs refuse to run.

agent-sdk validate
agent-sdk deploy

Agent SDK, Automations or Grok Bot?

Cursor’s own comparison: Cursor Automations suit a prompt, model and trigger set in the dashboard. Grok Bot suits configuring and talking to an agent without writing code. The Agent SDK suits code around model judgment that your team versions, reviews, tests and improves, on Cursor hosting or your own infrastructure.

Tips

• Test each tool with agent-sdk tool call before letting the model use it.
• Put the decision rule in instructions.md, such as “call inspect_pr before judging a PR”, so an eval can check it.
• Keep shared helpers in bot/lib/, where the SDK does not look for tools.
• Ask for a human before any tool that posts to GitHub or Slack while you are still testing; evals run real tools.

Next steps

Sources

• https://cursor.com/docs/agent-sdk · checked 2026-10-27
• https://cursor.com/docs/agent-sdk/quickstart · checked 2026-10-27
• https://cursor.com/docs/agent-sdk/reference/project-layout · checked 2026-10-27
• https://cursor.com/docs/agent-sdk/evals · checked 2026-10-27
• https://cursor.com/docs/agent-sdk/deployment · checked 2026-10-27
• https://cursor.com/docs/agent-sdk/reference/schedules · checked 2026-10-27
• https://cursor.com/docs/agent-sdk/changelog · checked 2026-10-27