Skip to content
Flue

Start typing to search the documentation.

SDK overview

Last updated View as Markdown

@flue/sdk is the TypeScript client for one agent conversation of a deployed Flue application. A client wraps a single conversation URL — the path where the agent’s router (createAgentRouter(...)) is mounted plus a caller-chosen conversation id — and exposes typed methods over the HTTP routes that URL serves: admit a message, await its settlement, read or observe the materialized conversation, abort in-flight work, and resolve attachment bytes.

The package is ESM-only, runs anywhere fetch is available (browsers, Node.js, edge runtimes), and has one dependency, @durable-streams/client, which provides the reconnecting stream transport under wait() and observe().

Installation

npm install @flue/sdk

A minimal round trip

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

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

// Admit one message. The server responds 202 before the agent runs.
const admission = await conversation.send({
  message: { kind: 'user', body: 'Summarize the open issues in my case.' },
});

// Await the submission's settlement. Resolves void on completion;
// throws FlueExecutionError when the run fails or is aborted.
await conversation.wait(admission);

// Read the reply from the conversation.
const { messages } = await conversation.history();
const reply = messages.at(-1);

wait() never returns the reply — sends are fire-and-forget admissions, and the agent’s response lands in the conversation. Read it once with history(), or maintain a live view with observe(), which streams the same materialized state across catch-up and live updates. All three methods are documented on the FlueClient page.

One conversation per client

There is no deployment-wide client and no agent-name addressing. The framework does not know where an application mounts its agents — the application’s route map (app.ts) does — so a client addresses exactly one conversation by URL. Consequences:

  • Starting a new conversation is constructing a client with a fresh id appended to the mount URL. The conversation itself is created on the first message it receives; createFlueClient() performs no I/O.
  • There is no API to enumerate conversations, look up agents by name, or delete a conversation. Those are application concerns behind application routes.
  • Auth is whatever the application’s routes require: the client attaches a bearer token or arbitrary headers to every request, including stream reconnections. Construction options are documented under CreateFlueClientOptions.

The HTTP surface it wraps

Every client method is a typed wrapper over one route of the conversation URL (see Routing — The conversation URL):

  • send() — POST <url>; the body is the same DeliveredMessage shape a server-side dispatch(...) admits, optionally with initialData and a uid send condition.
  • 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.
  • 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.

Any HTTP client can call these routes directly — the wire protocol is documented in the Streaming Protocol reference. What the SDK adds is the typed contract plus the stream mechanics you would otherwise reimplement: offset-based resume, reconnection backoff, per-request header resolution, and at-least-once redelivery dedup.

Relationship to @flue/react and @flue/runtime

  • useFlueAgent() from @flue/react is built on this package: it constructs a createFlueClient(...) from its url option (or accepts a pre-configured client for custom headers, auth, or fetch behavior) and reduces the client’s observe() output into React state.
  • Inside a Flue server process, HTTP is unnecessary: init() and dispatch() from @flue/runtime address agents directly (see Building agents). The SDK is for code outside the process — browsers, scripts, CI, other services — reaching a deployed agent over its HTTP surface.

Pages in this section

  • createFlueClient(…) — constructing a client (CreateFlueClientOptions: url, fetch, headers, token), URL resolution, and custom transports.
  • FlueClient — the conversation methods — send(), wait(), abort(), history(), observe(), and attachmentUrl() — with their option, result, and materialized conversation state types.
  • Events and records — the runtime activity event union (FlueEvent) and its normalized model-turn types, and the updates wire union (ConversationStreamChunk).
  • Errors — FlueApiError (failed HTTP requests), FluePublicError (the serialized server error shape), FlueExecutionError (failed or aborted settlements), and the re-exported @durable-streams/client stream errors.