学习笔记 · Obsidian
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，避免把相同页面记成两套能力。
升级步骤
- 盘点 runtime 版本、公共/内部 import、classic 依赖、custom hooks 和 stream consumer。
- 先锁 v1，在隔离分支逐项替换；不要同时重写业务流程。
- 对消息 content、structured output、tool error、HITL resume、checkpoint、stream event 与 frontend consumer 做契约测试。
- 比较 LangSmith experiments 的质量、延迟、token 与工具轨迹。
- canary 发布并保留旧依赖 lockfile/部署产物，确认无回归后再删除兼容层。