Skip to Content
DocumentationIntegrationCursorLaunch Agent

Launch Agent

Launches a new background agent to work on a repository. Background agents are AI-powered assistants that can autonomously work on code changes, create pull requests, and execute tasks in your GitHub repositories.

Overview

  • Purpose: Create and launch a new background agent to perform automated coding tasks on a specified repository.
  • Use Cases: Automated code refactoring, feature implementation, bug fixes, documentation updates, or any coding task that can be described in natural language.
  • API Method: POST /v0/agents

Required Input Fields

Prompt Text: A clear, detailed description of the task you want the agent to perform. Be specific about what changes you want, which files to modify, and any constraints or requirements.

Repository URL: The GitHub repository URL where the agent will work. Must be a repository you have access to through your Cursor integration.

Optional Input Fields

Prompt Images: Attach up to 5 images to provide visual context for the agent (e.g., UI mockups, diagrams, screenshots). Each image requires base64-encoded data and optional dimensions (width/height in pixels).

Source Ref: Specify a Git branch, tag, or commit SHA to use as the starting point. If not provided, the default branch is used.

Model: Select which AI model the agent should use. Use the ‘List Models’ action to see available options.

Target Configuration: Control how the agent creates and manages branches and pull requests.

Webhook: Configure a webhook URL and secret to receive real-time updates about the agent’s progress and completion status.

Target Configuration Options

  • Auto Create PR: Automatically create a pull request when the agent completes its work (default: false).
  • Branch Name: Specify a custom branch name for the agent’s work. If not provided, a name is auto-generated.
  • Open as Cursor GitHub App: Open the agent’s work in the Cursor GitHub App interface (default: false).
  • Skip Reviewer Request: Skip automatically requesting reviewers on the created PR (default: false).

Webhook Configuration

Webhook URL: HTTPS endpoint to receive agent status updates. Must be a valid URL (max 2048 characters).

Webhook Secret: Secret key for webhook signature verification. Must be between 32-256 characters for security.

Output

  • Agent ID: Unique identifier for the created agent, used for follow-up actions and status tracking.
  • Agent Name: Human-readable name assigned to the agent.
  • Status: Initial status will be ‘CREATING’. Other possible statuses: RUNNING, FINISHED, ERROR, EXPIRED.
  • Source: Repository and ref information where the agent is working.
  • Target: Branch details and URL to view the agent’s work in Cursor Web.
  • Created At: Timestamp when the agent was created (ISO 8601 format).
  • Summary: Brief description of the agent’s task (may be empty initially).

Tips

[!TIP] Write clear, specific prompts for better results - include file paths, function names, and expected behavior

[!TIP] Use images to provide visual context for UI-related tasks

[!TIP] Enable ‘Auto Create PR’ if you want the agent to automatically submit its work for review

[!TIP] Configure webhooks to integrate agent completion events into your workflow automation

[!TIP] Save the returned agent ID to track progress or add follow-up instructions later

[!TIP] Test with small tasks first to understand how the agent interprets your prompts

Need help? Have feedback?
OverviewAdd Follow-up Instruction