flue/sdk深度实战用HTTP驱动部署好的Agent【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flueflue/sdk是 Flue 框架官方提供的 TypeScript 客户端 SDK专门用于通过 HTTP 驱动已部署的 Agent 会话发送消息、等待结果、读取回复、实时观察对话流、中止任务全部封装成类型安全的异步方法。无论你是浏览器前端、Node.js 脚本还是 CI 流水线只要有一个fetch就能像调用函数一样调用远端 Agent。一、flue/sdk 是什么先建立一个心智模型Agent 在 Flue 中是被部署的服务端应用通过路由挂载到 HTTP 端点上。而flue/sdk就是这套 HTTP 表面的官方遥控器。它不是又一个 Agent 构建框架——构建 Agent 用的是flue/runtimeflue/sdk负责的是部署之后的事消费consume一个已部署 Agent 的对话。它的三大设计特点特点说明一个客户端 一个会话createFlueClient()精确指向挂载 URL 会话 ID没有全局客户端、没有按名字找 Agent纯 ESM零负担唯一依赖durable-streams/client浏览器、Node.js、边缘运行时通吃类型化的 HTTP 封装send、read、wait、abort、history、observe一一对应会话 URL 上的路由 会话是懒创建的createFlueClient()本身不发任何请求会话在收到第一条消息时才诞生。开启新对话 用一个新 ID 再构造一个客户端。核心客户端接口定义在 packages/sdk/src/client.ts安装只需一行npm install flue/sdk二、最小闭环send() read() 完成一次 Agent 对话这是 flue/sdk 最典型的用法两步走发消息、拿回复。import { createFlueClient } from flue/sdk; // 挂载 URL 会话 ID指向一个已部署的 Agent 会话 const conversation createFlueClient({ url: https://example.com/agents/support/ticket-8472, token: process.env.FLUE_TOKEN, }); // 第 1 步投递消息。服务端返回 202 即已接受Agent 尚未运行 const admission await conversation.send({ message: { kind: user, body: 总结一下我工单里未解决的问题。 }, }); // 第 2 步等待本次提交完成并读回 Agent 的回复 const reply await conversation.read(admission);这里有两个值得新手注意的机制send() 是发射后不管的受理admission它只保证消息被持久化接受不等待 Agent 执行完。返回的admission对象携带submissionId和流偏移量offset是后续所有操作的回执。read() 是组合式往返内部 wait()等提交结算 一次history()读取。运行失败或被中止时会抛出FlueExecutionError。send()还支持两类消息user直接对话和signal结构化事件如 webhook、Slack 线程、GitHub issue 场景让 Agent 以参与者身份融入多用户表面实现细节见 packages/sdk/src/public/send.ts。三、核心方法全景图一个 Agent 会话的完整生命周期FlueClient一共暴露 6 个方法 1 个 URL 解析器覆盖了驱动部署 Agent 的所有需求1️⃣wait()— 只要结果不要回复如果调用方只关心跑完了没有比如 CI 里判断任务成败wait()比read()更省——它只跟踪事件流直到结算块到达不额外拉取回复。2️⃣abort()— 一键中止整个会话的在途工作中止当前正在运行和排队的所有持久化任务。返回{ aborted: boolean }表示是否真的有工作被中止已结算的任务不受影响。3️⃣history()— 读取一次性的对话快照返回一个物化materialized快照完整消息列表 各提交的最终结果。适合审计、回放、渲染只读页面。缺失的会话会返回 404FlueApiError。4️⃣observe()— 实时观察对话前端聊天 UI 的主力observe()会先读历史快照补上过去再接上事件流跟上现在并且断线重连、指数退避、重复块去重全部内置——这些如果自己基于裸 HTTP 实现工作量不小。const observation conversation.observe({ live: sse }); // 订阅快照兼容 React useSyncExternalStore const unsubscribe observation.subscribe(() { const snap observation.getSnapshot(); console.log(snap.phase, snap.conversation?.messages.length); });live可选long-poll默认轮询或sse长连接逐 token 低延迟。flue/react的useFlueAgent()就是构建在observe()之上的。5️⃣attachmentUrl()— 解析附件字节 URL把file部件的附件 ID 解析成可直接用于img/a的绝对 URL。实际上history()和observe()会自动为附件填好url字段很少需要手动调用。四、崩溃恢复为什么 read() 可以事后重连这是 flue/sdk 最被低估的能力。wait()和observe()都是观察者而非驱动者等待进程即使消失服务端提交依然会结算并持久化记录。因此read()支持两种目标传入send()的 admission 回执——正常路径只传一个裸的submissionId——重连路径从流的起点重新跟随会话。把小的 admission 对象或仅submissionId持久化后一个崩溃脚本的继任者可以随时接上读取回复若提交早已结算则立即返回。对新手来说这意味着脚本可以安全地存下回执、随时来取而不必担心进程中断丢失结果。五、错误处理两类错误各司其职错误类型场景FlueApiErrorHTTP 请求失败非 2xx如 404 会话不存在、409 实例冲突FlueExecutionError提交结算为failed或aborted错误属性携带序列化失败详情流错误StreamClosedError等wait()/observe()的流传输层异常由durable-streams/client提供错误约定完整定义在 apps/docs/src/content/docs/sdk/errors.md类型导出见 packages/sdk/src/index.ts。六、实战场景与配套参考浏览器聊天 UI用createFlueClient()observe({ live: sse })构建实时对话界面官方演示 demo/src/lib/flue-client.ts 展示了挂载 URL 会话 ID 派生客户端的标准写法。服务端集成在 webhook 管线中调用 Agent 时可用send()受理后异步read()取结果参考 examples/chat-sdk/ 示例。进程内调用请绕开 HTTP如果你在 Flue 服务进程内部直接用flue/runtime的dispatch()即可SDK 专为进程之外的代码浏览器、脚本、CI、其他服务设计。七、核心资料索引资料路径SDK 包总览packages/sdk/客户端实现packages/sdk/src/client.ts方法参考页文档源apps/docs/src/content/docs/sdk/flue-client.mdSDK 概览文档apps/docs/src/content/docs/sdk/overview.md演示客户端封装demo/src/lib/flue-client.ts集成示例examples/chat-sdk/总结flue/sdk 用一个客户端绑定一个会话 URL的极简模型把持久化接受、结算等待、实时观察、崩溃恢复、中止控制全部收敛为 6 个类型化方法。掌握了send()read()的最小闭环和observe()的实时观察你就能在任何环境里优雅地驱动部署好的 Flue Agent。【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 @flue/sdk深度实战：用HTTP驱动部署好的Agent
flue/sdk深度实战用HTTP驱动部署好的Agent【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flueflue/sdk是 Flue 框架官方提供的 TypeScript 客户端 SDK专门用于通过 HTTP 驱动已部署的 Agent 会话发送消息、等待结果、读取回复、实时观察对话流、中止任务全部封装成类型安全的异步方法。无论你是浏览器前端、Node.js 脚本还是 CI 流水线只要有一个fetch就能像调用函数一样调用远端 Agent。一、flue/sdk 是什么先建立一个心智模型Agent 在 Flue 中是被部署的服务端应用通过路由挂载到 HTTP 端点上。而flue/sdk就是这套 HTTP 表面的官方遥控器。它不是又一个 Agent 构建框架——构建 Agent 用的是flue/runtimeflue/sdk负责的是部署之后的事消费consume一个已部署 Agent 的对话。它的三大设计特点特点说明一个客户端 一个会话createFlueClient()精确指向挂载 URL 会话 ID没有全局客户端、没有按名字找 Agent纯 ESM零负担唯一依赖durable-streams/client浏览器、Node.js、边缘运行时通吃类型化的 HTTP 封装send、read、wait、abort、history、observe一一对应会话 URL 上的路由 会话是懒创建的createFlueClient()本身不发任何请求会话在收到第一条消息时才诞生。开启新对话 用一个新 ID 再构造一个客户端。核心客户端接口定义在 packages/sdk/src/client.ts安装只需一行npm install flue/sdk二、最小闭环send() read() 完成一次 Agent 对话这是 flue/sdk 最典型的用法两步走发消息、拿回复。import { createFlueClient } from flue/sdk; // 挂载 URL 会话 ID指向一个已部署的 Agent 会话 const conversation createFlueClient({ url: https://example.com/agents/support/ticket-8472, token: process.env.FLUE_TOKEN, }); // 第 1 步投递消息。服务端返回 202 即已接受Agent 尚未运行 const admission await conversation.send({ message: { kind: user, body: 总结一下我工单里未解决的问题。 }, }); // 第 2 步等待本次提交完成并读回 Agent 的回复 const reply await conversation.read(admission);这里有两个值得新手注意的机制send() 是发射后不管的受理admission它只保证消息被持久化接受不等待 Agent 执行完。返回的admission对象携带submissionId和流偏移量offset是后续所有操作的回执。read() 是组合式往返内部 wait()等提交结算 一次history()读取。运行失败或被中止时会抛出FlueExecutionError。send()还支持两类消息user直接对话和signal结构化事件如 webhook、Slack 线程、GitHub issue 场景让 Agent 以参与者身份融入多用户表面实现细节见 packages/sdk/src/public/send.ts。三、核心方法全景图一个 Agent 会话的完整生命周期FlueClient一共暴露 6 个方法 1 个 URL 解析器覆盖了驱动部署 Agent 的所有需求1️⃣wait()— 只要结果不要回复如果调用方只关心跑完了没有比如 CI 里判断任务成败wait()比read()更省——它只跟踪事件流直到结算块到达不额外拉取回复。2️⃣abort()— 一键中止整个会话的在途工作中止当前正在运行和排队的所有持久化任务。返回{ aborted: boolean }表示是否真的有工作被中止已结算的任务不受影响。3️⃣history()— 读取一次性的对话快照返回一个物化materialized快照完整消息列表 各提交的最终结果。适合审计、回放、渲染只读页面。缺失的会话会返回 404FlueApiError。4️⃣observe()— 实时观察对话前端聊天 UI 的主力observe()会先读历史快照补上过去再接上事件流跟上现在并且断线重连、指数退避、重复块去重全部内置——这些如果自己基于裸 HTTP 实现工作量不小。const observation conversation.observe({ live: sse }); // 订阅快照兼容 React useSyncExternalStore const unsubscribe observation.subscribe(() { const snap observation.getSnapshot(); console.log(snap.phase, snap.conversation?.messages.length); });live可选long-poll默认轮询或sse长连接逐 token 低延迟。flue/react的useFlueAgent()就是构建在observe()之上的。5️⃣attachmentUrl()— 解析附件字节 URL把file部件的附件 ID 解析成可直接用于img/a的绝对 URL。实际上history()和observe()会自动为附件填好url字段很少需要手动调用。四、崩溃恢复为什么 read() 可以事后重连这是 flue/sdk 最被低估的能力。wait()和observe()都是观察者而非驱动者等待进程即使消失服务端提交依然会结算并持久化记录。因此read()支持两种目标传入send()的 admission 回执——正常路径只传一个裸的submissionId——重连路径从流的起点重新跟随会话。把小的 admission 对象或仅submissionId持久化后一个崩溃脚本的继任者可以随时接上读取回复若提交早已结算则立即返回。对新手来说这意味着脚本可以安全地存下回执、随时来取而不必担心进程中断丢失结果。五、错误处理两类错误各司其职错误类型场景FlueApiErrorHTTP 请求失败非 2xx如 404 会话不存在、409 实例冲突FlueExecutionError提交结算为failed或aborted错误属性携带序列化失败详情流错误StreamClosedError等wait()/observe()的流传输层异常由durable-streams/client提供错误约定完整定义在 apps/docs/src/content/docs/sdk/errors.md类型导出见 packages/sdk/src/index.ts。六、实战场景与配套参考浏览器聊天 UI用createFlueClient()observe({ live: sse })构建实时对话界面官方演示 demo/src/lib/flue-client.ts 展示了挂载 URL 会话 ID 派生客户端的标准写法。服务端集成在 webhook 管线中调用 Agent 时可用send()受理后异步read()取结果参考 examples/chat-sdk/ 示例。进程内调用请绕开 HTTP如果你在 Flue 服务进程内部直接用flue/runtime的dispatch()即可SDK 专为进程之外的代码浏览器、脚本、CI、其他服务设计。七、核心资料索引资料路径SDK 包总览packages/sdk/客户端实现packages/sdk/src/client.ts方法参考页文档源apps/docs/src/content/docs/sdk/flue-client.mdSDK 概览文档apps/docs/src/content/docs/sdk/overview.md演示客户端封装demo/src/lib/flue-client.ts集成示例examples/chat-sdk/总结flue/sdk 用一个客户端绑定一个会话 URL的极简模型把持久化接受、结算等待、实时观察、崩溃恢复、中止控制全部收敛为 6 个类型化方法。掌握了send()read()的最小闭环和observe()的实时观察你就能在任何环境里优雅地驱动部署好的 Flue Agent。【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考