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

# Design Useful Computer Agent Heartbeats

> Give a Computer Agent periodic awareness without creating noisy, repetitive, or unactionable alerts.

A heartbeat gives a Computer Agent periodic opportunities to notice something important and decide
whether action or attention is required. It is best for awareness and judgment, not for a rigid job
that must run on an exact schedule.

## Heartbeat or repeating Task?

| Use a heartbeat when                                                                     | Use a repeating Task when                                    |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| The Agent should survey current conditions and decide whether anything material changed. | A defined workflow must run on a known schedule.             |
| Silence is the correct result when nothing needs attention.                              | Every run needs a visible result and run history.            |
| Several signals may affect whether the Agent should act.                                 | The source, inputs, and completion criteria are predictable. |

## Write useful heartbeat instructions

Define:

* the systems and records the Agent should review
* the time window or freshness requirement
* what qualifies as a legitimate issue
* what measurable improvement is worth suggesting
* actions it may take without approval
* when it should alert a person
* when it should remain quiet

Avoid prompts such as “check everything and report problems.” They create noise and make it hard to
distinguish a real risk from routine activity.

## Set an alert threshold

Ask the Agent to notify people only when:

* a real issue remains unresolved
* a customer commitment or deadline is at risk
* approval or information is required
* a specific change is likely to produce a measurable improvement

A transient tool failure that recovers during the same heartbeat should not become a customer-facing
alert.

## Test and review

Run the heartbeat under normal conditions, a known issue, and an inconclusive condition. Review its
heartbeat conversation to see what it checked and why it did or did not alert.

Revisit the instructions when the Agent's responsibilities, connected systems, or customer risk
change. Use a repeating Task instead when the heartbeat evolves into one deterministic workflow.