# Agent SDK

Agent SDK lets you define, test, and deploy agents
as code. It uses the Cursor SDK harness that powers Bugbot, Security Review,
Approval Bot, and Rollouts.

An Agent SDK project is a folder of Markdown and TypeScript. Combine deterministic
code with model judgment, then make the bot or agent available in source
control, Slack, issue trackers, and Cursor.

After you deploy an agent, open [Deployed Agents](https://cursor.com/dashboard/deployed-agents) to see it and manage it.

## Why use it

- **Bots and agents live in your repo.** Instructions, tools, and evals are
  files you review, version, and ship like the rest of your code.

- **Cursor runs the loop.** You write the instructions and tools.
  Your agent gets Cursor's models, tool calling, skills, MCP, and
  subagents. Each turn runs on your host.

- **Use it where you work.** Trigger a project from source-control events,
  Slack threads, custom webhooks, or schedules.

- **Test normal TypeScript.** Add evals and unit tests without a separate
  configuration language.

- **Choose where it runs.** Deploy to Cursor-managed hosting or run the
  process on your infrastructure.

## When to use Agent SDK

| | Cursor Automations | Grok Bot | Agent SDK |
| --- | --- | --- | --- |
| **Use for** | Repeatable jobs driven by a prompt and a trigger | Interactive agents that work with you in Cursor | Agents that need custom code, integrations, tests, or deployment choices |
| **You define** | A prompt, model, and trigger in the dashboard | Instructions, skills, and connected tools in the app | A versioned Markdown and TypeScript project |
| **Where it runs** | Cursor-managed | Cursor-managed | Cursor-managed hosting or your infrastructure |
| **Choose it when** | The job fits a schedule or event trigger | You want an agent you can configure and talk to without creating a software project | You want deterministic code around model judgment and a project your team can review and test |

## Architecture

Define the project in source control. Run execution, inference, and
sandboxing on Cursor infrastructure or on your own host.

![Agent SDK architecture: you bring the agent as code, and the platform provides triggers, runtime, integrations, and operations](/docs/architecture.svg)

## Get started

Install `@grok/agent-sdk`, then start with `agent-sdk init` and `agent-sdk dev`.
The package was `@cursor/bdk` before.

```text
npm install --global @grok/agent-sdk
agent-sdk init ./my-bot
cd my-bot
agent-sdk dev
```

Open the project in Cursor. Agent SDK projects use `bot/`.

```text
my-bot/
├── .gitignore
├── AGENTS.md
├── package.json
├── tsconfig.json
├── bot/
│   ├── agent.ts               # model and local harness config
│   ├── instructions.md        # the system prompt
│   ├── tools/
│   │   └── echo.ts            # demo tool
│   ├── hooks/
│   │   └── memory.ts          # shared memory journal
│   ├── channels/
│   ├── lib/                   # shared code, never discovered
│   ├── mcp-connections/
│   ├── sandbox/
│   │   └── workspace/
│   ├── schedules/
│   ├── skills/
│   └── subagents/
└── evals/
    ├── evals.config.ts
    └── smoke.eval.ts
```

Describe your bot or agent in Cursor, or edit the files yourself.

## Next steps

- [Build your first PR reviewer](/docs/quickstart.md): a working GitHub
  reviewer, one step at a time.

- Start from a template:
  [security reviewer](/docs/templates/security-reviewer.md),
  [Thermo review](/docs/templates/thermo-review.md),
  [Thermo quality review](/docs/templates/thermo-quality-review.md),
  [owners-policy approver](/docs/templates/agentic-owners.md),
  [issue triager](/docs/templates/triage.md).

- [Convert a Cursor Automation](/docs/guides/convert-automation.md): export
  an Automation from the dashboard into a project you own.

- [Build agents with agents](/docs/building-with-agents.md): hand the build
  to a coding agent with the package's bundled skills.

- [Project layout](/docs/reference/project-layout.md) and
  [CLI](/docs/reference/cli.md): every folder and every command.

- [Access](/docs/reference/access.md): Viewer, Editor, and Owner on a deployed bot.