Getting started with agentic initiatives

This guide walks you through building the pattern described in Agentic initiatives: one entity represents a fix effort against a failing scorecard rule, and Port fans a coding agent out across every service that rule currently fails.

By the end, a platform engineer will be able to approve a Draft fix effort and watch Port create one tracked run per affected service, launch a Cursor agent against each repository, and roll every result back up into a single progress view.

Or implement it in one shot with your coding assistant

Connect Port MCP to your coding assistant, then copy the prompt below to implement this entire guide automatically against your Port account.

I want to set up a fleet-wide scorecard remediation pattern in Port.

Here is what I need you to do, step by step:

1. Create a blueprint with identifier "agentic_initiative", title "Agentic Initiative", icon "Automation":
   - description (markdown): what this initiative fixes
   - prompt (markdown): the instruction given to the coding agent for every target
   - approval_policy (string, enum: auto-merge, owner-approval, pe-approval)
   - status (string, enum: Draft, Running, Completed, Cancelled)
   - target_blueprint (string): the blueprint identifier the targets belong to
   - reference_context (array): supporting links or entity identifiers for the agent
   - target_entities (array): JSON objects of {serviceIdentifier, serviceTitle, repoUrl}, populated before the run begins
   Add aggregation properties targeting "run_target" entities, counting by status: total_targets (count all), targets_pending, targets_running, targets_pr_opened, targets_merged, targets_failed.

2. Create a blueprint with identifier "run_target", title "Run Target", icon "Branch":
   - target_blueprint, target_identifier, target_title (strings)
   - target_url (string, url)
   - status (string, enum: Pending, Running, PR Opened, Merged, Failed, Skipped)
   - pr_url (string, url)
   - pr_ci_status (string, enum: pending, passing, failing)
   - error_message (string)
   - agent_log_url (string, url)
   - team_notified (boolean)
   Add relations: service (target "service", not required, not many), pull_request (target "githubPullRequest", not required, not many), agentic_initiative (target "agentic_initiative", not required, not many).

3. Create a Port workflow with identifier "agentic_initiative_executor", title "Kickoff initiative fixer agents":
   - trigger (EVENT_TRIGGER): fires on ENTITY_UPDATED for agentic_initiative where status changed from Draft to Running.
   - bulk_create_targets (WEBHOOK): POSTs to the run_target bulk entities endpoint with upsert=true, building one target entity per object in the initiative's target_entities array with status Pending.
   - start_targets (WEBHOOK): bulk-upserts the same targets with status Running so the per-target executor's Pending-to-Running trigger fires reliably.
   Connections: trigger to bulk_create_targets to start_targets.

4. Create a Port workflow with identifier "agentic_target_executor", title "Execute task on a single service":
   - manual_trigger (SELF_SERVE_TRIGGER) on the service blueprint, with a required "prompt" text input and the triggering service as context.
   - fetch_service (WEBHOOK, GET): reads the service entity to get its title, repo URL, and identifier.
   - create_run_target (UPSERT_ENTITY): creates a run_target entity with status Running for the manual path.
   - trigger (EVENT_TRIGGER): fires on ENTITY_UPDATED for run_target where status changed from Pending to Running.
   - fetch_agentic_initiative (WEBHOOK, GET): reads the parent initiative to get its prompt, when the run came from the fan-out path.
   - cursor_agent (CURSOR_AGENT): launches a Cursor agent using {{ .secrets["CURSOR_API_KEY"] }}, using the initiative prompt or the manual prompt, targeting the run target's repository, with autoCreatePr true.
   - check_success (CONDITION): branches on whether the Cursor agent finished successfully.
   - update_target_pr (UPSERT_ENTITY, success branch): writes pr_url and status "PR Opened" back to the run_target.
   - update_target_failed (UPSERT_ENTITY, failure branch): writes status "Failed" and an error_message back to the run_target.
   - link_pr_entity (AI): looks up the matching githubPullRequest entity by PR link and sets the run_target's pull_request relation.
   Connections: both trigger paths converge on cursor_agent, which flows to check_success, which branches to update_target_pr (then link_pr_entity) or update_target_failed.

5. Create a Port workflow with identifier "begin_agentic_initiative", title "Begin Agentic Initiative":
   - trigger (SELF_SERVE_TRIGGER): scoped to agentic_initiative entities where status equals Draft, with an ENTITY context on the initiative input so it appears in the bolt menu.
   - start_initiative (UPSERT_ENTITY): sets the initiative status to Running.
   Connection: trigger to start_initiative.

6. Create a Port workflow with identifier "sync_run_target_pr_merged", title "Sync PR merge status to run targets":
   - trigger (EVENT_TRIGGER): fires on ENTITY_UPDATED for githubPullRequest where status changed to merged.
   - find_run_target (WEBHOOK, POST search): finds run_target entities related to the merged pull request, falling back to a pr_url match if the relation isn't set yet.
   - mark_merged (UPSERT_ENTITY): sets the related run_target status to Merged.
   Connections: trigger to find_run_target to mark_merged.

7. Add the required secret in Port Settings > Secrets:
   - CURSOR_API_KEY: the Cursor API key.

Use Port MCP to create each artifact. Confirm each step before moving to the next.

Prerequisites

• A Port account.
• Port's GitHub Ocean integration installed, with service entities carrying a repo_url property (mirrored from the repository).
• A scorecard on the service blueprint with at least one rule a coding agent can actually fix, such as a missing CODEOWNERS file or a missing PR template. See Ensure production readiness if you don't have one yet.
• A Cursor API key.

Adapt to your stack

This guide uses Cursor as the coding agent and GitHub as the source of repositories. The pattern is the same with any coding agent that accepts a prompt and a repository, and any Git provider Port ingests.

Data model

Two blueprints carry this pattern:

• agentic_initiative - one entity per fix effort. Holds the prompt given to the agent, the approval policy, and the list of target services. Its aggregation properties (total_targets, targets_pending, targets_running, targets_pr_opened, targets_merged, targets_failed) count the related run_target entities by status, so the initiative always shows live progress without a separate dashboard build.
• run_target - one entity per service touched by an initiative. Tracks that single service's run: status, the pull request it opened, CI result, and a link back to its parent initiative.

agentic_initiative blueprint (click to expand)

{
  "identifier": "agentic_initiative",
  "title": "Agentic Initiative",
  "icon": "Automation",
  "schema": {
    "properties": {
      "description": {
        "title": "Description",
        "type": "string",
        "format": "markdown"
      },
      "prompt": {
        "title": "Agent Prompt",
        "type": "string",
        "format": "markdown"
      },
      "approval_policy": {
        "title": "Approval Policy",
        "type": "string",
        "enum": ["auto-merge", "owner-approval", "pe-approval"],
        "enumColors": {
          "auto-merge": "yellow",
          "owner-approval": "green",
          "pe-approval": "blue"
        }
      },
      "status": {
        "title": "Status",
        "type": "string",
        "enum": ["Draft", "Running", "Completed", "Cancelled"],
        "enumColors": {
          "Draft": "lightGray",
          "Running": "orange",
          "Completed": "green",
          "Cancelled": "red"
        }
      },
      "target_blueprint": {
        "title": "Target Blueprint",
        "type": "string"
      },
      "reference_context": {
        "title": "Reference Context",
        "type": "array"
      },
      "target_entities": {
        "title": "Target Entities",
        "description": "JSON array of {serviceIdentifier, serviceTitle, repoUrl} objects, populated by Port AI before the run begins",
        "type": "array"
      }
    },
    "required": []
  },
  "aggregationProperties": {
    "total_targets": {
      "title": "Total Targets",
      "type": "number",
      "target": "run_target",
      "calculationSpec": { "calculationBy": "entities", "func": "count" }
    },
    "targets_pending": {
      "title": "Pending",
      "type": "number",
      "target": "run_target",
      "query": {
        "combinator": "and",
        "rules": [{ "property": "status", "operator": "=", "value": "Pending" }]
      },
      "calculationSpec": { "calculationBy": "entities", "func": "count" }
    },
    "targets_running": {
      "title": "Running",
      "type": "number",
      "target": "run_target",
      "query": {
        "combinator": "and",
        "rules": [{ "property": "status", "operator": "=", "value": "Running" }]
      },
      "calculationSpec": { "calculationBy": "entities", "func": "count" }
    },
    "targets_pr_opened": {
      "title": "PR Opened",
      "type": "number",
      "target": "run_target",
      "query": {
        "combinator": "and",
        "rules": [{ "property": "status", "operator": "=", "value": "PR Opened" }]
      },
      "calculationSpec": { "calculationBy": "entities", "func": "count" }
    },
    "targets_merged": {
      "title": "Merged",
      "type": "number",
      "target": "run_target",
      "query": {
        "combinator": "and",
        "rules": [{ "property": "status", "operator": "=", "value": "Merged" }]
      },
      "calculationSpec": { "calculationBy": "entities", "func": "count" }
    },
    "targets_failed": {
      "title": "Failed",
      "type": "number",
      "target": "run_target",
      "query": {
        "combinator": "and",
        "rules": [{ "property": "status", "operator": "=", "value": "Failed" }]
      },
      "calculationSpec": { "calculationBy": "entities", "func": "count" }
    }
  },
  "relations": {}
}

run_target blueprint (click to expand)

{
  "identifier": "run_target",
  "title": "Run Target",
  "icon": "Branch",
  "schema": {
    "properties": {
      "target_blueprint": {
        "title": "Target Blueprint",
        "type": "string"
      },
      "target_identifier": {
        "title": "Target Identifier",
        "type": "string"
      },
      "target_title": {
        "title": "Target Title",
        "type": "string"
      },
      "target_url": {
        "title": "Target URL",
        "type": "string",
        "format": "url"
      },
      "status": {
        "title": "Status",
        "type": "string",
        "enum": ["Pending", "Running", "PR Opened", "Merged", "Failed", "Skipped"],
        "enumColors": {
          "Pending": "lightGray",
          "Running": "orange",
          "PR Opened": "blue",
          "Merged": "green",
          "Failed": "red",
          "Skipped": "darkGray"
        }
      },
      "pr_url": {
        "title": "PR URL",
        "type": "string",
        "format": "url"
      },
      "pr_ci_status": {
        "title": "CI Status",
        "type": "string",
        "enum": ["pending", "passing", "failing"],
        "enumColors": {
          "pending": "yellow",
          "passing": "green",
          "failing": "red"
        }
      },
      "error_message": {
        "title": "Error Message",
        "type": "string"
      },
      "agent_log_url": {
        "title": "Agent Log URL",
        "type": "string",
        "format": "url"
      },
      "team_notified": {
        "title": "Team Notified",
        "type": "boolean"
      }
    },
    "required": []
  },
  "relations": {
    "service": {
      "title": "Service",
      "target": "service",
      "required": false,
      "many": false
    },
    "pull_request": {
      "title": "Pull Request",
      "target": "githubPullRequest",
      "required": false,
      "many": false
    },
    "agentic_initiative": {
      "title": "Agentic Initiative",
      "target": "agentic_initiative",
      "required": false,
      "many": false
    }
  }
}

Build it step by step

---

Track progress

The initiative's aggregation properties are the tracking view: total_targets, targets_pending, targets_running, targets_pr_opened, targets_merged, and targets_failed are counted live from the related run_target entities, so the entity page for any initiative already shows where it stands. The targets_merged count updates only after the workflow from step 5 propagates GitHub merge events onto linked run_target entities.

For a portfolio view across every initiative, add a table widget to a dashboard page scoped to the agentic_initiative blueprint, with the aggregation properties as columns. Add a second table scoped to run_target, grouped by status, when you want to see every pull request an initiative opened in one place.

What you built

A platform engineer approves a Draft initiative. Port bulk-creates one run_target per service in its target list, starts each target, launches a Cursor agent against each repository, and writes the resulting pull request, CI status, and outcome back to that target. When pull requests merge, a follow-up workflow updates each linked target to Merged. The initiative entity rolls every target's status up into a single set of counts, so there's one place to check whether a fleet-wide fix is done, in progress, or stuck.

What's next

• Route approval by criticality - extend step 4 so approval_policy and the target service's tier decide whether a PR needs a human before merge, not just whether the initiative can start.
• Populate target_entities automatically - connect Port AI to your scorecard's failing-rule results so a Draft initiative appears on its own, instead of being created by hand.
• Notify the owning team - use the team_notified property on run_target to drive a Slack message when a PR opens on a service that team owns.
• Add code review enrichment - the PR Enricher agent can surface catalog context on every PR this pattern opens.

For the full picture of where this pattern fits, see Agentic initiatives and the ATR solution overview.