Proxy Agents

Requires the websocket extra: uv add "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

str

required

Unique name for this agent.

AgentBus

required

The AgentBus for inter-agent communication.

str

required

The WebSocket URL to connect to.

str

required

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

str

required

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

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.

dict[str, str] | None

default:"None"

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

MessageSerializer | None

default:"None"

Serializer for bus messages. Defaults to JSONMessageSerializer.

Event Handlers

Event	Arguments	Description
`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

str

required

Unique name for this agent.

AgentBus

required

The AgentBus for inter-agent communication.

WebSocket

required

An accepted FastAPI/Starlette WebSocket connection.

str

required

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

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.

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.

MessageSerializer | None

default:"None"

Serializer for bus messages. Defaults to JSONMessageSerializer.

Event Handlers

Event	Arguments	Description
`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

Pipecat Server

Pipecat Subagents

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

WebSocketProxyClientAgent

Configuration

Event Handlers

WebSocketProxyServerAgent

Configuration

Event Handlers

​WebSocketProxyClientAgent

​Configuration

​Event Handlers

​WebSocketProxyServerAgent

​Configuration

​Event Handlers

WebSocketProxyClientAgent

Configuration

Event Handlers

WebSocketProxyServerAgent

Configuration

Event Handlers