深入浅出 LangChain — 第一章：AI Agent 开发导论

📖 本章学习目标

• ✅ 理解 AI Agent 的核心概念和三大构成要素
• ✅ 掌握 LLM 应用从简单问答到自主代理的演进历程
• ✅ 了解 LangChain 生态体系（LangChain/LangGraph/LangSmith）的定位与关系
• ✅ 明确 TypeScript 版本的选择理由和适用场景
• ✅ 识别 v1.x 新 API 与旧版教程的区别

一、LLM 应用的演进：从"问答机器"到"自主代理"

在学习任何框架之前，先搞清楚它解决了什么问题，会让后续的学习事半功倍。我们可以把 LLM 应用的发展看作一个"能力升级"的过程。

🎯 第一阶段：直接调用 API（2022 年底 ~ 2023 年初）

OpenAI 发布 GPT-3.5 的 Chat Completion API 之后，最直接的用法是这样的：

// 最原始的用法：直接拼 Prompt，调 API
const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.OPENAI_API_KEY}` },
  body: JSON.stringify({
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: '你好，介绍一下自己' }]
  })
});
const data = await response.json();
console.log(data.choices[0].message.content);

代码解读：

• 第 2-3 行：构建 HTTP 请求，设置认证头
• 第 4-7 行：构造请求体，指定模型和消息内容
• 第 8-9 行：发送请求并解析返回结果

这种方式能处理大量简单的问答场景。但问题很快就暴露出来了：

⚠️ 三大局限性

1. 知识截止：模型的训练数据有截止日期（比如 GPT-4 的知识截止到 2023 年），问它最新的事情，它要么不知道，要么会产生"幻觉"（编造答案）
2. 无状态：每次调用都是全新的对话，模型不记得你上一条说了什么（除非你手动把历史消息都带上）
3. 无行动能力：模型只能生成文本，不能帮你查数据库、发邮件、调用第三方 API

这就像一个博学但被关在图书馆里的学者------他知道很多知识，但无法获取最新信息，也无法帮你做任何实际的事情。

🛠️ 第二阶段：RAG 与工具调用（2023 年）

开发者们开始给模型"外挂"能力，就像给学者配备了助手和资料库。

（1）RAG（Retrieval-Augmented Generation，检索增强生成）

核心思路是在把问题发给模型之前，先从知识库里检索相关内容，塞进 Prompt，让模型基于这些上下文来回答。

用户问："帮我查一下今天北京的天气"
      ↓
【传统方式】模型凭记忆回答 → 可能错误
【RAG 方式】先查询天气 API → 获得真实数据 → 模型基于真实数据回答

（2）工具调用（Tool Calling / Function Calling）

2023 年 3 月，OpenAI 发布了 Function Calling，允许开发者预先定义一组函数，模型在回答时可以决定"我需要调用这个函数"，并给出调用参数------程序拿到参数后执行真实的调用，再把结果回传给模型继续推理。

工作流程拆解：

// 第一步：定义工具
const getWeather = {
  name: "get_weather",
  description: "查询指定城市的当前天气",
  parameters: {
    city: "string",  // 城市名称
    date: "string"   // 日期
  }
};

// 第二步：模型决定调用工具
// 模型输出：{ tool: "get_weather", args: { city: "北京", date: "今天" } }

// 第三步：程序执行工具
const weatherData = await fetchWeatherAPI("北京", "今天");
// 返回：{ temperature: 22, condition: "晴" }

// 第四步：模型基于真实数据生成回答
// "北京今天天气晴朗，气温 22°C，适合出行。"

💡 关键突破：工具调用让模型从"纯文本生成器"变成了"任务协调者"------它可以决定何时、如何调用外部工具来获取真实信息或执行操作。

🤖 第三阶段：AI Agent（2024 年至今）

RAG 和工具调用让模型有了"获取信息"和"执行动作"的能力，但这还不够------真实任务往往需要多步骤推理和动态决策。

实际场景举例：

假设你给模型下达任务："帮我调研竞品并生成一份报告"

这个任务需要多个步骤：

1. 搜索竞品信息
2. 阅读各个竞品的官网和产品文档
3. 总结每个竞品的特点
4. 对比分析优劣势
5. 生成结构化报告

关键挑战： 每一步的结果决定下一步怎么走，没有固定的执行路径。如果某个竞品网站打不开怎么办？如果发现新的竞品怎么办？这些都需要动态决策。

AI Agent 的核心思想： 让 LLM 自己决定"下一步做什么"，在循环中反复执行以下流程：

flowchart TD A[用户输入任务] --> B[Agent 思考
分析任务需求] B --> C{需要工具吗?} C -- 是 --> D[选择并调用工具] D --> E[获得工具结果] E --> F[观察结果
评估是否完成任务] F -->|未完成| B C -- 否 --> G[生成最终回答] F -->|已完成| G G --> H[返回给用户] style A fill:#e8f4fd,stroke:#1890ff style H fill:#f6ffed,stroke:#52c41a style D fill:#fff7e6,stroke:#fa8c16 style B fill:#f9f0ff,stroke:#722ed1

ReAct 模式（Reasoning + Acting）： 这是 Agent 最常用的推理模式，结合了"推理"和"行动"两个步骤：

• Thought（思考）：我现在应该做什么？
• Action（行动）：调用某个工具
• Observation（观察）：工具返回了什么结果
• Repeat（重复）：根据结果决定下一步

这就是从"问答机器"到"自主代理"的演进逻辑。理解了这个脉络，你才能真正理解 LangChain 为什么要这样设计。

---

二、什么是 AI Agent：三个构成要素

AI Agent 并没有一个严格的行业定义，一般定义为：一种在动态环境下，可以自主感知、自主决策、自主行动的智能系统。但它通常包含三个核心要素，可以用一个形象的类比来理解：

🧠 类比：AI Agent 就像一个智能员工

• 大脑（LLM）：负责思考、决策、规划
• 双手（Tools）：负责执行具体操作
• 笔记本（Memory）：记录重要信息和经验

mindmap root((AI Agent)) (大脑 LLM) 多步推理 决策规划 自然语言理解 (工具 Tools) 搜索引擎 代码执行 数据库查询 API 调用 (记忆 Memory) 短期记忆
对话历史 长期记忆
跨会话存储 外部知识库
RAG

1、大脑：LLM 负责推理和决策

LLM（Large Language Model，大语言模型） 是 Agent 的核心，负责：

• 理解用户意图
• 规划任务步骤
• 决定调用哪个工具
• 解读工具返回结果
• 最终给出答案

一些不同模型的差异：

模型系列	优势	典型应用场景
GPT-4o	综合能力强，工具调用成熟	通用 Agent
Claude Opus	长文本处理优秀，推理能力强	文档分析、复杂推理
Gemini	多模态能力强，免费额度高	图像+文本混合任务
本地模型（Llama）	数据隐私好，可离线运行	企业内部应用

选择合适的模型对 Agent 的效果影响很大，后续章节会详细介绍如何选择。

2、工具：赋予 Agent 行动能力

工具是 Agent 与外部世界交互的方式。一个工具本质上是一个函数，有明确的输入参数定义（通常用 JSON Schema 描述），LLM 可以根据任务需要决定调用哪个工具、传入什么参数。

常见工具类型及示例：

类型	具体示例	使用场景
信息检索	网络搜索、向量数据库查询、文档读取	获取实时信息、查询知识库
计算执行	代码解释器、计算器、SQL 执行	数学计算、数据分析
系统操作	文件读写、API 调用、数据库增删改查	自动化工作流
通信	发邮件、发消息、调用 Webhook	通知、协作

工具的 JSON Schema 定义示例：

// 定义一个天气查询工具的参数结构
const weatherToolSchema = {
  type: "object",
  properties: {
    city: {
      type: "string",
      description: "要查询天气的城市名称"
    },
    date: {
      type: "string",
      description: "查询的日期，格式为 YYYY-MM-DD"
    }
  },
  required: ["city"]  // city 是必填参数
};

💡 关键点：工具的描述（description）非常重要！LLM 会根据描述来决定是否调用这个工具。描述越清晰，Agent 的表现越好。

3、记忆：让 Agent 有上下文感知

记忆分为两类，就像人类的短期记忆和长期记忆：

（1）短期记忆（Short-term Memory）

作用： 记住当前会话的对话历史

实现方式： LLM 本身是无状态的，需要开发者把历史消息拼进每次请求的 Prompt 里，才能让它"记住"之前说了什么。

// 示例：维护对话历史
const conversationHistory = [
  { role: "user", content: "我喜欢吃川菜" },
  { role: "assistant", content: "好的，我记住了你喜欢川菜。" },
  { role: "user", content: "推荐一家餐厅" }
];

// 将历史发送给模型，它就能基于你的偏好推荐川菜馆

限制： 受限于模型的上下文窗口（Context Window），对话太长会被截断。

（2）长期记忆（Long-term Memory）

作用： 跨会话的持久化存储

存储内容：

• 用户的个人偏好（如"我喜欢川菜"）
• 历史任务结果
• 重要信息摘要

实现方式： 需要存到外部数据库（如 PostgreSQL、Redis），在需要时检索调用。第八章会详细讲解如何实现。

---

三、LangChain 生态全景

LangChain 不是一个单一的库，而是一个生态体系，包含四个主要组件。理解它们的关系，能帮你避免混淆。

flowchart TB subgraph 生态体系["LangChain 生态体系"] direction TB DA["Deep Agents
开箱即用的高级封装
内置长对话压缩、子 Agent 隔离等"] LC["LangChain
平衡易用性与灵活性的 Agent 框架
⭐ 推荐起点"] LG["LangGraph
底层图式 Agent 运行时
需要深度定制时使用"] LS["LangSmith
可观测性与评估平台
调试、监控、测试"] DA -->|基于| LC LC -->|基于| LG LG -.->|集成| LS end style DA fill:#e6f7ff,stroke:#1890ff style LC fill:#f6ffed,stroke:#52c41a,stroke-width:3px style LG fill:#fff7e6,stroke:#fa8c16 style LS fill:#f9f0ff,stroke:#722ed1

💡 学习建议 ：对于初学者，建议从 LangChain 入手，它能覆盖 80% 的使用场景。当你需要更精细的控制时，再下探到 LangGraph。

1、LangChain ------ 你的起点

LangChain 是这个生态的核心包（npm install langchain）。它提供了：

• 统一的模型接口：无论底层用 OpenAI、Anthropic 还是 Google，调用方式完全一致
• createAgent() API：用极少的代码创建一个具备工具调用能力的 Agent
• 预构建组件：提示词模板、消息管理、结构化输出、流式处理等

典型用法示例：

import { createAgent, tool } from "langchain";
import { z } from "zod";

// 第一步：定义工具
const search = tool(
  ({ query }) => `搜索结果：关于 "${query}" 的信息...`,
  { 
    name: "search", 
    description: "搜索互联网", 
    schema: z.object({ query: z.string() }) 
  }
);

// 第二步：创建 Agent
const agent = createAgent({ 
  model: "openai:gpt-4o", 
  tools: [search] 
});

// 第三步：调用 Agent
const result = await agent.invoke({ 
  messages: [{ role: "user", content: "LangChain 最新版本是什么？" }] 
});

代码分步解读：

1. 导入必要模块 ：createAgent 用于创建 Agent，tool 用于定义工具
2. 定义工具 ：使用 tool() 函数包装一个普通函数，同时提供名称、描述和参数校验（Zod Schema）
3. 创建 Agent：指定使用的模型和可用工具列表
4. 调用 Agent：传入用户消息，Agent 会自动决定是否调用工具

✨ 亮点：整个 Agent 的创建只用了不到 15 行代码！这就是 LangChain 的价值------帮你处理了复杂的底层逻辑。

2、LangGraph ------ 底层编排引擎

LangChain 的 Agent 是建立在 LangGraph 之上的。LangGraph 把 Agent 的执行过程抽象为一张有向图：

• 节点（Node）：执行步骤（如调用 LLM、执行工具）
• 边（Edge）：决定下一步去哪里
• 状态（State）：在节点之间流动的数据

flowchart LR Start([开始]) --> Agent[Agent 节点
调用 LLM 做决策] Agent -->|需要工具| Tools[工具节点
执行工具调用] Tools --> Agent Agent -->|任务完成| End([结束]) style Start fill:#e8f4fd,stroke:#1890ff style End fill:#f6ffed,stroke:#52c41a style Agent fill:#fff7e6,stroke:#fa8c16 style Tools fill:#fff0f6,stroke:#eb2f96

什么时候需要用 LangGraph？

• ✅ 需要人工审核节点（Human-in-the-loop）
• ✅ 需要条件分支（如果 A 则走路径 1，否则走路径 2）
• ✅ 需要多 Agent 协作
• ✅ 需要自定义状态管理

关系类比： LangGraph 之于 LangChain，就像 React 之于 Next.js------你可以直接用 Next.js（LangChain），也可以在需要时下探到 React（LangGraph）层去精细控制。

3、LangSmith ------ 可观测性平台

LLM 应用的调试和传统软件不一样。模型的推理过程是个黑盒，输出具有随机性，同一个 Prompt 在不同场景下表现可能截然不同。

LangSmith 能帮你解决这些问题：

• 追踪执行链路：每一步调用了哪个模型、用了什么 Prompt、输出是什么
• 捕获中间状态：Agent 的每次工具调用、每次推理决策
• 评估与测试：对 Agent 的输出进行系统性评估
• 监控生产环境：延迟、成本、错误率一览无余

接入方式极简------只需设置两个环境变量：

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your_api_key_here

之后所有的 LangChain 调用都会自动上报到 LangSmith 控制台，你可以在网页上看到完整的执行轨迹。

💡 强烈建议：即使是学习阶段，也建议接入 LangSmith。它能帮你直观地看到 Agent 的思考过程，对理解工作原理非常有帮助。

---

四、Python vs TypeScript：如何选择

很多人在开始学 LangChain 时会纠结：学 Python 版还是 TypeScript 版？

先说结论：两者在概念设计上完全一致，差异只在 API 风格层面。

1. 对比分析

维度	Python 版	TypeScript 版
社区生态	更成熟，第三方集成更多	持续追赶，核心功能齐全
类型安全	需要额外配置（mypy 等）	原生支持，IDE 体验更好
部署场景	AI/ML 服务端	Web 服务、Serverless、边缘计算
现有团队技术栈	数据科学/后端	前端/全栈/Node.js
社区教程数量	更多	较少，但本书在做

2. 选择建议

根据你的实际情况来选择：

• 已有 Python 团队，主要做后端服务 → Python 版更合适
• 全栈团队，需要前后端共用，或者想部署到 Vercel/Cloudflare → TypeScript 版更合适
• 只是学习目的，想了解 Agent 开发的思路 → 两个都可以，本书用 TypeScript

3. API 对比示例

为了让你直观感受两者的差异，这里展示同样的功能在两个版本中的写法：

Python 版：

from langchain import create_agent
from langchain_openai import ChatOpenAI

agent = create_agent(
    model=ChatOpenAI(model="gpt-4o"), 
    tools=[search_tool]
)
result = agent.invoke({
    "messages": [HumanMessage(content="你好")]
})

TypeScript 版：

import { createAgent } from "langchain";

const agent = createAgent({ 
  model: "openai:gpt-4o", 
  tools: [searchTool] 
});

const result = await agent.invoke({ 
  messages: [{ role: "user", content: "你好" }] 
});

核心思路完全一样，只是语法风格不同。 TypeScript 版本的字符串标识符（"openai:gpt-4o"）更加简洁。

---

五、LangChain.js 的版本演进与 v1.3.1 的定位

了解版本历史，能帮你避开很多网上陈旧教程的坑。

timeline title LangChain.js 版本演进 2023-01 : v0.0.x 发布 : JavaScript 版本首次亮相 : 基本的 Chain 和 Agent 支持 2024-01 : v0.1.0 : 架构稳定化 : 关注生产可用性 2024-02 : LangGraph 发布 : 底层编排能力补充 : 弥补 LangChain 控制流短板 2024-10 : v0.2.x ~ v0.3.x : LangGraph 深度集成 : 旧版 chains/agents 标记弃用 2025-10 : v1.0.0 重大更新 : 所有 Agent 迁移到 LangGraph : 全新的 createAgent API 2025-12 : v1.3.x : MCP 协议支持 : Anthropic 服务端工具 : 结构化输出 strict 模式

v1.3.1 的关键特点

1. createAgent() 是一等公民 ：新 API 简洁、类型安全，替代了旧版的 initializeAgentExecutorWithOptions
2. LangGraph 深度集成：每个 Agent 都运行在 LangGraph 图式运行时之上，持久化、流式、人工介入开箱即用
3. MCP 支持 ：通过 @langchain/mcp-adapters，Agent 可以直接接入 Model Context Protocol 工具生态
4. Provider 标识符格式 ：模型使用 "provider:model-name" 格式声明，如 "openai:gpt-4o"、"anthropic:claude-sonnet-4-6"

⚠️ 注意旧版教程

如果你在网上找到的教程里有以下 API，那是 v0.x 时代的旧写法，在 v1.x 中已经废弃：

• LLMChain
• ConversationChain
• initializeAgentExecutorWithOptions

本书所有内容均基于 v1.3.1 的最新 API，请放心参考。

---

六、本章小结

这一章的目的是建立认知地图，理解清楚几个核心关系：

📝 核心知识点回顾

问题	答案
AI Agent 是什么？	LLM + 工具 + 记忆，能自主完成多步骤任务的系统
LangChain 解决什么问题？	标准化 Agent 开发的基础设施，避免重复造轮子
LangChain 和 LangGraph 什么关系？	LangChain 高层 API 建立在 LangGraph 图式运行时之上
为什么选 TypeScript 版？	类型安全、Node.js 生态、前端同构，概念与 Python 版完全一致
v1.x 和 v0.x 最大的区别？	Agent 架构从旧版 chains 迁移到 LangGraph，createAgent() 是新入口

🎯 动手练习

尝试回答以下问题，检验学习效果：

1. 概念理解：用自己的话解释 AI Agent 的三个构成要素，并举例说明每个要素的作用。

2. 场景分析：如果要构建一个"智能订餐助手"，它会用到哪些类型的工具？请列出至少 3 个。

3. 技术选型：你的团队主要使用 JavaScript/TypeScript 技术栈，想要构建一个可以部署到 Vercel 的 AI 客服机器人，应该选择哪个版本的 LangChain？为什么？

4. 版本识别：看到以下代码片段，判断它是 v0.x 还是 v1.x 的写法：

   const executor = await initializeAgentExecutorWithOptions(tools, llm, {
     agentType: "zero-shot-react-description"
   });

📚 延伸阅读

• LangChain 官方文档
• LangGraph 概念介绍
• LangSmith 快速入门

---

下一章：《第二章 ------ 环境搭建与快速上手》(待撰写)