Deadlock Detection and Human Intervention Prompt for Agents

This prompt is designed for agent platform engineers and SREs monitoring autonomous workflows where an agent can enter a non-productive state. The core job-to-be-done is to programmatically detect when an agent is stuck in a loop, cycling between conflicting tool calls, or unable to satisfy its termination condition, and to produce a structured intervention request. The ideal user is an engineer integrating this prompt into a middleware layer that observes agent state transitions, tool-call logs, and step history. The required context includes the agent's original objective, a trace of recent actions and observations, and the termination criteria. This prompt is not a general debugging tool; it is a specific circuit breaker for production agent pipelines.

Do not use this prompt for simple retry logic, network timeout errors, or single-step failures where a standard exponential backoff is sufficient. It is also inappropriate for workflows where the cost of pausing for human review exceeds the cost of letting the agent continue, such as low-stakes, stateless data transformations. The prompt assumes the agent's action history is available in a structured format. If your system cannot provide a clean trace of tool calls, parameters, and observations, the prompt will produce unreliable deadlock assessments. Furthermore, this prompt is not a replacement for deterministic cycle detection in a graph of tool calls; it is a semantic layer on top of that data to distinguish productive retries from true deadlocks.

When to use this prompt: You have an agent orchestrator that manages multi-step tasks with tool access. You need to detect when the agent's loop is no longer making progress toward its goal, such as when it repeatedly calls the same tools with the same arguments and receives no new information, or when it oscillates between two conflicting actions. The output should feed into a human review queue or an automated circuit-breaker that pauses the agent. When to avoid: The agent's task is idempotent and safe to retry indefinitely, the cost of a false-positive pause is unacceptable, or you lack the observability infrastructure to provide a structured trace. Next, review the prompt template to see how to format the agent's state for accurate deadlock classification.

This template is designed to be injected into an agent's control loop when the system suspects a deadlock condition. It takes the agent's recent action history, tool outputs, and current task as input, and produces a structured assessment that distinguishes productive retries from true deadlocks. Use this prompt when your agent has exceeded a retry threshold, is cycling between conflicting tool calls, or has failed to make progress toward its goal after a configurable number of steps. Do not use this prompt for simple error handling or single-step failures—those should be caught by retry logic or validation layers before reaching this escalation point.

textCopy
You are an agent deadlock detector. Your job is to analyze an agent's recent execution trace and determine whether it is stuck in a true deadlock or is making legitimate progress through retries.

## INPUT

[AGENT_TASK]: The original task assigned to the agent.

[EXECUTION_TRACE]: A chronological log of the agent's last N actions, tool calls, and observations. Each entry includes:
- step_number
- action_type (thought, tool_call, observation, error)
- action_detail (the specific action taken or tool invoked)
- result_summary (the outcome or observation received)

[DEADLOCK_THRESHOLD]: The number of repeated or unproductive cycles observed.

[TOOL_SCHEMAS]: The available tools and their descriptions, to assess whether the agent is using them correctly.

## OUTPUT_SCHEMA

Return a JSON object with the following structure:
{
  "deadlock_detected": boolean,
  "deadlock_type": "loop" | "conflict" | "incapacity" | "none",
  "confidence": 0.0-1.0,
  "summary": "One-sentence description of the deadlock state or progress status.",
  "evidence": [
    {
      "step_numbers": [int, int],
      "pattern": "Description of the repeating or conflicting pattern observed."
    }
  ],
  "intervention_required": boolean,
  "intervention_recommendation": "If intervention is required, specify: pause agent, request human input, provide clarification, or modify tool access. If not required, explain why the agent is still making progress.",
  "suggested_next_action": "If no deadlock, suggest the next productive step. If deadlock, suggest the specific human intervention needed."
}

## CONSTRAINTS

- A true deadlock requires evidence of a repeating pattern, not just multiple retries.
- Distinguish between: (a) productive retries where the agent is trying different approaches, (b) unproductive loops where the same action repeats with the same failed outcome, (c) tool conflicts where two tools are called in opposition, and (d) incapacity where the agent lacks the necessary tools or information to proceed.
- If the agent is making progress (even slowly), deadlock_detected must be false.
- Do not escalate for transient errors or single failures.
- If confidence is below 0.7, set intervention_required to true as a precaution.

## EVALUATION CRITERIA

Your output will be evaluated on:
1. Accuracy: Correctly distinguishing true deadlocks from productive retries.
2. Evidence quality: Specific step numbers and patterns cited, not vague impressions.
3. Appropriate escalation: Not over-escalating on normal retries, not under-escalating on genuine stalls.
4. Actionability: The intervention recommendation must be specific enough for a human operator or orchestration layer to act on immediately.

To adapt this template, adjust the [DEADLOCK_THRESHOLD] based on your agent's typical task complexity—simple tasks may warrant a lower threshold, while complex multi-step workflows may need more tolerance. The [EXECUTION_TRACE] should include enough history to reveal patterns; too few steps will produce false negatives, while too many will increase token cost without improving accuracy. Wire the output into your agent orchestration layer so that when intervention_required is true, the agent pauses and the intervention_recommendation is routed to a human review queue or a supervisor agent. Always log the full prompt and response for post-mortem analysis of escalation accuracy.

Integrating this prompt into an agent platform requires embedding it within the orchestration layer's monitoring loop, not as a one-off call. The prompt should be invoked after a configurable threshold of repeated tool calls or state cycles is breached. A common pattern is to maintain a rolling window of the last N agent actions and their outcomes. When the window contains a repeated pattern—such as the same tool call with identical arguments failing more than twice, or a cycle of two conflicting tools undoing each other's work—the harness should assemble the [AGENT_LOG], [CURRENT_TASK], and [AVAILABLE_TOOLS] placeholders and invoke the model. The prompt's output should be parsed as structured JSON, and the intervention_required boolean field should gate the next action: if true, the agent must pause and the intervention_payload must be routed to the human review queue.

Validation of the model's output is critical before pausing an agent. The harness must check that the JSON schema is valid, that intervention_required is a boolean, and that if it is true, the deadlock_type field is one of the expected enum values (e.g., loop, conflict, stall). If the model returns intervention_required: false but the cycle count continues to increase, the harness should implement a hard circuit breaker after a maximum retry limit to force an escalation. Log every invocation of this prompt with the full input context, the raw model output, the parsed decision, and the cycle count at the time of invocation. This audit trail is essential for tuning the detection threshold and diagnosing false negatives where the agent was stuck but the prompt failed to detect it.

For high-stakes autonomous workflows, never allow the model's intervention_required: false decision to be the sole gate. Implement a secondary, deterministic check in the harness: if the agent has executed more than a hard-coded maximum number of steps (e.g., 50) without reaching a terminal state, force an intervention regardless of the model's output. This defends against prompt failure modes where the model hallucinates a plausible 'progress' summary while the agent remains stuck. Route the generated intervention_payload to a human review interface that displays the deadlock summary, the recent agent log, and one-click actions for the reviewer to inject a new instruction, modify tool arguments, or terminate the task. Close the loop by capturing the human reviewer's action and using it to update the agent's state before resuming the orchestration loop.