Studio 故障排除

Safari 连接问题

Safari 会阻止 localhost 上的纯 HTTP 流量。用 langgraph dev 运行 Studio 时，你可能会看到 "Failed to load assistants" 错误。

解决方案 1：使用 Cloudflare Tunnel

pip install -U langgraph-cli>=0.2.6
langgraph dev --tunnel

该命令会输出一个 tunnel URL。要连接 Studio：

1. 复制 tunnel URL（例如 https://hamilton-praise-heart-costumes.trycloudflare.com）
2. 在 https://smith.langchain.com/studio/ 打开 Studio
3. 点击 Connect to a local server
4. 粘贴 tunnel URL 并将其添加到 Allowed Origins
5. 点击 Connect

出于安全考虑，这个手动步骤是必需的——Studio 在连接到外部 URL 之前要求用户显式确认。

NOTE

Cloudflare tunnel 可能不可靠，且可能间歇性断开。

解决方案 2：使用 Chromium 浏览器

Chrome 和其他 Chromium 浏览器允许 localhost 上的 HTTP。使用 langgraph dev 而无需额外配置。

Chrome 连接问题

从 Chrome 142 版开始，当你试图将 LangSmith Studio 通过 langgraph dev 连接到你的本地开发服务器时，你可能会遇到带 "TypeError: Failed to fetch" 的 "Failed to initialize Studio" 错误。即使 http://127.0.0.1:2024/docs 处的 API 服务器成功加载，也会发生这种情况。

根因： Chrome 142 完全强制执行私有网络访问（PNA）规范且无回退，默认会阻止 HTTPS 站点（如 https://smith.langchain.com）访问 HTTP localhost 服务器。

症状

• 运行 langgraph dev 会成功启动服务器。
• 导航到 http://127.0.0.1:2024/docs 会正确显示 API 文档。
• 位于 https://smith.langchain.com 的 LangSmith Studio 显示："Failed to initialize Studio - Please verify if the API server is running or accessible from the browser. TypeError: Failed to fetch"。
• 浏览器控制台显示类似错误：Permission was denied for this request to access the 'unknown' address space。

解决方案：在 Chrome 中允许本地网络访问

1. 在 Chrome 中于 https://smith.langchain.com 打开 LangSmith Studio。
2. 点击地址栏左侧的 锁图标（或站点信息图标）。
3. 在下拉菜单中查找 "Local network access" 选项。
4. 将设置从 "Ask (default)" 或 "Block" 改为 "Allow"。
5. 重新加载页面。

Studio 现在应当能成功连接到你的本地开发服务器。

额外故障排除

检查浏览器扩展冲突

浏览器扩展（尤其是 Ollama Chrome 扩展或 AI 模型扩展）会干扰 localhost 连接：

1. 临时禁用所有浏览器扩展。
2. 重启 Chrome。
3. 再次尝试连接到 Studio。
4. 如果成功，逐个重新启用扩展以找出问题所在。

核实依赖是否为最新

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

清除浏览器缓存和站点数据

1. 在 Chrome 中，前往 Settings > Privacy and Security > Site Settings。
2. 在列表中找到 https://smith.langchain.com。
3. 点击 Clear data。
4. 重启 Chrome 再试。

Brave 连接问题

当启用 Brave Shields 时，Brave 会阻止 localhost 上的纯 HTTP 流量。用 langgraph dev 运行 Studio 时，你可能会看到 "Failed to load assistants" 错误。

解决方案 1：禁用 Brave shields

使用 URL 栏中的 Brave 图标，为 LangSmith 禁用 Brave Shields。

解决方案 2：使用 Cloudflare Tunnel

pip install -U langgraph-cli>=0.2.6
langgraph dev --tunnel

该命令会输出一个 tunnel URL。要连接 Studio：

1. 复制 tunnel URL（例如 https://hamilton-praise-heart-costumes.trycloudflare.com）
2. 在 https://smith.langchain.com/studio/ 打开 Studio
3. 点击 Connect to a local server
4. 粘贴 tunnel URL 并将其添加到 Allowed Origins
5. 点击 Connect

出于安全考虑，这个手动步骤是必需的——Studio 在连接到外部 URL 之前要求用户显式确认。

图边问题

未定义的条件边可能会在你的图中显示意外的连接。 这是因为若没有正确定义，Studio 会假定该条件边可以访问所有其他节点。要解决这一点，使用以下方法之一显式定义路由路径：

解决方案 1：路径映射

定义路由器输出与目标节点之间的映射：

graph.add_conditional_edges("node_a", routing_function, {True: "node_b", False: "node_c"})

解决方案 2：路由器类型定义

使用 Python 的 Literal 类型指定可能的路由目的地：

def routing_function(state: GraphState) -> Literal["node_b","node_c"]:
    if state['some_condition'] == True:
        return "node_b"
    else:
        return "node_c"

在 Studio 中排查实验问题

Run experiment 按钮被禁用

检查以下内容：

• 已部署的应用：如果你的应用部署在 LangSmith 上，你可能需要创建一个新修订版以启用此功能。
• 本地开发服务器：如果你在本地运行应用，请确保你已升级到最新版本的 langgraph-cli（pip install -U langgraph-cli）。此外，请确保通过在你项目的 .env 文件中设置 LANGSMITH_API_KEY 来启用追踪。

评估器结果缺失

当你运行一个实验时，任何附加的评估器都会被调度到队列中执行。如果你没有立即看到结果，很可能意味着它们仍在待处理中。

---