> ## 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.

# Proxy Agents

> WebSocket proxy agents for distributed deployments

<Note>
  Requires the websocket extra: `uv add "pipecat-ai-subagents[websocket]"`
</Note>

## 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.

```python theme={null}
from pipecat_subagents.agents.proxy.websocket.client import WebSocketProxyClientAgent
```

```python theme={null}
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

<ParamField path="name" type="str" required>
  Unique name for this agent.
</ParamField>

<ParamField path="bus" type="AgentBus" required>
  The [`AgentBus`](/api-reference/pipecat-subagents/bus#agentbus) for
  inter-agent communication.
</ParamField>

<ParamField path="url" type="str" required>
  The WebSocket URL to connect to.
</ParamField>

<ParamField path="remote_agent_name" type="str" required>
  Name of the agent on the remote server. Only messages targeted at this agent
  are forwarded.
</ParamField>

<ParamField path="local_agent_name" type="str" required>
  Name of the local agent that should receive responses. Only inbound messages
  targeted at this agent are accepted.
</ParamField>

<ParamField path="forward_messages" type="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.
</ParamField>

<ParamField path="headers" type="dict[str, str] | None" default="None">
  Optional HTTP headers sent with the WebSocket handshake (e.g. for
  authentication).
</ParamField>

<ParamField path="serializer" type="MessageSerializer | None" default="None">
  Serializer for bus messages. Defaults to
  [`JSONMessageSerializer`](/api-reference/pipecat-subagents/serializers#jsonmessageserializer).
</ParamField>

### 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.

```python theme={null}
from pipecat_subagents.agents.proxy.websocket.server import WebSocketProxyServerAgent
```

```python theme={null}
@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

<ParamField path="name" type="str" required>
  Unique name for this agent.
</ParamField>

<ParamField path="bus" type="AgentBus" required>
  The [`AgentBus`](/api-reference/pipecat-subagents/bus#agentbus) for
  inter-agent communication.
</ParamField>

<ParamField path="websocket" type="WebSocket" required>
  An accepted FastAPI/Starlette WebSocket connection.
</ParamField>

<ParamField path="agent_name" type="str" required>
  Name of the local agent to route messages to/from. Only messages from this
  agent are forwarded to the client.
</ParamField>

<ParamField path="remote_agent_name" type="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.
</ParamField>

<ParamField path="forward_messages" type="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.
</ParamField>

<ParamField path="serializer" type="MessageSerializer | None" default="None">
  Serializer for bus messages. Defaults to
  [`JSONMessageSerializer`](/api-reference/pipecat-subagents/serializers#jsonmessageserializer).
</ParamField>

### 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                     |