---
description: The @flue/sdk conversation client — installation, a minimal round trip, the HTTP surface it wraps, and a map of the SDK reference pages.
title: SDK overview | Flue
image: https://flueframework.com/docs/og4.jpg
---

# SDK overview

Last updated Jul 17, 2026[View as Markdown](https://nightly.flueframework.com/docs/sdk/overview/index.md)

`@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](https://nightly.flueframework.com/docs/guide/routing/#mounting-an-agent) 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

```sh
npm install @flue/sdk
```

## A minimal round trip

```ts
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](https://nightly.flueframework.com/docs/sdk/flue-client/) 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](https://nightly.flueframework.com/docs/sdk/create-flue-client/#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](https://nightly.flueframework.com/docs/guide/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](https://nightly.flueframework.com/docs/reference/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()](https://nightly.flueframework.com/docs/guide/react/) 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](https://nightly.flueframework.com/docs/guide/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(…)](https://nightly.flueframework.com/docs/sdk/create-flue-client/) — constructing a client (`CreateFlueClientOptions`: `url`, `fetch`, `headers`, `token`), URL resolution, and custom transports.
* [FlueClient](https://nightly.flueframework.com/docs/sdk/flue-client/) — the conversation methods — `send()`, `wait()`, `abort()`, `history()`, `observe()`, and `attachmentUrl()` — with their option, result, and materialized conversation state types.
* [Events and records](https://nightly.flueframework.com/docs/sdk/events/) — the runtime activity event union (`FlueEvent`) and its normalized model-turn types, and the `updates` wire union (`ConversationStreamChunk`).
* [Errors](https://nightly.flueframework.com/docs/sdk/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.

## Docs Navigation

Current page: [SDK overview](https://nightly.flueframework.com/docs/sdk/overview/)

### Sections

* [Guide](https://nightly.flueframework.com/docs/guide/getting-started/)
* [Reference](https://nightly.flueframework.com/docs/reference/agent-api/)
* [CLI](https://nightly.flueframework.com/docs/cli/overview/)
* [SDK](https://nightly.flueframework.com/docs/sdk/overview/)
* [Ecosystem](https://nightly.flueframework.com/docs/ecosystem/)

### SDK

* [Overview](https://nightly.flueframework.com/docs/sdk/overview/)
* [createFlueClient(...)](https://nightly.flueframework.com/docs/sdk/create-flue-client/)
* [FlueClient](https://nightly.flueframework.com/docs/sdk/flue-client/)
* [Events](https://nightly.flueframework.com/docs/sdk/events/)
* [Errors](https://nightly.flueframework.com/docs/sdk/errors/)