Cursor Agent

The Cursor Agent action node launches a Cursor cloud agent to perform coding tasks on a GitHub repository or pull request. The workflow pauses while the agent runs and automatically resumes when the agent completes.

Prerequisites

You need a Cursor API key to use this node. Get one from Cursor Settings.

Setup

1. Store your API key as a secret

Before using the Cursor Agent node, store your Cursor API key as a Port secret:

1. Go to your portal's secrets
2. Click + Secret and create a secret named CURSOR_API_KEY with your Cursor API key.

2. Configure the node

Reference the secret in your node configuration using {{ .secrets["CURSOR_API_KEY"] }}.

Configuration

Field	Type	Description
type	"CURSOR_AGENT"	Required. Must be "CURSOR_AGENT"
apiKey	string	Required. Your Cursor API key. Reference it from secrets: {{ .secrets["CURSOR_API_KEY"] }}
prompt	object	Required. The task prompt for the agent
prompt.text	string	Required. Instructions for what the agent should do
source	object	Required. Repository or PR to work on. Must specify either repository or prUrl
source.repository	string	GitHub repository URL (e.g. https://github.com/your-org/your-repo)
source.ref	string	Git ref (branch, tag, or commit) to use as the base
source.prUrl	string	GitHub pull request URL. When provided, repository and ref are ignored
model	string	Model to use (e.g. claude-sonnet-4-5). Omit to use the default model
target	object	Optional target configuration
target.autoCreatePr	boolean	Automatically create a pull request when the agent completes
target.branchName	string	Custom branch name for the agent to create

For the full list of configuration options, see the Cursor API documentation.

Basic example

Launch a Cursor agent to add tests to a service:

{
  "identifier": "add-tests",
  "title": "Add Unit Tests",
  "config": {
    "type": "CURSOR_AGENT",
    "apiKey": "{{ .secrets[\"CURSOR_API_KEY\"] }}",
    "prompt": {
      "text": "Add unit tests for the authentication module. Cover edge cases and error handling."
    },
    "source": {
      "repository": "https://github.com/{{ .outputs.trigger.org }}/{{ .outputs.trigger.repo }}",
      "ref": "main"
    },
    "target": {
      "autoCreatePr": true
    }
  }
}

Working with a pull request

You can point the agent at an existing PR to review or iterate on changes:

{
  "identifier": "review-pr",
  "title": "Review and Improve PR",
  "config": {
    "type": "CURSOR_AGENT",
    "apiKey": "{{ .secrets[\"CURSOR_API_KEY\"] }}",
    "prompt": {
      "text": "Review this PR for code quality issues and apply fixes. Add any missing error handling."
    },
    "source": {
      "prUrl": "{{ .outputs.trigger.prUrl }}"
    }
  }
}

Monitoring the agent

While the workflow is paused, you can monitor the agent's progress:

1. Go to cursor.com/agents to see all your running and completed agents.
2. Click on the agent run to see real-time logs and progress.

When the agent finishes (successfully or with an error), the workflow automatically resumes and the node completes.

Outputs

When the agent completes, the node produces the following outputs:

Field	Description
agentId	The Cursor agent run ID
agentName	The name of the agent run
status	Final status (FINISHED or ERROR)
summary	Summary of what the agent accomplished
target.prUrl	URL of the created pull request (if autoCreatePr was enabled)
target.branchName	Name of the branch the agent pushed to

Reference these outputs in subsequent nodes:

{
  "body": {
    "message": "Cursor agent completed. PR: {{ .outputs[\"add-tests\"].target.prUrl }}"
  }
}

Examples

Self-service: Generate documentation

Create a self-service workflow that generates documentation for a repository:

Workflow example (click to expand)

{
  "identifier": "generate-docs",
  "title": "Generate Documentation",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Select Repository",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "repository": {
              "type": "string",
              "title": "Repository URL",
              "description": "GitHub repository URL"
            }
          },
          "required": ["repository"]
        }
      }
    },
    {
      "identifier": "generate-docs",
      "title": "Generate Docs with Cursor",
      "config": {
        "type": "CURSOR_AGENT",
        "apiKey": "{{ .secrets[\"CURSOR_API_KEY\"] }}",
        "prompt": {
          "text": "Generate comprehensive README documentation for this repository. Include setup instructions, API documentation, and usage examples."
        },
        "source": {
          "repository": "{{ .outputs.trigger.repository }}",
          "ref": "main"
        },
        "target": {
          "autoCreatePr": true
        }
      }
    },
    {
      "identifier": "notify",
      "title": "Send Notification",
      "config": {
        "type": "WEBHOOK",
        "url": "https://hooks.slack.com/services/xxx",
        "method": "POST",
        "body": {
          "text": "Documentation PR created: {{ .outputs[\"generate-docs\"].target.prUrl }}"
        }
      }
    }
  ],
  "connections": [
    {
      "sourceIdentifier": "trigger",
      "targetIdentifier": "generate-docs"
    },
    {
      "sourceIdentifier": "generate-docs",
      "targetIdentifier": "notify"
    }
  ]
}

Event-driven: Fix failing CI

Automatically trigger a Cursor agent to fix issues when CI fails:

Workflow example (click to expand)

{
  "identifier": "auto-fix-ci",
  "title": "Auto-fix Failing CI",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "On CI Failure",
      "config": {
        "type": "EVENT_TRIGGER",
        "event": {
          "type": "ENTITY_UPDATED",
          "blueprintIdentifier": "githubPullRequest"
        },
        "condition": {
          "type": "JQ",
          "expressions": [
            ".diff.after.properties.ciStatus == \"failed\""
          ],
          "combinator": "and"
        }
      }
    },
    {
      "identifier": "fix-ci",
      "title": "Fix CI Issues",
      "config": {
        "type": "CURSOR_AGENT",
        "apiKey": "{{ .secrets[\"CURSOR_API_KEY\"] }}",
        "prompt": {
          "text": "The CI pipeline is failing. Analyze the errors and fix the issues. Focus on test failures and linting errors."
        },
        "source": {
          "prUrl": "{{ .outputs.trigger.diff.after.properties.link }}"
        }
      }
    }
  ],
  "connections": [
    {
      "sourceIdentifier": "trigger",
      "targetIdentifier": "fix-ci"
    }
  ]
}