精读 LangChain 官方文档（一）总览、安装与快速开始：从 create_agent 跑通第一个智能体

本文基于 LangChain Python 官方文档整理：
Overview：https://docs.langchain.com/oss/python/langchain/overview
Install：https://docs.langchain.com/oss/python/langchain/install
Quickstart：https://docs.langchain.com/oss/python/langchain/quickstart
对应开源文档：
https://github.com/langchain-ai/docs/tree/main/src/oss/langchain

大模型应用的发展，正在从单次问答式调用，转向更复杂的 Agent 应用形态。

在早期场景中，开发者只需要把一段 prompt 发送给模型，再接收一段文本响应；但在真实业务系统里，模型往往还需要调用工具、读取外部数据、维护对话状态、处理中间结果，并在必要时接受追踪、评估和人工干预。

因此，LangChain 入门文档真正要回答的，并不是“如何安装一个 Python 包”，也不是“如何运行一个最小示例”，而是一个更基础的工程问题：

如何把大模型从一个文本生成接口，组织成一个可以参与业务流程的 Agent 运行框架？

本文精读 LangChain 官方文档中的 Overview、Install 和 Quickstart 三个页面。它们共同构成了 LangChain 的最小入门闭环：先理解 LangChain 在 Agent 工程中的位置，再完成本地环境与模型供应商接入，最后通过 create_agent 跑通第一个可执行的智能体。

1. LangChain（框架定位）：它到底解决什么问题

它解决的问题：
LangChain 解决的是“如何把大模型接进真实应用”，而不是只解决“如何向模型发一句话”。

如果只是调用一次模型 API，代码可能很短：

用户输入 -> 模型回答

但真实业务通常不是这样。比如企业客服助手要先理解用户问题，再查询订单、读取售后规则、决定是否需要人工介入，最后生成回答。

更真实的流程是：

用户任务 -> 模型判断 -> 调用工具 -> 读取结果 -> 继续判断 -> 返回答案

LangChain 的价值就在这里：它提供一套标准方式，把模型、工具、提示词和运行状态组装起来。

示例：

import os

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="qwen3.7-max",
    api_key=os.environ["QWEN_API_KEY"],
    base_url=os.environ["QWEN_BASE_URL"],
)

agent = create_agent(
    model=model,
    tools=[],
    system_prompt="你是一名耐心的中文技术讲解助手。",
)

这里：

• ChatOpenAI：LangChain 里的 OpenAI-compatible 聊天模型客户端，这里用来接入兼容 OpenAI 协议的 qwen3.7-max。
• model：模型实例，是真正负责理解和生成的部分。
• create_agent：LangChain 创建智能体的核心入口函数。
• tools=[]：工具列表。空列表表示当前 Agent 暂时不调用外部工具。
• system_prompt：系统提示词，用来约束 Agent 的角色、语气和边界。

业务场景：
如果你做一个“公司制度问答助手”，模型只负责生成回答远远不够。它还需要知道能不能查知识库、能不能调用员工权限接口、回答是否需要引用来源。LangChain 就是把这些东西组织起来的工程框架。

最简记法：
LangChain 是让模型进入真实应用的 Agent 工程框架。

2. Agent = Model + Harness：官方总览里最重要的一句话

它解决的问题：
这句话帮我们区分“模型能力”和“应用能力”，避免把所有问题都归因于模型聪不聪明。

Model 是模型。它擅长理解语言、生成文本、判断下一步。

Harness 可以理解成“运行外壳”或“任务工作台”。它包括：

• prompt：提示词，告诉模型按什么角色和规则工作。
• tools：工具，让模型可以请求外部系统做事。
• middleware：中间件，在模型调用和工具调用前后加入策略。
• state：状态，保存消息、工具调用和中间结果。
• checkpointer：检查点，让会话和任务可以恢复。
• tracing：追踪调试，让你看到 Agent 内部发生了什么。

示例：

agent = create_agent(
    model=model,
    tools=[],
    system_prompt=(
        "你是一名企业知识库助手。"
        "回答时先给结论，再说明依据。"
        "如果资料不足，要明确说明无法确认。"
    ),
)

这里：

• model：决定 Agent 使用哪个模型做推理。
• tools：决定 Agent 能调用哪些外部能力。
• system_prompt：决定 Agent 按什么规则工作。
• create_agent：把模型和运行外壳组装成一个可调用对象。

业务场景：
同样一个强模型，如果没有工具，它查不到订单；如果没有提示词，它可能回答得很散；如果没有状态，它记不住上下文；如果没有追踪，你就很难知道它为什么调用某个工具。

最简记法：
模型负责思考，Harness 负责把任务现场搭起来。

3. LangChain、LangGraph、Deep Agents：三者不要混在一起

它解决的问题：
官方 Overview 特别提醒读者区分 LangChain、LangGraph 和 Deep Agents，因为它们不是同一个抽象层。

可以先这样理解：

名称	中文理解	适合场景
LangChain	Agent 应用框架	想快速创建可定制 Agent
LangGraph	底层编排框架	需要复杂流程、持久执行、状态图
Deep Agents	内置能力更完整的 Agent 套件	想开箱获得规划、文件系统、子 Agent 等能力
LangSmith	调试、追踪、评估平台	想看清 Agent 内部调用过程

示例：

from langchain.agents import create_agent

agent = create_agent(
    model=model,
    tools=[],
    system_prompt="你是一名轻量级任务助手。",
)

这里：

• LangChain：你直接使用 create_agent 创建 Agent。
• LangGraph：LangChain Agent 底层运行在 LangGraph 之上，提供更强的状态和持久执行能力。
• Deep Agents：在 LangChain 之上提供更多开箱能力，例如规划、文件系统和子智能体。
• LangSmith：用于追踪、调试和评估这些 Agent。

业务场景：
如果你只是做一个“查订单并回复用户”的客服助手，用 LangChain Agent 就够了。如果你要做一个长时间运行、可暂停、可恢复、有人审查的复杂流程，就会更靠近 LangGraph。如果你想快速做一个具备规划和文件系统能力的研究助手，可以考虑 Deep Agents。

最简记法：
LangChain 管 Agent 快速搭建，LangGraph 管底层流程编排，Deep Agents 管更完整的开箱能力。

4. Install（安装）：先装核心包，再装供应商集成包

它解决的问题：
安装页告诉我们，LangChain 核心包和模型供应商集成包是分开的。

官方 Python 安装方式很直接：

pip install -U langchain

如果你使用 uv，可以写成：

uv add langchain

官方文档还提醒，LangChain 支持很多模型和工具集成，但这些集成通常在独立的 provider packages（供应商包）里。

比如 OpenAI 兼容调用常用：

pip install -U langchain-openai

如果你使用 uv：

uv add langchain-openai

这里：

• langchain：LangChain 核心包，提供 Agent、模型接口、工具接口等核心能力。
• langchain-openai：OpenAI 供应商集成包，也常用于 OpenAI-compatible API。
• pip install -U：安装或升级 Python 包。
• uv add：用 uv 把依赖加入当前项目。
• Python 3.10+：官方安装页标明 Python 版本需要 3.10 或以上。

业务场景：
企业内部经常会通过统一模型网关接入模型。你可以保留 LangChain 的统一调用方式，只把模型供应商包或 base_url 换成公司网关地址。

最简记法：
核心能力装 langchain，模型接入另装供应商包。

5. API Key（密钥配置）：不要把真实密钥写进代码

它解决的问题：
模型调用需要密钥，但真实项目里不能把密钥直接写进源码。

官方 Quickstart 里会让你设置模型供应商的 API key。结合国内常见的 OpenAI-compatible 接入方式，我们可以这样配置：

export QWEN_API_KEY="你的真实密钥"
export QWEN_BASE_URL="你的 OpenAI-compatible 服务地址"

Windows PowerShell 可以写成：

$env:QWEN_API_KEY="你的真实密钥"
$env:QWEN_BASE_URL="你的 OpenAI-compatible 服务地址"

代码里只读取环境变量：

import os

from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="qwen3.7-max",
    api_key=os.environ["QWEN_API_KEY"],
    base_url=os.environ["QWEN_BASE_URL"],
)

这里：

• QWEN_API_KEY：保存模型服务密钥的环境变量名。
• QWEN_BASE_URL：保存 OpenAI-compatible 服务地址的环境变量名。
• os.environ[...]：从当前系统环境变量读取值。
• api_key：传给模型客户端的访问凭证。
• base_url：模型服务的基础地址。

业务场景：
如果你把真实密钥写进 Git 仓库，一旦仓库同步到远端或发给别人，密钥就可能泄露。环境变量是更安全、更可迁移的做法。

最简记法：
密钥放环境变量，代码只读变量名。

6. create_agent（创建智能体）：最小可运行入口

它解决的问题：
create_agent 把模型、工具和提示词组装成一个可以执行任务的 Agent。

下面是一个改写后的中文版本，使用 qwen3.7-max 和 OpenAI-compatible 配置：

import os

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="qwen3.7-max",
    api_key=os.environ["QWEN_API_KEY"],
    base_url=os.environ["QWEN_BASE_URL"],
)

# 定义天气查询工具，供 Agent 在需要天气信息时调用。
def get_weather(city: str) -> str:
    """根据城市名称查询天气，并返回简短结果。"""
    return f"{city} 今天适合出门，记得根据实际天气预报确认。"

agent = create_agent(
    model=model,
    tools=[get_weather],
    system_prompt="你是一名中文生活助手，回答要简洁、准确。",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "请查询上海今天的天气"}]}
)

print(result["messages"][-1].content_blocks)

这里：

• get_weather：工具函数名。函数名会进入模型可见的工具信息里，所以命名要清楚。
• city：工具参数，表示城市名称。
• tools=[get_weather]：把天气查询函数注册给 Agent。
• agent.invoke(...)：同步调用 Agent，等待它完成任务并返回结果。
• messages：传给 Agent 的消息列表。
• role：消息角色，user 表示用户输入。
• content：消息正文。
• content_blocks：模型返回内容的结构化块，后续可以更稳定地处理文本、工具调用、多模态内容等。

业务场景：
这段代码看起来像天气查询，但模式可以迁移到真实业务里：把 get_weather 换成 query_order_status，就是订单查询；换成 search_policy，就是公司制度问答；换成 get_customer_profile，就是 CRM 助手。

最简记法：
create_agent 是把模型、工具和规则扣在一起的入口。

7. Tool（工具）：让模型从“会说”变成“会做”

它解决的问题：
工具让模型可以请求程序去调用外部系统，而不是凭空编答案。

在官方 Quickstart 的基础示例里，天气函数就是一个工具。真实项目中，工具通常会连接数据库、HTTP API、搜索服务、文件系统或内部业务服务。

示例：

from langchain.tools import tool

# 定义订单查询工具，供 Agent 查询真实订单状态。
@tool
def query_order_status(order_id: str) -> str:
    """根据订单编号查询订单状态。"""
    return f"订单 {order_id} 当前状态：已出库，预计明天送达。"

这里：

• @tool：LangChain 的工具装饰器，用来把普通 Python 函数声明为模型可调用工具。
• query_order_status：工具函数名，表示查询订单状态。
• order_id：订单编号参数。
• 函数文档字符串：工具描述。模型会根据函数名、参数名和描述判断什么时候调用它。

业务场景：
用户问“我的订单到哪了”，模型不应该自己猜物流状态。更可靠的方式是：模型识别出要查订单，生成工具调用请求，程序执行订单查询，再让模型基于真实结果回答。

最简记法：
工具是 Agent 的手，模型是 Agent 的脑。

8. System Prompt（系统提示词）：给 Agent 立工作规则

它解决的问题：
系统提示词告诉 Agent 扮演什么角色、遵守什么边界、按什么风格回答。

官方 Quickstart 里的 system_prompt 很短，适合入门。但真实项目里，提示词要更具体、更可执行。

示例：

SYSTEM_PROMPT = """
你是一名电商售后助手。

## 工作规则
- 回答前先判断用户问题是否和订单、物流、退款或商品质量有关。
- 如果需要订单信息，必须先调用订单查询工具。
- 不要编造不存在的物流状态。
- 遇到退款、补偿、改地址等高影响操作时，要提示需要人工确认。
"""

agent = create_agent(
    model=model,
    tools=[query_order_status],
    system_prompt=SYSTEM_PROMPT,
)

这里：

• SYSTEM_PROMPT：系统提示词变量名，集中保存 Agent 的角色和规则。
• 工作规则：提示词中的结构化小标题，帮助模型理解行为要求。
• 不要编造：约束模型不能在缺少工具结果时乱答。
• 人工确认：把高风险动作交给人工审核，而不是让 Agent 自行执行。

业务场景：
同样一个订单查询工具，用在客服系统里要强调准确和合规；用在运营系统里可能强调效率和摘要；用在管理后台里可能强调审计和权限。系统提示词就是给同一套能力套上不同工作规则。

最简记法：
工具给能力，系统提示词给边界。

9. Invocation（调用）：messages 是 Agent 的输入状态

它解决的问题：
Agent 调用不是传一段普通字符串，而是传一组消息状态。

官方示例使用：

result = agent.invoke(
    {"messages": [{"role": "user", "content": "请查询上海今天的天气"}]}
)

这里最值得注意的是 messages。它不是随便起的字段名，而是 Agent 状态里的关键字段。

示例：

user_input = {
    "messages": [
        {"role": "user", "content": "请查询订单 DD20260622001 的物流状态"}
    ]
}

result = agent.invoke(user_input)
latest_message = result["messages"][-1]
print(latest_message.content_blocks)

这里：

• user_input：本次调用传给 Agent 的状态更新。
• messages：消息列表，承载本轮用户输入和后续 Agent 产生的消息。
• latest_message：结果中的最后一条消息，通常是 Agent 的最终回复。
• content_blocks：标准化内容块，可以比普通字符串保留更多结构。

业务场景：
如果是客服对话，第一轮用户问“我的订单到哪了”，第二轮又问“那能改地址吗”。系统需要把这些消息作为上下文管理，而不是每次只传一句孤立文本。

最简记法：
messages 不是聊天文本，而是 Agent 的输入状态。

10. Real-world Agent（真实场景示例）：从天气 Demo 走向研究助手

它解决的问题：
Quickstart 不只给了天气 Demo，还展示了一个更接近真实场景的研究 Agent：读取文本文件、配置模型、加入记忆，再比较 LangChain Agent 和 Deep Agents。

官方这个例子背后真正想讲的是：一个稍微真实的 Agent，至少会涉及六类能力：

1. 更具体的 system_prompt。
2. 能连接外部数据的工具。
3. 合适的模型参数。
4. 会话记忆。
5. Deep Agents 这类更完整的开箱能力。
6. 测试与验证。

示例：

import urllib.error
import urllib.request

from langchain.tools import tool

# 定义文本读取工具，供 Agent 从指定 URL 读取公开文档内容。
@tool
def fetch_text_from_url(url: str) -> str:
    """根据 URL 读取文本内容，并返回给 Agent 分析。"""
    request = urllib.request.Request(
        url,
        headers={"User-Agent": "Mozilla/5.0 (compatible; langchain-demo/1.0)"},
    )

    try:
        with urllib.request.urlopen(request, timeout=120) as response:
            raw = response.read()
    except urllib.error.URLError as error:
        return f"读取失败：{error}"

    return raw.decode("utf-8", errors="replace")

这里：

• urllib.request：Python 标准库里的 HTTP 请求模块。
• @tool：把 fetch_text_from_url 变成 Agent 工具。
• url：工具参数，表示要读取的文本地址。
• timeout=120：请求超时时间，避免工具一直卡住。
• User-Agent：HTTP 请求头，告诉目标站点请求来源。
• errors="replace"：遇到无法解码的字符时用替代字符处理，避免程序直接报错。

业务场景：
企业里常见的不是“查天气”，而是“读取合同文件并总结风险”“读取产品说明并生成客服话术”“读取知识库文档并回答问题”。这些都需要工具接入外部数据。

最简记法：
天气 Demo 教会你结构，真实 Agent 需要工具、记忆、测试和追踪。

11. Memory（记忆）：让 Agent 不只会单轮回答

它解决的问题：
记忆让 Agent 能在同一段对话里保留上下文，而不是每一轮都像第一次见面。

官方 Quickstart 里使用 InMemorySaver 加入会话记忆：

from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()

agent = create_agent(
    model=model,
    tools=[fetch_text_from_url],
    system_prompt=SYSTEM_PROMPT,
    checkpointer=checkpointer,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "请读取这份公开文本并统计关键词。"}]},
    config={"configurable": {"thread_id": "demo-thread-001"}},
)

这里：

• InMemorySaver：内存检查点保存器，适合学习和本地测试。
• checkpointer：检查点对象，用来保存对话状态。
• config：调用配置。
• configurable：LangGraph/LangChain 放置可配置参数的位置。
• thread_id：会话线程标识。同一个 thread_id 下的多轮调用可以关联到同一段会话。

注意：
InMemorySaver 只适合本地学习和临时测试。生产环境通常要换成数据库或其他持久化存储，否则进程重启后记忆就会丢失。

业务场景：
用户先问“帮我分析这份合同”，后面又问“第二条风险怎么处理”。如果没有同一个 thread_id 和持久化检查点，Agent 很可能不知道“第二条风险”指的是什么。

最简记法：
thread_id 管同一段对话，checkpointer 管状态保存。

12. LangSmith Tracing（追踪调试）：别让 Agent 变成黑盒

它解决的问题：
当 Agent 调模型、调工具、保存状态、生成中间结果时，你需要知道里面到底发生了什么。

官方 Overview 和 Quickstart 都提到 LangSmith。它的作用是追踪请求、调试 Agent 行为、评估输出质量。

基础环境变量可以这样设置：

export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="你的 LangSmith API Key"

Windows PowerShell：

$env:LANGSMITH_TRACING="true"
$env:LANGSMITH_API_KEY="你的 LangSmith API Key"

这里：

• LANGSMITH_TRACING：是否开启 LangSmith 追踪。
• LANGSMITH_API_KEY：LangSmith 平台的访问密钥。
• trace：一次 Agent 执行的调用轨迹。
• tool calls：工具调用记录。
• state transitions：状态变化记录。
• latency：延迟，用来观察哪里慢。

业务场景：
一个售后 Agent 回答错了，原因可能有很多：模型没理解问题、工具参数错了、工具返回数据不完整、提示词边界不清、上下文太长。没有追踪，只能猜；有了追踪，就能看到每一步。

最简记法：
能跑只是开始，看得见才方便改。

13. 第一篇应该怎么记：先跑起来，再谈复杂能力

回到这三页官方文档，最值得记住的并不是某一条安装命令，也不是某一个示例函数，而是 LangChain 给出的基本抽象方式：

它把大模型应用拆成了三个层次：

层次	关注点	代表对象
模型层	谁负责理解、生成和决策	model
行动层	模型如何连接外部能力	tools
运行层	如何组织提示词、状态、记忆和追踪	create_agent、messages、checkpointer

从这个角度看，create_agent 的意义并不只是“创建一个聊天机器人”，而是把模型调用提升为一个可组合的运行结构。

这也是 LangChain 入门阶段最重要的心智转换：

不要把 LangChain 理解成一个更方便的模型 SDK，而要把它理解成一个面向 Agent 应用的工程抽象层。

理解了这一点，后续再阅读 Models、Messages、Tools、Memory、Middleware 等文档时，就不会把它们看成彼此孤立的 API，而会看到它们都在服务同一个目标：让模型从一次性回答，走向可运行、可控制、可维护的智能体系统。