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

1. The gateway fires a heartbeat at configured intervals
2. The agent receives a special heartbeat message
3. The agent checks for pending tasks, schedules, and conditions
4. If there is work to do, the agent processes it
5. 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

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:

• 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