---
title: "Flue 1.0 Betaとは何か ローカル検証で分かった新機能とQuickstartの注意点"
description: "AstroチームのエージェントフレームワークFlue 1.0 Betaを手元で動かし、init・build・runまでの挙動とハマりどころを記録した実装検証メモ。"
lang: "ja"
canonical: "https://llm-lab.dev/posts/flue-1-0-beta-local-check/"
source: "https://llm-lab.dev/posts/flue-1-0-beta-local-check.md"
publishedAt: "2026-06-18"
updatedAt: "2026-06-18"
category: "Flue"
tags:
  - "agent"
  - "typescript"
  - "astro"
---

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

import LinkCard from "../../components/LinkCard.astro";

> [!NOTE]
> この記事で確認したこと: Flue 1.0 BetaはNode 22環境で素直に導入でき、`flue build --target node`でサンプルWorkflowを検出してビルドできました。`flue run`はprovider APIキー未設定で想定どおり止まりますが、その前にrun IDや実行管理の動きが見えます。一方でQuickstart風の`npx flue init`は`--target`指定が必要で、最初の確認ではドキュメントの導線とCLI実仕様の差分を見ることが重要でした。

AIエージェントフレームワーク、[Flue](https://flueframework.com/)の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が何を中心に置いたフレームワークなのかも整理しています。

<LinkCard
  href="https://llm-lab.dev/posts/flue-framework-overview/"
  title="Flueを触る前に、まず何のフレームワークなのかを整理した"
  description=""
  siteName=""
  image="/images/posts/flue-framework-overview/heroImage.webp"
/>

## 環境とインストール

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

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

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

```bash
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で試す場合はこちらを選ぶ |

```ts
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を動かした記事も公開しています。

<LinkCard
  href="https://llm-lab.dev/posts/flue-framework-overview/"
  title="Flueを触る前に、まず何のフレームワークなのかを整理した"
  description=""
  siteName=""
  image="/images/posts/flue-framework-overview/heroImage.webp"
/>

<LinkCard
  href="https://llm-lab.dev/posts/flue-1-0-beta-issue-triage-agent/"
  title="Flue 1.0 BetaでGitHub Issueトリアージエージェントを動かしてみた"
  description=""
  siteName=""
  image="/images/posts/flue-1-0-beta-issue-triage-agent/heroImage.webp"
/>