Skip to main content

cursor-agent-sdk

Thin, typed Python bindings for the Cursor Cloud Agents API—drive cloud coding agents from CI, bots, or scripts instead of clicking through the dashboard. Built on httpx; sync by default, async when you already use asyncio.

Python 3.10+.


Install

Install from PyPI (recommended):

pip install cursor-agent-sdk

From source (contributors or a git checkout):

git clone <repository-url> && cd cursor-agent-api && pip install -e .

Auth

Keys live in the Cursor Dashboard → Cloud Agents. The API uses Basic auth: username = API key, password empty (curl -u 'KEY': …). Overview.


30-second run

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")
    print(agent.create("Add a one-line note to README.md."))

create starts the remote agent; follow_up("…") sends more prompts on the same run.


Model: client → agent → API

One client (connection + credentials). One agent handle per repo/PR you care about. Methods map 1:1 to https://api.cursor.com/v0.

flowchart TB
    subgraph sdk ["cursor-agent-sdk"]
        C["SyncClient / AsyncClient"]
        A["Agent / AsyncAgent"]
    end
    API[("Cursor Cloud Agents API\napi.cursor.com/v0")]
    C -->|new_agent| A
    A -->|create, follow_up, refresh| API
    C -->|me, list_agents, …| API

Opinions: Prefer Agent.create / follow_up over raw launch_agent / followup—they keep ids and sources straight. Use SyncClient unless your app is already async; then AsyncClient. This repo is not official Cursor software.


Example (sync)

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 CONTRIBUTING.md with PR guidelines.",
        target={"autoCreatePr": True},
    )
    print(out.get("id"), out.get("status"))
    agent.follow_up("Ask for a minimal repro in issues.")
    print(agent.refresh().get("status"))

Resume later: agent.attach("bc_…") then follow_up / refresh only.


Async

Same API; await client and AsyncAgent methods.

async def run():
    async with AsyncClient(os.environ["CURSOR_API_KEY"]) as client:
        a = client.new_agent(repo="https://github.com/octocat/Hello-World", ref="main")
        await a.create("Update README.")
        await a.follow_up("Keep it short.")

Lifecycle

Call Role
new_agent(repo=…, ref=…) or new_agent(pr_url=…) Bind GitHub source.
create(prompt, …) Once per handle — POST /v0/agents, stores id.
follow_up(prompt, …) Same cloud agent — POST /v0/agents/{id}/followup.

First create only: model, target, webhook, images. Follow-ups: prompt and images only.

PR instead of branch:

agent = client.new_agent(pr_url="https://github.com/octocat/Hello-World/pull/42")
agent.create("Small doc fixes only.")

HTTP surface

Client method Route
me GET /v0/me
list_models GET /v0/models
list_repositories GET /v0/repositories
list_agents GET /v0/agents
get_agent / get_conversation GET /v0/agents/{id}…
launch_agent POST /v0/agents
followup POST /v0/agents/{id}/followup
stop_agent / delete_agent POST / DELETE …

Advanced

Custom httpx — SyncClient.from_httpx_client(httpx.Client) / AsyncClient.from_httpx_client(httpx.AsyncClient) for proxies, retries, tracing, etc.

Errors — failed requests raise CursorAPIError with status_code and response.


Docs

Unofficial package; not maintained by Cursor.

License

MIT

Metadata

Release files for cursor-agent-sdk 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cursor-agent-sdk 0.1.1
File Size Uploaded Provenance Actions
cursor_agent_sdk-0.1.1.tar.gz 6.5 kB Without provenance Details for cursor_agent_sdk-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cursor-agent-sdk 0.1.1
File Interpreter ABI Platform Actions
cursor_agent_sdk-0.1.1-py3-none-any.whl Python 3 none any Details for cursor_agent_sdk-0.1.1-py3-none-any.whl

Total release size: 13.4 kB

Release files / cursor_agent_sdk-0.1.1.tar.gz

Download URL cursor_agent_sdk-0.1.1.tar.gz
Size 6.5 kB
Tags Source
SHA-256 checksum
How to use checksums
62d55f32255f0a7c0708b8129bcc0b541259b016829e9e1a4343f7e6a92be0e2
BLAKE2b-256 checksum
How to use checksums
ab5b899580d62a80995e5ae0239de12998c095f65a795aa4f01e36f9be791840
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Release files / cursor_agent_sdk-0.1.1-py3-none-any.whl

Download URL cursor_agent_sdk-0.1.1-py3-none-any.whl
Size 6.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3e5a08a7a6e6aaf0ccce2d1cae01f67c407d33934928f930175b679b3a29b8eb
BLAKE2b-256 checksum
How to use checksums
250b45ae5821be664606668c0ee6019ac503cbc0c249acb6efd908f7fadb5ac0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Security for cursor-agent-sdk 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page