Human Clarification Request Prompt After Agent Failure

This prompt is for agent systems that have exhausted their retry budget or hit an unrecoverable error and must hand off to a human operator for clarification. The primary job-to-be-done is to produce a structured, actionable request that explains what the agent attempted, where it failed, and exactly what the human needs to provide to unblock the workflow. The ideal user is an AI platform engineer or orchestration developer building a multi-agent system where autonomous agents are expected to self-correct but must escalate gracefully when they cannot. Required context includes the original user intent, the agent's full action trace, the specific failure point, and any partial results or error logs generated before the failure.

Do not use this prompt for simple retry scenarios where the model can self-correct with a better error message or a different tool argument. This prompt is specifically for cases where the agent has already attempted multiple recovery strategies, the failure is persistent, and the only path forward requires human judgment—such as ambiguous user intent, missing required parameters, conflicting instructions, or a capability gap the agent cannot resolve. The prompt should be wired into an orchestration layer that tracks retry counts, detects repeated identical failures, and triggers the handoff only after a configurable threshold is exceeded. Without this gating logic, you risk flooding human reviewers with transient errors that the agent could have resolved on its own.

Before implementing this prompt, ensure your agent harness captures a structured failure context: the original task definition, the sequence of actions attempted, the error at each step, and any tool outputs or partial results. The human reviewer should not need to reconstruct what happened from raw logs. After deploying, monitor the ratio of clarification requests to successful autonomous completions—if the request rate exceeds 10-15% of agent tasks, the agent's retry logic, tool definitions, or input validation likely need redesign rather than more handoffs. Pair this prompt with an audit trail that records the human's response and whether it successfully unblocked the workflow, creating a feedback loop for improving both the agent and the clarification prompt over time.

This template produces a structured handoff when an agent cannot proceed without human input. It is designed for orchestration systems that detect repeated failures, unrecoverable errors, or ambiguity that exceeds the agent's authority to resolve. The output is a self-contained clarification request that a human reviewer can act on without reading raw agent logs or replaying the failed execution. Use this template when the agent has already attempted retries, self-correction, or alternative paths and has determined that only external clarification can unblock the workflow.

textCopy
You are an agent that has exhausted all available retry and self-correction paths. You cannot proceed without human clarification. Your task is to produce a structured handoff that explains what was attempted, where the failure occurred, and exactly what the human must provide to unblock the workflow.

## INPUT
[ORIGINAL_USER_REQUEST]
[AGENT_ROLE_AND_CAPABILITIES]
[FAILURE_CONTEXT]
[ERROR_TRACE_OR_LOG]
[RETRY_HISTORY]

## OUTPUT_SCHEMA
Return a JSON object with these fields:
{
  "handoff_type": "clarification_request",
  "agent_identity": "string",
  "original_goal": "string",
  "attempts_made": [
    {
      "attempt_number": "integer",
      "strategy": "string",
      "outcome": "string",
      "failure_reason": "string"
    }
  ],
  "blocking_error": {
    "error_type": "string",
    "error_message": "string",
    "error_location": "string",
    "recoverable_without_human": false
  },
  "clarification_needed": {
    "question": "string",
    "context_for_question": "string",
    "candidate_interpretations": ["string"],
    "impact_of_choice": "string"
  },
  "partial_results": "string or null",
  "recommended_next_step_after_clarification": "string",
  "urgency": "low | medium | high | critical",
  "urgency_justification": "string"
}

## CONSTRAINTS
- Do not guess the answer to the clarification question. If you are uncertain, state the uncertainty explicitly.
- Include only attempts that were actually executed. Do not fabricate retry history.
- The clarification question must be specific enough that a human can answer it without additional research.
- If partial results exist, include them so the human does not need to redo completed work.
- Set urgency based on the downstream impact of delay, not on your own execution time.
- If the error trace contains sensitive data, redact it and note the redaction.
- If [RISK_LEVEL] is "high" or "critical", add a field `"requires_approval": true` and include the approval authority required.

## EXAMPLES
[EXAMPLES]

## RISK_LEVEL
[RISK_LEVEL]

Adapt this template by replacing each square-bracket placeholder with values from your orchestration layer. [ORIGINAL_USER_REQUEST] should contain the exact user input that triggered the agent. [FAILURE_CONTEXT] should describe the state of the workflow when the failure occurred, including any tool outputs, intermediate results, or environmental conditions. [RETRY_HISTORY] should be a structured log of each retry attempt with the strategy used and the outcome. If your system does not track retry history, remove the attempts_made array or populate it from available logs. The [EXAMPLES] placeholder should contain one or two few-shot examples of well-formed clarification requests for your domain. The [RISK_LEVEL] placeholder accepts "low", "medium", "high", or "critical" and controls whether the output includes approval requirements. Before deploying, validate that the output JSON conforms to the schema and that the clarification question is answerable by a human without additional context gathering.

The clarification request prompt is triggered when an agent exhausts its retry budget or hits an unrecoverable error state. In the orchestration layer, this prompt should be called as a final fallback after the agent's primary execution loop and any self-correction or repair prompts have failed. The harness must capture the agent's full execution trace—including tool calls, intermediate outputs, error messages, and the original user intent—and pass it into the prompt as [FAILURE_CONTEXT]. The prompt then produces a structured handoff payload that a human reviewer can act on without reading raw agent logs.

Wire the prompt into a dedicated handoff function that is invoked by the orchestrator's error handler. The function should: (1) serialize the agent's trace into a structured [FAILURE_CONTEXT] object containing attempts, errors, last_state, and original_request; (2) call the LLM with the clarification prompt template and a strict [OUTPUT_SCHEMA] requiring clarification_needed, what_was_attempted, failure_point, specific_question, and context_for_reviewer; (3) validate the output against the schema before routing to a human queue. If validation fails, retry once with a repair prompt that includes the schema violation details. If the retry also fails, route the raw trace plus a generic escalation notice to the human queue as a degraded fallback. Log every handoff attempt, the validation result, and the final routing decision for audit and observability.

Model choice matters here: use a model with strong instruction-following and structured output support, such as GPT-4o or Claude 3.5 Sonnet, because the prompt requires precise extraction of the failure point and generation of a single clear question. Avoid smaller or older models that may produce vague questions or omit critical failure context. The human review queue should display the structured handoff payload, not the raw prompt output. If the workflow is high-risk—such as financial transactions, clinical decisions, or compliance actions—add a mandatory human acknowledgment step before the workflow can be unblocked, and ensure the handoff payload is persisted as an audit record with timestamps and reviewer identity.