flue

name	flue
description	Expert on Flue — the open-source TypeScript framework (by the Astro team) for building durable, autonomous AI agents and workflows on the Pi harness. Use when building Flue agents, workflows, channels, tools, or skills; deploying agents to Cloudflare/Node/AWS/etc.; or using the flue CLI/SDK/React hooks. Triggers on mentions of Flue, flueframework, @flue/runtime, @flue/cli, @flue/sdk, createAgent, flue add, durable agents.
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, WebFetch

Flue — The Open Agent Framework

Flue is an open-source TypeScript framework for building durable, autonomous AI agents and the workflows around them, from the team behind Astro. Pitch: "Build durable AI agents and workflows with a programmable TypeScript harness. Write once, deploy anywhere, use any LLM." Built on the Pi agent harness, Vite for builds, and Durable Streams for the replayable event log.

Overview

• Agents — stateful, long-lived; you fill a harness with context (model, tools, skills, sandbox, instructions, subagents) and point a model at it — "a model pointed at a harness, not a script."
• Workflows — finite, deterministic run(...) functions you author start-to-finish; each invocation gets a runId (not resumable).
• Channels — receive verified inbound provider events (Slack mention, GitHub issue, Stripe webhook) and dispatch them to an agent.
• Tools / Skills / Subagents / MCP — typed actions, on-demand SKILL.md capability packs, named delegates, and MCP server connections.
• Durable — every session is recorded to a Durable Stream; on restart another process replays the log and resumes. "Agents can't die when the server goes down."
• Open & AI-first — any model/sandbox/deploy target; designed to be driven by a coding agent (flue add hands your agent a Markdown blueprint, "like shadcn for agents").

Quick Start

npm install @flue/runtime
npm install --save-dev @flue/cli
echo 'ANTHROPIC_API_KEY="your-api-key"' > .env
npx flue init --target node        # or: --target cloudflare

// agents/hello-world.ts — default export registers the agent as `hello-world`
import { createAgent } from '@flue/runtime';

export default createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',   // provider-prefixed model id
  instructions: 'Tell a funny "hello world" engineering joke.',
}));

npx flue connect hello-world local   # interactive session (Node target)

Core Concepts

• Harness-first: agents are context, not scripts — "an agent without a harness is not a real agent."
• Models are provider-prefixed string ids (anthropic/claude-sonnet-4-6, openai/gpt-5.5, cloudflare/@cf/...) via Pi's unified API; output validated with Valibot schemas.
• Durability differs by target: durable-by-default on Cloudflare (Durable Objects); opt-in on Node via a persistence adapter.

Documentation

Getting started

• Why Flue? — the three design principles
• Quickstart — install, first agent, run locally
• What is an agent? / Durable Agents — mental model + durability

Guides

• Building Agents · Workflows · Subagents
• Tools · Skills · Channels · Routing
• Models · Database · Sandboxes · Observability
• Project Layout · React · Targets: Cloudflare / Node

Reference

• CLI — init, dev, run, connect, build, add, update, logs, docs
• SDK — createFlueClient, client.agents, client.workflows, client.runs, events, errors
• API Reference — agent, routing, provider, sandbox, data-persistence, channel APIs, errors
• Configuration — flue.config.ts

Ecosystem (first-party adapters)

• Deploy (10): Cloudflare, AWS, Docker, Fly, Node, Railway, Render, SST, GitHub Actions, GitLab CI
• Channels (17): Slack, GitHub, Discord, Stripe, Linear, Telegram, WhatsApp, Notion, Teams, Twilio, Zendesk, Intercom, Resend, Shopify, Messenger, Google Chat, Salesforce
• Sandboxes (10): Cloudflare, E2B, Daytona, Modal, Vercel, boxd, exe.dev, islo, Mirage, Cloudflare Shell
• Databases (8): Postgres, Redis, MongoDB, MySQL, libSQL, Turso, Supabase, Valkey
• Tooling (3): OpenTelemetry, Braintrust, Sentry

Common Workflows

• Add an integration: npx flue add channel slack (or sandbox daytona, database postgres, tooling opentelemetry) — hands your coding agent a Markdown blueprint to wire it into your codebase. See flue add.
• Deploy to Cloudflare (durable by default): flue dev --target cloudflare locally, then build/deploy — see targets/cloudflare and deploy/cloudflare.
• Frontend integration: @flue/react useFlueAgent() / useFlueWorkflow() stream live data — see React guide.

Upstream Sources

• Documentation: https://flueframework.com/docs
• Repository: https://github.com/withastro/flue
• Offline docs: flue docs ships searchable offline docs for coding agents