How to Build a Multi-Agent System: Roles, Contracts & Shared State

To build a multi-agent system, define specialized roles (e.g., planner, tool executor, reviewer), give each a narrow contract and tools, share state through an explicit schema or event log, and assign one orchestrator responsible for the final user-visible result. Adding agents without contracts creates silent failures and cost blowups.

Multi-agent is an organizational pattern for software: you split work when specialization, permissions, or review genuinely differ—not because “more agents sounds smarter.” Every additional agent adds latency, token cost, and coordination overhead. The bar for adding one should be clear ownership of a distinct subtask with measurable inputs and outputs.

When Do You Need Multiple Agents?

Short answer: When tasks need different tools, permissions, or review—not when one prompt feels crowded.

Good reasons to split: a planner that never touches production APIs; a worker with write access to a CRM; a reviewer that only reads and approves; a researcher with web search but no customer PII. Bad reasons: mimicking a human org chart, chasing framework demos, or hoping agents will “figure out” coordination in free-form chat.

Ask: would a single agent with a verifier and an allowlisted tool set solve this? If yes, stay single-agent. If the worker must not see certain credentials, or a human must approve before a payment tool fires, multi-agent separation earns its keep.

Enterprise examples—banking KYC handoffs, healthcare scheduling with PMS write-back—often need role separation for audit and least privilege. See Enterprise AI Agents: High-Impact Use Cases.

What Is a Good Starter Topology?

Short answer: Planner → Worker(s) → Verifier, with human escalate on verifier fail.

The planner decomposes the user goal into steps and assigns work—it should not call irreversible tools directly. Workers execute tool calls within their contract (one domain per worker is common: “CRM worker,” “calendar worker”). The verifier checks outcomes against success criteria and policy before the orchestrator responds to the user or triggers escalation.

• Planner: read-only context, outputs structured plan or task queue
• Worker(s): typed tools, narrow scope, idempotent where possible
• Verifier: compares tool results + draft reply to rubric; blocks on policy breach
• Orchestrator: owns the user thread; merges worker outputs; decides escalate vs finish

For high-volume production (collections, telecom), queue-based worker pools often replace conversational swarms—each job is a discrete unit with a disposition code, not an open-ended debate.

What Should an Agent Contract Include?

Short answer: Role name, allowed inputs, required outputs, tool allowlist, forbidden actions, and budget caps.

Contracts are interfaces, not vibes. Document them in code or config so you can test and version them:

• Input schema (what context this agent receives)
• Output schema (structured JSON, not free-form prose when downstream agents consume it)
• Tool allowlist with auth scopes
• Max steps / max tokens / max wall time for this role
• Escalation triggers (verifier fail, tool error, policy keyword)

When contracts drift—workers returning prose instead of JSON, planners inventing tool names—integration breaks silently. Treat contract violations as hard errors in observability, not soft warnings.

How Do You Share State Between Agents?

Short answer: Prefer a typed shared store or append-only event log over passing full chat history between agents.

Options that work in production:

• Shared state object: goal, plan, tool results, verifier status—updated by orchestrator
• Event log: each agent appends events; others subscribe to relevant types
• Blackboard pattern: workers write findings; planner reads summaries

Avoid copying entire conversation threads into every agent prompt—that scales cost poorly and leaks irrelevant context. Summarize or project only fields each role needs. Memory design details: Memory, Tools & Autonomy.

How Do You Prevent Agent Sprawl?

Short answer: One outcome owner, measurable contracts, and a rule: no new agent without a failing eval that single-agent cannot fix.

Teams often add a “supervisor” agent when debugging gets hard—then a “critic,” then a “memory agent,” until nobody knows who spoke to the user. Cap the topology: document the graph, assign the orchestrator as DRI for customer outcomes, and review agent count in architecture reviews the same way you review microservices.

Pair multi-agent builds with tracing so you can see which role added latency or caused a bad tool call. Framework comparison criteria: Orchestration Frameworks Compared.

How Do You Test Multi-Agent Systems?

Short answer: End-to-end evals on full journeys plus unit-style tests per contract—not isolated prompt tests per agent.

Build a private eval set of ~100–500 real or synthetic journeys. Score task success, tool correctness, policy violations, and total cost per run. Regression-test when any contract, tool, or model changes. Multi-agent systems fail at integration boundaries; test handoffs explicitly (planner output → worker input → verifier input).

Benchmarking guide: How to Benchmark AI Agent Accuracy. Production path: Production-Ready Agents.

Related

Autonomy hub · Architecture explained · Frameworks compared · Guardrails