协议消息 · Cloudflare Agents 文档

客户端连接时，Agent 会向其发送 JSON 协议帧：身份 (cf_agent_identity)、状态 (cf_agent_state) 和 MCP 服务器 (cf_agent_mcp_servers)。这些帧会在状态或 MCP 服务器发生变化时再次发送。useAgent 和 AgentClient 会为你读取这些帧。

某些客户端（例如 IoT 设备或 MQTT 客户端）无法处理 JSON 文本帧。对这些客户端，从 shouldSendProtocolMessages() 返回 false 即可关闭这些帧：

import { Agent } from "agents";

export class DeviceAgent extends Agent {
	shouldSendProtocolMessages(_connection, ctx) {
		return ctx.request.headers.get("Sec-WebSocket-Protocol") !== "mqtt";
	}
}

import { Agent, type Connection, type ConnectionContext } from "agents";

export class DeviceAgent extends Agent<Env> {
	shouldSendProtocolMessages(_connection: Connection, ctx: ConnectionContext) {
		return ctx.request.headers.get("Sec-WebSocket-Protocol") !== "mqtt";
	}
}

连接被接受时会做一次此判断，并且在休眠期间仍会保留。未启用协议帧的连接仍可发送和接收你自己的消息、接收 this.broadcast()，并调用 @callable() 方法。isConnectionProtocolEnabled(connection) 会返回当前设置。

此功能使用 WebSockets 功能模块的 protocol 选项。更多信息请参阅按连接控制协议。

只读连接

允许连接接收状态，但不允许更改状态。