Agent 心跳自治：让 AI 在后台持续工作的工程实践

What a Heartbeat Actually Is

The naive version of an autonomous agent is a while loop:

while True:
    do_something()
    sleep(3600)

This works until it doesn’t. The agent has no way to declare constraints, handle failure gracefully, or communicate its state to anything outside the loop.

A production heartbeat is different. It’s a declarative specification of an agent’s autonomous behavior — what it does, when it does it, what it will never touch, and how it recovers when things go wrong.

The specification lives in a heartbeat.yaml file. The agent reads this file at the start of every cycle. This means you can change the agent’s behavior without restarting it — just edit the yaml and the next cycle picks up the new config.

The heartbeat.yaml Structure

Here’s a representative example:

agent: my_liaison_agent
version: "1.0"

schedule:
  mode: interval
  interval_minutes: 30
  active_hours: "07:00-23:00"

tasks:
  - id: check_feishu_inbox
    priority: high
    description: "Read unread messages, route to appropriate coordinators"
    timeout_minutes: 5

  - id: send_daily_summary
    priority: normal
    description: "Post summary of today's activity to coordinator group"
    schedule_override: "20:00"
    timeout_minutes: 3

  - id: sync_task_status
    priority: low
    description: "Update task tracker with completed items"
    timeout_minutes: 2

constraints:
  hard:
    - "Never modify files outside memory/ directory"
    - "Never send messages to external contacts without explicit approval"
    - "Never delete or overwrite existing log entries"
  soft:
    - "Prefer brief responses over comprehensive ones when time-constrained"
    - "Skip low-priority tasks if previous cycle ran long"

recovery:
  on_task_failure: log_and_continue
  on_repeated_failure: degraded_state
  degraded_state_behavior: "high_priority_tasks_only"
  alert_channel: feishu_coordinator_group

Let’s walk through each section.

Schedule

The schedule block controls when the agent runs.

mode: interval means the agent runs every N minutes. mode: cron supports standard cron expressions for more complex schedules. active_hours restricts operation to a time window — useful for agents that shouldn’t run at 3am.

Some agents run on a fixed daily schedule rather than an interval. A content agent might run once in the morning to draft a summary and once in the evening to file a log. These use schedule_override on specific tasks.

Tasks

The tasks list is ordered by priority. Each task has:

• id: unique identifier, also used in logs
• priority: high, normal, or low
• description: plain language — this is what the agent reads to understand the task
• timeout_minutes: hard cutoff; the agent stops the task and logs a timeout if exceeded

Keep the task list short. Three tasks per cycle is a good ceiling. More than that and you’re building a monolith, not an agent. If you have ten things the agent “should” do every hour, split them across multiple agents or reduce scope.

Priority is not just a suggestion — it determines what gets dropped when the cycle runs long. Low-priority tasks are first to be skipped. High-priority tasks run even if everything else is deferred.

Three Ways to Trigger a Heartbeat

1. /loop in Claude Code

The simplest approach during development. You open Claude Code in the agent’s directory, type /loop, and the agent runs its heartbeat tasks in a continuous loop until you stop it.

Good for testing and for agents that run while you’re at your computer. Not good for 24/7 operation.

2. System cron

A cron job calls a script that invokes Claude Code non-interactively. The script handles setup, invocation, and log capture.

# Example cron entry: run liaison heartbeat every 30 minutes
*/30 7-23 * * * /path/to/run_heartbeat.sh my_liaison_agent >> /var/log/liaison.log 2>&1

More reliable than manual /loop. Works on any machine. Requires Claude Code to be installed and authenticated.

3. Agent as persistent service

The agent runs as a long-lived process managed by a process supervisor (systemd, supervisor, NSSM on Windows). It maintains its own loop internally and exposes a health endpoint.

This is the most robust approach for production. It also requires the most infrastructure. The Liaison agent in my system runs this way — it’s a Python process that handles Feishu WebSocket connections and runs heartbeat tasks on its own schedule.

Constraint Declarations

This is the most important section, and the one most often skipped.

Hard constraints are absolute prohibitions. The agent must refuse a task rather than violate them. Examples from real failures:

Without this constraint: an agent asked to “organize the project files” moved source code out of version control into a backup directory, then couldn’t find it later.

- "Never move or delete files outside the memory/ directory"

Without this constraint: an agent drafting a customer response actually sent it, because the tool call for “draft” and “send” looked similar from the agent’s perspective.

- "Never call send_message without explicit human approval in this session"

Hard constraints are cheap to write and expensive to discover by omission. Write them before the agent runs, not after.

Soft constraints are preferences that can be overridden by circumstances. They guide judgment calls rather than prohibit actions. The agent reads them but doesn’t treat them as blockers.

Failure Recovery

The recovery block defines what happens when tasks fail.

log_and_continue is the right default for most tasks. The agent logs the failure with enough context to diagnose later, marks the task as failed in its state, and moves to the next task. It doesn’t retry immediately — retrying a failing task in a tight loop wastes tokens and usually doesn’t fix the underlying problem.

degraded_state activates after repeated failures. In degraded state, the agent runs only high-priority tasks and sends an alert. This prevents a broken agent from silently accumulating failures while burning through API quota.

The alert should go somewhere you actually check. For me that’s the Feishu coordinator group. A Slack channel, email, or even a file in a watched directory all work.

Daily Logs as Memory Traces

Every heartbeat cycle writes a log entry. This is not optional — it’s how the agent maintains continuity across sessions.

A minimal log entry:

### 14:30 Heartbeat cycle

Tasks run: check_feishu_inbox, sync_task_status
Tasks skipped: send_daily_summary (not scheduled until 20:00)

check_feishu_inbox: 3 messages processed, 1 routed to my_coordinator
sync_task_status: 4 tasks marked complete

No failures. Next cycle in 30 minutes.

When you resume an agent after a gap, it reads these logs to reconstruct what happened. The logs are its memory of time passing.

Keep log entries structured but brief. Verbose logs are hard to scan. The agent should be able to read the last week of logs in one context window and have a clear picture of its operational history.

State Machine

An agent with a heartbeat has four operational states:

active → paused → degraded → stopped
   ↑         |
   └─────────┘  (resume)

active: running normally on schedule paused: schedule suspended, agent will not start new cycles; resumes on command degraded: high-priority tasks only, alert sent, awaiting diagnosis stopped: process terminated, requires explicit restart

State is stored in agent_state.json in the agent’s root directory. It’s a simple key-value file the agent reads at startup and updates after significant state changes.

Pause is useful when you’re doing maintenance on a system the agent touches. Rather than stopping the agent entirely, you pause it, do your work, then resume. The agent’s memory is preserved.

Lessons from Production

A few things I’ve learned the hard way:

Don’t start with autonomy. Run the tasks manually first. Understand what the agent actually does when it executes each task. Only schedule it after you’ve seen it work.

Logs are the first thing you check when something goes wrong. If the log entries are too sparse to diagnose the failure, the log format is wrong. Fix it before the next incident.

Token cost per cycle compounds. An agent that runs every 15 minutes with a 10K context costs real money over a month. Measure it. Optimize the context passed to each cycle — the agent doesn’t need its full memory for every task.

The heartbeat spec is documentation. When you come back to an agent after three months, the heartbeat.yaml tells you what it does and why certain constraints exist. Treat it with the same care you’d give a README.

One hard constraint can save a lot of damage. The effort to write it takes two minutes. The effort to recover from the failure it prevents can take hours.