---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langsmith
  - playground
  - studio
  - langgraph
  - debugging
topic: LangSmith Playground 与 Studio 的本地调试、实验、浏览器兼容和生产边界
sources:
  - https://docs.langchain.com/langsmith/test-from-playground
  - https://docs.langchain.com/langsmith/run-evaluation-from-playground
  - https://docs.langchain.com/langsmith/studio
  - https://docs.langchain.com/langsmith/quick-start-studio
  - https://docs.langchain.com/langsmith/use-studio
  - https://docs.langchain.com/langsmith/observability-studio
  - https://docs.langchain.com/langsmith/troubleshooting-studio
last_verified: 2026-08-11
---
# Playground 与 Studio：调试、实验和生产边界

## 三个入口不是替代关系

| 入口 | 最适合 | 主要边界 |
|---|---|---|
| Playground | 单个 prompt/model/tool/schema 的快速迭代 | 只覆盖 prompt 调用，不等同完整 agent |
| Studio | Agent Server 协议应用的 graph/thread/state 调试 | 能读写真实 thread、assistant、memory，权限与副作用更高 |
| SDK/CI | 可版本化、自动化、大批量实验和发布门 | 需要代码、环境与失败恢复治理 |

Playground 可改 model、prompt template、output schema、tools 和 input variables，并把 prompt 对 dataset 全量运行。Studio 则理解 graph nodes、state、assistant、thread、checkpoint 与部署。

## Playground 实验

运行前必须已有 dataset，且 dataset input keys 与 prompt variables 精确匹配；Playground 最多支持 15 个 input variables。开始前应先把 prompt commit 到 Hub，避免事后无法定位版本。

实验在后台对 dataset examples 执行，并可追加 LLM judge 或 code evaluator。Progress 包含 target 和 evaluator 完成度。Playground 适合比较 prompt/model，但不能自动证明：

- 完整业务 application 的 routing、memory、tool 权限和副作用；
- 并发、重试、checkpoint 或恢复；
- 输入 schema 以外的 API、认证和数据一致性。

Chat 可以辅助优化 prompt、生成 tool/schema，但改动应先审查和 commit，再进入受控 experiment。

## Studio 的协议和模式

Studio 是面向实现 Agent Server API 的 agent IDE，连接本地 Agent Server、LangSmith Cloud 或 self-hosted deployment。它依赖 LangSmith、Agent Server 和 LangGraph CLI。

两种模式：

- **Graph mode**：展示节点、路径、中间 state、breakpoint、assistant、dataset 和 Playground 集成。
- **Chat mode**：面向对话行为的轻量 UI，只支持 state 包含或扩展 MessagesState 的 graph；创建/编辑/删除 assistant 仍需 Graph mode。

Graph mode 的可视化是调试视图，不是架构事实的唯一来源。特别是 conditional edge 未声明 path map/Literal 时，Studio 会假设可到所有节点并画出多余边；应修正 graph 类型定义，而不是按错误图重构逻辑。

## 本地开发

langgraph dev 使用内存 Agent Server、watch mode，默认 API 为 localhost:2024。若不希望 trace 离开本机，在应用 .env 中显式设置 LANGSMITH_TRACING=false。

“不 tracing”只控制 LangSmith trace 上传，不等同于应用完全离线：模型 provider、tool、MCP 和 tunnel 仍可能联网。需要同时审查所有出站依赖。

Python/uv 使用 langgraph-cli[inmem]，JavaScript 使用 @langchain/langgraph-cli。可用 debug port 5678 附加 VS Code/PyCharm；debug listener 只能绑定受信接口，不能在共享网络无认证暴露。

## 浏览器连接问题

### Safari 与 Brave

两者会阻止 HTTPS Studio 访问 HTTP localhost。可用 Chromium，或使用 tunnel：

- Python tunnel 要求 langgraph-cli 0.2.6 以上；
- JavaScript 要求 @langchain/langgraph-cli 0.0.26 以上；
- tunnel URL 必须由用户手工加入 Allowed Origins，这一步是安全确认；
- Cloudflare tunnel 可能间歇断连。

Tunnel 把本地 Agent Server 暴露到外部可达通道。只能用于无生产密钥/无敏感数据的受控开发环境，使用短生命周期、严格 allowed origins 和访问日志；结束后关闭进程并轮换可能暴露的临时凭据。

### Chrome 142 以上

Private Network Access 会默认阻止 smith.langchain.com 访问 HTTP localhost。应在站点权限中只对 LangSmith 显式允许 Local network access，然后 reload。禁用 PNA 或浏览器整体安全策略会扩大攻击面，不是推荐修复。

扩展也可能拦截 localhost；通过临时全禁用并逐个恢复定位。清缓存/站点数据会清除本地授权状态，执行前先确认影响。

## 运行、Assistant 与 Thread

Graph mode 会基于 state schema 生成 input form，也可切换 raw JSON；所有输入仍要由 Agent Server 做服务端校验。

运行设置：

- assistant 决定 runtime configuration；
- streaming 可开关；
- breakpoint 可在节点前/后 interrupt，再 continue；
- Submit 会向当前 thread 添加 run，没有 thread 时新建；
- Cancel 只是请求取消，需要 application/tool 本身支持可取消和幂等。

Default configuration 的编辑只更新运行配置，不会自动创建新 assistant；必须明确 Create new assistant 才形成新资源。Chat mode 只能切换 assistant，完整管理在 Graph mode。

Thread state 可以从 checkpoint 编辑并 Fork，或不改 state 直接 Re-run from here；Chat 编辑历史 human message 也会创建 fork。Fork 是新执行分支，不会撤销原分支已完成的外部副作用。支付、邮件、数据库写入等 tool 必须用幂等键、dry-run adapter 或隔离环境。

## Prompt 配置与 Playground 下钻

要让 Studio 识别可编辑 prompt，configuration schema 使用：

- langgraph_nodes：该字段关联的 node 名称数组；
- langgraph_type=prompt：告诉 UI 用 prompt 编辑体验。

配置变更可保存到当前 assistant version 或新建 assistant。生产上应优先创建新版本并做 experiment，不要原地修改共享 active assistant。

对某个 node 可打开 View LLM Runs，把单次 LLM call 送入 Playground，调整 prompt/model/tool 后再复制回 graph。此流程只能验证局部 call；仍需回到完整 graph experiment 验证 routing、state 和工具链。

## 在 Studio 跑 Dataset

Dataset input schema 必须匹配 active assistant；可选 evaluator 会在 graph 处理完输入后自动运行。Experiment 在后台执行，Studio 可继续工作并跳转 LangSmith 看详情。

Retention/成本边界：

- Studio experiment trace 默认 base tier 14 天；
- dataset evaluator 或人工 feedback 会自动升级为 extended tier 400 天；
- 升级增加存储时间与费用。

因此批量跑前先估算 examples × repetitions × trace size，确认 evaluator、采样和 retention。Evaluator 结果暂时缺失可能只是仍在队列 pending，不应立即重跑造成重复成本。

## 远程 Trace 与本地 Agent

部署 trace 可通过 Run in Studio 打开关联 deployment/thread。把远程 thread 克隆给本地 agent 要求：

- langgraph 0.3.18 以上；
- langgraph-api 0.0.32 以上；
- 本地 graph 包含远程 trace 的同名 nodes。

克隆会推断并复制远程 thread history 到本地新 thread。生产 trace 可能包含客户数据、secret-like tool output 或内部 metadata；克隆前必须授权、脱敏并限制本地日志/磁盘。不要把“在本机调试”误认为没有数据复制。

## 从 Node 建 Dataset

Studio 可选择 thread log 中节点，把其 input/output 编辑后写入特定 dataset；默认可为 assistant+node 创建 dataset。这适合建立单节点回归集。

写入前要确认：

- 选择的是稳定业务边界而非偶然内部 state；
- 输入输出已脱敏；
- dataset schema 与 node contract 版本化；
- 不把错误输出直接当 reference；
- node 重命名/重构时保留迁移关系。

## 一键部署不是发布门

Studio 支持从本地快速创建或重新部署 LangSmith Cloud revision。按钮可用不代表可以上线。生产部署前仍需：

- code review、依赖锁定和安全扫描；
- dataset regression、成本/延迟/并发验证；
- secret、网络、tool 权限与数据驻留审查；
- migration、rollback、监控和告警；
- 明确 active assistant/revision 与流量切换策略。

若 Run experiment 按钮禁用，部署环境可能需要新 revision；本地则要升级 CLI 并启用有效 LangSmith API key/tracing。不要为启用按钮盲目把生产凭据放入开发 .env。