LangChain + LangGraph 环境搭建与快速入门：从零构建你的第一个 AI Agent

图片来源网络，侵权联系删。

文章目录

• 引言：为什么这个问题值得关心？
• 背景与挑战
• 核心机制解析
• • 1. 环境安装要点（Python ≥ 3.9）
  • 2. 最小验证示例（Hello World）
• 实战演示：构建一个带循环的简单 Agent
• 最佳实践与避坑指南
• 总结

引言：为什么这个问题值得关心？

你是否曾想过，如何让大模型（LLM）不只是“回答问题”，而是能像人一样分步骤思考、调用工具、循环修正？2024 年起，LangChain 生态中的 LangGraph 正在成为构建复杂 AI Agent 的标准范式。它基于状态机（State Machine）模型，让开发者能清晰定义“推理-行动-反思”的闭环流程。然而，许多工程师卡在第一步：环境配置混乱、示例跑不通、日志看不懂。本文将带你用最简路径完成 LangChain + LangGraph 的本地部署，并运行你的第一个可调试的智能体程序。

背景与挑战

LangChain 早期版本以链式调用（Chains）为主，适合线性任务。但真实场景中，AI 需要循环决策（如：查天气 → 发现下雨 → 建议带伞 → 用户追问品牌 → 调用电商 API）。传统 Chains 无法表达这种图结构逻辑。

LangGraph（由 LangChain 官方于 2024 年初推出）正是为解决此问题而生——它将工作流建模为有向图，每个节点是函数，边代表状态转移。但新手常遇到三大障碍：

💡 专家点评：LangGraph 的核心价值不是“更强大”，而是“更可控”。它把 LLM 的黑盒行为转化为可审计、可中断、可重试的状态机，这对金融、医疗等高风险场景至关重要。

核心机制解析

1. 环境安装要点（Python ≥ 3.9）

# 创建干净虚拟环境（强烈推荐）
python -m venv langchain-env
source langchain-env/bin/activate # Linux/Mac
# langchain-env\\Scripts\\activate # Windows

# 安装核心库（截至 2025 年 11 月，LangChain v0.2.13 + LangGraph v0.1.8）
pip install langchain-core langchain-community langgraph

# 若需使用 OpenAI 模型（示例所需）
pip install openai

⚠️ 注意：避免同时安装 langchain 全家桶（含 deprecated 模块），应按需引入子包以减少依赖冲突。

2. 最小验证示例（Hello World）

from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, END

# 定义状态结构（使用 TypedDict 更安全）
from typing import TypedDict

class State(TypedDict):
message: str

# 定义节点函数
def greet(state: State) –> dict:
return {"message": f"Hello, {state['message']}!"}

# 构建图
builder = StateGraph(State)
builder.add_node("greet", greet)
builder.set_entry_point("greet")
builder.add_edge("greet", END)

# 编译并运行
graph = builder.compile()
result = graph.invoke({"message": "Alice"})
print(result) # 输出: {'message': 'Hello, Alice!'}

💡 关键原理：StateGraph 是一个声明式构建器，compile() 后生成可执行的 CompiledGraph。每次 .invoke() 都会完整走完图流程，状态在节点间传递。

实战演示：构建一个带循环的简单 Agent

我们扩展上例，实现“用户输入名字 → 模型问候 → 若名字含数字则重试”：

from langgraph.graph import StateGraph, END
from typing import TypedDict, Annotated
import re

class State(TypedDict):
name: str
attempts: int

def validate_name(state: State):
if re.search(r'\\d', state["name"]):
return {"name": "INVALID", "attempts": state["attempts"] + 1}
return {"name": state["name"], "attempts": state["attempts"]}

def respond(state: State):
if state["name"] == "INVALID":
return {"name": "Please enter a valid name (no digits):"}
return {"name": f"Hi {state['name']}!", "attempts": state["attempts"]}

def should_retry(state: State) –> str:
return "respond" if state["name"] != "INVALID" or state["attempts"] >= 3 else "respond"

# 构建图
builder = StateGraph(State)
builder.add_node("validate", validate_name)
builder.add_node("respond", respond)
builder.set_entry_point("validate")
builder.add_conditional_edges(
"validate",
lambda s: "retry" if s["name"] == "INVALID" and s["attempts"] < 3 else "done",
{"retry": "respond", "done": END}
)
builder.add_edge("respond", "validate") # 形成循环

graph = builder.compile()

# 测试
result = graph.invoke({"name": "Alice123", "attempts": 0})
print(result)

日志输出将显示多次状态流转，直到达到最大尝试次数或成功。

最佳实践与避坑指南

⚠️ 常见坑：

• 忘记 set_entry_point() 导致图无起点
• 条件边返回值必须严格匹配目标节点名
• 状态更新必须返回完整新状态字典，而非增量

总结

LangGraph 正快速演进：2025 年 Q3 将支持异步节点与外部事件触发，使 Agent 能响应实时数据流。国内阿里通义实验室已在其 Qwen-Agent 框架中集成类似图引擎，用于电商客服场景。

下一步建议：

• 尝试集成 Tool Calling（如 TavilySearchAPIWrapper）
• 探索 Checkpointing 机制实现对话持久化
• 关注 LangGraph 官方文档 获取最新模式

技术的本质不是炫技，而是可控的智能。从今天这个“Hello World”开始，你已站在构建下一代 AI 应用的起跑线上。