Skip to main content
Requires the websocket extra: pip install pipecat-ai-subagents[websocket]

​
WebSocketProxyClientAgent

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. 
from pipecat_subagents.agents.proxy.websocket.client import WebSocketProxyClientAgent

proxy = WebSocketProxyClientAgent(
    "proxy",
    bus=runner.bus,
    url="ws://remote-server:8765/ws",
    remote_agent_name="worker",
    local_agent_name="voice",
)

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

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

await runner.add_agent(proxy)

​
Configuration

​
name
str
required
Unique name for this agent.
​
bus
AgentBus
required
The AgentBus for inter-agent communication.
​
url
str
required
The WebSocket URL to connect to.
​
remote_agent_name
str
required
Name of the agent on the remote server. Only messages targeted at this agent are forwarded.
​
local_agent_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
Optional[dict[str, str]]
default:"None"
Optional HTTP headers sent with the WebSocket handshake (e.g. for authentication).
​
serializer
Optional[MessageSerializer]
default:"None"
Serializer for bus messages. Defaults to JSONMessageSerializer.

​
Event Handlers

EventArgumentsDescription
on_connected(agent, websocket)Fired when the WebSocket connection is established
on_disconnected(agent, websocket)Fired when the WebSocket connection is closed

​
WebSocketProxyServerAgent

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. 
from pipecat_subagents.agents.proxy.websocket.server import WebSocketProxyServerAgent

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    proxy = WebSocketProxyServerAgent(
        "gateway",
        bus=runner.bus,
        websocket=websocket,
        agent_name="worker",
        remote_agent_name="voice",
    )

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

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

    await runner.add_agent(proxy)

​
Configuration

​
name
str
required
Unique name for this agent.
​
bus
AgentBus
required
The AgentBus for inter-agent communication.
​
websocket
WebSocket
required
An accepted FastAPI/Starlette WebSocket connection.
​
agent_name
str
required
Name of the local agent to route messages to/from. Only messages from this agent are forwarded to the client.
​
remote_agent_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
Optional[MessageSerializer]
default:"None"
Serializer for bus messages. Defaults to JSONMessageSerializer.

​
Event Handlers

EventArgumentsDescription
on_client_connected(agent, websocket)Fired when the WebSocket client connects and the proxy is ready
on_client_disconnected(agent, websocket)Fired when the WebSocket client disconnects