Skip to main content

​
What you’ll learn

This guide teaches you how to build multi-agent AI systems with Pipecat Subagents. By the end, you’ll understand how to decompose complex applications into specialized agents that coordinate through a shared message bus.
Prerequisites: Familiarity with Pipecat’s core concepts (pipelines, processors, transports) is recommended. This guide builds on that foundation.

​
Why Pipecat Subagents?

Pipecat is a powerful real-time framework for building voice and multimodal AI applications. A single pipeline covers many use cases, but as your application grows you may need multiple agents working together. Pipecat Subagents extends Pipecat with distributed multi-agent coordination where each agent runs its own pipeline. Some things you can build:
  • A customer support system where each specialist runs its own LLM with dedicated tools and context, transferring seamlessly between each other.
  • A video game where multiple LLMs independently control different characters, environments, or game mechanics.
  • A stock analysis app that dispatches parallel research to multiple worker agents and synthesizes their findings.
  • A video or image analysis pipeline where worker agents process media using Pipecat processors and stream updates back.
  • An IoT system where remote devices run agents on specialized hardware, reporting status and receiving commands.
If a single Pipecat pipeline covers your use case, you don’t need subagents. When you outgrow it, the transition is straightforward: your existing pipeline becomes one agent among many.

​
Architecture of a voice agent

One of the most common use cases is a voice agent, so let’s use it to illustrate the architecture. In this example, we have three agents: a main agent that owns the transport and two voice agents, each running its own LLM with different instructions and tools.
Subagents architecture
  • The AgentRunner manages the lifecycle of all agents and owns the bus
  • The main agent owns the transport and places a BusBridgeProcessor in its pipeline to route frames to other agents through the bus
  • Voice agents are bridged to the bus — they receive frames from the bridge and send responses back through it
  • Only one agent is active at a time (per bridge) — the active agent gets the frames
  • Worker agents receive tasks, process them, and return results
This is just one topology. Any agent can own a transport, and agents can coordinate purely through tasks and bus messages without a bridge at all.

​
What’s ahead

Each section builds on the previous one:
1

Agents and Runner

Agent types, the AgentRunner, and building your first single-agent system.
2

Agent Handoff

Activation, deactivation, and seamless control transfer between agents.
3

Task Coordination

Dispatching work to multiple agents in parallel and collecting results.

Let's start

Begin with agents and the runner