AGENTPAGER GUIDE
Agent heartbeat monitoring: what a beat can tell you
A heartbeat says an agent reached a checkpoint. It does not prove that its work is useful, correct or complete.
Start with an explicit cadence
Register an agent, choose its expected cadence and send beats from the job. A silence rule opens an incident when the expected signal stops. Choose a threshold that tolerates normal pauses without hiding a stalled job.
Use an active UTC schedule when the agent should only run during certain hours. A missing beat outside that schedule should not be treated like a failure during a run.
Track progress separately from presence
An agent can keep sending heartbeats while making no progress. Send run_started, run_progress, run_finished and run_failed signals alongside ordinary beats. A loop rule can then distinguish a running job with unchanged progress from an idle agent.
Error-rate rules need enough samples to be meaningful. A single failure is not the same as a sustained failure rate.
Keep incident context small and safe
Include a short note and non-sensitive resource identifiers. Do not send passwords, API keys, personal data or raw prompts. The incident timeline can include beats, rule context, escalation attempts and acknowledgment actions.
Cost and resource metadata are supplied by the agent or receipt sender. They are not independently verified billing or access evidence.
Account for offline delivery
The Python and Node SDKs queue beats locally. Call flush on a cadence and at orderly shutdown. A beat call alone does not send network traffic. Abrupt termination before persistence can lose recent queued events.
Registration is required before hosted ingestion. Ingest keys cannot read incidents or request control.
Acknowledgment is not remote execution
Acknowledgment cancels pending pages, not a message already in flight. Signed kill or restart requests require an agent-provided control endpoint. Receiver acceptance is not confirmation that the agent stopped.
The pager itself needs an independent dead-man check. A healthy application response is not proof that a real alert will reach a person.
Try the SDK locally
Follow the Python and Node SDK quickstart for lifecycle signals, local spool and hosted ingestion setup.
Current beta boundaries
AgentPager is a free beta with no billing or safety guarantee. Multi-user organization invitations and rotations are not available. Webhooks require an operator-approved public HTTPS host. SMS and voice are blocked in this beta. Provider acceptance is not inbox delivery.