LangChain、LangGraph学习笔记 - 初识庐山真面目

LangChain介绍

LangChain 是一个用来开发大模型应用的开源框架。简单说，它可以帮助我们把大语言模型，比如 DeepSeek、OpenAI、Claude 等，和自己的程序、数据库、文档、搜索工具、API 等连接起来，快速做出 AI 应用。LangChain 官方把它定位为用于构建 Agent 和 LLM 应用的框架，并提供模型、工具、检索等集成能力。

LangChain里有几个核心概念：

• Model（模型）：需要调用的大模型，例如deepseek-v4、gpt-4、claude等。
• Prompt（提示词）: 高速模型需要做什么指令，Prompt写的越好，模型能力越强。
• Chain（链） ： 可以理解为步骤组合，例如：先整理问题，再查询资料，最后让模型生成答案。
• Tool（工具）: 工具是模型调用的外部力量，例如搜索网页、查询数据、调用接口、运行代码等。
• Agent（智能体）：Agent更像一个会自己判断步骤的AI助手，它可以根据用户任务，决定要不要调用工具，调用哪个工具，下一步做什么。
• Retriever（检索器）：Retriever用来从文档、向量数据库或其他数据源中找出问和问题相关的内容。

LangChain的主要模块

• langchain-core：轻量核心，包含核心抽象接口（Runnable、BaseMessage等）
• langchain-community：供应商分离 第三方继承，例如langchain-openai、langchain-deepseek等
• langchain-classic ：向后兼容，冗余代码或者不推荐使用的api会移动到这里。
• langgraph ： Agent系统基础，深度整合LangGraph1.0，协调多个Chain、Agent、Tools完成更复杂的任务，并且还支持循环调用，是langchain图形化的增强版

中文文档：LangChain 文档 - LangChain 教程

API文档：LangChain - Python API Reference | LangChain Reference

LangChain的生态

LangChain的生态由四大核心支柱构成：LangChain、LangGraph、Deep Agent、LangSmith。

环境配置与项目

• uv
• rustc
• Python 3.13
• postgresql

创建项目

# 3.15实测不行。。。
uv python install 3.13
uv python pin 3.13
# 创建项目路径
cd D:\PycharmProjects\ 
mkdir langchain-agent
cd .\langchain-agent\

# 初始化项目
uv init  

# 添加依赖
uv add "langchain>=1.3.0" "langchain-core>=0.3.0"
# 确保本地rust是最新的，差了两个小版本居然安装出错了 （rustc 1.94 -> rustc 1.96）
uv add "langchain-deepseek" "langchain-openai"
uv add "langgraph>=1.2.0"
uv add "langchain-postgres>=0.0.17"
uv add "langchain-community"
uv add "httpx" "python-dotenv"

uv add --dev "pytest" "pytest-asyncio"

依赖说明：

• langchain-deepseek 、langchain-openai：目前以DeepSeek和OpenAI为例，有其他的可自行添加，例如：langchain-anthropic、langchain-ollama。
• langgraph是底层运行时，agent构建在它的上面。
• langchain-postgres提供pgvector向量存储。

设置环境变量

# 确保在项目根目录下
cd D:\PycharmProjects\langchain-agent
# 创建.env文件
nvim .env
# 填写如下信息
DEEPSEEK_API_KEY="你的 DEEPSEEK API Key"
OPENAI_API_KEY="你的 OPENAI API Key"

测试一下

将项目中的main.py，修改为如下：

from langchain.chat_models import init_chat_model
from dotenv import load_dotenv

load_dotenv()
llm = init_chat_model("deepseek:deepseek-v4-pro")
result = llm.invoke("你好，请介绍一下你自己")
print(result)

运行后，会打印如下：

content='你好呀！很高兴认识你！😊\n\n我是**DeepSeek**，由深度求索公司创造的AI助手。让我简单介绍一下自己的特点：\n\n## 🌟 ......’

如果只使用DeepSeek，可以改成以下代码：

from langchain_deepseek import ChatDeepSeek
from dotenv import load_dotenv


load_dotenv()
llm = ChatDeepSeek(model="deepseek-v4-pro")
res = llm.invoke("你好，请介绍一下你自己")
print(res.content)

比较推荐使用init_chat_model()，它是LangChain 1.x中推出的用于初始化聊天模型的统一接口。只要是LangChain支持的模型都可以处理，它会根据模型名称自动旋转对应的模型类初始化实例；如果是使用非支持的第三方模型：火山、讯飞等，可以使用ChatOpenAI()。

AI Agent

什么是 AI Agent

Agent是一个能自主感知环境、做出决策、执行行动的智能体程序。其流程是：

输入 -> 思考（大模型推理） -> 行动（调用工具/生成回复） -> 观察结果 -> 循环，直到完成

Agent的核心组件

组件	职责	LangChain
大脑（LLM）	推理、决策、生成	BaseChatModel
工具（Tools）	交互	@tool，BaseTool，Pydantic Schema
记忆（Memory）	保存对话上下文	checkpointer，BaseStore
规划（Planning）	分解任务、决定步骤	Agent loop + middleware
执行（Exectuion）	调用工具、处理结果	LangGraph graph runtime

RAG

Retrieval-Augmented Generation，检索增强生成。用来解决大模型的知识冻结（语料的时效性）和大模型幻觉（大模型不会的时候，它会胡扯乱编答案）

大约就是如下的方式：

第一个Agent

充分利用LLM的推理决策能力，通过增加规划、记忆和工具调用的能力，构造一个能够独立思考、逐步完成给定目标的Agent。

LLM Powered Autonomous Agents | Lil’Log

import json
from datetime import datetime
from dotenv import load_dotenv
from langchain.chat_models import init_chat_model

# 引入 LangChain 相关组件
from langchain_core.tools import tool
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.agents import create_agent
load_dotenv()


"""
模拟数据库
"""
ORDERS = {
    "O1001": {
        "order_id": "O1001",
        "user_id": "U001",
        "product": "无线鼠标",
        "amount": 199,
        "status": "delivered",
        "delivered_at": "2026-07-01",
        "payment_status": "paid"
    },
    "O1002": {
        "order_id": "O1002",
        "user_id": "U001",
        "product": "机械键盘",
        "amount": 599,
        "status": "delivered",
        "delivered_at": "2026-06-10",
        "payment_status": "paid"
    }
}

REFUND_REQUESTS = {}
SUPPORT_TICKETS = {}

"""
编写工具类
"""

@tool
def get_order(order_id: str) -> dict:
    """根据订单号查询订单信息。参数 order_id 格式如 O1001。"""
    order = ORDERS.get(order_id)
    if not order:
        return {"found": False, "message": "没有找到该订单"}
    return {"found": True, "order": order}

@tool
def check_refund_policy(order_id: str, reason: str) -> dict:
    """判断订单是否符合退款条件。"""
    order = ORDERS.get(order_id)
    if not order:
        return {"eligible": False, "reason": "订单不存在"}
    if order["payment_status"] != "paid":
        return {"eligible": False, "reason": "订单未支付，不能退款"}
    if order["status"] != "delivered":
        return {"eligible": False, "reason": "订单尚未签收，不能按售后退款处理"}

    delivered_at = datetime.strptime(order['delivered_at'], "%Y-%m-%d")
    today = datetime.strptime("2026-07-02", "%Y-%m-%d")
    days_since_delivered = (today - delivered_at).days

    if days_since_delivered < 7:
        return {
            "eligible": True,
            "days_since_delivered": days_since_delivered,
            "policy": "签收后7天内，质量问题可申请退款"
        }

    return {
        "eligible": False,
        "days_since_delivered": days_since_delivered,
        "reason": "已经超过7天，需要转人工客服审核"
    }

@tool
def create_refund_request(order_id: str, reason: str) -> dict:
    """创建退款申请。注意：该工具不会真正退款，只会创建待确认的退款申请。"""
    order = ORDERS.get(order_id)
    if not order:
        return {"found": False, "message": "订单不存在，无法创建退款申请"}

    refund_id = f"REF-{order_id.replace('O', '')}"
    REFUND_REQUESTS[refund_id] = {
        "refund_id": refund_id,
        "order_id": order_id,
        "reason": reason,
        "amount": order["amount"],
        "status": "pending_user_confirmation"
    }
    return {
        "created": True,
        "refund_request": REFUND_REQUESTS[refund_id],
        "next_step": "等待用户或人工客服确认后，才能执行真实退款"
    }

@tool
def create_support_ticket(order_id: str, issue: str) -> dict:
    """创建人工客服工单，用于处理超出自动化规则的问题。"""
    ticket_id = f"TICKET-{order_id.replace('O', '')}"
    SUPPORT_TICKETS[ticket_id] = {
        "order_id": order_id,
        "issue": issue,
        "status": "waiting_for_human_agent",
        "ticket_id": ticket_id,
    }
    return {"created": True, "ticket": SUPPORT_TICKETS[ticket_id]}


# 整合工具列表
tools = [get_order, check_refund_policy, create_refund_request, create_support_ticket]

"""
初始化 LangChain 核心组件
"""

SYSTEM_PROMPT = """
你是一个电商售后客服 Agent。

你的任务：
1. 理解用户诉求；
2. 如果用户提到订单号，先调用 get_order 查询订单；
3. 如果用户要退款，必须调用 check_refund_policy 判断退款资格；
4. 如果符合退款条件，只能调用 create_refund_request 创建退款申请；
5. 不能声称已经完成真实退款；
6. 如果不符合自动退款规则，调用 create_support_ticket 创建人工客服工单；
7. 涉及退款、资金、取消订单等高风险动作时，必须明确告诉用户需要确认或人工审核；
8. 回复要简洁、清楚、礼貌。
"""

# 配置大模型（适配 DeepSeek）
llm = init_chat_model(
    model="deepseek:deepseek-v4-pro",
    # api_key=os.environ.get("DEEPSEEK_API_KEY"),
    # base_url="https://api.deepseek.com",
    temperature=0.0  # 客服场景建议将温度设为 0，保证严谨度
)

# 组装 Prompt 模板
prompt = ChatPromptTemplate.from_messages([
    ("system", SYSTEM_PROMPT),
    MessagesPlaceholder(variable_name="chat_history"), # 预留给未来可能需要的上下文对话
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad"), # LangChain 存放中间思考和工具结果的占位符
])

# 创建 Agent 链
agent_executor = create_agent(
    model=llm,
    tools=tools,
    system_prompt=SYSTEM_PROMPT,
    # max_iterations=5  # 如果需要限制步数可以加上
)

"""
业务统一调用接口
"""
def run_agent(user_message: str) -> str:
    try:
        response = agent_executor.invoke({
            "messages": [("human", user_message)]
        })
        # 新版返回的对象中，最后的回复在 messages 列表的最后一条
        return response["messages"][-1].content
    except Exception as e:
        return "抱歉，这个问题处理步骤较多，我已经停止自动处理，请转人工客服继续处理。"


if __name__ == '__main__':
    user_message = "我的订单O1001,昨天收到的无线鼠标坏了，我想退款"

    reply = run_agent(user_message)

    print("\n ===== Agent回复 ====\n")
    print(reply)

    print("\n == 当前退款申请表 === \n")
    print(json.dumps(REFUND_REQUESTS, ensure_ascii=False, indent=2))

    print("\n ==== 当前人工工单表 === \n")
    print(json.dumps(SUPPORT_TICKETS, ensure_ascii=False, indent=2))

运行程序后，执行结果如下：

 ===== Agent回复 ====

退款申请已为您创建，以下是详情：

| 项目 | 内容 |
|------|------|
| **退款编号** | REF-1001 |
| **订单号** | O1001 |
| **退款金额** | ¥199.00 |
| **原因** | 收到的无线鼠标坏了 |
| **状态** | ⚠️ 待确认 |

需要提醒您：**当前退款申请尚未生效**，还需要您确认或人工客服审核后才能真正执行退款。请您留意后续通知，或前往「我的订单」中确认该退款申请。

请问还有其他需要帮您处理的吗？

 == 当前退款申请表 === 

{
  "REF-1001": {
    "refund_id": "REF-1001",
    "order_id": "O1001",
    "reason": "收到的无线鼠标坏了",
    "amount": 199,
    "status": "pending_user_confirmation"
  }
}

 ==== 当前人工工单表 === 

{}

这样，一个简单的AI Agent就完成了。