WebSocket 通信系统通过 Socket.IO 实现，支持 React 前端和 FastAPI 后端之间的实时双向通信。它负责在 AI Agent 执行会话期间处理 Agent 行动、观察和状态更新的事件流。
有关通用的 API 通信模式，请参阅 服务器 API 和通信。
OpenHands 使用 Socket.IO 实现 React 前端和 FastAPI 后端之间的实时 WebSocket 通信。该系统通过与会话绑定的持久连接来流式传输 Agent 事件、用户操作和状态更新。
来源
WsClientProvider React Context 管理 Socket.IO 连接并提供与后端的实时通信。
来源
WsClientProvider 通过特定于会话的连接以及事件重放功能管理 Socket.IO 连接。
来源
Provider 使用类型守卫来对不同事件类型进行分类和处理
| 类型守卫函数 | 目的 | 触发的操作 |
|---|---|---|
isOpenHandsEvent | 验证基本事件结构 | 基本事件处理 |
isOpenHandsAction / isOpenHandsObservation | 对事件进行分类 | 添加到 parsedEvents 数组 |
isFileWriteAction / isFileEditAction | 检测文件操作 | 使 React Query 缓存失效 |
isCommandAction | 检测命令执行 | 使文件更改缓存失效 |
isUserMessage / isAssistantMessage | 识别消息事件 | 移除乐观更新 |
isErrorObservation | 处理错误事件 | 触发错误跟踪 |
来源
WebSocket 客户端与 React Query 集成，以便在相关事件发生时使缓存的数据失效
来源
WsClientProvider 通过 WsClientProviderStatus 枚举和 React state 来管理连接状态
来源
客户端遵循特定的模式来发送用户操作和接收 Agent 事件
来源
WebSocket 通信使用特定的 Socket.IO 事件名称来表示不同的消息方向
| 方向 | 事件名称 | 目的 | 实现 |
|---|---|---|---|
| 客户端 → 服务器 | oh_user_action | 用户消息和操作 | socket.emit('oh_user_action', event) |
| 服务器 → 客户端 | oh_event | Agent 操作、观察、状态 | handleMessage(event) 回调 |
| 连接事件 | connect, disconnect, connect_error | 连接生命周期 | 内置 Socket.IO 事件 |
来源
客户端使用类型守卫的层次结构来处理传入事件
来源
来源
WebSocket 系统通过多个检测点实现全面的错误处理
来源
该系统通过事件观察来检测和处理 Agent 级别的错误
来源
客户端实现了具有事件重放功能的有状态重连
来源
WebSocket 连接状态在 UI 中可视化，为用户提供当前通信状态的反馈。
AgentStatusBar 组件显示连接状态，使用
来源
状态指示器根据连接状态和代理状态使用颜色和文本
来源
对于重要的状态更改，即使标签页未处于焦点状态，系统也会提供通知。
来源
OpenHands 中的 WebSocket 通信系统提供了前端和后端之间实时双向通信的强大机制。它支持有效 AI 代理交互所需的响应式、交互式体验，并能妥善处理连接、断开连接、错误和用户反馈。