Quickstart

Install

Install from PyPI (recommended):

pip install cursor-agent-sdk

To work on the SDK from a git clone, use an editable install:

pip install -e .

Python 3.10+ is required.

Authentication

Create an API key in the Cursor Dashboard under Cloud Agents.

The API expects Basic authentication: username = API key, password empty (same as curl -u 'YOUR_KEY': ...).

Set an environment variable for local runs:

set CURSOR_API_KEY=your-key-here

Minimal sync example

import os
from cursor_agent import SyncClient

with SyncClient(os.environ["CURSOR_API_KEY"]) as client:
    agent = client.new_agent(
        repo="https://github.com/octocat/Hello-World",
        ref="main",
    )
    out = agent.create("Add a one-line note to README.md.")
    print(out)
    agent.follow_up("Keep the tone neutral.")

Minimal async example

import asyncio
import os
from cursor_agent import AsyncClient

async def main():
    async with AsyncClient(os.environ["CURSOR_API_KEY"]) as client:
        agent = client.new_agent(
            repo="https://github.com/octocat/Hello-World",
            ref="main",
        )
        await agent.create("Update the README.")
        await agent.follow_up("Be concise.")

asyncio.run(main())

For contributors: build these docs locally

If you are editing the Sphinx sources in the repository, regenerate HTML like this (from the repo root):

cd docs
make.bat html

On Linux or macOS, use make html instead of make.bat html. Then open _build/html/index.html in a browser.