Understanding the Bus Bridge

How BusBridgeProcessor routes frames between the transport pipeline and the agent bus.

What is the bus bridge?

The BusBridgeProcessor is a pipeline processor that connects a transport pipeline to the agent bus. It sits in the main agent’s pipeline where an LLM would normally go, routing frames to whichever agent is currently active.

Without the bridge, your main agent’s pipeline would look like:

transport.input → STT → context_agg → LLM → TTS → transport.output

With the bridge, the LLM is replaced:

transport.input → STT → context_agg → BusBridge → TTS → transport.output

The bridge sends outgoing frames (like transcribed text) to the bus, and receives incoming frames (like LLM-generated text) from the active agent.

The examples above show a voice pipeline, but BusBridgeProcessor can be used in any type of pipeline. It works with any frames, not just audio.

How it works

The bridge operates in two directions:

Outgoing (pipeline to bus): Frames flowing downstream through the pipeline are captured by the bridge and published as BusFrameMessage on the bus. The active agent receives these frames.

Incoming (bus to pipeline): When an active agent sends frames back through the bus, the bridge pushes them into the pipeline. These frames continue downstream to TTS and the transport output.

Certain frames are never sent across the bus:

• Lifecycle frames (StartFrame, EndFrame, CancelFrame, StopFrame)
• Transport-urgent frames (these pass through the bridge locally)

Basic usage

The main agent is a PipelineWorker wrapping a pipeline that contains a BusBridgeProcessor. The bridge gets its bus from runner.bus:

from pipecat.bus import BusBridgeProcessor
from pipecat.pipeline.pipeline import Pipeline
from pipecat.workers.runner import WorkerRunner
from pipecat.pipeline.worker import PipelineParams, PipelineWorker

MAIN_NAME = "acme"

runner = WorkerRunner()

bridge = BusBridgeProcessor(
    bus=runner.bus,
    worker_name=MAIN_NAME,
    name=f"{MAIN_NAME}::BusBridge",
)

pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    bridge,
    tts,
    transport.output(),
    context_aggregator.assistant(),
])

main = PipelineWorker(pipeline, name=MAIN_NAME, params=PipelineParams())

await runner.add_workers(main)

The worker gets its bus from the runner when added with runner.add_workers(). You build the BusBridgeProcessor ahead of time with runner.bus and place it in the pipeline where an LLM would normally go.

Named bridges

When you have multiple bridges in a system, you can name them to control which agents receive frames from which bridge. This is useful with parallel pipelines where each branch has its own bridge (for example, separate audio and video branches):

voice_bridge = BusBridgeProcessor(
    bus=runner.bus,
    worker_name=MAIN_NAME,
    name=f"{MAIN_NAME}::VoiceBridge",
    bridge="voice",
)

Agents control which bridges they listen to through the bridged argument when they are created:

# Receives frames from all bridges
all_bridges_agent = MyLLMWorker("all", llm=llm, bridged=())

# Receives frames only from the "voice" bridge
voice_only_agent = MyLLMWorker("voice-only", llm=llm, bridged=("voice",))

The bridged agent side

When an agent sets bridged=() (or a tuple of bridge names), the framework automatically wraps its pipeline with edge processors that handle bus frame conversion. An LLM agent subclasses LLMWorker and passes its own LLM service:

from pipecat.services.openai.llm import OpenAILLMService
from pipecat.workers.llm import LLMWorker, tool

class MyLLMWorker(LLMWorker):
    @tool
    async def my_function(self, params, arg: str):
        ...

llm = OpenAILLMService(api_key="...")
agent = MyLLMWorker("greeter", llm=llm, bridged=())

A worker never takes a bus= argument. It receives its bus from the runner when you register it with runner.add_workers().

The resulting pipeline looks like:

BusEdgeProcessor (upstream) → [your pipeline] → BusEdgeProcessor (downstream)

The upstream edge processor receives BusFrameMessage from the bus and converts them back to regular Pipecat frames. The downstream edge processor captures output frames and sends them back through the bus. You don’t need to manage this — it happens automatically when bridged is set.