The Agent Becomes a Folder: Cursor's Agent SDK Goes Generally Available, and Prompts Finally Get Version History

On October 20, 2026, Cursor took its Agent SDK to general availability (GA). Its ambition, in one sentence: an agent stops being a prompt inside a chat box and becomes a folder you can put in a repository, review with diffs, and pin down with tests. The prompt lives in instructions.md, each tool is a typed file, skills load on demand, channels are configuration, and deployment is one command. The significance is not the feature list but the change in working method: for the first time, an agent's behavior has a version history — and therefore something that can be held accountable, rolled back, and reproduced.

This piece first states what the official changelog confirms, then offers three judgments worth taking seriously: why the "folder" shape matters more than the "prompt box," why evals are the part of the SDK most worth copying, and how to choose between self-hosting and Cursor hosting. Where the official announcement gives no numbers or prices, this article does not fill them in.

First, what exactly went GA

According to Cursor's official changelog entry for the Agent SDK, the SDK lets developers define an agent as a folder of code, test it with evals, and deploy it to Cursor or their own infrastructure. The starting commands are npx @cursor/agent-sdk init ./my-bot, then agent-sdk dev to run the bot locally in a playground. Templates include a security reviewer, an owners-policy approver, a PR autofixer, and Linear / Jira triagers — and those four templates are themselves a positioning statement: the SDK's first targets are not "chatbots" but working agents attached to nodes in the development workflow.

The folder structure is worth reading item by item. instructions.md is the prompt — the agent's "constitution"; 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; channels/ defines where the bot receives and answers messages. agent-sdk validate checks the project, and agent-sdk info prints what it discovered. The practical benefit of this layering: changing the prompt is one diff, changing a tool is one interface change, adding a skill is one on-demand-loading decision — not a few clicks in some admin console that nobody can reconstruct afterwards.

Deployment is likewise compressed into one command. agent-sdk deploy, run from the project directory, builds the agent, gives it a URL, and starts it on Cursor's infrastructure; secrets and integrations are managed from the dashboard, while the same logs, evals, and playground available locally remain available. In other words, local debugging and production runs are no longer two different behaviors: the session record you see in the local playground is kept online too. For solo developers, that lowers the bar from "demo" to "on duty"; for teams, it brings the agent inside the existing code-review process.

Channels: where the agent wakes up

The SDK's channel list is wider than many people expect. 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. One detail worth noting: GitHub events flow through your Cursor account, so no public webhook URL is required. That is friendly to small teams — no need to stand up a public endpoint just to connect a PR bot, and no edge cases of signature verification to babysit.

Each conversation keeps its own session and a complete record of every message and tool call. Follow-ups on a pull request or Slack thread resume the same session. That sentence matters a great deal in engineering terms: it means the agent's "memory" is not a marketing phrase but an auditable record. When the agent does something wrong, the first question you can answer is no longer "why did it think that" but "at which step did it call which tool, with what arguments."

But the wider the channels, the earlier the permission boundary must be drawn. An agent that can reply to PR comments could, under a misconfiguration, change the wrong thing; an agent that can receive Slack DMs could, in principle, be steered by a carefully crafted message. This article's advice: start read-only — review, triage, label — run it for two weeks, read the logs, and only then gradually widen write access. The SDK gives you evals and session records precisely to support that kind of gradual widening.

The part most worth copying: evals

If you steal one practice from the Agent SDK, steal evals. The definition is plain: send the bot a fixed message, then assert on what it did — which tools ran, with what input, and the shape of the reply. Run agent-sdk eval locally or in CI. Going further, agent-sdk github replay <pr-url> turns a real pull request into signed webhook payloads and sends them to the bot; add --dry-run --fixtures-dir fixtures/ to save the payloads as eval fixtures.

Why does this matter more than "writing a better prompt"? Because a prompt's effect cannot regress. Change one sentence, and whether the last ten cases got better or worse is guesswork without evals. Evals turn agent behavior into tests that can fail: the wrong tool call fails the test; a changed reply format fails the test; an action that should never have fired fails the test. When a team reviews an agent, the object of review also changes — from "does this prompt read well" to "which scenarios we most fear does this eval set cover."

When writing your first eval, do not start from "I hope it answers correctly." Start from "what I most fear it will do wrong." If the agent can send email or change records, first write an assertion: on receiving an unrelated message, neither action may fire. Only then the happy path: when the security-reviewer template receives a diff containing sensitive information, which tools should it call, in what order. Once you have around ten evals, every prompt change has a brake.

There is also an organizational implication. Agent knowledge used to live in one person's chat history or admin console; when the person left, the knowledge scattered. Now instructions.md goes into the repository and evals go into CI, so a newcomer inherits a behavior specification with tests. Cursor's changelog does not say this explicitly, but it is the real dividend of the folder shape: the agent turns from personal craft into a team asset.

Three easy traps

The first trap is writing instructions.md as prose. The longer the prompt, the easier it is for the model to lose key constraints in a long context. A better shape: the first three lines state identity, forbidden zones, and the definition of success, followed by sections for "what input arrives, in what order to call which tools, which fields the output must contain, and when to stop and ask for help." Each constraint should appear exactly once; repeated phrasing is not emphasis but raw material for contradictions the model must resolve. validate can check structure, but it cannot check a prompt for self-contradiction — only a human reading can.

The second trap is losing control of tool granularity. Each file in tools/ is one action. Too coarse, and evals cannot assert details; too fine, and one task needs dozens of tool calls, widening the failure surface instead. A usable rule of thumb: one tool does one thing that can be named in business terms — "label a PR" rather than "handle a PR," "check ticket status" rather than "query Jira." The tool's name is itself the model's operating manual; a vague name guarantees vague calls.

The third trap is treating evals as one-off acceptance. Their value is in regression: the prompt changed, the model changed, a tool was added — the same eval set must be re-run. Put evals in the PR's required checks, on equal footing with unit tests; and give evals themselves an expiry mechanism — when the business process changes, stale assertions must be updated promptly, or the team will sooner or later start ignoring a sea of red tests, which is exactly how an agent slips out of control.

Self-host or Cursor-host: how to choose

The official options are both: deploy to Cursor, or to your own infrastructure. You do not need to agonize over "which is more advanced"; three questions suffice. First, can the data leave your own boundary? If the agent must read internal repositories and internal tickets, compliance requirements may rule out hosting directly. Second, who carries the on-call cost? Self-hosting means you own availability, secret rotation, and log retention; hosting means handing that to Cursor, but accepting its runtime and pricing rules. Third, how deep is the channel dependency? If the main channels are GitHub and Slack, hosted pass-through saves effort; if the main channel is internal webhooks, self-hosting's network position may fit better.

For most vibe projects, a pragmatic sequence is: start in the local playground, pick the template closest to your own process (say, the PR autofixer or a triager), write three to five evals, run them against real PRs for two weeks; once behavior is stable and logs are readable, decide on hosting. Do not connect the agent to all PRs or all Slack channels on day one — the more complete the SDK's capability, the more important gradual rollout becomes.

One more caution: the changelog publishes no pricing or usage details, and this article does not speculate. When estimating cost, look at actual call volume once a template is running, then check Cursor's pricing page at that time; do not assume "GA" means free or cheap.

What it changes, and what it does not

The Agent SDK changes the engineering shape of agents: from a prompt into a project that can be reviewed, tested, and deployed. It does not change who bears judgment. Evals can prove an agent performed a fixed action on fixed input, but cannot prove it will always do right on unseen input; session records help you reconstruct afterwards, but cannot draw permission boundaries for you in advance. Making an agent a folder only makes "managing it well" possible, not automatic.

Seen in the October 2026 tooling landscape, the signal is also clear: editor vendors are turning agents from "a feature inside the editor" into "infrastructure that can be embedded in other people's products." Anthropic has its own Agent SDK, and Cursor now has one too. Before picking a side, developers should check one thing first: is the agent you write locked into one vendor's channels and runtime? The folder shape itself is open, but the concrete implementations of tools, channels, and deployment targets still need to be checked item by item for portability.

Finally, a minimal getting-started checklist. First, init a template project and read through the division of labor between instructions.md and tools/. Second, write one "most feared mistake" eval and watch it go red, then green, in CI. Third, use github replay to replay a real PR from last week and compare the tool calls against the session record. Fourth, run read-only for two weeks before discussing write permissions. After those four steps, your judgment of the Agent SDK will come from your own logs, not from the changelog's adjectives.

How this differs from what the site has already published

The site has previously published news and guides about Claude Code, Codex, and other agent tools, but this piece is about something else: on October 20, 2026, Cursor productized the agent itself as a deployable code project, with the emphasis on folder structure, evals, and channel deployment — not on a model's capability or on tricks for a single conversation. Read it as a new node in "agent engineering," not as yet another article about prompting agents better.