深入浅出 LangChain — 第一章：AI Agent 开发导论与 TaoToken 统一 Key 配置

1. 从「问答机器」到「自主代理」为什么 TypeScript 开发者现在要学 LangChain如果你已经能用 fetch 直接调通大模型接口大概率也踩过这几个坑模型不知道昨天发生的事、每轮对话都要手动拼历史消息、想让它查个数据库还得自己写 if-else 分发。这些问题的本质是——你手里只有一个「问答机器」而不是一个能干活的「自主代理」。AI Agent 要解决的就是这件事。它把 LLM 当作大脑配上工具Tools当双手再加上记忆Memory当笔记本让模型自己决定「下一步做什么」先搜索、再读文档、发现信息不够就换个关键词继续搜最后汇总成答案。这个「思考—行动—观察—再思考」的循环就是 ReAct 模式也是 LangChain 里createAgent()的默认工作方式。LangChain 生态现在分四层LangChain 是平衡易用性与灵活性的 Agent 框架LangGraph 是底层的图式运行时LangSmith 负责可观测性与评估Deep Agents 则是开箱即用的高级封装。对 TypeScript 开发者来说LangChain.js 的 v1.x 把createAgent()变成了一等公民类型安全、IDE 补全友好还能直接部署到 Vercel、Cloudflare 这类 Serverless 环境。这一章的目标很明确从零搭出一个能跑通的 Agent 骨架并且把模型调用的 Key 通道统一配置好让你后面每一章的代码都能直接复用。2. 前置准备用 TaoToken 统一 Key 打通模型通道写 Agent 代码最烦的不是逻辑是 Key 管理。今天试 OpenAI明天换 Claude后天想对比 Gemini每换一个模型就要改环境变量、改 base URL、改 SDK 初始化方式。我的做法是统一走一个兼容 OpenAI 协议的通道TaoToken 就是干这个的——它提供统一的 API 入口模型用provider:model-name的格式声明切换模型只改一个字符串。你需要先拿到一个 Key。打开 https://taotoken.net/api-keys 登录后在控制台创建 API Key复制出来形如sk-xxxx的字符串。这个 Key 后面会写进.env文件不要硬编码到代码里也不要提交到 Git。TaoToken 的 API 基地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions协议。这意味着 LangChain 里所有基于 OpenAI 兼容接口的模型类都能直接用不需要额外装 provider 包。如果你后面要跑长期编码任务或者 Agent 工作流可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它针对高频调用场景做了额度优化。注意Key 只显示一次创建后立刻保存到密码管理器。如果泄露了去控制台吊销重新生成。3. 可复制配置settings.json 与 config.toml 骨架先建项目。Node 版本建议 20 以上包管理器用 pnpm 或 npm 都行。mkdir langchain-agent-demo cd langchain-agent-demo npm init -y npm install langchain langchain/openai zod dotenv npm install -D typescript tsx types/node npx tsc --inittsconfig.json里把module改成NodeNexttarget改成ES2022strict保持true。然后在项目根目录建.env# .env TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用 VS Code可以在.vscode/settings.json里加一段让编辑器识别环境变量、减少 TS 报错{ typescript.tsdk: node_modules/typescript/lib, files.associations: { *.env: dotenv }, terminal.integrated.env.linux: { NODE_OPTIONS: --no-warnings } }习惯用 TOML 管理配置的可以建一个config.toml作为模型参数的集中声明代码里用fs读进来# config.toml [model] provider openai name gpt-4o base_url https://taotoken.net/api temperature 0.3 [agent] max_iterations 10 verbose true这样模型名、温度、迭代上限都不散落在代码里换模型只改 TOML。接下来写 Agent 骨架agent.tsimport dotenv/config; import { createAgent, tool } from langchain; import { ChatOpenAI } from langchain/openai; import { z } from zod; // 1. 用 TaoToken 统一通道初始化模型 const model new ChatOpenAI({ modelName: gpt-4o, temperature: 0.3, apiKey: process.env.TAOTOKEN_API_KEY, configuration: { baseURL: process.env.TAOTOKEN_BASE_URL, }, }); // 2. 定义一个最小工具查当前时间 const getCurrentTime tool( async ({ timezone }) { const now new Date().toLocaleString(zh-CN, { timeZone: timezone }); return 当前时间${now}; }, { name: get_current_time, description: 查询指定时区的当前时间timezone 用 IANA 格式如 Asia/Shanghai, schema: z.object({ timezone: z.string().describe(IANA 时区名例如 Asia/Shanghai), }), } ); // 3. 创建 Agent const agent createAgent({ model, tools: [getCurrentTime], }); // 4. 调用 const result await agent.invoke({ messages: [{ role: user, content: 现在上海几点了 }], }); console.log(result.messages.at(-1)?.content);跑起来npx tsx agent.ts4. 验证调用链确认 Agent 真的跑通了代码能跑不代表 Agent 逻辑对。你需要确认三件事模型请求发出去了、工具被正确调用了、最终回答基于工具结果生成。最直接的办法是打开 verbose。在createAgent里加verbose: true或者设置环境变量LANGCHAIN_VERBOSEtrue。跑一次你会看到类似这样的输出[agent] Invoking model with 1 messages [agent] Model requested tool: get_current_time [tools] Executing get_current_time with { timezone: Asia/Shanghai } [tools] Result: 当前时间2025/1/15 14:32:10 [agent] Invoking model with 3 messages [agent] Final answer: 上海现在是 2025年1月15日 14:32看到Model requested tool这一行说明模型正确识别了需要调用工具看到Executing和Result说明工具真的执行了最后模型基于工具返回的时间给出了回答整条链路就通了。如果你还想看得更细可以接入 LangSmith。在.env里加两行LANGSMITH_TRACINGtrue LANGSMITH_API_KEY你的LangSmithKey再去 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照一下接口文档确认 base URL 和路径拼接没问题。跑一次后去 LangSmith 控制台你能看到完整的执行轨迹每一步的 Prompt、模型输出、工具调用参数和返回值一目了然。这对调试多步 Agent 特别有用。想快速验证模型本身通不通可以直接用模型对话页面https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite发一条消息确认 Key 和通道正常再回来跑代码。5. 本篇常见错排查报错401 Unauthorized九成是 Key 没读到。检查.env文件是否在项目根目录、dotenv/config是否在文件第一行导入、Key 有没有多余空格。TaoToken 的 Key 以sk-开头复制时别漏字符。报错404 Not Foundbase URL 拼错了。正确写法是https://taotoken.net/api不要在后面加/v1LangChain 的 OpenAI 兼容层会自动补/v1/chat/completions。如果你手动拼了/v1就会变成/v1/v1/chat/completions。模型不调用工具直接瞎编答案检查工具的description是否清晰。LLM 完全靠描述判断要不要调用工具描述里写清楚「什么时候用、参数是什么格式」很关键。另外确认schema里的字段都有describe()Zod 的描述会转成 JSON Schema 传给模型。createAgent报类型错误确认langchain装的是 v1.x。跑npm ls langchain看一眼版本如果是 0.x旧 API 里没有createAgent需要升级。旧教程里的initializeAgentExecutorWithOptions、LLMChain在 v1.x 已经废弃别照抄。工具执行了但模型没用结果通常是工具返回值太长或格式混乱。工具返回尽量结构化、简洁比如返回 JSON 字符串而不是一大段自然语言。模型对短而清晰的工具结果利用率更高。TypeScript 报Cannot find module langchaintsconfig.json里moduleResolution设成NodeNext或Bundlermodule设成NodeNext。如果还不行删掉node_modules和package-lock.json重装。6. 下一步把 Key 通道固定下来开始写真正的 Agent这一章你拿到的东西不多但都是后面每一章都要用的地基一个统一的 Key 通道、一份可复制的配置骨架、一个能跑通的最小 Agent、一套验证调用链的方法。模型换不换、工具加不加这套骨架都不用动。接下来建议你先把 API Key 管理好https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite把 Key 存进密码管理器.env加进.gitignore。然后去接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite翻一下模型列表和参数说明确认你常用的模型名怎么写。如果你打算做长期编码类 AgentCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite的额度模型值得先了解避免后面频繁调用时额度不够。下一章我们会在这个骨架上加第二个工具、加对话记忆让 Agent 从「单次问答」变成「多轮任务执行」。现在先把agent.ts跑通看到那句「上海现在几点」的正确回答再往下走。