Revisiting Old Agent Architecture Decisions as the Field Moves
An accepted ADR is not a forever spell.
//
Search across all documentation pages
An accepted ADR is not a forever spell.
In agent systems, models, frameworks, gateways, and protocols move fast enough that scheduled and triggered reviews are part of the architecture.
This ranked-decision list tells you what to revisit first, how often, and when to supersede vs leave alone.
still valid, update pins, or superseded by ADR-0XX.| Rank | Decision class | Why it ages fastest | Typical action |
|---|---|---|---|
| 1 | Model pins and tiers | New releases and price shifts monthly | Re-eval; retarget roles |
| 2 | Provider / gateway path | Fees, outages, policy, BYOK | Confirm path still legal and cheap enough |
| 3 | Tool privilege surface | New MCP servers and write tools | Re-assert least privilege |
| 4 | Orchestration topology | Single vs multi-agent cost in prod metrics | Merge or split with evidence |
| 5 | Framework / runtime | Majors, checkpoint formats, lock-in pain | Spike migrate or stay |
| 6 | Memory and retention | Privacy law + product memory features | Tighten retention; migrate store |
| 7 | Eval gates and SLOs | Traffic shape changes | Recalibrate thresholds |
| 8 | HITL and kill switches | Autonomy creep | Re-map irreversible actions |
Always start at rank 1-2 on a quarterly review unless a higher-severity trigger says otherwise.
| Rank | Choice | Approach |
|---|---|---|
| Best | Re-run gold set on candidate pins; swap roles only if metrics win | Keep roles stable; change pins |
| 2nd | Canary new pin on one surface | Limit blast radius |
| 3rd | Ignore until annual planning | Only if spend and quality are already excellent |
Wrong choice: Silent production pin edits with no eval. Why best is best: You capture upside without rewriting architecture stories.
| Rank | Choice | Approach |
|---|---|---|
| Best | Inspect turns, model mix, and thrash; then retier or bound | Fix host policy before blaming one vendor |
| 2nd | Swap mid-tier pin or add triage role | Document in model decision record |
| 3rd | Big-bang multi-agent rewrite for cost alone | Coordination may raise cost |
Wrong choice: Cutting all evals and logging to "save money." Why best is best: Agent cost is usually loop-shaped, not only $/token.
| Rank | Choice | Approach |
|---|---|---|
| Best | Exercise documented fallback; file ADR amendment if fallback failed | Incidents test the access-path decision |
| 2nd | Add hybrid backup path | Direct + gateway or second provider |
| 3rd | Abandon multi-model forever out of anger | Overfitting to one outage |
Wrong choice: Emergency hardcode with no decision record update. Why best is best: The ADR should get smarter after every SEV.
| Rank | Choice | Approach |
|---|---|---|
| Best | List concrete escape-hatch pain; spike one alternative for a week | Evidence over vibes |
| 2nd | Stay; invest in platform wrappers | If pain is training, not capability |
| 3rd | Rewrite all agents in a weekend | Portable tools or bust |
Wrong choice: New framework every quarter. Why best is best: Framework ADRs should supersede only with spike + migration plan.
| Rank | Choice | Approach |
|---|---|---|
| Best | Measure handoff failure and duplicate tools; simplify topology if roles are fake | Merge specialists with identical allowlists |
| 2nd | Tighten handoff schema and budgets | Keep multi if privilege differs |
| 3rd | Add more agents to "fix" coordination | Usually worsens cost |
Wrong choice: Prompt-only "please coordinate better." Why best is best: Topology is an architecture decision; fix it with contracts and metrics.
| Rank | Choice | Approach |
|---|---|---|
| Best | Treat as hard trigger; re-validate gateway/direct and memory stores immediately | Legal beats convenience |
| 2nd | Segment traffic (PII path vs non-PII path) | Document hybrid |
| 3rd | Hope existing DPAs cover new tools | Audit failure waiting to happen |
Wrong choice: Shipping a new MCP server that exfiltrates customer data without review. Why best is best: Access path and tool ADRs are compliance artifacts.
| Cadence | Scope | Output |
|---|---|---|
| Monthly | Model pins, cost/success, error slices | Pin table updates or explicit "no change" |
| Quarterly | Full ADR index review (status + triggers) | still valid / supersede plan |
| Per major release | Framework or protocol upgrades | Spike notes + migration ADR |
| Per SEV | Related decisions only | Amendment within 5 business days |
| Per new write tool class | Privilege + HITL ADRs | Accept or reject before enable |
Put the quarterly review on the team calendar with an owner - not "when we have time."
accepted older than 90 days.| Situation | Action |
|---|---|
| Same decision, new model id | Amend pins + date; keep ADR id |
| Forces changed (legal, topology) | Supersede with new ADR |
| Minor wording | Edit with PR; no status circus |
| Decision still right, doc stale | Refresh consequences; status stays accepted |
| System retired | Deprecated with pointer to replacement |
| Anti-pattern | Better |
|---|---|
| Eternal accepted ADRs never opened | Quarterly pass |
| Rewrite without supersession links | Bidirectional ADR links |
| Review only when angry after outage | Calendar + triggers |
| Measuring framework hype, not evals | Gold set first |
| Changing topology and provider in one ADR | Split decisions |
Enough to cover binding choices (often 5-15), not one per ticket. Archive deprecated systems.
That is a review finding. Either reconstruct from git and metrics or supersede with a clean decision.
For autonomy, cost, and user-visible degrade paths, yes. Skip pure package-upgrade pins.
Require eval deltas and cost impact above a threshold before superseding topology or framework.
Yes. A dated still valid note prevents re-litigating the same argument without new evidence.
If others depend on your defaults, yes. Hobby scripts can keep a shorter pin changelog.
In the ADR file (append a Review log) or a linked minutes doc committed next to ADRs.
Task success, cost per success, p95 run latency, stop-reason mix, and (if multi-agent) handoff failure rate.
Flags implement rollout. Reviews still decide whether the target architecture remains correct.
Within one sprint of the major becoming relevant to your version pin - do not wait for a production break.
Monthly pin and cost review with a frozen gold set. Most field movement shows up there first.
Runtime exit cheatsheets are trigger sources for framework ADRs - link them in the quarterly agenda.
Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana
@solana/web3.js+@solana/spl-token.
Reviewed by Chris St. John·Last updated Jul 16, 2026