Proxy Agents

Connect agents on different buses with proxy agents.

Overview

Proxy agents connect agents running on different buses. Unlike distributed agents (which all share the same bus), proxy agents bridge two isolated bus instances point-to-point. This is useful when:

• You want to run an LLM agent on a separate server without shared infrastructure
• You need fine-grained control over which messages cross the network
• You’re connecting to a third-party service that hosts agents

Architecture

Each side has its own WorkerRunner and bus. The proxy agents relay messages between the two buses over a WebSocket connection. Like any worker, a proxy gets its bus from the runner when you register it — you never pass bus= to its constructor.

Client side: WebSocketProxyClient

The client connects to a remote server and forwards specific message types:

from pipecat.bus import BusFrameMessage
from pipecat.workers.proxy.websocket import WebSocketProxyClient

proxy = WebSocketProxyClient(
    "proxy",
    url="ws://remote-server:8765/ws",
    local_worker_name="acme",         # Agent on this bus
    remote_worker_name="assistant",   # Agent on remote bus
    forward_messages=(BusFrameMessage,),
)
await runner.add_workers(proxy)

Parameter	Description
url	WebSocket URL of the remote server
local_worker_name	Name of the local agent that exchanges frames with the remote
remote_worker_name	Name of the remote agent to communicate with
forward_messages	Tuple of message types to forward across the connection
headers	Optional HTTP headers (e.g. authentication tokens)

The proxy connects when activated. Activate it when the client connects, by calling activate_worker on the main agent:

@transport.event_handler("on_client_connected")
async def on_client_connected(transport, client):
    await main.activate_worker("proxy")

Server side: WebSocketProxyServer

The server accepts WebSocket connections and creates a proxy for each session:

from fastapi import FastAPI, WebSocket

from pipecat.bus import BusFrameMessage
from pipecat.workers.runner import WorkerRunner
from pipecat.workers.proxy.websocket import WebSocketProxyServer

app = FastAPI()


@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()

    runner = WorkerRunner(handle_sigint=False)

    proxy = WebSocketProxyServer(
        "gateway",
        websocket=websocket,
        worker_name="assistant",        # Agent on this bus
        remote_worker_name="acme",      # Agent on remote bus
        forward_messages=(BusFrameMessage,),
    )

    assistant = build_assistant()  # an LLMWorker named "assistant"

    await runner.add_workers(proxy, assistant)
    await runner.run()

Each WebSocket connection gets its own WorkerRunner, bus, and set of agents. This isolates sessions from each other.

Message filtering

Proxy agents provide security through message filtering:

• Only messages targeted at the configured agent names cross the connection
• Broadcast messages (no target) are not forwarded
• Local-only messages (BusLocalMessage) never cross
• forward_messages controls which message types are allowed

This means internal bus traffic stays local. Only the specific message types you opt into are relayed.

Full example

Client (main.py)

async def run_bot(transport, runner_args):
    runner = WorkerRunner(handle_sigint=runner_args.handle_sigint)

    # ... build the main transport pipeline with a BusBridgeProcessor ...
    main = PipelineWorker(pipeline, name="acme", params=PipelineParams(...))

    proxy = WebSocketProxyClient(
        "proxy",
        url=runner_args.cli_args.remote_url,
        local_worker_name="acme",
        remote_worker_name="assistant",
        forward_messages=(BusFrameMessage,),
    )

    async def on_assistant_ready(_data):
        await main.activate_worker(
            "assistant",
            args=LLMWorkerActivationArgs(
                messages=[{"role": "developer", "content": "Welcome the user."}],
            ),
        )

    await runner.registry.watch("assistant", on_assistant_ready)

    @transport.event_handler("on_client_connected")
    async def on_client_connected(transport, client):
        await main.activate_worker("proxy")

    @transport.event_handler("on_client_disconnected")
    async def on_client_disconnected(transport, client):
        await runner.cancel()

    await runner.add_workers(proxy, main)
    await runner.run()

Server (assistant.py)

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    runner = WorkerRunner(handle_sigint=False)

    proxy = WebSocketProxyServer(
        "gateway",
        websocket=websocket,
        worker_name="assistant",
        remote_worker_name="acme",
        forward_messages=(BusFrameMessage,),
    )

    @proxy.event_handler("on_client_connected")
    async def on_client_connected(proxy, client):
        logger.info("WebSocket client connected")

    @proxy.event_handler("on_client_disconnected")
    async def on_client_disconnected(proxy, client):
        await runner.cancel()

    assistant = AcmeAssistant()  # an LLMWorker named "assistant"
    await runner.add_workers(proxy, assistant)
    await runner.run()

Running

# Terminal 1: Start the LLM server
python assistant.py --port 8765

# Terminal 2: Start the transport client
python main.py --remote-url ws://localhost:8765/ws

Install the WebSocket extra: uv add "pipecat-ai[websocket]"

Proxy agents vs distributed agents

	Proxy Agents (different buses)	Distributed (same bus)
Topology	Point-to-point	Many-to-many
Session isolation	Each connection is isolated	All agents share a channel
Use case	Separate networks, third-party agents	Scaling agents across machines

What’s next

You’ve built a multi-agent system and scaled it across processes, machines, and networks. Here’s where to go from here.

What's Next

Explore Fundamentals and advanced patterns