An ADR Template for Agent Framework Selection
Use this page when you must pick (or replace) an agent framework and want a commit-ready ADR.
It is a cheatsheet template: copy the Markdown skeleton, fill every section, and link config pins.
How to Use This List
- Copy the template skeleton into
docs/adr/ADR-0XX-framework.md. - Score candidates with the comparison matrix before writing the Decision section.
- Fill consequences and revisit triggers even if the choice feels obvious.
- Keep tools, schemas, and evals outside the framework so the ADR can be superseded later.
Template Skeleton (copy/paste)
# ADR-0XX: Agent framework selection for <product/surface>
- Status: proposed | accepted | deprecated | superseded
- Date: YYYY-MM-DD
- Owner: <team>
- Supersedes: <ADR-id or none>
- Superseded by: <ADR-id or none>
## Context
What agent(s) are we building, under what time and compliance constraints?
## Forces
- Team skills:
- Deadline:
- Orchestration needs (loop / graph / HITL / multi-agent):
- Dependency and security constraints:
- Multi-model or single-provider:
- Non-goals:
## Options considered
### Option A: <name>
- Pros:
- Cons:
- Fit score (1-5):
### Option B: <name>
- Pros:
- Cons:
- Fit score (1-5):
### Option C: <name> (include "thin custom runtime" when relevant)
- Pros:
- Cons:
- Fit score (1-5):
## Decision
We will use **<framework or custom>** because <one paragraph>.
## Portable assets (must remain framework-agnostic)
- Tools / plugins:
- JSON/Pydantic schemas:
- Prompt templates:
- Gold-set evals:
- Stop reason enums:
## Config pins (verify at build)
- Package versions:
- Default model role / gateway:
- Checkpoint / state store:
- Tracing backend:
## Consequences
### Positive
-
### Negative (accepted)
-
### Follow-up work
- [ ]
## Revisit when
- [ ] Trigger 1
- [ ] Trigger 2
- [ ] Calendar review: YYYY-MM-DD
## References
- Spike notes / PR:
- Eval results:
- Related ADRs:Comparison Matrix (fill before deciding)
| Criterion | Weight (1-5) | Custom thin loop | LangGraph | CrewAI | MS Agent Framework | Pydantic AI / native SDK |
|---|---|---|---|---|---|---|
| Time-to-first production agent | ||||||
| Graph / join / resume needs | ||||||
| Multi-agent primitives | ||||||
| HITL / interrupt model | ||||||
| Typed tools and schemas | ||||||
| Observability integrations | ||||||
| Dependency / air-gap friendliness | ||||||
| Team skill fit | ||||||
| Lock-in risk if wrong | ||||||
| Escape hatch quality |
Score = sum(weight x fit). Highest score is a candidate, not an automatic winner if a single hard constraint (legal, resume, skill) vetoes it.
Option Cheatsheet
| Option | Best when | Weak when |
|---|---|---|
| Thin custom loop | One bounded tool agent; hard dependency limits | Durable multi-day graphs; multi-team platform needs |
| LangGraph | Graphs, checkpoints, streaming, LangChain ecosystem | You only need a 50-line loop and hate graph mental model |
| CrewAI | Role-oriented crews and demos that match the metaphor | You need strict host-owned control and minimal magic |
| Microsoft Agent Framework | Enterprise .NET/Python workflows, Microsoft-centric stack | Small polyglot teams outside that ecosystem |
| Pydantic AI | Schema-first Python services | Heavy multi-agent graph product without extra structure |
| OpenAI Agents SDK / native | Single-provider speed, handoffs, MCP | Strong multi-cloud / multi-vendor requirements day one |
| No/low-code orchestrator | Integration-heavy internal automation | Core product agents needing deep eval and code review |
Exact feature sets change - verify against current docs at decision time.
Decision Quality Checklist
- 1. Problem is agent-shaped - tools + multi-step choice, not a single LLM call.
- 2. At least two real options scored, including custom when skill allows.
- 3. Hard constraints called out (resume, data residency, approved vendors).
- 4. Portable assets listed - tools/schemas/evals not trapped in the framework.
- 5. Negative consequences accepted in writing.
- 6. Config pins named (packages, model role, state store).
- 7. Revisit triggers are falsifiable (metric, capability, or date).
- 8. Security review if tools can write, pay, or shell.
- 9. Spike evidence attached (even a one-day spike).
- 10. Status and owner set so supersession is possible later.
Sample Filled Decision (abridged)
Decision: LangGraph for the claims workflow agent; thin loop remains for
the FAQ single-tool bot.
Why: Claims need human approval mid-graph and durable resume across deploys.
FAQ does not.
Portable: claims tools are pure functions + Pydantic models; gold set in /evals.
Revisit when: MS Agent Framework becomes the org standard, or LangGraph
upgrade cost exceeds two eng-weeks per quarter without benefit.Anti-Patterns in Framework ADRs
| Anti-pattern | Fix |
|---|---|
| "We chose X because it is popular" | Tie to forces: resume, skill, compliance |
| No custom option considered | Include thin loop when scope is small |
| Decision mixes model vendor + framework | Split into two ADRs |
| No portable assets section | Extract tools before coding graphs |
| No revisit date | Add calendar + capability triggers |
| ADR lives only in a slide deck | Commit Markdown in git |
FAQs
Should every microservice pick its own framework?
Prefer a small set of approved options via platform ADRs. Product ADRs choose among approved options unless they have a special constraint.
Can we accept two frameworks in one org?
Yes if split by surface (for example UI SDK vs worker graphs) and portable tools stay shared. Document the split explicitly.
How long should the spike be before the ADR?
Often one to five days with a real tool and a tiny eval set. Longer spikes usually mean unclear forces.
What if legal has not approved a dependency yet?
Keep status proposed, list blockers, and do not ship production traffic on it. Consider custom or already-approved stacks as interim options.
Do we need a new ADR for a major version upgrade?
Yes when upgrade changes control model, state format, or requires multi-week migration. Routine patches can stay in release notes.
Where do model IDs go in this template?
Under config pins as roles plus a link to the model/provider ADR. Do not bury vendor-specific ids only inside framework examples.
Is "we will decide later" a valid decision?
Only as a time-boxed proposed ADR with an explicit deadline. Open-ended deferrals become accidental architecture.
How detailed should Consequences be?
Enough that a new hire understands the pain you accepted (ops load, lock-in, missing features) without reading the spike.
Should the ADR include code samples?
Optional short sketches are fine. Prefer links to the spike branch and to production config modules.
What related trade-off pages should reviewers read?
Single vs multi-agent, gateway vs direct, and framework-free vs framework-based pages in this site's architecture and choosing-framework sections.
How do we mark an ADR superseded after a migration?
Set status to superseded, point superseded by at the new id, and keep the old file forever for audit history.
Can this template work for no-code tools?
Yes. Treat the no-code product as the "framework" option and still list portable assets and exit triggers.
Related
- Why Agent Systems Need Their Own ADR Discipline - motivation
- Architecture Decisions Basics - first worked example
- Framework Comparison Matrix: LangGraph, CrewAI, Microsoft Agent Framework, and More - deeper matrix
- Framework-Free vs Framework-Based: When to Roll Your Own - custom path
- POC-to-Production Migration Paths Between Frameworks - migration
- Matching Team Skill Set to Framework Choice - skill fit
- Architecture Decisions Best Practices - process checklist
- When a Custom Runtime Stops Being Worth Maintaining - exit custom
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.