🦜🔗 LangChain 1.0 核心机制与开发指南 (2026版)

一、 LangChain 1.0 的核心变革

LangChain 1.0 是一个里程碑版本，从过去的硬编码“链式调用”（Chains）全面转向了 Agent（智能体）模式，并对包结构进行了大刀阔斧的精简。

1. 核心理念与架构变化

• 弃用复杂的旧 API：废弃了 initialize_agent、create_react_agent 等五花八门的入口。
• 统一的新标准：全面采用底层基于 LangGraph 的 create_agent 作为构建 Agent 的唯一标准入口。
• 依赖包精简：
  • langchain: 核心骨架，专注于 Agent 构建。
  • langchain-classic: 兼容包，存放老版本的 LLMChain、检索器等。

---

二、 create_agent 与工具系统

create_agent 核心实现的是 ReAct (Reasoning + Acting) 循环模式，即：模型思考 -> 决定是否调用工具 -> 工具执行 -> 模型整合结果。

1. Agent 初始化参数详解

from langchain.agents import create_agent
agent = create_agent(
    model="gpt-4o",                           # LLM 模型名称或 ChatModel 实例
    tools=[get_weather, calculate],           # 工具列表
    system_prompt="你是一个有帮助的中文助手",    # Agent 人设
    # checkpointer=MemorySaver(),             # 开启持久化上下文记忆
    # middleware=[...],                       # 注入自定义逻辑中间件
)

2. 工具 (Tools) 的三种定义方式

在 1.0 中，工具的定义被极大地简化，核心依赖函数签名和 Docstring 作为 LLM 识别调用时机的依据。

1. 纯 Python 函数（最推荐）：只需写好类型注解和详尽的注释。

   def search_web(query: str) -> str:
       """在互联网上搜索最新信息。当被问及实时数据时必须调用。"""
       return f"搜索 '{query}' 的结果..."
   

2. @tool 装饰器：适合需要配置额外参数或复杂输入的场景。
3. 内置/社区集成：直接实例化 langchain_community.tools.XXX。

---

三、 Message 系统与 Content Blocks

Message 是 LangChain 与底层大模型交互的唯一“通用语言”。

1. 五种核心 Message 类型

类型	作用	示例场景
SystemMessage	系统指令	“你是一个精通Python的专家”（最高优先级）
HumanMessage	用户输入	“请帮我写一段冒泡排序”（1.0已全面支持多模态输入如图片）
AIMessage	AI 回复	“好的，代码如下…”（或包含 tool_calls 请求操作外部环境）
ToolMessage	工具执行结果	“北京天气25度”（必须提供由 AIMessage 传来的 tool_call_id 匹配）
AIMessageChunk	流式输出	实时生成打字机效果时的消息碎片

2. Content Blocks（内容块）机制

这是 1.0 的重大创新。过去 OpenAI、Claude、Gemini 各自返回特定格式的“思维链”和工具调用详情，代码极其难兼容。Content Blocks 将所有大模型的复杂返回值统一化了：

ai_message = result["messages"][-1]
for block in ai_message.content_blocks:
    if block.type == "text":
        print(f"标准回答: {block.text}")
    elif block.type == "reasoning":
        print(f"模型思考过程: {block.reasoning}")
    elif block.type == "tool_use_summary":
        print(f"动作摘要: {block.summary}")
    elif block.type == "citation":
        print(f"参考来源: {block.source}")

---

四、 中间件系统 (Middleware) 剖析

中间件是 LangChain 1.0 的核心解耦机制，采用洋葱模型。它允许你在 Agent 获取输入到产生输出的每一个生命周期节点注入代码，而不影响业务核心。

1. 六个生命周期钩子 (Hooks)

1. on_agent_start: Agent 会话开始。
2. on_before_model_call: 即将拼装上下文发给 LLM。（常用：敏感词脱敏、长上下文强制压缩摘要）。
3. on_after_model_call: 刚拿到大模型的原生返回值。
4. on_before_tool_call: 即将执行外部工具。（核心场景：Human-in-the-loop 人工审批，比如拦截 delete_database 工具要求人类确认）。
5. on_after_tool_call: 工具执行完毕拿到输出。
6. on_agent_end: 整个会话循环结束。（常用：调用链路统计、计费日志）。

---

五、 Agent 记忆机制的底层真相

核心原理：Agent 本身是无状态的（没有记忆）。所有所谓的“记忆”，本质上就是把之前所有的对话记录保存下来，并在下一次请求时全部塞进 Context 里，随用户的最新问题一起发送给 LLM。
目前工业界存在三种主流记忆处理策略：

1. 全量记忆 (Buffer Memory)

• 做法：无脑保存历次对话，原文传递。
• 优缺点：100%零信息损失，仅适合短命对话。一长立刻 Token 爆炸。

2. 摘要记忆 (Summary Memory)

• 做法：当 messages 大于设定阈值，调用 LLM 将旧对话总结为摘要。
• 优缺点：Token 消耗稳定。但细节会丢失。适合常规客服对话。

3. 向量记忆 (Vector Memory)

• 做法：做 Embedding 存入向量数据库。新提问来时关联检索作为上下文单次注入。
• 优缺点：最节约 Token，支持长达几个月的“跨会话”长期记忆。但时序感弱。

---

六、 完整实战代码示例 (多工具 + 摘要记忆)

这是一个集成了天气查询工具、SQLite 持久化全量记忆、以及对话历史过长时自动压缩成摘要的生产级示例：

from langchain.agents import create_agent
from langchain.agents.middleware import conversation_summary
from langgraph.checkpoint.sqlite import SqliteSaver
# ================= 1. 定义工具 =================
def get_weather(location: str) -> str:
    """获取指定城市的天气状况，若用户询问天气必须调用本工具。"""
    # 模拟外部API返回
    weather_data = {
        "北京": "晴天，25度，适合出行。",
        "上海": "多云，28度，有轻微降水概率。"
    }
    return weather_data.get(location, "抱歉，无法获取该地的天气。")
# ================= 2. 准备持久化和中间件 =================
# SqliteSaver 将所有会话持久化存储到本地 db 文件，防止程序崩溃丢失记忆
memory = SqliteSaver.from_conn_string("chat_history.db")
# conversation_summary 是官方内置中间件，当 messages > 10 条，
# 会自动将前面的对话压缩成系统背景摘要，极大地保护 Token 消耗。
middlewares = [conversation_summary(max_messages=10)]
# ================= 3. 创建 Agent =================
agent = create_agent(
    model="gpt-4o",  # 确保你安装了 langchain-openai 并且配了 OPENAI_API_KEY
    tools=[get_weather],
    system_prompt="你是一位贴心的私人生活助理。",
    checkpointer=memory,
    middleware=middlewares
)
# ================= 4. 测试持续对话 =================
# configurable 中的 thread_id 就相当于用户的 "会话ID"
config = {"configurable": {"thread_id": "user_alan_001"}}
def chat_with_agent(user_message):
    print(f"\n用户: {user_message}")
    # 每次发起调用，框架会自动从 sqlite 拿到上面的这段对话历史记录，并拼接当前话语传给 LLM
    result = agent.invoke(
        {"messages": [{"role": "user", "content": user_message}]},
        config=config
    )
    # 取出 AI 最新的那一条回复
    print(f"AI: {result['messages'][-1].content}")
# 第一轮（Agent会调用 get_weather 工具）
chat_with_agent("嗨，我叫艾伦！查一下北京天气如何？")
# 第二轮（Agent并没有去查库，但是它从 DB 中的 checkpointer 取出了上一轮的历史所以记得你的名字）
chat_with_agent("你能结合天气情况给我今天的穿搭建议吗？顺带一提，我是谁？")