Flue Framework 実践入門を読んで — 本番向け AI エージェントの 3 プリミティブ

417 著の Zenn 本『Flue Framework 実践入門 — AIエージェントを本番で動かす』を読みました。2026年6月に公開された無料の技術書で、約6万字。Getting Started から Linear 連携、設計の罠、Vercel eve との比較、Cloudflare 上の Observability まで一通りカバーしています。

エージェントを「ローカルで動いた」から一歩進めて、本番で耐える構成をどう組むか。Flue はその答えのひとつとして、Astro チームと Cloudflare が同時期に押し出してきたフレームワークです。ここでは、本書と公式ブログをもとに、印象に残った点を整理します。

https://zenn.dev/417/books/flue-framework-guide

Flue とは何か

Flue は、Astro チーム（withastro/flue）が開発した TypeScript 製のオープンソース AI エージェント・フレームワークです。2026年6月に 1.0 Beta がリリースされ、Cloudflare とも公式連携しています。

特徴的なのは設計思想です。エージェントの手順を if-else で組み立てるのではなく、エージェントが知っていること——モデル、スキル、サンドボックス、指示——を宣言すると、あとは自律的に動く、というアプローチです。「何をするか」をスクリプトするより、「何を知っているか」を定義する。

内部では Pi ハーネス（OpenClaw と同系の最小エージェント・ハーネス）の上に乗っています。Claude Code 系のハーネス駆動アーキテクチャを、TypeScript でプログラマブルに扱えるようにした、という位置づけです。

3 層で見るスタック

本書と Cloudflare の説明では、Flue を次の 3 層で理解するのがわかりやすいです。

ハーネス単体では解けない問題——プロセス落ちからの復帰、安全なコード実行、永続ファイルシステム——はプラットフォーム依存です。Flue は Cloudflare 向けに Agents SDK のプリミティブをそのまま使う設計になっています。

3 つのプリミティブ — Agents, Workflows, Channels

Flue の設計の肝は、Agents / Workflows / Channels を並列の概念として分けることです。本書の第3章のタイトルそのままですが、ここが他フレームワークとの差分にもなります。

Agents（エージェント）

永続的な会話・処理を担います。セッションを持ち、対話しながらタスクを進める単位です。Cloudflare にデプロイすると、1 エージェント = 1 Durable Object としてスケールします。

Workflows（ワークフロー）

有限の作業単位です。入力を受け取り、処理し、結果を返して終わる。バックグラウンドジョブや構造化された自動化向けで、セッション永続化はしません。Agent との役割分担がはっきりしているのがポイントです。

Channels（チャネル）

外部との接続口です。Webhook 受信、Slack / GitHub / Linear / Discord との統合を扱います。flue add channel slack のように CLI で追加でき、イベント検証やディスパッチのボイラープレートを肩代わりしてくれます。

典型的なプロジェクト構成は次のとおりです。

src/
  agents/      # 永続的な会話
  workflows/   # 有限の作業
  channels/    # Webhook 等
  app.ts       # Hono + flue() マウント

app.route('/', flue()) の 1 行で、ディレクトリ構造からルーティングが自動生成される、という説明が本書にあります。

内部動作 — Pi, Durable Streams, Sandbox

なぜ Durable Streams が要るか

エージェントの 1 ターンは「1 リクエスト」ではありません。ストリーミング、ツール呼び出し、人間承認、サブエージェント委譲——と長くなり、途中でプロセスが落ちるとメモリ上の状態が消えます。会話履歴は残っていても、ユーザーにはスピナーが回り続けるだけ、という壊れた体験になります。

Flue は append-only な実行ログ（Durable Streams） で各イベントを記録し、プロセスが死んでもログから途中再開できるようにしています。Cloudflare 上では Agents SDK の runFiber() / stash() / onFiberRecovered() がこれを支えます。

Sandbox と Code Mode

Flue には内蔵の仮想サンドボックスがあり、多くの用途ではこれで足ります。Cloudflare ターゲットでは @cloudflare/codemode（動的 Worker でのコード実行）や @cloudflare/shell（仮想ファイルシステム）も使えます。

ツールを大量に定義するより、コードを 1 本書かせて実行させる方がモデルにとって扱いやすい、という Cloudflare の Code Mode 思想とも一致しています。read / grep / diff 程度ならコンテナを起動せず Durable Object 内で済ませられる、という話は本番コストの面でも効きそうです。

実行環境 — Node.js と Cloudflare Workers

Flue のもうひとつの強みは、同じコードをターゲットを変えるだけでデプロイ先を切り替えられることです。

セットアップは公式 Quickstart のとおりです。

npm install @flue/runtime
npm install --save-dev @flue/cli
npx flue init --target node      # または --target cloudflare

Node.js は >= 22.19.0 が必要です。LLM は anthropic/claude-sonnet-4-6 や cloudflare/@cf/moonshotai/kimi-k2.6 のように指定し、Cloudflare モデルなら API キー不要で使える場合もあります。

本書の補章では、コードを変えずにインフラだけ Cloudflare に切り替える話や、Custom Spans で処理時間を計測する話、Compaction（AI の記憶圧縮）を Cloudflare 上で可視化する話まで踏み込んでいます。エージェントの中身が見えない問題を、運用面から潰していく構成です。

Linear Channel — 62 行の実装例

本書の第7章では、Linear 連携が具体的に書かれています。流れはシンプルです。

1. Data Change Events の Webhook を受信
2. Issue 作成イベントだけフィルタ
3. dispatch() で Agent に非同期渡し
4. Agent が要約を生成 → Linear REST API でコメント投稿

約 62 行で実装できる、と本書では紹介されています。Linear 専用に閉じず、同じ Channel パターンを他の Webhook にも当てはめられる、という汎用性の話でもあります。

Vercel eve との比較

2026年6月、Flue と Vercel eve がほぼ同時にベータリリースされました。API も概念もかなり似ています（createAgent / defineTool / channels / skills / sandbox など）。

本書の補章と、同日リリースの2つのフレームワークを比較する記事では、Vercel なら eve、Cloudflare なら Flue、プラットフォーム非依存なら Flue、という選び方が示されています。

私はブログも Cloudflare Pages で動かしているので、Agents SDK との統合がネイティブな Flue 側に自然に惹かれます。

まとめ

Flue は Pi ハーネス + 3 プリミティブ + マルチターゲットデプロイ をセットにした、本番寄りのエージェント・フレームワークです。

• 書き方: 手順をスクリプトするより、エージェントの文脈を宣言する
• 構成: Agent（永続）/ Workflow（有限）/ Channel（外部接続）を分ける
• 強み: Cloudflare とのネイティブ統合、Durable Streams による耐障害性、Channels による実務ツール連携

『Flue Framework 実践入門』は、概念の整理から手を動かすところ、本番運用の罠まで一通り読める入門書だと感じました。エージェントをプロトタイプから本番へ持っていく段階にいるなら、Zenn Book として無料で読めるので、まず目次だけでも眺めてみる価値はあると思います。

参考

• Flue Framework 実践入門 — AIエージェントを本番で動かす（Zenn Book）
• Bringing more agent harnesses and frameworks to Cloudflare, starting with Flue
• withastro/flue（GitHub）
• Getting Started | Flue
• Flue vs eve — 同日ベータリリースされた2つのTypeScript AIエージェントフレームワークを比較する