环境的搭建 · 把项目准备好、把模型接通 ​

这一节的目标很朴素:在本机跑通第一句"Agent 对话"。 我们不谈任何业务逻辑,先把地基打好。

⚠️ 需要 Node.js >= 20。老版本(16/18)也行,但下面用到的语法和依赖会更挑剔,建议升级。

1. 建一个干净的工程 ​

随便找个目录,初始化项目:

mkdir agent-tutor && cd agent-tutor
npm init -y

为了让代码用上 ES 模块(更现代、和框架示例贴合),把 package.json 打开,加一行:

{
  "name": "agent-tutor",
  "version": "1.0.0",
  "type": "module",          // ← 加上这行: 用 import 语法
  "scripts": {
    "dev": "node src/index.js"   // 入口脚本
  }
}

目录结构建议(后续篇都会往里面加东西):

agent-tutor/
├── src/
│   ├── index.js         # 入口,后面我们主要在这写
│   ├── models.js        # 模型统一出口
│   ├── tools/           # 工具都放这
│   └── memory/          # 记忆持久化相关
├── .env                 # 密钥(不上传 git)
├── .gitignore           # 忽略 node_modules .env
└── package.json

mkdir -p src/tools src/memory

2. 装依赖 ​

npm install langchain @langchain/openai dotenv

说明:

• langchain —— 框架本体(编排、工具、记忆都在它里面);
• @langchain/openai —— LangChain 的 OpenAI 兼容模型封装(DeepSeek/Qwen/GLM 等都长一样,用 OpenAI 兼容协议接入);
• dotenv —— 读 .env 里的密钥。

后续加 RAG、加向量库时,再按需补包(如 chromadb 或 @langchain/community),先把最小集装好。

3. 把密钥放对地方,绝不写进源码 ​

创建 .env(⚠️ 别提交到 git,里面是你的密钥):

# .env —— 千万别提交这份文件!
OPENAI_API_KEY=sk-xxxxxxxxxxxxx        # 你的模型服务密钥
OPENAI_API_BASE=https://api.openai.com/v1   # 可换成 DeepSeek/Qwen/Ollama 地址
MODEL_NAME=gpt-4o-mini                  # 可选模型,想省钱换小模型

• 用 OpenAI 直接填 https://api.openai.com/v1;
• 用 DeepSeek:https://api.deepseek.com/v1,模型 deepseek-chat;
• 用 通义/Qwen:https://dashscope.aliyuncs.com/compatible-mode/v1;
• 用 本地 Ollama:http://localhost:11434/v1,模型 qwen2.5,可填任意 key 占位。

.gitignore 里别忘:

node_modules/
.env
dist/

4. 第一行能跑的代码:模型接通 ​

把 src/index.js 写成下面这样——这是整个系列的"最小可运行":

// src/index.js
import 'dotenv/config'
import { ChatOpenAI } from '@langchain/openai'

// 1. 创建一个"模型对象",全家桶里它就叫 ChatModel
const model = new ChatOpenAI({
  model: process.env.MODEL_NAME ?? 'gpt-4o-mini',
  apiKey: process.env.OPENAI_API_KEY,
  configuration: {
    baseURL: process.env.OPENAI_API_BASE ?? 'https://api.openai.com/v1',
  },
  temperature: 0.7, // 0 更确定 / 1 更有想象力的百变
})

// 2. 问它一句话
const reply = await model.invoke('你好,用一句话介绍什么是智能体')

// 3. 看结果
console.log(reply.content)

运行:

npm run dev
# 输出类似: 智能体是……(模型返回的一句话)

你已经有第一个"会说话的大脑"了。 现在就解释一下这几十行在干什么:

• ChatOpenAI —— LangChain 的模型类,它把"连接哪家服务、用什么模型、温度多少"全部集中在一个对象里;
• model.invoke(text) —— LangChain 所有东西统一的口径:你要"让模型干一件事",就 invoke 它。后面你要让模型"调用工具""检索资料""查记忆",全都会落到这些 invoke 上;
• 返回的 reply 不是字符串,而是一个 Message 对象——reply.content 才是文本,后面看它怎么携带"副作用"(工具调用)就知道了。

5. 马上可以做的几个小实验 ​

# 换模型: 改 .env 里的 MODEL_NAME 就行,代码不动
# 问它答不出日期? → 说明纯模型有知识截止,这为后面 RAG 埋了伏笔
# 问它算术? 大模型算 529*87 会错 → 为后面"工具调用"埋了伏笔

别急着往下跑通——先亲手感受一件事:纯模型能做的事有限。它不知道你的私有资料、算不准复杂算术、记不住上一句话。这三件事,正好是后面三篇要解决的三块能力(检索、工具、记忆),而你已经在第一节把它们的位置记住了。

🧪 本篇自检 ​

• [ ] npm run dev 能打印出模型回复
• [ ] 换 .env 里的 baseURL 能切换到另一家模型(比如 DeepSeek)
• [ ] 你搞清楚了 invoke() 是 LangChain 的核心动作

这一篇的灵魂,一句话:

项目 = 1 个模型对象 + 环境变量;一切能力都从 model.invoke(...) 出发。

接着,我们把"会聊"升级为"能干活"——先学 把对话做对:流式与多轮。