Proxy Agents

WebSocket proxy agents for distributed deployments

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

WebSocketProxyClient

Forwards bus messages to a remote agent over WebSocket. Connects to a WebSocket URL and forwards messages between a local agent and a remote agent.

The proxy does not take a bus in its constructor. It receives the shared bus when registered with the runner via add_workers().

from pipecat.workers.proxy.websocket.client import WebSocketProxyClient

proxy = WebSocketProxyClient(
    "proxy",
    url="ws://remote-server:8765/ws",
    remote_worker_name="worker",
    local_worker_name="voice",
)

@proxy.event_handler("on_connected")
async def on_connected(worker, websocket):
    logger.info("Connected to remote server")

@proxy.event_handler("on_disconnected")
async def on_disconnected(worker, websocket):
    logger.info("Disconnected from remote server")

await runner.add_workers(proxy)

Configuration

name · str · required

Unique name for this agent.

url · str · required

The WebSocket URL to connect to.

remote_worker_name · str · required

Name of the agent on the remote server. Only messages targeted at this agent are forwarded.

local_worker_name · str · required

Name of the local agent that should receive responses. Only inbound messages targeted at this agent are accepted.

forward_messages · tuple[type[BusMessage], ...] · default: "()"

Additional message types to forward from the local agent (e.g. (BusFrameMessage,) for frame routing). These are forwarded based on source agent name only, regardless of target.

headers · dict[str, str] | None · default: "None"

Optional HTTP headers sent with the WebSocket handshake (e.g. for authentication).

serializer · MessageSerializer | None · default: "None"

Serializer for bus messages. Defaults to JSONMessageSerializer.

active · bool · default: "False"

Whether the agent starts active. Defaults to False because on_activated opens the WebSocket connection, which is usually a deliberate action triggered by an upstream event (e.g. the local client connecting). Pass True to connect as soon as the agent starts.

Event Handlers

Event	Arguments	Description
on_connected	(worker, websocket)	Fired when the WebSocket connection is established
on_disconnected	(worker, websocket)	Fired when the WebSocket connection is closed

WebSocketProxyServer

Receives bus messages from a remote client over WebSocket. Accepts a FastAPI/Starlette WebSocket connection and forwards messages between the remote client and a local agent.

Like the client, the server does not take a bus in its constructor; it receives the shared bus when registered with the runner via add_workers().

from pipecat.workers.proxy.websocket.server import WebSocketProxyServer

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    proxy = WebSocketProxyServer(
        "gateway",
        websocket=websocket,
        worker_name="worker",
        remote_worker_name="voice",
    )

    @proxy.event_handler("on_client_connected")
    async def on_client_connected(worker, websocket):
        logger.info("Client connected")

    @proxy.event_handler("on_client_disconnected")
    async def on_client_disconnected(worker, websocket):
        logger.info("Client disconnected")

    await runner.add_workers(proxy)

Configuration

name · str · required

Unique name for this agent.

websocket · WebSocket · required

An accepted FastAPI/Starlette WebSocket connection.

worker_name · str · required

Name of the local agent to route messages to/from. Only messages from this agent are forwarded to the client.

remote_worker_name · str · required

Name of the agent on the remote client. Only outbound messages targeted at this agent are sent. Only inbound messages targeted at the local agent are accepted.

forward_messages · tuple[type[BusMessage], ...] · default: "()"

Additional message types to forward from the local agent (e.g. (BusFrameMessage,) for frame routing). These are forwarded based on source agent name only, regardless of target.

serializer · MessageSerializer | None · default: "None"

Serializer for bus messages. Defaults to JSONMessageSerializer.

Event Handlers

Event	Arguments	Description
on_client_connected	(worker, websocket)	Fired when the WebSocket client connects and the proxy is ready
on_client_disconnected	(worker, websocket)	Fired when the WebSocket client disconnects