Cursor Python SDK: Composer Agents Scriptable from Python

Cursor Expands Its SDK to Python: Composer 2.5 Agents Now Scriptable from Python

Cursor launched its Python SDK in public beta on May 23, 2026, marking a significant expansion of its developer platform. The SDK brings the same Composer 2.5 agent runtime that powers the Cursor IDE, CLI, and web application directly into Python codebases — allowing developers to integrate AI-powered coding agents into their own scripts, automation pipelines, and backend services.

The Python SDK follows the TypeScript SDK released in late April 2026, and is its functional peer: both expose the same underlying agent harness but through their respective native language idioms. Where the TypeScript SDK targets frontend tooling, Node.js services, and CI systems already running JavaScript, the Python SDK opens the door to data science workflows, FastAPI backends, asyncio-based services, and the broad Python automation ecosystem.

Two Runtimes, One Interface

The SDK (uv pip install cursor-sdk) provides a unified interface to create and interact with Composer 2.5 agents across two execution environments:

Local runtime: Executes directly against files on disk. Ideal for development scripts, automated code review, and any workflow that doesn't require cloud isolation. The agent runs in-process on the developer's machine, with access to the local filesystem and .cursor/ configuration.

Cloud runtime (Cursor-hosted or self-hosted): Runs in isolated virtual machines with repositories pre-cloned, enabling parallel agent fleet execution, automatic PR creation, and full lifecycle management without a local environment. Cloud agents are identified by a bc- prefix in their agent ID and can be resumed across process restarts.

from cursor_sdk import Agent, CloudAgentOptions, CloudRepository

with Agent.create(
    model="composer-2.5",
    cloud=CloudAgentOptions(
        repos=[CloudRepository(url="https://github.com/your-org/your-repo")],
        auto_create_pr=True,
    ),
) as agent:
    print(agent.send("Add structured logging to the auth middleware").text())

The Full Cursor Harness, in Python

Cursor emphasized that the SDK exposes the complete agent harness — not a stripped-down version. This means Python agents get codebase indexing, semantic search, MCP server support, subagent orchestration, and .cursor/ hook integration. Developers can define named subagents inline or via .cursor/agents/*.md files, inject MCP servers via HTTP or stdio transports, and receive typed streaming events throughout execution.

MCP servers can be attached inline at agent creation time, overriding file-based configuration:

from cursor_sdk import Agent, StdioMcpServerConfig, LocalAgentOptions

agent = Agent.create(
    model="composer-2.5",
    local=LocalAgentOptions(cwd="."),
    mcp_servers={
        "filesystem": StdioMcpServerConfig(
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem", "."],
        ),
    },
)

Sync and Async Clients

The SDK ships with a fully mirrored asynchronous client (AsyncAgent, AsyncClient), making it a natural fit for asyncio-based services. Streaming runs yield discriminated union message types — assistant, thinking, tool_call, status, and more — enabling fine-grained observability into what the agent is doing step by step.

For cases where streaming isn't needed, run.text() blocks and returns the final output. For lower-level control, run.messages() streams individual message frames.

Conversation Modes and Model Customization

Agents can operate in "plan" mode (exploring and designing before implementing) or "agent" mode (implementing directly). Model selection supports per-run overrides that are sticky for subsequent sends. The ModelSelection class allows passing model-specific parameters like reasoning effort:

from cursor_sdk import ModelSelection, ModelParameterValue, SendOptions

run = agent.send(
    "Refactor the auth module",
    SendOptions(model=ModelSelection(
        id="composer-2.5",
        params=[ModelParameterValue(id="thinking", value="high")],
    ))
)

Agent Resumption and Lifecycle

Cursor's SDK supports durable agent sessions. Cloud agents can be resumed by ID across process restarts, enabling multi-session long-running workflows. Agent lifecycle management includes archive, unarchive, and delete operations, with archive doing a soft-delete that preserves the transcript.

Pricing and Launch Promotion

SDK runs follow the same pricing, request pools, and Privacy Mode rules as runs from the IDE and Cloud Agents. API keys are generated through the Cursor Dashboard Integrations page. At launch during Memorial Day weekend 2026, Cursor offered 90% off Composer usage through the SDK.

Known Limitations at Public Beta Launch

Cursor has been transparent about limitations in the initial release:

• Tool-call payloads lack strong typing and the schema is not stable
• Inline MCP servers are not persisted across agent resumption
• Artifact download is not implemented for local agents
• Hooks are file-based only — there is no programmatic hook callback
• There is no global async default client; AsyncClient must be instantiated explicitly