SDK Overview

Purpose and Scope

The Flue SDK is the client-side entrypoint for applications that need to consume deployed Flue agents and workflows. In this context, client-side means application code outside the deployed Flue runtime: a product backend, frontend-adjacent service, internal dashboard, automation worker, or any program that calls the HTTP surface exposed by a Flue application. The SDK overview positions this package around consumption rather than authoring. Agents, workflows, durable state, routing, and persistence live in the Flue application and runtime; the SDK gives callers a typed way to reach that application once it has been mounted and deployed.

Sources: apps/docs/src/content/docs/sdk/overview.md

The most important boundary is that the SDK does not replace the runtime. A deployed Flue application owns its agents, workflows, route handlers, middleware, resource exposure, and any administrative endpoints the application author chooses to publish. The SDK configures access to that application by pointing at a base URL and, when needed, attaching a token. Readers should think of it as a public client for authored routes, not as an all-powerful project inspector. That distinction matters because Flue intentionally keeps deployment-wide listing and administration on the server side.

Sources: apps/docs/src/content/docs/sdk/overview.md, apps/docs/src/content/docs/cli/overview.md

Relevant Source Files

• apps/docs/src/content/docs/sdk/overview.md — Defines the public SDK overview, the @flue/sdk package entrypoint, createFlueClient(...), the client namespaces, and the server-side boundary for deployment-wide listing.
• apps/docs/src/content/docs/cli/overview.md — Explains how local development serves the real HTTP and SDK surface, how flue run calls through the authored application mount, and how builds package target-specific deployment output.

Core Primitives

The SDK overview names one main constructor: createFlueClient(...). It configures access to a deployed Flue application with a baseUrl and optional bearer-style token value supplied by the caller. From there, callers use namespaces on the returned client. The documented namespaces are agents, workflows, and runs. Agent calls invoke persistent agent instances and stream their events. Workflow calls start workflow runs. Run calls inspect and stream runs exposed by the workflow that owns them. These namespaces mirror the public tasks a client performs after a Flue application is already running.

import { createFlueClient } from '@flue/sdk';
 
const client = createFlueClient({
  baseUrl: 'https://example.com/api',
  token: process.env.FLUE_TOKEN,
});

Sources: apps/docs/src/content/docs/sdk/overview.md

The shared concepts behind those namespaces are events, records, normalized model-turn data, and errors. The SDK overview points readers to separate references for observable events and stream or HTTP errors, which is a clue about how callers should integrate with Flue. A consumer should not treat an agent or workflow invocation as a single opaque response when the route offers streaming. Instead, the client application should be prepared to consume incremental updates, display or record events, and handle transport or stream failures using the documented error model.

Sources: apps/docs/src/content/docs/sdk/overview.md

How the SDK Relates to Runtime Applications

A Flue application is authored and served through the runtime, while the SDK attaches to the routes that application exposes. The CLI overview reinforces this relationship for local development: flue dev serves the configured Node.js or Cloudflare target, watches source files, rebuilds on changes, and lets developers use the real HTTP and SDK surface while authoring routes and integrations. This means the same style of SDK client that targets production can also target a local development server, provided the base URL matches the authored mount.

Sources: apps/docs/src/content/docs/cli/overview.md

Resource discovery is not the same thing as public exposure. The CLI overview explicitly says agents and workflows are not public merely because they are discovered, and points readers to routing for authored exposure. That has a direct SDK consequence: if a client cannot reach an agent or workflow through the deployed base URL, the fix is usually in the application routing layer, not in the SDK constructor. The application author decides where flue() routes are mounted, which middleware runs, and which resources are reachable to external callers.

Sources: apps/docs/src/content/docs/cli/overview.md

Task Flow: From Local App to SDK Consumer

A practical development loop starts by installing the CLI as a development dependency, starting the local server, and then exercising the same HTTP surface that a deployed consumer will call. The CLI documentation shows npm install --save-dev @flue/cli followed by npx flue dev. During this phase, SDK consumers can be pointed at the local mount to test authentication headers, event handling, workflow inputs, and agent session behavior against real application code. This is safer than mocking the SDK because route middleware and resource exposure are part of the behavior.

npm install --save-dev @flue/cli
npx flue dev

Sources: apps/docs/src/content/docs/cli/overview.md

For quick resource checks, the CLI also provides flue run, which executes one agent prompt or workflow invocation and exits. Without an absolute server option, it temporarily starts the configured runtime and calls through the authored application and an existing mount. With an absolute URL, it attaches to an already-running local or deployed application. This complements the SDK: flue run is a terminal exercise tool for one invocation, while the SDK is the integration surface for applications that need to invoke, stream, and inspect work programmatically.

npx flue run assistant --input '{"message":"Summarize this repository."}'
npx flue run workflow:summarize-ticket --server https://example.com/api/flue --input '{"ticket":"Ticket details"}'

Sources: apps/docs/src/content/docs/cli/overview.md

API Namespace Reference

The SDK overview also draws a deliberate line around deployment-wide listing. Listing all runs or all agents is described as a server-side concern, not a built-in client-wide namespace. Application authors who need an admin console or operations endpoint should compose their own routes from runtime primitives such as listRuns(), getRun(), and listAgents(). This keeps broad visibility and authorization policy inside the deployed application, where the project can enforce identity, tenancy, auditing, and resource filtering before returning administrative data to a client.

Sources: apps/docs/src/content/docs/sdk/overview.md

Implementation Guidance and Next Steps

When integrating the SDK, first confirm the route mount and deployment target. The CLI overview says flue build creates target-specific deployment output but does not choose a model, add credentials, expose additional routes, or configure platform-owned bindings. In practice, that means a successful build is not enough to guarantee SDK access. The Flue application still needs credentials, platform configuration, and intentional route exposure. Once the deployed base URL is stable, create the client with that URL, pass the appropriate token, and test agents, workflows, streaming, and error handling against the mounted application.

Sources: apps/docs/src/content/docs/cli/overview.md, apps/docs/src/content/docs/sdk/overview.md

Next, read the SDK namespace references for agents, workflows, runs, events, and errors, then pair them with the routing and CLI pages. The SDK page tells consumers what they can call; the routing material explains why a resource is reachable; and the CLI page explains how to develop, run, and build the backing application. If you are building an administrative surface, do not search for a deployment-wide SDK listing shortcut. Instead, add explicit server routes that wrap runtime listing primitives and apply the authorization rules your product requires.

Sources: apps/docs/src/content/docs/sdk/overview.md, apps/docs/src/content/docs/cli/overview.md