Cursor Background Agents - Dify Plugin

A comprehensive Dify tool provider for integrating with Cursor Background Agents API, enabling autonomous AI-powered coding workflows in your applications.

Author: lysonober
Version: 0.0.1
Type: Tool

🤖 What are Cursor Background Agents?

Cursor Background Agents are autonomous AI-powered coding agents that work independently on your GitHub repositories. Think of them as skilled developers who can:

• Understand complex prompts and translate them into working code
• Make intelligent decisions about file structure, dependencies, and implementation approaches
• Run tests and iterate on solutions until they work correctly
• Create pull requests with clean, production-ready changes
• Work asynchronously while you focus on other tasks

✨ Key Capabilities

Feature	Description
Autonomous Code Generation	Agents understand your requirements and implement complete features
Repository Integration	Direct GitHub integration with automatic branch management and PR creation
Intelligent Problem Solving	Agents can debug, test, and refine their own code
Scalable Workflow	Support for up to 256 concurrent agents per API key
Follow-up Instructions	Send additional requirements to running agents
Environment Awareness	Automatically detects and uses your project's setup (package.json, requirements.txt, etc.)

🚀 Overview

This Dify plugin provides a complete interface to manage Cursor Background Agents on no-code canvas, allowing you to:

• Launch background agents on GitHub repositories
• Monitor agent status and progress in real-time
• Send follow-up instructions to running agents
• Retrieve conversation logs and agent outputs

🎯 Real-World Use Cases

For Product Teams:

• Feature Development: "Add user authentication with email verification and password reset"
• Bug Fixes: "Fix the memory leak in the image processing pipeline"
• Documentation: "Generate comprehensive API docs with examples for all endpoints"

For DevOps & Maintenance:

• Dependency Updates: "Upgrade React to v18 and fix all breaking changes"
• Test Coverage: "Add unit tests for the payment processing module"
• Code Refactoring: "Convert all class components to functional components with hooks"

For Content & Automation:

• Data Processing: "Parse CSV files and generate interactive charts"
• Integration Tasks: "Integrate Stripe payments with error handling and webhooks"
• Performance Optimization: "Optimize database queries and add caching layer"

🎯 Plugin Features

• GitHub Integration: Seamless repo cloning and branch management
• Real-time Monitoring: Track agent progress with live status updates
• Interactive Communication: Send follow-ups and adjust agent behavior
• Webhook Support: Receive status change notifications for automation
• Model Selection: Choose from Max Mode-compatible models (Claude, GPT-4, etc.)
• Environment Setup: Support for .cursor/environment.json configurations

📋 Prerequisites

• Cursor API Key: Create in Cursor Dashboard → Integrations
• GitHub Permissions: Grant access to target repositories
• Dify Instance: Version compatible with custom tool providers

🚀 Quick Start

1. Get Your API Key

1. Navigate to Cursor Dashboard → Integrations
2. Create a new API key for Background Agents
3. Copy the token (starts with sk-...)

2. Setup in Dify

1. Go to Tools → Providers in your Dify workspace
2. Add Cursor Background Agents provider
3. Enter your API key in the credentials field
4. Enable the tools you need from the three categories below

3. Launch Your First Agent

Tool: Launch Agent
Prompt: "Add a comprehensive README.md file with installation instructions and examples"
Repository: "https://github.com/your-username/your-repo"
Model: "claude-4-sonnet" (optional)

4. Monitor Progress

• Use Agent Status to check progress
• Use Agent Conversation to see detailed logs
• Click the progress URL for live dashboard view

🛠️ Installation

1. Configure Provider Credentials:

   • Add your Cursor API Key in Dify's tool provider settings
   • Format: Bearer token (paste only the token part)

2. Add Tool Categories:

   • Import all tools from the three categories below
   • Configure webhook endpoints if needed

📚 Available Tools

🔍 Agent Information Tools

Tool	Parameters	Description
List Agents	limit (1-100, optional) cursor (string, optional)	Retrieve paginated list of all background agents
Agent Status	agent_id (string, required)	Get current status, progress, and metadata for specific agent
Agent Conversation	agent_id (string, required)	Fetch conversation messages and interaction history

⚙️ Agent Management Tools

Tool	Parameters	Description
Launch Agent	prompt (string, required) repository (string, required) ref (string, optional) model (string, optional) webhook_url (string, optional) webhook_secret (secret, optional)	Create new background agent on specified repository Note: Environment setup via .cursor/environment.json in target repo
Add Follow-up	agent_id (string, required) message (string, required)	Send additional instructions to running agent
Delete Agent	agent_id (string, required)	Terminate and remove background agent

🔧 General Utility Tools

Tool	Parameters	Description
API Key Info	None	Validate API key and retrieve account metadata
List Models	None	Get available Max Mode-compatible models for agents
List GitHub Repositories	limit (1-100, optional) cursor (string, optional)	Browse accessible GitHub repositories

💡 Usage Examples

Launching a New Agent

prompt: "Add comprehensive unit tests for the authentication module"
repository: "https://github.com/your-org/your-repo"
ref: "main"
model: "claude-4-sonnet"

Monitoring Progress

1. Use Agent Status to check current phase and progress
2. Use Agent Conversation to review detailed logs
3. Click progress URLs for live dashboard view

Sending Follow-ups

agent_id: "bc_abc123"
message: "Also add integration tests for the login flow"

🔗 Environment Setup

For optimal results, commit .cursor/environment.json directly to your target repository:

Example: In your project repository (https://github.com/your-org/your-repo)

your-repo/
├── .cursor/
│   └── environment.json
├── src/
├── package.json
└── README.md

Sample .cursor/environment.json:

{
  "install": "npm install && npm run build",
  "terminals": [
    {
      "name": "Dev Server", 
      "command": "npm run dev"
    }
  ]
}

When a background agent is launched on your repository, it will automatically detect and use this environment configuration for proper setup.

🎣 Webhooks (Optional)

You can configure webhooks to receive real-time status updates from Cursor Background Agents.

1. Set webhook_url when launching an agent to receive event notifications.
2. Provide a webhook_secret for HMAC signature verification to ensure authenticity.
3. Handle statusChange events (including ERROR and FINISHED states).

💡 Tip: Using webhooks in combination with Supabase Edge Functions is highly recommended for secure, scalable, and low-latency event handling.

Webhook Request Headers

Each webhook request includes the following HTTP headers:

• X-Webhook-Signature: HMAC-SHA256 signature in the format sha256=<hex_digest>
• X-Webhook-ID: Unique identifier for this webhook delivery
• X-Webhook-Event: Event type (currently only statusChange)
• User-Agent: Always set to Cursor-Agent-Webhook/1.0

⚠️ Known Issues

• Planning Phase Hang: Background agents may occasionally get stuck at "Planning next moves" phase. This is a known limitation of the Cursor platform that will be addressed in future iterations. If this occurs, you may need to delete and restart the agent.
• Error Handling Design Note: Error will not be raised as exceptions (e.g., launching agent errors will not raise and block the program), but will be returned as normal output. This is intentional, so that downstream LLM/agent nodes can handle and notify you of errors without interrupting the workflow. If you require program interruption on error, please be aware of this design.

📖 Learn More

• Cursor Background Agents Documentation
• Background Agents API Reference
• Cursor Dashboard

🆘 Support

For issues or feature requests:

• X(Twitter): https://x.com/lyson_ober
• Email: lysonober@gmail.com

📄 Privacy

This plugin acts as a passthrough to Cursor's API and stores no data locally. Refer to Cursor's Privacy Policy for data handling details.

---

Made with 💙 for the Dify community