How to Pull an Agent’s Black Box onto Your Laptop

The moment an agent system becomes truly difficult is not when the model gives a wrong answer, but when no one can explain why it was wrong. An even more troublesome scenario is when failure itself is quiet. On the surface, all you get is a single log line saying it “worked,” but underneath, several unnecessary tool calls may have repeated, the context may have bloated halfway through, and token costs may be leaking at a pace that is hard to notice. If the result is bad, finding the cause is difficult, and if the result looks vaguely acceptable, it is even more dangerous. The system can keep burning money while making you think it is healthy.

That is why the important question in agent development today is no longer “Which model should we plug in?” Questions like “What path did this execution follow?”, “Where did the context get contaminated?”, and “At what point did cost and quality begin to trade places?” are much more practical. This is also why local-first observability tools like Lookspan are drawing attention. By name alone, it sounds like a simple debugger, but what this category of tools is actually aiming at is much broader. It is not just about opening up the agent’s black box. It is about pulling execution traces onto the developer’s desk and turning them into something observable and repeatable.

Most teams fixate on behavior before observability when they first build an agent. They refine prompts, clean up tool schemas, change memory strategies, and layer on retry policies. Then, at some point, strange things start to happen. The same input fails only occasionally. It worked fine in staging, but answers become unstable only in production. Costs spike only for a specific customer account. When you try to reproduce it, everything looks normal again. At that point, conventional application logging is almost powerless. HTTP requests and DB queries are relatively deterministic, but LLM calls are inherently probabilistic, and the state of external tools, the length of the history, the quality of intermediate summaries, and even function call decisions are all tangled together.

In these systems, the unit of “one request” is too coarse. An agent actually moves through many layers of fine-grained judgment. You need separate visibility into what messages were trimmed and passed along, why a tool was chosen, how its result was summarized again, how many retries occurred, and how much cost accumulated at intermediate steps. This is where the concept of a span becomes useful. It was originally a widely used unit in distributed tracing, but it fits the agent world better than expected. If you treat one execution as a parent span and attach child spans under it for model inference, retrieval, tool execution, memory read/write, reranking, and post-processing, the flow starts to reveal itself. You begin to see not just “what happened,” but “in what order, at what time and cost, while consuming what context.”

The phrase local-first is also easy to miss if you treat it as a matter of taste. Observability data for agents is often far more sensitive than ordinary application logs. It can include raw prompts, intermediate text that hints at internal reasoning, fragments of customer documents, search results, tool arguments, and parts of responses. Sending that data to a remote SaaS from the start is convenient, but it immediately invites questions from security and legal teams. By contrast, storing it locally first and exporting only what is needed, when needed, whether shared or anonymized, gives you both development speed and control. Especially in the early stages, it helps avoid the paradox of introducing yet another layer of operational complexity just to observe the system. The shorter the loop from viewing an execution flow on your laptop, to checking cost, to running a replay, to doing a simple eval, the faster design decisions become compared with prompt tweaking.

This is where replay becomes important. Agent debugging wears people down because even when you have seen a failure, it is hard to encounter exactly the same failure again. Saving only the input is not enough. You need to preserve what system prompt was attached, what tool results came in, what model parameters were used, how full the context window was, and even what compression or summarization happened along the way, so you can replay a similar path. Replay is not just a reproduction tool. It is a design experiment mechanism. For example, you can compare what happens when you reduce the top retrieval count from 8 to 4, or remove the planner stage and switch to direct execution, and see which spans get faster and which spans lose quality. Instead of tuning agents by feel, you turn execution history into comparable experimental groups.

When eval sits on the same screen, the nature of debugging changes again. Many teams think of observability and evaluation separately. Observability is for operations, evaluation is for research. But with agents, both often point to the same questions. Did cost go down while answer accuracy stayed the same? After switching to a faster model, did the number of tool calls increase? Did hallucinations decrease, but only because the system became so conservative that it gave up on solvable problems? If spans, replay, and eval live apart, comparisons like these become slow and exhausting. If they are connected in one place, you can examine “Why did this failure case happen?” and “What effect does this change have across the whole distribution?” in one motion. In agent development, the most expensive resource is often not tokens but attention, and this linkage reduces that waste significantly.

Many failures come not from dramatic model limitations but from small gaps in observability. A common example is runaway cost. On the surface, it looked like the system answered once, but internally it bounced back and forth between planning and validation, repeatedly hitting similar tools, and kept appending context while retrying failed calls. Response quality barely improved, but token usage and latency kept accumulating. This problem is not solved by saying, “Let’s just use a cheaper model.” In fact, a cheaper model can make tool selection more unstable and raise total cost. What you need is visibility into which span is becoming abnormally long, under what conditions fan-out happens, and whether there are patterns of repeated calls. Without observability, cost appears only as an accounting line item. With observability, cost becomes an execution characteristic you can control.

Another common trap is that the definition of success and failure is too crude. Agents are hard to evaluate based only on whether they got the right answer. They may have taken too long, read far too many documents, or delivered an answer to the user while taking a dangerous detour internally. For example, in a sensitive system, the moment tool permissions are exercised even slightly incorrectly, the run has already failed no matter how normal the final response looks. In these environments, the execution trajectory itself matters more than simple pass/fail. You need operating rules such as always raising a warning if a certain tool is called, forcing redaction if a certain prompt pattern appears, or intervening with a summarization policy if the reasoning chain grows too long. For observability tools, what matters more than a polished interface is where these kinds of rules can be inserted.

A name like Lookspan is interesting because it sounds like a declaration to turn attention away from the result and toward the process. While many developer tools sell the promise of a “smarter model,” this category sells “more readable execution traces.” It is less flashy at first glance, but in practice it is the kind of value that lasts much longer. An agent is, in the end, a system that automates several uncertainties at once. Systems full of uncertainty need explainability before they need performance. Only once explainability is in place can you tune performance, optimize cost, and control permissions. Until now, most of that explainability has been assembled in people’s heads. Attempts to bring execution graphs, spans, cost, replay, and eval into one place should be read as efforts to reduce exactly that inefficiency.

That does not mean local-first observability is a silver bullet. The first illusion is the comfort of thinking, “If it stays local, it is safe.” In reality, the data left on local machines may be even more sensitive. Prompts, document fragments, test inputs, API responses, and even failure cases all remain on individual developer devices. Without encryption, retention limits, sharing boundaries, and masking policies, the risk has not disappeared, it has only changed location. The second illusion is the urge to think, “If we record everything, it will be useful someday.” Agent observability quickly turns excessive. If you store full message transcripts, every tool payload, intermediate candidate sets, and debug text without omission, the cost of reading the data explodes before the storage bill does. Without judgment about what to keep, the observability tool becomes yet another black box.

The third trap is applying existing standards like OpenTelemetry too narrowly from a traditional application perspective. In web request tracing, meaningful span names alone can get you part of the way. But for agents, semantic conventions matter much more. Fields like llm.model, prompt.version, tool.name, retrieval.k, input.tokens, output.tokens, cache.hit, and eval.score need to be attached consistently if you want meaningful comparison later. Otherwise, the screen may look convincing, but you still cannot properly line up different executions side by side. In agent observability, what matters is not “it was visible,” but “it can be compared.” If comparison is impossible, retrospection may be possible, but improvement is hard.

In practice, the way you read operational signals is also different from traditional services. Before CPU or memory, you often need to look at tool call breadth, average context length, retry rate, token variance for the same query, and how failures concentrate around a specific prompt version. For example, if the error rate is low but response time is gradually increasing, the issue is more likely that retrieval results have become longer or intermediate summarization is collapsing than that the model itself has changed. If cost spikes only during certain hours, the cause may be not just more traffic but a certain query type over-activating the planner. If answer quality wobbles for the same class of questions, there are times when you should suspect cache invalidation or document snapshot differences before temperature. These signals are almost impossible to read from a traditional APM dashboard alone. Agent-specific observability is ultimately instrumentation for understanding the system’s behavioral grammar.

A simple example of what a span structure feels like might look like this:

trace("customer-support-run", async () => {
  await span("retrieve-docs", { k: 6 }, retrieveDocs)
  await span("plan-actions", { model: "gpt-4.1-mini" }, planActions)
  await span("tool.create-ticket", { tool: "jira" }, createTicket)
  await span("final-answer", { evalTarget: "groundedness" }, answerUser)
})

The point of this code is not the syntax but the perspective. It is about breaking one execution into units of judgment rather than units of functionality, and recording not just time at each stage but also the connection points for cost and quality evaluation. When an agent fails, what you need is not a long prompt but this kind of visibility into which stage the context became distorted.

What is interesting is that tools like this eventually change development culture as well. Until now, improving agents has often depended on a craftsperson’s intuition. Someone tweaks a prompt, deploys it because it feels better, and when a problem appears, someone else digs through logs and reconstructs things by instinct. Once execution traces are recorded clearly, the unit of discussion changes. Instead of “Let’s rewrite this sentence,” conversations become “The variance in tool selection at this step is too large,” “Retrieval span time increased from this prompt version onward,” or “This change lowered average cost but increased fan-out on failures.” Arguments of taste become arguments about instrumentation. At that point, agent development finally starts to look less like magic and more like engineering.

A local-first approach is especially meaningful for small teams and individual developers. You do not need to build a huge observability pipeline first, and you do not need to bend your design just to fit the data model of a remote platform during early experiments. That may be what is implied by the feeling of being able to get started immediately with a single npx command. Agent experiments are usually short-lived, change frequently, and often benefit more from seeing failure quickly than from scaling success dramatically. If installation, configuration, and external dependencies are heavy, observability always gets pushed to “later.” But with agents, observability added later is especially expensive. If you do not think from the start about how to record execution units and metadata, you eventually reach a state where records exist but interpretation is impossible.

In the end, what matters is not the tool’s name but the attitude behind it. When an agent fails or quietly burns money, what you need is not a longer prompt but the ability to read execution traces. Spans are the focus of that eye, replay is its memory, and eval is its standard of judgment. Local-first is closer to a placement strategy that lets you work with those three things at shorter range. For a while, the agent industry has competed on “how smart is it,” but in the real world, “how readable is it” may prove to be the more durable advantage. Even if we cannot eliminate the black box entirely, we can at least pull it down to a level where we can trace what happened. Observability in the age of agents may produce its greatest productivity gains from precisely that modest goal.

Comments

Loading comments.