Skip to main content

​
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

1

Gateway fires heartbeat

The gateway fires a heartbeat at configured intervals
2

Agent receives message

The agent receives a special heartbeat message
3

Agent checks for work

The agent checks for pending tasks, schedules, and conditions
4

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

SettingDefaultDescription
enabledtrueEnable/disable heartbeat
interval300000Interval in milliseconds (5 minutes)
taskChecktrueCheck 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:
  1. Queries pending tasks ordered by priority
  2. Picks the highest-priority task
  3. Starts the task (status -> in_progress)
  4. Works on it using available tools
  5. 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