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)

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: 20
      - 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
• Connect monitoring tools like Sentry or Datadog
• Set up MCP tools for Claude Code or Codex

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