Flue Framework

https://flueframework.com/docs
Admin
Flue Framework is a comprehensive toolkit for building and deploying intelligent agents and AI...
Tokens:278,308
Snippets:3,476
Trust Score:7.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configuring providers in start()

Source: https://flueframework.com/docs/reference/agent-api

Example of initializing the runtime with specific providers, overriding the default set.

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

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

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

### Common flue docs usage examples

Source: https://flueframework.com/docs/cli/docs

Practical examples for listing, reading, and searching documentation.

```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
```

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

### Build and Run for Production

Source: https://flueframework.com/docs/ecosystem/deploy/node

Commands to build the project and start the production server.

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

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

### flue update command examples

Source: https://flueframework.com/docs/cli/update

Examples of piping update guides to various coding agents.

```bash
flue update channel slack --print | claude
flue update database mysql --print | codex
flue update sandbox @cloudflare/shell --print | opencode
flue update channel https://developers.notion.com/reference/webhooks --print | claude
```

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

### Common flue run usage examples

Source: https://flueframework.com/docs/cli/run

Various command-line examples for running agents, continuing conversations, and handling CI integration.

```bash
# Run an agent once and print its reply
flue run src/agents/hello.ts -m "Hi there"

# Continue the same conversation across invocations
flue run src/agents/support.ts -m "It fails on startup." --id support-4821
flue run src/agents/support.ts -m "Node 22, macOS."      --id support-4821

# Pick one agent from a multi-agent module
flue run src/agents/team.ts --name second-shift -m "Take over."

# CI: create exactly once, seed creation data, capture the envelope
flue run src/agents/triage.ts -m "Triage this." --id "issue-$N" --data '{"issue": 17307}' --new --json

# Extract just the reply text from the envelope
flue run src/agents/hello.ts -m "Run the demo." --json | jq -r .message

# Load staging credentials for one run
flue run src/agents/hello.ts -m "Hi" --env .env.staging
```

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

### Start Flue application

Source: https://flueframework.com/docs/ecosystem/tooling/vitest-evals/index.md

Launch the development server to prepare the application for evaluation.

```sh
pnpm exec vite dev
```

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

### Build and Run on Node.js

Source: https://flueframework.com/docs/guide/deploy/index.md

Commands to bundle the application and start the server for a Node.js environment.

```bash
vite build
node dist/server.mjs
```

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

### Install Flue Agent SDK

Source: https://flueframework.com/docs/sdk/overview

Install the package using npm.

```bash
npm install @flue/sdk
```

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

### Initialize Flue Project

Source: https://flueframework.com/docs/ecosystem/deploy/node

Commands to create a new directory and install the necessary dependencies.

```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
```

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

### Examples

Source: https://flueframework.com/docs/cli/add/index.md

Common usage patterns for listing blueprints and piping them to coding agents.

```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
```

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

### Run application and evaluations

Source: https://flueframework.com/docs/ecosystem/tooling/vitest-evals

Commands to start the development server and execute the evaluation suite.

```bash
pnpm exec vite dev
```

```bash
pnpm run evals
```

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

### start(options)

Source: https://flueframework.com/docs/reference/agent-api/index.md

Bootstraps the Flue runtime in a Node.js environment, configuring agents, persistence, and providers.

```APIDOC
## start(options)

### Description
The Node bootstrap for running Flue outside a generated server entry. It handles agent registration, persistence, and the durable submission coordinator.

### Parameters
- **options** (StartOptions) - Required - Configuration object for the runtime.
  - **agents** (readonly StartAgentEntry[]) - Required - The agents this runtime serves.
  - **db** (PersistenceAdapter) - Optional - Persistence adapter for conversation storage.
  - **env** (Record<string, string | undefined>) - Optional - Runtime environment variables.
  - **providers** (readonly Provider[]) - Optional - Pi providers to register.

### Returns
- **Promise<Flue>** - A Flue handle containing stop() and asyncDispose methods.
```

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

### Install Flue CLI and Runtime

Source: https://flueframework.com/docs/cli/overview/index.md

Install the necessary runtime and CLI packages as dependencies in your project.

```bash
npm install @flue/runtime @flue/cli
```

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

### Run Development Server

Source: https://flueframework.com/docs/ecosystem/deploy/node

Command to start the local development server with hot reload.

```bash
npx vite dev
```

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

### Install Postgres Adapter

Source: https://flueframework.com/docs/ecosystem/deploy/fly

Add the required dependency for database connectivity in Node.js environments.

```bash
npm install @flue/postgres
```

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

### Install Jetty SDK

Source: https://flueframework.com/docs/ecosystem/tooling/jetty

Add the Jetty SDK to an existing Flue project using pnpm.

```bash
pnpm add @jetty/sdk
```

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

### Install libSQL blueprint

Source: https://flueframework.com/docs/ecosystem/databases/libsql

Run this command to add libSQL persistence to an existing Flue project.

```bash
flue add database libsql
```

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

### Add vitest-evals blueprint

Source: https://flueframework.com/docs/ecosystem/tooling/vitest-evals

Install the vitest-evals setup blueprint into an existing Flue project.

```bash
flue add tooling vitest-evals
```

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

### GET Callback API Request

Source: https://flueframework.com/docs/ecosystem/channels/salesforce-marketing-cloud

Example of the raw HTTP request structure for retrieving callback information from the Salesforce Marketing Cloud API.

```http
GET /platform/v1/ens-callbacks/{callbackId}
Authorization: Bearer <access token>
```

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

### start(options: StartOptions)

Source: https://flueframework.com/docs/reference/agent-api

Initializes the Flue runtime environment. Returns a Flue handle that allows for graceful shutdown and cleanup.

```APIDOC
## start(options: StartOptions)

### Description
Initializes the Flue runtime for standalone Node.js environments. This function configures agents, persistence, and providers, returning a handle to manage the runtime lifecycle.

### Parameters
- **options** (StartOptions) - Required - Configuration object for the runtime.
  - **agents** (readonly StartAgentEntry[]) - Required - The agents this runtime serves.
  - **db** (PersistenceAdapter) - Optional - Persistence adapter (defaults to in-memory SQLite).
  - **env** (Record<string, string | undefined>) - Optional - Runtime environment variables (defaults to process.env).
  - **providers** (readonly Provider[]) - Optional - Pi providers to register.

### Returns
- **Promise<Flue>** - A promise that resolves to a Flue handle containing `stop()` and `[Symbol.asyncDispose]()` methods.

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

const flue = await start({
  agents: [Reporter],
  providers: [anthropicProvider()],
});

// Cleanup
await flue.stop();
```
```

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

### Install OpenTelemetry dependencies

Source: https://flueframework.com/docs/ecosystem/tooling/opentelemetry

Install the required Flue OpenTelemetry adapter and the OpenTelemetry API package.

```bash
pnpm add @flue/opentelemetry @opentelemetry/api
```

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

### Command synopsis

Source: https://flueframework.com/docs/cli/init

The command structure for initializing a project.

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

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

### Resources Signal Example

Source: https://flueframework.com/docs/reference/agent-api

Example of a resources signal emitted when the set of available skills changes.

```xml
<signal type="resources" resource="skill">
New skill available:
- **refunds** — Process refund requests against the orders API.
All available skills: faq, refunds
</signal>
```

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

### Build and Run Container

Source: https://flueframework.com/docs/ecosystem/deploy/docker

Commands to build the image and start the container with an init process for proper signal handling.

```bash
docker build -t flue-agents .
docker run --init -p 8080:8080 -e ANTHROPIC_API_KEY=sk-... flue-agents
```

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

### Install Flue React dependencies

Source: https://flueframework.com/docs/guide/react

Install the required packages to enable Flue integration in a React project.

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

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

### Install Flue dependencies

Source: https://flueframework.com/docs/guide/getting-started/index.md

Installs the necessary packages for Vite-based build pipelines and Hono server integration.

```bash
npm install @flue/vite hono vite
```

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

### Run Container with Environment Variables

Source: https://flueframework.com/docs/ecosystem/deploy/docker

Example of passing model provider keys and configuration via environment variables at runtime.

```bash
docker run --init -p 8080:8080 \
  -e MODEL_SPECIFIER=anthropic/claude-sonnet-4-6 \
  -e ANTHROPIC_API_KEY=sk-... \
  flue-agents
```

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

### Resources signal example

Source: https://flueframework.com/docs/reference/agent-api/index.md

Example of a resources signal indicating a new skill availability and the current roster.

```plaintext
<signal type="resources" resource="skill">  
New skill available:
- **refunds** — Process refund requests against the orders API.  
All available skills: faq, refunds  
</signal>
```

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

### Add Postgres blueprint

Source: https://flueframework.com/docs/ecosystem/databases/postgres

Run this command to install the necessary dependencies and generate the initial database configuration.

```bash
flue add database postgres
```

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

### Evaluate Agent In-Process

Source: https://flueframework.com/docs/guide/evals

Uses the @flue/runtime/node start() function to boot the agent within the test process. Requires calling start() once per test file and stopping it after tests complete.

```typescript
import { init } from '@flue/runtime';
import { start } from '@flue/runtime/node';
import { afterAll, expect, it } from 'vitest';
import { ServiceStatus } from '../agents/service-status.ts';

const flue = await start({ agents: [ServiceStatus] });
achterAll(() => flue.stop());

it('checks live service status before answering', async () => {
  const toolsCalled: string[] = [];

  // No id: init() mints a fresh conversation for this case.
  const agent = init(ServiceStatus);
  const receipt = await agent.dispatch('Is the checkout service currently operational?');
  const reply = await agent.read(receipt, {
    onEvent: (chunk) => {
      if (chunk.type === 'tool-input') toolsCalled.push(chunk.toolName);
    },
  });

  expect(reply.text).toContain('operational');
  expect(toolsCalled).toContain('get_service_status');
});
```

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

### GET /:id

Source: https://flueframework.com/docs/reference/streaming-protocol/index.md

Reads the conversation history or incremental updates.

```APIDOC
## GET /:id

### Description
Reads the conversation. The 'view' query parameter determines the output: 'history' (default) returns a materialized snapshot, while 'updates' returns incremental chunks.

### Method
GET

### Endpoint
/:id

### Parameters
#### Query Parameters
- **view** (string) - Optional - The type of data to retrieve: 'history' or 'updates'.
```

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

### Initialize Flue Project

Source: https://flueframework.com/docs/ecosystem/deploy/github-actions/index.md

Commands to create a new directory, initialize npm, and install required runtime and CLI dependencies.

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

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

### GET /:id/attachments/:attachmentId

Source: https://flueframework.com/docs/guide/routing

Downloads the bytes for a specific attachment.

```APIDOC
## GET /:id/attachments/:attachmentId

### Description
Downloads one attachment’s bytes.

### Method
GET

### Endpoint
/:id/attachments/:attachmentId

### Parameters
#### Path Parameters
- **id** (string) - Required - The caller-chosen identifier for the conversation.
- **attachmentId** (string) - Required - The identifier for the specific attachment.
```

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

### GET /:id

Source: https://flueframework.com/docs/guide/routing

Retrieves a snapshot, updates, or live stream of the conversation.

```APIDOC
## GET /:id

### Description
Reads the conversation, providing a snapshot, updates, or a live stream.

### Method
GET

### Endpoint
/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The caller-chosen identifier for the conversation.
```

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

### Initialize a Flue project

Source: https://flueframework.com/docs/cli/init

Basic usage of the init command to scaffold a project skeleton.

```bash
flue init                                  # prompt for everything, scaffold into the current directory
flue init ./my-agent-app                   # prompt, scaffold into ./my-agent-app (created if missing)
flue init --target node                    # local-run skeleton, no prompts
flue init --target node --deploy           # Node server skeleton
flue init ./bot --target cloudflare        # Cloudflare skeleton (--deploy implied)
flue init --target node --force            # scaffold into a non-empty directory, overwrite flue.config.*
```

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

### Create Turso database and tokens

Source: https://flueframework.com/docs/ecosystem/databases/turso

Use the Turso CLI to provision a new database and generate the required authentication tokens.

```bash
turso db create flue-agents
turso db show --url flue-agents      # → TURSO_DATABASE_URL (libsql://…)
turso db tokens create flue-agents   # → TURSO_AUTH_TOKEN
```

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

### Configure Vite with flueWorkerConfig

Source: https://flueframework.com/docs/reference/configuration/index.md

Example usage of flueWorkerConfig within a vite.config.ts file.

```ts
// vite.config.ts
import { cloudflare } from '@cloudflare/vite-plugin';
import { flue, flueWorkerConfig } from '@flue/vite';

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

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

### Define SKILL.md Content

Source: https://flueframework.com/docs/guide/skills

Example of the frontmatter and instruction body for a skill definition.

```markdown
---
name: refunds
description: Process a customer refund request end-to-end. Use when a customer asks for a refund or disputes a charge.
---

Follow this procedure for every refund request:

1. Confirm the order ID and the reason for the refund.
2. Read `POLICY.md` and check the eligibility rules for that reason.
3. If eligible, issue the refund with the `issue_refund` tool and confirm the amount to the customer.
4. If not eligible, explain which rule applies and offer the alternatives listed in the policy.
```

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

### Configure Environment Variables

Source: https://flueframework.com/docs/ecosystem/deploy/node

Commands to set up the .env file and update .gitignore.

```bash
cat > .env <<'EOF'
OPENAI_API_KEY="your-api-key"
EOF

printf '\n.env\n' >> .gitignore
```

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

### Build and deploy commands

Source: https://flueframework.com/docs/ecosystem/deploy/cloudflare/index.md

Standard commands for local development, building the Worker output, and deploying to Cloudflare.

```bash
# Local development (reads local variables from .dev.vars or .env)
npx vite dev

# Build the deployable Worker output
npx vite build

# Configure a deployed secret interactively, then deploy the built output
npx wrangler secret put ANTHROPIC_API_KEY
npx wrangler deploy
```

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

### Preview production build

Source: https://flueframework.com/docs/guide/deploy

Command to serve the built artifact locally to verify production behavior before deployment.

```bash
vite preview
```

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

### Task Delegation Event Types

Source: https://flueframework.com/docs/reference/events

Definitions for task start and completion events.

```typescript
{
  type: 'task_start';
  taskId: string;
  prompt: string;
  agent?: string;
  cwd?: string;
}
{
  type: 'task';
  taskId: string;
  agent?: string;
  isError: boolean;
  result?: any;
  durationMs: number;
}
```

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

### Run Application in Production

Source: https://flueframework.com/docs/guide/node-target

Load environment variables from a .env file and execute the production server build.

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

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

### GET /:id

Source: https://flueframework.com/docs/reference/streaming-protocol

Retrieves a materialized snapshot of a conversation, including all messages and settlements.

```APIDOC
## GET /:id

### Description
Returns one materialized snapshot of the conversation, where every message is reduced to complete, render-ready parts. The default view is 'history'.

### Method
GET

### Endpoint
/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the conversation.

#### Query Parameters
- **view** (string) - Optional - The view type. Must be 'history' or 'updates'. Defaults to 'history'.

### Response
#### Success Response (200)
- **v** (number) - Snapshot schema version.
- **conversationId** (string) - The ID of the conversation.
- **offset** (string) - The durable head offset.
- **messages** (array) - List of FlueConversationMessage objects.
- **settlements** (array) - List of FlueConversationSettlement objects.
```

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

### Initialize Flue project dependencies

Source: https://flueframework.com/docs/ecosystem/deploy/cloudflare

Install the necessary runtime, SDK, and development dependencies for a Flue project on Cloudflare.

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

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

### Add Valkey blueprint

Source: https://flueframework.com/docs/ecosystem/databases/valkey

Command to install the Valkey database blueprint into a Flue project.

```bash
flue add database valkey
```

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

### Add Redis blueprint

Source: https://flueframework.com/docs/ecosystem/databases/redis

Run this command in the terminal to install the Redis blueprint and dependencies.

```bash
flue add database redis
```

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

### Launch and deploy a Flue application

Source: https://flueframework.com/docs/ecosystem/deploy/fly

Commands to initialize the Fly.io configuration and deploy the Dockerized Flue application.

```bash
fly launch
fly deploy
```

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

### Install Resend Channel

Source: https://flueframework.com/docs/ecosystem/channels/resend/index.md

Run this command to add the Resend channel to your Flue project.

```sh
flue add channel resend
```
Tokens:
Raw