Flue 框架从入门到精通
Part 1 · 起步

§02 十分钟跑通你的第一个 Agent

装依赖、写 8 行代码,在终端跑通第一个 Agent

📑 本章目录

02.1 你需要什么

上周我重装环境。Node 22.18.0、一条命令、30 秒,对话就跑起来了。

清单很简单:

  • Node.js ≥ 22.18.0(低于这个版本会报错)
  • 一个模型 API Key(我用 Anthropic,你用哪家电都行)
  • 15 分钟和一杯咖啡

02.2 我们最终要做成什么

一个会讲"hello world"冷笑话的 Agent。跑通后,你能在终端跟它对话。

为啥从笑话开始?因为它能验证整条链路:模型通了、会话通了、输出通了。

02.3 安装和第一次对话

第一步:建目录,装依赖。

# 装运行时和命令行工具
npm install @flue/runtime
npm install --save-dev @flue/cli

# 把密钥写进 .env,别提交到 git
echo 'ANTHROPIC_API_KEY="你的key"' > .env

# 初始化 Node 目标,生成 flue.config.ts
npx flue init --target node

预期结果:目录里多出 flue.config.tspackage.json 多了两个依赖。

第二步:写第一个 Agent 文件。

// src/agents/hello-world.ts
import { createAgent } from '@flue/runtime';

// 文件名就是 Agent 名:hello-world
export default createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',        // 模型用 provider/model 格式
  instructions: 'Tell a funny "hello world" engineering joke.',
}));

预期结果:文件保存即可,无需编译。Flue 会自动发现它。

第三步:连上去,开聊。

# hello-world 是模块名,local 是这次实例的 id
npx flue connect hello-world local

预期结果:终端显示已连接。你敲一句回车,它就回一段冷笑话。

注意:模型写法必须是 provider/model-id

写成 deepseek-v4-flash 会报 Invalid model。正确是 deepseek/deepseek-v4-flash。斜杠不能省。

02.4 两个新手必踩的坑

第一坑:valibot 版本。

# 必须 1.x,用 0.x 会报 TypeError: Cannot read properties of undefined
npm install valibot@^1.0.0

第二坑:init() 不收普通配置对象。这个我们 §08 细讲,先记住结论。

标叔的经验:环境对,一切顺。

我第一次卡了 40 分钟,最后发现是 Node 版本是 20。升到 22.18.0,秒通。版本这关,先过。

02.5 回顾

我们装了依赖,写了 8 行代码,在终端跟 Agent 聊上了。

核心建议:先跑通再优化。

别在第一天纠结"prompt 怎么写才完美"。先让它跑起来,看输出,再迭代。卡在完美主义是新手通病。

装完了,账号登了,第一次对话也跑通了。下一章,做个真能干活的项目。