基于 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：推荐的开发环境，便于配置虚拟环境及代码调试

工具安装指南

• Python for MacOS
• Miniconda installation
• pip Installation
• Visual Studio Code on macOS

快速开始

1. 环境设置

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

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

# 激活环境
conda activate clean_graph

2. 安装依赖

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

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文件，配置模型及追踪服务参数：

# 必需：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密钥（需在官网注册获取）

4. 启动LangGraph Studio

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

langgraph dev --no-reload

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

项目结构解析

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

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

核心文件说明

1. src/llms.py
   负责加载.env配置，创建LLM调用实例：

   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")
   )
   

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

   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
   

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

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

LangGraph Studio使用指南

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

1. 状态追踪
   实时展示State中messages列表的变化，清晰查看对话消息的累加过程。

2. 节点执行可视化
   以流程图形式展示智能体执行路径（当前为start → agent → end），复杂链路可直观呈现节点跳转逻辑。

3. 交互模式

   • Graph模式：展示完整执行链路及中间状态，适合调试。
   • Chat模式：隐藏中间过程，仅展示人机交互结果，适合快速测试。

基本操作步骤

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

总结

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

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

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

• LangGraph Studio Doc
• LangGraph Doc