Flue

https://github.com/withastro/flue
Admin
Flue is a TypeScript framework for building autonomous agents with a built-in agent harness that can...
Tokens:579,159
Snippets:3,884
Trust Score:9.5
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install @flue/react and @flue/sdk

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/guide/react.md

Install the @flue/react and @flue/sdk packages using pnpm. No provider or app-level setup is required after installation.

```sh
pnpm add @flue/react @flue/sdk
```

--------------------------------

### Start Vite dev server

Source: https://github.com/withastro/flue/blob/main/examples/braintrust/README.md

Starts the Node dev server from the example directory. Vite prints the local URL (default http://localhost:5173).

```bash
pnpm exec vite dev
```

--------------------------------

### start()

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/reference/agent-api.md

Documentation for the start() function from @flue/runtime/node, which boots the Flue runtime in Node.js.

```APIDOC
## `start()`

### Description
Starts the Flue runtime in a Node.js environment, registering agents, persistence, and providers. It returns a `Flue` handle that can be used to stop the runtime.

### Method
`start`

### Signature
```ts
function start(options: StartOptions): Promise<Flue>;
```

### Parameters
#### `options` (StartOptions) - Required
- **agents** (`readonly StartAgentEntry[]`) - Required, non-empty. Each entry is an agent function or `{ agent, name }` for identity override. Identity resolves from the entry's `name`, else the agent's own identity (`agentName` static, else function name). An anonymous function with no `agentName` and no `name` throws.
- **db** (`PersistenceAdapter`) - Optional. Persistence adapter. Defaults to in-memory SQLite (process lifetime). Pass `sqlite('./run.db')` to persist across runs.
- **env** (`Record<string, string | undefined>`) - Optional. Runtime environment (provider credentials and other bindings). Defaults to `process.env`.
- **providers** (`readonly Provider[]`) - Optional. Pi providers to register, replacing the default set. Omitted registers every Pi built-in; empty array registers none. Explicit entries overwrite same-ID providers set before `start()`.

### Return Value
Returns a `Flue` handle with `stop()` and `[Symbol.asyncDispose]()` methods. `stop()` drains in-flight work and disconnects persistence. The async-dispose symbol enables `await using flue = await start(...)` for automatic cleanup.

### Errors
Throws when a runtime is already configured (one process holds at most one Flue runtime). Inside a Flue server, call `init()`/`dispatch()` directly.

### Example
```ts
import { start } from '@flue/runtime/node';
import { anthropicProvider } from '@earendil-works/pi-ai/providers/anthropic';

await start({
  agents: [Reporter],
  providers: [anthropicProvider()], // only anthropic/* specifiers resolve
});
```
```

--------------------------------

### Twilio channel setup (abridged) - src/channels/twilio.ts

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/channels/twilio.md

This abridged channel setup shows how to create a Twilio client and a Twilio channel, handling webhooks with STOP opt-out and dispatching to an Assistant. The complete example includes a generated postMessage tool and the Fetch client implementation.

```typescript
import { createTwilioChannel } from '@flue/twilio';
import { dispatch } from '@flue/runtime';
import { Assistant } from '../agents/assistant.ts';
import { TwilioClient } from '../twilio-client.ts';

export const client = new TwilioClient({
  accountSid: process.env.TWILIO_ACCOUNT_SID!,
  authToken: process.env.TWILIO_AUTH_TOKEN!,
});

export const channel = createTwilioChannel({
  accountSid: process.env.TWILIO_ACCOUNT_SID!,
  authToken: process.env.TWILIO_AUTH_TOKEN!,
  webhookUrl: process.env.TWILIO_WEBHOOK_URL!,
  destination: {
    type: 'address',
    address: process.env.TWILIO_PHONE_NUMBER!,
  },
  async webhook({ payload, conversation }) {
    if (payload.OptOutType === 'STOP') return;
    await dispatch(Assistant, {
      id: channel.instanceId(conversation),
      // Recorded once when this event creates the instance; ignored after.
      initialData:
        conversation.type === 'messaging-service'
          ? {
              type: conversation.type,
              messagingServiceSid: conversation.messagingServiceSid,
              participant: conversation.participant,
            }
          : {
              type: conversation.type,
              address: conversation.address,
              participant: conversation.participant,
            },
      message: {
        kind: 'signal',
        type: 'twilio.message',
        body: payload.Body,
        attributes: { messageSid: payload.MessageSid, from: payload.From },
      },
    });
  },
});
```

--------------------------------

### Example .env file

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/guide/getting-started.mdx

Example .env file for managing API keys, showing the ANTHROPIC_API_KEY variable.

```plaintext
# .env
ANTHROPIC_API_KEY="your-api-key"
```

--------------------------------

### Install libSQL or Turso adapter with flue add database

Source: https://github.com/withastro/flue/blob/main/packages/libsql/README.md

Install the libSQL adapter for a local file or self-hosted libSQL server, or the Turso adapter for hosted Turso. Both commands install this package and write the db.ts file for the chosen target.

```sh
flue add database libsql   # local file / self-hosted libSQL server
flue add database turso    # hosted Turso
```

--------------------------------

### start() with custom providers option

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/reference/agent-api.md

Shows how to pass a custom providers array to start(), registering only the anthropic provider so only anthropic/* specifiers resolve. This overrides the default provider set and any same-ID provider set before start().

```ts
import { anthropicProvider } from '@earendil-works/pi-ai/providers/anthropic';

await start({
  agents: [Reporter],
  providers: [anthropicProvider()], // only anthropic/* specifiers resolve
});
```

--------------------------------

### Install Flue packages and initialize project

Source: https://github.com/withastro/flue/blob/main/apps/www/src/pages/blog/flue-1-0-beta.mdx

Install the Flue runtime and CLI, then initialize a new project. Run these commands in your terminal to set up Flue for the first time.

```sh
npm install @flue/runtime
npm install -D @flue/cli
npx flue init
```

--------------------------------

### Trigger example agents with curl

Source: https://github.com/withastro/flue/blob/main/examples/braintrust/README.md

Triggers each example agent via POST. Returns 202 admission; GET of the same URL streams the conversation.

```bash
curl -X POST 'http://localhost:5173/agents/prompt/demo-1' \
  -H 'content-type: application/json' \
  -d '{"kind":"user","body":"Welcome a developer named Ada."}'

curl -X POST 'http://localhost:5173/agents/tools/demo-1' \
  -H 'content-type: application/json' \
  -d '{"kind":"user","body":"What is the weather in San Francisco?"}'

curl -X POST 'http://localhost:5173/agents/task/demo-1' \
  -H 'content-type: application/json' \
  -d '{"kind":"user","body":"Rewrite this sentence: We are leveraging synergies to move faster."}'
```

--------------------------------

### Set up a Flue project

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/deploy/gitlab-ci.md

Initializes a new Node.js project and installs the Flue runtime, valibot, and the Flue CLI as a dev dependency.

```bash
mkdir my-flue-project && cd my-flue-project
npm init -y
npm install @flue/runtime valibot
npm install -D @flue/cli
```

--------------------------------

### Build packages and documentation

Source: https://github.com/withastro/flue/blob/main/CONTRIBUTING.md

Run this command to build all packages and prepare documentation before publishing.

```sh
pnpm run build && pnpm run build:docs
```

--------------------------------

### Install Jetty SDK with pnpm

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/tooling/jetty.md

Installs the Jetty TypeScript SDK in an existing Flue project. Jetty does not use a `flue add` blueprint; follow Jetty's Flue integration guide to create and deploy a grading runbook.

```sh
pnpm add @jetty/sdk
```

--------------------------------

### Simple Agent Function in TypeScript

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/guide/building-agents.md

This is a minimal agent function in Flue that returns a static system prompt. It is the first example shown in the guide.

```ts
// Example: A simple agent, written in Flue.
function TriageAgent() {
  return "Investigate the user's issue and recommend the next action.";
}
```

--------------------------------

### Set up project: install dependencies, configure vite.config.ts and package.json

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/deploy/node.md

Sets up a new Flue project: initializes a Node project, installs runtime and dev dependencies, configures the Vite plugin, and adds the dev/build scripts.

```bash
mkdir my-flue-server && cd my-flue-server
npm init -y
npm install @flue/runtime hono valibot
npm install -D @flue/vite @flue/cli vite
```

```ts
import { flue } from '@flue/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [flue()],
});
```

```jsonc
{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
  },
}
```

--------------------------------

### flue docs: list, read, search, then read examples

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/cli/docs.md

Everyday command examples: listing all documentation pages, printing a specific page as markdown, and searching then reading the top result. The final two commands form a typical agent loop: search to locate a page, then read it.

```bash
# List every page with its path and description
flue docs

# Print one page as markdown
flue docs read guide/sandboxes

# Search, then read the top result
flue docs search durable execution
flue docs read guide/durability
```

--------------------------------

### Basic virtual sandbox setup with bash() helper

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/guide/sandboxes.md

Sets up a virtual sandbox using the bash() helper with an in-memory filesystem. The agent uses the Claude Haiku model and returns a prompt for data fetching and reshaping. The sandbox is isolated and ephemeral.

```ts
'use agent';
import { bash, useModel, useSandbox } from '@flue/runtime';
import { Bash, InMemoryFs } from 'just-bash';

export function ScratchWorker() {
  useModel('anthropic/claude-haiku-4-5');
  useSandbox(bash(() => new Bash({ fs: new InMemoryFs() })));
  return 'Fetch, reshape, and summarize the data the user points you at.';
}
```

--------------------------------

### Fetching older conversation history

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/sdk/flue-client.md

Example showing how to use history() to get an initial page and then historyBefore() to fetch older messages if a cursor is present.

```ts
const page = await client.history({ limit: 50 });
if (page.before) {
  const older = await client.historyBefore(page.before, { limit: 50 });
}
```

--------------------------------

### Set up a Flue project on Cloudflare

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/deploy/cloudflare.md

Initializes a new project and installs the Flue runtime, Hono, and the Vite and Cloudflare plugins as dev dependencies. Optionally install @cloudflare/sandbox for a remote sandbox.

```bash
mkdir my-flue-worker && cd my-flue-worker
npm init -y
npm install @flue/runtime hono
npm install -D @flue/vite @cloudflare/vite-plugin vite wrangler
```

--------------------------------

### flue add

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/cli/add.md

The `flue add` command fetches a blueprint — a Markdown implementation guide that an AI coding agent follows to build an integration into your project. It is not a package installer: the command prints the guide, and your coding agent applies it. Run with no arguments to list every available blueprint.

```APIDOC
## flue add

### Description
Fetches a blueprint — a Markdown implementation guide that an AI coding agent follows to build an integration into your project. It is not a package installer: the command prints the guide, and your coding agent applies it. Run with no arguments to list every available blueprint.

### Method
CLI command

### Command
`flue add [<kind> <name|url>] [--print]`

### Arguments
- `<kind>` (string) - Required - The integration category: `channel`, `database`, `sandbox`, or `tooling`.
- `<name|url>` (string) - Required - A blueprint name (`slack`, `postgres`, `daytona`, `sentry`, …; run `flue add` with no arguments for the catalog), or an absolute URL to provider documentation, which selects the kind's generic build-from-scratch guide with the URL as the coding agent's research starting point.

### Options
- `--print` (flag) - Optional - Write the blueprint Markdown to stdout regardless of coding-agent detection.

### Examples
```bash
# List every available blueprint
flue add

# Add a Slack channel with Claude Code
flue add channel slack --print | claude

# Build a channel from scratch, starting the agent from a provider docs URL
flue add channel https://developers.notion.com/reference/webhooks --print | codex

# Add a Postgres persistence adapter
flue add database postgres --print | claude
```
```

--------------------------------

### flue init usage examples

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/cli/init.md

Provides various invocations of `flue init` for different scenarios, such as prompting for options, specifying a target, enabling deploy, and forcing overwrite.

```bash
flue init                                  # prompt for everything, scaffold into the current directory
```

```bash
flue init ./my-agent-app                   # prompt, scaffold into ./my-agent-app (created if missing)
```

```bash
flue init --target node                    # local-run skeleton, no prompts
```

```bash
flue init --target node --deploy           # Node server skeleton
```

```bash
flue init ./bot --target cloudflare        # Cloudflare skeleton (--deploy implied)
```

```bash
flue init --target node --force            # scaffold into a non-empty directory, overwrite flue.config.*
```

--------------------------------

### Create a new Astro project with the minimal template

Source: https://github.com/withastro/flue/blob/main/apps/www/README.md

Use this command to scaffold a new Astro project using the minimal template. Run it in your terminal to get started.

```sh
npm create astro@latest -- --template minimal
```

--------------------------------

### Start react-chat assistant on port 3583

Source: https://github.com/withastro/flue/blob/main/demo/README.md

Runs the faux `assistant` agent in the `react-chat` example. The `--port 3583` matches the SPA's default agent URL so no further configuration is needed.

```sh
# from the repo root
cd examples/react-chat
pnpm exec vite dev --port 3583
```

--------------------------------

### createIntercomChannel example

Source: https://github.com/withastro/flue/blob/main/packages/intercom/README.md

Example of setting up an Intercom channel with a client secret and a webhook handler that processes conversation events. The handler logs notifications for `conversation.user.created` and `conversation.user.replied` topics and returns for others. The channel exposes `HEAD /webhook` for validation and `POST /webhook` for signed notifications; it does not handle installation, subscriptions, OAuth, or outbound behavior. To deduplicate retries, set `idempotencyKey` to `notification.id` in the dispatch.

```typescript
import { createIntercomChannel } from '@flue/intercom';

export const channel = createIntercomChannel({
  clientSecret: process.env.INTERCOM_CLIENT_SECRET,

  // Path: /channels/intercom/webhook
  webhook({ notification }) {
    switch (notification.topic) {
      case 'conversation.user.created':
      case 'conversation.user.replied':
        console.log(notification.app_id, notification.data.item);
        return;
      default:
        return;
    }
  },
});

```

--------------------------------

### Set required environment variables

Source: https://github.com/withastro/flue/blob/main/examples/linear-channel/README.md

Required environment variables for the Linear channel example. Use LINEAR_ACCESS_TOKEN instead of LINEAR_API_KEY for an installed OAuth application. Optionally set LINEAR_ORGANIZATION_ID and LINEAR_WEBHOOK_ID to pin the signed endpoint to one fixed integration.

```sh
LINEAR_WEBHOOK_SECRET=...
LINEAR_API_KEY=lin_api_...
```

--------------------------------

### flue init synopsis

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/cli/init.md

Shows the command-line syntax for `flue init`, including the optional directory argument and flags for target, deploy, and force.

```bash
flue init [directory] [--target <node|cloudflare>] [--deploy] [--force]
```

--------------------------------

### Start react-chat helper agent with ANTHROPIC_API_KEY

Source: https://github.com/withastro/flue/blob/main/demo/README.md

Runs the `helper` agent using a real Anthropic model. Requires `ANTHROPIC_API_KEY` in the example's `.env` file or exported in the shell; shell-exported values take precedence because `vite dev` loads `.env` files automatically.

```sh
cd examples/react-chat
echo 'ANTHROPIC_API_KEY="sk-..."' > .env
pnpm exec vite dev --port 3583
```

--------------------------------

### Load .env and start built server

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/guide/node-target.md

Loads the .env file into the environment before starting the built server. Use this in production where the server reads only the environment supplied at startup.

```bash
set -a; source .env; set +a
node dist/server.mjs
```

--------------------------------

### Add vitest-evals blueprint

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/tooling/vitest-evals.md

Run this command in an existing Flue project to add the vitest-evals setup blueprint. The blueprint installs test dependencies, creates a dedicated eval configuration, adapts Flue's public SDK to a vitest-evals harness, and writes a starter eval case.

```sh
flue add tooling vitest-evals

```

--------------------------------

### Start the Flue demo SPA

Source: https://github.com/withastro/flue/blob/main/demo/README.md

Starts the demo SPA using the `flue-demo` package or from the demo directory. The printed URL (e.g. `http://localhost:5174`) is where you open the app.

```sh
pnpm --filter flue-demo dev
# or, from this directory:
pnpm dev
```
Tokens:
Raw