Flue 1.0 Betaとは何かローカル検証で分かった新機能とQuickstartの注意点

AIエージェントフレームワーク、Flueの1.0 Betaが出ていたので、正直リリースノートを読むだけでは温度感がつかめず、手元で触ってみました。 Agent / Workflow / Channels がひとつのストーリーに揃った、というアナウンスだったので、まずはWorkflowのサンプルコードをそのまま動かすところから始めています。

Flue 1.0 Betaとは

Flue 1.0 Betaは、Astroの開発者が手がけるTypeScript製のAIエージェントフレームワークです。今回のBetaでは、単発のLLM呼び出しではなく、エージェントと決定的なワークフローを同じ基盤で扱い、外部サービスとの接続やUI、観測までを一つの構成にまとめる方向が明確になりました。

追加・拡張された主な要素は次のとおりです。

自律的な処理を担うAgentと、処理手順をコードで制御するWorkflow
SlackやGitHubなどのイベントをAgentへ渡すChannels
AgentやWorkflowの状態をUIへストリーミングする@flue/react
OpenTelemetry、Braintrust、Sentryなどへ接続するObservability
オフラインドキュメントや連携機能を追加するCLI

機能	役割	今回の確認範囲
Agent	ツールやスキルを持ち、自律的に課題を解く	概要確認のみ
Workflow	開発者が定義した手順で有限の処理を実行する	サンプルをビルドし、実行入口まで確認
Channels	Slack、GitHub、LinearなどのイベントをAgentへ接続する	未検証
React	`@flue/react`からAgentやWorkflowの状態を扱う	未検証
Observability	OpenTelemetryなどへ実行情報を接続する	未検証

触る前に、Flueが何を中心に置いたフレームワークなのかも整理しています。

Flueを触る前に、まず何のフレームワークなのかを整理した https://llm-lab.dev/posts/flue-framework-overview/

環境とインストール

Node 22系で、npm install @flue/runtime と npm install -D @flue/cli を素直に叩くだけで詰まりはありませんでした。CLIのバージョンも 1.0.0-beta.1 で固定されており、ここまでは想定どおりです。

インストールから実行までの再現手順

検証では、空のディレクトリでruntimeとCLIを導入し、Node向けの設定を生成してからWorkflowをビルドしました。流れは次のとおりです。

npm install @flue/runtime
npm install -D @flue/cli
npx flue init --target node
npx flue build --target node
npx flue run summarize --target node --payload '{"text":"FlueのWorkflowを短く要約してください"}'

initはflue.config.tsを生成します。次にsrc/workflows/summarize.tsへWorkflowを置くと、buildがファイルを自動検出します。最後のrunはモデルproviderのAPIキーを必要とするため、キーを設定していない環境ではモデル呼び出しの直前で停止します。

いきなりQuickstartと挙動がズレた

公式のスタートプロンプトは「npx flue init を実行してプロジェクトを作る」という体験を前提にした書き方になっています。ところが実際に打つと、こうなりました。

Missing required --target flag for init command.

--target node か --target cloudflare を明示しないと先に進めない仕様です。エラーメッセージ自体は親切で、使い方一覧もそのまま表示されるので詰まりとしては軽いのですが、「コピペしたプロンプトをコーディングエージェントに渡すだけで動く」という訴求とは、初手で少しズレている印象を受けました。--target node を付けて通したところ、生成されたのは次のだけの薄い flue.config.ts でした。

コマンド	結果	判断
`npx flue init`	`Missing required --target flag for init command.`で停止	Quickstartの記述だけではtargetが不足する
`npx flue init --target node`	`flue.config.ts`を生成	Nodeで試す場合の実行可能な形
`npx flue init --target cloudflare`	Cloudflare向けtargetを指定	Cloudflareで試す場合はこちらを選ぶ

import { defineConfig } from '@flue/cli/config';

export default defineConfig({
	target: 'node',
});

エージェントやワークフローのひな型自体は生成されないので、init はあくまで設定ファイルの土台作りに役割が絞られている、という理解で進めました。

Workflowサンプルはビルドまで素直に通る

ブログ記事内の summarize ワークフローのサンプルコードを src/workflows/summarize.ts にそのまま置いて flue build --target node を叩くと、ワークフローが自動検出され、ビルド自体は問題なく完了しました。CLIが src/workflows 配下を規約として読みにいく作りになっている点は、Astroのファイルベースルーティングに近い感覚で、違和感なく馴染みました。

ただしビルド時に MODULE_TYPELESS_PACKAGE_JSON の警告が出ています。package.json に "type": "module" を足していないとesm判定の再解析が走る、というNode側の一般的な注意ですが、betaのテンプレート自体がこの一手間を埋めていない点は、初回体験としては惜しいと感じました。

実行はAPIキー未設定で意図どおり止まる

flue run summarize --target node --payload '{"text": "..."}' を実行すると、ローカルでrun IDが発行され、SQLiteを使った実行管理が動いていることが分かるログが出ます。その後、想定どおり次のエラーで止まりました。

Error: Workflow failed: [internal_error] prompt failed: No API key for provider: anthropic

ここはAPIキーを渡していない自分の検証環境の都合なので不具合ではありません。注目したのは、エラーに至るまでの過程でrunごとのIDが見えたことです。記事中で説明されている「Durable Streamsによる追記専用ログを正とする」という設計が、ローカル実行の時点から実際に機能している様子がうかがえました。ただし、このログが具体的にどこにどう永続化されるのかまでは、今回の短い検証では追い切れておらず未検証です。

docsコマンドはオフラインで実際に効く

地味に良かったのが flue docs です。npx flue docs を打つだけで、APIリファレンスやチャンネル別ドキュメントなど110ページ分の一覧がオフラインで返ってきました。コーディングエージェントに作業させる前提のフレームワークなら、ネット越しに毎回ドキュメントを取りに行かせるより、こうしてローカルに検索可能な形で持たせておくほうが、エージェントの調査コストを下げる設計として筋が良いと感じます。

まとめ

短い時間での検証なので踏み込めた範囲は限定的ですが、initとbuildの間にQuickstartの体験とCLIの実仕様で小さなギャップがあること、ビルド自体はサンプルコードそのままで問題なく通ること、実行管理の土台にDurable Streamsらしき仕組みが見えることまでは確認できました。Agent側のサンプル（tools / skills / sandbox を絡めたフルセット）はAPIキーを用意したうえで別途試したいので、続きはまた別の記事にします。

概要だけでなくFlueのAgent、Skill、Sandboxの責務を整理した記事と、実際にGitHub IssueトリアージAgentを動かした記事も公開しています。

Flueを触る前に、まず何のフレームワークなのかを整理した https://llm-lab.dev/posts/flue-framework-overview/

Flue 1.0 BetaでGitHub Issueトリアージエージェントを動かしてみた https://llm-lab.dev/posts/flue-1-0-beta-issue-triage-agent/

Flue 1.0 Betaとは何かローカル検証で分かった新機能とQuickstartの注意点