一、为什么需要实时可见：AI 不再是黑箱
企业级 AI 应用面临的最大信任障碍不是模型能力不足，而是 决策过程的不可见性。当用户问"为什么 AI 给出了这个答案？"时，传统的请求-响应 API 无法提供中间过程——你只能看到输入和输出，中间发生了什么无人知晓。这在合规要求严格的行业（金融、医疗、法律）是不可接受的。EIOS 的 WebSocket 实时推送机制正是为解决这一问题而生。通过 wss://api.eios.isoftbao.com/v1/ws/agent-execution 端点，开发者可以在 Agent 执行过程中接收到 结构化的实时事件流，涵盖：推理步骤（Reasoning Step）、工具调用（Tool Call）、工具返回（Tool Result）、知识库检索（RAG Retrieval）、子 Agent 委托（Sub-Agent Delegation）和最终回复（Final Response）。每个事件都带有精确的毫秒级时间戳、唯一的执行 ID 和父子关系引用，可以重建完整的执行因果链。对于终端用户，这意味着可以在 UI 中展示类似"AI 正在检索您的合同模板..."、"AI 正在分析第 3 条款..."的实时状态提示，将等待焦虑转化为对 AI 工作过程的信任感。
二、WebSocket 协议设计：消息格式与事件类型
EIOS WebSocket 协议建立在 JSON-RPC 2.0 风格的请求-事件模型之上。客户端首先发送 execution.start 方法发起 Agent 执行：
{
"jsonrpc": "2.0",
"id": 1,
"method": "execution.start",
"params": {
"agent_id": "legal-contract-reviewer",
"input": { "contract_text": "..." },
"options": { "stream_reasoning": true, "stream_tool_calls": true }
}
}服务端随后推送一系列事件。核心事件类型包括：execution.status（状态变更：initializing、running、waiting_for_tool、completed、failed）、reasoning.step（Chain-of-Thought 推理片段）、tool.call（工具调用详情，含工具名、参数、调用 ID）、tool.result（工具返回结果，含成功/失败状态和耗时）、knowledge.retrieval（知识库检索结果，含来源文档 ID、相似度分数和片段内容）、subagent.delegate（子 Agent 委托信息）、completion.chunk（最终回复的增量 Token）、execution.error（错误事件，含错误码和可恢复性建议）。所有事件共享 execution_id 和 timestamp 字段，客户端可以按执行 ID 聚合事件，按时间戳排序展示。协议的向后兼容性通过事件版本的 version 字段保证——新增字段不会破坏旧客户端的解析。
三、前端集成：构建实时 Agent 可视化面板
消费 WebSocket 事件流并构建引人入胜的 UI 是开发者体验的关键。EIOS JavaScript SDK 提供了 AgentExecutionSocket 类，封装了 WebSocket 生命周期管理：
import { AgentExecutionSocket } from '@eios/sdk/ws';
const socket = new AgentExecutionSocket({ apiKey, agentId });
socket.on('reasoning.step', (event) => {
// 在 UI 中追加推理步骤卡片
appendStepCard({ type: 'thinking', content: event.content, ts: event.timestamp });
});
socket.on('tool.call', (event) => {
// 展示工具调用动画——如"搜索中..."加载状态
showToolCallIndicator(event.tool_name, event.params);
});
socket.on('tool.result', (event) => {
// 更新工具调用结果为完成状态，展示耗时和结果摘要
updateToolResult(event.call_id, event.result, event.duration_ms);
});
await socket.execute({ input: userQuery });SDK 还提供了 自动重连（指数退避，最多重试 5 次）、心跳保活（每 30 秒发送 ping，60 秒无响应视为断连）、消息排序（基于时间戳和序列号确保事件按发生时间展示）和 React Hook 绑定（useAgentExecution，自动管理状态数组和 UI 更新）。对于需要 长时间运行的 Agent（如批量文档审查，可能持续数十分钟），SDK 支持 断线续传——客户端重连后提供上次接收的最后一个事件序列号，服务端从该点之后重新推送事件，确保不丢失任何中间状态。这种机制对于移动端网络切换（WiFi 到蜂窝网络）场景尤为重要。
四、性能优化：高并发下的实时推送架构
支撑成千上万并发 WebSocket 连接需要精心设计的后端架构。EIOS 的实时推送层基于 NestJS + Socket.IO（WebSocket 引擎） + Redis Pub/Sub（跨进程广播） 架构。每个 EIOS 服务实例管理自己的 WebSocket 连接池（单进程可承载 10,000+ 并发连接），当一个 Agent 的执行引擎产生事件时，事件通过 Redis Pub/Sub 广播至所有服务实例，由拥有该连接的服务实例负责推送给客户端。这种架构实现了 水平扩展——增加服务实例即可线性提升并发连接上限。消息序列化采用 MessagePack 替代 JSON，将事件体压缩约 30%，同时解析速度提升约 40%。对于高频事件（如 completion.chunk，每个 Token 一个事件），系统实现了 客户端自适应批量推送——根据客户端的处理能力和网络带宽动态合并多个 Token 为一个批次，在延迟和吞吐之间取得平衡。生产环境实测数据显示：在 5,000 并发连接下，事件推送的 P99 延迟为 42ms，消息到达率 99.97%。
五、安全与权限：推送通道的访问控制
WebSocket 连接同样需要严格的安全管控，不能因为协议差异而产生安全短板。EIOS 要求所有 WebSocket 连接在建立握手阶段携带 认证令牌（通过 URL 查询参数 ?token= 或首条消息中的 auth 字段）。令牌在握手阶段由服务端验证，验证通过后绑定到连接上下文中，后续所有事件推送均受该令牌的权限策略约束。这意味着：如果某个 API Key 没有访问特定 Agent 的权限，使用该 Key 建立的 WebSocket 连接也无法订阅该 Agent 的执行事件。连接建立后的 空闲超时 为 5 分钟（可通过连接参数调整），超时后服务端主动关闭连接并释放资源。速率限制同样适用于 WebSocket——单个连接每秒最多接收 200 个事件，超过限制的事件会被合并为批次，而非丢弃。对于包含 敏感信息 的事件（如工具调用参数中可能包含用户上传的文档内容），开发者可以在连接参数中设置 mask_sensitive: true，服务端将自动脱敏相关字段（替换为 [REDACTED]），在透明度和数据保护之间取得平衡。
六、应用案例与未来展望
WebSocket 实时推送已在 EIOS 平台的多个核心功能中得到验证。最典型的场景是 ChatPanel（智能对话面板）——通过 WebSocket 推送 Agent 的思考链条和工具调用过程，用户可以看到 AI 实时"翻阅"知识库文档、"分析"合同条款、"计算"数据指标，这种透明感极大提升了用户对 AI 输出的信任度和采纳意愿。第二个典型场景是 多 Agent 协作可视化——当主管 Agent 将子任务委托给多个专业 Agent 时，WebSocket 流式推送每个子 Agent 的执行状态，在 UI 中形成类似"团队协作看板"的实时视图。第三个场景是 审计与合规监控——合规团队通过 WebSocket 订阅所有 Agent 的执行事件，实时检测是否出现违规操作（如访问了无权限的知识库、输出了受限制的数据类别），实现从事后审计到事中拦截的升级。未来 12 个月，团队计划引入 WebTransport 协议（基于 HTTP/3 和 QUIC），在弱网环境下获得比 WebSocket 更低的延迟和更好的多路复用能力。
