Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

EventArgumentsDescription
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

EventArgumentsDescription
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