第一章：LangChain 生态系统概述与环境搭建

1. LangChain 是什么

LangChain 是一个开源框架，提供预构建的 Agent 架构和丰富的集成生态，专门用于构建由大语言模型（LLM）驱动的智能代理和应用。自 2022 年发布以来，LangChain 已经从一个简单的 LLM 封装库演进为一个完整的 Agent 开发生态系统。

核心优势

优势	说明
标准化模型接口	为不同 LLM 提供统一的调用抽象，切换模型只需修改一行代码
易用灵活的 Agent	通过 create_agent 等高级 API，几行代码即可构建功能完备的 Agent
基于 LangGraph 构建	底层编排引擎支持复杂的有状态工作流，具备持久化和流式传输能力
LangSmith 可观测性	内置追踪、评估和调试工具，让 Agent 的每一次推理过程都清晰可见
丰富的 Provider 集成	原生支持 OpenAI、Anthropic、Google、AWS、HuggingFace 等主流模型提供商

LangChain 的核心理念是：让开发者专注于 Agent 的业务逻辑，而非底层基础设施。无论是简单的对话机器人、RAG 检索增强系统，还是复杂的多 Agent 协作工作流，LangChain 都提供了从原型到生产的完整工具链。

---

2. LangChain 生态系统全景

LangChain 生态系统由三个核心层次和一个平台层组成，它们各司其职又紧密协作。

2.1 生态架构总览

┌─────────────────────────────────────────────────────┐
│                   LangSmith                         │
│          （追踪 · 评估 · 提示 · 部署）                 │
├─────────────────────────────────────────────────────┤
│                                                     │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────┐  │
│   │  Deep Agents │  │  LangChain   │  │LangGraph    │
│   │  （全包套件）  │  │ （Agent 框架）│  │（编排层） │   │
│   └──────────────┘  └──────────────┘  └──────────┘  │
│                                                     │
├─────────────────────────────────────────────────────┤
│              模型 / 工具 / 数据源                     │
│   OpenAI · Anthropic · Google · AWS · HuggingFace   │
└─────────────────────────────────────────────────────┘

2.2 各层详解

Deep Agents — 全包式 Agent 开发套件

Deep Agents 是面向"开箱即用"场景的高级 Agent 开发套件，内置了构建生产级 Agent 所需的一切组件：

• 内置规划引擎：自动将复杂任务分解为可执行的子步骤
• 子代理管理：支持创建和管理多个子代理并行协作
• 文件系统工具：原生的文件读写、搜索和管理能力
• 上下文管理：智能的上下文窗口管理，自动处理长对话和大量工具输出

适用场景：当你需要快速构建一个功能完整的 Agent，而不想手动组装各个组件时。

LangChain — Agent 框架层

LangChain 本身作为 Agent 框架层，提供核心抽象和集成：

• 模型抽象：为不同 LLM 提供统一的 init_chat_model 接口
• 工具系统：通过 @tool 装饰器轻松将任意 Python 函数转化为 Agent 工具
• Agent 循环：通过 create_agent 构建模型与工具之间的调用循环
• 消息管理：标准化的消息格式（SystemMessage、HumanMessage、AIMessage 等）
• 中间件机制：通过 Middleware 自定义 Agent 的行为链路

适用场景：从零开始构建 Agent，需要灵活控制每个环节。

LangGraph — 编排运行时层

LangGraph 是底层的编排运行时，为复杂工作流提供：

• 持久执行：任务可以在任意节点暂停并恢复，支持长时间运行的工作流
• 流式传输：支持 Token 级、步骤级等多种粒度的流式输出
• 人机协作（Human-in-the-loop）：在关键节点引入人类审核和决策
• 状态持久化：内置检查点机制，支持对话历史和工作流状态的持久化存储
• 确定性与代理混合：在同一工作流中混合确定性逻辑和 LLM 驱动的代理逻辑

适用场景：需要高度自定义的工作流编排，尤其是确定性逻辑与 Agent 逻辑混合的场景。

LangSmith — 平台层

LangSmith 是贯穿整个开发周期的可观测性平台：

• 追踪（Tracing）：记录 Agent 的每一步推理、工具调用和中间状态
• 评估（Evaluation）：自动化评估 Agent 的输出质量
• 提示管理（Prompt Hub）：集中管理和版本化 Prompt
• 部署监控：线上 Agent 的性能监控和告警

2.3 如何选择

场景	推荐方案	理由
从零快速构建 Agent	LangChain	标准化接口 + 丰富集成，几行代码即可启动
高度自定义的确定性+代理混合工作流	LangGraph	支持复杂的图结构编排和精细的流程控制
需要开箱即用的完整 Agent 能力	Deep Agents	内置规划、子代理、文件系统等全套能力
需要生产级可观测性	LangSmith	追踪、评估、部署一站式平台

实践建议：大多数项目建议以 LangChain 起步，当工作流复杂度增加时引入 LangGraph 进行编排，同时始终配合 LangSmith 进行调试和监控。Deep Agents 适合希望快速获得完整 Agent 能力而减少胶水代码的场景。

---

3. 环境搭建

3.1 Python 版本要求

LangChain 要求 Python 3.9 及以上版本。推荐使用 Python 3.11+ 以获得最佳性能和兼容性。

验证当前 Python 版本：

python3 --version

建议使用虚拟环境管理依赖，避免版本冲突：

python3 -m venv .venv
source .venv/bin/activate    # macOS / Linux
# .venv\Scripts\activate     # Windows

3.2 安装方式

核心安装

安装 LangChain 核心包：

pip install -U langchain

按 Provider 安装

LangChain 采用模块化架构，各模型提供商通过可选依赖的方式引入。根据你使用的 LLM 选择对应的安装命令：

# OpenAI（GPT-4o / GPT-4.1 等）
pip install -U "langchain[openai]"

# Anthropic（Claude 4 Sonnet / Claude 4 Opus 等）
pip install -U "langchain[anthropic]"

# Google（Gemini 2.5 Pro / Gemini 2.5 Flash 等）
pip install -U "langchain[google-genai]"

# AWS（Amazon Bedrock 托管模型）
pip install -U "langchain[aws]"

# HuggingFace（开源模型 Hub）
pip install -U "langchain[huggingface]"

你也可以在一个环境中安装多个 Provider，它们互不冲突：

pip install -U "langchain[openai]" "langchain[anthropic]"

LangGraph 安装

当需要自定义复杂工作流编排时，安装 LangGraph：

pip install -U langgraph

Deep Agents 安装

当需要开箱即用的全功能 Agent 套件时，安装 Deep Agents：

pip install -U deepagents

3.3 环境变量配置

各模型提供商的 API Key 通过环境变量注入。以下是常用的配置方式：

import os

os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..."
os.environ["GOOGLE_API_KEY"] = "..."

推荐在项目根目录创建 .env 文件管理密钥，配合 python-dotenv 加载：

pip install python-dotenv

from dotenv import load_dotenv
import os

load_dotenv()

.env 文件示例：

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

安全提醒：切勿将 .env 文件提交到版本控制系统。请确保 .env 已添加到 .gitignore。

3.4 LangSmith 配置（可选但强烈推荐）

LangSmith 提供 Agent 运行过程的全链路追踪，在开发和调试阶段极为有用。

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-api-key"

或在 .env 文件中添加：

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your-api-key

配置完成后，LangChain 会自动将每次调用的详细 Trace 发送到 LangSmith 控制台，你可以在 smith.langchain.com 查看：

• Agent 的推理过程和决策链路
• 每次工具调用的输入输出
• Token 消耗和延迟指标
• 错误详情和堆栈信息

---

4. 快速上手：10 行代码构建第一个 Agent

以下示例展示如何用 LangChain 最新的 create_agent API 构建一个具备工具调用能力的 Agent。

核心 API：create_agent（来自 langchain.agents）

# pip install -qU langchain "langchain[anthropic]"
from langchain.agents import create_agent


def get_weather(city: str) -> str:
    """获取指定城市的天气信息"""
    return f"{city}的天气总是晴朗的！"


agent = create_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[get_weather],
    system_prompt="你是一个有用的助手",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]}
)
print(result["messages"][-1].content)

代码解析：

1. create_agent 接收 model、tools、system_prompt 三个核心参数
2. model 使用 provider:model 格式指定，无需手动实例化模型对象
3. tools 接收一个函数列表，LangChain 自动从函数签名和文档字符串生成工具描述
4. agent.invoke() 执行 Agent 循环：模型接收消息 → 判断是否调用工具 → 执行工具 → 将结果回传模型 → 生成最终回答
5. 最终结果存储在 result["messages"] 的最后一条消息中

---

5. 核心概念速览

在深入学习之前，先理解 LangChain 的五大核心概念：

Model（模型）

LLM 推理引擎，驱动 Agent 的决策过程。LangChain 通过统一的 init_chat_model 函数抽象了不同提供商的差异：

from langchain.chat_models import init_chat_model

model = init_chat_model("anthropic:claude-sonnet-4-6")

Message（消息）

上下文的基本单元，每条消息携带角色（role）、内容（content）和可选的元数据。LangChain 定义了标准的消息类型：

消息类型	说明
SystemMessage	系统指令，定义 Agent 的行为规范
HumanMessage	用户输入
AIMessage	模型的回复，可能包含工具调用请求
ToolMessage	工具执行的结果

Tool（工具）

Agent 可调用的外部函数，扩展了 LLM 的能力边界。工具可以是数据库查询、API 调用、文件操作等任何可编程的能力。LangChain 提供两种定义方式：

from langchain.tools import tool


# 方式一：使用 @tool 装饰器（推荐）
@tool
def search_database(query: str) -> str:
    """在数据库中搜索信息"""
    return f"搜索结果：{query}"


# 方式二：使用 StructuredTool（需要更精细控制时）
from langchain.tools import StructuredTool
from pydantic import BaseModel


class SearchInput(BaseModel):
    query: str
    limit: int = 10

Agent（代理）

Agent 是 LangChain 的核心抽象，代表模型在一个循环中不断调用工具直到完成任务的过程：

用户输入 → 模型推理 → (调用工具 → 获取结果 → 模型推理) → 最终回答
                  ↑_________循环直到任务完成_________↑

Middleware（中间件）

中间件是自定义 Agent 行为的扩展机制，允许你在 Agent 循环的各个环节插入自定义逻辑，如日志记录、速率限制、输入输出过滤等。

---

6. 学习路线建议

根据你的经验水平，选择合适的学习路径：

初学者路线

从基础概念入手，逐步构建对 LangChain 核心组件的理解：

1. Models — 学习如何初始化和调用不同 LLM，理解 init_chat_model 的统一接口
2. Messages — 掌握消息类型和对话历史管理
3. Tools — 学习定义和使用工具，理解工具描述对 Agent 行为的影响
4. Agents — 使用 create_agent 构建第一个完整 Agent

进阶路线

在掌握基础后，深入 LangGraph 的编排能力：

1. LangGraph 基础 — 学习图节点（Node）、边（Edge）和状态（State）的概念
2. Persistence（持久化） — 使用 Checkpointer 实现对话历史和工作流状态的持久化
3. Human-in-the-loop（人机协作） — 在 Agent 工作流中引入人类审核节点，实现关键步骤的可控性

高级路线

面向生产环境的高级主题：

1. Deep Agents — 使用全包套件快速构建复杂 Agent 系统
2. Context Engineering（上下文工程） — 精细化管理 Agent 的上下文窗口，优化信息输入策略
3. Multi-agent（多 Agent 协作） — 设计多个 Agent 之间的协作模式和通信机制
4. 生产部署 — 结合 LangSmith 进行监控、评估和持续优化，将 Agent 部署到生产环境

---

下一章预告：第二章 — Chat Models 与消息系统 将深入讲解 LangChain 的模型抽象层和消息管理机制。