---
title: "Choose the transport that the feature · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/live-connections/choose-transport
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Choose the transport that the feature needs

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Live connections](https://agentwranglers.se/playbook/api-design/live-connections.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: API-69
- Level: Recommended
- Chapter: [Live connections](https://agentwranglers.se/playbook/api-design/live-connections)
- Rule: Poll when a delay of 30 seconds or more is fine. Use server-sent events when only the server sends. Use WebSockets only when the client also sends a stream of messages.
- How: Polling is a plain GET, so caching, rate limits and logs work as for any request. Server-sent events are one long HTTP answer that the browser reconnects and resumes on its own. Their format is in [stream in a standard format](https://agentwranglers.se/playbook/api-design/requests-and-responses/streamed-responses). A WebSocket is a separate protocol with its own framing, so every limit and check must be built again. Choose it for chat, shared editing or games, where the client sends many small messages. Write the choice and its reason in the contract for each live feature.
- Check: Each live endpoint in the contract names its transport and the reason. Each WebSocket endpoint lists at least one message type the client sends after it connects.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
const events = new EventSource('/v1/orders/events');
events.addEventListener('order.shipped', event => {
  const order = JSON.parse(event.data);
  showShipped(order.orderId);
});
```

### Python example

```python
import json
from starlette.responses import StreamingResponse

async def order_events(request):
    async def stream():
        async for event in subscribe(request.user.shop_id):
            yield f"id: {event.id}\nevent: {event.type}\ndata: {json.dumps(event.data)}\n\n"
    return StreamingResponse(stream(), media_type="text/event-stream")
```

## Sources

- [WHATWG HTML server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html)
- [RFC 6455 The WebSocket Protocol](https://www.rfc-editor.org/rfc/rfc6455)

## Related rules

- [Stream in a standard format and describe each item](https://agentwranglers.se/playbook/api-design/requests-and-responses/streamed-responses) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/api-design/live-connections/choose-transport">Agent Wranglers API design playbook</a>`. In code you write, add a comment next to it with the same link.

- Next: [Check access when the connection opens and while it lasts](https://agentwranglers.se/playbook/api-design/live-connections/connection-access)
- [Live connections](https://agentwranglers.se/playbook/api-design/live-connections)