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
- HTML documentation (Sphinx):
https://aidmet.github.io/cursor-agent-api/ - Package on PyPI: cursor-agent-sdk
- Cursor Cloud Agents API (endpoints) — cursor.com/docs
- Cursor APIs overview — cursor.com/docs/api
Unofficial package; not maintained by Cursor.
License
MIT
Metadata
Release files for cursor-agent-sdk 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cursor_agent_sdk-0.1.2.tar.gz | 6.6 kB | Without provenance | Details for cursor_agent_sdk-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cursor_agent_sdk-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for cursor_agent_sdk-0.1.2-py3-none-any.whl |
Total release size: 13.6 kB
Release files / cursor_agent_sdk-0.1.2.tar.gz
| Download URL | cursor_agent_sdk-0.1.2.tar.gz |
|---|---|
| Size | 6.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3eef7bb90de6a875741b1110f209232bcfbca976d5bd42259f75f3884ddb4e36
|
|
BLAKE2b-256 checksum How to use checksums |
20b5d9b6e29cb0c20a87c97fcbc17977b17463c543d9cec31eaa567a5be4c445
|
| 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.2-py3-none-any.whl
| Download URL | cursor_agent_sdk-0.1.2-py3-none-any.whl |
|---|---|
| Size | 7.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
203c65816fa84d331aacda540326abdab47a88e4af38c5b77da39c317f87c80b
|
|
BLAKE2b-256 checksum How to use checksums |
1e024af07264c846b1c1cd2918c3faaeb844b82b04ef99608644d1a0b2921c07
|
| 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.2
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.