一、开发环境准备

在写第一行代码之前，先把开发工具配好。像厨师准备厨具一样，环境缺一不可。

Node.js 与包管理器

LangChain.js 要求 Node.js LTS + ES Modules 支持。旧版会报 import is not a module...。

检查当前 Node 版本

node -v # 应该输出 v20.x.x 或更高

如果版本过低，请升级：

• macOS / Linux：nvm 或 fnm

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
# 加载配置
source ~/.bashrc # 或 source ~/.zshrc
# 安装并使用 Node
nvm install node
nvm use node

• Windows：fnm 更稳定。使用 winget 安装

winget install Schniz.fnm
fnm install node
fnm use node

安装包管理器 pnpm

Pnpm 提高速度 & 节省磁盘：

• 硬链接避免重复下载。
• 全局存储共享依赖。

npm install -g pnpm # 全局安装
pnpm -v # 验证成功

TypeScript 配置

初始化项目 & 安装依赖

mkdir my-langchain-agent && cd my-langchain-agent
pnpm init -y # 自动生成 package.json
pnpm add -D typescript tsx @types/node # 开发依赖：TS 编译器、tsx、Node 类型定义

以上一步已完成后你可以随时添加其它依赖。

tsconfig.json 示例

{
"compilerOptions": {
"target": "ES2022","module": "ESNext","moduleResolution": "bundler"。"strict": true,"esModuleInterop": true,"skipLibCheck": true,"outDir": "./dist","rootDir": "./src"
},"include":
}

从关键点来看，strict 开启能在编译阶段捕获错误；moduleResolution=“bundler”适配现代打包工具。

package.json 脚本与 ESM 声明示例：

json { "scripts": { 至于"dev"，"tsx src/index.ts","build": "tsc" }。"type":"module" }

"type":"module" 告诉 Node 用 ESM，否则会报错“SyntaxError: Cannot use import statement outside a module”。

安装 LangChain.js 与 Provider 集成包

• =主要包必装= pnpm add langchain
• =模块化好处= * 想用 OpenAI 就只装 openai 包；* 不需要 Anthropic/Google/Ollama 时不必下载，减小体积与冲突风险。
• 至少选择一个 Provider： bash pnpm add @langchain/openai # OpenAI GPT‑4o 等 pnpm add @langchain/anthropic # Claude 系列 pnpm add @langchain/google-genai # Gemini pnpm add @langchain/ollama # 本地模型 markdown

  LangGraph 必装示例：

  pnpm add @langchain/langgraph

  Zod 用于参数校验：

  pnpm add zod **💡 提示**：虽然 LangGraph 是底层依赖。但建议显式安装，以确保版本可控。老实说，

  配置 API Key 与环境变量安全性

  • 多数 LLM Provider 都需要 API Key。怎么说呢，示例以 OpenAI 为主，国内使用者可用千问或其他模型。
  • 创建根目录 .env 文件： bash OPENAI_API_KEY=sk-your-openai-key-here # OpenAI 密钥 ANTHROPIC_API_KEY=sk-your-anthropic-key-here # 可选 QIANWEN_API_KEY=sk-your-qwen-key # 千问密钥 QWEN_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 LANGSMITH_TRACING=true LANGSMITH_API_KEY=ls-your-langsmith-key-here LANGSMITH_PROJECT=my-first-agent
    ⚠️ 请勿将 .env 推送到公共仓库！按理说，使用 .gitignore 排除它。
    • .gitignore 示例： bash .env node_modules dist

      dotenv 加载 .env 文件：

      bash pnpm add dotenv # npm/yarn 同理 import 'dotenv/config';
      **验证**的观点是，在任意文件中打印 `process.env.OPENAI_API_KEY?.substring` 看是否正常。如果为空 → 检查 `.env` 方法或忘记 `import 'dotenv/config';`，按理说，--- ## 项目结构示例 text my-langchain-agent/ ├── src/ │ ├── agents/ │ │ └── main.ts // Agent 创建逻辑 │ ├── tools/ │ │ └── wear.ts // 工具定义 │ └── index.ts // 程序入口 ├── .env ├── .gitignore ├── package.json └── tsconfig.json --- ## 二、第一个 Agent：天气查询示例 此处演示如何用最少代码完成一个完整功能。### 完整代码 ts // 第一步先：加载环境变量 — 必须在所有 import 前执行！import 'dotenv/config';// 接下来：主要导入 import { createAgent,tool } from 'langchain';import { ChatOpenAI } from '@langchain/openai';import { z } from 'zod';// 然后：定义天气工具——注意三要素 const getWear = tool( => `${city} 今日天气：晴，气温 °C。湿度 %`,{ name的观点是，'get_wear',description: '查询指定城市的当前天气情况，包括温度、湿度和天气状况。',schema: z.object({ 从city来看。z.string.describe,}),} );老实说，// 第四步：创建 Agent —— 使用 OpenAI GPT‑4o 示例；若使用千问请自行实例化模型并传入。const agent = createAgent({ model这方面，new ChatOpenAI('qwen-max',{ 再看apiKey。process.env.QIANWEN_API_KEY,configuration: { baseURL: process.env.QWEN_API_URL },}),tools:,});// 第五步：调用 Agent 并打印最终回复 => { const result = await agent.invoke({ messages:,});console.log，.content);})，话说回来，### 如何运行？bash pnpm dev # 使用 tsx 启动 TS 文件，无需手动编译 ### 输出预期 北京今日天气这方面，晴，气温 °C，湿度 % 上海今日天气：晴。气温 °C，湿度 % 两个城市今天天气都不错... --- ## 三、接入 LangSmith 实现可视化调试 LangSmith 为 AI 调试提供端到端追踪。开启极其简单——只需设置两条 env。### 步骤一：注册并获取 API Key 1. 打开 . 2. 在项目设置 → API Keys 页面复制 key。### 步骤二：开启追踪 在 `.env` 添加： bash LANGSMITH_TRACING=true # 开启追踪模式 LANGSMITH_API_KEY=ls-your-key-here LANGSMITH_PROJECT=my-first-agent 不需要改动业务代码！### 步骤三：查看执行轨迹 运行 `pnpm dev` 后登录 LangSmith 控制台，你会看到完整链路图： * 每次 LLM 调用输入/输出 * 工具调用参数与返回值 * 每一步耗时与 Token 消耗 这让你能快速定位“为什么模型没有调用工具？”、“为什么回答不准确，”等问题。--- ## 四、流式输出——实时响应体验 默认 `invoke` 会等待全部推理结束再返回结果，对于多轮工具调用使用者体验差。通过 `stream` 可以实时获得中间状态或逐 Token 输出。### 基础流式示例 ts const stream = await agent.stream( { messages: },{ streamMode:'values' } // 返回每一次状态更新完整快照 );for await { const lastMsg = chunk.messages.at;if{ process.stdout.write;} } ### 三种 `streamMode` 模式对比 | 模式 | 返回内容 | 场景 | |------|----------|------| | values | 完整状态 | 想看每一步思考过程 | | updates | 增量差异 | 减少网络传输 | | messages | 单 Token | ChatGPT 打字机效果 | #### 推荐做法——聊天 UI 用 `"messages"`： ts const stream = await agent.stream( { messages: },{ streamMode:'messages' } );for await { process.stdout.write;// 打字机效果 } --- ## 五、完整项目结构 & 常规模板文件说明 保持代码整洁有助团队协作。老实说，1. **src/** – 源码区分 tools & agents。2. **.env.example** – 提供给新同事填写真实 key 的模板。3. **package.json** – scripts 与依赖声明。4. **tsconfig.json** – TypeScript 编译配置。`.env.example` 示例： text # .env.example OPENAI_API_KEY= ANTHROPIC_API_KEY= QIANWEN_API_KEY= QWEN_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 LANGSMITH_TRACING=true LANGSMITH_API_KEY= LANGSMITH_PROJECT=my-first-agent 克隆后复制并填充： bash cp .env.example .env && vim .env --- ## 六、常见问题 & 踩坑教程 | 痛点 | 表现 | 原因 | 对策 | |------|------|------|------| | **① 导入失败 “Cannot use import statement outside a module”** | SyntaxError 报错 | 未声明 `"type":"module"` 或 Node 默认 CommonJS | 在 package.json 添加 `"type":"module"` 并重启 | | **② API Key 无效 “AunticationError”** | 调用返回无权限错误 | dotenv 未在最顶部导入或 key 错误 | 确认 `import 'dotenv/config';` 放第一行，并检查 key 是否正确 | | **③ 工具返回值非字符串导致 “Tool output must be a string”** | 模型崩溃或未触发接下来 | 工具函数返回对象/数组等非字符串类型 | 手动序列化为 JSON 字符串或直接返回字符串 | | **④ 模型字符串格式错误导致 “Invalid model identifier”** | createAgent 报错非法模型名 | 使用了旧版写法 `) 或拼写错误 | 使用官方文档中的 `:` 字符串格式或显式实例化后传入 | | **⑤ Zod Schema 定义不严导致参数验证失效** | Tool 被误调用但传参错误且无报错 | Schema 未加 `.min/.max/.describe` 等严格校验规则 如只写 `z.object})` 会接受空字符串等非法值。建议添加描述与长度限制，|

      💡 快速排查流程： 1️⃣ 确认 package.json 中 `"type":"module"` 已加入。2️⃣ 确保 `.env` 位于根目录且未被忽略。3️⃣ 所有导入前先执行 `import 'dotenv/config';`，4️⃣ 若遇到 “Invalid model identifier”，请检查 provider 名称拼写及是否支持该模型。5️⃣ 当出现“Tool output must be a string”，务必手动序列化对象为字符串。

      七、本章小结 & 动手练习

      ✅ **已完成**

      • 搭建完整开发环境。
      • 理解模块化包安装优势及主要包需求。
      • 成功跑通第一个 Wear Agent 并查看流式输出。
      • 接入 LangSmith，实现全链路可视化追踪。

      🎯 练习任务

      1. 工具。让它真正请求公开 Wear API 并返回 JSON 数据，而不是占位文本。
      2. 新建 工具，实现“现在几点？”功能，测试多轮对话能否正确切换工具。
      3. 将模型从 "openai:gpt-4o" 切换为 "openai:gpt-4o-mini"；观察响应速度与成本差异，
      4. 登录 LangSmith 控制台，对比不同模型下 Token 消耗和工具调用次数。

      📚 延伸阅读

      • 《LangChain.js 官方文档 – Installation》 \
      • 《LangSmith 快速上手》 \
      • 《Zod 官方文档》 

      ---