用 LangGraph Studio 可视化多 Agent 协作：从终端到图形界面

起因

上一篇记录了我用 LangGraph 搭建的三 Agent 内容生产流水线（Supervisor + Researcher + Writer + Reviewer）。终端里能跑通，但只能看到最终输出，看不到中间过程。

我想要一个图形监控界面：

• 知道当前是哪个 Agent 在跑
• 看到控制权转交的完整路径
• 查看每个 Agent 的输入输出和工具调用
• 最后能看到结果和 report

LangGraph 官方提供了 LangGraph Studio，正好满足这些需求。

整体架构

text

浏览器（LangGraph Studio UI）
        ↕
LangSmith 云端
        ↕ Cloudflare Tunnel
VPS（langgraph dev 服务器）
        ↕
One API → LLM
        ↕
LangGraph 多 Agent 协作图

第一步：环境准备

LangGraph Studio 的内置服务器要求 Python 3.11+，但你现有的 venv 是 Python 3.10。

不要动现有 venv（它跑着视频服务、股票服务等），新建一个专用环境：

bash

# 装 Python 3.11
apt install -y software-properties-common
add-apt-repository -y ppa:deadsnakes/ppa
apt update
apt install -y python3.11 python3.11-venv

# 创建 Studio 专用 venv
python3.11 -m venv /opt/langgraph-studio-venv
source /opt/langgraph-studio-venv/bin/activate

pip install --upgrade pip
pip install langgraph langgraph-supervisor langchain-openai langchain "langgraph-cli[inmem]"

langgraph-cli[inmem] 是关键，它包含了 langgraph-api（内置服务器）和 langgraph-runtime-inmem（内存运行时）。

第二步：创建配置文件

LangGraph CLI 需要一个 langgraph.json，告诉它你的 graph 在哪：

bash

cat > /opt/rag-nvidia/langgraph.json << 'ENDOFFILE'
{
  "dependencies": ["."],
  "graphs": {
    "multi_agent_content": "./multi_agent_content.py:app"
  },
  "env": ".env"
}
ENDOFFILE

关键点：

• graphs 里的 :app 指向你的 Python 文件里导出的 graph 对象
• 你的 multi_agent_content.py 末尾必须有 app = workflow.compile()

同时创建 .env 文件：

bash

cat > /opt/rag-nvidia/.env << 'ENDOFFILE'
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_pt_你的LangSmithKey
LANGCHAIN_PROJECT=multi-agent-content
ENDOFFILE

LangSmith Key 从 smith.langchain.com 注册后获取。

第三步：启动 Studio

bash

cd /opt/rag-nvidia
source /opt/langgraph-studio-venv/bin/activate
langgraph dev --tunnel

--tunnel 参数会做两件事：

1. 下载 cloudflared：从 GitHub 下载 Cloudflare Tunnel 客户端
2. 创建临时隧道：在 VPS 和 Cloudflare 之间建立加密隧道，分配一个随机域名

输出类似：

text

🚀 API: https://oils-immigrants-ride-border.trycloudflare.com
🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=https://oils-immigrants-ride-border.trycloudflare.com
📚 API Docs: https://oils-immigrants-ride-border.trycloudflare.com/docs

注意：每次启动，Cloudflare 都会分配新的随机域名，旧域名会失效。

第四步：在浏览器连接

打开输出的 Studio UI URL。第一次连接时，Studio 会报错：

text

Failed to connect to Agent Server because the domain "xxx.trycloudflare.com" is not allowed.

这是安全设计——Studio 默认只信任 localhost，需要你手动允许外部域名。

解决方法：在错误页面找到 Advanced Settings，把 Cloudflare Tunnel URL 加进允许列表。

然后就能看到 Graph 的可视化界面了。

Studio 界面能做什么

面板	内容
左侧 Graph	Supervisor + Researcher + Writer + Reviewer 的节点和连线
中间执行流程	运行时节点高亮，能看到控制权转交的完整路径
右侧消息流	每个 Agent 的输入输出、工具调用参数和返回值
底部输入框	实时触发运行，不用改代码

触发一次运行，在输入框里填：

json

{"messages": [{"role": "user", "content": "写一篇关于 AI 改变教育的内容"}]}

你会看到：

1. supervisor 高亮，决定调用 researcher
2. transfer_to_researcher 工具被调用
3. researcher 执行，调用 search_topic
4. transfer_back_to_supervisor 交回控制权
5. 依次调用 writer、reviewer
6. 最终 supervisor 输出汇总结果

每一步的输入、输出、工具调用参数都能在右侧面板看到。

踩坑记录

1. Python 版本不够

langgraph dev 的内置服务器要求 Python 3.11+，但 VPS 默认是 3.10。需要装 Python 3.11 并创建独立 venv。

2. 缺少 langgraph.json

启动时报 Path 'langgraph.json' does not exist。需要手动创建，指定 graph 的位置。

3. 缺少 langgraph-api

即使装了 langgraph-cli，如果没有 [inmem] 扩展，会报 Required package 'langgraph-api' is not installed。必须装 langgraph-cli[inmem]。

4. 端口 2024 被占用

如果之前启动的 langgraph dev 没有完全退出，新实例会自动换端口（如 58711）。这会导致 Cloudflare Tunnel 指向错误的端口。

解决：启动前先清理旧进程：

bash

pkill -f "langgraph dev"
pkill -f "cloudflared"

5. One API 中途崩溃

测试过程中 One API 容器意外退出了（exit code 2）。日志显示它在做数据库迁移：

text

[InitDB] database migration started
SLOW SQL >= 200ms
[1430ms] INSERT INTO logs__temp ... SELECT ... FROM logs
DROP TABLE logs
[InitDB] database migrated
server started on http://localhost:3000

迁移过程消耗大量内存，可能触发了 OOM Killer。重启容器后恢复正常。

6. base_url 用 127.0.0.1 还是 172.17.0.1

langgraph dev 服务器跑在宿主机上，不是 Docker 容器。所以 multi_agent_content.py 里的 base_url 应该用：

text

http://127.0.0.1:3000/v1

而不是 Docker 网桥地址 172.17.0.1。

当前状态

组件	状态
Python 3.11	✅ 已安装
Studio venv	✅ /opt/langgraph-studio-venv
langgraph.json	✅ 已创建
LangGraph Studio	✅ 可访问
多 Agent 可视化	✅ 正常工作
One API	✅ 已恢复

日常使用

启动 Studio：

bash

cd /opt/rag-nvidia
source /opt/langgraph-studio-venv/bin/activate
langgraph dev --tunnel

在浏览器打开 Studio URL，发消息触发运行。

停止 Studio：

按 Ctrl+C，或：

bash

pkill -f "langgraph dev"
pkill -f "cloudflared"

可优化的方向

1. Studio 是开发工具，不是生产服务

日志里明确说了 “in-memory server, designed for development and testing”。数据存在内存里，重启就丢。

如果需要生产级部署，用 langgraph build 打包成 Docker 镜像，配合 PostgreSQL 做持久化。

2. 给 One API 加内存限制

避免它因为内存压力被 OOM Killer 杀掉：

bash

docker update --memory 512m --memory-swap 1g one-api

3. 换真实工具

当前的三个工具都是返回固定文本的模拟工具。换成真实 API 调用后，Studio 里就能看到真实的工具调用参数和返回值。

4. 加更多 Agent

在 Studio 里能看到 Graph 结构，加新 Agent 后可视化会自动更新。

一句话总结

LangGraph Studio 让多 Agent 协作从”黑盒”变成”白盒”。 通过 Cloudflare Tunnel 把 VPS 上的 langgraph dev 服务器暴露给 LangSmith，就能在浏览器里实时看到每个 Agent 的运行状态、控制权转交和工具调用。