Deployment
If you can't see what it did, you won't trust it
An audit trail isn't a nice-to-have, it's a precondition for going live. What to log in an agent, in what form, and what people actually do with it.
There’s a point where every deployment is decided, and it isn’t the accuracy number. It’s the moment the department head asks: “and why did it decide that?”
If the answer is “that’s what the model thought”, the project is over.
What to log
For every step, on every case:
The input. Exactly what the step received. Not summarised: the actual content, or a reference to the unmodified source.
The decision made. What the step returned.
What it was based on. This is the important one, and the one most often omitted. Which field the total came from, which record it pulled from the master, which rule matched.
The uncertainty. How confident it was, and whether there was a close alternative.
Technical context. Which model, which version, which prompt revision, how long it took, what it cost.
That last block is operationally critical: without it you can’t answer, after the fact, whether last week’s regression came from a model update or from somebody editing a prompt by hand.
Who it’s for
Three audiences, each wanting something different.
The daily user. They don’t want a log file. They want to see, on the approval screen, where the data came from: the invoice image with the source field highlighted. A glance, not a search.
The operator. They need a filterable, searchable view: show me every case last week where confidence was below 0.7. That’s how you see which way the system is drifting.
The auditor or the executive. They want the complete history of one specific case, in order, exportable. If you can’t produce that, it’s a problem at audit time.
The log has to speak human
This is the most common mistake. The log is technically complete and only a developer can read it.
Bad:
step=vendor_match status=FAIL code=ERR_VENDOR_404 sim=0.61Good:
Supplier identification — failed
On the invoice: "Kovács és Tsa. Kft."
Closest match in the master: "Kovács és Társa Kft." (61% similarity)
The threshold is 85%, so it was not accepted. Awaiting human decision.The second carries the same information, but the finance clerk can resolve it without a developer. That’s several hours a week of difference.
What not to log
Logging doesn’t exempt you from data protection. Watch for:
- Personal data. Only as much as reconstructing the decision requires. The retention period matches the source data’s, not longer.
- Secrets. API keys, passwords and tokens never go into a log. It sounds trivial and it’s still the most common leak.
- Whole documents, duplicated. If the source is already stored, a reference is enough — otherwise you’ve doubled both your storage and your deletion obligations.
Why this is what produces trust
Much of the fear around AI comes from systems being unpredictable and opaque. You can’t fully fix unpredictable. You can fix opaque — and that’s purely a software engineering job.
In practice we see that a well-logged 85% system gets deployed more readily than an opaque 95% one. Because people know what happens to the other 15%.
Related: exception handling and shadow mode.
Questions on this topic
How long should logs be kept?
For operations, 90 days is usually enough. Where audit or regulatory accountability is involved, the applicable retention period governs — settle that during discovery, because retrofitting it is expensive.
Doesn't detailed logging slow the system down?
Negligibly. Log writes are asynchronous and orders of magnitude cheaper than a model call. Storage cost is marginal next to everything else.
What does this look like at your company?
If this problem sounds familiar, let's start with one process. Tell us which department burns the most manual hours — we'll come back with a concrete proposal.