From Agent Folder to Shippable Agent: Five Checkpoints
An Agent SDK agent is a folder of instructions, tools, skills, and channels. This walkthrough follows five checkpoints from local validation to gateway-gated tool calls and replayable evals.
CursorAnnouncement
The Agent SDK is now generally available, letting developers define an agent as a folder of code using an instructions.md file as the prompt. The project structure includes tools/ for typed functions, skills/ for loadable procedures, mcp-connections/ for MCP server tools, and channels/ for message handling. The CLI provides commands for initialization, local development with a playground, validation, and deployment to Cursor or self-managed infrastructure. When deployed, secrets and integrations are managed from a dashboard while logs, evals, and the playground remain available, and agents can receive and respond to messages through GitHub, GitLab, Bitbucket, Slack, webhooks, and cron schedules with session persistence. Evals allow asserting on tool calls and replies, and the agent-sdk github replay command converts real pull requests into signed fixtures for offline testing.
Agents are defined as code projects with a standard structure: instructions.md for the prompt, tools/ for callable functions, skills/ for on-demand procedures, and channels/ for message routing.
The SDK supports deployment both to Cursor’s infrastructure and to self-managed environments, with a dashboard for managing secrets and integrations.
Evals allow testing agents by sending fixed messages and asserting on tool calls and responses; the agent-sdk github replay command enables testing GitHub-driven bots using actual pull request payloads.
Run npx @cursor/agent-sdk init ./my-bot to scaffold the project, then agent-sdk dev to start the bot locally with a playground. You can pass --template to start from a predefined agent like a security reviewer or PR autofixer.
Use agent-sdk github replay <pr-url> with --dry-run and --fixtures-dir to save signed webhook payloads as eval fixtures. This allows testing the bot's reactions to real pull request events offline.
Agents support GitHub, GitLab, and Bitbucket events (pull requests, comments, CI), Slack mentions and DMs, webhooks from any provider, and cron schedules. GitHub events pull through your Cursor account without needing a public webhook URL.
Summaries are generated from the original by a language model. Check the original before relying on it.
See the idea
An Agent SDK agent is a folder of instructions, tools, skills, and channels. This walkthrough follows five checkpoints from local validation to gateway-gated tool calls and replayable evals.
Keep reading
The Good Stuff
Paid picks we use ourselves. Links carry a referral code — a subscription through one earns us a commission at no extra cost to you.
One useful email. Unsubscribe anytime.