Building multi-agent systems: patterns, pitfalls and when not to

Short answer: a multi-agent system splits a job between several language-model "agents", each with its own instructions, tools and context, coordinated by code or by an orchestrator agent. It helps when sub-tasks are truly separable (research in parallel, then write) or need different tools and permissions. It costs more tokens, adds failure points and is harder to test, so start with a single agent or a fixed workflow and split only when you can measure the gain.

The four patterns you will actually use

Pattern	How it works	Good for
Pipeline	Agent A's output is agent B's input, in a fixed order	Draft, then review, then format
Router	A cheap classifier sends each request to one specialist	Support desks with distinct topics
Orchestrator-worker	One agent plans, spawns workers for sub-tasks, merges their short results	Research over many sources, large code changes
Evaluator-optimizer	One agent produces, another critiques against criteria, loop until it passes	Writing that must meet a rubric

A pipeline or router is often just ordinary code calling a model several times. That is a feature: fixed control flow is easier to debug than agents deciding everything.

Shared state and handoffs

Agents need a clear contract for what they pass on. Keep a typed state object (for example a Python TypedDict or a Pydantic model) that each step reads and updates, instead of passing whole chat histories around. Graph frameworks such as LangGraph make this explicit: nodes are steps, edges are transitions, and the state is checkpointed so a run can resume or be inspected. See a minimal two-node graph with its real output on the LangGraph glossary page.

Why multi-agent systems fail

• Context loss at handoffs. The worker never saw the detail that mattered. Pass the goal and constraints, not just the sub-task.
• Runaway loops and cost. Two agents politely asking each other for more information. Cap steps, tokens and time.
• Conflicting actions. Two workers edit the same file or record. Give each worker its own scope.
• Unclear responsibility. When the answer is wrong, which agent failed? Log every step with inputs and outputs.

How to evaluate one

Test each agent alone on its own small dataset, then the whole system end to end. Track task success, number of steps, tokens and cost per task, and how often a human had to step in. Compare against the single-agent baseline: if the multi-agent version is not clearly better on these numbers, keep the simpler one.

Safety

Give each agent the smallest set of tools it needs, require human approval for irreversible actions (payments, emails, deletions), and treat text coming back from tools and other agents as untrusted input that may carry prompt injection.

Where this is taught

Module 10 (Agents & MCP) covers workflows vs agents, the tool-use loop without a framework, planning and routing patterns, LangGraph state and checkpoints, multi-agent orchestration, human-in-the-loop approvals and evaluating agent cost. Related: How to implement MCP in Python · AI agent.