Why Your AI Agent Loops, Forgets or Claims It Is Finished

Image: Ali Kaan Uçar on Unsplash.

Most AI agent failures are not mysterious model behaviour. They are a specific layer failing: context, retrieval, a tool, a policy, runtime state or the success check. Start from the symptom, collect the run's evidence, find the layer, fix that mechanism and keep the case as a regression test.

The tempting fix is a stronger prompt.

It sometimes hides the symptom.

It rarely removes the cause.

This guide is part of the AI harness engineering guide.

Start with the symptom and the evidence

Before changing anything, collect:

• the task exactly as given,
• harness, model, prompt and tool versions,
• the run receipt and tool-call events,
• the final state of anything the task should have changed,
• whether it happens every time or sometimes.

The logging guide describes what a useful receipt contains. Without one, diagnosis is guessing.

Then map the symptom to likely layers:

Symptom	Most likely layers
Repeats the same step	Tool results, progress tracking, stop conditions
Forgets something it was told	Memory writing, retrieval scope, context assembly
Uses an outdated fact	Memory correction, stale index or cache
Wrong or unsupported citation	Retrieval, context, generation
Says "done", nothing happened	Tool status handling, success check
Did something twice	Retries, idempotency, scheduling
Costs spiking	Loops, retries, context growth, budget enforcement
Refuses legitimate work	Policy rules, tool scope, over-strict prompts

The agent repeats the same step or never stops

Typical causes:

a tool returns an ambiguous result, so the model tries again,
errors come back as unstructured text the model cannot interpret,
the task has no clear completion signal,
nothing records which steps are already done.

Diagnose: look at the repeated tool calls in the events. Are the arguments identical? Is the result an error, an empty list or something the model may misread as "try again"?

Fix the mechanism:

• return structured results and errors, such as NOT_FOUND or NOT_ALLOWED,
• track completed steps in task state the model can see,
• define what "finished" means for the task,
• keep a hard step and time limit in the runtime as a backstop.

A larger step limit is not a fix. It is a more expensive loop.

The assistant forgets or uses stale facts

Separate three possibilities:

1. It was never stored. Check the memory store for the record.
2. It was stored but not retrieved. Check retrieval scope and the selected passages for the run.
3. It was retrieved but lost in context. Check how much was in context and where the fact sat.

For stale facts, check whether an old record is still active, an index still holds the old text, or a cache was not invalidated. A correction must supersede the old record and update every index.

Long contexts can bury evidence. A 2023 study found the models of the time often did better with relevant passages at the start or end of a long input than in the middle (Liu et al.). If the fact was present but ignored, try fewer, better passages and test whether position matters for your model.

See the memory guide and RAG vs memory vs context.

The assistant says "done" but nothing happened

This is the most dangerous symptom, because it looks like success.

Typical causes:

a tool returned an error the harness passed on as text and the model glossed over,
the call was denied, and the denial was not surfaced as failure,
the harness marked the run complete because the model said so,
a timeout left the outcome unknown.

Fix the mechanism:

• propagate tool status explicitly: ok, denied, failed, uncertain,
• decide success by checking final state, not the model's message,
• treat uncertain outcomes as uncertain until reconciled.

Tau-bench, a benchmark of tool-using agents, grades by comparing the final database state with the expected goal state rather than trusting the conversation (Yao et al.). Your success check should work the same way. The evaluation guide covers it.

Actions repeat or costs spiral

Duplicates usually come from retries without idempotency, a schedule delivered twice, or a restart after an action succeeded but before it was recorded. Check run and attempt IDs, and look for uncertain outcomes that were retried blindly. The scheduling guide covers idempotency keys and reconciliation.

Cost spikes usually come from loops, retry storms or context that grows every step. Compare tokens per run over time and look for runs that end on limits. The cost worksheet shows how to track cost per successful task.

Fix the smallest responsible mechanism

Once you have a hypothesis:

1. Reproduce the failure with the smallest input that triggers it.
2. Change one thing related to the hypothesis.
3. Rerun the reproduction several times; intermittent failures need repeats.
4. Check the fix matches the failure. A state bug is not fixed by a prettier answer.
5. Run the full suite to make sure nothing else broke.

Prefer fixes in code and configuration: tool validation, status handling, state tracking, limits, index updates. Prompt changes are fine for quality issues, but they are not a reliable fix for control or state problems.

Keep the failure from returning

Every diagnosed failure becomes a permanent test:

Record	Example
Symptom	"Said the meeting was added; calendar unchanged"
Root cause	"Denied write returned as plain text; harness marked success"
Fix	"Status propagated; success requires state check"
Regression case	boundary-07: denied write must produce stop: failed

Rerun the suite whenever the model, prompts, tools, memory or harness change. Failures that were fixed once tend to come back during unrelated changes. For production-grade tracing that makes this easier, see AI agent observability.

Frequently asked questions

Should I solve every failure with a stronger prompt?

No. Prompts help with quality. Loops, false completion and duplicates are usually tool, state or check problems that need code fixes.

How do I tell forgetting from a retrieval failure?

Check whether the fact was stored, whether it was retrieved for the run and whether it was in the final context. Each answer points to a different layer.

What proves an external action actually completed?

A downstream effect: the sent message, the created event, the saved file, with its ID. Not the agent's message.

When should I stop retries and ask for help?

When an action may already have happened and you cannot confirm it, or when the same failure repeats. Duplicating a consequential action is worse than pausing.