Dependency Upgrade Agents

The bump was never the hard part.

Dependabot and Renovate already open the pull request, resolve the lockfile, group related packages and rebase on conflict. If opening PRs were the bottleneck, the backlog would not exist. The backlog exists because those PRs sit in a queue nobody wants to be responsible for, and an agent that produces the same PR with a nicer commit message adds volume rather than throughput.

• Name the bottleneck honestly: it is the reviewer's willingness to press merge on a change they did not make, to code they may not own, in a library they have not read.
• That willingness is a function of evidence, not of automation quality. The agent's output is judged as an argument — "here is why this is safe" — and its job is to be persuasive to a specific human on a specific repo.
• Which reframes the build. Do not start with "how does the agent apply the upgrade". Start with "what would make me merge this without reading the diff", write that down, and build backwards.
• Keep the existing bot. Let Renovate detect and open; let the agent do the part Renovate cannot — reading the changelog, adapting call sites, and assembling the case. Replacing the detector is work with no payoff.

A green test suite is weak evidence exactly where upgrades break.

The whole practice rests on an assumption worth stating out loud: that passing tests mean the upgrade is safe. That assumption is strongest for the upgrades that were never dangerous and weakest for the ones that are.

• Tests cover your code, not the library's behaviour. A dependency that changes a default — a timeout, a retry policy, a serialisation format, a timezone assumption — usually keeps its signature and passes every test you own while changing production behaviour.
• Transitive upgrades are invisible in the diff. A lockfile change can move a package three levels down that nothing in your test suite exercises directly and everything in production depends on.
• Coverage gaps correlate with risk. The modules nobody wrote tests for are usually the integration edges — auth, payments, file handling — which is exactly where a library's behaviour change lands.
• So the agent must know what the tests do not prove. A report that says "all 4,812 tests pass" is worth less than one that says "all tests pass; the three call sites touching the changed retry default have no test coverage; here they are." The second is a reviewable claim, the argument in patch generation & tests.

Design the evidence policy before the agent.

Write down, per class of upgrade, what the agent must produce before a human is asked to look. This document is the actual product; the agent is an implementation of it.

• Patch release, no API surface change: tests green, lockfile diff summarised, upstream changelog quoted with a link. Enough for an auto-merge lane.
• Minor release with new behaviour: the above, plus an explicit list of every changed default and every deprecation in the release notes, mapped to the call sites in your repo that touch them — including "none found", which is a claim the agent is making and can be wrong about.
• Major release: the above, plus the migration performed, plus a written statement of what the agent could not verify. Never auto-merge this lane.
• Security advisory: the above, plus whether the vulnerable code path is reachable from your code at all. "We use this package but never call the affected function" is the single most valuable sentence an upgrade agent can produce, and it is what turns a 200-item advisory queue into a five-item one.

Have the agent cite its sources — the changelog line, the upstream diff, the file and line in your repo. An unsourced claim from an agent is a claim a reviewer must independently verify, which costs more than doing the upgrade by hand.

Triage is the deliverable. Merging is only the easy lane.

The instinct is to measure the agent on upgrades merged. That metric drives it toward the safe patch bumps that were never the problem and away from the majors that are. Measure it instead on correct sorting.

• Lane one — auto-merge. Patch-level, evidence complete, no changed defaults, no coverage gaps at affected call sites. This should be most of the volume and should require no human at all.
• Lane two — human review, agent-prepared. The agent did the migration, wrote the case, and named the specific thing it wants a human to check. This is where the value is: a reviewer spending four minutes on a targeted question instead of forty on a cold diff.
• Lane three — blocked, with a reason. The agent could not adapt the call sites, or the upstream change is ambiguous, or it cannot determine reachability. A well-written blocked ticket is a successful outcome, and an agent that never produces one is over-claiming.
• Track lane-two acceptance rate and lane-one revert rate. The first tells you whether the evidence is persuasive; the second tells you whether it was true. A rising revert rate in lane one means the auto-merge criteria are too loose, and it is the only number that should be allowed to close the lane.

Read the release notes like an adversary, not like a summariser.

The single highest-leverage capability here is reading upstream material well, and the failure mode is producing a pleasant summary of a changelog instead of interrogating it. Give the agent an explicit checklist rather than an instruction to "review the changes".

• What changed that is not in the API surface? Defaults, error types, ordering guarantees, thread-safety, log format, timezone and locale handling. These break silently and are the reason this playbook exists.
• What was deprecated, and what is the deadline? A deprecation is a scheduled future break; recording it now is how you avoid a forced major migration later.
• Fetch the actual upstream diff for the affected paths rather than trusting the changelog. Release notes are marketing for maintainers; they under-report behaviour changes routinely.
• Check the ecosystem, not just the package. Peer-dependency ranges, the minimum runtime version, and whether your other libraries have shipped compatible releases. This is the class of failure that turns a one-package upgrade into an afternoon.
• Treat upstream text as untrusted input. The agent is reading attacker-influenceable content from a package registry with repo write access nearby; the isolation argument in sandboxing & execution and the threat model in agent supply chain security both apply directly here.

Operate it: batch by blast radius, never by convenience.

How you group upgrades decides whether a revert is a two-minute operation or an archaeology project, and it is the operational decision teams get wrong most often.

• Group by rollback unit. Twenty dev-dependency patches in one PR is fine — reverting the batch costs nothing. Two production libraries in one PR is not, because a bad deploy leaves you bisecting under pressure.
• Never mix an upgrade with a refactor. If the agent must change call sites to accommodate a new API, that is the upgrade; everything else it noticed goes in a separate PR. This is the discipline that keeps large-scale migration agents reviewable, and it matters more here because the reviewer is deliberately not reading closely.
• Run it on a cadence the team can absorb. A weekly batch that gets reviewed beats a nightly stream that gets ignored; an agent that outruns its reviewers has recreated the original backlog with better tooling. See scheduled & triggered agents.
• Scope the credentials to the job. The agent needs to read the repo, push a branch and open a PR. It does not need to merge, to push to the default branch, or to touch CI configuration or publishing secrets.
• Report the real metric: median dependency age. Not PRs opened, not upgrades merged. Age is what the security team cares about, it is what the practice exists to reduce, and it is the only number that goes up when the agent is producing volume instead of throughput.

Related: code review agents for the reviewer on the other side, test generation agents for filling the coverage gaps this work exposes, and evaluating coding agents for measuring whether any of it works.