Flue

Flue is a TypeScript framework for building AI agents using the harness-driven architecture popularized by coding agents. An application is a set of agents (continuing instances that accept messages over time), workflows (finite agent-backed operations), tools (application code the model can call), skills (reusable instructions), and channels (verified provider ingress). Flue mounts a Hono HTTP surface and runs on Node.js or Cloudflare Workers; on Cloudflare it uses the Agents SDK and Durable Object SQLite for durable runs and sessions.

CRITICAL — documentation first. Flue's API surface is young and version-sensitive. Before writing or editing Flue code, confirm the exact API against the installed version: run npx flue docs (bundled offline docs) or read https://flueframework.com/docs. Do not invent APIs, bindings, file layouts, or runtime behavior. If something is not in the docs, omit it or mark it as a recommendation.

CRITICAL — schema library. This project standardizes on Zod (v4) for all validation, see reference/validation-zod.md for the exact pattern and the z.toJSONSchema() fallback.

CRITICAL — Flue manages its own persistence. Flue stores session/run state in Durable Object SQLite automatically on Cloudflare (or via a db.ts adapter on Node) — never wire an external database in as Flue's session store. Keep your business data in your own application database. See reference/database.md.

Sub-skills

Task	File
Where files go, `src/` vs `.flue/`, naming	reference/project-layout.md
HTTP surface, `src/app.ts`, middleware, mounting `flue()`	reference/routing.md
Hono + Workers entrypoint, assets, request flow	reference/hono-workers.md
`createAgent`, profiles, ids, sessions, HTTP exposure	reference/agents.md
`run()`, `FlueContext`, sessions, result schemas	reference/workflows.md
`defineTool`, parameters, safe interfaces	reference/tools.md
Flue skills (`SKILL.md`, `with { type: 'skill' }`)	reference/skills.md
Subagent profiles, delegation boundaries	reference/subagents.md
Verified provider ingress, dispatch, idempotency	reference/channels.md
Zod validation, type inference, Flue schema slots	reference/validation-zod.md
Flue persistence + your own business database	reference/database.md
`flue build`, wrangler, migrations, secrets, deploy	reference/deployment-cloudflare.md
`ctx.log`, `observe()`, OTel/Braintrust/Sentry	reference/observability.md
vitest-evals, local dev, pre-deploy checks	reference/testing.md
Auth boundaries, secrets, prompt injection, isolation	reference/security.md
End-to-end copy-pasteable examples	reference/examples.md

Step-by-step task recipes live in workflows/. Start there for a concrete job; drop into reference/ for depth.

Quick decision tree

Need a continuing, conversational instance that accepts messages over time?  → agents
Need a finite, one-shot agent-backed job (summarize, review, transform)?      → workflows
Need the model to call your code (DB lookup, API call, action)?               → tools
Need reusable instructions/process the agent loads on demand?                 → skills
Need a specialist the parent agent delegates to (no public endpoint)?         → subagents
Need to accept verified webhooks/events from an external provider?            → channels
Need to validate input/output shapes?                                         → validation-zod
Need durable business data (customers, tickets, payments)?                    → database
Shipping to Cloudflare Workers?                                               → deployment-cloudflare

Default implementation philosophy

Prefer the smallest unit that fits: a tool for a discrete action, a workflow for a finite job, an agent only when conversation continuity matters, a subagent for bounded delegation. Validate every trust boundary. Keep Flue's session state separate from durable business data. Expose nothing over HTTP without an explicit route export and middleware. Go through Flue's HTTP admission boundary (or dispatch) — never call run() directly.

Minimal working example

// src/agents/hello.ts
import { createAgent } from '@flue/runtime';

export const description = 'Tells a short hello-world joke.';

export default createAgent(() => ({
  model: 'anthropic/claude-haiku-4-5',
  instructions: 'Tell a short "hello world" engineering joke.',
}));

npx flue dev                 # watch-mode local server
npx flue connect hello demo  # interactive session against instance "demo"

Verification is required before completion

Every workflow recipe in this pack ends with a verification step. Do not report a task done until you have run it. The baseline gate for any Flue change:

npx flue build --target <node|cloudflare>   # must build clean
# then exercise the affected route, e.g.:
curl "http://localhost:3583/workflows/<name>?wait=result" \
  -H 'Content-Type: application/json' -d '{ ... }'

Anti-patterns (do not do)

Inventing Flue APIs from memory instead of checking npx flue docs / the live docs.
Wiring an external database as Flue's session/run store — that is DO SQLite (automatic on Cloudflare) or a db.ts adapter (Node).
Deploying the source wrangler.jsonc instead of the generated dist/<name>/wrangler.json.
Adding an agent/workflow without a uniquely-tagged new_sqlite_classes migration.
Calling a workflow's run() directly from app code.
Exposing an agent/workflow without a route export and auth middleware.
One giant skill file or overloaded CLAUDE.md — use progressive disclosure.

skills/flue