LangChain.js 智能代理入门：从一次安装到跑通第一个 Agent 的路径
【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs
做一个能回答问题的 AI 应用，往往不是接一个大模型 API 那么简单：模型看不到你的私有资料，不能调用你系统里的工具，换一家模型供应商就要重写一遍胶水代码。LangChain.js 是 TypeScript 生态的智能代理平台（agent engineering platform），它用一套统一接口把模型、向量检索、工具调用、记忆和流式输出串起来，让 Node.js 开发者可以在一个框架内完成智能应用搭建。
🧭 先看懂它的能力版图
按使用场景而不是目录来切分，LangChain.js 的核心能力大致对应五类问题：
| 你遇到的问题 | 它提供的能力 | 仓库内对应位置 |
|---|---|---|
| 想让模型自主调用工具完成任务 | createAgent代理构建、中间件机制 | examples/src/createAgent/ |
| 想基于私有文档做问答 | RAG 检索链、文档加载与切分、向量库检索 | examples/src/langchain-classic/retrievers/、libs/langchain-textsplitters/ |
| 想在不同模型之间低成本切换 | 统一的 Chat 模型接口，各供应商独立成包 | libs/providers/ |
| 想让模型输出可解析的结构化数据 | 结构化输出示例（如实体抽取） | examples/src/extraction/ |
| 想连接 MCP 工具生态 | MCP 客户端与工具适配 | libs/langchain-mcp-adapters/ |
部署环境上，它覆盖 Node.js（ESM 与 CommonJS）、浏览器、Cloudflare Workers、Vercel/Next.js、Deno、Bun 等，一套代码基本可以跨端复用。
🤖 智能代理：从示例目录读起
代理是这套框架最常被问到的能力。打开 examples/src/createAgent/，每个文件对应一种真实开发需求：
- 基础工具调用与动态工具：
tools.ts、dynamicTools/ - 流式输出与结构化输出：
streaming.ts、structuredOutput.ts - 系统提示词控制与消息预处理：
customSystemPrompts.ts、controlOverMessagePreparation.ts - 记忆与上下文：
accessLongTermMemory.ts（长期记忆）、accessThreadLevelState.ts（会话级状态） - 中间件扩展点：
middleware/下有人机协同（hitl）、摘要、提示词缓存等
代理还能处理图片输入，例如 OpenAI 供应商的集成测试中就用一张网页截图验证模型对视觉内容的理解，这是多模态代理的常见输入形态。
多代理场景有独立目录 examples/src/multi-agent/，包含任务交接（handoffs）、知识库路由、SQL 技能助手等完整示例；若需要更精细的状态机与人在回路控制，官方生态中的 LangGraph.js 是下一步（开源文档站点可见，仓库内不展开）。
🔌 接入模型：换供应商只换参数
供应商实现都放在 libs/providers/ 下，每个包对应一家模型服务：
- 常用对话与多模态模型：langchain-openai/、langchain-anthropic/、langchain-google-genai/、langchain-deepseek/
- 国内/其他生态：langchain-xai/、langchain-ollama/（本地模型）、langchain-mistralai/ 等
各包的package.json中都标注了最低 Node 版本要求（如 18.x/20.x），选包前先确认运行环境。切换模型的典型做法是：保持业务代码不变，把聊天模型实例从 A 供应商换成 B 供应商，统一接口让这一步只需改构造参数。
🏃 最小可行路径：安装到跑通一个例子
按仓库自带的示例工程走一遍，是最快的上手方式：
- 克隆仓库：
git clone https://gitcode.com/GitHub_Trending/la/langchainjs - 在根目录安装依赖并构建各包（monorepo 用 pnpm 管理，pnpm-workspace.yaml 描述了包结构）
- 进入 examples/，把
.env.example复制为.env，填入你的模型 API 密钥（示例运行基本都依赖密钥） - 按 examples/src/README.md 的说明，用
pnpm run start加示例文件路径运行任意一个例子，例如createAgent/tools.ts
核心库的位置也顺手记一下：libs/langchain-core/ 承载消息、提示词模板、Runnable 抽象等底层概念；libs/langchain/ 是当前主包；libs/langchain-classic/ 是旧版 API（链、记忆等），仍在维护但新功能主要落在createAgent一侧。
⚠️ 常见误区与排错对照
- 导入报错、找不到符号：monorepo 示例依赖已构建的本地包，先执行根目录的构建命令再跑例子；
- 换了模型包却仍报错：确认新包的最低 Node 版本要求，且
.env中的密钥与新供应商匹配； - API 风格混乱：新代码建议走
createAgent路径，langchain-classic的 Chain/Memory 风格属于经典 API，两者混用会增加理解成本； - RAG 效果差：先检查文档切分策略（libs/langchain-textsplitters/）与向量库检索配置，而不是先怀疑模型；
- 示例跑不了但代码没问题：确认
.env已就位——examples/src/README.md 明确说明大多数例子需要密钥。
📚 深入资源在哪里找
- 代理模式全集：examples/src/createAgent/，按需求文件名检索比通读更快
- 多代理编排：examples/src/multi-agent/
- RAG 与文档处理：examples/src/langchain-classic/indexes/（含各种文本切分器示例）
- 核心概念源码：libs/langchain-core/src/runnables/、libs/langchain-core/src/prompts/、libs/langchain-core/src/messages/
- 新供应商集成脚手架：libs/create-langchain-integration/ 提供了从零创建集成包的模板
- 贡献规范：CONTRIBUTING.md
🚪 边界与下一步
明确它不做什么：LangChain.js 不提供模型权重与推理服务，必须自备模型 API；它也不是低层运行时，长任务状态管理、细粒度人在回路等需求应上 LangGraph.js；langchain-classic目录是维护态的经典 API，新特性（尤其是代理）以createAgent为默认方向。
建议的推进顺序：先跑通createAgent/tools.ts形成端到端感知，再按需叠加中间件、长期记忆或多代理路由；每加一个能力，都从examples/找到对应文件对照阅读，仓库内的示例本身就是最权威的使用文档。
【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
