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.
Connection: trigger to bulk_create_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 self-service action with identifier "begin_agentic_initiative", title "Begin Agentic Initiative", on the agentic_initiative blueprint, DAY-2 operation, visible only when status equals Draft. Its invocation upserts the same entity with status set to Running.
6. 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
serviceentities carrying arepo_urlproperty (mirrored from the repository). - A scorecard on the
serviceblueprint 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 relatedrun_targetentities 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.
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, launches a Cursor agent against each repository, and writes the resulting pull request, CI status, and outcome back to that target. 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_policyand the target service's tier decide whether a PR needs a human before merge, not just whether the initiative can start. - Populate
target_entitiesautomatically - 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_notifiedproperty onrun_targetto 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.