跳转到内容
Flue

输入关键词开始搜索文档。

Flue Agent SDK

最后更新 查看 Markdown 源文件

Flue Agent SDK（@flue/sdk）是用于已部署 Flue 应用中单个智能体会话的 TypeScript 客户端。一个客户端封装了一个会话 URL — 即智能体路由（createAgentRouter(...)）的挂载路径加上调用方选择的会话 ID — 并在该 URL 提供的 HTTP 路由上暴露类型化方法：接收消息、等待结算、读取或观察已物化的会话、中止进行中的工作，以及解析附件字节。

该包仅支持 ESM，可在任何有 fetch 的环境运行（浏览器、Node.js、边缘运行时），只有一个依赖 @durable-streams/client，它为 wait() 和 observe() 提供了可重连的流传输。

安装

npm install @flue/sdk

最小化往返示例

import { createFlueClient } from '@flue/sdk';

const conversation = createFlueClient({
  url: 'https://example.com/agents/support/ticket-8472',
  token: process.env.FLUE_TOKEN,
});

// 发送一条消息。服务器在智能体运行之前返回 202。
const admission = await conversation.send({
  message: { kind: 'user', body: 'Summarize the open issues in my case.' },
});

// 等待提交结算并读取回复。
// 当运行失败或被中止时抛出 FlueExecutionError。
const reply = await conversation.read(admission);

发送操作是即发即忘的 — 智能体的响应会落到会话中，而 read() 是组合的往返操作，它等待提交结算后再读取回复。底层原语也是公开的：wait() 在结算时解析但不获取回复（适用于只需要结果的调用方），history() 读取一个物化快照，observe() 维护一个跨追赶和实时更新的实时视图，而纯函数 readSubmissionReply() 辅助方法从任一方式中提取提交的回复 — 包括当发送加入了一个繁忙响应时的合并回复。所有这些都记录在 FlueClient 页面上。

每个客户端对应一个会话

没有部署级客户端，也没有按智能体名称寻址。框架不知道应用在哪里挂载了其智能体 — 应用的路由映射（app.ts）知道 — 因此客户端通过 URL 精确寻址一个会话。结果：

  • 开始新会话就是在挂载 URL 后附加一个新 ID 来构造客户端。会话本身在接收到第一条消息时创建；createFlueClient() 不执行任何 I/O 操作。
  • 没有枚举会话、按名称查找智能体或删除会话的 API。这些是应用路由背后的应用层关注点。
  • 认证方式取决于应用路由的要求：客户端在每个请求（包括流重连）上附加 bearer token 或自定义 headers。构造选项记录在 CreateFlueClientOptions 中。

它所封装的 HTTP 接口

每个客户端方法都是对会话 URL 某个路由的类型化封装（参见路由 — 会话 URL）：

  • send() — POST <url>; the body is the same DeliveredMessage shape a server-side dispatch(...) admits, optionally with initialData and a uid send condition.
  • read() — wait()’s stream follow, then one history() read to return the submission’s reply.
  • wait() — reads the GET <url>?view=updates stream from the admission’s offset until the submission’s submission-settled chunk arrives.
  • history() — GET <url>?view=history; one materialized snapshot, optionally bounded to the newest messages with limit.
  • historyBefore() — GET <url>?view=history&before=<cursor>; one page of older messages.
  • observe() — history() to hydrate, then the updates stream to stay live, with reconnection, rehydration, and duplicate-chunk suppression handled internally.
  • abort() — POST <url>/abort.
  • attachmentUrl() — resolves <url>/attachments/<attachmentId> for one file part’s bytes.

任何 HTTP 客户端都可以直接调用这些路由 — 线路协议记录在流协议参考中。SDK 增加的是类型化契约加上你否则需要重新实现的流机制：基于偏移量的恢复、重连退避、按请求的头部解析，以及至少一次的重发去重。

与 @flue/react 和 @flue/runtime 的关系

  • useFlueAgent() 来自 @flue/react，它基于此包构建：它从 url 选项（或接受一个预配置的客户端用于自定义头部、认证或 fetch 行为）构造 createFlueClient(...)，并将客户端的 observe() 输出归约为 React 状态。
  • 在 Flue 服务端进程内部，不需要 HTTP：@flue/runtime 的 init() 和 dispatch() 直接寻址智能体（参见构建智能体）。SDK 用于进程外的代码 — 浏览器、脚本、CI、其他服务 — 通过 HTTP 接口访问已部署的智能体。

本节页面

  • createFlueClient(…) — 构造客户端（CreateFlueClientOptions：url、fetch、headers、token）、URL 解析和自定义传输。
  • FlueClient — 会话方法 — send()、wait()、abort()、history()、observe() 和 attachmentUrl() — 及其选项、结果和物化会话状态类型。
  • 事件和记录 — updates 线路联合类型（ConversationStreamChunk）、FlueEventStream 迭代接口，以及偏移量/重发语义。
  • 错误 — FlueApiError（失败的 HTTP 请求）、FlueExecutionError（失败或中止的结算）、文档化的服务器错误信封，以及重新导出的 @durable-streams/client 流错误。