跳到主要内容
极客日志极客日志
首页博客AI提示词GitHub精选代理工具
搜索
|注册
博客列表
PythonAI

LangGraph Studio 可视化调试基于 LangGraph 构建的 AI 智能体

综述由AI生成LangGraph Studio 这一用于可视化调试基于 LangGraph 构建的 AI 智能体的集成开发环境。文章首先回顾了 LangGraph 的核心特性,如基于图结构的工作流、状态持久化及循环控制,并提供了构建简单搜索增强智能体的完整代码示例。接着详细阐述了 LangGraph Studio 的安装配置、项目结构要求及 Docker 部署流程。重点讲解了 Studio 提供的核心调试功能,包括交互式对话、消息编辑与分支运行(Fork)、节点中断(Interrupts)及线程管理。最后总结了该工具与 LangSmith 及 VSCode 的集成优势,强调了其在提升复杂 Agent 开发效率与可观测性方面的价值。

无尘发布于 2025/2/6更新于 2026/4/266 浏览
LangGraph Studio 可视化调试基于 LangGraph 构建的 AI 智能体

回顾 LangGraph 并创建测试智能体

LangGraph 是用于构建基于 LLM 的复杂智能体的底层框架。它并非类似于 Coze 这样的低代码 Agent 构建平台,而是更侧重于提供强大的图结构控制能力。与其类似的是另一家主流框架 LlamaIndex 推出的 Workflows。

主要特点包括:

  • 基于图结构定义的 AI 工作流:允许开发者以节点和边的形式定义逻辑。
  • 支持复杂的循环与条件分支:能够处理多轮对话、工具调用循环等复杂场景。
  • 细粒度的智能体控制:避免智能体成为'黑盒子',可精确控制每一步行为。
  • 智能体状态的持久化:支持单步控制、暂停与恢复,便于调试。
  • 支持多智能体开发与人机交互工作流:适合构建协作型系统。

现在让我们参考官方应用构建一个简单的测试智能体,这个智能体的 Graph 图定义如下:

这是一个非常简单的智能体,流程描述如下:

  1. 用户输入问题。
  2. 调用 LLM 获得问题答案,并决定是否需要调用搜索工具。
  3. 如果需要,则调用搜索引擎获得结果,并返回给 LLM 继续。
  4. 如果不再需要搜索,则给出答案,流程结束。

使用 LangGraph 实现智能体

1. 定义 State

定义在工作流中传递与保持的'状态'数据,可以理解为全局共享数据:

from typing import TypedDict, Annotated, Sequence
from langgraph.graph import StateGraph, END
from langgraph.graph import add_messages
from langchain_core.messages import BaseMessage
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import ToolNode
from langchain_community.tools.tavily_search import TavilySearchResults

class AgentState(TypedDict):
    messages: Annotated[Sequence[BaseMessage], add_messages]

2. 定义 Node

定义一个工作流中的处理节点,这里主要有两个:LLM 调用与搜索引擎调用。另外定义一个辅助判断方法,用来决定是否需要调用搜索引擎。

# 调用搜索引擎的工具节点,利用 ToolNode 构建
tools = [TavilySearchResults(max_results=1)]
tool_node = ToolNode(tools)

# 调用大模型
def ():
    messages = state[]
    messages = [{: , : }] + messages
    model = ChatOpenAI(temperature=, model_name=)
    model = model.bind_tools(tools)
    response = model.invoke(messages)
     {: [response]}


 ():
    messages = state[]
    last_message = messages[-]

    
      last_message.tool_calls:
         
    :
         
call_llm
state
"messages"
"role"
"system"
"content"
"你是一个中文智能小助手。"
0
"gpt-4o-mini"
return
"messages"
# 一个辅助方法:判断是否需要调用工具
def
should_continue
state
"messages"
1
# 根据大模型的反馈来决定是结束,还是调用工具
if
not
return
"end"
else
return
"continue"

3. 定义 Graph

现在你可以定义 Graph - 也就是智能体的工作流。

# 定义一个 graph
workflow = StateGraph(AgentState)

# 增加两个节点
workflow.add_node("llm", call_llm)
workflow.add_node("search", tool_node)

# 确定入口
workflow.set_entry_point("llm")

# 一个条件边,即从 llm 节点出来的两个分支及条件
workflow.add_conditional_edges(
    "llm",
    should_continue,
    {
        "continue": "search",
        "end": END,
    },
)

# search 调用后返回 llm
workflow.add_edge("search", "llm")

# 编译
graph = workflow.compile()

# 本地测试代码
if __name__ == "__main__":
    while True:
        user_input = input("User: ")
        print("User: "+ user_input)
        if user_input.lower() in ["quit", "exit", "q"]:
            print("Goodbye!")
            break
        
        response = graph.invoke({"messages": [("user", user_input)]})
        print(response["messages"][-1].content)

这里加上了本地测试代码,创建完成后可以在本地运行测试。

LangGraph Studio 是什么?

LangGraph Studio 是 LangChain 推出的专门用于复杂智能体与 RAG 应用可视化、交互与调试的桌面集成开发环境。借助于 LangGraph Studio,你可以非常直观地观察所创建的 AI 智能体的工作流程,并与其进行交互来调试它的多步骤任务,监控各个步骤的状态与输入输出,从而更快地发现故障与修复。

需要注意的几点是:

  • LangGraph Studio 不是一个快速创建 LangGraph 智能体的开发平台(至少目前还不是)。
  • LangGraph Studio 的调试是针对 LangGraph 智能体的 Cloud 部署模式,即:将智能体部署在独立的 API Server 中,并通过 API 调用智能体。
  • 使用时,LangGraph Studio 会把你的智能体打包成 docker image,并在本地启动测试的 API Server。
  • LangGraph Studio 使用需要 LangSmith 的账号,可以去 LangSmith 免费注册,并获得 LangSmith 的 API_Key。

用 LangGraph Studio 在本地加载智能体

准备工作:Docker 安装

由于 LangGraph Studio 需要启动一个 Docker 作为 API Server,因此依赖于 Docker Engine,请首先安装 Docker Desktop,并确保 docker-compose 的版本为 2.22.0 或更高版本。

步骤 1:下载 LangGraph Studio 并安装

进入 LangGraph Studio 的 github 项目地址(搜索 langgraph-studio),下载桌面客户端(暂时只有 Mac 版本,很快支持其他平台)。下载完成后安装打开,并使用 LangSmith 账户登录(免费账户也可)。

步骤 2:配置项目目录

为了让 LangGraph Studio 能够认识并在构建的 API Server(Docker Image)中加载你的智能体,你的智能体项目需要满足必要的项目结构,一般类似于:

这里的 agent.py 为基于 LangGraph 的智能体代码(参考上文),此外需要三个基本的配置:

  1. langgraph.json:基本配置文件。定义依赖项、环境变量、智能体路径等配置的文件。内容很好理解,就是一些路径和指向,请根据自己实际的目录结构进行修改。
  2. requirements.txt:项目依赖。用来在 docker 中运行 Agent。需列出所有 Python 依赖包。
  3. .env:智能体运行时需要的环境变量,比如 OPENAI_API_KEY 等。这里我们的配置项包括密钥信息。

步骤三:用 LangGraph Studio 加载智能体

确保 Docker 后台在运行。

  1. 打开 LangGraph Studio,使用 LangSmith 账户登录。
  2. 导航到你的 langgraph.json 文件所在的项目目录,并选择该目录打开。
  3. 如果一切正常,一段时间后(构建 docker image 并启动),你将会看到代理的可视化表示。

常见的问题通常和配置错误有关,比如不正确的 LangSmith 的 API Key,或者配置中的目录名称错误等。

用 LangGraph Studio 调试智能体

LangGraph Studio 通过调用本地 API Server(docker)中的智能体服务相关接口来向使用者提供一系列跟踪与调试功能。

1. 与智能体对话

在左上角菜单中选择需要调试的智能体 Graph,然后在下方的 Input 区域,选择 +Message,添加你的输入消息,然后点击 Submit,就可以调用智能体。

智能体的响应会显示在右侧区域,会清晰地显示每个步骤的执行情况,包括 Token 消耗、耗时等信息。

2. 编辑消息与 Fork

LangGraph Studio 一个重要的调试功能是可以查看当前运行线程中的某个步骤的消息,并对其进行编辑后创建一个新的'分支'运行,后续相关的步骤会在此基础上自动重新运行。通过这种方法,你可以观察到不同情况下的不同输出结果。

例如,我们可以把搜索的结果手工做个修改,然后点击下方的'Fork'按钮。此时智能体会从该节点生成一个新的'分支'运行,并重新输出结果。你可以点击下方的多个 Fork 之间的切换箭头来查看不同的结果,这对于智能体调试中观察不同中间结果的影响非常有用。

3. 设置中断 (Interrupts)

LangGraph Studio 允许给需要调用的智能体设置中断(interrupts)来控制工作流程。这有点类似程序调试中的断点与单步执行:你可以在特定节点的前后来暂停工作流的运行以进行观察,然后决定是否继续。这可以用于对智能体的每一步行为进行细粒度观察与控制,以排除某种故障。

在左侧窗口区域右上角的菜单点击 Interrupts 按钮,然后选择需要中断的节点及时间点(节点前与节点后),然后运行。例如对所有节点设置中断,就会发现输出窗格中需要确认'Continue'后才会继续运行,否则将会一直阻塞等待。

4. 运行线程管理

你可以在客户端管理多个智能体运行线程,而不互相影响。在右侧区域左上角菜单中选择线程进行切换,或者创建一个新的线程,打开新的窗口,这样就可以启动一个新的会话。这对于并行测试不同 Prompt 策略非常有效。

5. 与 LangSmith/VSCode 的集成

LangGraph Studio 与同属一家的 LangSmith 有着良好的集成,你可以在 LangSmith 中打开项目,可以查看到智能体的每一次运行的详细细节、输入输出、耗时、tokens 使用、提示词等。

此外,你可以在 LangGraph Studio 中直接打开 VScode 对智能体代码进行编辑修改,修改后智能体会实时更新并部署到 docker 中,然后就可以重新调试,这对于需要反复修改迭代的智能体开发非常有用。

总结

LangGraph Studio 提供了一种可视化调试 AI 智能体的实用方法。它与 LangGraph、LangSmith 一起组成了一个构建复杂 AI 智能体的强大工具集。这个工具集既具有了底层开发框架的灵活(相对于低代码开发平台更强大与可控),也兼顾了智能体在跟踪与调试时所需要的简洁易用。

对于开发者而言,掌握 LangGraph Studio 的使用能够显著提升 Agent 应用的迭代效率。通过可视化的方式观察状态流转,结合 Fork 和 Interrupt 功能,可以快速定位逻辑错误。建议在实际项目中结合 LangSmith 的观测能力,建立完善的监控体系,以确保生产环境智能体的稳定性。随着工具的持续更新,未来可能会支持更多平台的客户端以及更丰富的调试插件,值得持续关注。

目录

  1. 回顾 LangGraph 并创建测试智能体
  2. 使用 LangGraph 实现智能体
  3. 1. 定义 State
  4. 2. 定义 Node
  5. 调用搜索引擎的工具节点,利用 ToolNode 构建
  6. 调用大模型
  7. 一个辅助方法:判断是否需要调用工具
  8. 3. 定义 Graph
  9. 定义一个 graph
  10. 增加两个节点
  11. 确定入口
  12. 一个条件边,即从 llm 节点出来的两个分支及条件
  13. search 调用后返回 llm
  14. 编译
  15. 本地测试代码
  16. LangGraph Studio 是什么?
  17. 用 LangGraph Studio 在本地加载智能体
  18. 准备工作:Docker 安装
  19. 步骤 1:下载 LangGraph Studio 并安装
  20. 步骤 2:配置项目目录
  21. 步骤三:用 LangGraph Studio 加载智能体
  22. 用 LangGraph Studio 调试智能体
  23. 1. 与智能体对话
  24. 2. 编辑消息与 Fork
  25. 3. 设置中断 (Interrupts)
  26. 4. 运行线程管理
  27. 5. 与 LangSmith/VSCode 的集成
  28. 总结
  • 💰 8折买阿里云服务器限时8折了解详情
  • 💰 8折买阿里云服务器限时8折购买
  • 🦞 5分钟部署阿里云小龙虾了解详情
  • 🤖 一键搭建Deepseek满血版了解详情
  • 一键打造专属AI 智能体了解详情
极客日志微信公众号二维码

微信扫一扫,关注极客日志

微信公众号「极客日志V2」,在微信中扫描左侧二维码关注。展示文案:极客日志V2 zeeklog

更多推荐文章

查看全部
  • Android Jetpack LiveData 与 Lifecycle 源码深度解析
  • 老款 Mac 运行本地 AI:OpenClaw 环境一键搭建
  • Python 核心知识点与面试常见问题汇总
  • MaxBot 抢票机器人快速部署与配置指南
  • PyQt6 项目开发:虚拟环境修复与 PyInstaller 打包常见问题解决
  • 深入解析潜在扩散模型(LDMs):高分辨率图像合成范式
  • OpenHarmony 跨端生态适配指南:Flutter/RN/C/C++/仓颉鸿蒙化方案
  • Paperclip:AI 代理公司编排平台
  • openclaw新手入门指南:一文看懂环境搭建、模型配置与 WebUI 远程访问
  • WAAPI:开启 Web 动画新纪元
  • AI 辅助编程:利用 GitHub Copilot 等工具提升开发效率
  • OpenCV Hough Circle 变换原理与 C++ 实现详解
  • Linux 系统编译安装 GPU 版 LAMMPS 指南
  • 985 硕士毕业未进大厂是失败吗?职业选择与成长路径探讨
  • Java 面试核心知识点整理
  • JSP 高速公路管理系统设计与实现
  • 在线考试系统的设计与实现
  • MPC 控制算法原理及流程
  • 动态规划进阶:多状态模型与序列决策
  • Conda 环境配置报错 Solving environment: failed with repodata 解决方案

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online

  • 随机西班牙地址生成器

    随机生成西班牙地址(支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选),支持数量快捷选择、显示全部与下载。 在线工具,随机西班牙地址生成器在线工具,online

  • curl 转代码

    解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online