Agent Architectures Best Practices

Ten guidelines for matching architecture to task shape before - and while - you write orchestration code. Use them as a design rubric and a PR checklist for agent control flow.

How to Use This List

Walk A when selecting a pattern; B when implementing bounds and tools; C when shipping observability and change control.
Tick items only when they are true in code or docs, not as aspirations.
Pair with Common Architecture Anti-Patterns in Early Agent Projects for the inverse checklist.
Re-check after adding tools, roles, or longer task horizons.

A - Choose the Shape First

1. Name the top-level pattern in one sentence. ReAct, Plan-and-Execute, multi-agent, hybrid (with owner), or "not an agent." Unnamed control flow is undebuggable.
2. Prefer the simplest pattern that meets the job. Scripts beat agents; single ReAct beats multi-agent until roles or privileges truly diverge.
3. Match pattern to task predictability. Unknown path → bounded ReAct; known milestones → Plan-and-Execute; heterogeneous skills/trust → multi-agent or hybrid.
4. Draw the control graph before picking a framework. LangGraph, CrewAI, Microsoft Agent Framework, and custom hosts are wiring; architecture is the graph.
5. Decide hybrid nesting explicitly. If you combine patterns, document outer owner, inner runners, and hierarchical budgets on one page.

B - Bounds, Tools, and Contracts

6. Enforce stop conditions in the host, not only in the prompt. Max turns, timeouts, cost caps, and goal checks must be code-enforced for every loop (including specialists).
7. Keep tool allowlists least-privilege per role. Kitchen-sink tools recreate single-agent risk inside multi-agent costumes.
8. Use structured plans and handoff packets. Plans need ordered verifiable steps; handoffs need subgoal, constraints, inputs, success/failure contracts - not transcript dumps.
9. Cap retries and replans. Resilience without caps becomes thrash; log why a replan or retry fired.
10. Gate irreversible actions. Approve the plan or the privileged step before execute when blast radius is high.

C - Operate What You Designed

11. Log phase labels on every run. plan | step | react_turn | handoff | replan | stop_reason beats raw message graveyards.
12. Eval trajectories, not only final answers. Track turns, repeated tools, budget hits, handoff errors, and goal-complete vs max-turn stops.
13. Treat tool observations as untrusted data. Never let retrieved content redefine system policy or expand privileges.
14. Summarize context at boundaries. Nested loops and handoffs should pass artifacts and digests, not unbounded JSON histories.
15. Revisit architecture when metrics move. Rising turns, cost, or handoff failures are design signals, not only model-quality noise.

Applying These Practices in Order

Shape (1–5): cheap to fix on a whiteboard; expensive after tool sprawl.
Bounds and contracts (6–10): hard launch blockers for production agents.
Operate (11–15): required to keep architecture honest after real traffic.

FAQs

Why "ten guidelines" if there are fifteen checkboxes?

The section promise is ten core architecture guidelines (items 1-10). Items 11-15 extend them into operations so the list stays useful after launch.

What is the first practice if we can only adopt one?

Host-enforced stop conditions (max turns, timeout, cost). Everything else fails more safely when the loop cannot run forever.

How do these practices relate to framework choice?

They are framework-agnostic. Choose architecture first, then map the graph onto LangGraph, CrewAI, Microsoft Agent Framework, OpenAI Agents SDK, or a custom runtime.

Do chat demos need the full checklist?

Demos can be looser, but anything with real tools, credentials, or spend should implement bounds and least privilege before wider access.

How detailed should the "one sentence pattern" be?

Example: "Top-level Plan-and-Execute with 5-turn ReAct per step; no multi-agent." That is enough for reviews and on-call.

When is multi-agent justified under these practices?

When you can name different tools, prompts, or trust levels per specialist and show a handoff contract. Otherwise stay single-agent.

How do plan approvals fit interactive UX?

Show the plan for high-cost or high-risk runs; auto-run only low-risk template stages. Resume the host from an approved plan version.

What belongs in architecture docs vs runbooks?

Architecture docs: pattern, graph, tools per node, budgets, contracts. Runbooks: failure playbooks, replan storms, max-turn incidents.

Can we implement practices incrementally?

Yes. Ship bounds and least privilege first, then structured packets, then deeper evals and phase metrics.

How do these interact with model routing?

Model tier is a per-node config under the architecture. Do not confuse "use a bigger model" with "fix the control pattern."

What evidence shows practice 2 was violated?

Multiple agents or complex graphs for a task that a single tool call or short ReAct loop completes with equal quality and less cost.

Where should teams link this list?

In the section sidebar as the close-out checklist, and from ADRs that record pattern choices for agent systems.

The Three Core Agent Architecture Patterns, Compared - pattern map
When to Choose ReAct vs Plan-and-Execute vs Multi-Agent - decision cheatsheet
Common Architecture Anti-Patterns in Early Agent Projects - inverse checklist
Hybrid Architectures: Combining Planning, Reaction, and Delegation - nesting patterns safely
Agent Architectures Basics - first sketches
Multi-Agent Handoff: Specialist Agents Passing Work to Each Other - handoff design

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.

Agent Architectures Best Practices

Ten guidelines for matching architecture to task shape before - and while - you write orchestration code. Use them as a design rubric and a PR checklist for agent control flow.

How to Use This List

Walk A when selecting a pattern; B when implementing bounds and tools; C when shipping observability and change control.
Tick items only when they are true in code or docs, not as aspirations.
Pair with Common Architecture Anti-Patterns in Early Agent Projects for the inverse checklist.
Re-check after adding tools, roles, or longer task horizons.

A - Choose the Shape First

1. Name the top-level pattern in one sentence. ReAct, Plan-and-Execute, multi-agent, hybrid (with owner), or "not an agent." Unnamed control flow is undebuggable.
2. Prefer the simplest pattern that meets the job. Scripts beat agents; single ReAct beats multi-agent until roles or privileges truly diverge.
3. Match pattern to task predictability. Unknown path → bounded ReAct; known milestones → Plan-and-Execute; heterogeneous skills/trust → multi-agent or hybrid.
4. Draw the control graph before picking a framework. LangGraph, CrewAI, Microsoft Agent Framework, and custom hosts are wiring; architecture is the graph.
5. Decide hybrid nesting explicitly. If you combine patterns, document outer owner, inner runners, and hierarchical budgets on one page.

B - Bounds, Tools, and Contracts

6. Enforce stop conditions in the host, not only in the prompt. Max turns, timeouts, cost caps, and goal checks must be code-enforced for every loop (including specialists).
7. Keep tool allowlists least-privilege per role. Kitchen-sink tools recreate single-agent risk inside multi-agent costumes.
8. Use structured plans and handoff packets. Plans need ordered verifiable steps; handoffs need subgoal, constraints, inputs, success/failure contracts - not transcript dumps.
9. Cap retries and replans. Resilience without caps becomes thrash; log why a replan or retry fired.
10. Gate irreversible actions. Approve the plan or the privileged step before execute when blast radius is high.

C - Operate What You Designed

11. Log phase labels on every run. plan | step | react_turn | handoff | replan | stop_reason beats raw message graveyards.
12. Eval trajectories, not only final answers. Track turns, repeated tools, budget hits, handoff errors, and goal-complete vs max-turn stops.
13. Treat tool observations as untrusted data. Never let retrieved content redefine system policy or expand privileges.
14. Summarize context at boundaries. Nested loops and handoffs should pass artifacts and digests, not unbounded JSON histories.
15. Revisit architecture when metrics move. Rising turns, cost, or handoff failures are design signals, not only model-quality noise.

Applying These Practices in Order

Shape (1–5): cheap to fix on a whiteboard; expensive after tool sprawl.
Bounds and contracts (6–10): hard launch blockers for production agents.
Operate (11–15): required to keep architecture honest after real traffic.

FAQs

Why "ten guidelines" if there are fifteen checkboxes?

The section promise is ten core architecture guidelines (items 1-10). Items 11-15 extend them into operations so the list stays useful after launch.

What is the first practice if we can only adopt one?

Host-enforced stop conditions (max turns, timeout, cost). Everything else fails more safely when the loop cannot run forever.

How do these practices relate to framework choice?

They are framework-agnostic. Choose architecture first, then map the graph onto LangGraph, CrewAI, Microsoft Agent Framework, OpenAI Agents SDK, or a custom runtime.

Do chat demos need the full checklist?

Demos can be looser, but anything with real tools, credentials, or spend should implement bounds and least privilege before wider access.

How detailed should the "one sentence pattern" be?

Example: "Top-level Plan-and-Execute with 5-turn ReAct per step; no multi-agent." That is enough for reviews and on-call.

When is multi-agent justified under these practices?

When you can name different tools, prompts, or trust levels per specialist and show a handoff contract. Otherwise stay single-agent.

How do plan approvals fit interactive UX?

Show the plan for high-cost or high-risk runs; auto-run only low-risk template stages. Resume the host from an approved plan version.

What belongs in architecture docs vs runbooks?

Architecture docs: pattern, graph, tools per node, budgets, contracts. Runbooks: failure playbooks, replan storms, max-turn incidents.

Can we implement practices incrementally?

Yes. Ship bounds and least privilege first, then structured packets, then deeper evals and phase metrics.

How do these interact with model routing?

Model tier is a per-node config under the architecture. Do not confuse "use a bigger model" with "fix the control pattern."

What evidence shows practice 2 was violated?

Multiple agents or complex graphs for a task that a single tool call or short ReAct loop completes with equal quality and less cost.

Where should teams link this list?

In the section sidebar as the close-out checklist, and from ADRs that record pattern choices for agent systems.

The Three Core Agent Architecture Patterns, Compared - pattern map
When to Choose ReAct vs Plan-and-Execute vs Multi-Agent - decision cheatsheet
Common Architecture Anti-Patterns in Early Agent Projects - inverse checklist
Hybrid Architectures: Combining Planning, Reaction, and Delegation - nesting patterns safely
Agent Architectures Basics - first sketches
Multi-Agent Handoff: Specialist Agents Passing Work to Each Other - handoff design

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.

Agent Architectures Best Practices

Buscar en la documentación

Agent Architectures Best Practices