Heartbeat System

Overview

The heartbeat system periodically wakes the agent even when no user messages are coming in. This enables autonomous behaviors like:

Working through the task queue
Checking for scheduled actions
Proactive status updates
Background maintenance

How It Works

Gateway fires heartbeat

The gateway fires a heartbeat at configured intervals

Agent receives message

The agent receives a special heartbeat message

Agent checks for work

The agent checks for pending tasks, schedules, and conditions

Agent processes or returns to idle

If there is work to do, the agent processes it. If not, the agent returns to idle.

Configuration

{
  "gateway": {
    "heartbeat": {
      "enabled": true,
      "interval": 300000,
      "taskCheck": true,
      "quietHours": {
        "start": "22:00",
        "end": "07:00",
        "timezone": "America/Chicago"
      }
    }
  }
}

Settings

Setting	Default	Description
`enabled`	`true`	Enable/disable heartbeat
`interval`	`300000`	Interval in milliseconds (5 minutes)
`taskCheck`	`true`	Check task queue on each heartbeat
`quietHours`	—	Suppress heartbeats during these hours

Quiet Hours

During quiet hours, the heartbeat is suppressed to avoid unnecessary API calls and potential notifications during off-hours:

{
  "quietHours": {
    "start": "22:00",
    "end": "07:00",
    "timezone": "America/Chicago"
  }
}

Urgent tasks can override quiet hours.

Task Queue Integration

When taskCheck is enabled, each heartbeat:

Queries pending tasks ordered by priority
Picks the highest-priority task
Starts the task (status -> in_progress)
Works on it using available tools
Completes or blocks the task

This means high-priority tasks get worked on automatically without user intervention.

Cost Considerations

Each heartbeat that triggers agent work uses API tokens. Consider the following to manage costs:

Longer intervals reduce cost (15-30 minutes instead of 5)
Use the LOCAL tier for simple heartbeat checks
Quiet hours prevent unnecessary spending during off-hours
Disable heartbeat entirely if autonomous work is not needed

Monitoring

# Check last heartbeat time
argent gateway status

# View heartbeat activity in logs
argent gateway logs --filter heartbeat

Web UI

Dashboard

Tasks

Gateway & Ops

Intent & Safety

Security

Overview

How It Works

Configuration

Settings

Quiet Hours

Task Queue Integration

Cost Considerations

Monitoring

​Overview

​How It Works

​Configuration

​Settings

​Quiet Hours

​Task Queue Integration

​Cost Considerations

​Monitoring

Overview

How It Works

Configuration

Settings

Quiet Hours

Task Queue Integration

Cost Considerations

Monitoring