SuperAPI AI 工具集

agent-sdk-streaming

智能体与模型

查看项目

更新于 10-15 23:49

技能介绍

用途:该技能面向构建交互式 Agent 界面的开发者,说明如何正确流式消费 Agent SDK 输出,让文本边生成边显示、展示工具活动,并避免在长时间工具调用上阻塞界面。适用于任何交互式 Agent UI、需要展示进度的长任务,以及排查“Agent 为什么卡住”(常见原因是未读取流)。

主要能力:SDK 会发出带类型的事件流,核心类型包括 assistant 文本块(追加到当前消息气泡)、assistant thinking(显示思考中指示)、assistant tool_use(显示工具徽标)、user tool_result(展示结果或确认)、system progress(更新进度条)以及 result(结束回合、移除加载状态)。资料给出 TypeScript 遍历 query() 事件并按 msg.type 分发的示例,并说明部分 SDK 版本发出的是累积完整消息而非增量,需用 lastText 切片计算新增文本,具体以所用 SDK 版本文档为准。

使用方式:Web 场景可将 Node 流桥接为 SSE,设置 Content-Type: text/event-stream 与 Cache-Control: no-cache,每次写入后 flush;若在 nginx 后需禁用代理缓冲(X-Accel-Buffering: no),并每 15 秒发送心跳注释防止空闲超时。React 侧可用 Hook 读取 ReadableStream,按 \n\n 切分事件并归约消息状态。背压方面可把相邻文本增量合并到 30 FPS 渲染、批量处理工具事件,超长响应考虑虚拟化。取消通过 AbortController 传入 options.abortController,取消后应优雅显示“已由用户停止”。错误处理需区分 AbortError、429 限流与其他错误,不要静默失败。工具调用可映射为用户友好标签(如 web_fetch 显示“正在查询网络”),原始细节放入可展开区域。

限制与反模式:资料未提供具体 SDK 版本兼容矩阵、性能基准或部署环境细节。应避免等完整响应再渲染、服务端不 flush、无取消路径、同步渲染每个增量导致卡顿、流结束不记录日志等做法。