Cursor cloud agents

The Cursor cloud agents integration action allows workflows to launch new Cursor cloud agents or send follow-up prompts to existing ones directly using your installed Cursor Cloud Agents integration.

Prerequisites

A Cursor Cloud Agents integration installed in your Port organization.
Actions processing must be enabled on your integration:
- Hosted by Port: actions processing is enabled automatically.
- Self-hosted (Helm or Docker): actions processing is disabled by default and must be explicitly enabled.

Configuration

Field	Type	Description
`type`	`"INTEGRATION_ACTION"`	Required. Must be `"INTEGRATION_ACTION"`
`installationId`	`string`	Required. Your Cursor Cloud Agents integration installation ID
`integrationProvider`	`"cursor-cloud-agents"`	Required. Must be `"cursor-cloud-agents"`
`integrationInvocationType`	`string`	Required. Operation type: `"create_agent"` or `"trigger_agent"`
`integrationActionExecutionProperties`	`object`	Required. Operation-specific configuration

Action semantics

Cursor's create API always requires a prompt and immediately launches a run - there is no config-only "create". So on Cursor:

Create agent launches a new agent with an initial prompt against a repository, starting a run (and billable work) right away.
Trigger agent sends a follow-up prompt to an existing agent via the v1 Create Run API (config fields such as mcpServers, mode, and prompt.images apply when set in config).

Both operations run asynchronously and never block a workflow worker.

API version and completion tracking

	create_agent	trigger_agent
API	You choose `apiVersion`: `v0` or `v1` (default `v1`)	Always v1 follow-up
`reportCompletion: false`	Port run completes immediately after launch	Port run completes immediately after follow-up HTTP succeeds
`reportCompletion: true`	Only valid with `apiVersion: v0`. Attaches a webhook; Port run stays `IN_PROGRESS` until Cursor calls back with `FINISHED` or `ERROR`. Rejected on v1 (no webhooks).	Port run stays `IN_PROGRESS` only if the agent was originally created via v0 create + `reportCompletion: true` (webhook registered at launch). Otherwise completes immediately after follow-up HTTP succeeds.

Webhook tracking on v0 create

reportCompletion: true on create_agent requires apiVersion: v0 and a reachable public URL on your integration (see webhook configuration). Optionally configure webhookSigningSecret to verify incoming callbacks. v1 create always completes the Port run immediately after launch - reportCompletion is not supported on v1.

On apiVersion: v0, you can pass any Cursor API field through config (including mcpServers and mode). Cursor validates which fields apply to each API version. A common pattern is to set mcpServers or mode on the first trigger_agent call instead.

Create agent

Launches a new Cursor cloud agent with an initial prompt, and registers it in Port's catalog.

Execution properties

Field	Type	Description
`apiVersion`	`string`	Required. `v0` or `v1` (default `v1`). See API version and completion tracking.
`prompt`	`string`	Task instructions. Set the top-level `prompt` field, or `config.prompt.text` after merge (not both required). If you pass only `config.prompt`, include `text` - shallow merge replaces the whole `prompt` object.
`repository`	`string`	GitHub repository URL, for example `https://github.com/your-org/your-repo`. On `apiVersion: v0`, map to Cursor `source` (Cursor requires `repository` or `prUrl` in the merged body). On `apiVersion: v1`, satisfies the Port workspace requirement unless `config.repos` or `config.env` is set instead.
`ref`	`string`	Git branch name or commit SHA to use as the base branch. Ignored when `prUrl` is provided.
`prUrl`	`string`	GitHub pull request URL. On `apiVersion: v0`, can be used instead of top-level `repository`. On `apiVersion: v1`, applies when set together with top-level `repository` in the mapped `repos` entry.
`model`	`object`	Optional Cursor model. Omit to use your account default. String shorthand in workflows is also accepted. Object example: `{"id": "composer-2.5", "params": [{"id": "fast", "value": "false"}]}`. See Cursor `GET /v1/models` for valid `id` and `params` combinations. `config.model` overrides this field when both are set.
`autoCreatePr`	`boolean`	Whether to automatically create a pull request when the agent completes. Defaults to `false`.
`reportCompletion`	`boolean`	Only applies when `apiVersion` is `v0`. See API version and completion tracking. Defaults to `false`.
`config`	`object`	Shallow-merged onto the top-level Cursor request body (same shape as the Cursor API). With `apiVersion: v0`: `target`, `model` (model ID string), optional `webhook`. With `apiVersion: v1`: `model` (object), `mcpServers`, `customSubagents`, `envVars`, `mode`, `env`, `workOnCurrentBranch`, `name`, `prompt.images`, `repos`, `autoCreatePR`, `skipReviewerRequest`, `agentId`, and other Cursor fields. See How `config` is merged.

Basic example

Launch an agent with a prompt and a repository, waiting for it to complete (v0 + webhook tracking):

{
  "identifier": "create-agent",
  "title": "Create Cursor Cloud Agent",
  "config": {
    "type": "INTEGRATION_ACTION",
    "installationId": "<your-installation-id>",
    "integrationProvider": "cursor-cloud-agents",
    "integrationInvocationType": "create_agent",
    "integrationActionExecutionProperties": {
      "apiVersion": "v0",
      "prompt": "{{ .outputs.trigger.prompt }}",
      "repository": "{{ .outputs.trigger.repository }}",
      "ref": "{{ .outputs.trigger.ref }}",
      "autoCreatePr": true,
      "reportCompletion": true
    }
  }
}

Trigger agent

Sends a follow-up prompt to an existing Cursor cloud agent. Cursor only allows one active run per agent at a time, so runs targeting the same agent are automatically serialized.

Execution properties

Field	Type	Description
`agentId`	`string`	Required. The ID of the agent to send the follow-up prompt to, for example `bc-00000000-0000-0000-0000-000000000001`
`prompt`	`string`	Follow-up instructions. Set the top-level `prompt` field, or `config.prompt.text` after merge. If you pass only `config.prompt`, include `text`.
`reportCompletion`	`boolean`	See API version and completion tracking. Defaults to `false`.
`config`	`object`	v1 follow-up options in Cursor API shape: `mcpServers`, `mode`, `prompt.images` (under `config.prompt`, not at config root).

Basic example

Send a follow-up prompt to an existing agent, without waiting for completion:

{
  "identifier": "trigger-agent",
  "title": "Trigger Cursor Cloud Agent",
  "config": {
    "type": "INTEGRATION_ACTION",
    "installationId": "<your-installation-id>",
    "integrationProvider": "cursor-cloud-agents",
    "integrationInvocationType": "trigger_agent",
    "integrationActionExecutionProperties": {
      "agentId": "{{ .outputs.trigger.agentId }}",
      "prompt": "{{ .outputs.trigger.prompt }}"
    }
  }
}

Configuration reference

Each Cursor cloud agent capability can be configured in more than one place. This section explains, for every feature, how to manage it in Cursor generally, how to pass it inline through the raw Cursor API, how to pass it inline through the Port integration node, and how to define it with files committed to your repository.

Code snippets show only the field being discussed. Other fields required for a valid request (such as prompt in the merged body or agentId on trigger) are omitted.

Where configuration comes from

Cursor resolves each capability from a mix of inline request fields and on-disk or dashboard configuration. The precedence is the same shape across features: per-run inline values win, then create-time inline values, then project files in the repository, then user files, then team or dashboard configuration.

Inline (API or Port node) is best for values that should live only with a single agent or run, such as short-lived credentials.
Repository files (.cursor/environment.json, .cursor/mcp.json, .cursor/agents/*.md, AGENTS.md) are best for project defaults that your whole team should share.
Dashboard configuration (secrets, MCP servers, default model, network access) is best for team-wide policy and for secrets that should never appear in a request body.

In the Port integration, inline values are set in integrationActionExecutionProperties (top-level fields such as prompt, repository, model) and in its config object (the passthrough for Cursor API fields). Values in config take precedence over the mapped top-level fields when both set the same Cursor body key.

How `config` is merged

The integration builds a Cursor request body from the mapped top-level fields, then applies config with a shallow override at the top level on both v0 and v1:

config keys are merged onto the Cursor request body root (the same shape as the Cursor API).
Shallow means a key in config replaces the whole value for that key. Nested objects and arrays are not deep-merged. For example, if the integration already set prompt.text from the top-level prompt field and you pass config.prompt, your config.prompt object replaces the entire prompt (include text if you still need it).
On apiVersion: v0, put target options under config.target (for example config.target.branchName).
On apiVersion: v0, you may set config.webhook (url and secret) when reportCompletion is false. When reportCompletion is true, the integration owns the webhook used for Port completion tracking, so config.webhook is rejected and the integration webhook is applied after the merge.

The integration validates the merged request body before calling Cursor. Port enforces these rules on top of Cursor's API:

v1 create: the merged body must include a workspace - non-empty repos or env (from top-level repository, config.repos, or config.env).
v0 create + reportCompletion: true: config.webhook is not allowed; the integration supplies the webhook.
reportCompletion on v1 create: rejected (v1 has no webhooks).

Other fields (source on v0, repos/env pairing, API version-specific keys) are validated by Cursor when the request is sent.

API version affects available fields

create_agent targets either the POST /v0/agents or POST /v1/agents endpoint depending on apiVersion, while trigger_agent always uses the POST /v1/agents/{agentId}/runs follow-up endpoint. Some fields exist only on one version. See API version and completion tracking.

Model

The model determines which Cursor model runs the agent. When omitted, Cursor uses the default model configured for your team.

In Cursor: set a Default model for cloud agents in the Cloud Agents dashboard settings. Call GET /v1/models to discover valid id values and per-model params.
Raw API: pass model as a string ("composer-2.5") on v0, or as an object on v1:

{
  "model": { "id": "composer-2.5", "params": [{ "id": "fast", "value": "false" }] }
}

Port node: on v0, set config.model to a model ID string (v0 does not support params). On v1, set config.model as an object ({"id": "...", "params": [...]}). Do not map model at the top level in workflows - use config.model instead. Omit it to use the account default.

v0 (config.model as a string):

{
  "config": {
    "model": "composer-2.5"
  }
}

v1 (config.model as an object):

{
  "config": {
    "model": { "id": "composer-2.5", "params": [{ "id": "fast", "value": "false" }] }
  }
}

Model mapping and parameters

On v0, map a string form field (for example modelId) to config.model. v0 accepts a model ID string only - not params.

On v1, when the selected model has no default variant you must supply model.params. Call GET /v1/models: each model lists its accepted variants (each a concrete id plus params combination) and marks one as isDefault. If a model has no default variant, a model object without matching params is rejected.

Repositories, refs, and named environments

An agent needs a workspace to act on. You can point it at a repository and base ref, at an existing pull request, or at a named cloud environment.

In Cursor: connect source control at the account level, then configure saved environments in the Cloud Agents dashboard. An environment can be scoped to one repository or to a repository group, and it captures the snapshot or Dockerfile, install command, secrets, and network access. Commit .cursor/environment.json to keep this configuration in code. Cursor resolves the environment by .cursor/environment.json first, then a personal saved environment, then a team saved environment.
Raw API: on v0, use source.repository, source.ref, or source.prUrl. On v1, use repos (an array of { url, startingRef }) or env (a named cloud environment). repos and env are mutually exclusive in Cursor's API. On v1 create, Port requires non-empty repos or env in the merged body.

v0:

{
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  }
}

v1 (repos):

{
  "repos": [
    { "url": "https://github.com/your-org/your-repo", "startingRef": "main" },
    { "url": "https://github.com/your-org/other-repo", "startingRef": "main" }
  ]
}

v1 (env):

{
  "env": { "type": "cloud", "name": "my-env" }
}

Port node: set the top-level repository, ref, and prUrl fields for a single repo on v0, or set config.repos (an array) or config.env on v1. On v0, Cursor requires source.repository or source.prUrl in the merged body. On v1, Port requires repository, config.repos, or config.env in the merged body.

Top-level (v0):

{
  "repository": "{{ .outputs.trigger.repository }}",
  "ref": "{{ .outputs.trigger.ref }}"
}

config.repos (v1):

{
  "config": {
    "repos": [{ "url": "https://github.com/your-org/your-repo", "startingRef": "main" }]
  }
}

config.env (v1):

{
  "config": {
    "env": { "type": "cloud", "name": "my-env" }
  }
}

Environment variables

envVars are session environment variables injected into the cloud agent's shell. They are encrypted at rest and removed when the agent is torn down. Variable names cannot start with CURSOR_.

In Cursor: for durable secrets, add them in the Secrets tab at cursor.com/dashboard/cloud-agents. Secrets can be scoped to a user, a team, or a specific environment, and are exposed to the agent as environment variables. If you include .env.local files when creating a snapshot, they are saved too, though the Secrets tab is the recommended approach.
Raw API (v1 only): pass envVars as an object of name and value pairs.

{
  "envVars": { "STAGING_API_TOKEN": "..." }
}

Port node: set config.envVars on a v1 create_agent node.

{
  "config": {
    "envVars": { "STAGING_API_TOKEN": "{{ .outputs.mint_token.body.token }}" }
  }
}

Inline secrets are visible in run data

Values passed inline through the Port node (including config.envVars and inline mcpServers credentials) are stored in the workflow run's outputs, which anyone with permission to view the run can see. For durable secrets, prefer the Cursor Secrets tab or dashboard MCP configuration, and reserve inline values for short-lived, run-scoped credentials.

MCP servers

MCP (Model Context Protocol) servers give the agent access to external tools and data sources. Both HTTP and stdio transports are supported.

In Cursor: add and enable personal servers through the MCP dropdown at cursor.com/agents. Team admins configure shared servers under Dashboard -> Integrations & MCP. HTTP servers (recommended) are proxied through Cursor's backend and their credentials never enter the VM; stdio servers run inside the VM and read credentials from their env. OAuth is supported and stays per-user, so a service account API key cannot reuse a user's saved OAuth login.
Raw API (v1 create and every follow-up run): pass mcpServers as an array of server definitions, each with a name.

{
  "mcpServers": [
    {
      "name": "linear",
      "type": "http",
      "url": "https://mcp.linear.app/sse",
      "headers": { "Authorization": "Bearer ..." }
    }
  ]
}

Port node: set config.mcpServers (an array) on any create_agent or trigger_agent node. Cursor validates API version compatibility.

{
  "config": {
    "mcpServers": [
      {
        "name": "linear",
        "type": "http",
        "url": "https://mcp.linear.app/sse",
        "headers": { "Authorization": "Bearer ..." }
      }
    ]
  }
}

Repository files: commit .cursor/mcp.json for project-scoped servers.

Connecting to Port MCP

To let a cloud agent use Port's MCP server, configure it on the Cursor side rather than passing it inline through the integration.

Add it as an HTTP MCP server in the Cursor dashboard (the MCP dropdown at cursor.com/agents, or Dashboard -> Integrations & MCP for a team server), using the URL https://mcp.port.io/v1 (EU) or https://mcp.us.port.io/v1 (US), authenticated with OAuth.
Cloud agents then pick up the server automatically, so you never pass a Port token inline and it never enters the workflow run's data. This is the recommended, secure approach.

Service accounts and MCP OAuth

A Cursor service account API key cannot reuse a user's saved MCP OAuth login. Dashboard OAuth for Port MCP works cleanly when runs are triggered with a user API key. Passing a Port token through inline mcpServers headers is possible but exposes the token in the run's outputs, so prefer dashboard configuration.

Custom subagents

Subagents are named helper agents that the main agent can spawn for focused tasks such as code review or test writing.

In Cursor / repository files: commit definitions to .cursor/agents/*.md, each with frontmatter name, description, and optional model. Cloud agents pick these up automatically when they run against the cloned repository.
Raw API (v1 only): pass customSubagents as an array. Each entry requires name, description, and prompt, plus an optional model. Inline definitions override file-based ones with the same name.
Port node: set config.customSubagents (an array) on a v1 create_agent node.

{
  "config": {
    "customSubagents": [
      {
        "name": "code-reviewer",
        "description": "Expert code reviewer for quality and security.",
        "prompt": "Review code for bugs, security issues, and proven approaches."
      }
    ]
  }
}

Mode

mode controls whether the agent edits code (agent) or only produces a plan without making changes (plan). Cursor may add other mode values over time.

Raw API (v1 create and every follow-up run): pass mode as a string (for example "agent" or "plan").
Port node: set config.mode on any create_agent or trigger_agent node.

{
  "config": { "mode": "plan" }
}

Other v1 create options

These fields are passed through config on a v1 create_agent node and are shallow-merged onto the POST /v1/agents request body (nested objects and arrays replace the whole value).

`config` key	Description
`workOnCurrentBranch`	Work on the ref you provide instead of forking a new branch.
`name`	A human-readable name for the agent.
`prompt.images`	Images to attach to the prompt (under `config.prompt`, not at config root). Also available on `trigger_agent`.
`skipReviewerRequest`	Skip requesting reviewers on the pull request.
`agentId`	Reuse a specific agent ID instead of letting Cursor mint one. Cannot be combined with `envVars`.

v0 create options

These fields are passed through config on a v0 create_agent node and are shallow-merged onto the top-level Cursor request body. Use the Cursor API shape.

`config` key	Description
`target`	Object merged onto (and replacing) the request `target`. Include every target field you need, for example `branchName`, `autoBranch`, `openAsCursorGithubApp`, `skipReviewerRequest`, `autoCreatePr`.
`model`	Model ID string. v0 does not support `params`.
`webhook`	Optional `{ "url", "secret" }` for Cursor's v0 webhook. Not allowed when `reportCompletion` is `true`.

Complete workflow examples

Placeholders

Replace all <...> placeholders (e.g. <your-installation-id>) with your actual values before using these workflows.

Create Cursor Cloud Agent - full workflow JSON (click to expand)

This workflow uses condition nodes to route create requests. An API version condition sends v0 launches to a single node (with reportCompletion hardcoded for webhook tracking) and v1 launches through a Workspace condition that picks repos or env. Form fields are shown or hidden based on the selected API version and workspace target.

Why multiple create nodes

v0 and v1 accept different config keys, and Port sends every key you template (even when it resolves to null), so one node cannot mix API versions or pass both repos and env. Condition nodes keep each create_agent node's config limited to the keys that apply.

{
  "title": "Create Cursor Cloud Agent",
  "icon": "Cursor",
  "description": "Launch a new Cursor cloud agent with v0 or v1 configuration options.",
  "category": "Cursor Cloud Agents",
  "allowAnyoneToViewRuns": true,
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Create Cursor Cloud Agent",
      "icon": "Cursor",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "prompt": {
              "title": "Prompt",
              "type": "string",
              "format": "multi-line"
            },
            "apiVersion": {
              "title": "API version",
              "type": "string",
              "enum": ["v0", "v1"],
              "default": "v1"
            },
            "repository": {
              "title": "Repository",
              "type": "string",
              "format": "url",
              "visible": {
                "jqQuery": ".form.apiVersion == \"v0\""
              }
            },
            "ref": {
              "title": "Base branch",
              "type": "string",
              "visible": {
                "jqQuery": ".form.apiVersion == \"v0\""
              }
            },
            "modelId": {
              "title": "Model ID",
              "type": "string",
              "default": "composer-2.5",
              "visible": {
                "jqQuery": ".form.apiVersion == \"v0\""
              }
            },
            "workspaceTarget": {
              "title": "Workspace",
              "type": "string",
              "enum": ["repositories", "named_environment"],
              "default": "repositories",
              "visible": {
                "jqQuery": ".form.apiVersion == \"v1\""
              }
            },
            "repos": {
              "title": "Repositories",
              "description": "One or more repositories. Each entry needs a url; startingRef is optional.",
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "url": { "type": "string", "format": "url" },
                  "startingRef": { "type": "string" }
                },
                "required": ["url"]
              },
              "default": [
                { "url": "https://github.com/your-org/your-repo", "startingRef": "main" }
              ],
              "visible": {
                "jqQuery": ".form.apiVersion == \"v1\" and .form.workspaceTarget == \"repositories\""
              }
            },
            "env": {
              "title": "Named environment",
              "type": "object",
              "properties": {
                "type": { "type": "string", "enum": ["cloud"], "default": "cloud" },
                "name": { "type": "string" }
              },
              "required": ["name"],
              "visible": {
                "jqQuery": ".form.apiVersion == \"v1\" and .form.workspaceTarget == \"named_environment\""
              }
            },
            "model": {
              "title": "Model",
              "type": "object",
              "properties": {
                "id": { "title": "Model ID", "type": "string" },
                "params": {
                  "title": "Model parameters",
                  "type": "array",
                  "items": { "type": "object" },
                  "default": []
                }
              },
              "required": ["id"],
              "default": {
                "id": "composer-2.5",
                "params": [{ "id": "fast", "value": "false" }]
              },
              "visible": {
                "jqQuery": ".form.apiVersion == \"v1\""
              }
            },
            "mode": {
              "title": "Mode",
              "type": "string",
              "enum": ["agent", "plan"],
              "default": "agent",
              "visible": {
                "jqQuery": ".form.apiVersion == \"v1\""
              }
            },
            "autoCreatePr": {
              "title": "Auto create pull request",
              "type": "boolean",
              "default": true
            },
            "workOnCurrentBranch": {
              "title": "Work on current branch",
              "type": "boolean",
              "default": false,
              "visible": {
                "jqQuery": ".form.apiVersion == \"v1\""
              }
            },
            "mcpServers": {
              "title": "MCP servers",
              "description": "Array of MCP server definitions, each with a name.",
              "type": "array",
              "items": { "type": "object" },
              "default": [],
              "visible": {
                "jqQuery": ".form.apiVersion == \"v1\""
              }
            },
            "customSubagents": {
              "title": "Custom subagents",
              "description": "Array of subagent definitions (name, description, prompt).",
              "type": "array",
              "items": { "type": "object" },
              "default": [],
              "visible": {
                "jqQuery": ".form.apiVersion == \"v1\""
              }
            },
            "envVars": {
              "title": "Environment variables",
              "description": "Object of name/value pairs. Names cannot start with CURSOR_.",
              "type": "object",
              "additionalProperties": true,
              "default": {},
              "visible": {
                "jqQuery": ".form.apiVersion == \"v1\""
              }
            }
          },
          "required": {
            "jqQuery": "if .form.apiVersion == \"v0\" then [\"prompt\", \"apiVersion\", \"repository\"] else [\"prompt\", \"apiVersion\"] end"
          },
          "order": [
            "prompt",
            "apiVersion",
            "repository",
            "ref",
            "modelId",
            "workspaceTarget",
            "repos",
            "env",
            "model",
            "mode",
            "autoCreatePr",
            "workOnCurrentBranch",
            "mcpServers",
            "customSubagents",
            "envVars"
          ]
        },
        "actionCardButtonText": "Create",
        "executeActionButtonText": "Create",
        "published": true,
        "permissions": { "roles": ["Member", "Admin"] }
      },
      "variables": {},
      "links": [],
      "verbose": false
    },
    {
      "identifier": "api_version_condition",
      "title": "API version",
      "icon": "Cursor",
      "config": {
        "type": "CONDITION",
        "outlets": [
          {
            "identifier": "v0",
            "title": "v0",
            "expression": ".outputs.trigger.apiVersion == \"v0\""
          },
          {
            "identifier": "v1",
            "title": "v1",
            "expression": ".outputs.trigger.apiVersion == \"v1\""
          }
        ]
      },
      "variables": {},
      "links": [],
      "verbose": false
    },
    {
      "identifier": "create_agent_v0",
      "title": "Create agent (v0)",
      "icon": "Cursor",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<your-installation-id>",
        "integrationProvider": "cursor-cloud-agents",
        "integrationInvocationType": "create_agent",
        "integrationActionExecutionProperties": {
          "apiVersion": "v0",
          "prompt": "{{ .outputs.trigger.prompt }}",
          "repository": "{{ .outputs.trigger.repository }}",
          "ref": "{{ .outputs.trigger.ref }}",
          "reportCompletion": true,
          "config": {
            "model": "{{ .outputs.trigger.modelId }}",
            "target": {
              "autoCreatePr": "{{ .outputs.trigger.autoCreatePr }}"
            }
          }
        },
        "onFailure": "terminate"
      },
      "variables": {},
      "links": [],
      "verbose": false
    },
    {
      "identifier": "workspace_condition",
      "title": "Workspace target",
      "icon": "Cursor",
      "config": {
        "type": "CONDITION",
        "outlets": [
          {
            "identifier": "repositories",
            "title": "Repositories",
            "expression": ".outputs.trigger.workspaceTarget == \"repositories\""
          },
          {
            "identifier": "named_environment",
            "title": "Named environment",
            "expression": ".outputs.trigger.workspaceTarget == \"named_environment\""
          }
        ]
      },
      "variables": {},
      "links": [],
      "verbose": false
    },
    {
      "identifier": "create_agent_v1_repos",
      "title": "Create agent (v1, repositories)",
      "icon": "Cursor",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<your-installation-id>",
        "integrationProvider": "cursor-cloud-agents",
        "integrationInvocationType": "create_agent",
        "integrationActionExecutionProperties": {
          "apiVersion": "v1",
          "prompt": "{{ .outputs.trigger.prompt }}",
          "config": {
            "repos": "{{ .outputs.trigger.repos }}",
            "model": "{{ .outputs.trigger.model }}",
            "mode": "{{ .outputs.trigger.mode }}",
            "autoCreatePR": "{{ .outputs.trigger.autoCreatePr }}",
            "workOnCurrentBranch": "{{ .outputs.trigger.workOnCurrentBranch }}",
            "mcpServers": "{{ .outputs.trigger.mcpServers }}",
            "customSubagents": "{{ .outputs.trigger.customSubagents }}",
            "envVars": "{{ .outputs.trigger.envVars }}"
          }
        },
        "onFailure": "terminate"
      },
      "variables": {},
      "links": [],
      "verbose": false
    },
    {
      "identifier": "create_agent_v1_env",
      "title": "Create agent (v1, named environment)",
      "icon": "Cursor",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<your-installation-id>",
        "integrationProvider": "cursor-cloud-agents",
        "integrationInvocationType": "create_agent",
        "integrationActionExecutionProperties": {
          "apiVersion": "v1",
          "prompt": "{{ .outputs.trigger.prompt }}",
          "config": {
            "env": "{{ .outputs.trigger.env }}",
            "model": "{{ .outputs.trigger.model }}",
            "mode": "{{ .outputs.trigger.mode }}",
            "autoCreatePR": "{{ .outputs.trigger.autoCreatePr }}",
            "workOnCurrentBranch": "{{ .outputs.trigger.workOnCurrentBranch }}",
            "mcpServers": "{{ .outputs.trigger.mcpServers }}",
            "customSubagents": "{{ .outputs.trigger.customSubagents }}",
            "envVars": "{{ .outputs.trigger.envVars }}"
          }
        },
        "onFailure": "terminate"
      },
      "variables": {},
      "links": [],
      "verbose": false
    }
  ],
  "connections": [
    {
      "description": null,
      "sourceIdentifier": "trigger",
      "targetIdentifier": "api_version_condition"
    },
    {
      "description": null,
      "sourceIdentifier": "api_version_condition",
      "targetIdentifier": "create_agent_v0",
      "sourceOutletIdentifier": "v0"
    },
    {
      "description": null,
      "sourceIdentifier": "api_version_condition",
      "targetIdentifier": "workspace_condition",
      "sourceOutletIdentifier": "v1"
    },
    {
      "description": null,
      "sourceIdentifier": "workspace_condition",
      "targetIdentifier": "create_agent_v1_repos",
      "sourceOutletIdentifier": "repositories"
    },
    {
      "description": null,
      "sourceIdentifier": "workspace_condition",
      "targetIdentifier": "create_agent_v1_env",
      "sourceOutletIdentifier": "named_environment"
    }
  ]
}

Trigger Cursor Cloud Agent - full workflow JSON (click to expand)

{
  "title": "Trigger Cursor Cloud Agent",
  "icon": "Cursor",
  "description": "Send a follow-up prompt to an existing Cursor cloud agent.",
  "category": "Cursor Cloud Agents",
  "allowAnyoneToViewRuns": true,
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Trigger Cursor Cloud Agent",
      "icon": "Cursor",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "contexts": [
          {
            "on": "ENTITY",
            "userInput": "agentId"
          }
        ],
        "userInputs": {
          "properties": {
            "agentId": {
              "title": "Agent",
              "type": "string",
              "format": "entity",
              "blueprint": "cursor_agent"
            },
            "prompt": {
              "title": "Prompt",
              "type": "string",
              "format": "multi-line"
            },
            "mode": {
              "title": "Mode",
              "type": "string",
              "enum": ["agent", "plan"],
              "default": "agent"
            },
            "mcpServers": {
              "title": "MCP servers",
              "description": "Array of MCP server definitions, each with a name.",
              "type": "array",
              "items": { "type": "object" },
              "default": []
            }
          },
          "required": ["agentId", "prompt"],
          "order": ["agentId", "prompt", "mode", "mcpServers"]
        },
        "actionCardButtonText": "Trigger",
        "executeActionButtonText": "Trigger",
        "published": true,
        "permissions": { "roles": ["Member", "Admin"] }
      },
      "variables": {},
      "links": [],
      "verbose": false
    },
    {
      "identifier": "trigger_agent",
      "title": "Trigger Cursor Cloud Agent",
      "icon": "Cursor",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<your-installation-id>",
        "integrationProvider": "cursor-cloud-agents",
        "integrationInvocationType": "trigger_agent",
        "integrationActionExecutionProperties": {
          "agentId": "{{ .outputs.trigger.agentId }}",
          "prompt": "{{ .outputs.trigger.prompt }}",
          "config": {
            "mode": "{{ .outputs.trigger.mode }}",
            "mcpServers": "{{ .outputs.trigger.mcpServers }}"
          }
        },
        "onFailure": "terminate"
      },
      "variables": {},
      "links": [],
      "verbose": false
    }
  ],
  "connections": [
    {
      "description": null,
      "sourceIdentifier": "trigger",
      "targetIdentifier": "trigger_agent"
    }
  ]
}

Prerequisites​

Configuration​

Action semantics​

API version and completion tracking​

Create agent​

Execution properties​

Basic example​

Trigger agent​

Execution properties​

Basic example​

Configuration reference​

Where configuration comes from​

How config is merged​

Model​

Repositories, refs, and named environments​

Environment variables​

MCP servers​

Connecting to Port MCP​

Custom subagents​

Mode​

Other v1 create options​

v0 create options​

Complete workflow examples​

Prerequisites

Configuration

Action semantics

API version and completion tracking

Create agent

Execution properties

Basic example

Trigger agent

Execution properties

Basic example

Configuration reference

Where configuration comes from

How `config` is merged

Model

Repositories, refs, and named environments

Environment variables

MCP servers

Connecting to Port MCP

Custom subagents

Mode

Other v1 create options

v0 create options

Complete workflow examples