LangChain

一句话定位

一个分层的 LLM 应用 / agent 工程平台：底层 langchain-core 用 Runnable 协议把模型 / 工具 / 提示 / 检索器统一成可组合、可流式、可批处理的 LCEL 管道；上层 langchain(v1) 以 create_agent() 提供一个编译成 LangGraph 状态图的工具循环 agent，并把所有可扩展点收敛到一套 middleware 钩子上——核心卖点是“模型可互换、组件可组合、agent 可控可观测”。

设计理念 / 顶层架构

LangChain 是一个 uv 管理的大型 monorepo（libs/ 下多包独立版本，见 CLAUDE.md）。聚焦本笔记的三个主包及其分层关系：

• 核心层 langchain-core（libs/core/langchain_core/）：定义基础抽象，用户一般无需直接接触。最关键的是 Runnable 协议（libs/core/langchain_core/runnables/base.py:125）——统一 invoke / batch / stream / ainvoke（runnables/base.py:823,868,1131）四件套，配合 | 运算符组成 LCEL 管道（RunnableSequence/RunnableParallel）。模型 BaseChatModel（libs/core/langchain_core/language_models/chat_models.py:270）、工具 BaseTool（libs/core/langchain_core/tools/base.py:405，本身就是个 RunnableSerializable）、检索器、提示模板全是 Runnable，因此天然可换、可串、可观测。
• 实现层 langchain(v1, version 1.3.4)（libs/langchain_v1/langchain/）：当前主力包。入口极薄——__init__.py 只导出 __version__，真正面向用户的入口是 langchain.agents.create_agent（agents/__init__.py:3）。它依赖 langgraph（libs/langchain_v1/pyproject.toml:28）：create_agent() 不是自己实现循环，而是把 model 节点 / tools 节点 / middleware 节点装配成一张 StateGraph 再 compile()（agents/factory.py:1048,1671）。
• 遗留层 langchain-classic(version 1.0.7)（libs/langchain/langchain_classic/）：老的 AgentExecutor / chains 体系（langchain_classic/agents/），CLAUDE.md 明确标注 “legacy, no new features”。本笔记以 v1 体系为准。
• 集成层 partners/：OpenAI / Anthropic / Ollama 等具体 ChatXxx 实现，通过 init_chat_model("provider:model") 按字符串前缀懒加载（chat_models/base.py:38 的 _BUILTIN_PROVIDERS 表，base.py:175 的 init_chat_model）。

与 LangGraph 的关系（关键）：v1 的 agent 是 LangGraph 的“prebuilt 之上的封装”。工具循环的实际执行（ToolNode、ToolCallRequest、InjectedState、interrupt、checkpointer、Send 并行）全部来自 langgraph——langchain/tools/tool_node.py 整个文件只是从 langgraph.prebuilt 重导出（tool_node.py:3）。LangChain 负责“模型抽象 + middleware DX”，LangGraph 负责“图运行时 + 持久化”。README 进一步指向 Deep Agents（planning/subagents/文件系统的更高层封装）与 LangSmith（可观测/评估）。

最小示例（取自 agents/factory.py:831 docstring 与 README）：

from langchain.agents import create_agent


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


# create_agent 返回的是一个编译好的 LangGraph StateGraph
graph = create_agent(
    model="anthropic:claude-sonnet-4-5-20250929",  # 字符串 -> init_chat_model 懒加载 provider
    tools=[check_weather],                          # 普通函数自动转 BaseTool
    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)

组件实现（横向逐项）

设计权衡与特性

• 分层抽象是核心信条：core 的 Runnable/LCEL 让“模型可互换、组件可组合”成为底座；init_chat_model 一行换 provider 是它对比手写 SDK 的最大卖点。代价是抽象层很厚、概念多（Runnable/Chain/Tool/Retriever/Middleware/Graph），学习曲线陡。
• v1 把 agent 让位给 LangGraph：与 ConnectOnion/Swarm “自己写 while 循环”不同，LangChain v1 的 create_agent 把循环编译成状态图，换来可中断、可 checkpoint、可并行工具调用、可嵌套子图等图运行时能力——可控性强，但意味着 langchain 与 langgraph 强耦合（pyproject 锁 langgraph>=1.2.4,<1.3.0），调试需理解两层。
• middleware 是统一扩展面：planning、记忆压缩、HITL、重试、PII、shell 沙箱、结构化输出全部表达为同一套钩子（before/after/wrap × agent/model/tool），可任意叠加、按注册顺序组合成洋葱（factory.py:271 compose_two）。这是 v1 相对 v0 AgentExecutor 黑盒的最大架构改进。
• 结构化输出双策略：ProviderStrategy(原生 JSON schema) vs ToolStrategy(伪装成工具调用)，按模型能力 AutoStrategy 自动选择（factory.py:871,1220、structured_output.py），兼顾不同 provider。
• monorepo + partner 解耦：核心抽象与具体集成分包，partner 包按需安装（pyproject.toml:32 optional-deps），core 不依赖任何 SDK——保证“换模型不换代码”。
• 待确认/坑：①笔记基于仓库内 langchain_v1(主力,1.3.4) 与 langchain-classic(遗留,1.0.7) 并存，导入路径与教程版本极易混淆（import langchain.agents 走 v1，老教程的 AgentExecutor 在 classic）；②ToolNode/interrupt/checkpointer 等实现实际在 langgraph 仓库（本仓库内仅重导出），深入需另读 langgraph 源码；③评估/部署能力（LangSmith）为闭源 SaaS，OSS 仅提供 tracer 钩子。

关联

• component-taxonomy · single-vs-multi-agent · multi-agent-orchestration · model-abstraction
• 同范式(平台/可组合)：connectonion · 极简对照：swarm · 源码：agents-example/langchain/（聚焦 libs/core、libs/langchain_v1）