client

WebSocket client proxy that forwards bus messages to a remote server.

class pipecat.workers.proxy.websocket.client.WebSocketProxyClient(name: str, *, url: str, remote_worker_name: str, local_worker_name: str, forward_messages: tuple[type[BusMessage], ...] = (), headers: dict[str, str] | None = None, serializer: MessageSerializer | None = None, active: bool = False)

Bases: BaseWorker

Forwards bus messages to a remote worker over WebSocket.

Connects to a WebSocket URL and forwards messages between a local worker and a remote worker. Only messages targeted at the remote worker are sent. Only messages targeted at the local worker are accepted.

Event handlers available:

• on_connected: Fired when the WebSocket connection is established.

• on_disconnected: Fired when the WebSocket connection is closed.

Example:

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)

__init__(name: str, *, url: str, remote_worker_name: str, local_worker_name: str, forward_messages: tuple[type[BusMessage], ...] = (), headers: dict[str, str] | None = None, serializer: MessageSerializer | None = None, active: bool = False)

Initialize the WebSocketProxyClient.

Parameters:

• name – Unique name for this worker.

• url – The WebSocket URL to connect to.

• remote_worker_name – Name of the worker on the remote server. Only messages targeted at this worker are forwarded.

• local_worker_name – Name of the local worker that should receive responses. Only inbound messages targeted at this worker are accepted.

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

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

• serializer – Serializer for bus messages. Defaults to JSONMessageSerializer.

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

async on_activated(args: dict | None) → None

Connect to the remote WebSocket server.

async stop() → None

Cancel the receive loop and close the WebSocket connection.

async on_bus_message(message: BusMessage) → None

Forward messages targeted at the remote worker.

Parameters:

message – The bus message to process.