XIV · Anti-PatternsAnti-pattern✕

Black-Box Opaqueness

also known as Opaque Agent, No-Trace Agent

Anti-pattern: ship an agent without traces, decision logs, or provenance, then debug from user reports.

Context

A team is shipping an LLM-based agent under schedule pressure, often using a framework that emits no traces by default. Observability — recording each model call, each tool invocation, and the decision that led to it — is treated as something to add later once the product proves itself. The agent goes to production with no run logs, no decision log, and no record of which inputs led to which outputs.

Problem

When the agent eventually does something wrong, and it will, the team has no record of what the agent saw, what it decided, or which tool it called with which arguments. Debugging collapses into trying to reproduce a user's vague timeline from memory, and most incidents are never explained at all. The team ends up retrofitting traces during an outage, which is the most expensive moment to add them.

Forces

  • Observability has a cost (storage, dev time).
  • Frameworks differ in trace quality.
  • Privacy and trace coverage tension.

Example

A startup ships a customer-facing agent in a hurry with no traces, no decision logs, and no tool-call provenance. A week later a user complains the agent issued a duplicate refund. The team has nothing to look at — they spend two days trying to reproduce the bug from the user's vague timeline and never definitively explain it. This is the Black-Box Opaqueness anti-pattern: the absence of observability is itself the failure, and recovery requires retrofitting traces to every step before the next incident.

Diagram

Solution

Therefore:

Don't. Add traces, decision logs, and provenance from day one. See provenance-ledger, decision-log, lineage-tracking.

What this pattern forbids. By definition, this anti-pattern imposes no useful constraint; the missing constraint is the failure mode.

And the patterns that stand alongside it, or against it —

  • alternative-toProvenance Ledger★★— Log every agent decision and state change with enough metadata to explain or reverse it later.
  • alternative-toDecision Log★★— Persist the agent's reasoning trace alongside its actions so post-hoc review can explain why.
  • alternative-toLineage Tracking★★— Track which prompt version, model version, and data sources produced each agent output.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

References

Provenance