Agent Heartbeat and Health Check Prompt

This prompt is designed for Site Reliability Engineers (SREs) and platform engineers who are building and operating a mesh of AI agents. The core job-to-be-done is to produce a standardized, machine-readable health check response from an agent so that an external orchestrator, load balancer, or monitoring system can make a reliable routing decision. The ideal user is someone integrating an agent into a production control plane where decisions about liveness, readiness, and degraded operation must be programmatic, not based on a human reading a status message. To use this prompt effectively, you must provide the agent with a concrete list of its internal dependencies, external tool capabilities, and current operational state, as the prompt's value comes from forcing the agent to introspect and report against a known contract.

You should use this prompt when you are building a multi-agent pipeline, an agent mesh, or any system where a central orchestrator must decide whether to route a new task to a specific agent. The structured payload it generates, containing fields like agent_id, liveness, readiness, and a list of degraded_capabilities, is designed to be parsed by a control plane and fed into metrics dashboards or automated circuit breakers. However, do not use this prompt for generating human-readable status dashboards or for agents that lack a defined set of dependencies and capabilities to report against. If an agent has no self-knowledge of its tooling or internal state, this prompt will produce a generic and unactionable response that creates a false sense of security.

Before implementing this prompt, ensure your agent runtime can inject the necessary context about its own health. The prompt is a contract enforcement mechanism, not a diagnostic tool. It works by asking the agent to evaluate its own state against a provided schema, but it cannot replace actual external health checks on the agent's dependencies. The next step is to pair this prompt with an application-layer validator that confirms the output conforms to the expected schema and to set up an alert if the readiness field ever returns false without a corresponding degraded_capabilities entry, as this indicates a failure in the agent's self-reporting logic.

This prompt template produces a standardized health check payload that SRE teams and monitoring systems can consume to determine whether an agent is alive, ready to accept work, and operating within acceptable parameters. Replace each square-bracket placeholder with the agent's current runtime context before sending. The template is designed to be called on a regular interval by an orchestration layer or health probe, and its output should be parseable by Prometheus, Datadog, or custom monitoring dashboards.

textCopy
You are an agent health check reporter. Your job is to produce a structured health status payload based on the current runtime state provided to you. Do not fabricate metrics. Only report what is supplied in [RUNTIME_STATE].

[RUNTIME_STATE]
- Agent ID: [AGENT_ID]
- Agent Role: [AGENT_ROLE]
- Uptime (seconds): [UPTIME_SECONDS]
- Last Successful Task Completion (ISO 8601): [LAST_SUCCESSFUL_TASK]
- Last Error (ISO 8601 or null): [LAST_ERROR_TIMESTAMP]
- Last Error Code (or null): [LAST_ERROR_CODE]
- Active Task Count: [ACTIVE_TASK_COUNT]
- Queue Depth: [QUEUE_DEPTH]
- Connected Dependencies (name: status): [DEPENDENCY_STATUS_MAP]
- Memory Usage (MB): [MEMORY_USAGE_MB]
- CPU Usage (%): [CPU_USAGE_PERCENT]
- Tool Availability (tool_name: available|unavailable): [TOOL_AVAILABILITY_MAP]
- Degraded Mode Flag (boolean): [DEGRADED_MODE]
- Degraded Mode Reason (or null): [DEGRADED_REASON]

[OUTPUT_SCHEMA]
{
  "agent_id": "string",
  "timestamp": "ISO 8601 UTC now",
  "liveness": {
    "status": "alive" | "unreachable",
    "uptime_seconds": number
  },
  "readiness": {
    "status": "ready" | "not_ready",
    "active_tasks": number,
    "queue_depth": number,
    "last_successful_task": "ISO 8601 or null",
    "blocking_conditions": ["string"]
  },
  "degraded_mode": {
    "active": boolean,
    "reason": "string or null",
    "affected_capabilities": ["string"]
  },
  "dependencies": {
    "healthy": ["string"],
    "unhealthy": ["string"],
    "degraded": ["string"]
  },
  "resources": {
    "memory_mb": number,
    "cpu_percent": number,
    "tool_availability": {
      "available": ["string"],
      "unavailable": ["string"]
    }
  },
  "last_error": {
    "timestamp": "ISO 8601 or null",
    "code": "string or null"
  },
  "overall_status": "healthy" | "degraded" | "unhealthy"
}

[CONSTRAINTS]
1. Set readiness.status to "not_ready" if active_tasks > [MAX_CONCURRENT_TASKS] or queue_depth > [MAX_QUEUE_DEPTH] or any dependency in the unhealthy list is critical.
2. Set overall_status to "unhealthy" if liveness.status is "unreachable" or readiness.status is "not_ready" and degraded_mode.active is false.
3. Set overall_status to "degraded" if degraded_mode.active is true or any non-critical dependency is unhealthy.
4. Populate blocking_conditions with human-readable reasons for not_ready status.
5. Populate affected_capabilities based on unavailable tools and unhealthy dependencies.
6. If last_error_timestamp is older than [ERROR_WINDOW_SECONDS] seconds, set last_error.timestamp and last_error.code to null.
7. Use the current UTC timestamp for the timestamp field.
8. Do not invent metrics. If a value is not provided in [RUNTIME_STATE], omit the field or set it to null as appropriate.

[EXAMPLES]
Example healthy output:
{
  "agent_id": "doc-processor-01",
  "timestamp": "2025-01-15T10:30:00Z",
  "liveness": { "status": "alive", "uptime_seconds": 86400 },
  "readiness": { "status": "ready", "active_tasks": 2, "queue_depth": 5, "last_successful_task": "2025-01-15T10:29:45Z", "blocking_conditions": [] },
  "degraded_mode": { "active": false, "reason": null, "affected_capabilities": [] },
  "dependencies": { "healthy": ["vector-db", "ocr-service"], "unhealthy": [], "degraded": [] },
  "resources": { "memory_mb": 512, "cpu_percent": 34, "tool_availability": { "available": ["pdf-reader", "text-extractor"], "unavailable": [] } },
  "last_error": { "timestamp": null, "code": null },
  "overall_status": "healthy"
}

Generate the health check payload now.

To adapt this template, replace each [PLACEHOLDER] with live values from your agent runtime. The [RUNTIME_STATE] block should be populated by your orchestration layer or agent supervisor before the prompt is sent. The [OUTPUT_SCHEMA] is included inline so the model produces a valid JSON object matching your monitoring system's expected contract. Adjust [MAX_CONCURRENT_TASKS], [MAX_QUEUE_DEPTH], and [ERROR_WINDOW_SECONDS] to match your SLO thresholds. For high-reliability systems, validate the output against the schema before ingesting it into your monitoring pipeline, and log any parse failures as a separate alert condition.

Before deploying this prompt into production, wire it into a health probe that runs on a fixed interval. Validate the JSON output against the schema using a strict parser. If the model returns malformed JSON, retry once with a repair prompt. If the retry also fails, emit an agent_health_check_failed alert. Do not treat a missing or unparseable health check as a healthy state. For agents operating in regulated or safety-critical domains, add a human-review step when overall_status transitions from healthy to degraded or unhealthy.

The heartbeat prompt is not a standalone utility; it is a contract between an agent and its supervisor or orchestrator. In production, this prompt is called on a regular cadence—typically every 15 to 60 seconds—by a sidecar health-check process or the orchestration framework itself. The caller sends the agent's current [AGENT_STATE] (including active task IDs, tool-call queues, and recent error logs) and expects a structured response that indicates whether the agent is live, ready to accept work, or running in a degraded mode. The prompt must be treated as a synchronous, low-latency call: if the model does not respond within a defined timeout window, the system should mark the agent as unresponsive and trigger the escalation path defined in your runbook.

Wire the prompt into your application with a thin wrapper that enforces a strict output contract. After receiving the model's response, validate the JSON against the expected schema before acting on it. A liveness field of false or a readiness field of false should immediately pause task dispatch to that agent and log the degraded_mode_indicators array for the on-call channel. Implement a retry policy with exponential backoff (e.g., 1s, 2s, 4s) capped at three attempts before declaring the agent dead. Log every heartbeat attempt—including model latency, raw response, validation errors, and the final interpreted status—to your observability stack so that SRE teams can distinguish between model failures, agent crashes, and transient network issues. For high-reliability deployments, pair this prompt with a separate watchdog timer that independently monitors the agent process; the prompt should confirm what the watchdog suspects, not be the sole detection mechanism.

Avoid using this prompt as a generic 'is the model alive?' check. It is designed for agent runtimes that hold state, manage tool queues, and can degrade gracefully. If your agent is stateless or you only need to know if the model endpoint is reachable, a simple HTTP health check against the model provider's status endpoint is cheaper and more reliable. When deploying, pin the model version used for heartbeat checks and monitor for response drift—a model update that changes the output schema or adds hallucinated fields will break your validation layer and can cause false-positive failure cascades. Start with a conservative timeout (5 seconds) and tighten it only after you have production data on p95 latency for your chosen model and region.