跳到主要内容

LangChain — 架构与原理

30 秒导读: LangChain 是一个"搭 AI agent 的框架"。你给它一个模型名和一组工具,它就还给你一个能"想一步→调工具→看结果→再想"循环到底的 agent。它最核心的两个设计:(1) 这个循环不是一个 while 循环,而是被编译成一张状态图(底层是 LangGraph),天然带持久化/流式/断点续跑;(2) 所有想往这个循环里插的自定义行为(压缩历史、人工审批、出错重试、结构化输出),都被统一成一种叫 middleware(中间件) 的东西。

1. 这是什么(零基础也能懂)​

一句话定义: LangChain 是用来搭建 LLM agent 和应用的 Python/JS 框架——它给"调用大模型"和"让大模型在循环里调用工具"这件事,提供了一套标准积木。

解决什么问题 / 给谁用。 假设你想做一个能"查天气、订机票、改代码"的助手。底层无非是反复做一件事:

  1. 把对话历史发给大模型;
  2. 模型说"我要调 check_weather('SF')";
  3. 你的代码真去执行这个函数,把结果塞回对话;
  4. 再发给模型,直到模型不再要调工具、直接给出答案。

这个循环(业界叫 agentic loop)谁都会写,但要把它做得可流式输出、可中途人工审批、可断点续跑、可换模型、可裁剪超长历史,就很费劲。LangChain 把这些都预置好了。

它能做什么(功能):

  • 用一行 init_chat_model("openai:gpt-5.5") 连上任意厂商的模型,换厂商不改代码。
  • 用一行 create_agent(model, tools) 得到一个完整的 agent。
  • 用 middleware 往 agent 循环里插行为:压缩历史、人工审批工具调用、模型出错重试、限制调用次数、结构化输出……
  • 底层基于 LangGraph,白送持久化(checkpointer)、流式、断点(interrupt)。

用起来什么样。 这是官方 docstring 里的最小示例(libs/langchain_v1/langchain/agents/factory.py:942-960):

from langchain.agents import create_agent


def check_weather(location: str) -> str:
    """Return the weather forecast for the specified location."""
    return f"It's always sunny in {location}"


graph = create_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    tools=[check_weather],
    system_prompt="You are a helpful assistant",
)
inputs = {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
for chunk in graph.stream(inputs, stream_mode="updates"):
    print(chunk)

注意返回值叫 graph——不是一个对象方法,而是一张可以 .stream() / .invoke() 的状态图。这是理解整个项目的钥匙。

一句话直觉/类比。 把 agent 想成一台流水线机器:create_agent 不是"造一个会跑的程序",而是画一张电路图(哪个节点连哪个节点、什么条件下分叉),然后"通电"(.invoke)让数据在图里流动。Middleware 就是你往这条流水线的特定工位上"插"的检查站。

2. 顶层全景(它大概怎么转)​

这个仓库是 monorepo,核心是两层叠起来的:

   你的代码
      │  create_agent(model, tools, middleware=[...])
      ▼
┌───────────────────────────────────────────────┐
│  langchain_v1  (libs/langchain_v1/langchain)    │  ← agent 层
│   · create_agent  把循环编译成状态图            │
│   · middleware     可插拔行为(20+ 内置)        │
│   · init_chat_model 统一模型入口                │
└───────────────────────────────────────────────┘
      │ 依赖
      ▼
┌───────────────────────────────────────────────┐
│  langchain_core  (libs/core/langchain_core)     │  ← 抽象地基
│   · Runnable / LCEL  一切组件的统一接口 (| 串联)│
│   · BaseChatModel    模型抽象 (.invoke/.bind_tools)│
│   · BaseTool         工具抽象                    │
│   · messages         AIMessage / ToolMessage …  │
└───────────────────────────────────────────────┘
      │ 依赖(图运行时,独立仓库)
      ▼
   LangGraph  (StateGraph / 持久化 / interrupt)

各层一句话职责:

层干什么在哪
langchain_v1把 agent 循环 + 中间件编译成图,提供统一模型入口libs/langchain_v1/langchain/
langchain_core定义 Runnable(可组合接口)、模型/工具/消息抽象libs/core/langchain_core/
LangGraph真正跑图的运行时(状态、持久化、断点)——独立仓库,这里只作依赖(外部)

主线走一遍(高层,不进代码):

  1. 你调 create_agent(...),它读你的 model/tools/middleware,在内存里画一张状态图:核心是 model 节点和 tools 节点,中间件的各个钩子被插成额外的节点和边。
  2. 你调 graph.invoke({"messages": [...]}),数据(state,核心字段是 messages 列表)开始在图里流。
  3. 到 model 节点:把历史发给大模型,拿回一条 AIMessage。
  4. 一条条件边看这条消息:有 tool_calls → 去 tools 节点执行工具,把 ToolMessage 追加进 messages,再绕回 model;没有 → 走到 END,循环结束。
  5. 全程,中间件可以在 model 前后、tools 前后插手,甚至把模型调用整个"包起来"(retry / fallback)。

阅读地图(建议顺序):

  • 先读 01-agent-loop.md —— 看懂 create_agent 怎么把循环"画"成图,这是整个项目的主线。
  • 再读 02-middleware.md —— 中间件是 LangChain v1 最有特色的设计,六个钩子 + 两种"洋葱式"包装。
  • 想懂"为什么能 | 串"读 03-runnable-lcel.md —— langchain_core 的 Runnable 抽象,所有上层能力的地基。
  • 关心模型接入/工具/结构化输出读 04-models-tools-structured.md。

3. 一眼看懂的三件事(精华预告)​

这三点是读完全套文档你该带走的:

  1. "agent = 编译出来的图",不是对象。 create_agent 返回 CompiledStateGraph,所以 agent 白嫖了 LangGraph 的持久化、流式、断点。循环的退出条件就是图里一条条件边的逻辑(factory.py:_make_model_to_tools_edge)。

  2. 中间件把"修改 agent 行为"统一成两种形态。 一种是节点式钩子(before_model/after_model 等,插成图节点);另一种是包装式钩子(wrap_model_call/wrap_tool_call,像洋葱一层层裹住模型/工具调用,可重试、可短路)。压缩历史、人工审批、重试、限流全是它的实例。

  3. Runnable 是地基:一切皆可 |。 模型、工具、提示词、解析器都实现同一个 Runnable 接口,a | b 就拼成一条链,自动获得 invoke/stream/batch/async 四套执行方式(langchain_core/runnables/base.py:Runnable.__or__)。

4. 代码地图(导航索引)​

主题文件路径关键符号
agent 工厂入口libs/langchain_v1/langchain/agents/factory.pycreate_agent
图的节点/边装配libs/langchain_v1/langchain/agents/factory.pygraph.add_node / _add_middleware_edge
循环退出条件libs/langchain_v1/langchain/agents/factory.py_make_model_to_tools_edge / _make_tools_to_model_edge
中间件基类与钩子libs/langchain_v1/langchain/agents/middleware/types.pyAgentMiddleware / ModelRequest / ModelResponse
wrap_model_call 组合libs/langchain_v1/langchain/agents/factory.py_chain_model_call_handlers
中间件目录libs/langchain_v1/langchain/agents/middleware/__init__.pySummarizationMiddleware / HumanInTheLoopMiddleware …
统一模型入口libs/langchain_v1/langchain/chat_models/base.pyinit_chat_model / _init_chat_model_helper
可组合接口地基libs/core/langchain_core/runnables/base.pyRunnable / RunnableSequence
模型抽象libs/core/langchain_core/language_models/chat_models.pyBaseChatModel / bind_tools
工具抽象libs/core/langchain_core/tools/base.pyBaseTool
结构化输出策略libs/langchain_v1/langchain/agents/structured_output.pyToolStrategy / ProviderStrategy / AutoStrategy