DEV Community: Saurav Bhattacharya

Your Agents Are Fine. The Handoff Between Them Isn't.

Saurav Bhattacharya — Fri, 26 Jun 2026 01:02:37 +0000

Every guide to evaluating AI agents quietly assumes there is one agent. One model, one loop, one output you can score. So you build a clean eval harness, you trace the loop, you gate on a pass rate, and you feel good.

Then your system grows up. A router agent decides which specialist to call. A researcher agent hands a draft to a writer agent. A planner spawns three workers and merges their results. Now you do not have an agent. You have an org chart of agents, and the thing that breaks is almost never inside one of them. It is the handoff — the seam where one agent's output becomes another agent's input.

This is the failure class nobody puts in their eval suite, because it does not live in any single agent. I want to argue that multi-agent systems need a different shape of evaluation and a different shape of observability, and that if you bolt your single-agent tooling onto them you will ship blind.

The seam is where the bodies are buried

Here is a concrete incident. A support pipeline: a triage agent classifies an inbound ticket, then routes to either a billing agent or a technical agent. Each agent, in isolation, was excellent. Triage scored 0.94 on its classification eval. Billing scored 0.91 on resolution quality. Technical scored 0.89.

The pipeline as a whole was a disaster. Refund requests were landing in the technical agent, which would cheerfully invent a troubleshooting plan for a billing problem. Every component passed its own eval. The system failed anyway.

Why? Because triage emitted {"category": "refund_issue"} and the router was matching on "billing". The category vocabulary had drifted between two prompts owned by two people. No single-agent eval can catch this, because no single agent is wrong. The contract between them is wrong.

If you only evaluate agents in isolation, you are unit-testing a distributed system and calling it integration coverage. It is not.

Evaluate the contract, not just the agent

The fix is to treat every handoff as a first-class thing to assert on. Two layers:

Structural contract — deterministic. The producing agent's output must match the consuming agent's expected schema and its expected value domain. This is cheap, fast, and catches the vocabulary-drift class of bug completely.
Semantic handoff quality — model-judged. Given what the upstream agent produced, did the downstream agent receive enough context to do its job? Did the writer agent get the facts the researcher actually found, or a lossy summary?

The structural layer is where most of your protection comes from, and it is the cheapest thing in the entire stack. Here is the kind of contract check I put between every pair of agents:

import { z } from "zod";

// The contract is owned jointly by producer + consumer.
const TriageOutput = z.object({
  category: z.enum(["refund_issue", "charge_dispute", "tech_fault"]),
  confidence: z.number().min(0).max(1),
  customerId: z.string().uuid(),
});

type Handoff = {
  from: string;
  to: string;
  payload: unknown;
};

function assertHandoff(h: Handoff, schema: z.ZodTypeAny) {
  const result = schema.safeParse(h.payload);
  if (!result.success) {
    throw new HandoffViolation(h.from, h.to, result.error.issues);
  }
  return result.data;
}

class HandoffViolation extends Error {
  constructor(from: string, to: string, issues: unknown) {
    super(`Contract broken: ${from} -> ${to}`);
    this.cause = issues;
  }
}

Run this as an eval over recorded production handoffs, not just live. If triage starts emitting a category the router has never heard of, that is a failing test before it is a 2am page. This is exactly the deterministic-first, judge-second tiering that works for single agents — you are just applying it to the edges of the graph instead of the nodes.

But here is the part teams get wrong: a green contract eval tells you the seam is typed correctly. It does not tell you the seam is good. For that you need to see what actually flowed.

You cannot debug a seam you cannot see

When a handoff eval goes red, the score is useless on its own. "Handoff quality 0.6" tells you nothing actionable. You need to answer: what did agent A actually emit, what did agent B actually receive after the router mangled it, and which tool call in between dropped a field?

This is the split that matters, and it is why I run agent-eval and AgentLens as one workflow rather than two tools. agent-eval owns the judgment: it scores the agent's output, runs the structural contract checks, flags drift when a category vocabulary shifts, and catches the ungrounded claim when the technical agent invents a refund policy. It is the layer that decides pass or fail and gates the release.

AgentLens owns the trace: it captures every model call and every tool step across all the agents in the pipeline as one connected run — the resolved inputs each agent actually saw, the raw outputs each one actually produced, and the exact payload that crossed each seam. So when agent-eval says "handoff triage->billing scored 0.6," AgentLens lets you click into that specific run and watch refund_issue get silently coerced to null at the router boundary. The eval gives you the signal; the trace makes the signal debuggable. One without the other is either a number you cannot act on or a firehose you cannot grade.

In a single-agent world you can sometimes get away with eyeballing logs. In a multi-agent world the trace is a graph, and you will not reconstruct it by hand. The eval tells you a seam is bad; the trace is the only thing that tells you which seam and why.

A scoring model for graphs, not loops

Concretely, stop reporting one pass rate for "the system." Report a matrix:

Node scores — each agent in isolation, as you do today.
Edge scores — each handoff: structural contract pass rate + semantic quality.
Path scores — end-to-end on real routes (triage->billing, triage->technical), because an agent can be locally correct and globally useless.

The edge and path scores are the new information. They are also where regressions hide, because a prompt change to one agent can pass that agent's node eval while quietly breaking the contract its downstream neighbor depends on. Catch it at the edge, then jump to the AgentLens trace to see the field that changed.

The takeaway

Single-agent evals are a solved-enough problem. Multi-agent systems are not, because the unit of failure moves from the agent to the seam between agents, and almost no one is evaluating the seam. Assert the contract deterministically at every handoff, score your system as a graph with node/edge/path layers, and keep the eval signal welded to the trace that produced it — agent-eval to grade the seam, AgentLens to show you the byte that broke it. Your agents were never the problem. The handshake was.

Your Evals Are Flaky Too: Stop Trusting a Pass Rate You Can't Reproduce

Saurav Bhattacharya — Thu, 25 Jun 2026 01:03:04 +0000

We spent two years teaching everyone that agents are non-deterministic. Same prompt, different output, every run. Fine. We internalized it. We stopped asserting equality, we built model-as-judge evals, we put them in CI.

And then we quietly assumed the evals were deterministic. They are not.

Your eval suite is a non-deterministic system grading another non-deterministic system. If you haven't measured how much your own grader wobbles, you don't have a quality gate. You have a coin flip wearing a lab coat.

The bug that taught me this

We had a model-as-judge check on a support agent: "Does the response correctly resolve the customer's stated issue? Return PASS or FAIL." Green for weeks. Then a release went out, the dashboard stayed green, and complaints spiked anyway.

I reran the exact same eval on the exact same 200 stored responses. 14 of them flipped verdict. Not because the agent changed — the responses were frozen on disk. The judge changed its mind. Temperature, sampling, a model-side update, who knows. My "97% pass rate" was 97% +/- something I had never measured, and that something was big enough to hide a regression.

The eval wasn't wrong. It was flaky. And a flaky gate is worse than no gate, because it manufactures confidence.

Flaky evals come from three places

1. The judge model. Any LLM-as-judge call inherits the same variance as the thing it's grading. Run it at temperature: 0 and you reduce it, but "reduce" is not "eliminate" — providers don't guarantee determinism even at zero, and a silent model version bump resets your baseline overnight.

2. The harness around the judge. Retrieved context, the order tools resolved, a truncated input, a rate-limit retry that changed what the judge actually saw. The judge gave a perfectly consistent answer — to a different question than last time, because its inputs drifted.

3. Your own rubric. "Is this answer good?" is not a spec. Vague rubrics push the variance into the judge's interpretation, where you can't see it. Tight, decomposed rubrics collapse it.

Notice that only one of these is "the model is random." The other two are infrastructure, and you can't tell them apart from a PASS/FAIL alone.

Treat your eval like flaky test code, because it is

Backend engineers already know how to handle non-deterministic checks: you don't ship a flaky test, you quarantine it, you measure its flake rate, and you fix or delete it. Same discipline here.

First, quantify the flake before you trust the score. Run each judge call N times and look at the agreement, not the average:

type Verdict = "PASS" | "FAIL";

interface JudgeResult {
  verdict: Verdict;
  // every model + tool step that produced this verdict
  traceId: string;
}

async function stabilityCheck(
  caseId: string,
  runJudge: () => Promise<JudgeResult>,
  samples = 5,
): Promise<{ verdict: Verdict | "UNSTABLE"; agreement: number; traceIds: string[] }> {
  const results = await Promise.all(
    Array.from({ length: samples }, () => runJudge()),
  );

  const passes = results.filter((r) => r.verdict === "PASS").length;
  const agreement = Math.max(passes, samples - passes) / samples;
  const traceIds = results.map((r) => r.traceId);

  // If the judge can't agree with itself, the verdict is not a signal.
  if (agreement < 0.8) {
    return { verdict: "UNSTABLE", agreement, traceIds };
  }
  return {
    verdict: passes > samples / 2 ? "PASS" : "FAIL",
    agreement,
    traceIds,
  };
}

The point isn't the magic 0.8. The point is that UNSTABLE is now a first-class outcome. A case where the judge flips 3-of-5 is not a 60% pass — it's a broken check, and it should fail loud and get quarantined, not silently average into a comforting number.

Second — and this is the half everyone skips — you have to be able to debug the disagreement. Knowing a case is UNSTABLE is useless if you can't see why the judge split. That requires the trace behind every one of those five runs: the resolved prompt the judge actually received, the retrieved context, the tool outputs, the raw judge completion. Not the summary. The bytes.

This is exactly where the two-layer split earns its keep

This is the workflow I keep coming back to, and it's two halves of one loop — not two products you bolt together at the end.

agent-eval is the layer that scores and gates the output. It runs the deterministic checks and the model-as-judge passes, it computes the stability/agreement above, and it's the thing that turns "the agent answered" into PASS / FAIL / UNSTABLE that CI can act on. It owns the verdict.

AgentLens is the layer that captures the trace of how that verdict happened — every model call and every tool step, with resolved inputs and raw outputs, for both the agent run and the judge run. It owns the explanation.

You need both because the eval score alone can't tell you which of the three flake sources you hit. When agent-eval flags a case UNSTABLE, you pull the five AgentLens traces side by side and the cause is immediately legible: if the resolved judge inputs are identical across runs and the verdict still flipped, it's the judge model — tighten the rubric or pin the version. If the inputs differ, it was never a judge problem — your harness is non-deterministic and the agent's context drifted between runs. Same UNSTABLE flag, opposite fix. The verdict tells you that it's unstable; the trace tells you why, and the why is the only thing that's actionable.

Without the trace, every flaky eval looks like "the model is random," so you reach for temperature: 0, watch the flake rate drop a little, and convince yourself it's solved. It isn't — you just made the infrastructure bug quieter.

What to actually do Monday

Stop reporting a single pass rate from a single run. Report agreement. A 95% pass rate at 0.6 judge agreement is noise.
Make UNSTABLE a failing state in CI. If your grader can't agree with itself across a handful of samples, that case does not get to vote on whether you ship.
Pin and alert on judge model versions the same way you pin the agent's. A silent provider bump is a silent baseline reset.
When a check goes unstable, read the traces, not the average. The fix for "the judge is random" and "my context drifted" are opposite, and the verdict alone can't distinguish them.

We earned our humility about agents being non-deterministic the hard way. The eval layer is built from the same stochastic parts and deserves the same suspicion. A green dashboard you can't reproduce isn't a quality signal — it's a story you're telling yourself, and the only way to check whether it's true is to grade the grader and keep the trace that proves the grade.

You Can't Reproduce Your Agent's Bugs—That's Why You Can't Fix Them

Saurav Bhattacharya — Wed, 24 Jun 2026 01:05:27 +0000

Here is a bug report I have received, in some form, at every company running agents in production:

"The agent gave a customer a wrong refund amount yesterday around 2pm. Can you look into it?"

Here is how that investigation goes when your stack isn't built for it: you find the timestamp, re-run the same prompt, and it works perfectly. Correct refund, every time. You change nothing; it keeps being right. Eventually you write "could not reproduce — will monitor," which is a professional way of saying you gave up.

This is the failure I think is most under-discussed in the whole agent space. Not hallucination, not drift, not cost. Irreproducibility. A bug you cannot reproduce is a bug you cannot fix, cannot test, and cannot prove you've fixed. Agents are, by nature, the most irreproducible software most of us have ever shipped.

The opinion I'll defend: reproducibility is the precondition for every other quality practice you claim to have. Your evals, regression tests, and CI gates all assume you can take a real failure and run it again on demand. If you can't, that apparatus is built on sand.

Why "re-run it" silently lies to you

For a normal backend bug, reproduction is mostly free: same request, same row, same code, same bug. We've built an instinct that says if I run it again with the same inputs, I'll see the same thing. For agents that instinct is wrong in four independent ways, each enough to break reproduction alone:

The model is nondeterministic. Temperature above zero means the same prompt yields different completions. The 2pm run took a reasoning path your replay never will, and the bug lived on that path.
You aren't replaying the same input. You re-ran the same template. But the prompt the model saw had interpolated context — a retrieved document, the user's account state, the date, a tool result — and that resolved input is gone.
The world moved. The agent called a tool that hit a database or an API. Today those return different values than yesterday. Even a deterministic model would behave differently, because its inputs changed.
Hidden state. The model version rolled silently behind a pinned name; a cache was warm then, cold now; a flag flipped. None of it is in your code; all of it changed the run.

Only the first is about the model's randomness. The other three are about inputs you failed to capture — which means the fix is mostly engineering discipline, not a model problem. You can't make production deterministic, but you can make a run replayable, and those are very different goals.

Replayable beats deterministic

The instinct is to chase determinism: temperature: 0, pin every version, freeze the world. That's a trap. A temperature-zero agent is often a worse agent, and you still haven't captured the tool outputs, so you still can't reproduce a past failure. Determinism is something you'd impose on all of production forever. Replayability is a property you attach to each run as it happens, and it's strictly more powerful: it reconstructs that specific failure no matter how nondeterministic production was.

To replay a run you must have captured, when it happened: the resolved input (the exact bytes the model saw after templating), every tool call's raw output (what the APIs returned then), and the execution parameters (model id and version, temperature, seed, system prompt).

This is the seam where the two tools I lean on operate as one unit, because reproduction needs both a record and a verdict. AgentLens captures the trace — every model and tool step, the resolved inputs, the raw outputs, the parameters — the raw material a replay is rebuilt from. agent-eval is the other half: it takes that captured run, re-executes it under pinned conditions, and scores whether the bug is present. AgentLens makes the failure replayable; agent-eval makes the replay a pass/fail test you can gate on. A trace with no scorer is an archive you read by hand; a scorer with no trace is grading a prompt you've already lost.

import { getTrace } from "agentlens";
import { evaluate, assert } from "agent-eval";

interface ReplayBundle {
  resolvedPrompt: string;                 // exact bytes the model saw at 2pm
  params: { model: string; temperature: number; seed?: number };
  toolReplays: Record<string, unknown>;   // call signature -> raw output THEN
}

// Pull a real failure out of AgentLens into a self-contained replay bundle.
async function bundleFromTrace(traceId: string): Promise<ReplayBundle> {
  const trace = await getTrace(traceId);
  const model = trace.steps.find((s) => s.kind === "model");
  if (!model) throw new Error(`no model step in ${traceId}`);

  // Freeze each tool's output by call signature, so a replay returns
  // yesterday's values instead of hitting today's moved-on world.
  const toolReplays: Record<string, unknown> = {};
  for (const s of trace.steps.filter((s) => s.kind === "tool")) {
    toolReplays[`${s.name}:${JSON.stringify(s.input)}`] = s.output;
  }
  return {
    resolvedPrompt: model.input,                                 // RESOLVED input
    params: { model: model.model, temperature: model.temperature, seed: model.seed },
    toolReplays,
  };
}

// Re-run the agent against the captured reality. Tools are stubbed to replay
// recorded outputs, so the ONLY thing that can vary is the agent itself.
async function replay(b: ReplayBundle): Promise<string> {
  return runAgent(b.resolvedPrompt, {
    ...b.params,
    toolResolver: (name: string, input: unknown) =>
      b.toolReplays[`${name}:${JSON.stringify(input)}`],
  });
}

// Turn the reproduced failure into a permanent regression eval.
async function lockAsRegression(traceId: string, mustNotContain: string[]) {
  const b = await bundleFromTrace(traceId);
  const output = await replay(b);
  return evaluate({
    input: b.resolvedPrompt,
    output,
    checks: [
      assert.notContains(mustNotContain),  // the bogus refund amount, forbidden forever
      assert.judge({ criterion: "refund amount matches the tool result", threshold: 0.8 }),
    ],
    metadata: { sourceTraceId: traceId },  // provenance back to the real incident
  });
}

Two decisions do all the work. Tool outputs are replayed, not re-fetched: the toolResolver hands the agent yesterday's recorded responses instead of calling the live API. If your replay re-queries the database, you're testing a world that has changed, and any "fix" you observe might just be the data moving again — pinning tool outputs isolates the one variable you want to study. And the resolved prompt is replayed, not the template: the subtly-wrong retrieved document or the unusual account state lived in the resolved input, and nowhere else.

Replaying once is debugging; replaying many times is the fix

A subtlety I won't skip: if the failure happened on a high-temperature reasoning path, replaying once might reproduce it or might not, because you'll roll a different path. For nondeterministic failures a single replay isn't a reproduction; it's one sample.

The honest technique is to replay the bundle N times and measure the failure rate. A bug in 8 of 50 replays is reproduced — you've proven it's real and quantified it — even though no single run is guaranteed to show it. Your fix isn't "the replay passed once"; it's "the rate across 50 replays went from 16% to 0%."

async function reproductionRate(traceId: string, isBug: (o: string) => boolean, n = 50) {
  const b = await bundleFromTrace(traceId);
  const runs = await Promise.all(Array.from({ length: n }, () => replay(b)));
  const hits = runs.filter(isBug).length;
  return { rate: hits / n, hits, n }; // e.g. { rate: 0.16, hits: 8, n: 50 }
}

This reframes the bug-fixing loop. You don't fix a failure and eyeball it once; you capture it, establish its rate, change the agent, prove the rate dropped, and keep the replay in your suite so it can never silently climb back. agent-eval runs the bundle; the AgentLens trace behind it tells you, when a replay does fail, which step diverged from the recorded path.

What to do Monday

You don't need production to be deterministic. You need every run to be reconstructable:

Capture the resolved input, not the template. Store only the template and you've already lost most of your future bug reports.
Record every tool call's raw output inline with the run. A reproduction that re-fetches from a moved-on world is not a reproduction.
Stamp the execution parameters — model version, temperature, seed, system prompt — onto the trace. "It was a different model version" is a real root cause you'll otherwise never see.
Measure failure rate, not a single replay. For nondeterministic bugs, reproduction is statistical: replay N times, and treat "rate went to zero" as the bar for fixed.

The agents will keep producing failures you can't explain from the symptom alone. The difference between a team that fixes them and one that closes tickets with "could not reproduce" isn't model quality or prompt skill — it's whether the run left behind enough of itself to be run again. Capture the trace with AgentLens, replay-and-score it with agent-eval, and "could not reproduce" stops being a sentence you're allowed to write.

Shadow Deployments for AI Agents: Canary Your Prompt Changes Before They Burn Production

Saurav Bhattacharya — Mon, 22 Jun 2026 01:03:00 +0000

You shipped your agent. Evals were green. A week later you tweak the system prompt to fix one annoying edge case, the CI eval suite passes, you merge, and the next morning your support queue is on fire because the agent now refuses half the legitimate requests it used to handle.

This is the part nobody talks about: passing a pre-merge eval is not the same as knowing a change is safe in production. Your eval suite grades the cases you thought to write down. Production has cases you didn't. The gap between those two sets is exactly where agent changes go to die.

The fix is not "write more tests." It's borrowing something web infra has had for fifteen years and almost no agent team uses: shadow deployments and canary evals.

The deploy model agent teams skipped

When you deploy a normal service, you don't flip 100% of traffic to the new version and pray. You run a canary — 1%, then 5%, then 25% — and you watch error rates, latency, and saturation at each step. If the new version regresses, you halt and roll back before most users ever touch it.

Agent teams skipped this entirely. The typical agent "deploy" is: edit prompt, run offline evals, merge, full rollout. There's no canary because there's no obvious metric to canary on. HTTP 500s are easy. "The agent's answers got subtly worse" is not.

But it is measurable — if you have two things wired together: a way to score output quality continuously, and a way to see exactly how each answer was produced so a bad score is debuggable instead of mysterious. That's the entire reason agent-eval and AgentLens ship as a unit and not as two separate tools you bolt on later.

agent-eval scores and gates the agent's output: deterministic checks, drift detection against a baseline, hallucination/grounding checks. It answers "is this answer good?"
AgentLens captures the trace of how that answer was produced — every model call and tool step, the resolved inputs, the raw outputs. It answers "why did this answer come out the way it did?"

A canary score with no trace tells you the new version is worse but not where. A trace with no score tells you what happened but not whether it mattered. You need both, on the same request, or the canary is just a vibe with a percentage sign.

Shadow mode: grade the new version on real traffic before it serves anyone

The cheapest, safest first step is shadow deployment. Take live production requests, run them through both the current (champion) agent and the new (challenger) agent, but only return the champion's answer to the user. The challenger runs in the dark. You score both with agent-eval, trace both with AgentLens, and compare — on real traffic, with zero user risk.

import { evaluate } from "agent-eval";
import { trace } from "agentlens";

interface ShadowResult {
  requestId: string;
  championScore: number;
  challengerScore: number;
  championTraceId: string;
  challengerTraceId: string;
}

async function shadowCompare(
  request: AgentRequest,
  champion: Agent,
  challenger: Agent,
): Promise<ShadowResult> {
  // Champion serves the user; its trace is captured for debugging.
  const champRun = await trace("champion", () => champion.handle(request));

  // Challenger runs in the shadow — same input, result never returned.
  const challRun = await trace("challenger", () => challenger.handle(request));

  const [championScore, challengerScore] = await Promise.all([
    evaluate(champRun.output, {
      checks: ["grounding", "format", "drift"],
      baseline: request.baseline,
    }),
    evaluate(challRun.output, {
      checks: ["grounding", "format", "drift"],
      baseline: request.baseline,
    }),
  ]);

  return {
    requestId: request.id,
    championScore: championScore.value,
    challengerScore: challengerScore.value,
    championTraceId: champRun.traceId,
    challengerTraceId: challRun.traceId,
  };
}

Run this for a day across a few thousand real requests and you get something an offline suite can never give you: the challenger's score distribution on your actual traffic, not your imagination of it. When the challenger underperforms on some slice — say, multi-step tool requests — you don't argue about it. You pull the AgentLens trace pair for those request IDs and look at exactly where the two runs diverged: which tool got different inputs, which model step produced the regression.

Canary: promote on a score gate, not a calendar

Once shadow mode says the challenger is at least as good, you let it serve a small slice of real traffic and gate promotion on the live score — not on "it's been a week and nothing exploded."

interface CanaryGate {
  stage: number;          // current traffic percentage
  minScore: number;       // challenger must hold this
  maxDelta: number;       // and not regress vs champion by more than this
  minSamples: number;     // before any decision
}

function decideCanary(
  results: ShadowResult[],
  gate: CanaryGate,
): "promote" | "hold" | "rollback" {
  if (results.length < gate.minSamples) return "hold";

  const avg = (xs: number[]) => xs.reduce((a, b) => a + b, 0) / xs.length;
  const challengerAvg = avg(results.map((r) => r.challengerScore));
  const championAvg = avg(results.map((r) => r.championScore));
  const delta = championAvg - challengerAvg;

  if (challengerAvg < gate.minScore) return "rollback";
  if (delta > gate.maxDelta) return "rollback";
  return "promote";
}

The important detail: every rollback decision is attached to a set of failing challengerTraceIds. The gate doesn't just say no — it hands you the exact traces that caused the no. That is the difference between "the canary failed, somebody look into it eventually" and "the canary failed on these 14 requests, here are the traces, the regression is in the retrieval tool call." One of those gets fixed today.

Why the two halves have to be one workflow

You can technically buy a scoring tool and a tracing tool separately and duct-tape them. Most teams that do this end up with scores in one dashboard and traces in another, joined by nothing, and when a canary regresses someone spends an afternoon trying to line up timestamps to figure out which trace goes with which bad score.

The reason agent-eval and AgentLens are designed as a unit is that the eval signal is only as useful as it is debuggable. A score without its trace is a number you can't act on. A trace without a score is a haystack with no needle marked. Wire them together — same request ID, score and trace produced in the same step — and your canary stops being a guess. The eval tells you that the challenger regressed; the trace tells you exactly where, so the rollback comes with a root cause instead of a shrug.

The takeaway

Stop treating agent changes as merge-and-pray. You already accept canaries and shadow traffic for every other service you run; your agent deserves the same discipline, and it needs it more, because its failure mode is quiet degradation, not a loud 500.

Shadow new versions against real traffic. Gate promotion on a live score, not the calendar. And make sure every score comes welded to the trace that produced it — agent-eval to tell you whether the change is safe, AgentLens to tell you why — because a canary you can't debug is just a slower way to ship the same regression.

Harness Engineering Has No Fixed Address

Saurav Bhattacharya — Mon, 22 Jun 2026 00:17:04 +0000

TL;DR — Harness engineering is one thing: getting reliable judgment out of a reasoner you didn't train — given an instruction, bounded by a spec that can override that instruction, and verified before the result ships. It is not "the wrapper around the model." It's a property of code, not a place in your stack, and it lives on both sides of every tool call. The generic scaffolding — loops, dispatch, memory — melts into the model a little more every quarter. What survives is the part that stays external to the model: the specification of what the agent may do, and the verification that it did. That's the discipline. The rest is plumbing.

I've written before that Agent = Model × Harness, and that the harness is the half you actually engineer. I still believe the formula. But stop there and it oversells two things — so this is me correcting my own framing, precisely, with code.

The two things the formula gets wrong

The × oversells separability. Multiplication implies the factors are independent. They aren't. A better model doesn't leave your harness untouched — it dissolves parts of it. Chain-of-thought prompting became reasoning models. ReAct-style tool loops became native tool use. Half your RAG plumbing is being quietly absorbed by longer context and better-trained retrieval. Every model generation collapses a layer of harness the previous one needed.

"Harness absorbs software engineering" oversells the annexation. It doesn't absorb it. It partly consumes it — pulls in the slice that encodes the agent's behavior — while the deterministic spine (payments, ledgers, auth) and the dumb tools stay exactly what they were. Relocation with an annexation at the seam. Not a takeover.

Both corrections point at the same uncomfortable question: if the model eats the scaffold every quarter, isn't the harness the melting part — the thing you'd be foolish to bet a career on?

What melts, and what doesn't

Here's the resolution, and it's the whole point.

The harness mechanism melts. The loop, the dispatch, the retry, the memory-stitching — that's the part the model and the frameworks commoditize, and they should.

What doesn't melt is the part that's external to the model:

The model can get arbitrarily good at running an agent and still not know what your agent is for.

Your refund policy isn't in the weights and never will be. Your escalation thresholds, your risk tolerance, what this agent must never do regardless of how it's asked — that's private, contextual, and changing. It's a specification, and specifications live outside the thing they govern. Same for evaluation: a model can't be its own measurement layer without circularity — the thing being judged can't be trusted to judge itself.

So the durable core of harness engineering was never the machinery. It's specification and verification — defining the envelope of allowed behavior, and proving the agent stayed inside it. Both survive every model upgrade for the same reason: they're external to the model, one as constraint, one as adversary.

The boundary has no fixed address

The tempting picture is tidy: the harness wraps the model, and the tools sit outside it. That picture does not survive contact with agent-facing APIs.

Ask where the refund cap actually lives. In the agent's orchestration guardrails? Or in the refund endpoint that refuses the call? The honest answer is both — and the load-bearing copy is the one in the API, because you never trust a probabilistic reasoner to self-limit. Defense in depth pushes the hard constraints down into the tool. Which means the agent-facing endpoint is doing harness-grade work — specifying and constraining agency — from the far side of the boundary you thought separated harness from tool.

So harness engineering isn't a location in the stack. It's a property:

Does this code exist to bend a fallible reasoner toward a spec?

Run that test and the boundary stops mattering. The model-facing side — the code that talks to the model, elicits its judgment, constrains it — passes wholesale; that's its entire job. The service side passes selectively: a plain database or a human-facing endpoint is just a tool, but an endpoint purpose-built for an agent — idempotent, dry-runnable, policy-enforcing, with errors a model can parse and recover from — is harness. The Stripe-for-agents dev is doing harness engineering. The Stripe-for-humans dev whose endpoint an agent happens to call is not. Membership by function, not address.

And the model itself? Never. It's exogenous — the × you don't own.

What it looks like in code

Here's the whole discipline as one function. The comment headers are the taxonomy:

def handle_refund(instruction, ctx):
    # ── MODEL-FACING (agent side): elicit judgment from the non-deterministic reasoner
    decision = model.decide(
        instruction=instruction,        # per-task: "refund this customer"
        policy=ctx.policy_summary,      # standing spec, handed to the model
        account=ctx.account,
    )  # -> { action: "refund", amount: 52000, reason: "..." }

    # ── THE ENVELOPE: a spec that OUTRANKS the instruction.
    # This is CODE, not a prompt. You can argue with a prompt.
    # You cannot argue with an if-statement. That line is the discipline.
    if decision.action == "refund" and decision.amount > ctx.policy.auto_approve_cap:
        return escalate(decision, reason="over auto-approve cap")

    # ── RUNTIME EVAL (inner loop): verify the judgment BEFORE the side effect commits
    check = evals.verify(decision, ctx.policy)
    if not check.passed:
        log_failure(check)              # outer loop: feeds harness re-tuning across versions
        return escalate(decision, reason=check.violation)

    # ── ENVIRONMENT-FACING (service side): agent-optimized tool, idempotent on purpose
    return refund_api.execute(
        amount=decision.amount,
        idempotency_key=ctx.request_id, # because the model might retry
    )

(model.decide, evals.verify, and refund_api.execute stand in for the real implementations.)

The teaching is in two lines.

The envelope if is what makes this harness engineering and not prompt engineering. If the cap lived in the prompt, the model could be cajoled past it — flattered, confused, jailbroken. In code, it can't. That single branch is "reliable judgment given an instruction, bounded by a spec that can override it" — compiled.

And evals.verify before execute is the judgment getting checked while it's still cheap to be wrong.

Now notice what's absent: the model itself (exogenous), and any human-facing refund UI (a tool, not harness). Run the membership test down every line — does this exist to bend a fallible reasoner to a spec? — and everything that remains is the harness.

The hard part isn't obedience — it's refusal

The naive read of "reliable behavior" is does the agent do what it's told. That's the easy half, and it's the half models are getting better at on their own.

The durable, hard half is the opposite:

Reliable judgment includes the agent refusing when the instruction would breach the spec.

The refund agent's hardest moment isn't executing "refund this customer." It's declining "refund $50,000" even though it was told to. That refusal doesn't come from the instruction — it comes from the envelope that outranks it. And making a probabilistic reasoner reliably disobey at exactly the right boundary, every time, is the whole safety problem in miniature. It's also the failure that doesn't surface until it's expensive — which is exactly why you verify it in code rather than hope for it in a prompt.

Evals are the feedback — and there are two of them

A discipline with a measured error signal you can drive down is engineering. Without it, it's prompt-craft. Evals are what close the loop — and there are two loops, nested at different timescales.

The inner loop is the runtime check that catches the bad judgment before it commits — the evals.verify above. It feeds the agent, mid-task. It's how the envelope gets enforced, and it saves the money now.

The outer loop is the offline suite that tells you "this agent breaches policy 3% of the time." It feeds you, across versions, and re-tunes the harness over weeks.

Same discipline, two controllers. One keeps a single decision inside the lines; the other keeps the system improving.

The whole thing, assembled

Step back and it's a control system, and every piece has a name:

The model is the plant — powerful, non-deterministic, the thing you're controlling.
The spec (instruction + overriding envelope) is the setpoint.
The harness is the controller.
The evals are the feedback.

That's harness engineering, fully factored.

The bet

Here's the part that reconciles "bet on the harness" with "the harness melts," because both are true.

Every individual harness melts. Each one has the model's shadow baked into it — its specific failure modes, its current reliability — and gets rewritten when the curve moves: fewer guardrails as the model gets dependable, different ones as its failure modes shift. The artifact is disposable.

The discipline doesn't melt. Something must always specify what an autonomous reasoner may do, and prove it stayed inside that — and that something sits external to the model, which is exactly why no model generation can absorb it.

The harness melts. Harness engineering doesn't.

So the bet isn't "build the loop" — the model ships more of the loop every quarter. The bet is: be the person who decides what the agent is allowed to want, and can prove it stayed there. Mechanism commoditizes. Specification and verification don't.

And the surface is only getting wider, because the consumer of software is changing — your users are becoming agents too. Every system that exposes itself to an autonomous reasoner now needs a face built for one. That face is harness work, wherever it sits.

The model half is being handed to all of us for free, and it gets better every quarter. Whether your agent — your product, your role — gets better is a question about the half you engineer: the judgment you specify, and the verification that holds it true.

That's where I'd place the bet. It just doesn't have a fixed address.

The Agent Is the Harness, Not the Model — and Why That Reorganizes Software Engineering

Saurav Bhattacharya — Sun, 21 Jun 2026 23:09:11 +0000

TL;DR — Every AI system decomposes into two things that matter: the model and the harness (the code wrapping it). Claude Code, GitHub Copilot, ChatGPT — those are harnesses, not models. Right now only frontier labs build both halves. That won't last. As harness engineering becomes its own discipline — domain-specialized, model-agnostic — it absorbs most of what we currently call software engineering. The app store becomes the agent store, and our job shifts from writing code for humans to writing harnesses that automate human workflows.

I keep coming back to one formula whenever someone asks where AI engineering is actually headed:

Agent = Model × Harness

It sounds almost too simple. But it draws a line that clears up a surprising amount of confusion — about what an agent is, about who builds them, and about what our jobs become.

The distinction: model vs harness

Claude Code is an agent. GitHub Copilot is an agent. Their CLIs are agents. ChatGPT is an agent.

None of those things are models. They're harnesses — the software infrastructure built on top of an LLM that turns raw next-token prediction into something that plans, calls tools, holds context, retries, and ships a result.

The clean way to hold it in your head:

If GPT-5.5 is the model, then ChatGPT is the harness wrapping it.

The model is one ingredient. The harness is the dish.

This isn't pedantry. Separating the two gives you the only two levers that matter at the highest level of any AI system:

The model — the raw reasoning. Swappable. Improving on a curve you don't control.
The harness — goals, loops, tools, memory, evals, the product surface. The part you actually engineer.

(There's a third ingredient — data — but it's implicit in both. It trains the model and it flows through the harness.)

Almost every interesting engineering decision in an AI product lives in the harness, not the model. Which prompts. Which tools, with which guardrails. How the loop terminates. What gets remembered. How failures get caught. You don't train GPT — you wrap it. The wrapping is the work.

Why this framing matters now

Here's the part that turns a definition into a thesis.

Today, only the frontier labs build both halves. OpenAI builds GPT and ChatGPT. Anthropic builds Claude and Claude Code. The model and the harness ship from the same building, by the same company, as one bundle.

That is a temporary arrangement. It's what the early phase of every platform looks like — the people who make the engine also make the only car.

It won't stay that way, because the harness is separable from the model, and we're already watching the split begin.

GitHub Copilot is the clearest preview. It's a harness that wraps any major model — you can point it at different frontier models underneath. The harness is the product; the model is a swappable backend. That's the shape of the future, generalized: harnesses as first-class products, model-agnostic, increasingly specialized to the domain the agent operates in.

A coding harness wants tool access, repo context, and test loops. A legal harness wants citation discipline and retrieval grounding. A support harness wants state verification and escalation paths. A finance harness wants determinism and audit trails. Same underlying models — radically different harnesses, because the domain is where the engineering lives.

The claim: harness engineering absorbs software engineering

So here's the bold version, and I'll own that it's bold:

As harness engineering matures into its own discipline, it consumes most of what we currently call software engineering.

Call it agentic engineering, call it harness engineering — the name matters less than the shift. The center of gravity of the work moves from writing the deterministic logic ourselves to engineering the system that wraps a model so it can do the non-deterministic parts well.

I'm not the only one pointing at this. Dario Amodei has said versions of this publicly — that an enormous fraction of code, and of knowledge work generally, is heading toward being written and operated by these systems rather than typed by hand. You don't have to accept the most aggressive timeline to see the direction.

And we're already seeing the early traces:

Companies are bolting chatbots and agents onto their existing products — first as a side feature, a widget in the corner.
Then those capabilities stop being bolt-ons and bleed into the core offering. The agent stops being the thing beside the product and becomes a primary way you use the product.

Follow that to its conclusion and you get an agentic app ecosystem. Think app store — but for agents. An agent store.

It happens on a spectrum, not a cliff

I want to be precise here, because the lazy version of this take is "AI replaces all code," and that's wrong.

The realistic version is a spectrum:

Foundational business processes stay code- and determinism-heavy. Payments, ledgers, auth, anything where "approximately right" is a defect — that stays deterministic code, and it should. You do not want a probabilistic model freelancing your double-entry accounting.
The human-driven parts get automated by agents. All the judgment, glue, triage, and workflow that never got automated because only a person could do it — that's exactly the territory agents move into. Not by replacing the deterministic core, but by filling the gaps around it that used to require a human in the loop.

So the work doesn't vanish. It re-shapes. Our job stops being only "write code for other humans to use" and increasingly becomes "write systems that automate human workflows via agents." The deterministic spine remains; the soft tissue around it gets agentic.

What this means for our roles

If you zoom out, the discipline splits cleanly along the same line as the formula:

Developers move to the harness side. ML folks own the model side.

Model side — the people training, fine-tuning, evaluating, and improving the raw reasoning engine. This stays specialized and stays with the people who do ML.
Harness side — the people designing goals, wiring tools, closing feedback loops, building the eval and observability layers, and shaping the domain-specific product the agent lives inside. This is where most developers end up.

That's not a downgrade for software engineers. It's a relocation. The harness is where correctness, safety, latency, cost, and user trust are actually decided. The model gives you capability; the harness decides whether that capability becomes a product or a liability.

The honest caveat

I'll flag the part it's tempting to oversell. None of this means "models do everything and engineers go home." The opposite, really: as models get more capable, the harness becomes more important, not less, because a more capable model with a sloppy harness is a more capable way to fail. The leverage of good harness engineering goes up as the underlying model improves.

That's the whole bet. The model is improving on its own, on a curve you don't control. Whether your agent — your product, your company, your role — improves is a question about your harness.

Agent = Model × Harness. The model half is being handed to all of us for free, and it's getting better every quarter. The harness half is the part we get to engineer. That's where the next decade of this work lives — and that's where I'd be placing my bets.

This is the long-form version of a thought I first posted on LinkedIn. If you want the short, punchy take and the discussion around it, it's here: the original LinkedIn post. For the companion piece on what actually goes inside a harness — goals, loops, tools, lens, and evals — and why your eval layer is part of the agent rather than a tool beside it, see Agent = Model × Harness: Your Eval Layer Is Part of the Agent.

Goodhart's Law Comes for Your Agent Evals: Why Your Green Dashboard Stops Meaning Anything

Saurav Bhattacharya — Sun, 21 Jun 2026 01:02:27 +0000

There is a specific moment in the life of every agent team that nobody puts on the roadmap. You build an eval suite. It catches real bugs. You wire it into CI as a release gate. The dashboard goes green. And then, somewhere over the next three months, the green stops meaning anything — while everyone keeps treating it like it does.

This is Goodhart's Law, and it is coming for your agent evals whether you plan for it or not.

"When a measure becomes a target, it ceases to be a good measure."

The day your eval suite becomes the thing that decides what ships, it stops being a neutral measurement of quality and becomes a target your team optimizes toward. That is not a hypothetical risk. It is the default trajectory, and most teams only notice after a "fully passing" release lands in production and quietly makes everything worse.

How a good eval suite rots

The decay is boring, which is exactly why it's dangerous. Here's the usual sequence:

You write evals against the bugs you already found. Reasonable. But now your suite measures yesterday's failure modes, not tomorrow's.
A change fails one case. Instead of asking "did we regress?", someone asks "is the eval too strict?" and tweaks the assertion until it's green.
Prompts get tuned to the eval set. Few-shot examples drift toward the exact phrasings your judge rewards. The agent gets better at your test cases and no better at the actual job.
The held-out set quietly becomes the training set. Every case you debug against is a case you've now overfit to.

The endpoint is an agent with a 98% pass rate that is measurably worse for users — because the score is now measuring how well the agent satisfies the test, not how well it does the work. The map replaced the territory.

The tell: a green gate you can't explain

The cleanest signal that Goodhart has arrived is this — a release passes the gate, and nobody on the team can explain why a specific borderline case passed. It just did. The score is a number with no narrative behind it.

That's the real problem. A pass/fail bit is not a measurement you can reason about. It's a measurement you can only trust or distrust. And trust, unaudited, always decays toward green.

This is exactly the seam where the two tools I lean on have to work as one unit, not as separate dashboards.

agent-eval scores and gates the output. It runs the deterministic checks, the model-as-judge rubrics, the drift and hallucination signals — and it returns a verdict on what the agent produced.

AgentLens captures the trace of how the agent got there. Every model call and tool step, the resolved inputs (after templating, not the raw template), and the raw outputs before any post-processing.

Neither half is sufficient alone, and that's the entire point. A bare eval score is a target waiting to be gamed. A bare trace is forensic data with no verdict attached. You need agent-eval's score anchored to AgentLens's trace so that every gate decision carries a "show me why" attached to it. When a borderline case flips, you don't argue about whether the eval is too strict — you open the trace, see the resolved prompt and the exact tool output, and find out whether the agent actually reasoned correctly or got lucky on a phrasing.

That linkage is what keeps the measure honest. The eval tells you the gate flipped; the trace tells you whether the flip was earned.

What it looks like in code

The anti-pattern is a gate that returns a boolean and nothing else:

// Goodhart bait: a verdict with no evidence behind it.
async function gate(testCase: TestCase): Promise<boolean> {
  const output = await runAgent(testCase.input);
  return judge(output, testCase.expected) >= 0.8; // green or red, no "why"
}

The fix is to make the score and the trace travel together, so a passing case is auditable, not just countable:

import { evaluate } from "agent-eval";
import { trace } from "agentlens";

interface GatedResult {
  passed: boolean;
  score: number;
  traceId: string;     // the receipt
  heldOut: boolean;    // was this case ever debugged against?
}

async function gatedRun(testCase: TestCase): Promise<GatedResult> {
  // AgentLens records every model + tool step, resolved inputs, raw outputs.
  const session = trace.start({ caseId: testCase.id });

  const output = await runAgent(testCase.input, { trace: session });

  // agent-eval scores the OUTPUT: deterministic checks + judge rubric + drift.
  const verdict = await evaluate(output, {
    expected: testCase.expected,
    checks: ["schema", "grounding", "drift"],
    judge: "rubric-v3",
  });

  await session.attach({ verdict }); // bind score <-> trace

  return {
    passed: verdict.score >= 0.8,
    score: verdict.score,
    traceId: session.id,         // open this to see WHY it passed
    heldOut: testCase.heldOut,   // overfit guard, see below
  };
}

Two things in that snippet are doing the anti-Goodhart work. The traceId means no pass is unexplainable — every green is one click from its own evidence. And heldOut is the discipline that keeps the suite from collapsing into a training set.

Three rules to keep the measure honest

Tooling won't save you from Goodhart on its own. The process around it has to hold the line:

Quarantine a held-out set you never debug against. If you've ever opened the trace for a case to fix a failure, that case is burned for measurement — it's now a regression test, not an evaluation. Keep a rotating set you only ever score, never tune toward. When held-out and debugged scores diverge, that gap is your overfit, measured directly.
Treat eval edits like production changes. Loosening an assertion to get green is a code change with a blast radius. It needs a diff, a reviewer, and a one-line justification anchored to a trace — "this case was wrong because the trace shows X," not "this was flaky."
Mine new cases from production traces, not your imagination. The cases you invent reflect failures you can already picture. The cases in your AgentLens traces reflect what users actually trigger. Promote real, surprising traces into the held-out set continuously, so the suite keeps measuring a moving target instead of a frozen one.

The uncomfortable conclusion

A green eval dashboard is not evidence that your agent is good. It is evidence that your agent satisfies your evals — and those are only the same thing while you're actively defending the gap between them.

The teams that ship reliable agents aren't the ones with the highest pass rates. They're the ones who can pull up any green checkmark and explain, from the trace, exactly why it earned the pass. agent-eval gives you the verdict; AgentLens gives you the receipt. Keep them bound together, keep a real held-out set, and your dashboard might actually keep meaning something six months from now.

Most won't. Now you know why.

Agent = Model x Harness: Your Eval Layer Is Part of the Agent, Not a Tool Beside It

Saurav Bhattacharya — Sat, 20 Jun 2026 22:49:09 +0000

There's a formula I keep coming back to when people ask why their slick demo agent falls apart in production:

Agent = Model × Harness

The model is the raw reasoning — Claude, GPT, whatever. It's swappable, and it's getting better on a curve you don't control. The harness is everything else: the goals, the loops, the tools, the scheduler, the retry logic. Most of the engineering that matters lives in the harness, not the model.

But here's the part most teams get wrong. They define the harness as the plumbing to run the model — goals + loops + tools — and then bolt evals and observability on the side as external QA. Things you point at the agent, after the fact, from outside.

That's the mistake. Your eval layer and your trace layer are inside the harness. They're not tools beside the agent; they're the half of the agent that makes it a closed loop instead of an open one.

Harness = goals + loops + tools + lens + evals. The first three let the agent act. The last two let it know whether the action was any good — which is the only thing that turns an agent that runs into an agent that improves.

Let me make that concrete, because I learned it the unglamorous way: by watching a scheduled agent crash and discovering exactly which parts of my harness saved me.

Open loop vs closed loop

An open-loop agent acts and moves on. It writes the file, hits the API, ships the commit — and nobody, including the agent itself, knows if the outcome was correct. You find out when a human notices something's broken. Most "autonomous" agents in the wild are open-loop. They're impressive right up until they silently do the wrong thing for three days.

A closed-loop agent has a feedback path:

act → observe → evaluate → correct → act better

The two pieces that close it are the lens (observability — every model call and tool step, resolved inputs, raw outputs, so a run is never a black box) and the evals (judgment — the output scored against a standard: deterministic checks, contract validation, model-as-judge). Lens tells you what the agent did; evals tell you whether it was good. You need both, wired into the harness itself — not run by hand once a week by a human who remembers to check.

The incident that taught me this

I run a fleet of scheduled agents — background workers on cron, each doing a focused job on a timer, each in an isolated session the main process can't watch live.

One of them crashed mid-run.

In an open-loop setup, that's a silent disaster: the worker dies, produces nothing, leaves no trace. You discover it days later when the output that should exist doesn't. (If you've run background agents, you know this exact pain — the ones that "go dark" for a week before anyone notices.)

Here's what happened instead, because the lens and eval layers were part of the harness:

1. The lens meant the failure left a record. Every worker writes its transcript stub-first: the moment it starts, before doing any real work, it writes a record with Outcome: IN-PROGRESS. So even a worker that dies one second later has left a footprint. The crash wasn't invisible — there was a transcript sitting there, frozen mid-run, saying "I started and never finished."

2. The evals meant the failure got caught — loudly, and repeatedly. Worker transcripts are validated against a versioned contract. A stub stuck at IN-PROGRESS is fine in normal mode (it might still be running), but under the "finished" check it becomes an error:

# Normal: an unfinished stub is acceptable
agent-eval validate transcripts/

# Finished mode: a lingering IN-PROGRESS is a hard error
agent-eval validate transcripts/ --finished

So the dead run didn't just leave a record — it got scored as invalid, and kept showing up in the gate's invalid list every single run until someone dealt with it. The eval layer refused to let the failure quietly blend into the background.

That's the whole point. The lens made the failure observable; the evals made it un-ignorable. Neither is something I went and ran by hand — they're standing parts of the harness that turned a crash from a black hole into a tracked defect.

Closing the correction step

Detecting the failure is observe + evaluate. The last piece is correct.

The naive fix is "add a finally block so the worker finalizes its own transcript on crash." That doesn't work, and the reason is instructive: a crashed isolated session is gone. The process that would run the finally is the thing that died. You can't ask a dead worker to clean up after itself.

So the correction step has to live outside the worker, as its own small loop. I wrote a sweeper: a scheduled janitor that scans for transcripts stuck at IN-PROGRESS whose run is provably over — older than a threshold set safely past the longest possible run time, so it can never race a worker that's still legitimately going — and finalizes them to fail.

The logic is deliberately boring:

for each transcript stub still marked IN-PROGRESS:
    if age > MAX_RUN_TIME + safety_margin:   # the run is provably dead
        rewrite Outcome -> "fail (auto-finalized: abandoned mid-run)"

Idempotent, never deletes anything, runs on a timer. The first time it ran it finalized a backlog of long-dead stubs and dropped the gate's invalid count in finished-mode to just the known, expected exceptions. Now it keeps the loop closed automatically: a worker can still crash, but its corpse gets cleaned up within the hour without me touching anything.

That's act → observe → evaluate → correct, fully wired — and three of those four steps are the lens + eval layers doing their job.

Self-correcting ≠ self-improving (and why that matters)

Here's where I have to be honest, because this is the part it's tempting to oversell.

What I built is a self-correcting harness. The loop closes: the system detects deviations from its own standard and repairs them without a human in the loop. That's real, and it's the floor you want under any fleet of autonomous agents.

But self-correcting is not self-improving. Self-correcting means the system holds the line — it keeps itself at the standard. Self-improving would mean the system moves the line up on its own: noticing a check has false positives and tightening its own rubric, noticing a worker keeps regressing and adjusting that worker's instructions. My harness doesn't do that. I still author every improvement. The loops run themselves; the loops were designed by a human.

And honestly — that's the right place to stop, for now. A harness that rewrites its own workers and its own eval criteria unsupervised is a different and much riskier thing, precisely because the evals would be grading work the same system authored. The moment the thing being judged and the thing doing the judging are the same closed system with no external anchor, "it passes its own evals" stops meaning very much. Self-correction within a human-set contract is the sound version. Self-modification of the contract itself is where you want hard guardrails and a human gate before you flip it on.

So the honest formula, fully expanded:

Agent = Model × Harness, where Harness = goals + loops + tools + lens + evals — and it's the lens + evals that make the agent self-correcting. Getting from there to self-improving is a real step further, and it's one you should take deliberately, with a human holding the gate.

The takeaway

If you're building agents and your evals and traces are something you run occasionally, from outside, you don't have a closed loop — you have an open-loop agent with some QA scripts nearby. The upgrade isn't more tooling. It's a reframe:

Lens and evals belong inside the harness, running on every action, not on demand.
The lens makes failures observable; the evals make them un-ignorable — that's what converts a crash from an invisible black hole into a tracked defect.
Closing the correction step often means a separate loop, because the thing that failed can't always clean up after itself.
Self-correcting is the floor; self-improving is a further, deliberate step — keep a human on the gate before the system grades its own homework.

Agent = Model × Harness. The model is improving on its own. Whether your agent improves is a question about your harness — and specifically about whether you've wired the loop closed.

The two layers in this post map to two tools I use as a single unit. **agent-eval* is the eval framework — it scores and gates an agent's output (contract validation, drift, hallucination, staleness); the validate --finished check in the incident above is its work. AgentLens is the trace layer — it captures how the agent got there (every model and tool step, resolved inputs, raw outputs) so the eval signal is actually debuggable. agent-eval tells you something broke; AgentLens tells you why. They ship together on purpose: two halves of one feedback loop — which is exactly the argument of this post.*

Your Agent Didn't Break, It Drifted: Detecting Slow Decay in Autonomous Systems

Saurav Bhattacharya — Sat, 20 Jun 2026 01:06:33 +0000

There is a specific kind of incident that no alert ever fires for, and it is the one I trust least. Nothing crashed. No exception, no 500, no failed health check. The agent ran every day, returned answers every time, and stayed green on every dashboard you own. And yet, over six weeks, it got measurably worse — and you found out from a customer, not a monitor.

That is drift, and it is the failure mode I think the industry is least prepared for. We have gotten good at catching the cliff: the agent throws, the tool 500s, the JSON won't parse, CI goes red. We are still terrible at catching the slope: answer quality bleeding out two percent a week while every system reports perfect health. Crashes are loud and self-announcing. Drift is silent by construction, and that silence is exactly why it wins.

Here is the opinion I will defend: drift is not an outlier problem, it's a baseline problem. You cannot detect decay by looking at any single run, because a single run looks completely fine. Drift only exists as a change in a distribution over time — so if you are not continuously scoring production and trending the score, you are structurally incapable of seeing it. Not unlucky. Incapable.

Why your code didn't change but your behavior did

The thing that makes drift so disorienting is that it violates our deepest instinct: if the code didn't change, the behavior didn't change. For agents, that is just wrong. Your agent decays while your git history sits perfectly still:

The model moves under you. You pinned gpt-4o, but a pinned model name is not a pinned model — providers roll checkpoints and quietly re-tune behind a stable string. Your prompt is byte-for-byte identical and your outputs shifted anyway.
The world moves under your prompt. Your few-shot examples were written against March's reality. It is now September. Users ask about products and edge cases that did not exist when you froze the prompt, and the agent improvises — worse, but fluently.
Your dependencies and inputs move. A retrieval index gets re-embedded; a tool renames a field; your user base grows into a new locale. The agent was never broken for the inputs you tested — it's that the data and traffic it actually serves have drifted away from them, and it keeps running while confidently citing slightly-wrong results.

Not one of these shows up in a code diff. Not one throws. Every one degrades what your users actually experience. This is why "we'll notice if it breaks" is a fantasy — the most expensive agent regressions don't break anything.

A baseline is the only thing drift is measured against

To detect drift you need two things: a baseline — what "normal" scored like over a trusted window — and a continuous signal, the same score computed the same way on live traffic. Drift is the gap between them, measured statistically, not by eyeball.

The naive version is a single threshold: "alert if quality drops below 0.8." That catches the cliff and misses the slope. A score that walks from 0.91 to 0.82 over five weeks never trips an absolute floor, yet it has lost nearly a tenth of its quality. You are not looking for low; you are looking for moving — a different statistical question, and it needs the baseline.

This is where evaluation and observability stop being separate concerns and become one workflow — because you need both a thing that scores and a thing that remembers the route. I run agent-eval to score and gate the agent's output: deterministic checks where it can, a model-as-judge rubric where it must, and crucially it persists each verdict so a series of scores exists to trend at all. And I run AgentLens to capture the trace behind every scored run — every model and tool step, the resolved inputs the model actually saw after interpolation, the raw outputs that came back. The pairing is the whole point: agent-eval tells you the score is drifting; AgentLens tells you which step started drifting. A drift alert with no trace behind it is just a number falling on a chart with no way to ask why — and "quality is down 6% this month, cause unknown" isn't an actionable signal, it's an anxiety generator.

Here is a drift detector over a rolling window of scored production runs. The scores come from agent-eval; each run's traceId points back into AgentLens so a flagged window is one click from the evidence:

import { queryScoredRuns } from "agent-eval";

interface ScoredRun {
  runId: string;
  traceId: string;   // -> AgentLens: the full route that produced this score
  score: number;     // agent-eval rubric verdict, 0..1
  at: number;        // epoch ms
}

interface DriftReport {
  drifting: boolean;
  baselineMean: number;
  recentMean: number;
  deltaPct: number;       // how far recent has moved from baseline
  zScore: number;         // is the move bigger than normal run-to-run noise?
  sampleTraceIds: string[]; // worst recent runs, for AgentLens drill-in
}

function mean(xs: number[]): number {
  return xs.reduce((a, b) => a + b, 0) / xs.length;
}

function stdev(xs: number[], mu: number): number {
  return Math.sqrt(mean(xs.map((x) => (x - mu) ** 2)));
}

// Compare a recent window against a trusted baseline window.
// Drift = the recent mean has moved further than baseline NOISE explains.
function detectDrift(baseline: ScoredRun[], recent: ScoredRun[]): DriftReport {
  const baseScores = baseline.map((r) => r.score);
  const recentScores = recent.map((r) => r.score);

  const baselineMean = mean(baseScores);
  const recentMean = mean(recentScores);
  const baselineSd = stdev(baseScores, baselineMean) || 1e-9;

  // Standard error of the recent window's mean, scaled by baseline noise.
  // This asks: is this gap real, or just the sample size talking?
  const se = baselineSd / Math.sqrt(recentScores.length);
  const zScore = (recentMean - baselineMean) / se;

  const deltaPct = ((recentMean - baselineMean) / baselineMean) * 100;

  // Flag when quality dropped AND the drop is statistically meaningful.
  // z < -3 ~ a one-sided drop well outside normal run-to-run wobble.
  const drifting = zScore < -3 && deltaPct < -2;

  const sampleTraceIds = [...recent]
    .sort((a, b) => a.score - b.score)
    .slice(0, 5)
    .map((r) => r.traceId);

  return { drifting, baselineMean, recentMean, deltaPct, zScore, sampleTraceIds };
}

// Roll the windows forward continuously, not on deploy.
async function checkProductionDrift(): Promise<DriftReport> {
  const baseline = await queryScoredRuns({ from: "-30d", to: "-7d" });
  const recent = await queryScoredRuns({ from: "-7d", to: "now" });
  return detectDrift(baseline, recent);
}

Two design decisions carry the whole approach.

It compares against baseline noise, not an absolute floor. The zScore is the entire trick. Every agent's scores wobble run-to-run — that is normal nondeterminism, not decay. By dividing the drop by the standard error of the recent window, you only fire when the move is bigger than the agent's own natural jitter. A 1% dip on a noisy agent is nothing; the same dip on a rock-steady one is a five-alarm signal. An absolute threshold cannot tell those apart.

It emits sampleTraceIds, not just a verdict. A boolean drifting: true is where most homegrown detectors stop, and it's why they get ignored — nobody can act on it. By attaching the five worst recent runs' trace IDs, the alert carries its own evidence: you open those AgentLens traces and read the resolved inputs and tool outputs that produced the low scores. That is the difference between "quality is down, somebody investigate" and "quality is down, and here is the retrieval step that started returning stale documents."

Segment your baseline or it will lie to you

One trap worth calling out, because it produces the most confusing drift incidents: a healthy aggregate can hide a brutal per-segment collapse. Your overall score holds at 0.90 while your Spanish-language traffic quietly craters from 0.88 to 0.61 — masked because it's only 8% of volume and the other 92% is fine. The aggregate is technically accurate and completely useless.

So slice the baseline along the dimensions that actually vary — language, tool path, user tier, intent — and run the same drift check per slice.

async function driftBySegment(segmentBy: (r: ScoredRun) => string) {
  const baseline = await queryScoredRuns({ from: "-30d", to: "-7d" });
  const recent = await queryScoredRuns({ from: "-7d", to: "now" });

  const group = (runs: ScoredRun[]) => {
    const m = new Map<string, ScoredRun[]>();
    for (const r of runs) (m.get(segmentBy(r)) ?? m.set(segmentBy(r), []).get(segmentBy(r))!).push(r);
    return m;
  };

  const baseGroups = group(baseline);
  const recentGroups = group(recent);

  for (const [seg, recentRuns] of recentGroups) {
    const baseRuns = baseGroups.get(seg);
    if (!baseRuns || recentRuns.length < 20) continue; // need signal to call it
    const report = detectDrift(baseRuns, recentRuns);
    if (report.drifting) {
      console.warn(
        `DRIFT [${seg}] ${report.baselineMean.toFixed(3)} -> ` +
        `${report.recentMean.toFixed(3)} (${report.deltaPct.toFixed(1)}%) ` +
        `traces: ${report.sampleTraceIds.join(", ")}`,
      );
    }
  }
}

The most dangerous drift hides inside an average. Segmenting the baseline drags it into the light, and the per-segment trace IDs tell you, via AgentLens, exactly which step does badly on those inputs.

What to do Monday

You don't need a statistics PhD or a platform team to start — you need a baseline and a trend:

Score production continuously, not just on deploy. Sample real traffic, run it through your agent-eval rubric, and persist every verdict with its AgentLens trace ID. Without a series of scores there is no trend, and without a trend there is no drift detection — just hope.
Trend against a baseline window, and compare to noise, not a floor. Alert on statistically significant movement. You are hunting the slope, not the cliff.
Segment the baseline — per-language, per-tool, per-tier — to find the collapse before the aggregate smothers it.
Make every drift alert carry trace IDs. A signal you can't drill into is one your team learns to ignore. The score names the symptom; the trace names the cause.

The agents are not going to crash on their way down. They will keep answering, keep returning 200s, keep looking healthy, and get quietly worse until the decay is large enough for a human to notice — the most expensive possible detector. Score the output with agent-eval, keep the route with AgentLens, trend the two against a baseline, and you catch the slope while it's still two percent instead of explaining the cliff to a customer who found it first.

Hallucination Is Not a Vibe: How to Actually Detect Ungrounded Claims in Agent Output

Saurav Bhattacharya — Fri, 19 Jun 2026 01:02:41 +0000

Every team I talk to says their agent "sometimes hallucinates," and almost none of them can tell me how often. That gap — between knowing it happens and being able to count it — is the whole problem. You cannot fix, gate, or even trend a failure mode you only detect by feel.

Here is the opinion I will defend: hallucination detection is not a model-quality problem, it's an instrumentation problem. The reason you can't measure it is that you threw away the evidence the moment the agent finished running. Detecting an ungrounded claim requires knowing what the agent was allowed to claim, and that lives in the tool outputs and retrieved context, not in the final answer string. If you don't capture those, every hallucination check you write is guessing.

Let me break down what hallucination actually is in an agentic system, why the popular detection methods miss the common case, and how to wire up a number you can put in CI.

"Hallucination" is three different bugs wearing one coat

The word is overloaded, and the overloading is why detection efforts flail. In a tool-using agent, there are at least three distinct failures people lump together:

Parametric leakage. The agent answers from training-data memory instead of the tool result it was given. The answer might even be correct — but it's correct by luck, not because it used the data you grounded it on. Tomorrow the same code path produces a confidently wrong answer and you have no idea why.
Fabricated grounding. The agent cites a source, a record ID, a field, or a number that does not appear anywhere in its retrieved context. This is the dangerous one because it looks grounded. It has the shape of a sourced claim.
Unsupported synthesis. Every individual fact is present in the context, but the agent combined them into a conclusion the source never makes. No single token is fabricated; the inference is.

These need different detectors. Lumping them under one "hallucination score" gives you a number nobody trusts, because it conflates a lucky-but-ungrounded answer with an invented customer ID. The first move toward measuring hallucination is refusing to treat it as one metric.

Why "ask the model if it hallucinated" is the weakest option

The most common detection approach is to hand the output back to an LLM and ask "is this faithful to the context?" It's appealing because it's one API call. It's also the method most likely to wave through the exact failures you care about.

The self-consistency variant — sample the answer five times, flag disagreement — catches unstable hallucinations but misses stable ones. If the agent reliably leaks the same wrong fact from parametric memory every time, all five samples agree and your detector reports high confidence. The model is reproducibly wrong, and consistency was your signal. That's not a corner case; it's the most common production hallucination there is.

Model-as-judge faithfulness scoring is genuinely useful — but only for unsupported synthesis, the fuzzy case where you actually need judgment. For the other two, you don't need an LLM at all. You need set membership. And a deterministic check that you can fully explain beats a 0.7-from-a-judge that you can't, every time.

Grounding is checkable when you keep the grounding

Here's the core technique, and it's almost embarrassingly mechanical: extract the verifiable claims from the output, and check each one against the actual text the agent retrieved. The catch — the entire reason this is hard in practice — is that "the actual text the agent retrieved" has usually evaporated by the time you want to check.

This is exactly why I treat tracing and evaluation as one workflow rather than two tools. AgentLens captures the execution trace: every tool call with its raw output, the resolved context that actually went into the model, the final answer — the full ground-truth record of what the agent had access to. agent-eval is the other half: it takes that trace plus the output and runs the grounding checks, returning a pass/fail verdict you can gate a build on. The pairing is the point. agent-eval can only check a claim against the source if AgentLens kept the source. A faithfulness scorer with no trace behind it is reduced to asking a model to vibe-check itself — which is where we came in.

Here's what a layered detector looks like over a captured trace:

import { getTrace } from "agentlens";
import { defineScorer } from "agent-eval";

// Pull the agent's actual evidence out of the trace: every tool result
// and the resolved retrieval context the model was actually shown.
function collectGrounding(trace: Awaited<ReturnType<typeof getTrace>>): string {
  return trace.steps
    .filter((s) => s.kind === "tool" || s.kind === "retrieval")
    .map((s) => JSON.stringify(s.output))
    .join("\n");
}

// Detector 1 (deterministic): fabricated grounding.
// Any structured reference the agent emits MUST appear in the evidence.
// Catches invented record IDs, citation keys, dollar amounts.
const noFabricatedRefs = defineScorer({
  name: "no_fabricated_refs",
  async score({ output, runId }) {
    const evidence = collectGrounding(await getTrace(runId));

    // Reference shapes this agent is allowed to cite.
    const patterns = [/CUST-\d{5}/g, /DOC-[a-f0-9]{8}/g, /\$[\d,]+\.\d{2}/g];
    const claimed = patterns.flatMap((p) => [...output.matchAll(p)].map((m) => m[0]));

    const fabricated = claimed.filter((ref) => !evidence.includes(ref));
    return {
      pass: fabricated.length === 0,
      value: fabricated.length,
      detail: fabricated.length ? `ungrounded: ${fabricated.join(", ")}` : "ok",
    };
  },
});

// Detector 2 (judge): unsupported synthesis.
// The fuzzy case — every fact is present but the CONCLUSION isn't supported.
// This is the only layer that needs a model, and it needs the real evidence.
const faithfulSynthesis = defineScorer({
  name: "faithful_synthesis",
  async score({ output, runId }) {
    const evidence = collectGrounding(await getTrace(runId));
    const verdict = await judge({
      system: "Return supported=false if any claim is not entailed by EVIDENCE. " +
              "Correct-but-absent-from-evidence counts as NOT supported.",
      evidence,
      claim: output,
    });
    return { pass: verdict.supported, value: verdict.confidence, detail: verdict.reason };
  },
});

Two design decisions in there carry the whole thing, and I'll defend both.

The deterministic detector runs first and is the one I trust most. Fabricated reference IDs and invented dollar amounts are not a matter of judgment — a claimed ID either appears in the tool output or it doesn't. That's a String.includes, not a 9.1-from-a-judge. It never flakes, costs nothing, and when it fails it hands you the exact ungrounded token. Most of your scary, customer-visible hallucinations are this category, and they're catchable without an LLM in the loop.

The judge instruction explicitly defines correct-but-ungrounded as a failure. This is the line that catches parametric leakage. A naive faithfulness prompt rewards correct answers, so a lucky memory-leak passes. By forcing "absent from evidence = not supported," you separate grounded from merely right — which is the distinction that actually predicts whether the agent will be wrong tomorrow when its luck runs out.

A hallucination rate is a trend, not a verdict

One run telling you "this output was grounded" is nearly worthless, because hallucination is a property of the distribution, not of a single answer. The number that matters is the rate — what fraction of production runs emit an ungrounded claim — and its slope over time.

This is where keeping the trace pays off a second time. Because every AgentLens trace carries the evidence inline, you can re-run these detectors across a window of historical production traffic without re-invoking the agent, and watch the rate move:

import { queryTraces } from "agentlens";
import { runScorers } from "agent-eval";

async function hallucinationRate(sinceHours: number): Promise<number> {
  const traces = await queryTraces({ sinceHours, hasOutput: true });
  const reports = await Promise.all(
    traces.map((t) => runScorers([noFabricatedRefs, faithfulSynthesis], { runId: t.id })),
  );
  const flagged = reports.filter((r) => !r.passed).length;
  return flagged / reports.length; // e.g. 0.031 == 3.1% of runs ungrounded
}

Now "the agent sometimes hallucinates" becomes "3.1% of runs last week emitted an ungrounded claim, up from 1.8% — here are the trace IDs." That's a number you can put on a dashboard, gate a release on, and hand to a skeptic. The eval gives you the rate; the trace behind each flagged run gives you the specific tool output the claim should have come from and didn't. You stop arguing about whether hallucination is a problem and start clicking into the step where it happened.

The takeaway

Stop treating hallucination as an inherent, unmeasurable property of language models and start treating it as a grounding check you forgot to instrument. Split it into its three real failure modes. Catch fabricated references and parametric leakage with deterministic set-membership checks — no judge required. Reserve model-as-judge for the genuinely fuzzy synthesis case. And capture the trace, because every one of these checks is impossible without the evidence the agent actually saw.

The agents hallucinate at a specific, knowable rate. The only reason you don't know yours is that you let the evidence disappear. Capture the path with AgentLens, score the grounding with agent-eval, and the vibe becomes a number — which is the only form of the problem you can actually fix.

Your Agent Passed Every Eval and Still Cost $4,000 a Day

Saurav Bhattacharya — Thu, 18 Jun 2026 01:01:48 +0000

Here is a failure mode nobody puts on their roadmap: the agent works. It answers correctly. It passes your golden set. Your model-as-judge gives it a 9.2. Your hallucination checks are green. And then finance forwards you the inference bill and asks, politely, what exactly you have been doing for the last three weeks.

Most eval suites measure one axis: was the output correct? That is the axis everyone copies from the demos and the leaderboards. But "correct" is necessary, not sufficient. A production agent has at least three more dimensions that determine whether it survives contact with reality — cost, latency, and tool-call efficiency — and almost nobody scores them. So they regress silently, release after release, until they become an incident instead of a number on a dashboard.

I want to make the case that operational metrics are evals, not monitoring afterthoughts, and show how to wire them in.

"Correct" is the cheapest thing to measure and the least complete

Think about what actually changes between two versions of an agent. You tweak a system prompt. You add a "think step by step" nudge. You bump the model. You add a retrieval step "just to be safe." Every one of those changes can leave correctness flat while quietly doubling token usage or adding three seconds of latency or sending the agent into a 14-step tool-calling spiral to answer a question that used to take two.

Your correctness eval will not catch any of that. It is, by design, blind to how the answer was produced. It only looks at the final string. Which means the most expensive regressions in agentic systems are exactly the ones a naive eval suite is structurally incapable of seeing.

The fix is not more correctness tests. It is treating the trace — the full record of how the agent reached its answer — as a first-class eval target.

The two halves: scoring the output vs. capturing the path

This is where two tools that ship as a unit earn their keep, and you need both because they measure different things.

agent-eval scores and gates the agent's output. It runs your assertions — deterministic checks, model-as-judge, drift, hallucination — and, critically, it can assert on operational metrics too. It is the thing that fails the build when a number crosses a line.

AgentLens captures the trace: every model call and tool step, the resolved inputs that actually went over the wire, the raw outputs that came back, token counts, and wall-clock timings per step. Without that trace, an operational eval signal is undebuggable — you'd know cost went up 40% but have zero idea which step did it. agent-eval tells you the bill doubled; AgentLens tells you it was the retrieval step firing three times because of a bad cache key.

You score the output. You capture the path. The path is what makes the score actionable instead of just alarming. One without the other is half a workflow.

What an operational eval actually looks like

Let's make it concrete. AgentLens gives you a structured trace per run; agent-eval lets you assert against it. Here's the shape:

import { defineEval, runEval } from "agent-eval";
import { getTrace } from "agentlens";

// A "case" is one task we want the agent to handle.
const eval = defineEval({
  name: "refund-lookup",
  cases: [
    { input: "Where is my refund for order 88231?", expectResolved: true },
  ],

  // Correctness — necessary, but not the whole story.
  scorers: [
    async ({ output, expected }) => ({
      name: "resolves_refund",
      pass: output.includes("refund") && expected.expectResolved,
    }),

    // Operational scorers, pulled straight from the captured trace.
    async ({ runId }) => {
      const trace = await getTrace(runId);

      const totalTokens = trace.steps.reduce((n, s) => n + s.tokens, 0);
      const toolCalls   = trace.steps.filter(s => s.type === "tool").length;
      const latencyMs   = trace.endedAt - trace.startedAt;

      return [
        { name: "token_budget", pass: totalTokens <= 6000, value: totalTokens },
        { name: "tool_calls",   pass: toolCalls   <= 4,    value: toolCalls   },
        { name: "latency_p95",  pass: latencyMs   <= 8000, value: latencyMs   },
      ];
    },
  ],
});

const report = await runEval(eval);
if (!report.passed) {
  // Same gate as a failing correctness test. No special-casing.
  process.exit(1);
}

Three things make this work, and they are all opinions I will defend.

1. The budgets live next to the correctness assertions. Not in a Grafana panel someone glances at on Fridays. In the same file, enforced by the same process.exit(1). A 5x token regression should fail the build with the same authority as a wrong answer, because operationally it is just as much a defect.

2. The numbers come from the trace, not from re-instrumentation. You are not sprinkling console.time through your agent. AgentLens already recorded every step's tokens and timing as a side effect of running. agent-eval just reads it back. If your operational metrics require a separate instrumentation pass, you will skip it, and you know you will.

3. You assert on value, not just pass. Store the number. Because the day a budget fails, your very next question is "by how much, and since when?" — and that is a trend, not a boolean.

Catching the slow bleed

The dangerous regressions are rarely a cliff. They are a slow bleed: 4,100 tokens, then 4,400, then 4,900, each one under budget, until one day it isn't and you have no idea which of the last forty PRs did it.

Because agent-eval persists the trace-derived values per run, you diff them:

import { compareRuns } from "agent-eval";

const diff = await compareRuns({ base: "main", head: "PR-512" });

for (const m of diff.metrics) {
  if (m.delta > m.value * 0.15) {
    console.warn(
      `⚠ ${m.case}/${m.name}: ${m.baseValue} → ${m.headValue} ` +
      `(+${Math.round((m.delta / m.baseValue) * 100)}%) — see trace ${m.headRunId}`
    );
  }
}

A 15% jump in tokens on a PR is a conversation, even if every absolute budget still passes. And because the warning carries the AgentLens headRunId, the reviewer is one click from the exact step that moved. The eval says that it regressed; the trace says why. You don't argue about it in the PR thread — you open the trace.

The uncomfortable part

Adopting this means admitting your agent has a cost and latency profile that is a product surface, not an implementation detail. The "just add another tool call to be safe" reflex is exactly how a $400/day agent becomes a $4,000/day agent, one defensible little change at a time. None of those changes is wrong in isolation. Their sum is the incident.

So put a number on it. Score the output with agent-eval, capture the path with AgentLens, and let the two together fail your build when the agent gets correct but expensive. Correctness keeps you honest with your users. Operational evals keep you honest with everyone who has to run the thing in production — which, eventually, is you.

The agent that passes every correctness eval and still bankrupts the feature is not a hypothetical. It is the default outcome of measuring only the half of the system that is easy to measure.

Your Eval Suite Is Grading Fiction: Stop Inventing Test Cases and Mine Your Traces

Saurav Bhattacharya — Wed, 17 Jun 2026 01:02:29 +0000

Your eval suite is only as good as the cases in it, and almost nobody talks about where those cases come from. We argue endlessly about deterministic checks versus model-as-judge, about CI gates and drift thresholds — and then we feed all of that machinery a dataset of twelve examples someone made up in an afternoon. The scoring is rigorous. The corpus is fiction.

Here is the opinion I will defend: the hardest part of agent evaluation is not the scorer, it's the dataset. A perfect judge over an unrepresentative set of inputs gives you a confident green checkmark that means nothing. You can have flawless assertions and still ship a broken agent, because your eval set never contained the input that breaks it. The corpus is the test. Everything else is plumbing.

Why hand-written eval cases rot

When teams build their first eval set, they sit down and imagine inputs. "A user asks to summarize a ticket." "A user asks for a refund." These cases share a fatal property: they are what the engineer imagined a user would do, written by the same person who wrote the prompt. They encode the happy path twice — once in the agent, once in the test — and then congratulate each other for agreeing.

Real users do not behave like your imagination. They paste 8,000 tokens of Slack history into a one-line field. They ask three questions at once. They use your product for something you never designed. They write in the second language they're least comfortable in. None of that is in your hand-authored set, which means none of it is gated, which means every one of those inputs is a live grenade in production that your "comprehensive eval suite" has never seen.

Synthetic data generation — "ask GPT to write me 100 test queries" — feels like a fix and isn't. The model generates from the same distribution your prompt already handles well. You get 100 variations of the easy case and zero of the weird ones, because the weird ones are weird precisely because no model would think to generate them. Synthetic sets inflate your case count and your confidence without touching your actual risk.

The source of truth is your production traces

The only honest source of eval cases is the distribution you actually serve: production traffic. Your users are running a continuous, adversarial, free fuzzing campaign against your agent every single day. The job is to capture that, find the inputs that matter, and promote them into permanent regression cases.

This is exactly why I treat tracing and evaluation as one workflow instead of two products. AgentLens captures the full execution trace of every production run — the resolved input the model actually saw after template interpolation, every tool call with its arguments, the raw outputs, the final answer. That trace store is not just a debugging tool; it is the raw material your eval set is mined from. agent-eval is the other half: it takes a case, runs the deterministic checks and the model-as-judge rubric, and returns a pass/fail verdict you can gate on. The pairing matters because AgentLens decides which cases are worth testing, and agent-eval decides whether the agent passes them. A scorer with no pipeline from production is a scorer grading fiction; a trace store you never promote into evals is an archive nobody reads.

The loop looks like this: a production run gets a bad outcome (a thumbs-down, a support escalation, a failed downstream action). That trace is the most valuable test case you will ever have, because it is a real failure that really happened. You capture its resolved input, attach the corrected expected behavior, and it becomes a permanent case. Now that exact failure can never silently regress again.

Here is the harness that turns a flagged trace into a frozen regression case:

import { getTrace } from "agentlens";
import { evaluate, assert } from "agent-eval";
import { writeFileSync, readFileSync } from "node:fs";

interface GoldenCase {
  id: string;
  sourceTraceId: string;     // provenance: which real run this came from
  input: unknown;            // the RESOLVED input, exactly as the model saw it
  policy: string;            // the judge rubric this case must satisfy
  mustContain?: string[];    // deterministic anchors from the corrected answer
  mustNotContain?: string[]; // things the bad run did that we now forbid
}

// Promote a flagged production trace into a permanent eval case.
async function promoteTrace(traceId: string, policy: string): Promise<GoldenCase> {
  const trace = await getTrace(traceId);

  // Critical: freeze the RESOLVED input, not the template. The whole reason
  // this run failed may live in the interpolated context, not your prompt.
  const resolvedInput = trace.steps.find((s) => s.kind === "model")?.input;
  if (!resolvedInput) throw new Error(`no model step in trace ${traceId}`);

  const golden: GoldenCase = {
    id: `case_${traceId.slice(0, 8)}`,
    sourceTraceId: traceId,
    input: resolvedInput,
    policy,
  };

  const set: GoldenCase[] = JSON.parse(readFileSync("./goldens.json", "utf8"));
  set.push(golden);
  writeFileSync("./goldens.json", JSON.stringify(set, null, 2));
  return golden;
}

// Run the curated set. Every case here is a real failure we refuse to repeat.
async function runRegressionSet(): Promise<void> {
  const set: GoldenCase[] = JSON.parse(readFileSync("./goldens.json", "utf8"));

  const results = await Promise.all(
    set.map(async (g) => {
      const output = await runAgent(g.input);
      const report = await evaluate({
        input: g.input,
        output,
        checks: [
          assert.contains(g.mustContain ?? []),
          assert.notContains(g.mustNotContain ?? []),
          assert.judge({ criterion: g.policy, threshold: 0.7 }),
        ],
      });
      return { id: g.id, source: g.sourceTraceId, ...report };
    }),
  );

  const failed = results.filter((r) => !r.passed);
  for (const f of failed) {
    // Provenance pays off: jump straight back to the original incident.
    console.error(`FAIL ${f.id}  (regressed from trace ${f.source})`);
  }
  if (failed.length > 0) process.exit(1);
}

The detail that earns its keep is sourceTraceId. Every case carries a pointer back to the real run it came from. When a case fails six months later, you are not staring at a synthetic input wondering what it was supposed to prove — you open the original AgentLens trace and see the actual incident that motivated it. Your eval set becomes a museum of every real bug you've ever fixed, and the gate's job is to make sure none of them come back.

Curation is a discipline, not a one-time export

Mining traces is not "dump everything into the eval set." A set of 50,000 cases that takes four hours to run is a set nobody runs. Curation means actively managing the corpus:

Stratify by outcome. Deliberately oversample failures and edge inputs. A set that mirrors production exactly is 95% easy cases and tells you almost nothing per dollar of judge spend. You want the hard tail over-represented.
Deduplicate by behavior, not by string. Ten traces that all trip the same tool-selection bug are one case, not ten. Cluster on the failure mode and keep the clearest representative.
Expire cases that no longer test anything. When a capability is rock-solid for months, demote those cases to a nightly suite and keep the per-commit gate lean and fast.
Track coverage as a real metric. Which user intents, which tools, which input shapes have zero eval cases? Those gaps are exactly where your next production incident is hiding.

The takeaway

Stop pouring engineering effort into a more sophisticated scorer on top of a dataset you invented. The leverage is in the corpus. Build the pipeline that turns real production failures — captured as AgentLens traces — into permanent agent-eval cases, and your suite stops being a record of what you imagined could go wrong and becomes a record of what actually did. That is the only eval set that gets stronger every week instead of staler.

Your users are writing your test cases for you, every day, for free. The only question is whether you're capturing them — or letting them expire into a log file you'll never query.