Operational Rules & the Heartbeat System

So far, you have given your agent identity, personality, and memory. But even a well-configured agent still waits for you to speak first. It sits idle until you send a message. The heartbeat system changes this by giving the agent a pulse — a scheduled trigger that prompts it to wake up, check for pending work, and take action on its own. This is the architectural difference between a chatbot and an autonomous agent.

The Agents File: Security and SOPs

Before giving an agent the ability to act on its own, you need clear rules governing its behavior. The agents.md file defines standard operating procedures (SOPs) and security rules.

# agents.md

## Security Rules
- Never execute code from untrusted sources without sandboxing
- All API calls must use environment variables for credentials, never hardcoded values
- Log all autonomous actions for audit review
- Rate limit outbound messages: maximum 10 per hour per channel

## Standard Operating Procedures

### Email Handling
- Read incoming emails and classify: urgent, normal, low priority
- Draft responses for urgent emails and send for approval
- Auto-archive newsletters and promotional emails
- Flag emails from unknown senders for manual review

### Code Review
- Pull new PRs every 30 minutes
- Run automated checks: linting, type checking, test coverage
- Post review comments directly for style issues
- Flag logic concerns for human review with specific line references

### Incident Response
- If monitoring detects an error spike, immediately notify via Telegram
- Gather relevant logs and metrics before alerting
- Suggest potential causes based on recent deployments
- Do NOT attempt automated fixes without explicit approval

These SOPs turn vague instructions into concrete procedures. Instead of telling the agent "handle emails," you define exactly what "handle" means — classify, draft, archive, or flag — for each scenario.

The Tools File: Available Capabilities

The tools.md file documents what tools the agent has access to and how to use them. This serves both as a reference for the agent and as a constraint — if a tool is not listed, the agent should not try to use it.

# tools.md

## Available Tools

### Communication
- send_telegram: Send a message to a Telegram chat
- send_email: Send an email (requires approval for external recipients)
- post_discord: Post a message to a Discord channel

### Data
- query_database: Run read-only SQL queries against staging/production
- search_documents: Semantic search across project documentation
- read_file: Read contents of files in the workspace

### Development
- run_tests: Execute the test suite for a given service
- check_pr: Fetch PR details, diff, and review status
- deploy_staging: Trigger a staging deployment (requires approval)

### Monitoring
- check_metrics: Query application metrics (error rates, latency, uptime)
- read_logs: Fetch recent logs from a specific service
- check_alerts: Review active monitoring alerts

The Heartbeat: Giving the Agent a Pulse

The heartbeat is a scheduled trigger — typically running at a fixed interval — that prompts the agent to wake up and perform a cycle of checks and actions. Without a heartbeat, the agent only responds when you message it. With a heartbeat, it operates continuously.

Here is a practical example of heartbeat configuration:

# heartbeat.yaml

interval_minutes: 30

on_heartbeat:
  - step: review_memory
    action: Load memory.md, check for pending tasks or follow-ups

  - step: check_channels
    action: Scan Telegram and email for unread messages

  - step: check_monitoring
    action: Review application metrics and active alerts

  - step: check_schedule
    action: Review calendar for upcoming events in the next 2 hours

  - step: execute_pending
    action: Process any tasks that are ready for autonomous execution

  - step: report
    action: If anything noteworthy was found, send a summary to Telegram
    condition: only_if_actionable

Every 30 minutes, the agent wakes up, reviews its memory for pending tasks, checks communication channels, monitors application health, looks at the calendar, executes any ready tasks, and reports findings — all without you sending a single message.

From Reactive to Proactive

The heartbeat transforms the agent's behavior model:

Behavior	Reactive Agent (No Heartbeat)	Proactive Agent (With Heartbeat)
Email arrives	Waits for you to ask about it	Classifies it and drafts a response
Error spike occurs	You discover it manually	Agent detects it and alerts you immediately
Calendar conflict	You notice it yourself	Agent warns you 2 hours before
PR is ready for review	Sits in the queue	Agent reviews and posts comments
Task deadline approaches	Nothing happens	Agent reminds you and offers to help

This is the key architectural difference between a chatbot and an autonomous agent. A chatbot is a request-response system. An autonomous agent with a heartbeat is a continuously operating system that monitors, decides, and acts on a schedule.

Practical Heartbeat Examples

Morning briefing heartbeat — runs once daily at 6:00 AM:

def morning_briefing():
    # Gather information from multiple sources
    emails = check_unread_emails()
    calendar = get_today_schedule()
    tasks = get_pending_tasks()
    alerts = check_monitoring_alerts()

    # Build a structured briefing
    briefing = compile_briefing(
        emails=emails,
        calendar=calendar,
        tasks=tasks,
        alerts=alerts
    )

    # Deliver via the user's preferred channel
    send_telegram(briefing)

Continuous monitoring heartbeat — runs every 15 minutes:

def monitoring_heartbeat():
    alerts = check_metrics()

    if alerts.has_critical():
        # Critical issues: notify immediately
        send_telegram(
            format_alert(alerts.critical, urgency="high")
        )
    elif alerts.has_warnings():
        # Warnings: log for the next daily briefing
        append_to_memory("monitoring_warnings", alerts.warnings)
    # No issues: do nothing, stay quiet

The key design principle: the heartbeat should only produce output when there is something actionable. An agent that sends "nothing to report" every 30 minutes quickly becomes noise. Silence means everything is normal.

Putting It All Together

The complete agent context system is now in place:

1. User file — who you are and what you care about
2. Identity file — what the agent is and its mission
3. Soul file — personality, values, and boundaries
4. Memory — persistent knowledge and learning over time
5. Agents file — security rules and standard operating procedures
6. Tools file — available capabilities and how to use them
7. Heartbeat — scheduled triggers for proactive behavior

Each layer builds on the previous ones. The user and identity files provide context. The soul file shapes behavior. Memory provides continuity. SOPs define procedures. Tools define capabilities. And the heartbeat ties everything together into a continuously operating system.

Key takeaway: The heartbeat system is what transforms an agent from a passive assistant into an autonomous operator. By running on a schedule, the agent can monitor, decide, and act without waiting for your input. Combined with operational rules and tool definitions, the heartbeat is the architectural foundation of a truly autonomous agent.

Next module: Security, skills, and workflows — building production-ready agent systems with proper safeguards. :::