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, 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.
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:
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. If you adopt behavior diffs in code review, begin with one high-risk fixture and learn which differences your team actually finds actionable.