If your AI agent is hallucinating, the instinct is to blame the model. Swap to a better one, tune the temperature, add more examples. But in my experience running production agents 24/7, hallucinations are almost always a config problem. Here's the pattern I keep seeing.
Hallucinations happen in predictable conditions
After running four agents continuously for months, I've identified three scenarios where hallucinations cluster:
1. Stale context. The agent is working from information that's hours or days old. It fills the gaps confidently with plausible-but-wrong data. Fix: add a context freshness rule — "before using any external data, check its timestamp."
2. Vague constraints. The SOUL.md doesn't define what the agent does when uncertain. So it guesses. Fix: explicit escalation rule — "if I am uncertain, stop and write context to outbox.json."
3. No output format. Without a structured output requirement, the agent improvises. Improvised outputs are harder to validate. Fix: require JSON schema output and validate every response.
The test I use
I ask one question about every agent config: "What does this agent do when it doesn't know the answer?"
If the answer is "it figures something out," hallucinations are guaranteed. If the answer is "it escalates to outbox.json and waits," the agent is safe to run unsupervised.
What the fix looks like in a SOUL.md
## Uncertainty Rule
If I do not have verified information for a required field:
- Do NOT infer or guess
- Write a structured escalation to outbox.json with: what I needed, what I tried, and why I couldn't verify it
- Stop the current task and wait for resolution
## Output Rule
All outputs must conform to the task schema defined in task-spec.json.
Validate before writing. If validation fails, escalate rather than write invalid output.
These two rules, added to a SOUL.md, eliminate the majority of hallucinations I've seen in practice.
The bottom line
Hallucinations are a signal, not a mystery. They happen when the agent has no instructions for uncertainty. Give it those instructions and the hallucinations mostly stop — regardless of which model you're running.
The Library at askpatrick.co has 30+ production-tested configs that bake these rules in from the start. Every entry includes the SOUL.md, escalation rule, and output schema.
Running agents in production? I write about what actually works at askpatrick.co.
Top comments (0)