Flue 技术解读：把大模型装进 Agent Harness

一、Flue 到底是做什么的？

如果只用一句话概括：Flue 是一个 TypeScript Agent Harness 框架，用来构建可部署、可恢复、能调用工具和进入工作区执行任务的 AI Agent。 它把开发者平时零散拼起来的 LLM 调用、工具函数、上下文、沙箱、会话存储、HTTP 路由和部署目标，收进一个统一的工程模型里。

这和普通的“调一次模型拿一次回答”不一样。Flue 更关注的是让模型在一个持续上下文里工作：它可以先读文件，再调用工具，再根据结果继续行动，必要时把一部分任务交给子 agent，最后把结果返回给你的应用。

二、用户如何使用 Flue？

Flue 的“用户”需要分成两类：开发者和最终用户。开发者直接使用 Flue 写 agent；最终用户通常并不知道 Flue 的存在，而是通过产品里的聊天框、按钮、Webhook、队列任务或 CI 流程间接触发 agent。

npm install @flue/runtime
npm install --save-dev @flue/cli
npx flue init --target node

# 然后创建一个 agent，例如 agents/hello-world.ts
npx flue connect hello-world local

一个最小 agent 长什么样？

最小版本只需要模型和指令。文件名会成为 agent 名称，运行时会发现并加载它。

import { createAgent } from '@flue/runtime';

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

稍微像生产系统一点的 agent

真实项目通常会加上工具、技能、工作目录和沙箱。下面这个伪例子表达的是 Flue 的工程思路：让 agent 在一个受控环境里完成“代码仓库审查”。

import { createAgent } from '@flue/runtime';
import { local } from '@flue/runtime/node';
import reviewChecklist from '../skills/review-checklist/SKILL.md' with { type: 'skill' };
import { repositoryTools } from '../shared/repository-tools.ts';

export default createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  instructions: 'Review the change and report findings supported by evidence.',
  cwd: '/srv/repositories/catalog-service',
  tools: repositoryTools,
  skills: [reviewChecklist],
  sandbox: local(),
}));

三、它的原理：Agent = LLM + Harness

Flue 官方文档给出的核心心智模型是：agent 不是“一个聪明 prompt”，而是运行在 harness 里的大语言模型。模型单独存在时，只能接收上下文并生成文本；harness 则给它工作环境、可调用能力和恢复机制。

工具为什么不是“随便给模型一个 API key”？

Flue 的工具通过 defineTool(...) 定义，包含名称、描述、参数 schema 和 execute 函数。模型只能选择参数；真正使用哪个用户、哪个仓库、哪个 ticket、哪组凭据，应该由你的应用在工具闭包或 agent id 里绑定。

import { defineTool } from '@flue/runtime';
import * as v from 'valibot';

export const lookupOrderStatus = defineTool({
  name: 'lookup_order_status',
  description: 'Look up the current fulfillment status for one order ID.',
  parameters: v.object({
    orderId: v.string(),
  }),
  execute: async ({ orderId }) => {
    return await orders.getStatus(orderId);
  },
});

沙箱承担什么职责？

持久化执行解决什么问题？

Agent 一旦能调用外部工具，就会遇到“执行到一半服务重启”的问题。简单重放可能导致重复发消息、重复建工单或重复付款。Flue 的 durable agent 思路是把 session history、输入队列和事件记录下来，在恢复时尽量保守地判断：能确认没执行过才重试，已经完成的结果要保留，结果不确定的外部动作不能盲目再跑一遍。

Cloudflare 目标会利用 Durable Object 和 SQLite 提供更强的默认恢复能力；Node.js 目标默认以内存为主，如果要跨重启保存状态，需要配置数据库适配器。这个设计很重要，因为它把“会话可恢复”和“文件工作区可恢复”拆成了两个不同问题。

四、什么时候适合用 Flue？

Flue 适合那些“模型不能只回答，还要持续行动”的场景。换句话说，如果你的需求需要上下文、工具、文件、命令、恢复和部署入口一起工作，Flue 的抽象就开始有价值。

工程实践建议

• createAgent
• defineTool
• skills
• subagents
• virtual sandbox
• local()
• dispatch()
• durable session
• Node.js target
• Cloudflare target

五、和“普通 LLM 应用”的差异

普通 LLM 应用往往是“用户输入 → 模型输出”。Flue 的重点则是“应用输入 → agent 进入上下文 → 根据环境行动 → 把过程和结果沉淀回来”。这个差异会影响你如何设计系统。

六、参考资料

本文基于官方仓库和文档梳理，并结合 agent harness 工程实践做了解读。

1. withastro/flue GitHub 仓库
2. Flue Getting Started
3. What is an agent?
4. Agents guide
5. Tools guide
6. Sandboxes guide
7. Durable Agents