我把 Flue 从零跑了一遍，发现它解决的是 LangChain 最让人头疼的那个问题

"LangChain 用了半年，我至今不确定 Memory 到底存在哪里。"

这句话是我在某个 AI 开发者群里看到的，发出来的人有 3 年前端经验，用 LangChain 搭了一个客服 Agent，跑了两个月之后发现对话上下文偶尔会"失忆"，但他完全不知道从哪里开始 debug。

我当时笑了，但笑得很心虚——因为我也不确定。

就在那个时候，我看到了 Flue 的 README，它自称是 "Agent Harness"，而不是 Agent Framework。

这个词让我停了几秒。Harness 在英文里是"挽具"，是套在马身上控制方向的那套装备，不是马本身。这个比喻很有意思——它暗示 Flue 不想成为你的 Agent，它只想管好"Agent 怎么跑"这件事。

带着这个疑问，我花了一个周末把它从零跑了一遍。本文不是翻译官方文档，也不是 Flue 广告——哪里好用我会说，哪里难用我也会直说。

---

第一步：10 分钟跑通最简单的 Flue Agent

先把环境跑起来，理论放后面。

初始化项目

mkdir flue-demo && cd flue-demo
npm init -y
npm install typescript ts-node @types/node --save-dev
npx tsc --init

然后安装 Flue 核心包：

npm install @flue-ai/core

⚠️ 新手第一个坑：Flue 要求 Node.js >= 18，因为它依赖原生的 fetch API。如果你用的是 16，npm install 不会报错，但运行时会直接崩。先 node -v 检查一下。

配置 API Key

在项目根目录创建 .env 文件：

OPENAI_API_KEY=your_key_here
OPENAI_BASE_URL=https://api.884819.xyz/v1

⚠️ 新手第二个坑：很多教程会告诉你直接 export OPENAI_API_KEY=xxx，但 Flue 的 Harness 初始化时读的是 process.env，如果你用的是 Windows PowerShell，环境变量写法完全不同。强烈建议统一用 .env 文件 + dotenv 包来管理。

安装 dotenv：

npm install dotenv

写第一个 Agent

创建 src/agent.ts：

import 'dotenv/config';
import { Harness, Agent, tool } from '@flue-ai/core';

// 定义一个简单的工具：获取当前时间
const getCurrentTime = tool({
name: 'get_current_time',
description: '获取当前的本地时间',
parameters: {},
execute: async () => {
return { time: new Date().toLocaleString('zh-CN') };
},
});

// 创建 Agent
const myAgent = new Agent({
name: 'TimeAgent',
instructions: '你是一个助手，当用户问时间时，使用工具获取当前时间并回答。',
tools: [getCurrentTime],
});

// 创建 Harness（运行容器）
const harness = new Harness({
model: 'gpt-4o-mini',
apiKey: process.env.OPENAI_API_KEY!,
baseURL: process.env.OPENAI_BASE_URL,
});

// 运行
async function main() {
const result = await harness.run(myAgent, {
messages: [{ role: 'user', content: '现在几点了？' }],
});

console.log('Agent 回复：', result.output);
console.log('消耗 tokens：', result.usage);
}

main().catch(console.error);

在 package.json 里加一行：

"scripts": {
"start": "ts-node src/agent.ts"
}

然后运行：

npm start

如果一切正常，你会看到类似这样的输出：

Agent 回复：现在是 2025年7月15日 下午3:42:18。
消耗 tokens：{ prompt: 187, completion: 34, total: 221 }

---

第二步：和 LangChain 最不一样的 3 个地方

跑通之后，我们来看看 Flue 到底在设计上做了什么不同的选择。

① Harness vs Chain：把"跑"和"想"分开

LangChain 的 AgentExecutor 是一个黑盒，你把 Agent、Memory、Tools 全塞进去，它帮你运行。问题是，当你想控制"Agent 在第几步暂停"或者"某次工具调用失败后怎么重试"，你会发现这些逻辑深埋在 AgentExecutor 内部，很难干预。

Flue 的做法是把这两层彻底分离：

Harness（运行容器）
└── 负责：模型调用、重试策略、token 计数、生命周期钩子

Agent（逻辑单元）
└── 负责：系统提示、工具列表、对话策略

from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_openai import ChatOpenAI
from langchain.tools import tool

@tool
def get_time() -> str:
"""获取当前时间"""
from datetime import datetime
return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

llm = ChatOpenAI(model="gpt-4o-mini")
agent = create_openai_tools_agent(llm, [get_time], prompt)
executor = AgentExecutor(agent=agent, tools=[get_time], verbose=True)
result = executor.invoke({"input": "现在几点了？"})

const harness = new Harness({ model: 'gpt-4o-mini', apiKey: '...' });
const agent = new Agent({ tools: [getCurrentTime] });
const result = await harness.run(agent, { messages: [...] });

行数差异不是重点，重点是：Flue 里 harness 和 agent 是独立的对象，你可以用同一个 harness 跑不同的 agent，也可以换一个 harness（比如换成支持流式输出的版本）而不动任何 Agent 逻辑。

② 状态管理：显式 vs 隐式

LangChain 的 Memory 是隐式挂载的：

memory = ConversationBufferMemory()
executor = AgentExecutor(agent=agent, memory=memory, ...)
之后的每次调用，memory 自动注入上下文

这很方便，但副作用是你不知道 Memory 里现在有什么、什么时候会满、满了之后怎么截断。那个群里的开发者遇到的"失忆"问题，很可能就是 Memory 在某个条件下被静默清空了。

Flue 的状态是显式传递的：

// 你自己维护 messages 数组
const messages = [
{ role: 'user', content: '你好' },
];

const result1 = await harness.run(agent, { messages });

// 把上一轮的回复手动加进去
messages.push({ role: 'assistant', content: result1.output });
messages.push({ role: 'user', content: '刚才你说了什么？' });

const result2 = await harness.run(agent, { messages });

这样写更啰嗦，但你对状态有完全的掌控权。当 Agent 出现奇怪行为时，你可以直接 console.log(messages) 看到完整的上下文，一眼定位问题。

③ Tool 注册：类型推断 vs 手写 Schema

LangChain 需要你手写 Zod Schema 或 JSON Schema 来描述工具参数：

from langchain.tools import StructuredTool
from pydantic import BaseModel

class SearchInput(BaseModel):
query: str
max_results: int = 5

search_tool = StructuredTool.from_function(
func=search,
name="search",
description="搜索网络",
args_schema=SearchInput,
)

Flue 利用 TypeScript 的类型系统做推断：

const searchTool = tool({
name: 'search',
description: '搜索网络',
parameters: {
query: { type: 'string', description: '搜索关键词' },
max_results: { type: 'number', description: '最大结果数', default: 5 },
},
execute: async ({ query, max_results }) => {
// query 和 max_results 在这里已经是正确的类型
return await doSearch(query, max_results);
},
});

---

第三步：什么场景选 Flue，什么场景别用它

说完优点，该泼冷水了。

• 生态小：LangChain 有几百个现成的 Integration（数据库、向量库、搜索引擎），Flue 基本没有，你需要自己写适配层
• 文档稀：官方文档覆盖了核心 API，但进阶用法（比如流式输出、并发 Agent）几乎没有示例
• 社区不活跃：GitHub Issues 回复慢，遇到冷门问题基本靠自己看源码

• TypeScript/Node.js 原生项目，不想引入 Python 依赖
• 需要精细控制 Agent 生命周期（比如在工具调用前后插入自定义逻辑）
• 团队对"隐式状态"有洁癖，希望数据流向完全透明

你的项目是 TypeScript/Node.js 吗？
├── 否 → 用 LangChain（Python 生态更成熟）
└── 是 → 你需要现成的向量库/数据库集成吗？
├── 是 → 还是用 LangChain（或 LlamaIndex）
└── 否 → 你在意状态管理的透明度吗？
├── 是 → 试试 Flue，值得花半天
└── 否 → LangChain 或 Vercel AI SDK 都行

说实话，如果你是在做一个需要快速上线的 MVP，LangChain 的生态优势是压倒性的，Flue 现在还不是那个能帮你省时间的选择。但如果你是在搭一个需要长期维护的系统，Flue 的显式状态管理会在三个月后帮你省下大量 debug 时间。

---

第四步：下一步可以做什么

本文跑通的完整代码我放在了 GitHub：github.com/your-repo/flue-demo（建议 star，后续会持续更新）。

• Flue 官方文档：docs.flue-ai.dev
• Flue GitHub：github.com/flue-ai/flue
• 本文示例代码：见上方 repo

跑通这个 Demo 之后，你会发现真正的成本不在框架学习曲线，而在 API 调用费用。我自己测试 Flue 全程用的是 [api.884819.xyz](https://api.884819.xyz)——兼容 OpenAI 格式，直接把 .env 里的 OPENAI_BASE_URL 换掉就能跑，不需要改任何 Flue 配置。

对于"反复跑 Agent 调试"这种场景，你可能一个下午就要跑几百次，每次都消耗 200-500 个 token，累积下来不是小数目。选一个按量付费、没有月租的渠道，比订阅固定套餐划算很多。

新用户注册即送体验 token，Deepseek R1/V3 等国产模型完全免费，用来跑这类调试场景很合适。注册只需要用户名+密码，不需要邮箱验证，30 秒搞定。

---

结语：框架是工具，但"跑"的方式很重要

Flue 给我最大的启发不是它的 API 设计，而是它提出的那个问题："Agent 的运行容器"和"Agent 的逻辑"，真的需要分开管理吗？

用了一个周末之后，我的答案是：在小项目里，分不分无所谓；但在一个需要长期迭代的系统里，分开管理会让你在六个月后感谢现在的自己。

Flue 现在还不成熟，但它提出的设计哲学值得认真对待。如果你是 TypeScript 开发者，花半天跑一遍，形成自己的判断，比看十篇对比文章都有用。

---

不过，跑通这个 Demo 之后，你可能会遇到一个更深的问题：当 Agent 需要"记住"跨会话的信息时，状态到底该存在哪里？

内存会在进程重启后消失，数据库存全量对话又太重，向量库适合语义检索但不适合精确记忆——这三种方案各有各的适用场景，也各有各的坑。

下一篇，我会用 Flue + 一个真实的持久化方案，搭一个能"记住你是谁"的 Agent。这才是 Agent 从 Demo 走向实用的关键一跳，也是很多教程跳过不讲的部分。

---

#AI开发 #Agent框架 #TypeScript #LangChain #Flue #8848AI #AI工程 #大模型应用