Why Code Diffs Are Not Enough for AI Agent Changes

AgentInspect, an open-source TypeScript toolkit for inspecting agent runs, introduces a run-diff workflow that compares execution traces to source diffs. The toolkit's CLI can identify behavioral changes such as added or removed steps, duration shifts, and first divergence points, providing a more accurate risk assessment for AI agent modifications.

A pull request changes three lines in a prompt. The source diff is tiny. The resulting agent run adds a tool call, skips a planning step, changes its recovery path, and takes twice as long. Which diff describes the risk more accurately? Both do—but they describe different things. I maintain AgentInspect https://github.com/rajudandigam/agent-inspect , an open-source TypeScript toolkit for inspecting agent runs locally. I designed its run-diff workflow around a simple idea: code review tells us what the developer changed; execution evidence tells us what the agent did differently. The examples below use synthetic fixtures verified against agent-inspect@6.17.4 https://github.com/rajudandigam/agent-inspect/tree/agent-inspect%406.17.4 . In ordinary deterministic code, a source diff is often a strong predictor of runtime change. Agent systems add several moving parts: A large refactor can preserve the same trajectory. A one-word prompt change can alter tool selection. Identical code can behave differently when a model or external result changes. That does not make code review obsolete. It means the review unit needs another layer: source diff behavior diff ----------- ------------- what was edited? what path changed? what code owns the change? where did runs diverge? is the implementation sound? which steps/errors/outputs differ? A useful behavioral comparison needs a deliberate baseline and candidate: baseline same synthetic input pinned or recorded configuration known-good trace candidate same synthetic input intended code/prompt/model change newly captured trace Control what you can. Record what you cannot. If the input, retrieval corpus, model, and tool fixtures all change at once, the diff may be accurate but difficult to interpret. With two local run IDs, compare them from the CLI: npx agent-inspect diff minimal-success minimal-error \ --dir .agent-inspect The synthetic fixture output begins with the summary and first divergence: Run diff Left: minimal-success Right: minimal-error Summary: Differences: 4 Errors: 0 Warnings: 3 Info: 1 First divergence: run-status at run left: success right: error That “first divergence” is often more actionable than a long list of event differences. It gives the reviewer a starting point for the causal investigation. The same fixture reports: Differences: warning run-status Run completion status differs left: success right: error info duration Run duration differs left: 120 right: 70 warning step-removed plan Step only in left run: plan left: step root right: undefined warning step-added failing-step Step only in right run: failing-step left: undefined right: step fail The evidence says that plan appears only in the left run and failing-step only in the right. It does not automatically say why. Possible explanations include: This is why a behavioral diff is an input to review, not an automatic verdict. Pair it with the source diff and inspect the execution tree around the divergence. The CLI can limit the comparison to a specific check dimension. To inspect only structure: npx agent-inspect diff minimal-success minimal-error \ --dir .agent-inspect \ --check structure That removes status and duration noise and leaves the added/removed steps. For a performance-oriented review: npx agent-inspect diff minimal-success minimal-error \ --dir .agent-inspect \ --check timing \ --duration-threshold 20ms The command also supports JSON output for automation, --ignore-duration , focus modes, and verbose output. A practical rule is to begin with the broad human-readable diff, then narrow the view when you know which hypothesis you are testing. The fixture reports 120 versus 70 milliseconds. It would be a mistake to generalize that single synthetic delta into a performance claim. Agent latency can vary with network conditions, cache state, provider load, token volume, and concurrency. A timing diff is most useful when: Use --duration-threshold to suppress insignificant changes, but derive the threshold from your environment. Do not choose a number merely because it makes a current test pass. AgentInspect’s diff is a read-only comparison of persisted traces. It does not replay either agent, invoke a model, or prove that the difference will recur. That property is useful for review: the comparison is deterministic for the two stored artifacts. It is also a limitation: representative capture remains your responsibility. I think of the workflow as three separate actions: php execute - capture evidence compare - describe observed differences judge - decide whether the change is acceptable Only the middle action is the run-diff engine. For changes that can materially affect an agent path, a compact pull-request section can make review faster: Agent behavior evidence - Fixture: refund-eligible-order - Baseline run: refund-before - Candidate run: refund-after - Expected change: prefer cached policy when current - First divergence: retrieve-policy replaced by load-policy-cache - Contract result: pass - Evidence artifact: attached CI bundle - Reviewer note: no production or customer data used This is intentionally concise. The full trace should remain an artifact, not be pasted into the pull-request description. The most important field is “expected change.” It tells reviewers whether an observed divergence is intentional. Without that statement, the diff is merely a list of facts. A diff answers “What changed?” A contract answers “Did a declared invariant still hold?” Use both. Suppose a candidate run replaces remote retrieval with a cache hit. The structural diff should show the path change. A contract might still require: The candidate can therefore differ from the baseline and still pass the invariant gate. This is healthier than either extreme: Choose fixtures around decisions, not around random traffic. High-value comparisons include: Did tool selection, ordering, retry behavior, or token usage change? Does the new model reach the same goal with a different trajectory? Does it invoke a fallback more often in controlled cases? Did a renamed or re-described tool disappear, get replaced, or start failing? Did parent-child structure, concurrency, or error propagation change even if final answers stayed stable? Did the run add or skip retrieval, or generate before the required evidence step? For each case, pair the behavioral observation with a domain-specific quality check. A shorter path is not necessarily a better answer. Code diffs remain the foundation of software review. Agent systems need an additional artifact because runtime behavior depends on more than source text. A disciplined workflow is straightforward: This does not eliminate nondeterminism. It gives reviewers something more precise than “I tried the prompt and it looked better.” The tagged release and fixtures used for this article are available on GitHub https://github.com/rajudandigam/agent-inspect/tree/agent-inspect%406.17.4 . If you adopt behavior diffs in code review, begin with one high-risk fixture and learn which differences your team actually finds actionable.