Delegating agents

​

Choosing which agent runs

​

Cursor

​

Your own platform

​

How a delegated task flows

1. A responder asks for a code change (for example from the incident channel), and we render a self-contained markdown brief: the incident title and reference, the repository, the user’s instructions, our expectations for the PR, and a snapshot of the investigation so far.
2. We call POST /agents on your platform with the brief and structured identifiers, plus a per-launch webhook URL and signing secret.
3. Your platform starts a run and responds with a run ID and a link to its own UI, which we surface in Slack.
4. While the run is in flight, you send signed status callbacks to the webhook, or we poll GET /agents/{id} every 2 minutes. Both work.
5. Your agent opens a draft PR with its own GitHub credentials and reports finished with the PR URL. We attach the PR to the incident and move the task into review.
6. If a responder asks for changes, we call POST /agents/{id}/followup with the new instructions, and the same run updates the same PR.

​

The interface you implement

​

POST /agents: launch

{
  "task_id": "01JXAMPLE7AXZ2C93K61WBPYEH",
  "prompt": "<self-contained markdown brief>",
  "incident_id": "01JXAMPLE0INCIDENT0ID0000",
  "reference": "INC-123",
  "investigation_id": "01JXAMPLE0INVESTIGATION00",
  "repository": "acme/payments-service",
  "webhook": {
    "url": "https://app.incident.io/webhooks/code-agent/custom/<org_id>",
    "secret": "<hmac secret>"
  }
}

• task_id is our identifier for the request. Treat it as an idempotency key: if you receive a second launch with a task_id you’ve already started, return the existing run rather than starting another.
• prompt is the rendered brief. It’s self-contained, so an agent with no other context can act on it.
• incident_id, reference and investigation_id are also embedded in the prompt, but exposed as structured fields so your harness can fetch live data through our MCP server without parsing markdown. They’re omitted when the task has no incident or investigation.
• webhook is where to send status callbacks for this run, and the secret to sign them with. You may ignore it and rely on polling, but webhook-driven updates feel noticeably faster in Slack.

{ "id": "run_8f2k1", "url": "https://agents.example.com/runs/run_8f2k1" }

• id is your opaque run identifier. We include it in every subsequent call.
• url (optional) links to your platform’s UI for the run and is shown to responders in Slack.

​

GET /agents/{id}: status

{
  "id": "run_8f2k1",
  "status": "running",
  "summary": "Reproduced the bug, writing a regression test",
  "pr_url": "",
  "branch": ""
}

• status is one of running, finished or error.
• summary is a short progress message. We show the latest one in Slack, so keep it human-readable and current.
• pr_url is required when reporting finished. A finished status without a PR URL is treated as a failure, not as “almost done”, so report running until the PR exists.
• branch (optional) is the feature branch the agent pushed to.

​

POST /agents/{id}/followup: iteration

{ "instructions": "Also handle the retry case in the worker" }

​

POST /agents/{id}/stop: cancel

​

GET /ping: connection test

​

The webhook you send us

X-Webhook-Signature: sha256=<hex(HMAC-SHA256(secret, raw request body))>

• Send one whenever the run meaningfully progresses: on completion at minimum, and ideally on summary changes too.
• Our handling is idempotent, and the webhook and our poller converge on the same logic, so duplicate or out-of-order deliveries are harmless.
• You don’t need a retry pipeline: if a delivery fails, our 2-minute poll picks the status up. (Retries are welcome all the same.)
• We respond 200 even for runs we no longer track, so you can fire-and-forget.

​

Timing expectations

​

What this interface doesn’t do

​

Giving your agent live incident data

• investigation_sync downloads the complete investigation (findings, hypotheses, check outputs) as an archive via a short-lived signed URL.
• incident_show and alert_show fetch the live incident and related alerts.

​

Security model

1. Us → your API: the bearer token you issue and paste into our dashboard. We store it encrypted and send it on every call. Rotate it by reconnecting with a new token.
2. You → our webhook: the HMAC secret we generate when you connect, delivered to you inside each launch request. You never need to store it long-term. Sign each run’s callbacks with the secret that run was launched with.
3. Your agent → our MCP: an incident.io API key you create and configure into your agent environment, governed by the same scopes as any other API key.

​

Related