Overview

Multi-agent systems coordinate specialized agents or components to handle complex workflows. Not every complex task needs multiple agents—a single agent with the right tools and prompt can often suffice. This page summarizes when multi-agent patterns help and which patterns the project supports.

​

Why multi-agent?

Multi-agent patterns are useful when you need one or more of the following:

• Context management: Expose specialized knowledge without overloading the model’s context. When context and latency are limited, you need ways to surface only what’s relevant per step or per agent.
• Distributed development: Let different teams own different capabilities (e.g. skills, sub-agents, specialists) and compose them behind clear boundaries.
• Parallelization: Run specialized workers for subtasks concurrently to reduce latency.
• Structured workflows: Enforce order (e.g. classify then route, or loop until a condition) or role-based handoffs (e.g. sales vs. support) that a single agent would not naturally enforce.

Multi-agent patterns are especially valuable when a single agent has too many tools and chooses poorly, when tasks need deep domain context (long prompts and domain-specific tools), or when you need sequential or state-driven routing (e.g. collect info before escalating, or switch who “owns” the conversation).

​

Patterns supported

The project supports the following multi-agent patterns. Each has a dedicated page with implementation details and examples.

​

Choosing a pattern

At a high level, multi-agent patterns fall into workflow and conversational modes:

• Workflow mode: Pipeline, Routing, Handoffs, Custom Workflow. The flow moves between agents or nodes; each node may interact with the user.
• Conversational mode: Supervisor, Subagents, Skills. Agent decisions happen in a continuous dialogue context; usually only the main agent interacts with the user and returns the final result.

Other patterns (e.g. MsgHub, Agent as Tool, Handoffs, Multi-Agent Debate) can be combined with either mode as needed.

​

Routing vs Supervisor

Both patterns dispatch work to multiple agents, but they differ in how routing decisions are made:

• Routing: A dedicated routing step (often a single LLM call or rule-based logic) classifies the current input and dispatches to one or more specialists. The router itself does not maintain conversation history or perform multi-turn orchestration—it is a preprocessing step. Use when you have clear input categories and want lightweight or deterministic classification, and one request should complete “classify → specialists → merge”.
• Supervisor: The main supervisor agent dynamically decides which specialist to call next (as tools) within an ongoing conversation. The main agent keeps context and can call different specialists across turns to orchestrate complex multi-step flows. Use when you need flexible, conversation-aware orchestration where the LLM decides the next step based on evolving context.

When to choose: Use Routing when input categories are clear and you want a single pass of classification and merge; use Supervisor when you need multi-turn dialogue and the main agent should schedule specialists based on context.

​

Skills vs Subagents / Supervisor

The main difference is whether context is isolated:

• Skills: Skill content (e.g. SKILL.md) is loaded on demand into the main agent’s context via a tool (e.g. read_skill), sharing the same dialogue context as the main agent—no isolation. There is a single process and one context; the agent just pulls in domain text when needed. Use when you want “one agent, many specializations, load on demand” and do not need separate execution or isolated context.
• Subagents / Supervisor: Sub-agents or specialists run in separate invocations or sessions, isolated from the main agent’s (orchestrator or supervisor) dialogue context; each call can have its own system prompt and tool set, and results are aggregated back. Use when you need isolated execution, to avoid context pollution, or to restrict tools/permissions per specialist.

When to choose: Use Skills when you want to load multiple domains on demand in one conversation and are fine with shared context; use Subagents or Supervisor when you need dedicated sub-agents or specialists to run in isolation and then aggregate. Use this as a quick guide; details and tradeoffs are on each pattern’s page. Combining patterns: You can mix them. For example, a supervisor can use Agent as Tool for specialists; a subagent orchestrator can use Skills for on-demand context; a graph can use Handoffs for one part and Routing for another. Choose the pattern that best fits each part of your workflow.

​

Summary

• Use Pipeline for predefined flows (sequential, parallel, loop).
• Use Custom Workflow when you need your own graph with mixed deterministic and agentic steps.
• Use Routing for classify → specialists → synthesize.
• Use MsgHub for group conversation or debate-style message sharing.
• Use Agent as Tool when a parent agent should invoke a sub-agent as a tool.
• Use Skills when one agent should load specialized prompts/content on demand.
• Use Subagents when one orchestrator delegates to many task-style sub-agents.
• Use Supervisor when one agent routes to specialists exposed as one tool each.
• Use Handoffs when the “active” agent changes via tool-driven state in a graph.
• Use Multi-Agent Debate when you want debaters plus a moderator and a clear end condition.

For implementation details, code samples, and example projects, see the linked pages for each pattern.