Agent Loop Failure Diagnosis Prompt

This prompt is for agent developers and AI SREs who have a production trace where an agent entered a loop: repeating the same action, cycling through a small set of tool calls without progress, or failing to reach a termination condition. The prompt reconstructs the planning-action-observation cycle from raw trace spans, identifies the first deviation from expected behavior, pinpoints the repeated action or missing stop condition, and produces a structured diagnosis report. Use this prompt when you have a single trace that exhibits looping behavior and you need to understand what broke before aggregating across sessions or modifying the agent's system prompt.

The ideal user has access to a raw trace containing the agent's reasoning steps, tool calls, tool responses, and any termination checks. You should not use this prompt for latency analysis, cost attribution, or multi-trace incident correlation—those require separate specialized prompts. Before invoking this prompt, confirm that the trace actually contains a loop: look for repeated tool calls with identical or near-identical arguments, a cycle of 2-4 actions that repeats without state change, or a trace that exceeds the expected step count without reaching a terminal action. If the trace is incomplete or missing observation spans, run an end-to-end trace reconstruction prompt first to fill gaps.

This prompt works best with traces from agents that follow a planning-action-observation loop pattern, such as ReAct agents, tool-calling agents with reasoning steps, or multi-step retrieval agents. It is less effective for single-call workflows, streaming-only agents without logged reasoning, or agents that use opaque internal planners where the planning step is not captured in the trace. For agents with human-in-the-loop steps, ensure the trace includes approval or rejection events so the prompt can distinguish between a loop caused by the model and a loop caused by repeated human rejections.

The output of this prompt is a structured diagnosis report, not a fix. After receiving the diagnosis, you will typically need to take one of several actions: add or tighten a termination condition in the agent's system prompt, increase the maximum step count with a forced stop, modify the tool descriptions to prevent ambiguous responses that trigger retries, or add a state-tracking mechanism so the agent can detect when it is repeating itself. If the diagnosis points to a model reasoning failure rather than a prompt or tool defect, consider whether a different model or a fine-tuned variant is warranted for this agent workload.

This prompt template is designed to be copied directly into your observability or debugging interface. It instructs the model to act as a diagnostic engine that reconstructs the planning-action-observation cycle from a raw agent trace, identifies the first deviation that led to a loop, and pinpoints the missing termination condition. Before using it, ensure you have extracted the relevant trace spans—including tool calls, their arguments, responses, and any intermediate reasoning tokens—from your tracing system (e.g., LangSmith, Arize, or a custom logger). Replace every square-bracket placeholder with concrete data from the trace you are investigating.

textCopy
You are an agent reliability engineer diagnosing a production agent loop failure.
Your task is to reconstruct the agent's planning-action-observation cycle from the raw trace data provided below and identify the root cause of the loop.

## TRACE DATA
[RAW_TRACE_SPANS]

## AGENT CONFIGURATION
- Max Steps Allowed: [MAX_STEPS]
- Available Tools: [TOOL_LIST_WITH_DESCRIPTIONS]
- Termination Condition: [TERMINATION_CONDITION]

## INSTRUCTIONS
1. Reconstruct the chronological sequence of agent steps. For each step, extract the Thought, Action, Action Input, and Observation.
2. Identify the first step where the agent's behavior deviated from a path toward termination. This could be a repeated action, a semantically identical thought, or an action that does not change the state.
3. Determine the root cause of the loop. Classify it into one of the following categories:
   - **Missing Termination Condition**: The agent achieved the goal but did not recognize it.
   - **Repeated Action**: The agent called the same tool with the same arguments multiple times.
   - **State Confusion**: The agent misinterpreted the observation and believed progress was made when it was not.
   - **Tool Failure Ignored**: A tool returned an error, but the agent did not adapt its plan.
   - **Infinite Sub-Goal**: The agent got stuck trying to complete a non-essential sub-task.
4. Provide a concise root-cause analysis summary.
5. Suggest one concrete fix to the system prompt, tool description, or termination logic that would prevent this loop.

## OUTPUT FORMAT
Return a JSON object with the following schema:
{
  "total_steps_observed": <integer>,
  "reconstructed_cycle": [
    {
      "step_number": <integer>,
      "thought": "<string>",
      "action": "<tool_name | null>",
      "action_input": "<object | string>",
      "observation": "<string>",
      "is_repeat": <boolean>,
      "deviation_flag": <boolean>
    }
  ],
  "first_deviation_step": <integer | null>,
  "loop_root_cause": "<category>",
  "root_cause_analysis": "<string>",
  "suggested_fix": "<string>"
}

To adapt this template, start by populating [RAW_TRACE_SPANS] with the full JSON or formatted log output from your tracing system. Be careful not to truncate the trace; loops often span many steps, and cutting off the data will hide the first deviation. The [TOOL_LIST_WITH_DESCRIPTIONS] placeholder should contain the exact function definitions the agent had access to, as misleading or incomplete tool descriptions are a common root cause of state confusion. The [TERMINATION_CONDITION] field is critical—explicitly state the rule the agent was supposed to follow (e.g., "Stop when the Final Answer tool is called" or "Stop when the user's question is answered"). If you are using this prompt in an automated pipeline, validate the output JSON against the schema before surfacing the diagnosis to an on-call engineer. For high-severity incidents where the loop caused a cost overrun or user-facing error, route the output for human review before applying the suggested fix to the system prompt.

This prompt is designed to be integrated into an automated trace analysis pipeline, not just used as a one-off debugging tool. The primary integration point is a trace ingestion system (e.g., LangSmith, Arize, or a custom OpenTelemetry collector) that captures agent execution spans. When a session is flagged for excessive step count, repeated actions, or a timeout, the raw trace data—including the full sequence of planning, action, and observation spans—should be programmatically extracted and formatted into the [TRACE_LOG] placeholder. The [AGENT_CONFIG] placeholder must be populated from the deployment's configuration store, pulling the system prompt, tool definitions, and the explicit termination condition (e.g., max_steps or a Final Answer tool).

To operationalize this, build a lightweight harness function that accepts a session_id and a trace_backend client. The function should first query the backend for all spans belonging to the session, sort them by timestamp, and serialize them into the structured text format required by the prompt. Next, it should fetch the agent's deployed configuration from a versioned artifact store (like an S3 bucket or a database) to populate [AGENT_CONFIG]. The harness then calls the LLM with the assembled prompt. The model choice here is critical: use a model with strong reasoning capabilities and a large context window (e.g., gpt-4o or claude-3.5-sonnet) because the trace log for a stuck agent can easily exceed 10,000 tokens. Implement a retry logic with exponential backoff for API failures, but do not retry on validation failures.

The output from the LLM must be parsed as JSON and validated against a strict schema before it is surfaced to an on-call engineer. The schema should enforce the presence of loop_start_step, repeating_pattern, root_cause_category, and termination_condition_missing fields. If parsing fails, log the raw output and the validation error, then fall back to surfacing the raw trace without the AI diagnosis. For high-severity incidents where the agent controls a critical system, route the diagnosis to a human reviewer for confirmation before closing the incident. Avoid wiring this prompt directly into an automated rollback or configuration change; it is a diagnostic tool, not a self-healing mechanism. The next step is to store the validated diagnosis as a structured annotation on the trace itself, enabling trend analysis across multiple loop failures to identify systemic prompt or tool design flaws.