AIエージェント自作フレームワーク「Flue」の仕組みと類似OSSとの違い

TypeScript で「自律的に動く AI エージェント」を作りたい、と考えたことはないでしょうか。Claude Code や Codex のように、ユーザーが目的だけを与えればエージェントが自分で手順を組み立て、シェルを叩き、ファイルを書き換える――そんな種類のエージェントです。

ところが実際に作ろうとすると、すぐに壁にぶつかります。LLM の API を呼ぶだけでは動きません。安全に任意コードを走らせるサンドボックス、サーバ再起動やデプロイから復旧する仕組み、複数セッションをまたぐ状態管理、Slack や GitHub からのイベント受信、デプロイ先の多様性――こうした「ハーネス（harness）」と呼ばれる足回りを自前で組むのは現実的ではありません。Mastra や Vercel AI SDK のような既存フレームワークも便利ですが、サンドボックスや耐久実行は「ユーザーが必要に応じて組み立てる」前提のものが多いのが実情です。

そこで登場したのが、Astro チーム（withastro）が 2026 年 5 月にパブリックローンチした OSS フレームワーク Flue です。Flue は「ハーネスをフレームワークの第一級プリミティブにする」という設計思想を掲げ、サンドボックスと耐久実行を最初から組み込みで提供します。GitHub のスター数は 6,968（2026 年 6 月時点）と、パブリックローンチから約 2 ヶ月の新興 OSS としては高ペースで支持を集めています。

本記事では、Flue が解決しようとしている課題、主要な構成要素、Mastra や Vercel AI SDK との違い、そして採用すべきケースと見送るべきケースを、公式ドキュメントと README ベースで整理します。読み終わったときに、「自プロジェクトに Flue を採用すべきか」を判断できる材料が揃っていることを目指します。

Flueとは何か

Flue は、公式リポジトリで「The sandbox agent framework.」と紹介されている TypeScript 製の OSS フレームワークです。README では「The Agent Harness Framework」を、公式サイトでは「The Open Agent Framework」をタグラインとして掲げており、いずれも「ハーネス層」がフレームワークの中心であることを強調しています。

提供元は Astro と同じ Organization withastro です。Astro チームが新たに送り出した OSS という背景から、ドキュメント整備や設計の一貫性に一定の信頼が置けるリポジトリと位置づけられます。

Agent = Model + Harness という思想

Flue の公式サイトには、エージェントを次のように定義する一文があります。

Agent = Model + Harness

出典: Flue 公式サイト

つまり「モデル（LLM）」と「ハーネス（モデルを取り囲んで自走可能にする層）」の組み合わせがエージェントである、という立場です。多くの既存 SDK は「Model」側、すなわちプロバイダ非依存 API やモデルルーティングを充実させてきました。一方の Flue は「Harness」側――サンドボックス・セッション・ツール・スキル・耐久実行・チャネルといった足回り――を第一級のプリミティブとして提供します。

README のサブタイトルも次のように、ハーネス指向を明確にしています。

Not another SDK. Build autonomous agents and powerful AI workflows with Flue's programmable TypeScript harness.

出典: withastro/flue README

リポジトリ基本情報

執筆時点（2026 年 6 月 30 日）のリポジトリ情報は以下のとおりです。

スター数 6,968 はパブリックローンチから 2 ヶ月弱の OSS としては高水準です。fork ではない独立リポジトリで、アーカイブもされていません。Apache-2.0 ライセンスのため商用利用にも比較的扱いやすい条件で公開されています。

「ハーネス」とは何か

「ハーネス（harness）」は本記事の中心概念のため、初出としてここで整理します。Flue におけるハーネスとは、LLM そのものではなく「LLM を取り囲んで自律的に動作させるためのランタイム層」を指します。具体的には次のような責務を負います。

• セッション（会話履歴）の永続化
• ツール呼び出しの実行と結果の取り回し
• スキル（再利用可能な指示書）の解決
• サンドボックス（シェル / ファイルシステム）の提供
• 耐久実行（durable execution）による中断・復旧
• HTTP / イベント駆動のエントリポイント

これらを「アプリ側で都度組み立てる」のではなく、「フレームワークが提供する」ことが Flue の発想です。

Flueが解決しようとしている課題

Flue の README は、最初のエージェントが置かれている現状について次のように述べています。

The first agents were built with raw LLM API calls. This worked for simple chatbots and scripted tasks, but not much else. Agents like Claude Code and Codex broke the mold. These were real agents. Autonomous.

出典: withastro/flue README

つまり「LLM API を直に叩くだけのエージェント」と「Claude Code や Codex のような真の自律エージェント」は、構造的に別物だという立場です。Flue は後者――任意のモデル、任意のホスト上で、自律的に動くエージェント――を作れるようにすることを目指しています。

raw LLM API では届かない領域

LLM API を直接呼ぶだけのエージェントは、以下のようなユースケースで限界に当たります。

• 会話を複数セッションにまたいで継続したい（履歴の永続化が必要）
• エージェントに「行動」を許可したい（ツール呼び出し・コマンド実行）
• 任意コード実行を「安全に」させたい（サンドボックス分離）
• サーバ再起動やネットワーク切断から「自動で」復旧させたい
• Slack や GitHub などのイベントを「検証付きで」受けたい
• 同じエージェントを Node.js でも Cloudflare Workers でも動かしたい

これらをすべてアプリ側で組むのは大きな実装負荷です。Flue はこのギャップを埋めるために、ハーネス層を標準装備しました。

自律エージェント構築で発生する 5 つの課題

公式ドキュメントの構成からは、Flue が主に次の 5 つの課題を「フレームワーク内で解決する」ことを掲げていると読み取れます。

1. サンドボックス: シェルやファイルシステムを安全に触らせる仕組み
2. 耐久実行（durable execution）: 再起動やデプロイから状態を失わず復旧する仕組み
3. セッション持続: 会話履歴・トポロジ・復旧用ファクトの永続化
4. ツール接続: 型付き API アクション・MCP サーバとの統合
5. デプロイ先の多様性: Node.js / Cloudflare Workers / CI 等への単一コードでのデプロイ

次の章では、これら 5 つの課題がフレームワーク内でどう実装されているかを、主要構成要素ごとに見ていきます。

Flueの主要構成要素

Flue は大きく分けて 5 つのプリミティブで構成されています。Agents・Workflows・Sandboxes・Durable Execution・Skills です。それぞれの役割と、Flue ならではの設計判断を見ていきます。

Agents（defineAgent）

Agent は Flue における中心的なプリミティブです。defineAgent() で宣言的に定義し、ファイル名がエージェントの識別子になります（例: agents/joke-teller.ts → joke-teller）。

公式ドキュメントには、最も小さな Agent 定義の例が次のように示されています。

import { defineAgent, type AgentRouteHandler } from '@flue/runtime';

export const description = 'Tells a short joke in response to each message.';

export const route: AgentRouteHandler = async (_c, next) => next();

export default defineAgent(() => ({
  model: 'anthropic/claude-haiku-4-5',
  instructions: 'Tell a short joke in response to each message.',
}));

出典: Flue Docs - Building Agents

設定項目には model / instructions / tools / skills / sandbox / cwd / route などがあり、エージェントごとに独立した ID が付与されます。この ID で会話履歴と状態が紐付けられるため、セッションを跨いだ継続的なやり取りが可能になります。

raw LLM API との差分として、Agent は以下を最初から備えます。

• 会話履歴の永続化
• ツール・アクション・スキルによる「行動できる能力」
• サンドボックス・cwd・DB 等の環境設定
• 認証付き HTTP ルーティング
• イベント駆動（Slack / GitHub などのチャネル）

Workflows（defineWorkflow）

Workflow は Agent と対になる、有限・検査可能なオペレーションのためのプリミティブです。背景タスク・ドキュメント変換・レビュー・CI など、「入力 → 出力の一回完結」に該当する用途で使います。

Agent との対比は次のように整理できます。

Workflow は defineWorkflow() で定義し、run({ harness, input }) のなかで harness.session() を介してモデルを呼びます。詳しくは Flue Docs - Workflows を参照してください。

Sandboxes（3 種類のサンドボックス）

Flue の最大の差別化要素は、サンドボックスがフレームワークに組み込まれている点です。公式ドキュメントによれば、サンドボックスは 3 種類用意されています（Flue Docs - Sandboxes）。

Local Sandbox を指定する場合の最小コード例は次のとおりです。

import { defineAgent } from '@flue/runtime';
import { local } from '@flue/runtime/node';

export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  sandbox: local(),
  cwd: '/srv/checkouts/catalog-service',
  instructions: 'Inspect the requested change and run only relevant validation.',
}));

出典: Flue Docs - Sandboxes

設計原則として公式ドキュメントは「Choose the narrowest sandbox that supports the task」――タスクに必要な最小限のサンドボックスを選ぶこと――を強調しています。セキュリティ境界は ①会話履歴の永続化 ②ワークスペース永続化 ③API / 認証情報アクセス の 3 軸で分離して設計されており、用途に応じてどこまで権限を渡すかを段階的に絞れる構成です。

Durable Execution（耐久実行）

Flue の 2 つ目の核心機能が、Durable Execution（耐久実行）です。サーバの再起動、デプロイ、ネットワーク切断、予期せぬ失敗から、エージェントを安全に復旧させる仕組みを指します。

仕組みの中核は「canonical conversation stream」と呼ばれる正規化された会話ストリームです。ここに以下が保存されます。

• model-visible messages（モデルに見える形のメッセージ）
• assistant output（アシスタントの出力）
• tool calls and results（ツール呼び出しと結果）
• compaction（履歴の要約化）
• topology（並列・分岐構造）
• recovery facts（復旧に必要な事実）

添付ファイル（attachments）は不変ストアに分離して保存され、復旧時の整合性を保ちます。復旧時の挙動は次の 3 つの原則に従います。

1. すでに完了した出力は再実行しない
2. durable delta から部分出力を継続する
3. 完了済みのツール結果は再利用する

永続化先は PersistenceAdapter（src/db.ts または .flue/db.ts）を通じてアプリ側 DB に接続します。Node.js では新しいプロセスを起動して復旧、Cloudflare では Durable Objects が自動で復旧を担います。

なお Workflow の方は中断された run を「終了扱い」とし、関数の途中再開はしません。Agent と Workflow で復旧の戦略が非対称になっている点は、設計上の重要な分岐です。詳細は Flue Docs - Durable Execution を参照してください。

Skills（再利用可能な指示書）

Skill は「再利用可能な指示書」をディレクトリ単位でまとめる仕組みです。Skill 自体は「行動する能力」を持たず、行動はツールやサンドボックスが担います。Skill が提供するのは、「特定タスクをこなすために必要な手順・前提・コツ」をマークダウンで記述した知識資産です。

SKILL.md をディレクトリに配置し、frontmatter に次の 2 項目を書きます。

• name: 小文字英数ハイフン、64 文字以内。ディレクトリ名と一致が必須
• description: 1024 文字以内。必須

Skill のロード方法は 2 通り用意されています。

1. Imported: import skill from '../skills/foo/SKILL.md' with { type: 'skill' } のように import attribute で取り込み、skills 配列に登録
2. Workspace-discovered: <cwd>/.agents/skills/ に置けば、コード変更なしで自動ロード

後者は、エージェントが操作するワークスペース側で Skill を更新・追加でき、コード反映を待たずに振る舞いを調整できる設計です。

パッケージ構成とデプロイ先

Flue は単一の巨大パッケージではなく、責務ごとに分割された 5 つの公式パッケージで構成されています（withastro/flue README）。

サンドボックスや永続化アダプタが別パッケージに切り出されているため、必要なものだけを取り込めば軽量に始められる構成です。

対応するデプロイ先は次のとおりです。

• Node.js
• Cloudflare Workers
• GitHub Actions
• GitLab CI/CD
• Daytona
• Render

公式サイトでは「write once, deploy anywhere, use any LLM」というコアコピーが掲げられており、コードベースを変えずに複数の実行環境へデプロイできる点が訴求されています。Node.js / Cloudflare Workers が両方サポートされている点は、エッジ実行を視野に入れているプロジェクトでは大きな評価軸になります。

類似OSSとの違い

ここまで Flue 単体の特徴を見てきましたが、AI エージェント関連の TypeScript フレームワークは他にもあります。代表的な選択肢である Mastra と Vercel AI SDK との違いを整理しておきます。なお、いずれが優れているかではなく「どんな用途にどちらが向くか」という観点で比較します。

Mastraとの違い

Mastra は、25.6k stars を集める TypeScript ベースの AI フレームワークです。タグラインは "The modern TypeScript framework for AI-powered applications and agents" で、モデルルーティング（40+ プロバイダ）・グラフ型ワークフロー・評価・観測まで「全部入り」を志向しています。

Flue との対比は次のように整理できます。

要旨としては、Mastra は「モデル抽象 + オーケストレーション + 観測」を一体で提供する DX 重視の総合フレームワークです。一方 Flue は「エージェントを安全に走らせるためのハーネス」に焦点を絞り、モデル抽象は最小限にとどめている、と整理できます。

Vercel AI SDKとの違い

Vercel AI SDK は、25.2k stars を集める TypeScript 用 AI ツールキットです。タグラインは "The AI Toolkit for TypeScript" で、プロバイダ非依存 API と React / Vue / Svelte / Next.js 向けの UI フックを提供しています。

Vercel AI SDK は「UI を含む AI アプリを素早く構築するためのツールキット」、Flue は「UI を持たずヘッドレスで自律実行するエージェントのためのハーネス」、と棲み分けられます。サンドボックスを「フレームワークの一部」として持っているかどうかが、両者の構造的な分岐点です。

3 製品比較表

3 つのフレームワークの違いを 1 枚にまとめると、次のようになります。

差分の核は「サンドボックスをフレームワーク自身が持つかどうか」です。Mastra と Vercel AI SDK は「サンドボックスはユーザーが組み立てる前提」のアーキテクチャを採用しています。Flue は逆に「サンドボックスがフレームワーク内蔵」であり、これが後発でありながら短期間で 7k stars を集めている主因と考えられます。

Flueを採用すべきケース・見送るべきケース

ここまでの整理を踏まえ、Flue が向くケースと別の選択肢を検討すべきケースを、意思決定に直接使える形でまとめます。

Flueの採用が向くケース

以下のいずれかに該当する場合、Flue は有力な選択肢になります。

1. Claude Code / Codex のような「ユーザーが目的だけを与え、エージェントが手順を組んで自走する」タイプを TypeScript で作りたい
2. セッションを跨いで継続するエージェントが必要（durable execution が欲しい）
3. シェルやファイルシステムを安全に触らせたい（Virtual Sandbox が標準で用意されている）
4. Cloudflare Workers / Node.js / GitHub Actions など、複数のホストで同じコードを動かしたい
5. Slack / Teams / Discord / GitHub などのイベント駆動エージェントを作りたい

別の選択肢を検討すべきケース

逆に、以下のようなケースでは他のフレームワークの方が適している可能性があります。

1. UI ベースのチャットアプリを Next.js で素早く作りたい: Vercel AI SDK の方が UI フックが揃っており、ページ単位の実装まで素早く到達できる
2. 40+ モデルプロバイダを横断するモデルゲートウェイ的な機能が中心: Mastra のモデルルーティングが手厚い
3. エンタープライズ運用実績を最優先したい: Flue は stars 7k 規模でパブリックローンチから約 2 ヶ月、安定版（1.0 GA）も未リリースの新興 OSS。stability を最優先する場合は様子見も合理的な選択
4. 既に社内でハーネス相当（サンドボックス + 復旧機構）を内製済み: その上に薄い SDK だけ欲しい場合、Flue は機能過多になる可能性がある

メンテナンス状況の健全性

新興 OSS を採用するうえで気になる「メンテナンスは続きそうか」という観点について、公開情報から判断できる事実を整理します。

最終 push が当日であり、open issues が 4 件と少なく、提供元が Astro チームという後ろ盾を持っている点を踏まえると、現時点のメンテナンス状況は健全な部類と評価できます。一方でパブリックローンチから日が浅く、安定版 1.0 GA がまだリリースされていないため、エンタープライズ運用で求められる長期 LTS や互換性ポリシーがどう運用されるかは、今後の観察対象です。

まとめ

ここまでの内容を、採用判断のチェックリストとして整理しておきます。

• Flue は何か: Astro チームが公開した TypeScript 製の「Agent Harness Framework」。Apache-2.0、stars 6,968、パブリックローンチから約 2 ヶ月（2026 年 5 月 1 日ローンチ、執筆時点）
• 何を解決するか: Claude Code / Codex のような自律エージェントを作るために必要な「ハーネス層」――サンドボックス・耐久実行・セッション・ツール接続・チャネル・デプロイ多様性――をフレームワークの第一級プリミティブとして提供する
• 主要構成要素: Agents / Workflows / Sandboxes / Durable Execution / Skills の 5 つ
• 最大の差別化要素: サンドボックスがフレームワーク内蔵である点。Virtual / Local / Remote の 3 種から「タスクに必要な最小限」を選ぶ設計
• 類似 OSS との棲み分け: Mastra は「モデル抽象 + 総合」、Vercel AI SDK は「UI を含む AI アプリ」、Flue は「ヘッドレス自律エージェントのハーネス」
• 採用判断の軸: 自律エージェント / 耐久実行 / サンドボックス / マルチホストデプロイ / イベント駆動 のいずれかが要件にあれば Flue は有力。UI ファースト・モデルゲートウェイ・実績重視（安定版 1.0 GA 待ち）のケースは別の選択肢を検討

次の一歩としては、Flue 公式ドキュメント を読み、自プロジェクトの要件に対して defineAgent() と defineWorkflow() のどちらが主役になるか、どのサンドボックスを使うかを設計レベルで見立てるのがおすすめです。本記事で整理した「採用判断の軸」が、その設計検討の出発点として役立てば幸いです。