pagerduty-agent

# PagerDuty Agent

> ⚠️ This is an unofficial community skill and is not affiliated with or endorsed by PagerDuty, Inc.

Trigger, acknowledge, and resolve PagerDuty incidents, check who's on-call,
manage maintenance windows, and inspect services — all without leaving your
agent workflow.

## Setup

1. Generate a PagerDuty API key: **PagerDuty → Integrations → API Access Keys → Create New API Key**
2. Export required environment variables:

```bash
export PAGERDUTY_API_KEY="your-v2-api-key"
export PAGERDUTY_FROM_EMAIL="you@yourcompany.com"   # required for write operations
```

> `PAGERDUTY_FROM_EMAIL` must be the email of a valid PagerDuty user in your
> account. It is required by PagerDuty's REST API for any POST/PUT request.

## Usage

All commands are invoked by piping a `{ command, params }` JSON object to
`node pagerduty.js`. The skill returns structured JSON on stdout.

```bash
echo '{"command":"list_incidents","params":{"status":"triggered"}}' | node pagerduty.js
```

---

## Commands

### Incidents

---

#### `trigger_incident`

Create a new incident on a service.

**Params**

| Field | Type | Required | Description |
|---|---|---|---|
| `service_id` | string | ✓ | PagerDuty service ID (e.g. `"P1ABCDE"`) |
| `title` | string | ✓ | Incident title / summary |
| `severity` | string | | `"critical"`, `"error"`, `"warning"`, `"info"` — maps to urgency |
| `body` | string | | Detailed description / runbook context |

**Example**

```json
{
  "command": "trigger_incident",
  "params": {
    "service_id": "P1ABCDE",
    "title": "Database replication lag > 60s",
    "severity": "critical",
    "body": "Replica db-02 is 90s behind primary. Check pg_stat_replication."
  }
}
```

**Response**

```json
{
  "id": "Q2W3E4R",
  "incident_number": 1042,
  "title": "Database replication lag > 60s",
  "status": "triggered",
  "urgency": "high",
  "html_url": "https://your-subdomain.pagerduty.com/incidents/Q2W3E4R",
  "created_at": "2026-03-04T12:00:00Z",
  "service": { "id":...