vendor_connectors.cursor

vendor_connectors.cursor

Cursor Connector - HTTP client for Cursor Background Agent API.

This connector provides Python access to the Cursor Background Agent API for managing AI coding agents, following the patterns established in the jbcom ecosystem.

Usage: from vendor_connectors.cursor import CursorConnector

connector = CursorConnector(api_key="...")
agents = connector.list_agents()

agent = connector.launch_agent(
    prompt_text="Implement feature X",
    repository="org/repo",
    ref="main"
)

Reference: https://cursor.com/docs/cloud-agent/api/endpoints

Submodules

• vendor_connectors.cursor.tools

Package Contents

Classes

AgentState	Agent execution state.
Agent	Cursor Background Agent representation.
Repository	Repository available for Cursor agents.
ConversationMessage	Single message in agent conversation.
Conversation	Agent conversation history.
LaunchOptions	Options for launching a new agent.
CursorConnector	Cursor Background Agent API connector.

Functions

validate_agent_id	Validate an agent ID to prevent injection attacks.
validate_prompt_text	Validate prompt text.
validate_repository	Validate repository name.
validate_webhook_url	Validate webhook URL to prevent SSRF attacks.
sanitize_error	Sanitize error messages to prevent sensitive data leakage.

Data

DEFAULT_BASE_URL
DEFAULT_TIMEOUT
MAX_PROMPT_LENGTH
MAX_REPO_LENGTH
AGENT_ID_PATTERN
BLOCKED_HOSTNAME_PATTERNS

API

vendor_connectors.cursor.DEFAULT_BASE_URL

‘https://api.cursor.com/v0’

vendor_connectors.cursor.DEFAULT_TIMEOUT

60.0

vendor_connectors.cursor.MAX_PROMPT_LENGTH

100000

vendor_connectors.cursor.MAX_REPO_LENGTH

200

vendor_connectors.cursor.AGENT_ID_PATTERN

‘compile(…)’

vendor_connectors.cursor.BLOCKED_HOSTNAME_PATTERNS

None

exception vendor_connectors.cursor.CursorError(message: str, status_code: int | None = None)

Bases: Exception

Base exception for Cursor API errors.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception vendor_connectors.cursor.CursorValidationError(message: str, status_code: int | None = None)

Bases: vendor_connectors.cursor.CursorError

Validation error for Cursor API inputs.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception vendor_connectors.cursor.CursorAPIError(message: str, status_code: int | None = None)

Bases: vendor_connectors.cursor.CursorError

API error from Cursor service.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class vendor_connectors.cursor.AgentState

Bases: str, enum.Enum

Agent execution state.

Initialization

Initialize self. See help(type(self)) for accurate signature.

PENDING

‘pending’

RUNNING

‘running’

FINISHED

‘finished’

ERRORED

‘errored’

CANCELLED

‘cancelled’

class vendor_connectors.cursor.Agent

Bases: pydantic.BaseModel

Cursor Background Agent representation.

model_config

‘ConfigDict(…)’

id : str

‘Field(…)’

state : vendor_connectors.cursor.AgentState

‘Field(…)’

task : str | None

‘Field(…)’

repository : str | None

‘Field(…)’

branch : str | None

‘Field(…)’

pr_number : int | None

‘Field(…)’

pr_url : str | None

‘Field(…)’

created_at : datetime.datetime | None

‘Field(…)’

updated_at : datetime.datetime | None

‘Field(…)’

model : str | None

‘Field(…)’

error : str | None

‘Field(…)’

class vendor_connectors.cursor.Repository

Bases: pydantic.BaseModel

Repository available for Cursor agents.

model_config

‘ConfigDict(…)’

name : str

‘Field(…)’

url : str | None

‘Field(…)’

default_branch : str | None

‘Field(…)’

private : bool | None

‘Field(…)’

class vendor_connectors.cursor.ConversationMessage

Bases: pydantic.BaseModel

Single message in agent conversation.

model_config

‘ConfigDict(…)’

role : str

‘Field(…)’

content : str

‘Field(…)’

timestamp : datetime.datetime | None

‘Field(…)’

class vendor_connectors.cursor.Conversation

Bases: pydantic.BaseModel

Agent conversation history.

model_config

‘ConfigDict(…)’

agent_id : str

‘Field(…)’

messages : list[vendor_connectors.cursor.ConversationMessage]

‘Field(…)’

class vendor_connectors.cursor.LaunchOptions

Options for launching a new agent.

prompt_text : str

None

repository : str

None

ref : str | None

None

images : list[dict[str, Any]] | None

None

auto_create_pr : bool

True

branch_name : str | None

None

open_as_cursor_github_app : bool

True

skip_reviewer_request : bool

False

webhook_url : str | None

None

webhook_secret : str | None

None

vendor_connectors.cursor.validate_agent_id(agent_id: str) → None

Validate an agent ID to prevent injection attacks.

Args: agent_id: The agent ID to validate.

Raises: CursorValidationError: If the agent ID is invalid.

vendor_connectors.cursor.validate_prompt_text(text: str) → None

Validate prompt text.

Args: text: The prompt text to validate.

Raises: CursorValidationError: If the prompt is invalid.

vendor_connectors.cursor.validate_repository(repository: str) → None

Validate repository name.

Args: repository: The repository name to validate.

Raises: CursorValidationError: If the repository is invalid.

vendor_connectors.cursor.validate_webhook_url(url: str) → None

Validate webhook URL to prevent SSRF attacks.

Only allows HTTPS URLs to external hosts.

Args: url: The webhook URL to validate.

Raises: CursorValidationError: If the URL is invalid or potentially dangerous.

vendor_connectors.cursor.sanitize_error(error: Any) → str

Sanitize error messages to prevent sensitive data leakage.

Args: error: The error to sanitize.

Returns: Sanitized error message string.

class vendor_connectors.cursor.CursorConnector(api_key: str | None = None, base_url: str | None = None, timeout: float = DEFAULT_TIMEOUT, logger: lifecyclelogging.Logging | None = None, **kwargs)

Bases: vendor_connectors.base.VendorConnectorBase

Cursor Background Agent API connector.

Provides HTTP client access to Cursor’s agent management API for spawning, monitoring, and coordinating AI coding agents.

Args: api_key: Cursor API key. Defaults to CURSOR_API_KEY env var. base_url: API base URL. Only override for testing. timeout: Request timeout in seconds. Default 60s. logger: Optional logger instance. **kwargs: Additional DirectedInputsClass arguments.

Example:

connector = CursorConnector() agents = connector.list_agents() for agent in agents: … print(f”{agent.id}: {agent.state}”)

Initialization

Initialize the connector.

Args: api_key: API key (overrides environment variable) base_url: Base URL (overrides class default) timeout: HTTP timeout in seconds logger: Logger instance **kwargs: Passed to DirectedInputsClass

API_KEY_ENV

‘CURSOR_API_KEY’

BASE_URL

None

static is_available() → bool

Check if API key is available.

Returns: True if CURSOR_API_KEY is set in environment.

_request_api(endpoint: str, method: str = ‘GET’, json_body: dict[str, Any] | None = None) → dict[str, Any] | None

Make an HTTP request to the Cursor API.

Args: endpoint: API endpoint path (e.g., “/agents”). method: HTTP method. json_body: Optional JSON body for POST/PUT requests.

Returns: JSON response data or None for empty responses.

Raises: CursorAPIError: If the API returns an error.

list_agents() → list[vendor_connectors.cursor.Agent]

List all agents.

Returns: List of Agent objects.

Raises: CursorAPIError: If the API request fails.

get_agent_status(agent_id: str) → vendor_connectors.cursor.Agent

Get status of a specific agent.

Args: agent_id: The agent identifier.

Returns: Agent object with current status.

Raises: CursorValidationError: If agent_id is invalid. CursorAPIError: If the API request fails or returns empty response.

get_agent_conversation(agent_id: str) → vendor_connectors.cursor.Conversation

Get conversation history for an agent.

Args: agent_id: The agent identifier.

Returns: Conversation object with message history.

Raises: CursorValidationError: If agent_id is invalid. CursorAPIError: If the API request fails.

launch_agent(prompt_text: str, repository: str, ref: str | None = None, images: list[dict[str, Any]] | None = None, auto_create_pr: bool = True, branch_name: str | None = None, open_as_cursor_github_app: bool = True, skip_reviewer_request: bool = False, webhook_url: str | None = None, webhook_secret: str | None = None) → vendor_connectors.cursor.Agent

Launch a new agent.

Args: prompt_text: The task description for the agent. repository: Repository name (owner/repo) or URL. ref: Git ref (branch/tag/commit). Defaults to default branch. images: Optional list of images with data and dimensions. auto_create_pr: Whether to automatically create a PR. branch_name: Custom branch name for the PR. open_as_cursor_github_app: Open PR as Cursor GitHub App. skip_reviewer_request: Skip reviewer request on PR. webhook_url: Webhook URL for status updates. webhook_secret: Webhook secret for signature verification.

Returns: The launched Agent object.

Raises: CursorValidationError: If inputs are invalid. CursorAPIError: If the API request fails.

add_followup(agent_id: str, prompt_text: str) → None

Send a follow-up message to an agent.

Args: agent_id: The agent identifier. prompt_text: The follow-up message text.

Raises: CursorValidationError: If inputs are invalid. CursorAPIError: If the API request fails.

list_repositories() → list[vendor_connectors.cursor.Repository]

List available repositories.

Returns: List of Repository objects.

Raises: CursorAPIError: If the API request fails.

list_models() → list[str]

List available models.

Returns: List of model names.

Raises: CursorAPIError: If the API request fails.