Agent Tool Error Log Enrichment Prompt Template

This prompt is designed for platform reliability engineers and AI operations teams who need to transform a raw, unstructured tool exception into a structured, queryable, and enriched log record. The core job-to-be-done is closing the observability gap between a failed tool call and a useful diagnostic artifact. In production agent runtimes, a bare stack trace or error string lacks critical context: the agent's session, the retry count, the circuit breaker state, or whether the error message was truncated by an upstream proxy. This prompt sits in the error-handling path, consuming the raw failure and producing a JSON payload that your observability stack can index, alert on, and correlate with other traces.

The ideal user is an engineer integrating this prompt into an agent framework's exception handler. You need three pieces of context before this prompt is useful: the raw error object from the tool, the agent's current state (session ID, task ID, retry count, circuit state), and any known constraints about the tool's error output (e.g., a 1024-character truncation limit from a logging proxy). Without this context, the prompt will produce a valid JSON structure but with empty or placeholder fields, which defeats the purpose of enrichment. Do not use this prompt for real-time user-facing error messages; it is designed for machine-to-machine observability pipelines, not for explaining failures to end users.

This prompt is not a replacement for structured logging libraries in your tool code. If your tools already emit OpenTelemetry-compatible spans with full metadata, you do not need this enrichment step. Use it when you are consuming errors from third-party tools, legacy APIs, or sandboxed execution environments where you cannot modify the logging behavior. Additionally, avoid using this prompt for non-error telemetry, such as successful tool call traces or performance metrics; those require different schemas and should not be forced through an error-centric enrichment template. The next step after reading this section is to gather your raw error samples and agent state schema so you can populate the prompt's placeholders accurately.

The prompt below is designed to be pasted directly into your error-handling path. It takes a raw tool error and enriches it with agent state, retry count, circuit state, and contextual metadata before the error is written to your observability system. Replace every square-bracket placeholder with runtime values from your agent execution context. The output is a structured JSON log record that your logging pipeline can index, alert on, and use for debugging multi-step agent failures.

textCopy
You are an error log enrichment agent for a production AI system. Your task is to take a raw tool error and produce a structured, enriched error log record that includes agent state, retry context, circuit state, and diagnostic metadata.

## INPUT
Raw Tool Error: [RAW_ERROR]

## CONTEXT
- Agent ID: [AGENT_ID]
- Session ID: [SESSION_ID]
- Trace ID: [TRACE_ID]
- Tool Name: [TOOL_NAME]
- Tool Version: [TOOL_VERSION]
- Tool Arguments (sanitized): [TOOL_ARGS]
- Retry Count: [RETRY_COUNT]
- Max Retries: [MAX_RETRIES]
- Circuit State Before Call: [CIRCUIT_STATE]
- Agent State Snapshot (last 3 steps): [AGENT_STATE_SNAPSHOT]
- Timestamp (UTC ISO 8601): [TIMESTAMP]
- Environment: [ENVIRONMENT]

## CONSTRAINTS
- Do not fabricate missing fields. Mark unavailable fields as null.
- If the raw error message appears truncated, set `error_truncated` to true and note the truncation point.
- If no stack trace is present, set `stack_trace_available` to false and do not attempt to generate one.
- Preserve the original error message verbatim in the `raw_error` field.
- Classify the error category from this fixed list: TIMEOUT, AUTHENTICATION, AUTHORIZATION, RATE_LIMIT, INVALID_ARGUMENT, UPSTREAM_UNAVAILABLE, CIRCUIT_OPEN, UNKNOWN.

## OUTPUT_SCHEMA
Return a single JSON object with this exact structure:
{
  "enriched_error": {
    "trace_id": "string",
    "session_id": "string",
    "agent_id": "string",
    "tool_name": "string",
    "tool_version": "string",
    "timestamp": "string (ISO 8601)",
    "environment": "string",
    "error_category": "TIMEOUT | AUTHENTICATION | AUTHORIZATION | RATE_LIMIT | INVALID_ARGUMENT | UPSTREAM_UNAVAILABLE | CIRCUIT_OPEN | UNKNOWN",
    "raw_error": "string (original error verbatim)",
    "error_truncated": true,
    "stack_trace_available": false,
    "stack_trace": null,
    "retry_context": {
      "retry_count": 0,
      "max_retries": 0,
      "retries_exhausted": false
    },
    "circuit_state": "CLOSED | OPEN | HALF_OPEN",
    "agent_state_summary": "string (concise summary of last 3 agent steps)",
    "diagnostic_hints": ["string (actionable hint for the on-call engineer)"],
    "missing_fields": ["string (list of context fields that were unavailable)"]
  }
}

## INSTRUCTIONS
1. Parse the raw error for error category signals (e.g., 'timed out', '401', 'circuit breaker').
2. Check if the raw error message ends abruptly or contains truncation indicators.
3. Check if a stack trace is present in the raw error.
4. Determine if retries are exhausted based on retry_count vs max_retries.
5. Generate 1-3 diagnostic hints based on the error category, retry state, and circuit state.
6. List any context fields that were empty or unavailable in `missing_fields`.
7. Output only the JSON object. No markdown, no commentary.

Adaptation guidance: If your observability pipeline expects OpenTelemetry-compatible attributes, add span context fields to the output schema. If you log to a structured logging system like Splunk or Datadog, flatten the JSON to top-level key-value pairs. For high-compliance environments, add a redaction_audit field documenting any PII or secret removal performed before enrichment. Always test this prompt with truncated errors, missing stack traces, and circuit-open states before deploying to production error paths.

This prompt is designed to sit inside an agent's exception handler, not as a standalone debugging script. When a tool call fails—whether due to a network timeout, a malformed response, or a permission error—the raw error object is often too sparse for diagnosis. The prompt enriches that error with the agent's current state, retry count, circuit breaker status, and contextual metadata before the record is written to your observability stack. The goal is to make every error log entry self-contained enough that an SRE can begin an investigation without hunting down separate session traces.

To wire this in, intercept the error at the tool execution boundary. Capture the raw error object, the tool's input arguments, the agent's current task ID, the session ID, the retry count for this specific tool invocation, and the circuit breaker state if you're using one. Pass these as structured inputs to the prompt. The model should receive a clear schema for the enriched log record, including fields like error_category, root_cause_hypothesis, missing_context_flags, and recommended_investigation_steps. Validate the output against this schema before writing it to your log store. If validation fails, fall back to a minimal structured log with the raw error and a prompt_enrichment_failed flag—never drop the error entirely. For high-severity errors (e.g., permission denials, data access failures), route the enriched record to a human review queue in addition to the log store.

Model choice matters here. Use a fast, cheap model for enrichment because this prompt runs on the error path and you don't want to add latency or cost to an already-degraded request. A small model like GPT-4o-mini or Claude Haiku works well. Set a tight timeout on the enrichment call—if the model doesn't respond within 2 seconds, log the raw error and move on. Never retry the enrichment prompt itself; if it fails, you still have the raw error. The enriched log is a value-add, not a critical-path dependency. Finally, ensure your logging pipeline redacts sensitive fields from tool arguments before they reach the prompt, using a separate sanitization step or a dedicated redaction prompt from the Tool Observability pillar.