> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Heartbeat System

> Periodic agent wake-ups for autonomous task work and proactive check-ins.

## 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

<Steps>
  <Step title="Gateway fires heartbeat">
    The gateway fires a heartbeat at configured intervals
  </Step>

  <Step title="Agent receives message">
    The agent receives a special heartbeat message
  </Step>

  <Step title="Agent checks for work">
    The agent checks for pending tasks, schedules, and conditions
  </Step>

  <Step title="Agent processes or returns to idle">
    If there is work to do, the agent processes it. If not, the agent returns to idle.
  </Step>
</Steps>

## Configuration

```json theme={null}
{
  "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:

```json theme={null}
{
  "quietHours": {
    "start": "22:00",
    "end": "07:00",
    "timezone": "America/Chicago"
  }
}
```

<Info>
  Urgent tasks can override quiet hours.
</Info>

## 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

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

* 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

```bash theme={null}
# Check last heartbeat time
argent gateway status

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