基于 LangGraph 构建极简对话式 AI 智能体

基于LangGraph构建极简对话式AI智能体：Clean Graph工程搭建指南

视频地址：LangGraph 最简工程搭建_哔哩哔哩_bilibili
项目地址：GitHub - slow-coding/clean_graph: A LangGraph v1.0 Minimal Quick Starter for Agents

引言

LangGraph作为基于图结构的AI应用框架，为构建复杂智能体提供了灵活的节点编排能力。本文将详细介绍如何搭建一个最小化的LangGraph工程（Clean Graph），该工程可作为智能体开发的脚手架或实验场，帮助开发者快速掌握LangGraph的核心用法，并通过LangGraph Studio实现智能体行为的可视化调试。

项目概述

Clean Graph是一个基于LangGraph构建的极简对话式AI智能体，旨在为学习、构建和实验高级智能体技术提供实用起点。其核心优势在于：

极简结构：去除冗余代码，聚焦LangGraph核心逻辑
可视化调试：集成LangGraph Studio，支持智能体行为的实时追踪
环境兼容：支持本地模型（如LM Studio、Ollama）及在线API（如OpenAI）
可扩展性：清晰的模块划分便于功能扩展

前置要求

必需工具

Python：编程语言环境（推荐3.12版本）
pip：Python包管理器
Miniconda：轻量级环境管理器，用于隔离项目依赖
VSCode：推荐的开发环境，便于配置虚拟环境及代码调试

工具安装指南

快速开始

1. 环境设置

首先创建并激活独立的Conda虚拟环境，避免依赖冲突：

bash 复制代码

# 创建名为clean_graph的虚拟环境，指定Python 3.12
conda create -n clean_graph python=3.12

# 激活环境
conda activate clean_graph

若使用VSCode开发，可通过右下角Python环境选择器关联该虚拟环境，无需手动激活。

2. 安装依赖

项目依赖已整理至requirements.txt，执行以下命令批量安装：

bash 复制代码

pip install -r requirements.txt

核心依赖说明：

langgraph~=1.0：LangGraph框架核心
langchain~=1.0：AI应用开发工具链
langchain_openai：OpenAI兼容API客户端
python-dotenv：环境变量管理
langgraph-cli：LangGraph Studio开发工具

3. 环境配置

编辑项目根目录下的.env文件，配置模型及追踪服务参数：

env 复制代码

# 必需：LLM API配置（支持所有OpenAI兼容接口）
LLM_API_BASE=http://localhost:1234/v1  # 本地模型服务地址（如LM Studio、Ollama）
LLM_MODEL=qwen/qwen3-next-80b          # 模型名称（需与服务端一致）
LLM_API_KEY=your-api-key-here          # API密钥（本地模型可填任意值）

# 可选：LangSmith追踪配置（用于调试与分析）
LANGSMITH_TRACING=false                # 是否启用追踪（开发阶段建议设为false）
LANGSMITH_API_KEY=your-langsmith-key   # LangSmith密钥（需在官网注册获取）

LangSmith是LangChain提供的在线追踪服务，用于记录智能体执行过程，注册地址：LangSmith官网。

4. 启动LangGraph Studio

通过以下命令启动可视化调试界面：

bash 复制代码

langgraph dev --no-reload

--no-reload：禁用热更新（避免频繁代码改动导致界面假死）
启动成功后，访问http://localhost:2024即可打开LangGraph Studio界面

项目结构解析

Clean Graph采用模块化设计，核心结构如下：

bash 复制代码

clean_graph/
├── src/
│   ├── __init__.py      # 包初始化文件
│   ├── graph.py         # LangGraph图结构定义（核心逻辑）
│   └── llms.py          # LLM实例配置（加载.env参数）
├── .env                 # 环境变量配置（模型地址、密钥等）
├── langgraph.json       # LangGraph应用定义（关联Studio）
├── requirements.txt     # 项目依赖清单
├── README.md            # 英文版说明文档
└── README_CN.md         # 中文版说明文档

核心文件说明

src/llms.py

负责加载.env配置，创建LLM调用实例：

python 复制代码

from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
import os

load_dotenv()  # 加载.env文件

llm = ChatOpenAI(
    base_url=os.getenv("LLM_API_BASE"),
    model=os.getenv("LLM_MODEL"),
    api_key=os.getenv("LLM_API_KEY")
)

src/graph.py

定义LangGraph图结构，包含一个极简的对话链路（start → agent → end）：

python 复制代码

from langgraph.graph import Graph, StateGraph
from langgraph.graph.message import add_messages
from pydantic import BaseModel, Field
from src.llms import llm

# 定义状态结构（存储对话消息列表）
class State(BaseModel):
    messages: list = Field(default_factory=list)

# 定义Agent节点逻辑（调用LLM生成回复）
def agent(state: State):
    response = llm.invoke(state.messages)
    return {"messages": [response]}

# 构建图结构
builder = StateGraph(State)
builder.add_node("agent", agent)  # 添加Agent节点
builder.set_entry_point("agent")   # 入口点为Agent
builder.set_finish_point("agent") # 出口点为Agent
graph = builder.compile()         # 编译为可执行图

# 暴露应用实例（供Studio调用）
app = graph

langgraph.json

关联LangGraph Studio与应用实例，确保Studio能正确加载图结构：

json 复制代码

{
    "graphs": {
        "default": {
            "source": "src.graph:app",
            "title": "Clean Graph"
        }
    }
}

LangGraph Studio使用指南

LangGraph Studio是可视化调试智能体的核心工具，主要功能包括：

状态追踪

实时展示State中messages列表的变化，清晰查看对话消息的累加过程。
节点执行可视化

以流程图形式展示智能体执行路径（当前为start → agent → end），复杂链路可直观呈现节点跳转逻辑。
交互模式
- Graph模式：展示完整执行链路及中间状态，适合调试。
- Chat模式：隐藏中间过程，仅展示人机交互结果，适合快速测试。

基本操作步骤

在Studio界面左侧输入框选择human角色，输入对话内容并提交。
系统会触发agent节点逻辑，调用LLM生成回复并更新messages状态。
多轮对话时，messages列表会自动累加历史消息，实现上下文连贯。

总结

Clean Graph通过极简设计降低了LangGraph的学习门槛，开发者可基于此框架：

快速理解LangGraph的图结构与节点编排逻辑
借助LangGraph Studio可视化调试智能体行为
扩展节点与链路，实验复杂智能体功能（如工具调用、多智能体协作等）

如需进一步学习，可参考官方文档：