一步步教你LangGraph Studio：可视化调试基于LangGraph构建的AI智能体

之前我们在第一时间介绍过使用LangChain的LangGraph开发复杂的RAG或者Agent应用，随着版本的迭代，LangGraph已经成为可以独立于LangChain核心，用于开发多步骤、面向复杂任务、支持循环的AI智能体的强大框架。

近期LangGraph推出了一个使得复杂AI智能体开发更加高效的工具：LangGraph Studio，一个为可视化测试与调试基于LangGraph构建的AI智能体而设计的集成环境。本文将带领大家初步探索这个新的工具。

1. 回顾LangGraph并创建测试智能体

LangGraph是用于构建基于LLM的复杂智能体的底层框架（注意LangGraph并非类似于Coze这样的低代码Agent构建平台），它的确更复杂但也更强大（与其类似的是另一家主流框架LlamaIndex推出的Workflows）。主要特点有：

• 基于图结构定义的AI工作流
  

• 支持复杂的循环与条件分支
  

• 细粒度的智能体控制，而非智能体“黑盒子”
  

• 智能体状态的持久化，可单步控制、暂停与恢复

• 支持多智能体开发、人机交互工作流

  
  

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

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

1. 用户输入问题

2. 调用LLM获得问题答案，并决定是否需要调用搜索工具

3. 如果需要，则调用搜索引擎获得结果，并返回给LLM继续

4. 如果不再需要搜索，则给出答案，流程结束

   
   

现在使用LangGraph实现这个智能体：

【定义State】

定义在工作流中传递与保持的“状态”数据，可以理解为全局共享数据：

from typing import TypedDict,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]

【定义Node】

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

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

# 调用大模型
def call_llm(state):
    messages = state["messages"]
    messages = [{"role": "system", "content": "你是一个中文智能小助手。"}] + messages
    model = ChatOpenAI(temperature=0, model_name="gpt-4o-mini")
    model = model.bind_tools(tools)
    response = model.invoke(messages)
    return {"messages": [response]}

# 一个辅助方法：判断是否需要调用工具
def should_continue(state):
    messages = state["messages"]
    last_message = messages[-1]

    #根据大模型的反馈来决定是结束，还是调用工具
    if not last_message.tool_calls:
        return "end"
    else:
        return "continue"

【定义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)

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

2. 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。

  
  

3. 用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的智能体代码（参考上文），此外需要三个基本的配置：

langgraph.json：基本配置文件。定义依赖项、环境变量、智能体路径等配置的文件。下图是例子配置，内容很好理解，就是一些路径和指向，请根据自己实际的目录结构进行修改。

requirements.txt：项目依赖。用来在docker中运行Agent。下图是例子配置：

.env：智能体运行时需要的环境变量，比如OPENAI_API_KEY等。这里我们的配置项包括：

【步骤三：用LangGraph Studio加载智能体】

确保Docker后台在运行。

打开LangGraph Studio，使用LangSmith账户登录。

导航到你的langgraph.json文件所在的项目目录，并选择该目录打开。

如果一切正常，一段时间后（构建docker image并启动），你将会看到代理的可视化表示。常见的问题通常和配置错误有关，比如不正确的LangSmith的API Key，或者配置中的目录名称错误等。

4. 用LangGraph Studio调试智能体

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

• 与智能体对话：发送消息并接受反馈

  
  

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

智能体的响应会显示在右侧区域，会清晰地显示每个步骤的执行情况：

• 编辑消息

LangGraph Studio一个重要的调试功能是可以查看当前运行线程中的某个步骤的消息，并对其进行编辑后创建一个新的“分支”运行，后续相关的步骤会在此基础上自动重新运行。通过这种方法，你可以观察到不同情况下的不同输出结果。比如，这里我们把这里搜索的结果手工做个修改：

然后点击下方的“Fork”按钮，此时智能体会从该节点生成一个新的“分支”运行，并重新输出结果。你可以点击下方的多个Fork之间的切换箭头来查看不同的结果，这对于智能体调试中观察不同中间结果的影响非常有用：

• 设置中断

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

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

• 运行线程管理

你可以在客户端管理多个智能体运行线程，而不互相影响。在右侧区域左上角菜单中选择线程进行切换，或者创建一个新的线程，打开新的窗口，这样就可以启动一个新的会话。

• 与LangSmith/VSCode的集成

  
  

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

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

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