Part 5｜LangChain Agent 部署与上线流程（LangGraph 生态）

0. 本章目标与核心结论

用 LangGraph CLI 把一个 LangGraph/LangChain Agent 项目"标准化"为可运行服务
本地启动后会得到三类能力：
1. 后端服务接口（可供外部调用）
2. LangGraph Studio（可视化调试）
3. LangSmith（可选：运行链路追踪与监控）
前端侧可用官方的 agent-chat-ui 快速对接对话界面，实现"可用的 demo / 内测版上线形态"

1. LangChain Agent 开发必备工具套件回顾

1.1 LangSmith：运行监控/调试/评估平台（监控链路）

作用：对 LLM 工作流（尤其是 Agent/Graph）做 跟踪、可视化、调试、评估（偏工程/产品落地全生命周期）
官网（原文给出）：https://docs.smith.langchain.com/
使用方式（在本章项目里）：通过 .env 配置相关 Key / 项目信息后，运行过程中会把链路上报到 LangSmith 仪表盘

文件里强调：如果不需要 LangSmith，则 .env 中间三个 LangSmith 相关环境变量可以不设置。

1.2 LangGraph Studio：图结构可视化与调试 IDE

作用：面向 LangGraph 的图式 Agent，提供：
- 节点/状态可视化
- 运行过程实时调试
- 与本地 langgraph dev 启动联动

1.3 LangGraph CLI：服务部署与运行入口

作用：把 Graph 项目按官方规范组织后，通过 CLI 一键启动
本章关键命令：
bash 复制代码
```
langgraph dev
```
启动成功后，通常能看到 三个链接：
1. 后端服务端口（API 服务）
2. Studio 页面地址（可视化调试）
3. 端口说明/帮助信息（含接口调用方式等）

1.4 Agent Chat UI：Agent 前端可视化对话界面

官方开源前端模板：https://github.com/langchain-ai/agent-chat-ui
作用：把后端 Agent 服务快速接入一个"能聊天、能展示结果"的 UI

2. 借助 LangGraph CLI 创建完整智能体项目（标准项目结构）

2.1 为什么必须按规范组织项目？

因为要把你定义的 Graph 加入 LangGraph Studio / CLI 管理，需要满足官方要求的项目结构
核心在于：必须提供 langgraph.json ，并把 Graph 的入口以 "图名": "文件路径:变量名" 的方式注册

2.2 创建完整 LangGraph 智能体项目流程（Chatbot 示例）

Step 1｜创建项目主文件夹

示例项目名：LangChain Chatbot（文件里是示意）
目标：形成一个独立可运行的 Agent 工程目录

Step 2｜创建 `requirements.txt`

在项目目录中新建 requirements.txt，写入依赖（文件给出的示例，部分被 ... 省略）：

bash 复制代码

langchain
langchain-deepseek
python-dotenv
langsmith
pydantic
...

依赖含义（结合上下文）：

python-dotenv：读取 .env
langsmith：可选链路追踪
pydantic：工具入参 schema / 结构化参数
langchain-deepseek：示例模型提供方（DeepSeek）
其他：按你的工具/绘图/数据处理需求添加

Step 3｜注册 LangSmith（可选）

注册/登录 LangSmith 后，可查看仪表盘
配好 .env 后运行时链路会自动上报（用于企业级监控）

Step 4｜创建 `.env`（敏感信息集中管理）

目的：把 API Key/密钥放环境变量里，不要硬编码到代码中。

文件原文提示：
- 不使用 LangSmith 可不配中间三个变量
- 变量按你的模型/工具实际情况配置

（该 notebook 用截图展示具体内容，文字未完整展开）

Step 5｜创建核心文件 `agent.py`

在 LangChain Chatbot 文件夹中创建 agent.py
在这里编写你的：
- Graph/Agent 定义
- 工具（tools）
- 模型初始化
- 状态/消息结构（如需要）

文件里还提示：用 LangGraph CLI 创建项目时，会自动处理"记忆相关内容并持久化存储"，因此很多场景无需手动设置（原文在此处有省略 ...）。

Step 6｜创建 `langgraph.json`

这是 最关键的上线/部署配置入口。

规则（原文列出）：

必须包含 dependencies 和 graphs
graphs 格式："图名": "文件路径:变量名"
配置文件需与 Python 文件同级或更高层
文件名必须叫 langgraph.json

文件给的示例（注意：原文 json 块写成了 josn，这里按实际 json 理解）：

json 复制代码

{
  "dependencies": ["./"],
  "graphs": {
    "chatbot": "./graph.py:graph"
  },
  "env": ".env"
}

并解释了每个字段（原文）：

dependencies: ["./"]：告诉 LangGraph 在当前目录查找依赖（会自动读取 requirements.txt）
chatbot: "./graph.py:graph"：图名 chatbot，入口在 graph.py 文件的 graph 变量
env: ".env"：指定环境变量文件

Step 7｜安装 `langgraph-cli` 与其他依赖

安装 CLI（原文命令）：

bash 复制代码

pip install -U "langgraph-cli[inmem]"

安装项目依赖（原文也给了）：

bash 复制代码

pip install -r requirements.txt

启动项目（本地 dev）

在项目目录下运行：

bash 复制代码

langgraph dev

启动成功后会输出三个链接（原文说明）：

第一个：部署完成后的服务端口
第二个：LangGraph Studio 可视化页面
第三个：端口说明（含接口调用方式）

3. Agent 部署后调用流程（后端/Studio/LangSmith）

3.1 后端服务接口

启动后查看 "第三个链接" 的端口说明，里面包含详细接口调用方法（原文件用截图展示）
这些接口可用于进一步开发/测试（例如前端接入、业务系统调用等）

3.2 LangGraph Studio 调试

Studio 用于可视化查看节点与状态，并对图式 Agent 做交互式调试（原文件此处有 ... 与截图）

3.3 LangSmith（可选）

若已配置追踪，则可在 LangSmith 中看到该项目的运行情况与链路（原文件用截图展示）

4. LangChain Agent 后端接入 Agent Chat UI（完整流程）

4.1 项目地址

https://github.com/langchain-ai/agent-chat-ui

4.2 Step 1｜克隆前端项目

原文给的命令（含 GitHub 代理配置示例）：

bash 复制代码

# git config --global http.proxy http://127.0.0.1:10080
# git config --global https.proxy http://127.0.0.1:10080

git clone https://github.com/langchain-ai/agent-chat-ui.git

cd agent-chat-ui

原文件还额外提示了"GitHub 代理设置（若开启代理且端口为10080）"，但中间部分内容用 ... 省略。

4.3 Step 4｜启动 Chat Agent UI

原文给的启动命令：

bash 复制代码

pnpm dev

文件中 Step 2/3 的细节（如 pnpm install、以及如何配置后端地址等）在 notebook 里被 ... 或截图遮盖；一般实践中通常需要：

pnpm install

配置后端 API 地址（env 或配置文件）

但这部分属于通用补充，不是文件明确文字内容。

4.4 备注

原文提醒：需要自己创建 .env 文件（用于前端侧的必要配置）

5. 实战：打造智能数据分析助手 Data Agent（SQL + Python 执行 + 绘图）

5.1 项目目标

构建一个 Data Agent，同时具备：

MySQL 数据库查询（NL→SQL 的更稳定替代方案：先让 Agent 产 SQL，再由外部函数执行）
Python 代码解释器（用于数据处理/统计/建模）
绘图能力（生成图像并在前端展示）

文件强调：

LangChain 内置有 NL2SQL 和 Python 工具，但为稳定性考虑，本章选择 手写外部工具函数。

5.2 数据库查询工具（MySQL）

1) `sql_inter`：执行 SQL 查询并返回结果

功能描述（原文）：

当用户需要数据库查询时调用
使用 pymysql 连接 MySQL
只负责"运行 SQL 并查询"，如果需要"提取成 dataframe"，用另一个函数

结构化入参 schema（原文）：

python 复制代码

description = """
当用户需要进行数据库查询工作时，请调用该函数。
该函数用于在指定MySQL服务器上运行一段SQL代码，完成数据查询相关工作，
并且当前函数是使用pymsql连接MySQL数据库。
本函数只负责运行SQL代码并进行数据查询，若要进行数据提取，则使用另一个extract_data函数。
"""

class SQLQuerySchema(BaseModel):
    sql_query: str = Field(description=description)

工具封装（原文片段中间有 ...）：

python 复制代码

@tool(args_schema=SQLQuerySchema)
def sql_inter(sql_query: str) -> str:
    """
    当用户需要进行数据库查询工作时，请调用该函数。
    ...
    """
    connection = pymysql.connect(
        host=host,
        user=user,
        passwd=mysql_pw,
        db=db,
        port=int(port),
        charset='utf8'
    )
    try:
        with connection.cursor() as cursor:
            cursor.execute(sql_query)
            results = cursor.fetchall()
    finally:
        connection.close()

    return json.dumps(results, ensure_ascii=False)

要点：

返回 JSON 字符串，便于 LLM 阅读与后续链路处理
host/user/mysql_pw/db/port 来自 .env

2) `extract_data`：把 SQL 结果提取为 pandas DataFrame 并保存为全局变量

结构化参数（原文）：

python 复制代码

class ExtractQuerySchema(BaseModel):
    sql_query: str = Field(description="用于从 MySQL 提取数据的 SQL 查询语句。")
    df_name: str = Field(description="指定用于保存结果的 pandas 变量名称（字符串形式）。")

工具实现（原文中间有 ...）：

python 复制代码

@tool(args_schema=ExtractQuerySchema)
def extract_data(sql_query: str, df_name: str) -> str:
    """
    用于在MySQL数据库中提取一张表到当前Python环境中...
    """
    connection = pymysql.connect(
        host=host,
        user=user,
        passwd=mysql_pw,
        db=db,
        port=int(port),
        charset='utf8'
    )

    try:
        df = pd.read_sql(sql_query, connection)
        globals()[df_name] = df
        return f"✅ 成功创建 pandas 对象 `{df_name}`，包含从 MySQL 提取的数据。"
    except Exception as e:
        return f"❌ 执行失败：{e}"
    finally:
        connection.close()

要点：

通过 globals()[df_name] = df 把 DataFrame 暴露到 Python 执行环境，供后续 python_inter/fig_inter 使用

5.3 Python 解释器工具

1) `python_inter`：执行非绘图类 Python 代码

结构化入参（原文）：

python 复制代码

class PythonCodeInput(BaseModel):
    py_code: str = Field(description="一段合法的 Python 代码字符串，例如 '2 + 2' 或 'x = 3\\ny = x * 2'")

核心逻辑（原文中间有 ...）：

python 复制代码

@tool(args_schema=PythonCodeInput)
def python_inter(py_code):
    """
    当用户需要编写Python程序并执行时，请调用该函数。
    本函数只能执行非绘图类的代码，绘图请用 fig_inter。
    """
    g = globals()
    try:
        return str(eval(py_code, g))
    except:
        global_vars_before = set(g.keys())
        try:
            exec(py_code, g)
        except Exception as e:
            return f"代码执行时报错{e}"
        global_vars_after = set(g.keys())
        new_vars = global_vars_after - global_vars_before
        if new_vars:
            result = {var: g[var] for var in new_vars}
            return str(result)
        else:
            return "已经顺利执行代码"

要点：

优先 eval：适合表达式直接返回结果
不行则 exec：适合多行脚本/赋值/函数定义
对比前后 globals() 变量集合，返回新变量，帮助 Agent"看到"执行产物

2) `fig_inter`：执行绘图代码并保存为图片，供前端展示

结构化入参（原文）：

python 复制代码

class FigCodeInput(BaseModel):
    py_code: str = Field(description="要执行的 Python 绘图代码，必须使用 matplotlib/seaborn 创建图像并赋值给变量")
    fname: str = Field(description="图像对象的变量名，例如 'fig'，用于从代码中提取并保存为图片")

关键逻辑（原文中间有 ...，但核心保存流程明确）：

切换 matplotlib backend 为 Agg（适合无 GUI 环境）
执行绘图代码
将生成的图对象保存为 png
返回相对路径（给前端使用）

原文片段（含保存路径逻辑）：

python 复制代码

current_backend = matplotlib.get_backend()
matplotlib.use('Agg')

local_vars = {"plt": plt, "pd": pd, "sns": sns}
...

base_dir = r"C:\Users\Admin\Desktop\LangGraph App\data_agent\agent-chat-ui\public"
images_dir = os.path.join(base_dir, "images")
os.makedirs(images_dir, exist_ok=True)

...

fig = local_vars.get(fname, None)
if fig:
    image_filename = f"{fname}.png"
    abs_path = os.path.join(images_dir, image_filename)  # 绝对路径
    rel_path = os.path.join("images", image_filename)    # 相对路径（给前端用）

    fig.savefig(abs_path, bbox_inches='tight')
    return f"✅ 图片已保存，路径为: {rel_path}"
else:
    return "⚠️ 图像对象未找到..."

要点（非常关键）：

base_dir 必须改成你本机 agent-chat-ui 的 public 目录，否则前端拿不到图片
返回 images/xxx.png 相对路径，方便前端静态资源直接展示

5.4 创建完整 Data Agent 项目（LangGraph CLI 标准化）

Step 1｜创建 `agent.py` 主函数

文件中给了 imports 的示例（后续主体用 ... 省略）：

python 复制代码

import os
from dotenv import load_dotenv 
from langchain_deepseek import ChatDeepSeek
from typing import Annotated
from typing_extensions import TypedDict
from langchain.agents import create_agent
from langchain.tools import tool
from pydantic import BaseModel, Field
import matplotlib
import json
import matplotlib.pyplot as plt
import seaborn as sns
import pandas as pd
...

并明确有：

.env 加载（load_dotenv）
工具注册（@tool）
结合 MySQL / Python / 绘图工具组装 Agent

Step 2｜创建 `requirements.txt`

文件给的依赖清单（同样部分省略）：

bash 复制代码

langchain
langchain-deepseek
python-dotenv
langsmith
pydantic
matplotlib
seaborn
pandas
IPython
pymysql
scikit-learn
langchain-tavily

然后安装：

bash 复制代码

pip install -r requirements.txt

Step 3｜编写 `.env`

文件明确列出了与 MySQL 相关的环境变量（值用 ** 占位）：

复制代码

MYSQL_PW=**
DB_NAME=**
PORT=3306

结合上文工具实现，通常还需要 host/user 等变量（文件截图可能包含但文字未完整给出）。

Step 4｜创建 `langgraph.json`

文件给的 Data Agent 版本配置（原文 json 块里把 "json" 拼成了 josn，这里按实际 json 理解）：

json 复制代码

{
  "dependencies": ["./"],
  "graphs": {
    "data_agent": "./agent.py:agent"
  },
  "env": ".env"
}

并说明：将 Agent 取名为 data_agent。

Step 5｜开启后端服务

bash 复制代码

langgraph dev

启动后即可在 LangGraph Studio 中进行功能测试（文件用截图展示）。

Step 6｜开启前端服务（建议单独下载 UI 模板）

文件建议：

可以复用前端服务，但更推荐围绕当前项目单独下载前端模板运行

文件在这里的命令块内容明显被破坏/粘贴错位（如下所示），但核心意思仍是 运行 agent-chat-ui 并启动 pnpm dev：

bash 复制代码

# git config --global https.proxy http://127.0.0.1:10080

# set HTTP_PROXY=http://127.0.0.1:10080
pnpm devtallt-ui//github.com/langchain-ai/agent-chat-ui.git

这段命令在 notebook 里不是一个可直接运行的标准脚本（疑似排版/粘贴错误）。

结合前文第 4 节，正确思路应是：

git clone agent-chat-ui

pnpm dev

并在 UI 中填入 Agent 名称、以及可选 LangSmith API Key（文件最后一句明确提到这一点）

6. 联调与测试要点清单（从文件内容抽出的"上线关键点"）

后端
- langgraph.json 必须存在且格式正确
- graphs 入口 "文件路径:变量名" 要对得上
- .env 放敏感信息（模型 key / DB 密码 / LangSmith key）
- langgraph dev 启动后，用端口说明里的接口进行调用测试
可视化调试
- LangGraph Studio 用于调试 Graph 流程与状态
- LangSmith（可选）用于线上链路追踪与观测
前端
- agent-chat-ui 用 pnpm dev 启动
- 绘图时 fig_inter 保存图片到 agent-chat-ui/public/images（或你的静态资源目录），并返回相对路径给 UI

Part 5｜LangChain Agent 部署与上线流程（LangGraph 生态）

0. 本章目标与核心结论

1. LangChain Agent 开发必备工具套件回顾

1.1 LangSmith：运行监控/调试/评估平台（监控链路）

1.2 LangGraph Studio：图结构可视化与调试 IDE

1.3 LangGraph CLI：服务部署与运行入口

1.4 Agent Chat UI：Agent 前端可视化对话界面

2. 借助 LangGraph CLI 创建完整智能体项目（标准项目结构）

2.1 为什么必须按规范组织项目？

2.2 创建完整 LangGraph 智能体项目流程（Chatbot 示例）

Step 1｜创建项目主文件夹

Step 2｜创建 requirements.txt

Step 3｜注册 LangSmith（可选）

Step 4｜创建 .env（敏感信息集中管理）

Step 5｜创建核心文件 agent.py

Step 6｜创建 langgraph.json

Step 7｜安装 langgraph-cli 与其他依赖

启动项目（本地 dev）

3. Agent 部署后调用流程（后端/Studio/LangSmith）

3.1 后端服务接口

3.2 LangGraph Studio 调试

3.3 LangSmith（可选）

4. LangChain Agent 后端接入 Agent Chat UI（完整流程）

4.1 项目地址

4.2 Step 1｜克隆前端项目

4.3 Step 4｜启动 Chat Agent UI

4.4 备注

5. 实战：打造智能数据分析助手 Data Agent（SQL + Python 执行 + 绘图）

5.1 项目目标

5.2 数据库查询工具（MySQL）

1) sql_inter：执行 SQL 查询并返回结果

2) extract_data：把 SQL 结果提取为 pandas DataFrame 并保存为全局变量

5.3 Python 解释器工具

1) python_inter：执行非绘图类 Python 代码

2) fig_inter：执行绘图代码并保存为图片，供前端展示

5.4 创建完整 Data Agent 项目（LangGraph CLI 标准化）

Step 1｜创建 agent.py 主函数

Step 2｜创建 requirements.txt

Step 3｜编写 .env

Step 4｜创建 langgraph.json

Step 5｜开启后端服务

Step 6｜开启前端服务（建议单独下载 UI 模板）

6. 联调与测试要点清单（从文件内容抽出的"上线关键点"）

Step 2｜创建 `requirements.txt`

Step 4｜创建 `.env`（敏感信息集中管理）

Step 5｜创建核心文件 `agent.py`

Step 6｜创建 `langgraph.json`

Step 7｜安装 `langgraph-cli` 与其他依赖

1) `sql_inter`：执行 SQL 查询并返回结果

2) `extract_data`：把 SQL 结果提取为 pandas DataFrame 并保存为全局变量

1) `python_inter`：执行非绘图类 Python 代码

2) `fig_inter`：执行绘图代码并保存为图片，供前端展示

Step 1｜创建 `agent.py` 主函数

Step 2｜创建 `requirements.txt`

Step 3｜编写 `.env`

Step 4｜创建 `langgraph.json`