Pipecat Subagents is a distributed multi-agent framework for Pipecat. Each agent runs its own Pipecat pipeline and communicates with other agents through a shared message bus, enabling you to decompose complex systems into specialized, coordinating agents that can run locally or across machines.
Whether local or distributed, the programming model is the same: create an AgentRunner, connect it to the bus, and add agents.
Pipecat is a powerful real-time framework for building voice and multimodal AI applications. Pipecat Subagents extends it with distributed multi-agent coordination where each agent runs its own Pipecat 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.
- Per-agent pipeline: every agent runs its own Pipecat pipeline with access to all services, processors, and transports (e.g. different LLMs, local models, image analysis, custom processors).
- Agent handoff: transfer control between agents mid-conversation, seamlessly switching context and capabilities.
- Task coordination: dispatch work to specialized worker agents in parallel, track progress with timeouts and cancellation, and stream results back.
- Distributed agents: run agents across machines, scaling each independently. Agents communicate via a shared bus that works the same locally or over the network.
- Mixed agent types: combine free-form LLM agents with structured Pipecat Flows agents or wrap third-party frameworks as subagents.
- Agent lifecycle: activation, deactivation, error propagation, and graceful shutdown across a tree of agents.
uv add pipecat-ai-subagents
# or: pip install pipecat-ai-subagentsRequires Python 3.11+ and Pipecat.
See the examples directory for complete, runnable demos.
Clowder (a group of cats) is a real-time observability tool for Pipecat Subagents. It shows runners, agents, tasks, and bus messages in a web UI, whether local or distributed.
Add a ClowderAgent to any runner:
from pipecat_subagents.clowder import ClowderAgent
clowder = ClowderAgent("clowder", bus=runner.bus, port=7070)
await runner.add_agent(clowder)Or use a setup file to add Clowder without modifying your application code. Create a file (e.g. clowder_setup.py):
from pipecat_subagents.clowder import ClowderAgent
from pipecat_subagents.runner import AgentRunner
async def setup_runner(runner: AgentRunner):
clowder = ClowderAgent(bus=runner.bus)
await runner.add_agent(clowder)Then set the environment variable:
export PIPECAT_SUBAGENTS_SETUP_FILES=/path/to/clowder_setup.pycd clowder-ui
npm install
npm run devOpen http://localhost:5173 and click Connect. The UI shows agents grouped by runner, tasks with live duration, and a filterable bus message stream. Connect at any time; all messages are buffered.
We welcome contributions from the community! Whether you're fixing bugs, improving documentation, or adding new features, here's how you can help:
- Found a bug? Open an issue
- Have a feature idea? Start a discussion
- Documentation improvements? Docs PRs are always welcome
Before submitting a pull request, please check existing issues and PRs to avoid duplicates.
We aim to review all contributions promptly and provide constructive feedback to help get your changes merged.