Flue 中文教程：用 TypeScript 构建可部署的沙箱 Agent

Flue 是 Astro 团队维护的 TypeScript Agent 框架。它把 Agent 写成带 'use agent' 指令的函数，再用 hooks 组合模型、工具、技能和沙箱。相同定义可以通过 CLI 单次运行，也可以挂到 Hono 路由后部署到 Node.js 或 Cloudflare。

1. 安装前先定运行边界

准备 Node.js 22.19.0 或更新版本，以及一个模型提供方的 API key。Flue 的 Cloudflare runtime 也支持内建的 cloudflare/* AI gateway；除此之外，应按具体 provider 的要求把密钥放在环境变量里，不要写进 Agent 文件或提交到仓库。

node --version
mkdir my-flue-agent && cd my-flue-agent
npm init -y
npm install @flue/runtime @flue/cli

也可以运行 npx flue init 生成项目。第一次接触时建议先手写最小 Agent，确认每一层在做什么，再引入 blueprint、MCP 或外部渠道。

2. 写一个最小 Agent

在 src/agents/assistant.ts 中定义函数。'use agent' 标记 Agent，useModel() 选择模型；需要文件或 shell 时再显式添加沙箱。下面保留官方 hooks 的结构，模型名应换成你已经配置凭据且实际可用的型号。

'use agent';
import { useModel } from '@flue/runtime';

export function Assistant() {
  useModel('anthropic/claude-sonnet-4-6');
  return '先复述约束，再给出可核对的答案。';
}

按官方 CLI 方式运行一个带固定会话 id 的消息：

npx flue run src/agents/assistant.ts --id hello-1 --message "列出三个上线前检查项"

不要一开始就给 Agent 宿主 shell。先验证模型凭据、回复、错误和超时；确认任务确实需要文件操作后，再接 useSandbox() 和受限工具。

3. 沙箱不等于统一的安全等级

Flue 支持虚拟、本地和远程容器类沙箱，但它们的边界不同。Node 目标的 local() 直接绑定宿主文件系统和 shell，并不是隔离容器。生产任务应缩小工作目录、环境变量、命令、网络和执行时长；需要处理不可信代码时，应选择有清晰隔离与回收机制的远程沙箱。

4. 从 CLI 任务走到 HTTP 服务

需要长期服务时，安装 Vite、Flue 插件和 Hono，把 Agent 挂载到 src/app.ts。开发环境使用 npx vite dev；生产构建使用 npx vite build，Node 目标输出自启动的 dist/server.mjs。

npm install @flue/vite hono vite
npx vite dev
npx vite build
node dist/server.mjs

官方文档还指出两个容易遗漏的条件：应用依赖默认不会全部打进产物，部署时要带上 node_modules 或在容器内安装依赖；没有配置数据库适配器时，会话只保存在进程内存里，重启就会丢失。正式上线前至少验证一次重启恢复、任务中止、重复事件和超时。

5. 版本升级怎么检查

Flue 是多包仓库，release 页面可能同时出现 runtime、SDK、Vite 插件和渠道包。不要只看某个渠道包的版本；先核对 @flue/runtime，再检查 @flue/cli、@flue/vite 及正在使用的渠道适配器是否属于同一发布组。2.1.0 的官方 release 还补充了工具调用 timeoutMs、MCP annotations 和观测内容预算等文档。

常见问题