Multi-Agent Architecture Best Practices

Ten practices for scoping, coordinating, and debugging multi-agent systems. Use them as a design rubric and a PR checklist for role graphs and handoff code.

How to Use This List

Walk A when deciding whether to multi-agent at all; B when implementing packets and workers; C when operating production runs.
Tick items only when true in code, schemas, or dashboards - not aspirations.
Pair with Avoiding Context Loss and Duplication Across Agent Handoffs for boundary hygiene.
Re-check after adding a specialist, tool, or cross-runtime peer.

A - Scope the Graph

1. Split only on real boundaries. Different tools, trust levels, model tiers, or human gates - not cosmetic names. See Why Split One Agent Into Many Specialized Agents.
2. Prefer the smallest graph that works. Two agents beat five until metrics demand more hops.
3. Name topology in one sentence. Orchestrator-worker, pipeline, peer mesh, or hybrid - and who owns the global budget.
4. Keep least-privilege tool allowlists per role. Shared superuser belts recreate monolith risk.
5. Default new product paths to orchestrator-worker. Adopt peer-to-peer only with cycle guards and a clear user channel.

B - Contracts, Budgets, Handoffs

6. Use structured handoff packets and return contracts. Subgoal, constraints, inputs/refs, success fields, status enum - not transcript dumps. See Context Handoff: Passing State Between Agents Cleanly.
7. Validate at every boundary in the host. Schema failures fail closed; do not ask the model to self-police structure alone.
8. Enforce nested budgets. Per-specialist max turns/time/cost and global caps with a non-agent watchdog.
9. Define failure policy explicitly. Retry, re-route, replan, refuse, or needs_human - with caps on retries and handoff depth.
10. Version the communication contract. Envelope + payloads + authz edges documented and tested in CI. See Architecture Guide: Designing a Multi-Agent System's Communication Contract.

C - Operate and Prove

11. Trace every hop. run_id, handoff_id, from, to, status, packet keys, budget remaining.
12. Eval roles separately and together. Return-schema validity and route accuracy plus end-to-end task success.
13. Store large artifacts once; pass refs. Merge with explicit conflict rules on fan-in.
14. Redact by role. Packets and logs must not leak secrets or PII to low-trust specialists or vendors.
15. Revisit the graph when metrics move. Rising depth, validation failures, duplicate tool calls, or cost without quality gains are design smells.

Applying These Practices in Order

Scope (1-5): cheap on a whiteboard; expensive after five entangled agents ship.
Contracts and budgets (6-10): launch blockers for any multi-agent path with real tools.
Operate (11-15): keep the architecture honest under traffic and retries.

FAQs

Why "ten practices" if there are fifteen checkboxes?

Items 1-10 are the core multi-agent practices promised by the section. Items 11-15 extend them into production operations so the list stays useful after launch.

What is the single most important practice?

Host-enforced budgets and stop conditions across all loops. Everything else fails more safely when agents cannot run forever.

How do these practices relate to framework choice?

They are framework-agnostic. Choose topology and contracts first; then map onto LangGraph, CrewAI, OpenAI Agents SDK, Microsoft Agent Framework, or a custom host.

When is multi-agent the wrong default?

When one role, one trust level, and one tool belt complete the job with a short single-agent loop. Coordination tax is not free.

How do I detect multi-agent costume?

Same tools, near-identical prompts, full shared transcript, and no validated return status - only different display names.

Should the orchestrator use a stronger model than workers?

Often the opposite: a cheap router and stronger specialists for hard work - or strong planner and cheap workers. Measure; do not assume.

How deep may handoffs go?

Set a low hard cap for interactive products (often single digits). Research meshes may go deeper but still need progress tokens and watchdogs.

Where should humans sit in the checklist?

As first-class nodes with contracts (practice 9) and as owners of kill switches (practice 8's watchdog). Never only as an informal Slack side channel.

What dashboard tiles map to these practices?

Handoff validation rate, depth histogram, budget-hit rate, duplicate artifact writes, route accuracy, and final task success.

Do A2A deployments change the practices?

Core practices stay. Add mutual auth, discovery (Agent Cards), and transport timeouts when peers cross runtimes.

Can we adopt practices incrementally?

Yes. Ship two-agent path with packets and budgets first; then schema CI, richer evals, and only later peer edges or fan-out.

Where should teams link this list?

Section close-out in the sidebar, agent ADRs, and PR templates that touch role graphs or handoff code.

Why Split One Agent Into Many Specialized Agents - decomposition rationale
Multi-Agent Architecture Basics - first two-agent system
Orchestrator-Worker Patterns for Coordinating Specialist Agents - central dispatch
Peer-to-Peer Agent Collaboration Without a Central Orchestrator - decentralized option
Context Handoff: Passing State Between Agents Cleanly - packet recipe
Avoiding Context Loss and Duplication Across Agent Handoffs - loss/dupe cheatsheet
Architecture Guide: Designing a Multi-Agent System's Communication Contract - ADR guide
Multi-Agent Handoff: Specialist Agents Passing Work to Each Other - related architecture section

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.

Multi-Agent Architecture Best Practices

Ten practices for scoping, coordinating, and debugging multi-agent systems. Use them as a design rubric and a PR checklist for role graphs and handoff code.

How to Use This List

Walk A when deciding whether to multi-agent at all; B when implementing packets and workers; C when operating production runs.
Tick items only when true in code, schemas, or dashboards - not aspirations.
Pair with Avoiding Context Loss and Duplication Across Agent Handoffs for boundary hygiene.
Re-check after adding a specialist, tool, or cross-runtime peer.

A - Scope the Graph

1. Split only on real boundaries. Different tools, trust levels, model tiers, or human gates - not cosmetic names. See Why Split One Agent Into Many Specialized Agents.
2. Prefer the smallest graph that works. Two agents beat five until metrics demand more hops.
3. Name topology in one sentence. Orchestrator-worker, pipeline, peer mesh, or hybrid - and who owns the global budget.
4. Keep least-privilege tool allowlists per role. Shared superuser belts recreate monolith risk.
5. Default new product paths to orchestrator-worker. Adopt peer-to-peer only with cycle guards and a clear user channel.

B - Contracts, Budgets, Handoffs

6. Use structured handoff packets and return contracts. Subgoal, constraints, inputs/refs, success fields, status enum - not transcript dumps. See Context Handoff: Passing State Between Agents Cleanly.
7. Validate at every boundary in the host. Schema failures fail closed; do not ask the model to self-police structure alone.
8. Enforce nested budgets. Per-specialist max turns/time/cost and global caps with a non-agent watchdog.
9. Define failure policy explicitly. Retry, re-route, replan, refuse, or needs_human - with caps on retries and handoff depth.
10. Version the communication contract. Envelope + payloads + authz edges documented and tested in CI. See Architecture Guide: Designing a Multi-Agent System's Communication Contract.

C - Operate and Prove

11. Trace every hop. run_id, handoff_id, from, to, status, packet keys, budget remaining.
12. Eval roles separately and together. Return-schema validity and route accuracy plus end-to-end task success.
13. Store large artifacts once; pass refs. Merge with explicit conflict rules on fan-in.
14. Redact by role. Packets and logs must not leak secrets or PII to low-trust specialists or vendors.
15. Revisit the graph when metrics move. Rising depth, validation failures, duplicate tool calls, or cost without quality gains are design smells.

Applying These Practices in Order

Scope (1-5): cheap on a whiteboard; expensive after five entangled agents ship.
Contracts and budgets (6-10): launch blockers for any multi-agent path with real tools.
Operate (11-15): keep the architecture honest under traffic and retries.

FAQs

Why "ten practices" if there are fifteen checkboxes?

Items 1-10 are the core multi-agent practices promised by the section. Items 11-15 extend them into production operations so the list stays useful after launch.

What is the single most important practice?

Host-enforced budgets and stop conditions across all loops. Everything else fails more safely when agents cannot run forever.

How do these practices relate to framework choice?

They are framework-agnostic. Choose topology and contracts first; then map onto LangGraph, CrewAI, OpenAI Agents SDK, Microsoft Agent Framework, or a custom host.

When is multi-agent the wrong default?

When one role, one trust level, and one tool belt complete the job with a short single-agent loop. Coordination tax is not free.

How do I detect multi-agent costume?

Same tools, near-identical prompts, full shared transcript, and no validated return status - only different display names.

Should the orchestrator use a stronger model than workers?

Often the opposite: a cheap router and stronger specialists for hard work - or strong planner and cheap workers. Measure; do not assume.

How deep may handoffs go?

Set a low hard cap for interactive products (often single digits). Research meshes may go deeper but still need progress tokens and watchdogs.

Where should humans sit in the checklist?

As first-class nodes with contracts (practice 9) and as owners of kill switches (practice 8's watchdog). Never only as an informal Slack side channel.

What dashboard tiles map to these practices?

Handoff validation rate, depth histogram, budget-hit rate, duplicate artifact writes, route accuracy, and final task success.

Do A2A deployments change the practices?

Core practices stay. Add mutual auth, discovery (Agent Cards), and transport timeouts when peers cross runtimes.

Can we adopt practices incrementally?

Yes. Ship two-agent path with packets and budgets first; then schema CI, richer evals, and only later peer edges or fan-out.

Where should teams link this list?

Section close-out in the sidebar, agent ADRs, and PR templates that touch role graphs or handoff code.

Why Split One Agent Into Many Specialized Agents - decomposition rationale
Multi-Agent Architecture Basics - first two-agent system
Orchestrator-Worker Patterns for Coordinating Specialist Agents - central dispatch
Peer-to-Peer Agent Collaboration Without a Central Orchestrator - decentralized option
Context Handoff: Passing State Between Agents Cleanly - packet recipe
Avoiding Context Loss and Duplication Across Agent Handoffs - loss/dupe cheatsheet
Architecture Guide: Designing a Multi-Agent System's Communication Contract - ADR guide
Multi-Agent Handoff: Specialist Agents Passing Work to Each Other - related architecture section

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.

Multi-Agent Architecture Best Practices

Search Documentation

Multi-Agent Architecture Best Practices