An ADR Template for Agent Framework Selection

Q: 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.

Q: 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.

Q: 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.

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

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.

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.

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

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.

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.

An ADR Template for Agent Framework Selection

Search Documentation

An ADR Template for Agent Framework Selection