---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - langgraph
  - migration
  - studio
topic: LangChain LangGraph v1 迁移与 Studio 路由边界
sources:
  - https://docs.langchain.com/oss/javascript/migrate/langchain-v1
  - https://docs.langchain.com/oss/javascript/migrate/langgraph-v1
  - https://docs.langchain.com/oss/javascript/releases/langchain-v1
  - https://docs.langchain.com/oss/javascript/releases/langgraph-v1
  - https://docs.langchain.com/oss/javascript/studio
  - https://docs.langchain.com/oss/python/migrate/langchain-v1
  - https://docs.langchain.com/oss/python/migrate/langgraph-supervisor
  - https://docs.langchain.com/oss/python/migrate/langgraph-v1
  - https://docs.langchain.com/oss/python/releases/langchain-v1
  - https://docs.langchain.com/oss/python/releases/langgraph-v1
  - https://docs.langchain.com/oss/python/studio
last_verified: 2026-08-11
---
# v1 迁移与 Studio 别名

## LangChain v1 主线

v1 把 agent 入口从 LangGraph prebuilt 的 `create_react_agent` 收敛到 LangChain 的 `create_agent` / `createAgent`。LangChain 包只保留 agent、messages、tools、chat models 等核心构件，旧 chains、retrievers、indexing、hub/community re-export 移到 `langchain-classic` / `@langchain/classic`。

核心迁移映射：

| v0 | v1 |
|---|---|
| `create_react_agent` | `create_agent` / `createAgent` |
| `prompt` | `system_prompt` / `systemPrompt` |
| pre/post model hook | middleware `beforeModel` / `afterModel` 等 hook |
| 动态 model function | `wrap_model_call` / `wrapModelCall` middleware |
| tool error handler | `wrap_tool_call` / `wrapToolCall` |
| prompted structured output | ToolStrategy 或 ProviderStrategy |
| `config.configurable` 注入依赖 | typed runtime `context` |
| stream node `agent` | `model` |

structured output 进入主 agent loop，不再必然增加一次模型调用。model 应以未预绑定 tools 的实例/字符串与独立 tools 列表传入，便于策略选择。Python 自定义 state 优先由对应 middleware 声明，让状态与行为同域；顶层 `state_schema` 主要用于工具共享状态和兼容。

## 标准内容与运行时要求

消息新增 provider-neutral standard content blocks；原 `content` 仍保留。Python 可通过输出版本选项序列化标准块，TypeScript 用 `contentBlocks`，默认不会强行重写原生 content。

- Python v1 最低 Python 3.10，移除 3.9。
- TypeScript v1 最低 Node.js 22，移除 Node 18；包改用 bundler 构建，不能继续深层导入 `dist/` 文件。
- 大量早已 deprecated 的 call/predict/serialize、旧 tracer、store 和 loader helper 在 v1 移除；应通过公开 exports、invoke/stream/batch 与 LangSmith tracing 替代。

## LangGraph v1

Python LangGraph v1 主要保持 graph/state/node/edge 与执行模型稳定，重点是弃用 prebuilt `create_react_agent` 并转到 LangChain。TypeScript 还新增 typed interrupts，移除低层 `toLangGraphEventStream`，改由 `graph.stream` 的 encoding 选择 wire format；`useStream` 支持自定义 transport。

迁移时不要把“LangChain agent 换入口”误解成 LangGraph 被废弃。显式 StateGraph、durable execution、checkpoint、HITL 和自定义 orchestration 仍属于 LangGraph。

## `langgraph-supervisor` 迁移

Python `langgraph-supervisor` 已不再积极维护。推荐把 specialist agent 包装为 tools，由一个 `create_agent` supervisor 调用：

- `create_supervisor` → `create_agent` + tool-wrapped subagents；
- `output_mode` → wrapper 内明确格式化 subagent 输出；
- handoff tool → 自定义工具调用 subagent；
- nested supervisor → tool 内再调用含 subagents 的 agent。

worker 内的 `interrupt()` 可以穿透 tool-wrapped agent 层到最外层 graph，再用 `Command(resume=...)` 恢复；要保持同一 checkpointer/thread，并让 wrapper 不吞掉 GraphInterrupt。若需要精确共享 state、并行 fan-out/join、跨 agent reducer 或复杂 routing，应直接建 custom StateGraph，而不是强行套 supervisor agent。

## Studio 路由边界

`/oss/python/studio` 与 `/oss/javascript/studio` 都是 307 别名，统一跳到 `/langsmith/studio`；两条路由没有独立的 OSS Studio 产品正文。Studio 的运行、assistants、threads、local server、observability 与排障内容归入 LangSmith Test 专题。维护链接时保留 canonical LangSmith URL，避免把相同页面记成两套能力。

## 升级步骤

1. 盘点 runtime 版本、公共/内部 import、classic 依赖、custom hooks 和 stream consumer。
2. 先锁 v1，在隔离分支逐项替换；不要同时重写业务流程。
3. 对消息 content、structured output、tool error、HITL resume、checkpoint、stream event 与 frontend consumer 做契约测试。
4. 比较 LangSmith experiments 的质量、延迟、token 与工具轨迹。
5. canary 发布并保留旧依赖 lockfile/部署产物，确认无回归后再删除兼容层。