以编程方式使用文档

Safari 连接问题

Safari 会阻止 localhost 上的纯 HTTP 流量。运行 Studio 时使用 langgraph dev，您可能会看到"加载助手失败"错误。

解决方案 1：使用 Cloudflare Tunnel

Python

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

JS

    # Requires @langchain/langgraph-cli>=0.0.26
    npx @langchain/langgraph-cli dev --tunnel

该命令会输出一个 tunnel URL。连接 Studio 的方法：

  1. 复制 tunnel URL（例如 https://hamilton-praise-heart-costumes.trycloudflare.com)
  2. 在以下地址打开 Studio https://smith.langchain.com/studio/
  3. 点击 **连接到本地服务器**
  4. 粘贴 tunnel URL 并将其添加到 **允许的来源**
  5. 点击 **连接**

此手动步骤是出于安全考虑——Studio 在连接到外部 URL 之前需要用户的明确确认。

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

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

Chrome 连接问题

从 Chrome 版本 142 开始，尝试通过 LangSmith Studio 连接到本地开发服务器时，您可能会遇到"初始化 Studio 失败"错误，提示"TypeError: Failed to fetch"。 langgraph dev即使位于 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 显示："初始化 Studio 失败——请验证 API 服务器是否正在运行或可从浏览器访问。TypeError: Failed to fetch"。
  • - 浏览器控制台显示类似以下错误： Permission was denied for this request to access the 'unknown' address space.

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

  1. 在 Chrome 中打开 LangSmith Studio，访问 https://smith.langchain.com 。
  2. 点击地址栏左侧的 **锁定图标** （或网站信息图标）。
  3. 在下拉菜单中查找 **"本地网络访问"** 选项。
  4. 将设置从 **"询问（默认）"** or **"阻止"** to **"允许"**.
  5. 重新加载页面。

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

其他故障排除

检查浏览器扩展冲突

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

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

验证依赖项是最新的

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

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

  1. 在 Chrome 中，转到 **设置** > **隐私与安全** > **网站设置**.
  2. 在列表中查找 https://smith.langchain.com 。
  3. 点击 **清除数据**.
  4. 重启 Chrome 并重试。

Brave 连接问题

当启用 Brave Shields 时，Brave 会阻止 localhost 上的纯 HTTP 流量。运行 Studio 时 langgraph dev，您可能会看到"加载助手失败"错误。

解决方案 1：禁用 Brave shields

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

解决方案 2：使用 Cloudflare Tunnel

Python

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

JS

    # Requires @langchain/langgraph-cli>=0.0.26
    npx @langchain/langgraph-cli dev --tunnel

该命令输出一个隧道 URL。连接 Studio：

  1. 复制隧道 URL（例如， https://hamilton-praise-heart-costumes.trycloudflare.com)
  2. 在以下地址打开 Studio https://smith.langchain.com/studio/
  3. 点击 **连接到本地服务器**
  4. 将隧道 URL 粘贴到 **允许的来源**
  5. 中，然后点击 **连接**

这是出于安全考虑的手动步骤——Studio 需要用户明确确认后才能连接到外部 URL。

图形边问题

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

解决方案 1：路径映射

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

Python

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

Javascript

    graph.addConditionalEdges("node_a", routingFunction, { true: "node_b", false: "node_c" });

<a id="python"></a> ### 解决方案 2：路由器类型定义

使用 Python 的 Literal type:

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

Studio 中的实验故障排除

**运行实验** 按钮被禁用

请检查以下内容：

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

评估器结果缺失

运行实验时，所有附加的评估器都会被安排在队列中执行。如果看不到立即显示的结果，可能意味着它们仍在等待中。