SuperAPI AI 工具集

ai-core/ag-ui-protocol

智能体与模型

查看项目

更新于 10-16 12:43

技能介绍

用途:在 TanStack AI 服务端实现 AG-UI 流式协议,将 chat() 返回的 AsyncIterable<StreamChunk> 编码为 SSE 或 NDJSON 响应,并接收 AG-UI 的 RunAgentInput 请求。

主要能力:

  1. SSE 输出:toServerSentEventsStream 返回 ReadableStream,toServerSentEventsResponse 自动设置 Content-Type: text/event-stream、Cache-Control: no-cache、Connection: keep-alive,格式为 data: <JSON>\n\n,以 data: [DONE]\n\n 结束。
  2. HTTP 流输出:toHttpStream 与 toHttpResponse 输出换行分隔 JSON(NDJSON),无 SSE 前缀和 [DONE],且不自动设置 Content-Type。
  3. 请求解析:chatParamsFromRequestBody 按 @ag-ui/core 的 RunAgentInputSchema 校验请求体;mergeAgentTools 合并服务端工具与客户端工具,冲突时服务端优先,客户端独有工具成为无执行桩。
  4. 事件类型:RUN_STARTED、TEXT_MESSAGE_START/CONTENT/END、TOOL_CALL_START/ARGS/END、STEP_STARTED/FINISHED、MESSAGES_SNAPSHOT、STATE_SNAPSHOT、STATE_DELTA、CUSTOM、RUN_FINISHED、RUN_ERROR。StreamChunk 是 AGUIEvent 的别名。
  5. 类型化 CUSTOM 事件:chat() 默认返回 ChatStream,通过 if (chunk.type === 'CUSTOM' && chunk.name === '...') 可获得具体 value 类型。

必要用法:服务端用 chat({ adapter, messages }) 生成流,再交给对应的 toServerSentEventsResponse 或 toHttpResponse。流抛出错误时自动发出 RUN_ERROR;若 abortController 已中止则静默关闭。forwardedProps 不应直接展开进 chat(),应白名单字段。

适用场景:需要以 AG-UI 协议向前端流式输出文本、工具调用、状态更新的智能体服务端。

限制:STEP_STARTED/FINISHED 仅在带思考的模型出现;TOOL_CALL 系列仅在调用工具时出现;STATE 与 MESSAGES_SNAPSHOT 需服务端显式发送;CUSTOM 默认不发出。反向代理可能缓冲 SSE,需设置 X-Accel-Buffering: no 等头。非字面量判断(如 .endsWith)不能收窄 CUSTOM 类型。用户自定义 emitCustomEvent 名称不在 ChatStream 类型内。

其他:本技能构建于 ai-core 之上,应先阅读。完整 CUSTOM 事件分类见 docs/protocol/custom-events.md。