{"slug": "how-cursor-s-agent-sdk-works", "title": "How Cursor's Agent SDK Works", "summary": "Cursor released its Agent SDK in October, a framework for building agents as code that Cursor says it uses to build its own bots, including Bugbot, its pull request reviewer. Agents are written as projects — a Markdown prompt, TypeScript tool files, and event triggers such as a new pull request, a Slack mention, or a schedule — then deployed to Cursor's hosting or run on the user's own server, with every model call routed through Cursor's model list and account. The Agent SDK builds on the Cursor SDK released in April, which lets code drive Cursor's coding agent directly; Cursor staff said in October that the custom system prompt option is not yet open to outside accounts.", "body_md": "[All guides](https://www.omnara.com/guides)\n\n# How Cursor's Agent SDK Works\n\nAgents as code, on Cursor's models\n\n## On this page\n\nCursor's [Agent SDK](https://cursor.com/blog/agent-sdk) is a framework for building agents as code, released in October. Cursor says it's what they use to build their own bots, like Bugbot, their pull request reviewer. You write an agent as a project: a prompt in Markdown, tools as TypeScript files, and the events that wake it up, like a new pull request, a Slack mention, or a schedule. Then you deploy it to Cursor's hosting or run it on your own server.\n\nThe Agent SDK is built on the Cursor SDK, an earlier library for running Cursor's coding agent from your own code. The Agent SDK runs an agent as its own service that waits for events. The Cursor SDK lets your code drive Cursor's coding agent directly. In both, every model call goes through Cursor, so you're tied to Cursor's model list, your Cursor account, and Cursor's service even when the agent runs on your own machines.\n\n## The Short Version\n\n## What It's Good At\n\nFor a team that's fine with only Cursor's models and a Cursor account, the Agent SDK's appeal is how little setup it takes to build an agent that reacts to events, from a new pull request to a Slack message to a nightly schedule. Each agent is a project laid out like this:\n\nIts [GitHub connection](https://cursor.com/docs/agent-sdk/guides/github) reuses the one on your Cursor account, so there's no webhook URL to expose, no GitHub App to register, and no token to manage. You decide in code which events start a conversation, and every event on the same pull request lands in the same conversation, so the bot remembers the PR when someone comments on it a day later. Slack, GitLab, Bitbucket, other webhooks, and schedules work the same way, and your own app can start a conversation through the agent's [HTTP API](https://cursor.com/docs/agent-sdk/reference/http-api).\n\nTools are TypeScript functions that run in the same server as the agent, so they can call your APIs directly, and you can run any tool yourself, without the model, to test it. Alongside your tools, the agent gets Cursor's coding tools for reading, searching, and editing files and running shell commands. For a bigger coding job, it can hand the work to one of Cursor's cloud agents.\n\nIt also comes with evals, which most agent frameworks leave to you. An [eval](https://cursor.com/docs/agent-sdk/evals) sends the agent a fixed message and checks what it did: which tools it called, and whether the answer looks right. You can also replay a real pull request into your local agent to test it against something that actually happened.\n\n## The Cursor SDK\n\nYou don't need the Agent SDK to run Cursor's agent from code. The [Cursor SDK](https://cursor.com/blog/typescript-sdk), released in April, lets your code start Cursor's coding agent, give it a task, and read what it did. The agent runs either on your machine against local files, or on a Cursor cloud machine that clones your repo and can open a pull request when it's done:\n\nBetween Cursor's two SDKs, this one fits when your own code is in charge, like a CI job that fixes failing tests. The Agent SDK fits when the agent is its own service, waiting for events.\n\nEach Cursor SDK agent works on one task at a time. And replacing the system prompt or adding your own tools only works when the agent runs on your machine, not in Cursor's cloud. Cursor staff [said in October](https://forum.cursor.com/t/175262) that the custom system prompt option isn't open to outside accounts yet.\n\nWe compare Cursor's Cloud Agents API with other cloud agent APIs in [Cloud Agent APIs Compared](https://www.omnara.com/guides/cloud-agent-apis), and cover running Cursor's agents on your own machines in [Self-Hosted Managed Agents](https://www.omnara.com/guides/self-hosted-managed-agents).\n\n## Every Model Call Goes Through Cursor\n\nWhichever SDK you use, and wherever the agent runs, you're tied to Cursor's model list, your Cursor account, and Cursor's service. From Cursor's docs: [\"All inference goes through Cursor's hosted models in both modes.\"](https://cursor.com/docs/sdk/typescript) Self-hosting the Agent SDK moves the server, the tools, and the conversation history onto your machines, but every model turn still needs a Cursor API key and Cursor's service.\n\nYou pick models from Cursor's list, not your own endpoints or local models. The list is broad: Cursor's own models plus Claude, GPT, and Gemini. The Agent SDK defaults to Grok, which shows up across the docs because Cursor is now [sold as part of The X Subscription](https://cursor.com/docs/models-and-pricing), alongside Grok and X.\n\nNeither SDK is open source. The Agent SDK package's README calls it open source, but [its license](https://www.npmjs.com/package/@grok/agent-sdk) says \"All rights reserved,\" and there's no public source code. The Cursor SDK is proprietary too.\n\n## Usage Is Billed to Your Cursor Plan\n\nBoth SDKs are free to install, and Cursor lists no separate fee for hosting your agent or for its cloud machines. Model usage counts against your [Cursor plan](https://cursor.com/docs/models-and-pricing): included usage first, then each model's rate. Every conversation reports its estimated cost. Handing work to Cursor's cloud agents needs a plan that includes them, which on Cursor's current plans means Premium or higher.\n\n## Serving Many Users Means Enterprise\n\nBuilding a product for your own customers is a [supported use](https://forum.cursor.com/t/169111), according to Cursor staff. Running it for many users from one account, without a Cursor key per user, means [service accounts](https://cursor.com/docs/account/enterprise/service-accounts), which only come with Cursor's Enterprise plan. Cursor's [terms](https://cursor.com/terms-of-service) also bar reselling the service, and they don't say how that applies to a product built on the SDK.\n\n## Changing a Hosted Agent Means a Redeploy\n\nThe prompt, tools, and model are files in the project, so on Cursor's hosting, changing any of them means pushing and deploying again. Conversations [carry over the redeploy](https://cursor.com/docs/agent-sdk/deployment), so nothing in progress is lost. Secrets are the exception: a new secret value applies to the agent's next task without a deploy.\n\nA message sent through the agent's API in the middle of a turn interrupts that turn and runs instead. On Slack, messages that arrive mid-turn get folded into the work instead of interrupting it.\n\n## Things to Know Before You Build on It\n\nWhen you run the Agent SDK yourself, the sandbox is [off by default](https://cursor.com/docs/agent-sdk/reference/agent-config). Shell commands run without approval and can see everything the server can, including its credentials. Turn the sandbox on before the agent reads anything untrusted, like pull request diffs or chat messages.\n\nInstall `@grok/agent-sdk`, the name in [Cursor's docs](https://cursor.com/docs/agent-sdk). The package was renamed after launch, and Cursor's launch post and changelog use a name that doesn't exist on npm.\n\nAccounts on Cursor's old privacy mode [can't deploy](https://cursor.com/docs/agent-sdk/deployment) to Cursor's hosting at all.\n\n## Agent SDK vs Omnara\n\nBoth define an agent as instructions, tools, and the events that start it, and run it as a service. The difference is what you depend on.\n\nThe Agent SDK is a quick way to build a bot for your own team if you already pay for Cursor. The GitHub connection reuses the one on your Cursor account, Slack and schedules are built in, evals with pull request replay come with it, and the agent gets Cursor's tools for reading and editing code. In exchange, every model call goes through Cursor's models and your Cursor account, the SDK is proprietary, and serving many users from one account takes Enterprise service accounts.\n\n[Omnara](https://github.com/omnara-ai/omnara) has none of those dependencies, which matters once the agent is part of your product. It's open source under Apache 2.0, and you can self-host all of it, including the agent loop and the conversation history, with model calls going straight from your servers to the provider you choose. You choose the models, from OpenAI, Anthropic, OpenRouter, or any compatible endpoint, on your own keys. You change a running agent's model, tools, or instructions through the API in the middle of a conversation, without a redeploy. The platform is free, with no per-seat fees, and it's built for products that serve your own users.\n\n## FAQ\n\n### Is Cursor's Agent SDK open source?\n\nNo. Its README calls it open source, but the license says \"All rights reserved,\" and the source isn't public.\n\n### Can I self-host the Agent SDK?\n\nYou can run the server yourself, which keeps the tools and conversation history on your infrastructure. Every model call still goes through Cursor with a Cursor API key.\n\n### How much does the Cursor SDK cost?\n\nIt's free to install. Model usage counts against your Cursor plan, with no separate fee for Cursor's cloud machines. Cloud runs need a plan that includes cloud agents, which on Cursor's current plans means Premium or higher.\n\n### What models does the Agent SDK use?\n\nIt defaults to Grok, and you can pick other models from Cursor's list, including Claude, GPT, and Gemini. You can't use your own endpoint or a local model.", "url": "https://wpnews.pro/news/how-cursor-s-agent-sdk-works", "canonical_source": "https://www.omnara.com/guides/cursor-agent-sdk", "published_at": "2026-10-28 00:00:00+00:00", "updated_at": "2026-11-05 19:21:17.967776+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Cursor", "Agent SDK", "Cursor SDK", "Bugbot", "GitHub", "Slack", "GitLab", "Bitbucket"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-cursor-s-agent-sdk-works", "markdown": "https://wpnews.pro/news/how-cursor-s-agent-sdk-works.md", "text": "https://wpnews.pro/news/how-cursor-s-agent-sdk-works.txt", "jsonld": "https://wpnews.pro/news/how-cursor-s-agent-sdk-works.jsonld"}}