feature request: option to turn off agent protocol messages on the websocket

[genmon]

Text frames such as CF_AGENT_IDENTITY, CF_AGENT_STATE and CF_AGENT_MCP_SERVERS are sent by default, and don't play nicely with binary-only clients, e.g. hardware devices with MQTT clients.

I would like to continue to use the Agents SDK for the DO, so would ideally like an option to opt out of these text frames for tagged connections only (set via a header on the request or perhaps a query string).

[genmon]

cc @threepointone because you've seen what I'm hacking on -- lmk if I can add more context

[threepointone]

would you be ok turning it off at the agent level? something like:

static options = {
disableProtocolMessages: true
}

[whoiskatrin]

cc @genmon

[threepointone]

Yeah I actually don't think this should be static options anymore, but query string is also tricky because it can clash with stuff. Lemme think this through

[genmon]

Thinking it though, perhaps I'm asking for two separate things here:

1. One DO that treats two different connections types very differently. I'm currently using tagged connections to separate mqtt (binary) and web client (for real-time monitoring view) and basing that on the query string. But the "standards" way to do this would be websocket subprotocol (request headers), mqtt-over-ws actually does require this. PERHAPS the response here is that I am doing something which violates the principle of DO simplicity, and it's on me to re-architect into 2 DOs that talk to each other!

2. Being able to turn off some features (e.g. web client sync, MCP) at an agent level. Currently I've reverted to partyserver... but this means that I don't have client RPC or easy queues. More than that, I'm nervous about relying on partyserver because it feels like it could easily disappear in the future (get merged into agents). So this is the part of my request that still stands.

[threepointone]

/bonk what do you think?

[ask-bonk]

This is a thorough and well-articulated issue. Here's my analysis:

Assessment

The issue author (@genmon) is right that the current protocol messages (CF_AGENT_IDENTITY, CF_AGENT_STATE, CF_AGENT_MCP_SERVERS) are problematic for binary-only clients. These are unconditionally sent as JSON text frames on every connection (except identity, which respects sendIdentityOnConnect), and there's no way to suppress them.

Looking at the code, the situation is:

• CF_AGENT_IDENTITY — already has an opt-out via static options = { sendIdentityOnConnect: false } (packages/agents/src/index.ts:918)
• CF_AGENT_STATE — always sent on connect if state exists (packages/agents/src/index.ts:928-935), and broadcast to all connections on every state change (packages/agents/src/index.ts:1054-1060)
• CF_AGENT_MCP_SERVERS — always sent on connect (packages/agents/src/index.ts:937-942) and broadcast on every MCP state change (packages/agents/src/index.ts:3551-3558)

On the design question

I agree with @threepointone's instinct that static options alone isn't the right lever here, and that the issue is really two things as @genmon clarified:

For (2) — agent-level feature opt-out: A static options approach like { syncState: false, mcp: false } makes sense. This would suppress CF_AGENT_STATE broadcasts and CF_AGENT_MCP_SERVERS messages entirely. It's clean, simple, and covers the "I just want a DO with RPC and queues, not the full protocol" use case. This is the straightforward part.

For (1) — per-connection protocol control: This is harder and more interesting. The existing pattern of shouldConnectionBeReadonly(connection, ctx) at packages/agents/src/index.ts:1253-1258 is a good model — it's a hook that receives the connection and request context, letting you decide per-connection behavior. A similar hook like shouldSendProtocolMessages(connection, ctx) (or more granularly, getConnectionCapabilities(connection, ctx)) would let you inspect the request's subprotocol, query string, or headers to decide whether to send text-frame protocol messages.

The broadcast calls in _setStateInternal and broadcastMcpServers would also need to respect this — they'd need to filter out connections that opted out of protocol messages, similar to how broadcasts already exclude the source connection.

What I'd recommend

A combined approach:

1. Agent-level: Add static options = { sendStateOnConnect: true, broadcastState: true, sendMcpOnConnect: true } (all defaulting to true for backward compatibility). This covers the simple "I don't use these features" case.

2. Connection-level: Add a shouldSendProtocolMessages(connection, ctx): boolean hook (defaulting to true). This covers the "mixed connection types" case without needing query string conventions that could clash.

This follows the existing SDK patterns, keeps backward compat, and addresses both needs without forcing users to split into multiple DOs — which would be significantly more complex for what is fundamentally a connection-filtering problem.

The WebSocket subprotocol idea @genmon mentioned is elegant but probably unnecessary as a built-in mechanism — users can just check ctx.request.headers.get("Sec-WebSocket-Protocol") inside the hook themselves.

github run

[threepointone]

/bonk I think option 2 is more appealing/powerful. Feel free to make a PR, with tests. Think of what the tradeoffs and edge cases are and report them to me. We don't need it to be able to be dynamically set, so it should be just shouldSendProtocolMessages and maybe a predicate helper to check what kind of connection it is atm (just like isConnectionReadOnly)

[ask-bonk]

Bonk workflow was cancelled.

View workflow run

[ask-bonk]

Bonk workflow was cancelled.

View workflow run

[threepointone]

/bonk I think option 2 is more appealing/powerful. Feel free to make a PR, with tests (It failed a couple of times because the timeout wasn't high enough). Think of what the tradeoffs and edge cases are and report them to me. We don't need it to be able to be dynamically set, so it should be just shouldSendProtocolMessages and maybe a predicate helper to check what kind of connection it is atm (just like isConnectionReadOnly)

[ask-bonk]

Created PR #892

github run

[threepointone]

@genmon would you like to try npm i https://pkg.pr.new/cloudflare/agents@892 and lemme know if it works for you? I want to let it marinate for a couple of days before landing this, but you can test it out today with the preview build.