The Prompt Gets the Demo Working. It Does Not Get the System Working.
I have watched smart people spend three days refining a prompt for an agent that was going to fail anyway. Not because the prompt was bad. Because the data feeding it was inconsistent, the tool it called had no retry logic, and nobody had defined what the agent should do when it got an ambiguous result at two in the morning with no human available to ask.
The prompt is the part you can show in a slide deck. It fits in a text box. It sounds like the product. It is not the product.
In every production agent I have shipped, the prompt accounts for maybe five percent of the engineering decisions that determine whether the system actually works in the field. The other ninety-five percent is infrastructure, data contracts, tool reliability, state management, escalation paths, and observability. None of that fits in a slide deck, which is exactly why it gets skipped in the conversation and then bites you six weeks after go-live.
Where the Real Complexity Accumulates
Take a document processing agent I built for a mid-size lending operation. The prompt itself was maybe two hundred words. It told the model what kind of document it was looking at, what fields to extract, and how to handle missing values. Reasonable people could write that prompt in an afternoon.
What took months was everything else. The ingestion pipeline had to normalize documents arriving as scanned PDFs, native PDFs, and occasionally photographs taken on a phone. The OCR layer introduced errors that the model would confidently propagate downstream if we did not catch them first. We built a pre-processing step that flagged low-confidence OCR regions before the model ever saw the text, because a model that does not know it is reading garbled input will still give you a structured output. It will just be wrong with high confidence.
Then there was the question of what happens when the model extracts a loan amount that does not match the figure in a different section of the same document. The prompt cannot solve that. You need a validation layer, a confidence scoring system, and a routing rule that sends the right cases to a human reviewer without routing everything to a human reviewer, because that defeats the purpose.
The prompt was the easy part. The data contracts and the exception handling were the job.
Tool Reliability Is the Silent Killer of Agent Projects
Agents in production call tools. They query databases, write to systems of record, trigger workflows, pull from APIs. Every one of those connections is a place where something can go wrong in a way the model cannot recover from on its own.
I worked on a procurement agent for a distribution company. The agent was responsible for flagging purchase orders that looked anomalous against historical patterns and either auto-approving them or escalating them. The prompt logic was solid. The problem was the ERP connection. It returned stale data under load, silently, with no error code. The agent was making decisions on inventory figures that were four hours old and had no way to know that.
We fixed it by building a data freshness check into every tool call. If the timestamp on the data exceeded a threshold, the agent did not proceed. It escalated with a specific reason code. That logic lives in the tool wrapper, not in the prompt. The model never sees it. But without it, the agent was confidently wrong on a regular schedule.
This is the pattern I see constantly. The model behavior is fine. The scaffolding around it is where production systems break.
State Management and Memory Are Underbuilt in Almost Every First Version
Most agent demos are stateless. The agent gets a task, does the task, returns a result. That works for demos. Real operational workflows are not like that.
In field operations, a maintenance agent might be coordinating across a shift change. The technician who started the diagnostic is not the technician who finishes it. The agent needs to carry context across sessions, across users, and sometimes across days. If you have not built that state layer carefully, you get agents that ask the same clarifying questions repeatedly, lose track of what has already been tried, or worse, take an action that a previous session already took.
I built a field service coordination agent for an industrial equipment operator. Early versions had no persistent state beyond the current session. Technicians would come back after a break and the agent had no memory of the prior context. They stopped trusting it within two weeks. Not because the model was bad. Because the experience was incoherent.
We rebuilt the state layer so the agent maintained a structured log of every action taken, every question asked, and every piece of information confirmed during a job. The prompt barely changed. The reliability of the experience changed completely. Trust came back.
Escalation Design Is an Engineering Problem Not a Prompt Problem
Every production agent needs to know when to stop and hand off to a human. This sounds obvious. It is almost always underspecified in the first version.
You cannot write a prompt that covers every edge case. The model will encounter situations the prompt designer did not anticipate. What happens then matters enormously in regulated industries. In a financial compliance context, an agent that makes a confident decision on an ambiguous case it was never trained to handle is a liability. In a manufacturing context, an agent that proceeds when it should have paused can mean a production line running on bad parameters.
Escalation design means defining, in code and configuration, the conditions under which the agent stops acting and routes to a human, what information it passes along when it does, and how that handoff is tracked so nothing falls through. It means building confidence thresholds that are calibrated to the actual cost of a wrong decision in that specific domain, not a generic threshold copied from a tutorial.
I have seen agents go live with escalation logic that amounted to a sentence in the prompt saying something like if you are unsure, say so. That is not escalation design. That is optimism. The model may or may not follow that instruction under pressure, and you have no visibility into whether it did.
Observability Is What Separates a Prototype from a System You Can Operate
If you cannot see what your agent is doing in production, you cannot improve it, you cannot debug it, and you cannot defend it to a stakeholder when something goes wrong. This is not a model problem. It is an instrumentation problem.
Every agent I run in production emits structured logs for every decision point. I can reconstruct exactly what context the model received, what tool calls it made, what it returned, and how long each step took. When something breaks or behaves unexpectedly, I am not guessing. I have a trace.
This also matters for the ongoing work of improving the system. Prompt iteration without observability is guesswork. You change a few words, you redeploy, you wait to see if things seem better. With proper tracing, you can identify the specific input patterns that produce bad outputs, fix the underlying cause whether that is the prompt, the data, or the tool logic, and verify the fix actually worked.
In a manufacturing quality control agent I operated, the first month of production logs showed that about eight percent of escalations were happening because of a specific formatting inconsistency in how one data source reported batch numbers. Nothing in the prompt addressed it because nobody knew it existed until we could see the traces. We fixed the normalization step upstream. Escalation rate dropped by a third. The prompt never changed.
The Practical Takeaway for Anyone Building or Buying an Agent
If you are evaluating an agent built by a vendor or an internal team, ask these questions before you ask about the prompt.
- What happens when a tool call fails or returns stale data
- How does the agent handle a case it has not seen before
- Where does state live and how is it maintained across sessions
- What are the escalation conditions and how are they enforced in code not just in the prompt
- What does the observability layer look like and can you see a real trace from production
If the answers are vague, the system is not production-ready regardless of how good the prompt sounds in the demo. The prompt is the smallest part of the work. The teams that ship reliable agents know that and build accordingly.
The teams that do not ship reliable agents usually have a very polished prompt.