Agent Error Reporting Message Prompt

This prompt is for SRE teams and platform engineers who need every agent in a multi-agent system to report failures in a consistent, machine-readable format. Use it when an agent encounters an error during task execution and must communicate that failure to an orchestrator, a message bus, a dead-letter queue, or a human operator. The prompt produces a structured error payload that downstream systems can parse, route, and act on without manual interpretation. Do not use this prompt for successful task completion notifications, progress updates, or health checks. Those require separate payload schemas with different required fields and semantics.

The ideal user is an integration engineer or platform builder who already has an agent communication bus and needs a single, enforceable error contract. The required context includes the agent's role, the task it was attempting, the raw error or exception, and any relevant correlation IDs. The prompt forces the agent to categorize the failure (e.g., TRANSIENT, PERMANENT, POLICY_VIOLATION), declare retry eligibility, and suggest an escalation path. This removes ambiguity from error handling: a downstream orchestrator can branch on the error_category field instead of parsing free-text logs. For high-risk domains like finance or healthcare, the prompt also requires an evidence_snapshot field so human reviewers can see exactly what the agent saw before it failed.

Before using this prompt, confirm that your agent framework can capture structured error context at the point of failure. If your agents only produce unstructured stack traces, you will need to wrap their execution in a harness that catches exceptions and injects them into this prompt. Also avoid using this prompt for warnings or non-fatal anomalies—those should use a separate Agent Warning Notification schema to prevent alert fatigue. Once you have a validated error payload, route it to your dead-letter queue, incident management system, or human review dashboard based on the escalation_path field.

This prompt template instructs a model to act as an error-reporting agent. It takes raw failure context from a source agent and produces a structured error payload that downstream systems—such as orchestrators, retry queues, or human review dashboards—can parse reliably. The template is designed to be used within a multi-agent system where ad-hoc error strings are not acceptable and every failure must carry enough metadata for automated triage.

textCopy
SYSTEM:
You are an Agent Error Reporter. Your only job is to convert raw agent failure information into a structured error report that follows the exact schema and constraints provided. Do not attempt to fix the error. Do not speculate about root causes beyond what is in the input context. If required fields are missing from the input, mark the report as incomplete and set the error code to `INCOMPLETE_INPUT`.

USER MESSAGE:
Generate a structured error report from the following failure context.

FAILURE CONTEXT:
[FAILURE_CONTEXT]

SOURCE AGENT ID: [SOURCE_AGENT_ID]
TARGET AGENT ID: [TARGET_AGENT_ID]
CORRELATION ID: [CORRELATION_ID]

OUTPUT SCHEMA (JSON):
{
  "error_report": {
    "report_id": "string, unique identifier for this error report",
    "timestamp": "string, ISO 8601 UTC timestamp of report generation",
    "source_agent_id": "string",
    "target_agent_id": "string",
    "correlation_id": "string",
    "error_code": "string, from the approved error code enumeration",
    "severity": "string, one of: CRITICAL, HIGH, MEDIUM, LOW",
    "retry_eligibility": {
      "retryable": "boolean",
      "max_retries": "integer, 0 if not retryable",
      "retry_strategy": "string, one of: IMMEDIATE, EXPONENTIAL_BACKOFF, FIXED_DELAY, NONE",
      "suggested_delay_seconds": "integer"
    },
    "escalation_path": "string, one of: HUMAN_REVIEW, FALLBACK_AGENT, DEAD_LETTER_QUEUE, NONE",
    "stack_context": {
      "failed_operation": "string, the specific operation that failed",
      "input_summary": "string, brief summary of the input that caused the failure",
      "observed_error": "string, the raw error message or symptom",
      "agent_state_at_failure": "string, what the agent was doing when it failed"
    },
    "evidence": [
      {
        "type": "string, one of: LOG, TOOL_OUTPUT, MESSAGE, TRACE",
        "content": "string, the evidence snippet"
      }
    ],
    "incomplete": "boolean, true if required input fields were missing"
  }
}

CONSTRAINTS:
- Use only the approved error codes: TIMEOUT, TOOL_FAILURE, SCHEMA_VIOLATION, PERMISSION_DENIED, RATE_LIMITED, INVALID_INPUT, AGENT_UNAVAILABLE, INCOMPLETE_INPUT, UNKNOWN.
- If the failure context does not contain enough information to determine retry_eligibility, set retryable to false and escalation_path to HUMAN_REVIEW.
- Never invent evidence. Only include evidence items that are explicitly present in the failure context.
- If the failure context is empty or missing, return an error report with error_code INCOMPLETE_INPUT and incomplete set to true.

Adaptation notes: Replace [FAILURE_CONTEXT] with the raw error output, tool response, or exception message from the failing agent. [SOURCE_AGENT_ID] and [TARGET_AGENT_ID] should come from your agent registry. [CORRELATION_ID] must match the trace ID used across your agent message bus. The error code enumeration and severity levels should be aligned with your organization's incident response taxonomy. Before deploying, validate that the output JSON parses correctly and that the error_code field matches one of the approved values—schema validation should be applied at the application layer, not trusted to the model alone.

The error reporting prompt must be integrated into the agent's execution wrapper, not called as an afterthought. Wrap every agent task execution in a try-catch block. In the catch path, invoke the model call with the error context, agent state, and correlation ID. If the model call itself fails—due to a network error, rate limit, or model unavailability—fall back to a minimal static error payload. That fallback must include at least the error_id, correlation_id, agent_id, error_category set to INFRASTRUCTURE, and a sanitized error_message derived from the caught exception type. Never expose raw stack traces in the fallback payload; log them internally and replace the external-facing message with a generic description such as 'Internal agent error during error reporting.'

After the model returns a structured error payload, validate it against the expected schema before publishing it to the message bus. Check that all required fields are present, enums match allowed values, and the error_category is one of the defined levels (e.g., TRANSIENT, RECOVERABLE, CRITICAL, INFRASTRUCTURE). If validation fails, log the malformed payload with its correlation ID and fall back to the static error payload. Route the validated payload based on severity: if error_category is CRITICAL or the retry_count exceeds the configured maximum (e.g., 3), publish directly to the escalation target—typically a human review queue, a PagerDuty incident, or a dead-letter topic. For non-critical errors with remaining retries, publish to the retry queue with retry_count incremented by one and the original correlation_id preserved for trace continuity.

Log every generated error report—whether model-produced or fallback—with its correlation ID, timestamp, agent ID, and error category. This creates an audit trail for debugging agent chains and measuring error reporting accuracy. In production, monitor the ratio of fallback payloads to model-generated payloads; a rising fallback rate signals model endpoint instability or prompt drift. Also track the distribution of error categories to identify whether agents are failing due to transient infrastructure issues or recoverable logic errors. For high-risk domains, consider adding a human review step before escalation payloads are delivered, especially when the error involves sensitive data or regulated actions. The goal is a harness that fails safely, communicates clearly, and never leaves an agent failure unlogged or misrouted.