LangChain on Morgoth

LangGraph

Wed, 22 Jul 2026 10:00:00 +0800

LangGraph 是一个用于构建有状态 Agent 的底层编排框架。它把 Agent 的执行过程描述成一张图：状态在节点之间流动，边决定下一步执行哪个节点，直到任务完成。

普通的聊天程序通常只有一次模型调用，而 Agent 会不断重复“思考、调用工具、读取结果、继续思考”的循环。随着流程变长，我们还会遇到分支、重试、持久化、人工审批和故障恢复等问题。LangGraph 的价值就是让这些控制逻辑变得显式、可追踪和可恢复。

LangGraph 与 LangChain

LangChain 和 LangGraph 解决的问题并不完全相同：

LangChain 提供模型、Prompt、Tool、Retriever 和预构建 Agent 等高层抽象；
LangGraph 提供状态图、持久化、流式执行和 Human-in-the-loop 等编排能力；
LangSmith 用于追踪、评估和观察 Agent 的执行过程。

如果只是开发标准的 ReAct Agent，LangChain 的 create_agent 通常更简单。如果需要自定义执行路径、审批节点、并行任务或长时间运行的工作流，再直接使用 LangGraph。

核心概念

一张 LangGraph 主要由三个部分组成。

State

State 是整个工作流共享的数据。它可以保存消息、用户信息、中间结果、重试次数或审批状态。

节点不应该随意修改 State，而是返回需要更新的部分。LangGraph 会根据 State Schema 和 Reducer 合并更新。

Node

Node 是执行实际工作的函数，例如：

调用 LLM；
执行 Tool；
查询数据库；
检查权限；
等待人工审批。

节点读取当前 State，并返回一个局部 State 更新。

Edge

Edge 决定节点之间的执行顺序：

普通 Edge 固定跳转到下一个节点；
Conditional Edge 根据 State 动态选择路径；
START 和 END 分别表示图的入口和结束。

一个 Tool-calling Agent 的图通常如下：

START
 │
 ▼
Agent Node ─── 无工具调用 ───▶ END
 │
 │ 有工具调用
 ▼
Tool Node
 │
 └──────────────────────────▶ Agent Node

模型可以连续调用多个工具。只有当模型返回最终答案、不再产生 Tool Call 时，图才会进入 END。

开发一个 Agent

下面开发一个简单的天气 Agent。模型负责理解用户意图，Tool 负责返回天气信息，LangGraph 负责控制模型和 Tool 之间的循环。

安装依赖

python -m venv .venv
source .venv/bin/activate
pip install -U langgraph langchain langchain-openai

通过环境变量提供模型凭据：

export OPENAI_API_KEY="..."

不要把 API Key 写入代码或提交到版本控制。

定义 Tool

Tool 是 Agent 与外部世界交互的接口。真实项目中的 Tool 可以调用 API、数据库或内部服务；这里使用静态数据，使示例可以专注于 Agent 的执行逻辑。

from langchain.tools import tool


@tool
def get_weather(city: str) -> str:
 """查询城市当前的天气。"""
 weather = {
 "北京": "晴，26°C",
 "上海": "多云，29°C",
 "深圳": "阵雨，31°C",
 }
 return weather.get(city, f"暂时没有 {city} 的天气数据")

函数的类型标注和 Docstring 会成为 Tool Schema 的一部分。描述应该清晰说明工具能做什么，但不要让模型看到内部凭据或不需要的参数。

定义模型节点

将 Tool 绑定到模型后，模型可以选择返回普通消息，也可以返回结构化 Tool Call。

from langchain.chat_models import init_chat_model
from langgraph.graph import MessagesState


tools = [get_weather]
model = init_chat_model("openai:gpt-4.1-mini").bind_tools(tools)


def call_model(state: MessagesState):
 system_message = {
 "role": "system",
 "content": "你是一个天气助手。需要实时数据时调用工具，不要编造天气。",
 }
 response = model.invoke([system_message, *state["messages"]])
 return {"messages": [response]}

MessagesState 已经定义了消息列表及对应的 Reducer。节点只返回新消息，Reducer 会把它追加到历史记录，而不是覆盖整个列表。

构建执行图

ToolNode 负责执行模型产生的 Tool Call，tools_condition 则根据模型输出决定进入 Tool Node 还是结束工作流。

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import START, StateGraph
from langgraph.prebuilt import ToolNode, tools_condition


builder = StateGraph(MessagesState)
builder.add_node("agent", call_model)
builder.add_node("tools", ToolNode(tools))

builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")

checkpointer = InMemorySaver()
graph = builder.compile(checkpointer=checkpointer)

StateGraph 只是构建器，调用 compile() 后才会得到可以执行的 Graph。这里加入了内存 Checkpointer，用于在同一个 Thread 中保存每一步的 State。

运行 Agent

config = {"configurable": {"thread_id": "demo-thread"}}

inputs = {
 "messages": [
 {"role": "user", "content": "上海和深圳哪个城市更热？"}
 ]
}

for state in graph.stream(inputs, config, stream_mode="values"):
 state["messages"][-1].pretty_print()

执行过程如下：

用户消息进入 agent 节点；
模型生成两个天气 Tool Call；
tools_condition 把执行路径路由到 tools；
ToolNode 执行工具并把结果写入消息列表；
图重新进入 agent；
模型比较工具结果并生成最终回答；
没有新的 Tool Call，图进入 END。

多轮对话与持久化

Checkpointer 会按照 thread_id 保存 Graph State。下一次调用使用相同的 Thread ID，Agent 就能继续之前的对话：

follow_up = {
 "messages": [
 {"role": "user", "content": "那北京呢？"}
 ]
}

result = graph.invoke(follow_up, config)
print(result["messages"][-1].content)

InMemorySaver 适合本地开发和测试，进程退出后数据就会消失。生产环境应该使用持久化 Checkpointer，例如 PostgreSQL，或者使用自动管理持久化的 Agent Server。

Checkpoint 不只是聊天记忆，它还支持：

从失败前的成功步骤继续执行；
查看每个节点执行后的 State；
回到历史 Checkpoint 进行调试；
暂停工作流并等待人工输入。

Human-in-the-loop

当 Agent 准备执行发送消息、修改数据或产生费用等高风险操作时，可以使用 interrupt() 暂停 Graph：

from langgraph.types import Command, interrupt


def review_action(state):
 decision = interrupt(
 {
 "question": "是否允许执行该操作？",
 "action": state["pending_action"],
 }
 )
 return {"decision": decision}

Graph 会保存当前 State，并把审批请求返回给调用方。审批完成后，使用相同的 thread_id 恢复执行：

graph.invoke(Command(resume="approve"), config)

恢复时，包含 interrupt() 的节点会从头重新执行。因此，应把不可重复的副作用放在审批之后，并保证可能重试的节点具有幂等性。

生产实践

State 保持精简

State 应保存控制流程需要的数据，而不是无限增长的原始内容。长对话需要裁剪、摘要或外部存储，否则模型上下文和 Checkpoint 都会不断膨胀。

Tool 保持单一职责

每个 Tool 应完成一个清晰动作，并使用严格的参数类型。读操作和写操作最好分开，写操作可以单独接入审批节点。

处理错误与重试

外部 API 可能超时或限流。根据异常类型配置重试策略，不要让模型在未知错误上无限循环。工具错误应该返回足够的信息供模型调整，但不能泄露凭据和内部实现。

控制循环

Agent 可能因为错误的 Tool Call 不断循环。生产环境需要限制执行步数、调用次数和总超时时间，并为无法完成的任务提供明确的退出路径。

持久化前考虑幂等性

恢复和重试可能再次执行节点。支付、发送消息或写数据库等操作应使用幂等键，避免产生重复副作用。

增加可观测性

Agent 的问题通常不是单个函数报错，而是选择了错误路径或错误工具。应记录节点输入输出、Tool Call、延迟、Token 使用量和最终执行路径，并使用 LangSmith 等工具进行追踪和评估。

什么时候使用 LangGraph

适合直接使用 LangGraph 的场景包括：

Agent 有明确的多步骤流程和条件分支；
需要暂停、恢复或长时间运行；
需要保存状态或跨会话记忆；
高风险 Tool 必须经过人工审批；
需要多个 Agent 或子图协作；
需要精确控制失败重试和执行路径。

如果需求只是“模型调用几个工具并回答问题”，优先从高层 Agent API 开始。只有当默认循环无法表达业务流程时，再下沉到 LangGraph。这样既能保留开发效率，也不会过早引入复杂度。

参考资料

LangChain

Sat, 19 Jul 2025 11:17:34 +0800

LangChain 是一个用于开发 LLM 应用和 AI Agent 的开源框架。它统一了不同模型提供商的调用方式，并提供 Messages、Tools、Agents、Middleware、Retrieval 和 Structured Output 等组件。

LangChain 的重点不是封装一次模型请求，而是把模型与外部数据、工具和应用控制逻辑组合起来。开发者可以先使用高层 API 快速构建 Agent，再在需要精确控制执行路径时下沉到 LangGraph。

LangChain 生态

LangChain 生态中的几个项目各有职责：

项目	主要职责
LangChain	模型、Tool、Agent、Middleware 和 Retrieval 等开发框架
LangGraph	有状态、可恢复的底层 Agent 编排运行时
LangSmith	Trace、评估、测试和生产可观测性
Deep Agents	在 LangGraph 之上提供规划、子 Agent、文件系统和上下文管理能力

create_agent 创建的 Agent 底层运行在 LangGraph 上，因此也支持 State、Checkpoint、Streaming 和 Human-in-the-loop。大多数项目可以从 LangChain 开始，不需要一开始就手写 Graph。

核心组件

Models

LangChain 使用统一接口连接不同模型提供商。应用可以使用 invoke()、stream()、batch() 和对应的异步方法调用模型，而不需要让业务逻辑依赖某一个 SDK。

from langchain.chat_models import init_chat_model


model = init_chat_model("openai:gpt-5.4")

response = model.invoke(
 [
 {"role": "system", "content": "你是一名简洁的技术助手。"},
 {"role": "user", "content": "用一句话解释 Tool Calling。"},
 ]
)

print(response.content)

模型集成通常放在独立的 Provider Package 中。更换模型时除了修改模型名称，还需要安装相应集成包并配置该提供商的凭据。

Messages

Messages 是模型交互的标准数据结构。常见角色包括：

System Message：定义模型角色和约束；
Human Message：用户输入；
AI Message：模型输出，可能包含 Tool Call；
Tool Message：工具执行结果。

使用 Messages 而不是拼接字符串，可以保留角色、Tool Call、Token Usage 和其他元数据。

Tools

Tool 让模型可以读取实时数据或执行外部操作。普通 Python 函数可以通过 @tool 转换为 Tool：

from langchain.tools import tool


@tool
def get_weather(city: str) -> str:
 """查询指定城市当前的天气。"""
 weather = {
 "北京": "晴，26°C",
 "上海": "多云，29°C",
 "深圳": "阵雨，31°C",
 }
 return weather.get(city, f"暂时没有 {city} 的天气数据")

函数名、类型标注和 Docstring 会共同构成 Tool Schema。描述越准确，模型越容易在正确的时机选择正确的工具。

Tool 应保持单一职责。查询和修改操作最好拆开，敏感参数应由运行时注入，不要暴露给模型。

开发一个 Agent

安装依赖

下面以 OpenAI Provider 为例：

python -m venv .venv
source .venv/bin/activate
pip install -U "langchain[openai]"

通过环境变量配置凭据，不要把 API Key 写进源代码：

export OPENAI_API_KEY="..."

创建 Tool-calling Agent

from langchain.agents import create_agent
from langchain.tools import tool


@tool
def get_weather(city: str) -> str:
 """查询指定城市当前的天气。"""
 weather = {
 "北京": "晴，26°C",
 "上海": "多云，29°C",
 "深圳": "阵雨，31°C",
 }
 return weather.get(city, f"暂时没有 {city} 的天气数据")


agent = create_agent(
 model="openai:gpt-5.4",
 tools=[get_weather],
 system_prompt="你是天气助手。需要天气数据时调用工具，不要编造结果。",
)

result = agent.invoke(
 {
 "messages": [
 {"role": "user", "content": "上海和深圳哪个城市更热？"}
 ]
 }
)

result["messages"][-1].pretty_print()

Agent 的执行循环是：

用户输入 → 模型判断 → 调用 Tool → 读取结果 → 模型继续判断 → 最终回答

如果模型一次生成多个 Tool Call，Agent 可以执行这些工具后再把结果交回模型。当模型不再请求工具时，循环结束。

Structured Output

如果下游代码需要稳定的数据结构，不应该依赖自然语言解析。可以通过 Pydantic Schema 要求 Agent 返回结构化结果：

from pydantic import BaseModel, Field
from langchain.agents import create_agent


class WeatherResult(BaseModel):
 city: str = Field(description="城市名称")
 condition: str = Field(description="天气情况")
 temperature_celsius: float = Field(description="摄氏温度")


structured_agent = create_agent(
 model="openai:gpt-5.4",
 tools=[get_weather],
 response_format=WeatherResult,
)

result = structured_agent.invoke(
 {"messages": [{"role": "user", "content": "上海天气如何？"}]}
)

weather = result["structured_response"]
print(weather.temperature_celsius)

对于支持原生 Structured Output 的模型，LangChain 会优先使用 Provider 能力；否则可以使用 Tool Calling 生成符合 Schema 的结果。

Memory

Agent 的短期记忆保存在 State 中。加入 Checkpointer 后，可以使用 thread_id 隔离和恢复不同会话：

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver


checkpointer = InMemorySaver()

agent = create_agent(
 model="openai:gpt-5.4",
 tools=[get_weather],
 checkpointer=checkpointer,
)

config = {"configurable": {"thread_id": "demo-thread"}}

agent.invoke(
 {"messages": [{"role": "user", "content": "我准备去上海。"}]},
 config,
)

result = agent.invoke(
 {"messages": [{"role": "user", "content": "那里的天气如何？"}]},
 config,
)

同一个 thread_id 会继续之前的消息历史，不同 Thread 之间相互隔离。

InMemorySaver 只适合开发和测试。生产环境应使用持久化 Checkpointer，并对长对话进行裁剪或摘要，避免上下文无限增长。

Middleware

Middleware 可以在 Agent 循环的关键位置插入控制逻辑，而不需要修改 Agent 本身。常见用途包括：

自动摘要过长的对话；
限制模型或 Tool 调用次数；
重试和模型降级；
PII 检测与脱敏；
动态选择模型和 Tool；
记录日志、延迟和 Token 使用量；
在敏感操作前请求人工审批。

Human-in-the-loop

下面的 Agent 会在执行订单操作前暂停，等待人工批准、修改或拒绝：

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langchain.tools import tool
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command


@tool
def submit_order(item: str, quantity: int) -> str:
 """提交商品订单。"""
 return f"已提交 {quantity} 件 {item}"


agent = create_agent(
 model="openai:gpt-5.4",
 tools=[submit_order],
 middleware=[
 HumanInTheLoopMiddleware(
 interrupt_on={"submit_order": True},
 )
 ],
 checkpointer=InMemorySaver(),
)

config = {"configurable": {"thread_id": "approval-thread"}}

agent.invoke(
 {"messages": [{"role": "user", "content": "订购两件显示器"}]},
 config,
)

agent.invoke(
 Command(resume={"decisions": [{"type": "approve"}]}),
 config,
)

生产环境中的写操作必须具备幂等性，并使用持久化 Checkpointer，确保审批等待期间进程重启也不会丢失 State。

Retrieval 与 RAG

LLM 的上下文长度有限，训练数据也不是实时知识。Retrieval 会在请求时获取相关外部内容，再让模型基于这些内容回答，这就是 RAG 的基础。

LangChain 将 Retrieval 拆成可替换的组件：

Document Loader
 ↓
Text Splitter
 ↓
Embedding Model
 ↓
Vector Store
 ↓
Retriever
 ↓
Prompt + Model

不同场景可以选择不同的 RAG 架构：

架构	特点	适用场景
2-step RAG	每次先检索再生成，流程固定、延迟可预测	FAQ、文档问答
Agentic RAG	Agent 自己决定何时检索以及使用哪个数据源	研究助手、多数据源查询
Hybrid RAG	加入查询改写、检索验证和答案检查	对质量和可控性要求较高的系统

如果已经有搜索服务、SQL 数据库或知识库，不需要为了使用 LangChain 重新建立向量数据库。可以把现有系统包装成 Retriever 或 Tool。

LangChain 与 LangGraph 的选择

优先使用 LangChain 的场景：

调用不同 Provider 的模型；
开发标准 Tool-calling Agent；
使用 Middleware、Structured Output 或 RAG；
希望快速组合现有集成。

直接使用 LangGraph 的场景：

工作流包含复杂条件分支或并行节点；
需要精确控制 State 和执行路径；
需要暂停、恢复、长时间运行或故障恢复；
需要多个 Agent 或子图协作。

两者不是互斥关系。可以先用 create_agent 构建一个 Agent，再把它作为 Node 或 Subgraph 放入更大的 LangGraph 工作流中。

生产实践

明确 Tool 边界

Tool 的输入必须严格校验。读操作和写操作分离，高风险 Tool 需要权限检查和人工审批。不要让模型直接拼接 SQL、Shell 或其他可执行内容后无条件运行。

使用 Structured Output

模型输出需要进入数据库、API 或后续工作流时，应使用 Schema 校验，而不是依赖正则表达式解析自然语言。

限制 Agent 循环

限制模型调用次数、Tool 调用次数、总超时和 Token 预算。Agent 无法完成任务时应该明确退出，而不是无限重试。

管理上下文

只向模型提供当前任务需要的信息。长对话应裁剪或摘要，大型文档应通过 Retrieval 按需加载。

增加 Trace 与评估

记录 Prompt、模型输出、Tool Call、延迟、错误和执行路径。除了单元测试，还应建立包含正常请求、边界条件和恶意输入的数据集，对 Agent 进行回归评估。

保持 Provider 可替换

把模型初始化、参数和凭据放在配置层。切换 Provider 时仍需要重新评估 Tool Calling、Structured Output、上下文长度、延迟和成本，不能只修改模型名称就认为行为完全一致。