目录

1. 引言
2. WebSocket协议优势
3. 连接握手过程
4. 消息帧格式
5. 客户端实现
6. 服务端集成
7. 会话状态管理
8. 异常断开处理
9. 与其他协议对比

引言

WebSocket协议作为一种全双工通信通道，在实时交互场景中展现出显著优势。本文档详细阐述了在FastMCP框架中如何实现WebSocket支持，包括客户端与服务端的集成方式、连接管理机制以及消息处理流程。通过分析代码实现，展示了WebSocket如何为AI代理等需要持续双向通信的应用提供低延迟的解决方案。

WebSocket协议优势

WebSocket协议通过建立持久化的全双工连接，实现了客户端与服务端之间的实时双向通信。相较于传统的HTTP请求-响应模式，WebSocket避免了频繁的连接建立和断开开销，显著降低了通信延迟。这种特性特别适用于需要持续数据交换的AI代理场景，如实时对话系统、流式数据处理和即时通知服务。在FastMCP框架中，WebSocket被用作主要的传输协议之一，支持JSON-RPC消息的高效传输。

连接握手过程

WebSocket连接的建立始于标准的HTTP升级请求。客户端向服务端发起连接请求，要求将HTTP连接升级为WebSocket协议，并指定"mcp"子协议。服务端验证请求后，返回101状态码确认协议切换，完成握手过程。在FastMCP实现中，websocket_client函数负责客户端的连接建立，使用websockets.asyncio.client.connect方法连接指定URL并请求"mcp"子协议。服务端则通过websocket_server函数作为ASGI应用处理连接请求，调用WebSocket.accept方法确认连接并指定"mcp"子协议。

本节来源

• websocket.py
• websocket.py

消息帧格式

WebSocket连接建立后，通信双方通过文本消息帧交换数据。在FastMCP框架中，所有消息都采用JSON-RPC 2.0格式进行编码。消息体包含方法调用、通知或响应等信息，通过JSONRPCMessage类型进行建模。每个传输的消息都被封装在SessionMessage对象中，该对象包含JSONRPCMessage和可选的传输特定元数据。消息在发送前被序列化为JSON字符串，接收后通过model_validate_json方法进行反序列化和验证。这种结构化的消息格式确保了通信的可靠性和可扩展性。

图源

• types.py
• message.py

客户端实现

客户端通过websocket_client上下文管理器建立和管理WebSocket连接。该函数接受服务器URL作为参数，创建内存中的读写流用于消息交换。内部实现包含两个协程：ws_reader负责从WebSocket读取文本消息，解析为JSONRPCMessage对象，并通过读流传递给应用层；ws_writer则从写流读取SessionMessage对象，序列化为JSON字符串后发送到服务器。异常处理机制确保当消息验证失败时，相应的ValidationError会被发送到读流，供调用方处理。这种设计实现了通信逻辑与业务逻辑的解耦，提供了简洁的API接口。

本节来源

• websocket.py

服务端集成

服务端通过websocket_server ASGI应用处理WebSocket连接。该函数符合ASGI规范，接收scope、receive和send参数，创建WebSocket实例并接受连接。与客户端类似，服务端也使用内存流进行消息交换，ws_reader协程负责解析客户端消息并验证，ws_writer协程将服务器消息发送回客户端。异常处理机制包括捕获anyio.ClosedResourceError，在连接关闭时优雅地清理资源。这种实现方式使得FastMCP服务器能够无缝集成到Starlette等ASGI框架中，由Hypercorn等服务器运行。

本节来源

• websocket.py

会话状态管理

WebSocket连接的会话状态通过内存对象流进行管理。客户端和服务端都创建了成对的MemoryObjectSendStream和MemoryObjectReceiveStream，分别用于发送和接收消息。这些流在连接生命周期内保持打开状态，确保消息的有序传递。anyio.create_task_group用于管理读写协程的生命周期，当连接结束时，任务组被取消，所有相关资源被释放。这种基于流的状态管理机制支持高并发连接，每个连接都有独立的消息通道，避免了状态混淆。

图源

• websocket.py
• websocket.py

异常断开处理

WebSocket连接的异常断开通过异常处理机制进行管理。在服务端实现中，ws_reader和ws_writer协程都包含对anyio.ClosedResourceError的捕获，当连接意外关闭时，会尝试调用websocket.close()进行清理。客户端实现中，任务组的取消作用域确保在连接结束时所有协程被正确终止。消息验证失败时，ValidationError会被封装并发送到读流，供应用层决定如何处理。这种分层的异常处理策略确保了连接的稳定性和系统的健壮性。

本节来源

• websocket.py
• websocket.py

与其他协议对比

相较于SSE（Server-Sent Events）和传统HTTP轮询，WebSocket协议在实时通信场景中具有明显优势。SSE仅支持服务器到客户端的单向通信，而WebSocket提供真正的全双工通道。与HTTP轮询相比，WebSocket避免了频繁的连接开销和延迟，实现了更低的通信延迟。在FastMCP框架中，WebSocket与SSE等其他传输方式并存，开发者可根据具体需求选择合适的协议。对于需要持续双向交互的AI代理应用，WebSocket的低延迟特性使其成为首选方案。