Quickstart - Humans + AI Agents

This guide walks you through setting up a complete beeps system with human responders and AI agents working in parallel. New to beeps? Read Core Concepts first to understand how the pieces fit together.

What You’ll Build

By the end of this guide, you’ll have:

• A relay that receives alerts
• A schedule with team members rotating on-call
• Contact methods (email and SMS) for notifications
• An AI agent integration for automated triage
• Parallel routing: alerts go to both humans and AI simultaneously

Prerequisites

• A beeps account
• An API key from your organization settings (looks like bk_xxxxxxxx)

Prefer the CLI or MCP?

Skip to Quickstart via CLI to set up from the command line, or Quickstart via MCP to manage alerts from Claude Code or Codex.

Step 1: Install the SDK and Initialize the Client

npm

npm install @beepsdev/sdk

pnpm

pnpm add @beepsdev/sdk

bun

bun add @beepsdev/sdk

Set your API key:

export BEEPS_API_KEY="bk_your_api_key_here"

Create a new file beeps.config.ts:

import { BeepsClient } from "@beepsdev/sdk";

const client = new BeepsClient({
  apiKey: process.env.BEEPS_API_KEY,
});

Step 2: Create a Relay

Create a relay, which is the pipeline that receives alerts and routes them through rules.

const relay = await client.relay.create({
  name: "production relay",
  description: "routes critical production incidents",
  externalKey: "production::relay",
});

Use externalKey for Idempotency

Always set externalKey on relays, schedules, and rules. This makes your config idempotent — safe to re-run without creating duplicates. Think of externalKey as a stable identifier you control, while id is generated by beeps.

Related: Managing Relays

Step 3: Create an On-Call Schedule

Create a schedule to define who is on-call and when rotations happen.

const schedule = await client.schedule.create({
  name: "Primary On-Call",
  relayId: relay.id,
  type: "weekly",
  handoffDay: "monday",
  handoffTime: "09:00", // UTC
  externalKey: "primary::schedule",
});

Omitting startAt here is intentional. beeps defaults it to the current time so the schedule starts immediately and you can test alerts right away.

Related: Managing Schedules

Step 4: Add Team Members to Schedule

Add users to the on-call rotation by email address:

await client.schedule.addMember(schedule.id, {
  email: "alice@example.com",
});

await client.schedule.addMember(schedule.id, {
  email: "bob@example.com",
});

You can also add members by user ID if you have it:

await client.schedule.addMember(schedule.id, {
  userId: "usr_alice",
});

Members rotate in the order they’re added.

Related: Schedule Members

Step 5: Configure Contact Methods

Contact methods define how users receive notifications. Your signup email is automatically added as a verified contact method when you create your account.

To add SMS or additional email contact methods, go to Settings > Profile in the beeps web UI. SMS contact methods require verification via a confirmation text.

Related: Contact Methods Overview

You can stop here if you don’t need AI agents

At this point, you have a working human-only on-call setup. Skip to Step 7 and create only the human notification rule (Rule 2).

Step 6: Set Up AI Agent Integration

Add an integration to store credentials for your AI agent. For this quickstart, use Cursor and get an API key from the Cursor dashboard.

Cursor requirements

Enable Privacy Mode in your Cursor account settings before using the API. Cursor agent rules also require a repository URL in the rule config.

const integration = await client.integration.create({
  name: "Cursor Agent",
  provider: "cursor",
  apiKey: process.env.CURSOR_API_KEY,
  metadata: {
    environment: "production",
  },
});

Related: Managing Integrations

Step 7: Create Parallel Relay Rules

Create rules that route alerts to responders. These rules run in parallel so AI agents and humans both get notified simultaneously.

Rule 1: AI Agent (Cursor)

await client.relay.rules.create(relay.id, {
  name: "AI Agent Auto-Triage",
  externalKey: "agents::cursor",
  ruleType: "agent",
  group: "agents",
  order: 1,
  config: {
    agentType: "cursor",
    integrationId: integration.id,
    repository: "https://github.com/your-org/your-repo",
    autoCreatePr: true,
    pollInterval: 30000,
    maxPollAttempts: 120,
  },
  enabled: true,
});

Rule 2: Human On-Call

await client.relay.rules.create(relay.id, {
  name: "Notify On-Call Engineer",
  externalKey: "humans::primary::schedule-notify",
  ruleType: "schedule_notify",
  group: "humans",
  order: 1,
  config: {
    scheduleId: schedule.id,
  },
  enabled: true,
});

Rules in different groups ("agents" vs "humans") run in parallel. Both the AI agent and human receive the alert simultaneously.

Related: Relay Rules

Step 8: Verify Your Setup

List all rules to confirm configuration:

const rules = await client.relay.rules.list(relay.id);

console.log("\nRelay Rules:");
rules.forEach((rule) => {
  console.log(`  [${rule.group}] ${rule.name}`);
  console.log(`    Type: ${rule.ruleType}`);
  console.log(`    Enabled: ${rule.enabled}`);
});

Complete Config

Here’s the complete beeps.config.ts combining all steps:

import { BeepsClient } from "@beepsdev/sdk";

async function configure() {
  const client = new BeepsClient({
    apiKey: process.env.BEEPS_API_KEY,
  });

  // 1. Create relay
  const relay = await client.relay.create({
    name: "production relay",
    description: "routes critical production incidents",
    externalKey: "production::relay",
  });

  // 2. Create schedule
  const schedule = await client.schedule.create({
    name: "Primary On-Call",
    relayId: relay.id,
    type: "weekly",
    handoffDay: "monday",
    handoffTime: "09:00",
    // startAt omitted -> schedule starts immediately
    externalKey: "primary::schedule",
  });

  // 3. Add team members by email
  await client.schedule.addMember(schedule.id, { email: "alice@example.com" });
  await client.schedule.addMember(schedule.id, { email: "bob@example.com" });

  // 4. Contact methods are managed in Settings > Profile in the web UI.
  //    Each user's signup email is automatically added as a verified contact method.
  //    SMS and additional emails can be added from the profile settings.

  // 5. Create AI integration
  const integration = await client.integration.create({
    name: "Cursor Production Agent",
    provider: "cursor",
    apiKey: process.env.CURSOR_API_KEY,
    externalKey: "agents::cursor::integration",
  });

  // 6. Create relay rules (parallel: agents + humans)
  await client.relay.rules.create(relay.id, {
    name: "AI Agent Auto-Triage",
    externalKey: "agents::cursor",
    ruleType: "agent",
    group: "agents",
    order: 1,
    config: {
      agentType: "cursor",
      integrationId: integration.id,
      repository: "https://github.com/your-org/your-repo",
      autoCreatePr: true,
    },
    enabled: true,
  });

  await client.relay.rules.create(relay.id, {
    name: "Notify On-Call Engineer",
    externalKey: "humans::primary::schedule-notify",
    ruleType: "schedule_notify",
    group: "humans",
    order: 1,
    config: {
      scheduleId: schedule.id,
    },
    enabled: true,
  });

  // 7. Verify
  const rules = await client.relay.rules.list(relay.id);
  console.log("\nRelay Rules:");
  rules.forEach((rule) => {
    console.log(`  [${rule.group}] ${rule.name}`);
    console.log(`    Type: ${rule.ruleType}`);
    console.log(`    Enabled: ${rule.enabled}`);
  });
}

configure().catch(console.error);

Run it:

export BEEPS_API_KEY="bk_your_key_here"
export CURSOR_API_KEY="cursor_api_key_here"

npx tsx beeps.config.ts

Test Your Configuration

Send a test alert to your relay’s webhook URL (found in your relay’s details):

curl -X POST https://hooks.beeps.dev/YOUR_WEBHOOK_ID \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Alert",
    "message": "Testing the on-call system",
    "severity": "high"
  }'

You should see:

• The AI agent (Cursor) receives the alert and starts triaging
• The on-call engineer receives an email/SMS notification
• Both happen simultaneously!

Deploy Your Config

Since beeps.config.ts uses externalKey everywhere, it’s idempotent and safe to re-run. Treat it like database migrations — check it into your repo and run it in CI on merge.

GitHub Actions

name: Deploy beeps config

on:
  push:
    branches: [main]
    paths: [beeps.config.ts]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm install @beepsdev/sdk
      - run: npx tsx beeps.config.ts
        env:
          BEEPS_API_KEY: ${{ secrets.BEEPS_API_KEY }}
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}

Changes to your on-call config go through PR review like any other code change.

Understanding Parallel Execution

Alert Received
    |
Relay: "production relay"
    |
    |-- [agents] AI Agent Auto-Triage --> Cursor starts working
    |
    |-- [humans] Notify On-Call Engineer --> Email/SMS sent

Both rules run in parallel because they’re in different groups ("agents" and "humans").

Common Customizations

Sequential Instead of Parallel

To run AI first, then escalate to humans, use the same group:

await client.relay.rules.create(relay.id, {
  name: "Try AI first",
  ruleType: "agent",
  group: "default",
  order: 1,
  config: {
    agentType: "cursor",
    integrationId: integration.id,
    repository: "https://github.com/your-org/your-repo",
  },
});

await client.relay.rules.create(relay.id, {
  name: "Escalate to humans",
  ruleType: "schedule_notify",
  group: "default",
  order: 2,
  config: { scheduleId: schedule.id },
});

Add a Secondary Schedule

await client.relay.rules.create(relay.id, {
  name: "Escalate to backup",
  ruleType: "schedule_notify",
  group: "humans",
  order: 2,
  config: { scheduleId: backupSchedule.id },
});

Next Steps

• Add more team members to the rotation
• Configure escalation rules for unresponded alerts
• Set up webhooks for Slack/PagerDuty integration
• Monitor active alerts through the SDK or CLI
• Connect monitoring tools like Sentry or Datadog
• Set up MCP tools for Claude Code or Codex
• Manage everything from the CLI with config-as-code

Quickstart via CLI

You can set up the same system entirely from the command line.

Step 1: Install and authenticate

npm install -g @beepsdev/cli
export BEEPS_API_KEY="bk_your_key_here"

Step 2: Create a relay

beeps relay create --name "production relay" \
  --external-key production::relay \
  --description "routes critical production incidents"

Step 3: Create a schedule

beeps schedule create \
  --name "Primary On-Call" \
  --relay-id rly_abc123 \
  --type weekly \
  --handoff-day monday \
  --handoff-time 09:00 \
  --external-key primary::schedule

Step 4: Add team members

beeps schedule add-member --schedule-id sch_abc123 --email alice@example.com
beeps schedule add-member --schedule-id sch_abc123 --email bob@example.com

Members rotate in the order they’re added.

Step 5: Set up an AI agent integration

export CURSOR_API_KEY="cursor_api_key_here"
beeps integration create --provider cursor --name "Cursor Agent" --api-key-env CURSOR_API_KEY

Step 6: Create relay rules

Create rules that route alerts to both AI and humans in parallel:

beeps relay rule create --relay-id rly_abc123 \
  --name "AI Agent Auto-Triage" \
  --rule-type agent \
  --group agents \
  --order 1 \
  --external-key agents::cursor \
  --config '{"agentType":"cursor","integrationId":"int_abc123","repository":"https://github.com/your-org/your-repo","autoCreatePr":true}'

beeps relay rule create --relay-id rly_abc123 \
  --name "Notify On-Call Engineer" \
  --rule-type schedule_notify \
  --group humans \
  --order 1 \
  --external-key humans::primary \
  --config '{"scheduleId":"sch_abc123"}'

Rules in different groups (agents vs humans) run in parallel.

Step 7: Verify your setup

beeps relay list
beeps relay rule list --relay-id rly_abc123
beeps schedule on-call --schedule-id sch_abc123
beeps integration list

Respond to alerts

Once alerts start flowing:

beeps alert list --active
beeps alert on-it --alert-id alr_abc123
beeps alert resolve --alert-id alr_abc123

Config-as-Code

Once you’re comfortable, you can manage everything declaratively with a config file and beeps relay apply. See CLI Config-as-Code for details and CI deployment examples.

Quickstart via MCP

If you use Claude Code, Codex, or any MCP-compatible client, you can manage alerts and on-call directly from your editor.

Step 1: Connect the MCP server

Claude Code

claude mcp add --transport http --scope user beeps https://mcp.beeps.dev/mcp

Codex

codex mcp add beeps --url https://mcp.beeps.dev/mcp
codex mcp login beeps --scopes "openid,profile,email,offline_access,beeps.tools.read,beeps.tools.write"

Step 2: Check who’s on call

Who's on call for the primary schedule?

Step 3: Triage alerts

Show me all active alerts

Are there any critical alerts right now?

Step 4: Respond to an alert

I'm on it for alert alr_abc123

Load the fix context for alert alr_abc123 and help me resolve it

Step 5: Resolve

Mark my response as done with PR https://github.com/org/repo/pull/42

Resolve alert alr_abc123

Step 6: Manage schedules

Set a schedule override for the primary schedule — put Bob on call from now until Friday

For the full list of 27 MCP tools, see MCP Server.

Troubleshooting

If you encounter issues, see the Troubleshooting Guide for solutions:

• Alerts not appearing
• No one receiving notifications
• AI agent not responding
• Rules not executing