Send agent heartbeats with Python or Node

Use the source checkout

These examples use the SDK code in the AgentPager repository. They do not imply a published package registry release. For Python, install the source project in your own environment. The Node example imports the repository SDK directly.

Local mode needs no account. It creates a spool directory in your working directory unless AGENTPAGER_SPOOL is set.

Python lifecycle signals

from agentpager import Client

pager = Client()  # local spool, no hosted account required
pager.run_started("example-worker", "example-run")
pager.beat("example-worker", note="working")
pager.run_progress("example-worker", "example-run", progress=1)
pager.run_finished("example-worker", "example-run")
pager.flush()  # persist queued beats; attempt delivery if configured

Use a unique run ID for each job. Progress should change when useful work advances, rather than on every timer tick.

Node lifecycle signals

import { Client } from './sdks/node/index.js';

const pager = new Client();
pager.runStarted('example-worker', 'example-run');
pager.beat('example-worker', 'working');
pager.runProgress('example-worker', 'example-run', 1);
pager.runFinished('example-worker', 'example-run');
await pager.flush();

Await flush before an orderly shutdown. Calling beat queues an event; it does not by itself send a network request.

Connect hosted ingestion

1. Sign in to your isolated beta organization.
2. Register an agent name and choose rules in the dashboard.
3. Create an SDK ingest key and store it privately.
4. Set AGENTPAGER_URL to https://agentpager.io and AGENTPAGER_KEY to that key in your process environment.
5. Use the exact registered name in your SDK calls. Flush periodically and at shutdown.

Do not paste keys into source code, screenshots, heartbeat notes or incident metadata. Ingest keys are not dashboard sessions: they cannot read incidents or request control.

What local durability does and does not cover

Queued events are written to disk. Flush attempts delivery when a URL and key are configured; failed sends remain spooled for a later attempt. An abrupt kill before persistence can still lose recent beats. Local filesystem failure can prevent persistence.

Local mode is not proof of a healthy hosted pipeline, inbox delivery or successful remote control. Test those separately before relying on alerts.

Choose rules before you page

Read the heartbeat monitoring guide for cadence, progress, privacy and control limits. AgentPager is a free beta, with no billing or safety guarantee.

Return to AgentPager.